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.

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 10 seconds, then tries again. If the second attempt fails, the server waits 30 seconds and then makes a final attempt. All together, it's a total of three tries to make the delivery.
  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:





A 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.


The subresource accessed; it is set to mo_sms.


An 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.



A 4-digit status code telling you the outcome of the request.


A text description for the specified status code.


A timestamp indicating when the status was last updated.


An ISO 8601 UTC timestamp indicating when the callback was sent.



The end user's phone number, including the country code.


A two letter country code representing the country the phone number is associated with.


Short 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.


Content 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 dedicated phone number to use as a sender ID when sending communications to your end users. To buy a phone number to use as a sender ID, follow these steps:

  1. Go to 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.



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.



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.



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:




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

Did this page help you?