Synento docs

Getting started

Get from zero to your first live video stream in under 5 minutes.

View as Markdown

Get from zero to your first live video stream in under 5 minutes.

Using a coding agent? Connect it to Synento over MCP and it can do all of this for you, including proving the video works. See Connect your agent.

Prerequisites

  • A Synento account (sign up free: 10,000 participant-minutes a month, no card)
  • A server-side key: an sk_live_ API key from the dashboard, or an rk_live_ restricted key (one project; enough for Options A and B, while the CLI in Option C takes an sk_live_ key)

1. Install the packages

npm install @synento/node      # server-side: create sessions, mint tokens
npm install @synento/client    # browser: publish and receive live audio/video

React applications can use @synento/react for hooks and components, and @synento/player for embedded replay.

2. Mint connection tokens on your server

Your API key is a server-side secret. It never goes to the browser. Instead, your backend creates a session for each call and exposes one small route that mints a short-lived connection token for the user asking to join it.

// app/api/synento/route.ts  (Next.js App Router)
import { createSynentoClient, resolveWsUrl } from "@synento/node";

// An empty config reads SYNENTO_API_KEY and SYNENTO_API_URL from the environment.
const synento = createSynentoClient({});

export const dynamic = "force-dynamic"; // or the route is cached and serves a stale token

export async function POST(request: Request) {
  // Authenticate your own user here before minting a token for them.
  const { sessionId, userId } = await request.json();

  const token = await synento.createConnectionToken(sessionId, { userId });

  return Response.json({
    token: token.accessToken,
    wsUrl: resolveWsUrl({
      apiBaseUrl: process.env.SYNENTO_API_URL ?? "https://api.synento.com",
      requestOrigin: request.headers.get("origin"),
      sessionId,
      userId,
    }),
  });
}

The session itself is created once per call, wherever your app decides a call exists, with the same client:

const session = await synento.createSession({ name: "Morning standup" });
// session.id is the sessionId the browsers send to the route above

Use resolveWsUrl rather than assembling the URL yourself. It handles the loopback-hostname case that otherwise makes local development fail in a way that produces no error at all, just a call that never connects.

3. Join from the browser

import { SynentoRoom } from "@synento/client";

const sessionId = "…"; // the session id your server created

const room = new SynentoRoom({
  userId: "alice",
  // Re-invoked on every reconnect, so tokens rotate automatically.
  getToken: async () => {
    const res = await fetch("/api/synento", {
      body: JSON.stringify({ sessionId, userId: "alice" }),
      method: "POST",
    });
    return res.json(); // { wsUrl, token }
  },
});

room.on("participantsChanged", (ids) => console.log("in the room:", ids));
// Run this from your Join button's click handler. Browsers only start sound
// inside a tap, so unlock first, before anything is awaited.
void room.unlockAudio();
// If the browser still refuses, offer a button that calls unlockAudio() again.
room.on("audioStateChanged", (state) => console.log("sound:", state)); // "playing" | "blocked"
// Whether your own mic reaches the call. Safari captures it only once sound
// was started from a click; on "blocked", the same button fixes it.
room.on("micStateChanged", (state) => console.log("mic:", state)); // "sending" | "muted" | "blocked" | …
await room.connect();

// Publish. The second argument is optional — pass your local preview element
// if you have one. A stream with no video tracks publishes audio only.
const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
await room.publishCamera(stream, previewVideoEl);

Media travels as binary frames, not JSON. @synento/client handles the framing, decoding and reconnection. Do not open a raw WebSocket and try to JSON.parse messages off it.

Recording needs no code. The session's durable streams are the recording, so there is no start-recording call and no recording flag.

Video is HD by default. Cameras go out at up to 720p, 30 fps, in their own shape. To show someone, call room.attachParticipant(id, canvas); the canvas takes the size of their picture, so size it with CSS and choose object-fit: contain (whole picture) or cover (fill the tile). See Video and audio quality to change the resolution or bitrate.

4. See it running

demo.synento.com is a two-way call built on exactly these packages. Open it in two tabs and join the same session to see both sides.

Your own calls are recorded the moment they happen: open one under Recordings in the dashboard to replay it, or read GET /v1/sessions/{sessionId}/manifest to check that each participant's camera (cam) and microphone (mic) tracks hold data.

Option B: Use HTTP API directly (cURL)

Every key belongs to one project, and sessions are created in that project. The project your account starts with is enough for this walkthrough.

1. Create a session

curl -X POST https://api.synento.com/v1/sessions \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Demo Session"}'

The response's data.id is the session id used below.

2. Get a connection token

curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "viewer-1"}'

The response's data.access_token is valid for an hour (expires_in is in seconds). user_id is required: letters, digits, - and _.

3. Connect to WebSocket streaming

Once you have the access_token from step 2, open a WebSocket. Prefer sending the token as a subprotocol, so it stays out of URLs and access logs:

wss://api.synento.com/ws?session={sessionId}&user_id=viewer-1
Sec-WebSocket-Protocol: synento.v1, synento.token.{accessToken}

The query-string form (&access_token=...) is still accepted, but logs the token.

What travels over that socket is binary, in a self-describing frame format, not JSON. Unless you are implementing a client from scratch, use @synento/client, which handles framing, codec negotiation, decoding, backpressure and reconnection.

Option C: Use the CLI

# Login with your API key
npx @synento/cli login sk_live_xxxxx

# Create a session in your key's project (the project ID is shown in the dashboard)
npx @synento/cli create-session "Demo Session" -p {projectId}

-p must be the project the key belongs to; a key cannot create sessions in another project.

Option D: Let your coding agent do it

Connect your agent to Synento's MCP server and ask it to add video to your app:

claude mcp add --transport http synento https://api.synento.com/mcp

Once you approve it, the agent can mint a restricted key for your .env, write the server route and the browser code above, and then check the recording with verify_session to confirm camera and microphone actually arrived. See Connect your agent for other clients and what you approve. For agents has the same configs for Cursor, VS Code and Codex, and prompts you can paste. AI interview recorder is a complete small app for the recorded 1:1 prompt.

Next steps

Environment variables

VariableDescriptionDefault
SYNENTO_API_KEYSecret key. Server-side only. Never expose it to a browser.-
SYNENTO_API_URLBase URL of the Synento API.https://api.synento.com
SYNENTO_PROJECT_IDProject to act on. Only needed for a credential that spans more than one project; a key identifies its own.-

All three are read automatically by createSynentoClient({}) for any option you leave out.

Troubleshooting

WebSocket opens, then closes immediately

The server refuses a connection by closing it (code 1008) just after it opens, not by failing the handshake. Check that:

  • the token has not expired (tokens last an hour by default; @synento/client mints a new one on every reconnect)
  • the session and user_id in the URL match the ones the token was minted for
  • SYNENTO_API_URL, if you set it, points at the same API that minted the token

Codes 4001 (call full), 4002 (account limit) and 4003 (replay allowance used) are plan limits; @synento/client reports them instead of reconnecting.

"401 Unauthorized" on API calls

  • Verify your key starts with sk_live_ (or rk_live_ for a restricted key)
  • Check the header is Authorization: Bearer <key>: the word Bearer, one space, then the key

Nothing to replay

  • Read GET /v1/sessions/{sessionId}/manifest: a participant whose media arrived has cam/mic tracks with a non-null start_ts. An empty participants list means no media reached Synento.
  • The dashboard's Recordings list shows sessions that have ended.

On this page