Initiate an Audio Stream

This method lets you initiate an audio stream for an active call and send that stream to a secure WebSocket URL.

Initiate real-time audio streaming for an active call. The audio stream connects to your WebSocket URL and transmits raw audio data that you can process, transcribe, or analyze in real-time.

Requirement: The call must be active (in-progress status) before you can initiate an audio stream. You'll need the call_uuid from when the call was created.

HTTP Request

POSThttps://api.vobiz.ai/api/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Authentication: Include X-Auth-ID and X-Auth-Token headers.

Request Parameters

Name	Type	Description
`service_url`Required	string	WebSocket URL to which the audio stream is initiated. Example: wss://yourapp.example.com/audiostream. If a valid URL is not provided or an active stream already exists at the URL, a 400 error is returned.
`bidirectional`	boolean	Specifies if the WebSocket supports bidirectional audio streaming (read and write). If true, Vobiz accepts: (1) event: Takes "playAudio" as value, (2) media: JSON object with contentType (audio/x-l16, audio/x-mulaw), sampleRate (8000, 16000), and payload (Base64-encoded raw audio).
`audio_track`	string	The audio track of the call to stream. Values: "inbound" (default - only audio received by Vobiz), "outbound" (only audio sent by Vobiz), "both" (both directions). Note: If bidirectional is true, audio_track must not be "outbound" or "both".
`stream_timeout`	integer	Maximum duration (in seconds) for audio streaming. Streaming stops after this duration without affecting the rest of the call. Must be a positive integer. Default: 86400 (24 hours).
`status_callback_url`	string	URL to notify when specific stream events occur: stream is connected and audio begins, stream is stopped or times out, stream fails to connect or gets disconnected.
`status_callback_method`	string	HTTP method to use for the status_callback_url. Allowed values: GET, POST. Default: POST.
`content_type`	string	Preferred audio codec and sample rate. Allowed values: "audio/x-l16;rate=8000" (default), "audio/x-l16;rate=16000", "audio/x-mulaw;rate=8000".
`extra_headers`	string	Key-value pairs passed to the WebSocket service with each request. Format: "key1=value1,key2=value2". Must be under 512 bytes in total. Only alphanumeric characters [A-Z], [a-z], [0-9] are allowed in keys and values.

Important: When bidirectional is set to true, the audio_track value should not be set to "outbound" or "both".

Response

Returns the complete audio stream object including the auto-generated stream_id UUID and timestamps.

Response - 201 Created

{
  "api_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "audio_track": "both",
  "bidirectional": false,
  "bill_duration": 27,
  "billed_amount": "0.00300",
  "call_uuid": "call-uuid-xxxx-yyyy-zzzz-abcd",
  "created_at": "2025-11-14 02:44:50.617032+00:00",
  "end_time": "2025-11-14 08:14:50+05:30",
  "account_id": "MA_AABBCC",
  "resource_uri": "/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy-zzzz-abcd/Stream/stream-id-aabbcc-ddeeff/",
  "rounded_bill_duration": 60,
  "service_url": "wss://yourapp.example.com/audiostream",
  "start_time": "2025-11-14 08:14:29+05:30",
  "stream_id": "stream-id-aabbcc-ddeeff"
}

Examples

cURL - Basic Audio Stream

cURL Request

curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_url": "wss://yourapp.example.com/audiostream"
  }'

cURL - Bidirectional Stream with Callbacks

cURL Request

curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_url": "wss://yourapp.example.com/audiostream",
    "bidirectional": true,
    "audio_track": "inbound",
    "content_type": "audio/x-l16;rate=16000",
    "status_callback_url": "https://yourapp.example.com/stream-status",
    "status_callback_method": "POST"
  }'

cURL - Advanced Stream with Extra Headers

cURL Request

curl -X POST https://api.vobiz.ai/api/v1/Account/MA_AABBCC/Call/call-uuid-xxxx-yyyy/Stream/ \
  -H "X-Auth-ID: YOUR_AUTH_ID" \
  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_url": "wss://yourapp.example.com/audiostream",
    "bidirectional": false,
    "audio_track": "both",
    "stream_timeout": 3600,
    "content_type": "audio/x-l16;rate=16000",
    "extra_headers": "sessionid=abc123,userid=xyz789",
    "status_callback_url": "https://yourapp.example.com/stream-status"
  }'

Next Steps:

• Save the stream_id for retrieval and management
• Configure your WebSocket server to handle incoming audio data
• Set up status callback handlers to monitor stream lifecycle events
• Test the stream with a sample call before production use

The Audio Stream Object

Retrieve an Audio Stream

Initiate an Audio Stream

HTTP Request

Request Parameters

Request Parameters

Response

Examples

cURL - Basic Audio Stream

cURL - Bidirectional Stream with Callbacks

cURL - Advanced Stream with Extra Headers

On this page