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" : &lt;your base64 encoded mp3 file&gt;
  \}
\}

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

application/json

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.

stream_bidirectional_mode Stream Bidirectional Mode (string)

Possible values: [mp3, rtp]

Default value: mp3

Configures method of bidirectional streaming (mp3, rtp).

stream_bidirectional_codec Stream Bidirectional Codec (string)

Possible values: [PCMU, PCMA, G722]

Default value: PCMU

Indicates codec for bidirectional streaming RTP payloads. Used only with stream_bidirectional_mode=rtp. Case sensitive.

enable_dialogflow boolean

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

dialogflow_config

object

analyze_sentiment boolean

Enable sentiment analysis from Dialogflow.

partial_automated_agent_reply boolean

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.

application/json

Schema

data

object

result string

{
  "data": {
    "result": "ok"
  }
}

default: Unexpected error

application/json

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

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Callbacks

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": {}
    }
  ]
}

Streaming start

Request ​

Path Parameters

Body

Responses ​

Callbacks ​

Request

Responses

Callbacks