Skip to main content

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:

  • 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": "PCMU",
"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

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

Start streaming media request

    stream_url string

    The destination WebSocket address where the stream is going to be delivered.

    stream_track string

    Possible values: [inbound_track, outbound_track, both_tracks]

    Default value: inbound_track

    Specifies which track should be streamed.

    enable_dialogflow boolean

    Default value: false

    Enables Dialogflow for the current call. The default value is false.

    dialogflow_config

    object

    analyze_sentiment boolean

    Default value: false

    Enable sentiment analysis from Dialogflow.

    partial_automated_agent_reply boolean

    Default value: false

    Enable partial automated agent reply from Dialogflow.

    client_state string

    Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

    command_id 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.

Schema

    data

    object

    result string

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

  • code integerrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object
  • ]

Callbacks

Loading...