Session Management Guide

Deep dive into creating, managing, and controlling live streaming sessions.

Creating a Session

Sessions are the core unit of Synento. Every stream is attached to exactly one session:

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

Response:

{ "data": {
  "id": "sess_abc123",
  "project_id": "proj_xyz789",
  "name": "Team Standup",
  "created_by": "api-key-user",
  "started_at": null,     // set when first participant joins
  "ended_at": null,       // set when last participant leaves
  "created_at": "2025-01-15T10:30:00.000Z"
}, "error": null }

Options

Field	Required	Default	Description
`name`	No	"Untitled session"	Display name for the session

Session Lifecycle

Created → Waiting for participants...
   ↓ (first join)
Started — Active streaming, recording begins
   ↓ (participant leaves)
Still Started (other participants remain)...
   ↓ (last participant leaves)  
Ended — Recording complete, replay available immediately

Lifecycle Timestamps

Field	Set When	Value
`created_at`	Session created via API	ISO 8601 timestamp
`started_at`	First participant joins	ISO 8601 timestamp
`ended_at`	Last participant leaves	ISO 8601 timestamp

Duration calculation: ended_at - started_at (in milliseconds). Usage tracking records this as streaming_minutes.

Listing Sessions

Retrieve all sessions for a project:

curl https://api.synento.com/v1/sessions \
  -H "Authorization: Bearer sk_live_xxxxx"

Returns sessions sorted by created_at DESC. The same endpoint is accessible via SDK:

const sessions = await synento.listSessions();
// [{ id, name, startedAt, endedAt, createdAt }, ...]

Getting Session Details

Fetch a single session:

curl https://api.synento.com/v1/projects/{projectId}/sessions/{sessionId} \
  -H "Authorization: Bearer sk_live_xxxxx"

Connection Tokens

Every participant needs a connection token to join or replay:

For Live Streaming

curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"user_id": "alice", "focus": ""}'

For Replay Mode

curl -X POST https://api.synento.com/v1/sessions/{sessionId}/connection \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"user_id": "viewer", "replay": true, "from_ts": 0, "speed": 1.0}'

Token Connection Parameters

Parameter	Type	Default	Description
`user_id`	string	`"anonymous"`	Participant identifier (appears in chat/media headers)
`replay`	boolean	false	If true, enables replay mode instead of live streaming
`from_ts`	number (ms)	0	Replay start timestamp; use session's `min_ts` from timeline API
`speed`	number	1.0	Replay speed multiplier (0.25x to 4x)
`focus`	string	""	Focus on a specific stream (user ID or empty for all)

Token Response

{ "data": {
  "access_token": "jwt_eyJhbGc...",    // JWT valid for 5 minutes
  "expires_in": 300,                     // seconds until expiry
  "session": "sess_abc123"              // session ID
}, "error": null }

The connection token's access_token is used to connect via WebSocket:

const wsUrl = synento.getWebSocketUrl(sessionId, accessToken, "alice");
// → wss://host/ws?session=sess_abc123&access_token=jwt_eyJhbGc...&user_id=alice

Session Visibility Management

Sessions are private by default. Control who can replay them:

Toggle Public/Private

# Make this session publicly accessible (no auth needed for replay)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": true}'

# Revert to private (only connection token holders can access)
curl -X PUT https://api.synento.com/v1/sessions/{sessionId}/visibility \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -d '{"is_public": false}'

Setting via SDK

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

Billing & Session Limits

New session creation is checked against billing limits:

Free tier: 300 streaming minutes/month across the organisation
If exceeded with no active Stripe subscription, new sessions are blocked (402 error)

Check current limits before creating sessions:

curl https://api.synento.com/v1/billing/limits \
  -H "Authorization: Bearer sk_live_xxxxx"

# Check before every new session in your app
const limits = await synento.getBillingLimits();
if (limits.isBlocked) {
  console.error(limits.statusMessage); // Show user-friendly error to developer
}

Common Patterns

Create Session, Get Token, Connect (All in One Flow)

const session = await synento.createSession({ name: "Team Meeting" });
const token = await synento.createConnectionToken(session.id, { userId: "alice" });

// WebSocket URL
const wsUrl = synento.getWebSocketUrl(session.id, token.accessToken, "alice");

// For embedding in the browser (token generated server-side):
document.getElementById("player").src = wsUrl; // or use Player SDK with access_token

List and Replay All Ended Sessions in a Project

const sessions = await synento.listSessions();
for (const session of sessions) {
  if (session.endedAt && !session.isPublic) {
    const token = await synento.createConnectionToken(session.id, { 
      userId: "replay-bot",
      replay: true,
    });
    // Use the token with Player SDK or direct WebSocket for replay...
  }
}

Session Management Guide

On this page