Authentication
APIs
SMS API
Voice API
Score API
PhoneID API

Inbound SMS

TeleSign’s Inbound SMS enables you to receive Mobile Originated (MO) messages sent by your end users. For this to work, you must have a dedicated Sender ID provided by TeleSign.

For sending outbound SMS messages, you can use the SMS API.

You can read about Inbound SMS in the following sections:

Service Setup

To receive MO messages from end users, you need to set up the following:

  1. Create a private URI on your web server for receiving callback notifications from TeleSign.
  2. In the left navigation menu, under Products, click SMS.
  3. Click Settings.
  4. Next to Customer Callback URLs, click Edit. The Customer Callback URLs popup appears.
  5. Click Add a URL.
  6. Enter the URL you want to use for receiving callbacks from your end users.
  7. Click Save.
  8. Buy a phone number to use as a sender ID.
  9. You will receive callback notifications after an end user sends MO messages to your dedicated short or long code.
  10. If TeleSign is unable to deliver a callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt.
  11. TeleSign expects an HTTP 200 response. For every non HTTP 200 status response returned, TeleSign will do a retry.

Callback Responses

When you check callback notifications to retrieve messages from end users, each callback notification’s JSON response contains the following:

Custom Authorization header (refer to the section Authenticate Callbacks from TeleSign below) and a response that contains the following parameters:

ValueDescription
reference_idA 32-digit hex value used to identify the MO (Mobile Originating) message. The value is randomly-generated by TeleSign, and is returned in the callback.
sub_resourceThe subresource accessed; it is set to mo_sms.
errorsA JSON object that contains information on error conditions that might have happened. For now, this field will always be empty. If you receive a callback, there is no error.
status
ValueDescription
codeA 4-digit status code telling you the outcome of the request.
descriptionA text description for the specified status code.
updated_onA timestamp indicating when the status was last updated.
submit_timestampAn ISO 8601 UTC timestamp indicating when the callback was sent.
user_response
ValueDescription
phone_numberThe end user's phone number, including the country code.
sender_idShort or long code over which an end user response was received. This is the short or long code to which the end user is sending their MO message.
mo_messageContent of the message sent by end user.

Authenticate Callbacks from TeleSign

You can read about how to set up authenticated callbacks on the Authentication page here: Authenticated Callbacks with the Get Status / Verify Transaction API.

Buy a Phone Number (Sender ID)

TeleSign offers the option of buying a sender ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number, and in the portal (portal.telesign.com) it is referred to as a phone number. If you want to buy a phone number to use as a sender ID, do the following:

  1. Go to portal.telesign.com and log in.
  2. If you are on TeleSign’s free trial, you need to upgrade and provide billing information before proceeding. You do that by clicking the Upgrade button in the upper lefthand corner. If you already upgraded your account, ignore this step.
  3. In the left nav, under Products, click SMS.
  4. Click Settings.
  5. Next to Customer Callback URLs, click Edit. The Customer Callback URLs popup appears.
  6. Click Add a URL.
  7. Enter the URL you want to use for receiving callbacks from your end users.
  8. Click Save.
  9. On the left nav, under Account, click Phone Numbers. The Buy a Phone Number screen appears.
NOTE:

If you did not upgrade your account, you cannot buy phone numbers. Upgrade your account before proceeding.

  1. You can search for a phone number to use as a sender ID by country and by feature using the drop downs. Use the Search by Country drop down to choose the appropriate country. Because you are going to use the phone number as a sender ID, open the Feature drop down and choose 2-Way SMS.
  2. Click Search.
  3. From the list of numbers returned, choose a number you want to buy and next to it click Buy Now. If you did not set up a callback URL, you will not be able to buy a number. You must have your URL configured before buying. If your URL is configured, the Confirm Payment popup appears.
  4. Check to see that you have the correct phone number and features. Review the compliance information provided if you need to. If everything looks ok, click Submit. You get a message saying your phone number was successfully purchased.
NOTE:

TeleSign recommends that you purchase a phone number in each country in which you want to transact. TeleSign cannot guarantee preservation in other countries.

Filtering for Specific Keywords

You can request to receive only messages that have specific keywords. You must provide the keywords you want to use for filtering to TeleSign. TeleSign will filter out all messages that do not contain those keywords.

WARNING:

You own the dedicated short or long code over which MO messages are received. You may be charged for messages sent to you even though they are filtered out.

Automatic Response to Compliance Keywords

Due to compliance requirements in the United States and Canada, TeleSign automatically responds to certain MO keywords that are sent to a dedicated phone number. Keywords that trigger an automatic response include:

  • STOP, END, CANCEL, UNSUBSCRIBE, QUIT, ARRET
  • HELP, AIDE, INFO
NOTE:

These behaviors are for the US and Canada only. The auto response is not customizable, and cannot be turned off.