Change the Queue Music with Twilio Flex – Twilio Support

With Twilio Flex, you can personalize just about everything to your liking. One quick and easy update is to add custom hold music. If you already have a recording file prepared, you can make this change in minutes. This guide walks you through the full process for changing the hold music incoming callers hear.

Here are the steps to get you started:

Pick your Audio
Create a <Play> TwiML Verb Script
Publish your <Play> Script
Update your Flex "Voice IVR" Studio Flow
Test your Changes

Notice: Modifications published to a Flex "Voice IVR" Studio flow will immediately affect a Flex instance on this project. We recommend testing these changes on a trial account before sending them to production.

Pick your Audio

For hold music on a Twilio voice call, we use the <Play> TwiML verb. The <Play> verb supports the following file types:

mp3
wav
aiff
gsm
ulaw

Since this audio could be transmitted over standard copper-wire phone lines, a lossless or high-quality file is unnecessary. For our audio file formatting and quality suggestions, please see Best Practices for Audio Recordings.

Notice: The audio file must be accessible by Twilio's proxy servers to be broadcast over the call. Local files on your desktop are likely inaccessible via these methods, but your audio file may be uploaded to Twilio Assets for use here.

Create a <Play> TwiML Verb Script

The next step is to create a TwiML script to play and loop your audio file. This script will make use of the <Play> TwiML verb to broadcast your chosen audio file on the call. Here's a simple example of what this XML code might look like:

<Response>
  <Play loop="0">https://mysite.com/audio/holdMusic.mp3</Play>
</Response>

Setting the value of loop to 0 in this script will replay the audio file holdMusic.mp3 continuously until the call is answered. To make this code work for you, you'll need to update the URL listed here with the URL for your chosen audio file(s).

You could also add text-to-speech messages to your hold music with the <Say> TwiML verb. Here's an example of what this XML code might look like:

<Response>
  <Play>https://mysite.com/audio/holdMusic.mp3</Play>
  <Say>Your call is important to us. Please wait for the next available agent.</Say>
  <Play>https://mysite.com/audio/holdMusic.mp3</Play>
  <Say>We apologize for the wait, thank you for your continued patience.</Say>
  <Redirect>https://mysite.com/holdMusic.xml</Redirect>
</Response>

This script will play your hold music once (in this example, we removed the loop attribute), and then read the first message -

Your call is important to us. Please wait for the next available agent.

Your hold music will play again, and then when finished, the next message will be read -

We apologize for the wait, thank you for your continued patience.

The script will then use the <Redirect> TwiML verb to reload itself, and run through the script again. This process will continue until the call is answered

Here's how to make this code work for you:

Line 2 update with your chosen audio file's URL
Line 3 update with the desired first message
Line 4 update with your chosen audio file's URL
Line 5 update with the desired second message script
Line 6 update with the URL for this script, so it can reload itself

For full details, including code samples using our helper library SDKs, please see the following resources:

Publish your <Play> Script

Users can publish their script in any way that is convenient for them. The page will just need to be accessible from our proxy servers, and respond to our HTTP POST requests with the TwiML you created above.

For users without their own hosting, or those looking for a quick and easy XML script host, we offer our serverless TwiML Bins. These only require that you create a bin, and add your code. Here's how you would set one up to host your TwiML script:

Access the TwiML Bins page in Console.
Click Create New TwiML Bin, or the red Plus + sign button.
Add a Friendly Name and your TwiML XML code, and then click Create.
- Friendly Name: This is up to you - we recommend using something that gives an idea of what the TwiML Bin will do, like “Hold Music”.
- TwiML: For the field, you will use the <Play> verb script you created above - just copy and paste it here.

Once your TwiML Bin is saved, copy the URL - it should be in this format:

https://handler.twilio.com/twiml/EHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Update your Flex "Voice IVR" Studio Flow

With your script published, you'll now need to modify the Flex "Voice IVR" flow in Twilio Studio. This flow is automatically created when you set up your Flex project, all you need to do is add your <Play> script's URL. Here's how to update this:

Access the Studio page in Console.
Click the Voice IVR flow.
Once you see the flow, click the "Send to Flex" widget - this is named SendCallToAgent by default.
In the SEND TO FLEX "Config" tab on the right, scroll down and paste your <Play> script's URL in the HOLD MUSIC TWIML URL field. Click Save when finished.
Once the widget configuration has been saved, click Publish at the top of the screen to deploy your Studio flow's changes to production.

Test your Changes

Once the changes to your Voice IVR flow have been pushed to production, your new hold music script should be live. Go ahead and give a call to your Flex instance and test if this works as intended.