Skip to main content
This guide explains the common streaming architecture used by all Suki modalities. Create a session using a REST API, stream live audio over a WebSocket connection, then end the session using a REST API. Ambient and Dictation both stream audio as JSON text frames, with each frame containing a single JSON object. Although the streaming pattern is the same, each API uses different endpoints, message formats, and result retrieval workflows.
Use the same base host for REST and WebSocket in a given environment (for example staging https://sdp.suki-stage.com and wss://sdp.suki-stage.com). Your partnership team confirms which host and credentials apply.
Read the following related guides:

Click Each Button to Learn More

This guide applies to: Direct HTTP and WebSocket integrations with Suki for Partner Ambient, Form filling, and Dictation APIs. Form filling uses the same ambient socket (GET /ws/stream) with an ambient session ID.
Do not send raw audio as binary WebSocket frames on /ws/stream or /ws/transcribe. Outbound audio is Base64 inside JSON text frames.

​
What this guide covers

Use this page to understand the end-to-end flow before you implement a client:
  • What Ambient (and Form filling) and Dictation share
  • Where the two products differ (endpoint, messages, results)
  • Network and connection rules that affect both
  • Stage-by-stage Ambient and Dictation flows
For field-level JSON shapes and chunking, open WebSocket streaming wire format. For a compact endpoint comparison, open Ambient vs Dictation streaming.

​
What stays the same

Across Ambient, Form filling, and Dictation:
  1. Authenticate with Partner APIs and obtain an sdp_suki_token.
  2. Create a session with REST.
  3. Open a WebSocket Secure (wss://) connection on the same base host as REST.
  4. Send one UTF-8 JSON text frame per message (exactly one JSON object per frame).
  5. Put audio bytes in a Base64 string field inside that JSON, not in a binary WebSocket frame.
  6. Close the socket, then use REST to end the session and retrieve final results as needed.

​
What differs

​
High-level architecture

Below is the high-level architecture for Ambient, Form filling, and Dictation flows. Where they differ is the:
  • Endpoint
  • Outbound message contract
  • How results come back

​
Network and connection management

Plan your integration around the following network requirements and connection behaviors.

​
Network requirements

For reliable real-time streaming, Suki recommends these minimums: Refer to Audio capture and streaming FAQs for the source list.

​
How do you keep the connection alive

While a stream is paused, send an EVENT message with event: KEEP_ALIVE at least once every five seconds. Ambient streaming allows a maximum pause of 30 minutes. For related idle-timeout guidance (including the 25 second audio inactivity window), see the Ambient API quickstart and Audio capture and streaming FAQs.

​
Call duration and reconnection

Ambient
  • There is no upper limit on call duration while the stream is active.
  • You can reopen GET /ws/stream with the same ambient_session_id only while the ambient job is still in the CREATED state. If the job has moved to another status (for example RUNNING, COMPLETED, or CANCELLED), the handshake fails with FailedPrecondition.
  • Suki needs a minimum amount of audio to generate content. For calls shorter than 1 minute, Suki may not have enough data, returns empty content, and marks the session as skipped.
Dictation
  • One Dictation session can support multiple speech sessions over time (for example push-to-talk).
  • Open /ws/transcribe only when the session is READY or IDLE. See Stream Dictation audio for the session-state rules.

​
How streaming works

Choose the tab for your product. Ambient (and Form filling on the same socket) and Dictation share the REST → WebSocket → REST pattern, but use different endpoints and message contracts.
Use this path when you already have an ambient session (or a Form filling session on the same socket) and stream to GET /ws/stream.The WebSocket carries live audio and control messages only. After streaming, use ambient REST APIs to end the session, poll status, and retrieve transcripts, notes, and structured data.
  1. Create an ambient session and seed session context with REST.
  2. Open a WebSocket connection to GET /ws/stream.
  3. Send one START_TIME message for the stream segment.
  4. Send one JSON message per audio chunk (Base64 PCM in data).
  5. Optionally send EVENT messages, such as PAUSE, RESUME, or KEEP_ALIVE, when control is needed.
  6. Send the ambient end marker as the final AUDIO message (data: RU9G).
  7. Close the socket, then end the ambient session with REST and retrieve results.

​
Create the Ambient session and seed context

Create the session with REST, then seed session context before you stream. Do not open the WebSocket until the ambient session exists and context is seeded.

​
Open WebSocket GET /ws/stream

Authenticate with the documented handshake:
  • Browser Sec-WebSocket-Protocol: SukiAmbientAuth,<sdp_suki_token>,<ambient_session_id> (token before session ID)
  • Non-browser headers: sdp_suki_token and ambient_session_id
Open the socket only when the ambient job is still in the CREATED state. Other statuses return FailedPrecondition.

​
Send START_TIME

Send one START_TIME message for the stream segment before audio chunks. This is required for Ambient in the documented contract.

​
Send AUDIO chunks

Send one JSON text frame per chunk. Audio bytes are Base64 PCM in the data field.Do not:
  • Send binary WebSocket frames
  • Send multiple JSON objects in one frame
  • Stream raw audio over HTTP

​
Optional EVENT messages

When control is needed, send EVENT messages such as PAUSE, RESUME, KEEP_ALIVE, CANCEL, or ABORT. The gateway acts on PAUSE, RESUME, and CANCEL. While paused, send KEEP_ALIVE at least once every five seconds per the documented idle-timeout guidance. Refer to the Audio capture and streaming FAQs for the full event enum.

​
End the stream with RU9G

End the stream segment with a final AUDIO message whose data is RU9G (Base64 of the bytes EOF).

​
Close the socket, then finish with REST

Close the WebSocket, then end the ambient session with REST and retrieve results. Final transcripts and notes are not guaranteed on the WebSocket. Treat REST as the source of truth after streaming.For field-level message shapes, refer to the Ambient tab in WebSocket streaming wire format. For end-of-session steps, refer to Complete the session after streaming.

​
Available tutorials

Ambient

​
Build an Ambient Streaming Client

Authenticate, create a session, stream PCM audio over WebSocket, and retrieve clinical note results.

20 minIntermediate
Dictation

​
Build a Dictation Streaming Client

Create a transcription session, stream audio, read partial frames, and print the final transcript.

15 minIntermediate
Form Filling

​
Build a Form Filling Session Client

Create a Form filling session, send template context, stream audio, and retrieve structured form data.

20 minIntermediate

​
Next steps

Follow Ambient vs Dictation streaming to compare endpoints, auth, and message contracts. Read Audio capture best practices before you open the WebSocket. Follow Stream ambient audio when you already have an ambient session and need to push live audio on /ws/stream. Follow Stream Dictation audio when you have a Dictation session and need real-time transcript frames on /ws/transcribe. Open WebSocket streaming wire format for message types, send order, and chunking.
Last modified on July 24, 2026