Skip to main content

custom-hold-music

This feature allows customization of the hold music used when an agent places a call or conference participant on hold, including when initiating a transfer.

setup and dependencies

Hold experience TwiML

To use this feature, you will need to provide the URL of TwiML to execute during hold. This TwiML can be hosted anywhere, such as TwiML Bins, Twilio Functions & Assets, or on your own infrastructure. Here is example TwiML that will loop an audio file continuously:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Play loop="0">http://com.twilio.music.soft-rock.s3.amazonaws.com/_ghost_-_promo_2_sample_pack.mp3</Play>
</Response>

Here is how you can create and use a TwiML Bin for this functionality:

  1. Open Twilio Console and navigate to TwiML Bins > My TwiML Bins
  2. Create a new TwiML Bin and give it a name
  3. Paste in the above TwiML, or write your own
  4. Save the TwiML Bin
  5. Copy the URL that is provided after saving.

Configuring the feature

Within your ui_attributes file, you must set two settings for the custom-hold-music feature:

  • enabled - set this to true to enable the feature
  • url - set this to the URL of the TwiML containing the desired hold experience

Note When using TwiML Bins, you must append your account SID to the URL, like so: https://handler.twilio.com/twiml/EHxxxxx?AccountSid=ACxxxxx

Warning While you may provide a direct URL to an audio file rather than using TwiML, it will play only once and not loop.

Once your updated flex-config is deployed, the feature is enabled and ready to use.

how does it work?

This feature adds listeners to the beforeHoldCall, beforeHoldParticipant, and beforeTransferTask actions to set the hold music URL. The TwiML at that URL will be played while the call is held.