Copy page

OneML reference

Stream

The <Stream> noun forks a call's audio to a WebSocket endpoint you control, for real-time processing such as a live voice agent or transcription pipeline. Nest <Stream> inside <Connect> for a two-way, blocking media session, inside <Start> to fork audio one-way in the background without blocking the document, or inside <Stop> to end a stream you started earlier.

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

Connect: bidirectional, blocking

<Connect><Stream> opens a two-way audio connection: PressOne sends the caller's audio to your WebSocket endpoint, and plays back any audio your endpoint sends in return. <Connect><Stream> blocks: PressOne waits for the stream to end (your endpoint closes the connection, or the call ends) before executing the next verb in the document.

<Connect> itself accepts action and method attributes:

Name	Type	Default	Description
action	string (uri)	—	Accepted but not currently applied. When the stream ends, execution continues with the next verb in the document; PressOne does not request this URL.
method	string	POST	HTTP method for action. One of GET or POST.

The nested <Stream> accepts:

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

Start: one-way, non-blocking

<Start><Stream> forks the call's audio to your WebSocket endpoint one way: PressOne sends audio, but does not play back anything your endpoint sends. <Start> does not block: PressOne starts the stream in the background and immediately executes the next verb in the document. The stream keeps running until a matching <Stop> or the call ends.

Name	Type	Default	Description
url	string (uri)	—	Required. WebSocket URL to stream audio to. Must start with wss://.
name	string	—	Label to identify this stream, so a later <Stop> can target it.
track	string	inbound_track	Which audio to stream. One of 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 previously started with <Start>, identified by name.

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

Custom parameters

Nest one or more <Parameter> elements inside <Stream> (either the <Connect> or <Start> form) to send custom key/value data to your WebSocket endpoint:

Name	Type	Default	Description
name	string	—	Required. Parameter name.
value	string	—	Required. Parameter value.

Metadata sent on stream start

When the stream starts, PressOne includes the following in the metadata delivered to your WebSocket endpoint, 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"/>
  </Connect>
</Response>

Forking audio to a background transcription service without blocking the call, then stopping it later:

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>+2341800000001</Dial>
</Response>

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

See also

• Dial
• Disconnect
• OneML overview