Sign in
Call Commands

Play audio URL

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:

  • call.playback.started
  • call.playback.ended
post/calls/{call_control_id}/actions/playback_start

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

audio_urlstring

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_namestring

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.

overlayboolean

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.

stopstring

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_legsstring

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

cache_audioboolean

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

audio_type'mp3' | 'wav'

Specifies the type of audio provided in audio_url or playback_content.

playback_contentstring

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_statestring

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

command_idstring

Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

Example request

{
  "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

Successful response upon making a call control command.

Example response

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

Changes

Changed in 2 of the 99 revisions of this API.7

  • 1571b0380bd73See the full diff
    • ▲

      the response's body type changed from object to no type for status

      response-body-type-changed

    • ▲

      the / response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to integer for status

      response-property-type-changed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e5379944See the full diff
    • ▲

      the response's body type changed from no type to object for status

      response-body-type-changed

    • ▲

      the / response's property type changed from no type to object for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from integer to int32 for status

      response-property-type-changed

    • ▲

      the /// response's property format changed from json-pointer to no format for status

      response-property-type-changed

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 99 revisions, 1 has no diff computed.