play

Play file(s), ringtones, speech or silence.

Properties

objectRequired

An object that accepts the following properties. Accepts either a single URL or multiple URLs. See audio source below.

play.volume

numberDefaults to 0

Volume adjustment for playback, in decibels (dB). Applies to every sound in the list, including speech, ringtones, and audio files. Allowed values from -40 to 40.

play.loop

integerDefaults to 1

Number of times to play the full list of sounds. Set to 0 to repeat the list continuously. The list only repeats while at least one of its sounds can be played.

play.say_voice

string

Voice to use for say: text to speech. When not set, the say_voice variable is used if it is set; otherwise, a voice is selected based on the language and gender. Has no effect on audio files, ringtones, or silence.

play.say_language

stringDefaults to en-US

Language to use for say: text to speech. When not set, the say_language variable is used if it is set, otherwise en-US.

play.say_gender

stringDefaults to female

Gender to use for say: text to speech. When not set, the say_gender variable is used if it is set, otherwise female.

play.status_url

string

HTTP or HTTPS URL to deliver play status events, or a SWML variable that resolves to one. Learn more about status callbacks.

Audio source

The play object accepts one of the following properties to specify the audio source:

Single URL (url)

Multiple URLs (urls)

play.url

stringRequired

A single playable sound. Authentication can also be set in the url in the format of username:password@url.

Playable sounds

Audio file from a URL

To play an audio file from the web, simply list that audio’s URL. Specified audio file should be accessible with an HTTP GET request. HTTP and HTTPS URLs are supported. Authentication can also be set in the url in the format of username:password@url.

Example: https://cdn.signalwire.com/swml/audio.mp3

Ring

To play the standard ringtone of a certain country, use ring:[duration:]<ringtone>.

The total duration can be specified in seconds as an optional second parameter, and must be at least 1 second. When left unspecified, it will ring just once. The ringtone name must be specified. Most names are country identifiers, like us for United States or it for Italy. For the list of available ringtones, refer to the supported ringtones section below. For example:

ring:us - ring with the US ringtone once ring:3.2:uk - ring with the UK ringtone for 3.2 seconds

Speak using a TTS

To speak using a TTS, use say:<text to speak>. The text can’t be empty. When using say, you can optionally set say_voice, say_language and say_gender in the play or prompt properties. For the list of useable voices and languages, refer to the supported voices and languages section below.

Silence

To be silent for a certain duration, use silence:<duration>. The duration is in seconds, and must be at least 1 second.

Variables

Read by the method:

say_voice: (in) - Optional voice to use for text to speech.
say_language: (in) - Optional language to use for text to speech.
say_gender: (in) - Optional gender to use for text to speech.

The say_voice, say_language, and say_gender properties take precedence over these variables when set.

Set by the method:

play_result: (out) - success if the play request succeeded, failed otherwise. This reflects the result of the play request, not whether every sound was heard. Use status callbacks to follow playback state.

Possible values for voice, language, and ringtone

Supported voices and languages

To learn more about the supported voices and languages, please visit the Supported Voices and Languages Documentation.

Supported ring tones

Parameter
`urls.ring`	Available values are the following two-letter country identifiers: at, au, be, bg, br, ca, ch, cl, cn, cy, cz, de, dk, dz, ee, eg, es, fi, fr, gr, hu, il, in, it, jp, ko, lt, mx, my, nl, no, nz, ph, pk, pl, pt, ro, rs, ru, sa, se, sg, th, tr, tw, uk, us, ve, za. The named tone bong is also available.

StatusCallbacks

Status callbacks are advisory

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

A POST request will be sent to status_url with a JSON payload like the following for each playback state change:

event_type

string

The type of event. calling.call.play for playback state notifications.

event_channel

string

The channel for the event, includes the SWML session ID.

timestamp

number

Unix timestamp (float) when the event was generated.

project_id

string

The project ID associated with the call.

space_id

string

The Space ID associated with the call.

params

object

An object containing playback-specific parameters.

params.call_id

string

The call ID.

params.node_id

string

The node handling the call.

params.control_id

string

The control ID for this play operation.

params.state

string

The current playback state. Valid values: playing, paused, finished, error.

Raw JSON example

{
  "event_type": "calling.call.play",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "state": "finished"
  }
}

Error notifications

When the play request itself fails, status_url can also receive a separate event with event_type set to calling.error instead of a playback state. Its params.error object carries the error code and message. Not every failure produces this event.

Examples

Playing a single URL

version: 1.0.0
sections:
  main:
    - play:
        url: 'https://cdn.signalwire.com/swml/audio.mp3'

Playing multiple URLs

version: 1.0.0
sections:
  main:
    - play:
        urls:
          - 'https://cdn.signalwire.com/swml/audio.mp3'
          - 'say: this is something to say'
          - 'silence: 3.0'
          - 'ring:10.0:us'

Playing multiple URLs with volume adjusted

version: 1.0.0
sections:
  main:
    - play:
        volume: 20
        urls:
          - 'https://cdn.signalwire.com/swml/audio.mp3'
          - 'say: this is something to say'
          - 'silence: 3.0'
          - 'ring:10.0:us'

Specifying a voice to use for speaking

Globally

version: 1.0.0
sections:
  main:
    - set:
        say_voice: gcloud.en-US-Neural2-A
    - play:
        url: 'say:Hi, do I sound different?'
    - play:
        url: 'say:I don''t, do I?'

For just one instance

version: 1.0.0
sections:
  main:
    - play:
        url: 'say:Hi, do I sound different?'
        say_voice: gcloud.en-US-Neural2-A
    - play:
        url: 'say:I was down with the flu'