Skip to main content
Get startedGuidesTechnical Reference

play

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

play
objectrequired

An object that accepts the play parameters.

play Parameters​

play.url
stringrequired

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

play.auto_answer
boolean
Default: true

If true, the call will automatically answer as the sound is playing. If false, you will start playing the audio during early media, additionally, you can instruct to answer the call with the answer method.

play.volume
number
Default: 0

Volume gain to apply to played URLs. Allowed values from -40.0 to 40.0.

play.say_voice
string
Default: Polly.Salli

Voice to use with say: for text to speech.

play.say_language
string
Default: en-US

Language to use with say: for text to speech.

play.say_gender
string
Default: female

Gender to use with say: for text to speech.

play.status_url
string

HTTP or HTTPS URL to deliver play status events.

Playable sounds​

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

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

  3. 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 params. For the list of useable voices and languages, refer to the supported voices and languages section below.

  4. 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.ringAvailable 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.

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'