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.

Set up Click-to-Call with TeleSign’s Voice API

Click-to-call refers to the user experience of pushing a button on a website (or a file or database entry or similar) and then a phone call is made, connecting you to someone.

Setting up click-to-call with the TeleSign Voice API is similar to setting up anonymous 2-way voice. The main difference is click-to-call begins with clicking or pressing of a button. This then triggers the dialing and connecting of that person’s number to whoever they were trying to call by pressing the button. This page walks you through how to do a basic call.

Contents of this page:

NOTE:

TeleSign calls have a maximum call duration of four hours.

Requirements

You must have the following:

  • Pool of virtual phone numbers from TeleSign (see the Get Started with the Phone Numbers API page to buy numbers).
  • Customer ID and API key
  • Valid SSL certificate for the server hosting your endpoint (callback URL)
  • Python 3
  • Run pip install bottle if you do not already have bottle installed
  • 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 choice about how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:

Implement Click-to-Call

This use case is triggered by an end user pressing or clicking a button in a mobile or web app. For the purpose of this walkthrough, imagine the scenario where a rider wants to contact their driver. The rider presses a button, and they are connected to their driver.

Here is a diagram showing the flow:

To set up the call, you do the following:

  1. Create logic on your app associated with a button for an end user to press.
  2. When the rider presses the button, a request to dial the rider is sent to your server.
  3. Implement logic on your server that receives the request and issues a dial command to TeleSign.
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 = 'The complete phone number you want to call, including country code, with no special characters or spaces.'
caller_id_number = '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)
  1. TeleSign sends you a response indicating the dial was accepted and dials the rider.
  2. TeleSign sends dial_completed after dialing the rider. You should have some logic to check for whether the status is answered. Here is an example of the JSON payload you receive from TeleSign that you will want to check the status for:
Answered Event from TeleSign
{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "answered"
  }
}
  1. Next, your server sends TeleSign a request to dial the driver. The code for this would be the same as the Outbound Call with Python example. TeleSign dials the driver and when the driver answers, the call is bridged between the rider and driver.
  2. Either the rider or driver can terminate the call by hanging up. TeleSign receives this information, and sends you two responses detailing the different legs of the calls. Sample responses might look like this:
Response from TeleSign - Rider
{
  "reference_id": "B5A0E700A214016489854B9D5D8D01EC",
  "event": "call_completed",
  "data": {
    "from": "15555551212 - example only",
    "to": "15558675309 - example only",
    "direction": "outbound",
    "created_on_utc": "2019-01-10T21:52:01.963406",
    "answered_on_utc": "2019-01-10T21:53:17.243435",
    "ended_on_utc": "2019-01-10T21:54:16.103446",
    "duration": 20,
    "status": "hangup"
  }
}
Response from TeleSign - Driver
{
  "reference_id": "B5A0E700A214016489854B9D5D8D01EC",
  "event": "call_completed",
  "data": {
    "from": "15558675309 - example only",
    "to": "15555551212 - example only",
    "direction": "outbound",
    "created_on_utc": "2019-01-10T21:52:35.963491",
    "answered_on_utc": "2019-01-10T21:53:17.243435",
    "ended_on_utc": "2019-01-10T21:54:16.103446",
    "duration": 59,
    "status": "hangup"
  }
}

Next Steps

This section offers suggestions for next steps to take.