SDK guide
Integrate Synento into your application using the JavaScript/TypeScript SDK.
Keep @synento/node on the server. The browser uses @synento/client.
Installation
npm install @synento/nodeimport { 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. 9b1c4e7a2d3f4a8b9c0d1e2f3a4b5c6dList 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 publicDelete a session
await synento.deleteSession(sessionId); // erases the recording, exports and replay linksDelete an export
await synento.deleteExport(jobId); // deletes one MP4; the session is untouchedUse 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=aliceReturn { 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.readyThe 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 ONCERevoke 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 };
}