Voice API - Play Audio with Multiple Files

This page walks you step-by-step through how to use the Voice API 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 /v2/voice open in another window while you work on these steps.

📘

NOTE

If you are interested in trying TeleSign's Voice API, sign up by contacting our experts.

Before You Begin

Make sure you have the following:

  • Authentication Credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
  • Customer Event URL: A notification service you have set up for TeleSign to post event information to. For more details, refer to the Set up the Customer Event URL section on the Voice API Reference page.
  • 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 (see Get Started with the 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 Get Started with the Phone Numbers API for more details.

🚧

CAUTION

Use only codecs and standards for audio files supported by the Voice API. See 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 Voice 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

Voice 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 Notification

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. Send a request to the Voice API 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.

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

Did this page help you?