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 voice-capable phone number you have purchased from Telesign to use as a caller ID. Contact our Customer Support Team for 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. You can also include other optional parameters.

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",
	  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101"
	}
}

2. 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",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "data": {
    "to": "15554441313",
    "from": "15555551212",
    "status": "answered"
  }
}

3. Respond to that Event with the play_multiple Action. Include the following parameters in the request.

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"
    ]
  }
}

4. 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"
  }
}

5. Hang up the call using the hangup Action or send further messages using the play or speak Actions.