Synento docs
Guides

SDK guide

Integrate Synento into your application using the JavaScript/TypeScript SDK.

View as Markdown

Keep @synento/node on the server. The browser uses @synento/client.

Installation

npm install @synento/node
import { createSynentoClient } from "@synento/node";
import type { Session, ConnectionToken, SessionManifest } from "@synento/node";

Initialization

const synento = createSynentoClient({
  apiKey: "sk_live_xxxxx",           // optional: defaults to SYNENTO_API_KEY
  baseUrl: "https://api.synento.com" // optional: SYNENTO_API_URL, then this
});

This client holds your secret API key, so it belongs on the server only. In the browser, use @synento/client (or @synento/react) and have your server mint connection tokens for it. See the web quickstart.

Retries

The client does not retry failed requests. withRetry() and getRetryOptions() exist and store a setting, but in @synento/node 0.3.0 nothing reads it. If you want retries, wrap the call yourself and retry on 429 and 5xx (a 429 carries a retry-after header).

Session methods

Create a session

const session = await synento.createSession({ name: "My Meeting" });
console.log(session.id); // 32 hex characters, e.g. 9b1c4e7a2d3f4a8b9c0d1e2f3a4b5c6d

List sessions

const sessions = await synento.listSessions(); // newest first, up to 500
for (const s of sessions) {
  console.log(`${s.name} — ${s.startedAt ? "Started" : "Not started"} at ${s.createdAt}`);
}

Get a single session

const session = await synento.getSession(sessionId);
if (session) {
  console.log(`Session ended at: ${session.endedAt || "not yet"}`);
} else {
  console.log("Session not found"); // returns null for 404
}

Toggle session visibility

await synento.setSessionVisibility(sessionId, true); // make public

Delete a session

await synento.deleteSession(sessionId); // erases the recording, exports and replay links

Delete an export

await synento.deleteExport(jobId); // deletes one MP4; the session is untouched

Use it for the earlierExportIds a participant redaction returns. An export still rendering is refused with a 409.

Connection token methods

Get a live streaming token

const token = await synento.createConnectionToken(sessionId, { userId: "alice" });
// → { accessToken: "...", expiresIn: 3600, session: "9b1c…" }

expiresIn is how long the token can be used to open a connection; a call that is already connected is not cut off when it passes.

Get a replay token

const token = await synento.createConnectionToken(sessionId, {
  userId: "viewer",
  replay: true,
  fromTs: 0,     // epoch ms to start from; 0 is the beginning
  speed: 1.0,    // playback speed multiplier, any positive number
});

A replay token opens a WebSocket replay stream: the resolveWsUrl URL with &replay=true added. The server sends the recording back over the same binary wire protocol as a live call, paced at speed. Neither SDK plays that stream yet; for playback in your app use the playback API or the MP4 export in Recordings & Replay.

Generate the WebSocket URL

const wsUrl = synento.resolveWsUrl({ sessionId, userId: "alice" });
// → wss://api.synento.com/ws?session=9b1c…&user_id=alice

