NOTE:

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

Stream 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 Voice API Reference open in another window while you work on these steps.

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.

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.
Parameter Value Meaning Required?
method dial Specifies the action. Yes
params.to A complete phone number. The phone number of the recipient of your call. Yes
params.caller_id_number A complete phone number. The phone number to display to the recipient as the caller. Yes
Voice API Request
HTTPS
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
HTTPS
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.
Parameter Value Meaning Required?
method play_multiple Specifies the action. Yes
params.urls An 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
JSON
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
HTTPS
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.

Next Steps

Check out these related pages: