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 consecutively issued, the audio files will be placed in a queue awaiting playback.

Notes:

  • when 'overlay' is enabled, 'loop' is limited to 1, and '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:

  • Playback started
  • Playback ended

Request ​

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

    audio_url stringrequired

    The URL of the file to be played back on the call. The URL can point to either a WAV or MP3 file.

    loop string

    Default value: 1

    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.

    overlay boolean

    Default value: false

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

    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 commands with the same "command_id".

Responses ​

200: Successful response

Schema

    result stringrequired

422: Error response

Schema

    code stringrequired
    title stringrequired
    detail stringrequired

Request samples

curl -L 'https://api.telnyx.com/calls/:call_control_id/actions/playback_start' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-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

{
  "result": "ok"
}