TwiML™ Voice: <Play>

The <Play> verb plays an audio file back to the caller. Twilio retrieves the file from a URL that you provide.

Verb Attributes

The <Play> verb supports the following attributes that modify its behavior:

Attribute Name	Allowed Values	Default Value
loop	integer >= 0	1
digits	integer >= 0, w	no default digits for Play

loop

The 'loop' attribute specifies how many times the audio file is played. The default behavior is to play the audio once. Specifying '0' will cause the <Play> verb to loop until the call is hung up.

Use it like so:

Using Play with loop

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play({
    loop: 10
}, 'https://api.twilio.com/cowbell.mp3');

console.log(response.toString());

using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play(new Uri("https://api.twilio.com/cowbell.mp3"), loop: 10);

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play('https://api.twilio.com/cowbell.mp3', ['loop' => 10]);

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(loop: 10, url: 'https://api.twilio.com/cowbell.mp3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('https://api.twilio.com/cowbell.mp3', loop=10)

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("https://api.twilio.com/cowbell.mp3")
            .loop(10).build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play loop="10">https://api.twilio.com/cowbell.mp3</Play>
</Response>

Using Play with loop

digits

The ‘digits’ attribute lets you play DTMF tones during a call.

For example, if you need to test an IVR system, you can use this feature to simulate digits being pressed to navigate through the menu options.

Include w to introduce a 0.5s pause between DTMF tones. For example, 1w2 will tell Twilio to pause 0.5s before playing DTMF tone 2. To include 1s of pause, simply add ww.

If you are dialing a phone number and need to play DTMF tones to enter the extension, you should use the sendDigits attribute for <Number>.

Nouns

The "noun" of a TwiML verb is the stuff nested within the verb that's not a verb itself; it's the stuff the verb acts upon. These are the nouns for <Play>:

Noun	Description
plain text	The URL of an audio file that Twilio will retrieve and play to the caller.

Twilio supports the following audio MIME types for audio files retrieved by the <Play> verb:

MIME type	Description
audio/mpeg	mpeg layer 3 audio
audio/wav	wav format audio
audio/wave	wav format audio
audio/x-wav	wav format audio
audio/aiff	audio interchange file format
audio/x-aifc	audio interchange file format
audio/x-aiff	audio interchange file format
audio/x-gsm	GSM audio format
audio/gsm	GSM audio format
audio/ulaw	μ-law audio format

Nesting Rules

You can't nest any verbs within <Play>. You can nest <Play> within a <Gather> verb, with one major exception - you can't play "digits" within a <Gather>.

Examples

Example 1: Simple Play

This TwiML document tells Twilio to download the cowbell.mp3 file and play the audio to the caller.

Simple Play

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play('https://api.twilio.com/cowbell.mp3');

console.log(response.toString());

using Twilio.TwiML;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play(new Uri("https://api.twilio.com/cowbell.mp3"));

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play('https://api.twilio.com/cowbell.mp3');

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(url: 'https://api.twilio.com/cowbell.mp3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('https://api.twilio.com/cowbell.mp3')

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("https://api.twilio.com/cowbell.mp3")
            .build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play>https://api.twilio.com/cowbell.mp3</Play>
</Response>

Simple Play

We are going to test our IVR menu to make sure users can navigate properly. We know that the length of the initial greeting and the menu number we need to enter. We can add a few leading 'w' characters to add a pause. Each 'w' character tells Twilio to wait 0.5 seconds instead of playing a digit. This lets you adjust the timing of when the digits begin playing to suit the phone system you are dialing.

Using digits

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play({
    digits: 'wwww3'
});

console.log(response.toString());

using Twilio.TwiML;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play("", digits: "wwww3");

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play(['digits' => 'wwww3']);

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(digits: 'wwww3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('', digits='wwww3')

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("").digits("wwww3").build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play digits="wwww3"></Play>
</Response>

Using digits

Hints and Advanced Uses

Twilio will attempt to cache the audio file the first time it is played. This means the first attempt may be slow to play due to the time spent downloading the file from your remote server. Twilio may play a processing sound while the file is being downloaded.
Twilio will cache files when HTTP headers allow it (via ETag and Last-Modified headers). Responding with Cache-Control: no-cache will ensure Twilio always checks if the file has changed, allowing your your web server to respond with a new version or with a 304 Not Modified to instruct Twilio to use its cached version.
Audio played over the telephone network is transcoded to a format the telephone network understands. Regardless of the quality of the file you provide us, we will transcode so it plays correctly. This may result in lower quality because the telephone number does not support high bitrate audio.
High bitrate, lossy encoded files, such as 128kbps mp3 files, will take longer to transcode and potentially sound worse than files that are in lossless 8kbps formats. This is due to the inevitable degradation that occurs when converting from lossy compressed formats and the processing involved in converting from higher bit rates to low bit rates.
<Play>ing a file that is longer than 40 minutes can result in a dropped call. If you need to <Play> a file longer than 40 minutes, consider splitting it up into smaller chunks.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Using Play with loop
Simple Play
Using digits

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play({
    loop: 10
}, 'https://api.twilio.com/cowbell.mp3');

console.log(response.toString());

using Twilio.TwiML;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play(new Uri("https://api.twilio.com/cowbell.mp3"), loop: 10);

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play('https://api.twilio.com/cowbell.mp3', ['loop' => 10]);

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(loop: 10, url: 'https://api.twilio.com/cowbell.mp3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('https://api.twilio.com/cowbell.mp3', loop=10)

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("https://api.twilio.com/cowbell.mp3")
            .loop(10).build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play loop="10">https://api.twilio.com/cowbell.mp3</Play>
</Response>

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play('https://api.twilio.com/cowbell.mp3');

console.log(response.toString());

using Twilio.TwiML;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play(new Uri("https://api.twilio.com/cowbell.mp3"));

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play('https://api.twilio.com/cowbell.mp3');

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(url: 'https://api.twilio.com/cowbell.mp3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('https://api.twilio.com/cowbell.mp3')

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("https://api.twilio.com/cowbell.mp3")
            .build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play>https://api.twilio.com/cowbell.mp3</Play>
</Response>

SDK Version:

Format:

TwiML

const VoiceResponse = require('twilio').twiml.VoiceResponse;

const response = new VoiceResponse();
response.play({
    digits: 'wwww3'
});

console.log(response.toString());

using Twilio.TwiML;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        response.Play("", digits: "wwww3");

        Console.WriteLine(response.ToString());;
    }
}

<?php
require_once './vendor/autoload.php';
use Twilio\Twiml;

$response = new Twiml();
$response->play(['digits' => 'wwww3']);

echo $response;

require 'twilio-ruby'

response = Twilio::TwiML::VoiceResponse.new
response.play(digits: 'wwww3')

puts response

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('', digits='wwww3')

print(response)

import com.twilio.twiml.voice.Play;
import com.twilio.twiml.VoiceResponse;
import com.twilio.twiml.TwiMLException;


public class Example {
    public static void main(String[] args) {
        Play play = new Play.Builder("").digits("wwww3").build();
        VoiceResponse response = new VoiceResponse.Builder().play(play).build();

        try {
            System.out.println(response.toXml());
        } catch (TwiMLException e) {
            e.printStackTrace();
        }
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Play digits="wwww3"></Play>
</Response>

TwiML™ Voice: <Play>

Thank you for your feedback!

Using Play with loop

Simple Play

Using digits

Need some help?