Create Masked Session for SMS

This page shows you how to create an anonymous session where two users can send text messages to each other using assigned masking IDs instead of their real phone numbers. You must use only SMS capable (not voice capable or dual-capable) numbers from TeleSign as masking IDs when using this action. You must have the Number Masking API enabled to use this action.

Contents of this page:

Reference Page

POST /v1/anonymous/session/sms - See complete technical details for this action, including all request parameters and response properties.

Try It

If you have been granted access and credentials for the Number Masking API, you can try a test request in the API Explorer below. You can also get a code snippet for the request.

  1. Select the Auth tab.
  2. Enter your Customer ID for Username.
  3. Enter your API key for Password.
  4. Select the Body tab.
  5. For phone_number_1, enter your complete phone number with the country code and no special characters or spaces.
  6. For phone_number_2, enter a second phone number to use for testing.
  7. For validity_period, enter an integer between 1 and 720 (assuming the units are configured to hours for your account). This is the time duration that you want the session to last. The units may vary depending on your configuration at setup, ask our Customer Support Team if you are not sure what units apply for your account. (See full parameter details on the API reference page at POST /v1/anonymous/session/sms.)
  8. Select Send.
  9. Select the Code Generation tab and use the Language and Library menus to choose the language you want your code snippet in.
  10. After you send your request, look through the response and make a note of the masked_id and session_id values. The masking ID (masked_id) for each number is what your users will use to communicate with their real numbers masked. You will use the session ID to track the users’ session and monitor as needed.
Caution

When using the API Explorer, you will be charged your contracted rate for each transaction.

Number Masking API Explorer
NOTE: The time shown is not indicative of regular transmission rates, and only applies to this API Explorer.
Send requests directly from the browser (CORS must be enabled)
$$.env
No $$.env variables are being used in this request.
NOTE:

It is possible that the masking ID for both parties is the same number. This does not impact SMS communication between the two parties.

Endpoint

The full endpoint for this action is: https://rest-ww.telesign.com/v1/anonymous/session/sms

How it Works

To connect two users without either knowing the other’s true phone number, the flow works like this:

  1. You receive a request for communication from an end user wanting to text with another end user (say a rider wants to text the driver in a taxi app).
  2. You send an anonymous SMS session request to TeleSign. Your request will include the real phone numbers of both parties.
  3. The rider sends their message. This arrives at TeleSign’s servers.
  4. TeleSign receives the message and sends a text message to the driver, but masked.
NOTE:

Any time a message is sent in an anonymous session, you are billed for two text messages. The first message is the one sent to TeleSign from the originating end user. The second message is the one TeleSign sends to the destination end user.

Example

Below is an example of basic usage of this action.

Request
HTTPS
POST https://rest-ww.telesign.com/v1/anonymous/session/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Content-Type: application/json; charset=utf-8
Date: Tue, 31 Jan 2017 14:51:26 GMT

{
   "phone_number_1": "15555551212", 
   "phone_number_2": "15558675309",
   "validity_period": 500
}
Response (body only)
application/json
{
  "reference_id": "B5862A14363C016C8832D53625270015",
  "session_data": {
    "message": "",
    "phone_number_1": {
      "complete_phone_number": "15555551212",
      "country_code": "1",
      "country_iso2": "US",
      "country_iso3": "USA",
      "country_name": "United States",
      "masked_id": "15557740233"
    },
    "phone_number_2": {
      "complete_phone_number": "15558675309",
      "country_code": "1",
      "country_iso2": "US",
      "country_iso3": "USA",
      "country_name": "United States",
      "masked_id": "15557740234"
    },
    "resource": "sms",
    "session_end_on": "2018-03-05 10:59:13.761245",
    "validity": 500
  },
  "status": {
    "code": 2700,
    "description": "Session successfully created",
    "updated_on": "2018-02-12T14:57:11.765723Z"
  }
}

Next Steps

Check out these related pages: