Skip to main content

Play audio URL

POST 
/calls/:call_control_id/actions/playback_start

Play an audio file on the call. If multiple play audio commands are issued consecutively, the audio files will be placed in a queue awaiting playback.

Notes:

  • When overlay is enabled, target_legs is limited to self.
  • A customer cannot Play Audio with overlay=true unless there is a Play Audio with overlay=false actively playing.

Expected Webhooks (see callback schema below):

  • call.playback.started
  • call.playback.ended

Request ​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

Play audio URL request

    audio_url string

    The URL of a file to be played back on the call. The URL can point to either a WAV or MP3 file. media_name and audio_url cannot be used together in one request.

    media_name string

    The media_name of a file to be played back on the call. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

    loop

    object

    The number of times the audio file should be played. If supplied, the value must be an integer between 1 and 100, or the special string infinity for an endless loop.

    oneOf

    string

    overlay boolean

    When enabled, audio will be mixed on top of any other audio that is actively being played back. Note that overlay: true will only work if there is another audio file already being played on the call.

    stop string

    When specified, it stops the current audio being played. Specify current to stop the current audio being played, and to play the next file in the queue. Specify all to stop the current audio file being played and to also clear all audio files from the queue.

    target_legs string

    Default value: self

    Specifies the leg or legs on which audio will be played. If supplied, the value must be either self, opposite or both.

    cache_audio boolean

    Default value: true

    Caches the audio file. Useful when playing the same audio file multiple times during the call.

    audio_type string

    Possible values: [mp3, wav]

    Default value: mp3

    Specifies the type of audio provided in audio_url or playback_content.

    playback_content string

    Allows a user to provide base64 encoded mp3 or wav. Note: when using this parameter, media_url and media_name in the playback_started and playback_ended webhooks will be empty

    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 ​

Request samples

curl -L 'https://api.telnyx.com/v2/calls/:call_control_id/actions/playback_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
  "audio_url": "http://www.example.com/sounds/greeting.wav",
  "loop": "infinity",
  "overlay": true,
  "stop": "current",
  "target_legs": "self",
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901"
}'

Response samples

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