Voice - Set up a call with number masking

📘

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 a call where both parties have their numbers masked, using Telesign Voice.

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

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.
  • Webhook endpoint: A notification service you have set up for Telesign to send 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

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

  • Telesign phone number: A voice-capable phone number you have purchased from Telesign to use as a caller ID. Contact our Customer Support Team for details.

Be sure also to only use supported standards and codecs (see Voice - Supported standards and codecs).

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:

A comparison of call flow diagrams A and B which demonstrate two ways a call is handled when Voice's number masking is used.

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 Event from Telesign. This Event contains the real phone number of the end user trying to make the call (originating number) and the virtual number of the user they would like to contact (destination number).
  2. Connect the call by sending 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 Event from Telesign. This 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 Event from Telesign. The incoming call contains the real phone number of the end user trying to make the call (originating number) and the virtual number of the user they would like to contact (destination number).
  2. Since you don't want to connect the two users, send a request to Telesign to terminate the call.
  3. You get a call completed Event from Telesign. This 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 Telesign Number Masking. See Number Masking - 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

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 Telesign Voice 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 sends Event notifications.
    # Each Event can be responded to with a supported Action.
    #
    # 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 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)

What’s Next

Check out these related pages: