OneML reference

Stream

The <Stream> noun sends a call's audio to a WebSocket endpoint you control, for real-time processing such as a voice agent or a live transcription pipeline. Place <Stream> inside <Connect> for a two-way session that holds the document until it ends, inside <Start> to send audio one way in the background, or inside <Stop> to end a stream you started earlier.

In every form, url must start with wss://. Signals rejects the document otherwise.

Connect: two-way, blocking

<Connect><Stream> opens a two-way audio connection: Signals sends the caller's audio to your endpoint and plays back any audio your endpoint sends. The next verb runs only after the stream ends, when your endpoint closes the connection or the call ends.

<Connect> accepts these attributes:

Name	Type	Default	Description
`action`	string (uri)	None	Accepted but not applied. When the stream ends, the next verb in the document runs; Signals does not request this URL.
`method`	string	`POST`	HTTP method for `action`. `GET` or `POST`.

The nested <Stream> accepts:

Name	Type	Default	Description
`url`	string (uri)	None	Required. WebSocket URL to stream audio to and from. Must start with `wss://`.
`name`	string	None	Label that identifies this stream.

Start: one-way, non-blocking

<Start><Stream> sends the call's audio to your endpoint one way: Signals sends audio but does not play anything your endpoint sends. The next verb runs immediately while the stream continues in the background, until a matching <Stop> or the end of the call.

Name	Type	Default	Description
`url`	string (uri)	None	Required. WebSocket URL to stream audio to. Must start with `wss://`.
`name`	string	None	Label that identifies this stream, so a later `<Stop>` can target it.
`track`	string	`inbound_track`	Audio to stream: `inbound_track` (caller audio only), `outbound_track` (the other leg's audio only) or `both_tracks`.

Stop: end a stream

<Stop><Stream name="..."/></Stop> ends a stream started with <Start>, identified by name.

Name	Type	Default	Description
`name`	string	None	Required. Name of the stream to stop, matching the `name` given to `<Start><Stream>`.

Custom parameters

Place one or more <Parameter> elements inside <Stream>, in either the <Connect> or <Start> form, to send your own key and value pairs to your endpoint:

Name	Type	Default	Description
`name`	string	None	Required. Parameter name.
`value`	string	None	Required. Parameter value.

Metadata sent on stream start

When the stream starts, Signals sends your endpoint the following, alongside any <Parameter> values:

Field	Sent by `<Connect>`	Sent by `<Start>`
`call_sid`	Yes	Yes
`account_sid`	Yes	No
`custom_parameters` (containing `From` and `To`)	Yes	Yes

Examples

Connecting a call to a WebSocket voice agent:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Connecting you to our voice assistant.</Say>
  <Connect>
    <Stream url="wss://agent.example.com/voice-stream">
      <Parameter name="customerTier" value="gold"/>
    </Stream>
  </Connect>
</Response>

Sending audio to a background transcription service while the call is forwarded:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Stream url="wss://transcribe.example.com/live" name="call-transcript" track="both_tracks"/>
  </Start>
  <Say>This call is being transcribed for quality purposes.</Say>
  <Dial callerId="+2342013300100">+2348051234567</Dial>
</Response>

Stopping that stream from a later document:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stop>
    <Stream name="call-transcript"/>
  </Stop>
  <Hangup/>
</Response>