Streaming start
POST/calls/:call_control_id/actions/streaming_start
Start streaming the media from a call to a specific WebSocket address or Dialogflow connection in near-realtime. Audio will be delivered as base64-encoded RTP payload (raw audio), wrapped in JSON payloads.
Example: Starting a stream to a Websocket address
The stream_url
param is mandatory.
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '{
"stream_url": "wss://www.example.com/websocket",\
"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d",\
"command_id":"891510ac-f3e4-11e8-af5b-de00688a4901" \
}' \
https://api.telnyx.com/v2/calls/{call_control_id}/actions/streaming_start
Example: Starting a stream to a Dialogflow connection
Enable the Dialogflow integration by sending "enable_dialogflow": true
in the request. You need to have a Dialogflow connection associated with your Call Control application first, click here for instructions.
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer YOUR_API_KEY" \
--data '\{
"client_state":"aGF2ZSBhIG5pY2UgZGF5ID1d", \
"command_id":"891510ac-f3e4-11e8-af5b-de00688a4901", \
"enable_dialogflow": true \
\}' \
https://api.telnyx.com/v2/calls/\{call_control_id\}/actions/streaming_start
Expected Webhooks (see callback schema below):
streaming.started
streaming.stopped
streaming.failed
WebSocket events
When the WebSocket connection is established, the following event is being sent over it:
\{
"event": "connected",
"version": "1.0.0"
\}
And when the call is started, an event which contains information about the encoding and stream_id
that identifies a particular stream:
\{
"event": "start",
"sequence_number": "1",
"start": \{
"user_id": "3e6f995f-85f7-4705-9741-53b116d28237",
"call_control_id": "v3:MdI91X4lWFEs7IgbBEOT9M4AigoY08M0WWZFISt1Yw2axZ_IiE4pqg",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"media_format": \{
"encoding": "audio/x-mulaw",
"sample_rate": 8000,
"channels": 1
\}
\},
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
\}
The start event is followed by the following media events that contain base64-encoded RTP payload (raw audio, no RTP headers) (:
\{
"event": "media",
"sequence_number": "4",
"media": \{
"track": "inbound/outbound",
"chunk": "2",
"timestamp": "5",
"payload": "no+JhoaJjpzSHxAKBgYJD...IsSbjomGhoqQn1Ic"
\},
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
\}
Please note that the order of events is not guaranteed and the chunk number can be used to reorder the events.
When the call ends, the stop event over WebSockets connection is sent:
\{
"event": "stop",
"sequence_number": "5",
"stop": \{
"user_id": "3e6f995f-85f7-4705-9741-53b116d28237",
"call_control_id": "v2:T02llQxIyaRkhfRKxgAP8nY511EhFLizdvdUKJiSw8d6A9BborherQ"
\},
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc"
\}
Bidirectional Media Streaming
Media can be sent back to the call through the websocket as well. This is done in a way very similar to the playback_start command, when using a base64 encoded mp3 file in the payload. Simply send a packet to the websocket connection as follows:
\{
"event": "media",
"media": \{
"payload" : <your base64 encoded mp3 file>
\}
\}
The payload, which is a base64-encoded mp3 file, will be played on the call.
Some limitations to be aware of:
- Media payloads can only be submitted once per second.
- Media must be base64 encoded mp3
Stream Errors
Any errors in the media packet, including when a rate limit is reached, will result in an error frame being sent to your websocket server. The error frame will appear as follows:
\{
"stream_id": "32de0dea-53cb-4b21-89a4-9e1819c043bc",
"event": "error",
"sequence_number": "6",
"error": \{
"title": "rate_limit_reached",
"code": "100005",
"detail": "Too many requests"
\}
\}
Possible errors are as follows:
- Error 100002:
"unknown_error"
- Error 100003:
"malformed_frame"
- Error 100004:
"invalid_media"
- Error 100005:
"rate_limit_reached"
Request
Path Parameters
Unique identifier and token for controlling the call
- application/json
Body
required
Start streaming media request
The destination WebSocket address where the stream is going to be delivered.
Possible values: [inbound_track
, outbound_track
, both_tracks
]
Default value: inbound_track
Specifies which track should be streamed.
Possible values: [mp3
, rtp
]
Default value: mp3
Configures method of bidirectional streaming (mp3, rtp).
Possible values: [PCMU
, PCMA
, G722
]
Default value: PCMU
Indicates codec for bidirectional streaming RTP payloads. Used only with stream_bidirectional_mode=rtp. Case sensitive.
Enables Dialogflow for the current call. The default value is false.
dialogflow_config
object
Enable sentiment analysis from Dialogflow.
Enable partial automated agent reply from Dialogflow.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id
for the same call_control_id
.
Responses
200: Successful response upon making a call control command.
- application/json
default: Unexpected error
- application/json
Request samples
curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/streaming_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"stream_url": "wss://www.example.com/websocket",
"stream_track": "both_tracks",
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
"enable_dialogflow": false,
"dialogflow_config": {
"analyze_sentiment": false,
"partial_automated_agent_reply": false
}
}'
Response samples
{
"data": {
"result": "ok"
}
}
{
"errors": [
{
"code": "string",
"title": "string",
"detail": "string",
"source": {
"pointer": "string",
"parameter": "string"
},
"meta": {}
}
]
}