Return { wsUrl, token: token.accessToken } from your token route; the browser SDK sends the token as a WebSocket subprotocol, so it stays out of URLs and logs. Pass requestOrigin (the request's Origin header) when developing against a local server. getWebSocketUrl() is deprecated: it puts the token in the query string.

Project methods

Create a project

const project = await synento.createProject("My App", "production");
// → { id: "...", name: "My App", org_id: "...", environment: "production", created_at: "..." }

List projects

const projects = await synento.listProjects();
// → [{ id, name, org_id, environment, created_at }, ...]

These two, and the webhook and API-key methods below, return the API's fields as sent, in snake_case. The TypeScript types in 0.3.0 declare some of them in camelCase (orgId, projectId, isActive), and those properties are undefined at runtime. id, name and url are the same either way.

createSession() always creates in the API key's own project, not in one you just created; to work in a new project, create an API key for it.

Webhook methods

Create a webhook

const webhook = await synento.createWebhook(
  "https://example.com/webhooks/synento",
  ["session.created", "session.started", "session.ended"]
);
// → { id, project_id, url, events: "session.created,session.started,session.ended",
//     is_active: true, created_at, secret }

// Events: session.created, session.started, session.ended, recording.ready, export.completed, transcript.ready

The response carries the signing secret once, at creation; store it to verify deliveries (Webhooks). events comes back as one comma-separated string.

List webhooks

const webhooks = await synento.listWebhooks();
// → [{ id, project_id, url, events: "session.created,…", is_active, created_at }]
// Paused endpoints are included, with is_active: false.

Usage and billing methods

Check billing limits

const limits = await synento.getBillingLimits();
if (limits.isBlocked) {
  console.error(`Blocked: ${limits.statusMessage}`);
}

// Access individual fields
console.log(`Minutes used: ${limits.streamingMinutesUsed}`);
console.log(`Has subscription: ${limits.hasActiveSubscription}`);

The response also carries the allowances and the rest of the period's usage: includedMinutes, storageUsedGib, includedStorageGib, replayMinutesUsed, includedReplayMinutes, exportMinutesUsed, includedExportMinutes, billableExportMinutes, maxParticipantsPerCall, maxConcurrentParticipants and plan. The 0.3.0 BillingLimits type declares only the six fields used above, so read the others through a cast.

Billing summary and usage totals

getBillingSummary() and getUsage() exist, but in 0.3.0 their return types do not describe what the API sends. Until that is fixed, call GET /v1/billing/summary (period, plan, usage totals and cost breakdown) or GET /v1/usage directly, or use getBillingLimits() above.

API key management

List keys (metadata only, no secrets)

const keys = await synento.listApiKeys();
// → [{ id, label, project_id, created_at }]

Create a new key (returns the raw secret)

const result = await synento.createApiKey("ci"); // optional label, default "default"
// → { id: "...", label: "ci", secret: "sk_live_xxxxx" } ← show this ONCE

Revoke a key (deletes it)

await synento.revokeApiKey("key_id_here"); // deletes the key permanently
// → true (on success)

Restricted keys

A restricted key (rk_live_…) works with the same client for everything an integration does: createSession, createConnectionToken (live and replay) and getSessionManifest, and nothing else. It is what a coding agent connected over MCP writes into your environment:

SYNENTO_API_KEY=rk_live_…
SYNENTO_API_URL=https://api.synento.com
SYNENTO_PROJECT_ID=…

Check that media arrived

const manifest = await synento.getSessionManifest(session.id);
// A participant whose tracks include "cam" and "mic" really published both.
const alice = manifest.participants.find((p) => p.user_id === "alice");
const kinds = alice?.tracks.map((t) => t.kind) ?? [];

Advanced patterns

Full session lifecycle in one block

const session = await synento.createSession({ name: "Q&A Session #5" });
await synento.setSessionVisibility(session.id, true); // make the replay public

// One token per participant. Every token can publish and watch; roles such
// as host and guest are up to your app.
const hostToken = await synento.createConnectionToken(session.id, { userId: "host" });
const guestToken = await synento.createConnectionToken(session.id, { userId: "guest-1" });

// What each browser needs: its WebSocket URL and its token.
const host = { wsUrl: synento.resolveWsUrl({ sessionId: session.id, userId: "host" }), token: hostToken.accessToken };
const guest = { wsUrl: synento.resolveWsUrl({ sessionId: session.id, userId: "guest-1" }), token: guestToken.accessToken };

Error handling

import { SynentoError } from "@synento/node";

try {
  const session = await synento.createSession({ name: "Test" });
} catch (err) {
  if (!(err instanceof SynentoError)) throw err;
  if (err.status === 401) {
    console.error("Invalid or revoked API key");
  } else if (err.status === 403) {
    // Not allowed, or a plan limit (e.g. the call is full); the message says which.
    console.error(err.message);
  } else if (err.status === 503) {
    console.error("Usage allowance used up:", err.message);
  } else if (err.status === 429) {
    console.error("Rate limited — retry after delay");
  } else {
    console.error("Unexpected error:", err.status, err.message);
  }
}

Every failure is a SynentoError with the HTTP status and the API's message. 401/403 arrive as its subclass SynentoAuthenticationError, and 404 as SynentoNotFoundError (except getSession, which returns null).

Reconnecting

A token only has to be valid when a connection opens. @synento/client calls your getToken function again on every reconnect, so a token route that mints a fresh token each time is all reconnection needs. There is nothing to refresh on a timer:

async function tokenFor(sessionId: string, userId: string) {
  const token = await synento.createConnectionToken(sessionId, { userId });
  return { wsUrl: synento.resolveWsUrl({ sessionId, userId }), token: token.accessToken };
}

On this page