Voice - Play audio with multiple files

πŸ“˜

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to use Telesign Voice to play a message consisting of multiple audio files to your end user in an outbound call. You can also use a similar procedure to play multiple files in response to an inbound call.

Keep the reference page POST https://rest-ww.telesign.com/v2/voice open in another window while you work on these steps.

Before you begin

Make sure you have the following:

  • Telesign authentication credentials: Your Customer ID and API key.
  • Customer event URL: A notification service you have set up for Telesign to post Event notifications to. See Voice - Receive Events with webhooks for instructions on how to set that up.
  • Telesign phone number: A phone number you have purchased from Telesign to use as a caller ID. Purchase a number using the Telesign Phone Numbers API or ask our Customer Support Team to purchase a number for you. Make sure that the number is voice-capable (include the parameter and value voice_capable=true in your request to the Phone Numbers API). Refer to Phone Numbers API - Get Started for more details.

🚧

CAUTION

Use only codecs and standards for audio files supported by Voice. See Voice - Supported standards and codecs for more details.

How to stream audio with multiple files

To make a call and play streaming audio from multiple files:

  1. Create an outbound call using a request to the API with the dial Action. Include the following parameters in the request.
ParameterValueMeaningRequired?
methoddialSpecifies the Action.Yes
params.toA complete phone number.The phone number of the recipient of your call.Yes
params.caller_id_numberA complete phone number.The phone number to display to the recipient as the caller.Yes

API request

POST /v2/voice HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: rest-ww.telesign.com
{
    "method":"dial",
    "params":{
    "to":"15554441313",
    "caller_id_number":"15555551212"
  }
}
  1. Telesign notifies you of the call status with a dial_completed Event. Check that the value of the dial.status property in the Event payload is answered (highlighted below). If so, proceed to the next step.

dial_completed Event

POST /customer_event_endpoint HTTP/1.1
Host: your-customer-event-url.com
{
  "event": "dial_completed",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
    "to": "15554441313",
    "from": "15555551212",
    "status": "answered"
  }
}
  1. Respond to that Event with the play_multiple Action. Include the following parameters in the request.
ParameterValueMeaningRequired?
methodplay_multipleSpecifies the Action.Yes
params.urlsAn array of strings.The reference URLs for each audio file played to the recipient. They are played in the order they appear in this array.Yes
params.urls[n]An audio file reference URL.One of the audio files to play to the recipient.Yes, there should be at least one element in the array.

API Request

POST /v2/voice HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/json; charset=utf-8
Host: rest-ww.telesign.com
{
  "method": "play_multiple",
  "params": {
    "urls": [
      "https://url-pointing-to-audio-file.com/file1.wav",
      "https://url-pointing-to-audio-file.com/file2.wav",
      "https://url-pointing-to-audio-file.com/file3.wav"
    ]
  }
}
  1. If playing the audio files is successful, you get back the play_multiple_completed Event from Telesign.

play_multiple_completed Notification

POST /customer_event_endpoint HTTP/1.1
Host: your-customer-event-url.com
{
  "event": "play_multiple_completed",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
    "from": "15555551212",
    "to": "15554441313",
    "status": "play_successful"
  }
}
  1. Hang up the call using the hangup Action or send further messages using the play or speak Actions.

What’s Next

Check out these related pages: