Want to provide feedback?

Write to docs@telesign.com.

NOTE:

If you are interested in trying TeleSign’s Voice API, sign up by contacting our experts.

Set Up a Call with Number Masking

This page explains how to set up a call where both parties have their numbers masked, using the TeleSign 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:

Requirements

You must have the following:

  • TeleSign credentials: Your customer ID and API key
  • Pool of virtual phone numbers: Purchase these numbers using the TeleSign Phone Numbers API (see Get Started with the Phone Numbers API) or ask our Customer Support Team to purchase numbers for you.
  • SSL: Valid SSL certificate for the server hosting your customer event URL
  • 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.

If you do not want to use your own number, you should also have:

  • 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). If you plan to create anonymous sessions in advance that can be used for number masked calls later, this number also needs to be SMS-capable (include the parameter and value sms_capable=true in your request to the Phone Numbers API).

Be sure also to only use supported standards and codecs (see Supported Standards and Codecs).

Note

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

How it Works

This use case begins with an inbound call. 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 to connect the incoming call to the destination number being requested. If you do decide to connect, you then set up an outbound call. The outbound call contains the number that the end user wanted to call and the masking caller ID you want to use. TeleSign then bridges the call from the originating end user to the phone number they wanted to call, masked with the caller ID you chose.

Call Flow Diagrams

These diagrams show you two ways that the call can be handled:

Diagram A: Connect the End Users

An end user tries to make a call and you decide to connect them to the other end user.

  1. You get an incoming call notification from TeleSign. The incoming call contains the real phone number of the end user trying to make the call (originating number) and the real number of the user they would like to contact (destination number).
  2. Your system determines whether you should connect the call. In this case you decide to connect, so you send a request to TeleSign containing the originating number and the caller ID to be used to mask it. TeleSign bridges the call between the two users.
  3. One of the users hangs up.
  4. You get a call completed notification from TeleSign. The notification contains information about both the inbound and outbound parts of the call.

Diagram B: Do Not Connect the End Users

An end user tries to make a call and you decide to not connect them to the other end user.

  1. You get an incoming call notification from TeleSign. The incoming call contains the real phone number of the end user trying to make the call (originating number) and the real number of the user they would like to contact (destination number).
  2. Your system determines whether you should connect the call. In this case you decide not to connect, so you send a request to TeleSign asking to terminate the call.
  3. You get a call completed notification from TeleSign. The notification contains information about only the inbound part of the call.
NOTE:

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

Using Sessions

You can also configure and save the details that will be used for your number masked call in advance, before the request to initiate the call is made. You can do this by creating a session using the TeleSign Number Masking API. See Create Masked Session for SMS or Voice for more details on how to do this.

Example

Here is an example in Python showing you how to set up a call with number masking.

NOTE:

To run the code sample below on your own machine, you need both Python 3 and Bottle. Run pip install bottle if you do not already have Bottle installed.

Example: Set Up a Call with Number Masking
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
# {
#     "method": "dial",
#     "params": {
#         "caller_id_number": "18888888888", # this is your masking ID
#         "to": "19999999999"  # this is the destination number
#     }
# }

class TelesignEvent:
    """
    Events that the Telesign Voice API sends.
    """
    INCOMING = "incoming_call"
    CALL_COMPLETED = "call_completed"
    ANSWERED = "dial_completed"
    PLAY_COMPLETED = "play_completed"
    SPEAK_COMPLETED = "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.method = method
        self.params = params

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

@post('/')
def telesign_event():
    # Throughout a call session TeleSign notifies you of all events.
    # Each event requires you to send us an appropriate action defined in our documentation.
    #
    # In this example, the server responds 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 the masking number
        destination_number = '19999999999'

        # Generate the action to send to TeleSign. Refer to the Voice API Reference 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)

Next Steps

Check out these related pages: