Want to provide feedback?

Write to docs@telesign.com.

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by navigating to our Voice API signup page.

Make an Outbound Call with TeleSign’s Voice API

You can use the TeleSign Voice API to place outbound calls. Some common uses for the calls are:

Alerts, reminders, and notifications
Marketing messages
One-time passcodes (OTPs) for verification
Setting up outbound IVR

This page explains how to make an outbound call using TeleSign’s Voice API.

NOTE:

TeleSign calls have a maximum call duration of four hours.

Requirements

You must have the following:

TeleSign credentials - your customer ID and API key
TeleSign phone number - you must purchase a TeleSign phone number to use as a callerID. You can do this using the Phone Numbers API. Refer to the Get Started with the Phone Numbers API page.
For details about supported standards and codecs, see Supported Standards and Codecs*
If you plan to use events posted by TeleSign as a trigger for what action to take next with a call, you need a customer event URL on your server 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.
If you want to make choices about how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:
- Customer Action API Reference
- Call Query API Reference

Implement an Outbound Call

You set up an outbound call by using the dial action. You add a destination phone number for to and your callerID (the phone number you bought from TeleSign) goes in the caller_id_number slot.

Here is a Python code sample showing how you would request an outbound call:

Outbound Call with Python

from base64 import b64encode

import requests

customer_id = 'Your customer ID goes here.'
api_key = 'Your API key goes here.'

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 goes here.'

url = "https://rest-ww.telesign.com/v2/voice"

payload = {
            "jsonrpc": "2.0",
            "method": "dial",
            "params": {
                "to": destination_number,
                "caller_id_number": caller_id_number
            }
    }


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)

Depending on what TeleSign tells you about the status of the dial in the response event (for example that the person hung up or answered the call), you may be able to request another action at this point. If the person answers the call, for example, you might:

Send a play action to play a recorded message for the end user.
Send a speak action to use text-to-speech (TTS) to deliver a custom message in the language of your choice.
Send a send_dtmf action to enter DTMF digits programmatically into the call.

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.

Figure 1

Outbound Call Flows

Workflow Diagram, Option A

This option in the diagram shows you what happens if a 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.

Workflow Diagram, Option B

This option in the diagram shows you what happens if 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 hangup.
( B ) TeleSign sends you notification that the call is completed.

Workflow Diagram, Option C

This option in the diagram shows you what happens if 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

This section offers some suggestions for next steps to take.

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 Anonymous 2-way Voice - Learn how to set up a phone call where both speakers have their phone numbers hidden from one another.