If you are interested in trying TeleSign’s Voice API, sign up by contacting our experts.
Make an Outbound Call with the TeleSign Voice API
This page explains how to use the TeleSign Voice API to make outbound calls.
Contents of this page:
TeleSign calls have a maximum call duration of four hours.
Common Use Cases
Some common use cases for these calls are:
- Alerts, reminders, and notifications
- Marketing messages
- One-time passcodes (OTPs) for verification
- Setting up outbound IVR
Requirements
You must have the following:
- TeleSign credentials: Your Customer ID and API key.
- 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. - 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.
Be sure also to only use supported standards and codecs (see Supported Standards and Codecs).
How To Make the Call
Follow these steps to make an outbound call.
Step 1: Dial
Send the dial
action to the Voice API.
Include these required parameters with your action:
to
– Include the destination phone number here.caller_id_number
– Include a TeleSign phone number here
Dial with Extension
Include this optional parameter if desired:
send_dtmf
– Include digits to add into the call after it connects. Common use cases for this feature are to enter an extension or a conference code.
Full technical details for the dial
action can be found here.
Example:
Here is an example of making an outbound call using Python:
from base64
import b64encode
import requests
customer_id = '12345678-9ABC-DEF0-1234-56789ABCDEF0' # Your Customer ID.
api_key = 'n135MeEOwaWnkWVFWG0DFULtRLY=' # Your API key.
destination_number = '15554441313' # The complete phone number you want to call, including country code, with no special characters or spaces.
caller_id_number = '15555551212' # The phone number you purchased from TeleSign.
send_dtmf - '8' # Digits to add into the call.
url = "https://rest-ww.telesign.com/v2/voice"
payload = {
"jsonrpc": "2.0",
"method": "dial",
"params": {
"to": destination_number,
"caller_id_number": caller_id_number,
"send_dtmf": send_dtmf
}
}
headers = {
'Accept': "application/json",
'Content-Type': "application/json",
'Authorization': "Basic {}".format(b64encode(customer_id + ":" + api_key).decode('utf-8')),
}
response = requests.request("POST", url, data = json.dumps(payload), headers = headers)
print(response.text)
Step 2: React to Dial Response
Depending on what TeleSign tells you about the status of the dial in the response event (for example that the end user hung up or answered the call), you might be able to make another action at this point. For example, if the call is answered you can send one of the following actions:
play
– Play a recorded message for the end user.speak
– Use text-to-speech (TTS) to deliver a custom message in the language of your choice.send_dtmf
– Enter DTMF digits programmatically into the call.
Possible Call Flows
Figure 1 shows you some of the ways an outbound call could go. The arrows with dotted lines represent asynchronous responses. The labeling of steps 6-9 with a letter (such as 6A, 6B, 6C) show you three different ways an outbound call could complete.
Call Flow A: Call Accepted
The call is accepted and you choose to play a recorded message or send a text-to-speech message in response.
- You send the
dial
command to TeleSign. - TeleSign calls the
destination_number
parameter. - TeleSign notifes you that your dial request was accepted.
- The end user’s device notifies TeleSign that the call was answered.
- TeleSign notifies you that the dial completed and the call was answered.
- ( A ) You send a request asking that TeleSign play a message or use text-to-speech to speak a message (this may include requesting that digits be collected).
- ( A ) TeleSign plays or speaks your message for the end user.
- ( A ) The end user’s device notifies TeleSign that the message finished playing.
- ( A ) TeleSign notifies you that the play message or play recording task action completed.
Call Flow B: You Terminate
You choose to terminate the call without playing or speaking a message.
- You send the dial command to TeleSign.
- TeleSign calls the number you requested a call to.
- TeleSign notifes you that the dial request was accepted.
- The end user’s device notifies TeleSign that the call was answered.
- TeleSign notifies you that the dial completed and the call was answered.
- ( B ) You request that TeleSign hang up.
- ( B ) TeleSign sends you notification that the call is completed.
Call Flow C: End User Terminates
The end user hangs up the call before the audio finishes playing.
- You send the dial command to TeleSign.
- TeleSign calls the number you requested a call to.
- TeleSign notifes you that the dial request was accepted.
- The end user’s device notifies TeleSign that the call was answered.
- TeleSign notifies you that the dial completed and the call was answered.
- ( C ) You send a request asking that TeleSign play a message or use text-to-speech to speak a message (this may include requesting that digits be collected)
- ( C ) TeleSign plays or speaks your message for the end user.
- ( C ) The end user hangs up during the call.
- ( C ) You receive notification that the call completed.
Next Steps
Check out these related pages:
- Voice API Reference - See further technical details for the API, including definitions for each parameter.
- Get Started with the Phone Numbers API - If you need to buy a phone number to use as a CallerID get started here.
- Set Up a Call with Number Masking - Learn how to set up a phone call where both speakers have their phone numbers hidden from one another.