Skip to main content
WSS
Planned protocol reference. Live sessions and this WebSocket stream are not served by the current Talent API sandbox. Start with the runnable quickstart and sandbox support matrix.
The planned session stream pushes changes to a live voice or video session as they happen. Stay connected for the whole session: a revocation or a denied sample reaches you here before your next renewal would fail.

Connect

Open a WebSocket to the stream_url returned by POST /v1/sessions:
Authenticate in one of two ways: Reflections selects tlp.session.v1 and never echoes the token, so it stays out of response headers and proxy logs. The token is checked once, when the connection opens. Renewing it with POST /v1/sessions/{session_id}/renew keeps the session alive and does not reconnect the stream. Message fields follow the API version the session was created with. The first message is session.ready. Messages arrive in order on one connection. Send a ping at least every 30 seconds when nothing else is sent; Reflections answers with a pong carrying the same id. The stream closes when the session ends.

Send samples

You can send samples on the stream as sample.submit instead of calling POST /v1/sessions/{session_id}/samples, which saves a round trip per sample. Send them at least as often as the session’s sampling requires. A sample sent with POST gets its decision in the response; a sample sent on the stream gets it as sample.decided.
A sample that gets an error was not received. It does not count toward sampling, so send a corrected one before the next act_by:
code is one of invalid_request (text that is not JSON, or an unknown type), parameter_missing, parameter_invalid, unsupported_media_type, media_unreadable and payload_too_large. detail is for you, not your user.

Stop within one second

When session.terminated arrives, stop generating and stop playing what you already generated, within one second. Do not wait for the current sentence or frame to finish. Then end the session on your side and report its usage up to at. The session.terminated webhook reports the same termination, usually later, in data.object.termination; act on whichever arrives first.

Close codes

A request that is not a WebSocket upgrade gets 426 Upgrade Required, and one that does not offer tlp.session.v1 gets 400 invalid_request, each with a problem details body. Every other failure happens after the upgrade, so a browser can read it too: Reflections closes the connection with a code and a reason, without sending session.ready. The 44xx codes are the HTTP status plus 4000, and their reasons are the error codes the same failure gets over REST.

Reconnect

If the connection drops with any code other than 1000, reconnect with the session’s current token, the one from your last renewal. Before you reconnect, read the session with GET /v1/sessions/{session_id}: if status is terminated or ended, a session.terminated you missed is recorded in termination, and you stop output instead of reconnecting. If you cannot read the session, stop output no later than when the current token expires; the example stops at once. Renewal is the second safeguard: when a renewal fails with session_not_active, stop output at once.

Example

Real-time sessions

Renewal, sampling, termination and the one-second stop.

Session token

The claims in the token, and how a provider verifies it.
session_id
type:string
required

The session ID, ses_….

Sec-WebSocket-Protocol
type:httpApiKey

tlp.session.<token> with the session's current token, offered with tlp.session.v1. Use this from a client.

secretKey
type:http

Your secret key. Use this only from a server.

method
type:string

GET

headers
type:object
Sec-WebSocket-Protocol
type:string
required

From a client: tlp.session.v1, tlp.session.<token>. From a server: tlp.session.v1.

Authorization
type:string

From a server only: Bearer and your secret key.

Session ready
type:object

Sent once, when the connection is authenticated.

Session warning
type:object

Something will end the session unless you act.

Session terminated
type:object

Stop output within one second. Renewals now fail.

Sample decided
type:object

The decision on a sample you sent on the stream. A deny is followed by session.terminated.

Error
type:object

A message you sent could not be used. The connection stays open.

Pong
type:object

The answer to a ping.

Submit a sample
type:object

A sample of what the session produced, with the same fields as the REST call.

Ping
type:object

Keeps the connection open. Send one at least every 30 seconds when nothing else is sent.