NOTE:

If you are looking for the legacy Voice API at endpoint https://rest-ww.telesign.com/v1/voice go to the Voice (Legacy) page.

Get Started with TeleSign’s Voice API

The TeleSign Voice API allows you to:

  • Make, receive and control calls
  • Collect digits (DTMF tones)
  • Connect two parties
  • Deliver secure, voice-based one-time passcodes (OTPs)
  • Stream audio
  • Use text-to-speech with broad language support
  • Anonymize phone calls
  • Build inbound and outbound Interactive Voice Response (IVR)
  • Perform cold transfers

Voice is discussed in the following sections:

General Information

All requests submitted for this API:

  • Can be authenticated with basic authentication.
  • Use https://rest.telesign.com/v2/voice as the base endpoint.
  • Are formatted using JSON-RPC.
  • Accept only UTF-8 encoded unicode characters as inputs.

All information TeleSign submits to you is submitted to a customer event URL that you provide to TeleSign. Speak with your Technical Account Manager (TAM) to set this up. You can learn more on the Set up the Customer Event URL section of the Voice API Reference page.

Make an Outbound Call

If you want to make an outbound call to make a phone call, or send alerts, marketing messages, notifications, or one-time pass codes (OTPs) refer to the Make an Outbound Call page.

Receive an Inbound Call

Learn how to receive inbound calls and handle them on the Receive an Inbound Call page.

Play Message and Collect Digits

This page shows you how to make a call, play or speak a message, and collect digits from the end user who receives the call. See the Play Message and Collect Digits page for more information.

Set up Anonymous 2-Way Voice

If you want to get started connecting two users into a phone call where the phone number for each user is masked, see the Set up Anonymous 2-Way Voice page.

Set up Click-to-Call

Click-to-call is when a user kicks off a request for a call by pressing a button in an app or on a website. If you want to learn about setting up click-to-call, check out the Set up Click-to-Call page.

Perform a Cold Transfer

A cold transfer is when you transfer a caller from one agent or automated message to another agent or automated message without any notice or introduction. You can learn about creating a cold transfer on the Perform a Cold Transfer page.

Buy a Phone Number (Sender ID)

You can buy phone numbers to use with the Voice API by using the Phone Numbers API. Read more on the Phone Numbers API page.

Voice API Examples

This section provides examples from the documentation.

Event Examples

These are example events your server will receive throughout the duration of a call.

POST Request for incoming_call
{
  "event": "incoming_call",
  "reference_id": "534e1848-235f-482d-983d-e3e11a04f58a",
  "data": {
        "to": "+15555551212",
        "from": "+15558675309",
      }
}
Answered Event for dial
{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "answered"
  }
}
Play Completed Event
{
  "event": "play_completed",
  "reference_id": "Q772E290BG4C01648984EAD7EA1D0021",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "playback_successful",
    "collected_digits": "923"
  }
}
Speak Completed Event
{
  "event": "speak_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "speak_successful",
    "collected_digits": "923"
  }
}
Call Completed Example
{
  "event": "call_completed",
  "reference_id": "B596D7B0D1800164898350B4E71B005C",
  "data": {
    "to": "15558675309",
    "from": "15555551212",
    "direction": "inbound",
    "created_on_utc": "2018-08-07T20:33:38.003718",
    "answered_on_utc": "2018-08-07T20:33:40.003718",
    "ended_on_utc": "2018-08-07T20:33:44.003718",
    "status": "hangup",
    "duration": 4
  }
}

Action Examples

Here are examples of JSON responses TeleSign expects when we send you an event. This is your command.

Dial
[
  {
    "method": "dial",
    "params": {
      "to": "+15555551212",
      "caller_id_number": "+15554441313"
    }
  }
]
Play Action
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com"
  }
}
Play Action with Collect Digits Feature
{
  "method": "play",
  "params": {
    "url": "https://url-pointing-to-audio-file.com",
    "collect_digits": {
      "max": 5,
    }
  }
}

Next Steps

This section offers some suggestions for next steps to take.