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 Anonymous 2-way Voice with TeleSign’s Voice API

This page explains how to make an anonymous 2-way call using TeleSign’s Voice API.

Each end user’s real phone number will be hidden from the other, instead they will each see a masking ID.

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 Get Started with the Phone Numbers API 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 Set up the Customer Event URL on the Voice API Reference page.
  • If you want to choose how to handle a call without needing an event posted by TeleSign as a trigger, you will need to review:
Note

For further technical details, including definitions for each parameter, see Voice API Reference.

Implement Anonymous 2-way Voice

This use case must be triggered by an inbound call. For the purpose of the example, you receive an inbound call event containing the following information:

  • The number calling (from parameter)
  • The number the end user wants to call (to parameter)

You must create logic that determines whether the incoming call may be connected to the number being requested. If the answer is yes, you then set up an outbound call. The outbound call contains the number that the end user wanted to call, and the callerID you want to use. The request will bridge the call from the end user to the phone number they wanted to call, masked with the callerID you chose.

Here is a code sample showing you how anonymous 2-way voice works.

Anonymous 2-way Voice with Python
from typing import Optional
from json import dumps

from bottle import run, request, post

# This is a an example response to an Incoming Call event
# {
#     "jsonrpc": "2.0",
#     "method": "dial",
#     "params": {
#         "caller_id_number": "18888888888", # this is your assigned virtual number
#         "to": "19999999999"  # this is the intended destination number
#     }
# }

class TelesignEvent:
    """
    Events Telesign Voice API sends.
    """
    INCOMING = "incoming_call"
    CALL_COMPLETED = "call_completed"
    ANSWERED = "dial_completed"
    PLAY_COMPLETED = "play_completed"
    SPEAK_COMPELTED = "speak_completed"

class DialCommand:
    def __init__(self, to: str, caller_id_number: str):
        self.method: str = 'dial'
        self.to: str = to
        self.caller_id_number: str = caller_id_number

    def generate_response(self):
        params = {
            'caller_id_number': self.caller_id_number,
            'to': self.to
        }
        return Response(method=self.method,
                        params=params).to_json()

class SpeakCommand:
    def __init__(self, tts_message: str, language=Optional[str], collect_digits: bool=False, digits_to_collect: int=1, timeout: int=10000, inter_digit_timeout: int=3000):
        self.method: str = 'speak'
        self.tts_message: str = tts_message
        self.language: str = language
        self.collect_digits = None
        if collect_digits:
            self.collect_digits = {
                'collect_digits': {
                    'max': digits_to_collect,
                    'timeout': timeout,
                    'inter_digit_timeout': inter_digit_timeout
                }
            }

    def generate_response(self):
        params = {
            "tts": {
                "message": self.tts_message,
                "language": self.language
          }
        }
        if self.collect_digits:
            params.update(**self.collect_digits)

        return Response(method=self.method,
                        params=params).to_json()
class HangupCommand:
    def __init__(self):
        self.method = 'hangup'

    def generate_response(self):
        return Response(method=self.method,
                        params={}).to_json()
class Response:

    def __init__(self, method, params=None):
        if params is None:
            params = {}

        self.json_rpc = "2.0"
        self.method = method
        self.params = params

    def to_json(self):
        return dumps(self.__dict__)

@post('/')
def telesign_event():
    # Throughout a call session TeleSign will notify you of all events.
    # Each event requires you to send us an appropriate action defined in our documentation.
    # This endpoint needs to match the URL stored in our system to properly communicate.
    #
    # In this example, the server will respond to the incoming call event.

    # First extract the event from the JSON body in the request.
    event = request.json.get('event')

    if event == TelesignEvent.INCOMING:
        # Respond to this event with a dial command.
        caller_id_number = '18888888888' # This is your leased number from TeleSign
        destination_number = '19999999999'

        # Generate the command in the JSON format used by TeleSign. Refer to the Voice documentation for details.
        return DialCommand(to=destination_number,
            caller_id_number=caller_id_number).generate_response()

    elif event == TelesignEvent.ANSWERED:
        return SpeakCommand(tts_message='Thanks for using Telesign',
                            language="en-US",
                            collect_digits=True).generate_response()
    else:
        # You do not know the number
        return HangupCommand().generate_response()

run(host='localhost', port=8080, debug=True)

Here is a drawing showing you the flow:

Workflow Diagram, Option A

This workflow demonstrates what happens if you choose to connect the two end users to one another for their call.

  1. You are notified by TeleSign that there is an incoming call. The incoming call will contain the real phone number of the end user trying to make the call and the number they would like to contact.
  2. Using logic you create, you determine whether you should connect the call. If you decide yes, you send a request to TeleSign containing the phone number the end user wanted to dial and the callerID to be used to mask the number. TeleSign bridges the call between the two users.
  3. One of the users hangs up.
  4. TeleSign notifies you that the call completed. The notification contains information about both the inbound and outbound parts of the call.

Workflow Diagram, Option B

This workflow demonstrates what happens if an end user tries to make a call and there is a reason for you to not connect the end user.

  1. You are notified by TeleSign that there is an incoming call. The incoming call will contain the real phone number of the end user trying to make the call and the number they would like to contact.
  2. Using logic you create, you determine whether you should connect the call. If you decide yes, you send a request to TeleSign asking to terminate the call.
  3. TeleSign notifies you that the call completed. The notification contains information about the inbound part of the call.

Set Up an Anonymous Session

You have the option of configuring and saving the details that will be used for the anonymous 2-way call in advance, before the request to initiate the call is made. You can do this by creating a session. See Set Up an Anonymous Voice Session for more details on how to do this.

Next Steps

Check out these related pages: