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:
- 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.
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 |
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"
}
}
- Telesign notifies you of the call status with a
dial_completed
Event. Check that the value of thedial.status
property in the Event payload isanswered
(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"
}
}
- Respond to that Event 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. |
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"
]
}
}
- 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"
}
}
- Hang up the call using the
hangup
Action or send further messages using theplay
orspeak
Actions.
Updated about 1 month ago
Check out these related pages: