NOTE:

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:

Common Use Cases
Requirements
How To Make the Call
- Step 1: Dial
  - Dial with Extension
- Step 2: React to Dial Response
Possible Call Flows

NOTE:

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.

NOTE:

Full technical details for the dial action can be found here.

Example:

Here is an example of making an outbound call using Python:

make_outbound_call.py

Python

import base64
import requests
import os

# Replace the defaults below with your TeleSign authentication credentials from https://teleportal.telesign.com
customer_id = os.getenv('CUSTOMER_ID', 'FFFFFFFF-EEEE-DDDD-1234-AB1234567890')
api_key = os.getenv('API_KEY', 'TE8sTgg45yusumoN6BYsBVkh+yRJ5czgsnCehZaOYldPJdmFh6NeX8kunZ2zU1YWaUw/0wV6xfw==')

# Set the REST API URL
url = "https://rest-ww.telesign.com/v2/voice"

# Set the Voice API inputs.
destination_number = os.getenv('PHONE_NUMBER', '15554441313') # The complete phone number you want to call, including country code, with no special characters or spaces.
caller_id_number = os.getenv('SENDER_ID', '15555551212') # The phone number you purchased from TeleSign.
send_dtmf = '8' # Digits to add into the call.

# Generate auth string.
auth_string = ":".join([customer_id, api_key]).encode()
auth_string = " ".join(["Basic", base64.b64encode(auth_string).decode("utf-8")])

# Create the request body.
payload = {
  "method": "dial",
  "params": {
    "to": destination_number,
    "caller_id_number": caller_id_number,
    "send_dtmf": send_dtmf
  }
}

# Create the request headers.
headers = {
  'Accept': "application/json",
  'Content-Type': "application/json",
  'Authorization': auth_string
}

# Make the request and capture the response.
response = requests.post(url, headers=headers, json=payload)

# Display the response for debugging purposes.
print(f"\nResponse:\n{response.status_code}\n")

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.

Figure 1

Outbound Call Flows

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.