Start a live transcription

Live speech uses two REST calls around a WebSocket stream:

1. create a session;
2. connect to the returned WebSocket URL and stream raw PCM audio;
3. receive recognition messages;
4. stop the session to finalize the call.

The account must have Live Transcription enabled. Otherwise, the start and stop operations return 403 Forbidden.

1. Start the session

Authenticate as described in Submit your first transcription, then call:

curl --request POST "https://api.example.com/api/v1/live-speech/start" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "support-call-42",
    "numberOfChannels": 2,
    "language": 1,
    "translationLanguage": 4,
    "username": "agent@example.com",
    "local": "1001",
    "remote": "+15551234567",
    "sampleRate": 16000,
    "multilingualDetection": false,
    "autoTranslationDirection": false
  }'

The response supplies everything needed to stream and view the call:

{
  "id": 4821,
  "url": "wss://api.example.com/ws/transcribe?sessionId=4821",
  "pinCode": "341882"
}

Save the session id. The PIN can be shared with a viewer who is allowed to follow the live call without a full account login.

2. Stream audio

Connect to the returned url and set the WebSocket Authorization header to the raw JWT. For this socket, send the token itself without the REST Bearer prefix.

Send audio as binary WebSocket messages in real time. Use uncompressed PCM samples matching sampleRate and numberOfChannels; do not send the WAV header. A practical chunk is 9,600 bytes per channel, paced according to the audio byte rate.

For stereo audio, channel 1 is treated as the agent (Left) and channel 0 as the customer (Right). Mono uses the shared Both channel and cannot provide true per-speaker metrics.

The server returns text messages with recognition states such as recognizing for interim text and recognized for finalized segments. Clients should reassemble fragmented WebSocket frames before parsing each JSON message.

Reference client

Speechlytics.RealTimeTranscriptionClient in the product repository is an end-to-end .NET example. It reads a PCM WAV file, starts the session, strips the 44-byte header, streams chunks at real-time speed, prints recognition events, and stops the session.

3. Stop and finalize

curl --request POST "https://api.example.com/api/v1/live-speech/stop" \
  --header "Authorization: Bearer $SPEECHLYTICS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"id": 4821}'

Successful finalization returns:

{"isValid": true}

Stopping persists the recording, closes live processing, and starts the enabled post-call pipeline. An unknown session returns 404 Not Found.

Live events and incremental audio

Accounts with the Events API feature can consume live intelligence in two ways:

• GET /api/v1/calls/{id}/live-events?afterId=<cursor>&limit=<n> returns events after a durable cursor. Use the largest returned id as the next afterId.
• /ws/live-events?callId=<id> pushes the same event stream over WebSocket. Authenticate with the Authorization header.

GET /api/v1/calls/{id}/live-payload?fromByte=<offset> returns only the recorded audio after the supplied byte offset. Persist totalBytes and pass it as the next fromByte to keep polling responses constant in size.

The live event stream can include keyword detections, alerts, language, sentiment, conversation state, summaries, and coaching, depending on account configuration. See Live transcription and translation for the dependency map and behavior of all live features.

Common failures

Symptom	Resolution
Start or stop returns 403	Enable Live Transcription for the account.
WebSocket returns 400	Upgrade the request to WebSocket and use the exact returned URL.
No transcript messages	Verify PCM format, sample rate, channel count, pacing, and authentication.
Stereo speakers are reversed	Ensure channel 1 contains the agent and channel 0 the customer.
Live events return 403	Enable the account's Events API feature.
Live payload returns 404	Verify the call belongs to the token's account and the session is still live.