Voice - Set up click-to-call

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page explains how to set up click-to-call using Telesign Voice.

Click-to-call refers to the user experience of selecting a call-to-action (such as a button) on a website that results in a phone call being made.

Requirements

You must have the following:

• Telesign authentication credentials: Your Customer ID and API key.
• Pool of virtual phone numbers: Purchase these voice-capable numbers from Telesign. Contact our Customer Support Team for details.
• Python 3
• Bottle: Run pip install bottle if you do not already have bottle installed.
• Webhook endpoint: A notification service you have set up for Telesign to post Event notifications to. See Voice - Receive Events with webhooks for instructions on how to set that up.
• SSL: Valid SSL certificate for the server hosting your webhook endpoint

📘

NOTE

Telesign calls have a maximum call duration of four hours. You can also set a shorter maximum for an individual call.

Implement click-to-call

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. In the user interface of your app, create a button for an end user to press.
2. When the rider presses the button, have the app send a request to to your system to dial the rider.
3. When your system receives the request, send a dial Action 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.'
external_id = 'An external ID you generated for this transaction.' # Optional parameter

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

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


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)

4. Telesign sends you a response indicating the Action was accepted and dials the rider.
5. Telesign sends a dial_completed Event after dialing the rider. You should have some logic to check for whether the data.status property in the Event payload is answered. Here is an example of this payload:

Dial completed Event from Telesign

{
  "event": "dial_completed",
  "reference_id": "DF596D7B0D1800164898350B4E71B05C",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "status": "answered"
  }
}

6. Send Telesign an Action to dial the driver. Telesign dials the driver and when the driver answers, the call is bridged between the rider and driver.
7. Either the rider or driver can terminate the call by hanging up. When this occurs, Telesign sends you two Events detailing the different legs of the calls.

Example response from Telesign - Rider

{
  "reference_id": "B5A0E700A214016489854B9D5D8D01EC",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "event": "call_completed",
  "data": {
    "from": "15555551212",
    "to": "15558675309",
    "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"
  }
}

Example response from Telesign - Driver

{
  "reference_id": "B5A0E700A214016489854B9D5D8D01EC",
  "external_id": "4142b474-d65d-4265-a5fa-a581b1fe6101",
  "event": "call_completed",
  "data": {
    "from": "15558675309",
    "to": "15555551212",
    "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"
  }
}