Form Filling Audio Streaming

GET

stream

cURL

curl --request GET \
  --url https://sdp.suki.ai/ws/stream \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --header 'ambient_session_id: <ambient_session_id>'

import requests

url = "https://sdp.suki.ai/ws/stream"

headers = {
    "ambient_session_id": "<ambient_session_id>",
    "sdp_suki_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {ambient_session_id: '<ambient_session_id>', sdp_suki_token: '<api-key>'}
};

fetch('https://sdp.suki.ai/ws/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/ws/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ambient_session_id: <ambient_session_id>",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/ws/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("ambient_session_id", "<ambient_session_id>")
	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/ws/stream")
  .header("ambient_session_id", "<ambient_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/ws/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["ambient_session_id"] = '<ambient_session_id>'
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

Use this API to stream visit audio over the Partner WebSocket (GET /ws/stream) for Form filling sessions. For more information on how to handle the handshake, wire format, message order, and error handling, and poll for structured data when the session is complete, refer to the Aaudio streaming guide.

Use the ambient_session_id from Create Form Filling session while streaming audio. Do not use the ambient_session_id from an Create Ambient session, even though both fields use the name ambient_session_id.

Prerequisites

Complete these steps before you open the WebSocket.

Opening /ws/stream before the session and context are ready can cause handshake failures or a broken stream.

Authenticate and obtain sdp_suki_token
Create a Form filling session with POST /api/v1/form-filling/session/create. Save the ambient_session_id from the 201 Created response
Seed session context (recommended) with POST /api/v1/form-filling/session/{ambient_session_id}/context. Include form_template_id values when you send context
Open the WebSocket at wss://sdp.suki-stage.com/ws/stream (staging) or wss://sdp.suki.ai/ws/stream (production). Use your Form filling ambient_session_id in the handshake

Browser clients

Send Sec-WebSocket-Protocol during the handshake as one comma-separated string, in this order:

Subprotocol name
Form filling session ID (ambient_session_id)
sdp_suki_token

Do not add spaces between values unless your client library requires them.

Example:

Sec-WebSocket-Protocol: SukiAmbientAuth,<ambient_session_id>,<sdp_suki_token>

The server negotiates this subprotocol to establish the connection.

Non-browser clients

For mobile apps, backend services, or testing tools, pass headers on the WebSocket upgrade request. Do not use Sec-WebSocket-Protocol.

sdp_suki_token - Session token from login
sdp_provider_id - Provider identifier. Optional for standard partners; required for Single Auth Token authentication
ambient_session_id - Form filling session ID from Create Form Filling session

Sending non-JSON payloads where the server expects JSON can cause parse errors (for example invalid character or null byte errors).

Code examples

Python
TypeScript

# pip install websocket-client
import base64
import json
from datetime import datetime, timezone

import websocket

# Form filling ambient_session_id from POST /api/v1/form-filling/session/create
form_filling_session_id = "<form_filling_ambient_session_id>"
token = "<sdp_suki_token>"
sdp_provider_id = "<sdp_provider_id>"  # Optional; Required for Single Auth Token authentication
CHUNK_BYTES = 3200
WAV_HEADER_BYTES = 44

ws_url = "wss://sdp.suki-stage.com/ws/stream"
ws = websocket.create_connection(
    ws_url,
    header=[
        f"sdp_suki_token: {token}",
        f"sdp_provider_id: {sdp_provider_id}",
        f"ambient_session_id: {form_filling_session_id}",
    ],
)


def b64(data: bytes) -> str:
    return base64.b64encode(data).decode("ascii")


try:
    rfc3339 = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    ws.send(json.dumps({"type": "START_TIME", "data": b64(rfc3339.encode("utf-8"))}))

    with open("audio.wav", "rb") as f:
        raw = f.read()
    if len(raw) >= 12 and raw[:4] == b"RIFF" and raw[8:12] == b"WAVE":
        pcm = raw[WAV_HEADER_BYTES:]
    else:
        pcm = raw

    for i in range(0, len(pcm), CHUNK_BYTES):
        chunk = pcm[i : i + CHUNK_BYTES]
        ws.send(json.dumps({"type": "AUDIO", "data": b64(chunk)}))

    ws.send(json.dumps({"type": "AUDIO", "data": b64(b"EOF")}))

    while True:
        try:
            print(ws.recv())
        except websocket.WebSocketConnectionClosedException:
            break
finally:
    ws.close()

// Browser example: use Form filling ambient_session_id from POST /api/v1/form-filling/session/create

const formFillingSessionId = '<form_filling_ambient_session_id>';
const token = '<sdp_suki_token>';
const CHUNK_BYTES = 3200;
const WAV_HEADER_BYTES = 44;

function utf8ToBase64(s: string): string {
  const bytes = new TextEncoder().encode(s);
  let binary = '';
  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!);
  return btoa(binary);
}

function bytesToBase64(u8: Uint8Array): string {
  let binary = '';
  for (let i = 0; i < u8.length; i++) binary += String.fromCharCode(u8[i]!);
  return btoa(binary);
}

const ws = new WebSocket(`wss://sdp.suki-stage.com/ws/stream`, [
  `SukiAmbientAuth,${formFillingSessionId},${token}`,
]);

ws.binaryType = 'arraybuffer';

ws.onopen = () => {
  const rfc3339 = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
  ws.send(JSON.stringify({ type: 'START_TIME', data: utf8ToBase64(rfc3339) }));

  const input = document.getElementById('audioFile') as HTMLInputElement;
  const file = input.files?.[0];
  if (!file) return;

  const reader = new FileReader();
  reader.onload = () => {
    const buf = new Uint8Array(reader.result as ArrayBuffer);
    let pcm = buf;
    if (
      buf.length >= 12 &&
      buf[0] === 0x52 &&
      buf[1] === 0x49 &&
      buf[2] === 0x46 &&
      buf[3] === 0x46 &&
      buf[8] === 0x57 &&
      buf[9] === 0x41 &&
      buf[10] === 0x56 &&
      buf[11] === 0x45
    ) {
      pcm = buf.subarray(WAV_HEADER_BYTES);
    }
    for (let i = 0; i < pcm.length; i += CHUNK_BYTES) {
      const chunk = pcm.subarray(i, i + CHUNK_BYTES);
      ws.send(JSON.stringify({ type: 'AUDIO', data: bytesToBase64(chunk) }));
    }
    ws.send(
      JSON.stringify({
        type: 'AUDIO',
        data: bytesToBase64(new Uint8Array([0x45, 0x4f, 0x46])),
      }),
    );
  };
  reader.readAsArrayBuffer(file);
};

ws.onmessage = (ev) => console.log('Received:', ev.data);
ws.onerror = (e) => console.error(e);
ws.onclose = () => console.log('closed');

Authorizations

sdp_suki_token

string

header

required

Suki access token for the authenticated provider. Obtain this by calling Login or Register with a valid partner_token. Pass the suki_token value from the JSON response as the sdp_suki_token header on REST requests and non-browser WebSocket upgrades. Browser WebSocket clients pass the token in Sec-WebSocket-Protocol instead. Tokens expire after one hour; call Login again to refresh.

Headers

Sec-WebSocket-Protocol

string

Required FOR BROWSER CLIENTS ONLY. Sent during WebSocket handshake. Format: 'SukiAmbientAuth,<ambient_session_id>,<sdp_suki_token>' (comma-separated, no spaces required between parts).

ambient_session_id

string

required

Required for non-browser clients only. Session UUID from Create Ambient Session or Create Form Filling Session.

sdp_provider_id

string

Optional - Stable identifier for the active provider. Omit for standard partners whose partner_token identifies the user. Required for Bearer partners and Single Auth Token authentication where multiple providers share one partner_token. Use the same provider_id you sent on Login or Register.

Example:

"provider-123"

Response

Switching Protocols - Indicates successful WebSocket handshake.

The response is of type string.

Last modified on June 30, 2026

Update Form Filling Session Context

End Form Filling Session

⌘I

cURL

curl --request GET \
  --url https://sdp.suki.ai/ws/stream \
  --header 'sdp_suki_token: <sdp_suki_token>' \
  --header 'sdp_provider_id: <sdp_provider_id>' \
  --header 'ambient_session_id: <ambient_session_id>'

import requests

url = "https://sdp.suki.ai/ws/stream"

headers = {
    "ambient_session_id": "<ambient_session_id>",
    "sdp_suki_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {ambient_session_id: '<ambient_session_id>', sdp_suki_token: '<api-key>'}
};

fetch('https://sdp.suki.ai/ws/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sdp.suki.ai/ws/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "ambient_session_id: <ambient_session_id>",
    "sdp_suki_token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sdp.suki.ai/ws/stream"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("ambient_session_id", "<ambient_session_id>")
	req.Header.Add("sdp_suki_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sdp.suki.ai/ws/stream")
  .header("ambient_session_id", "<ambient_session_id>")
  .header("sdp_suki_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sdp.suki.ai/ws/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["ambient_session_id"] = '<ambient_session_id>'
request["sdp_suki_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

"<string>"

​Prerequisites

​Browser clients

​Non-browser clients

​Code examples

Authorizations

Headers

Response

Prerequisites

Browser clients

Non-browser clients

Code examples