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

Properties

play

objectRequired

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

play.status_url

string

HTTP or HTTPS URL to deliver play status events. 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:]<country code>.

The total duration can be specified in seconds as an optional second parameter. When left unspecified, it will ring just once. The country code must be specified. It has values like us for United States, it for Italy. For the list of available country codes, 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>. 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.

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.

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 ISO 3166-1 alpha-2 country codes: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.

StatusCallbacks

A POST request will be sent to status_url with a JSON payload like the following:

event_type

string

The type of event. Always calling.call.play for this method.

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"

  }

}

---

Examples

Playing a single URL

YAMLJSON

version: 1.0.0

sections:

  main:

    - play:

        url: 'https://cdn.signalwire.com/swml/audio.mp3'

Playing multiple URLs

YAMLJSON

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

YAMLJSON

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

YAMLJSON

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

YAMLJSON

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'