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, see SMS - Overview or SMS Verify - Overview.



The expected response is HTTP 200.

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. Provide Telesign with your private URI.
  3. Allow 1 business day for setup to be completed.
  4. You will receive callback notifications after an end user sends MO messages to your dedicated short or long code.
  5. If Telesign is unable to deliver your callback notification on the first attempt, the Telesign server tries again. If the second attempt fails, the server makes a third and final attempt.

Service setup for SMPP

If you are a Telesign client using SMPP, you can consume MO (Mobile Originating) messages over SMPP only. Telesign delivers these messages using the deliver_sm PDU and short_message parameter. To set this up, do the following:

  1. Establish a TRx or Rx bind with Telesign.
  2. Have our Customer Support Team enable Inbound Messaging for you.
  3. You will receive messages after an end user sends MO messages to your dedicated short or long code.
  4. If your bind is down, Telesign will deliver your MO messages to you once your bind is re-established.

Callback responses

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

An Authorization header (refer to the section Authenticate callbacks from Telesign below) and a response that contains the following properties:






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.



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



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. You can see a complete list in the Country Codes and Dialing Codes section of the Codes, Languages, and Time Zones page.



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.



Returns the price of the mo message you sent. This feature must be enabled by our Customer Support Team.

Example response

  "status": {
    "updated_on": "2017-01-27T19:46:55.787464Z",
    "code": 1500,
    "description": "Delivered to customer"
  "submit_timestamp": "2017-01-27T19:46:55.778000Z",
  "errors": [],
  "user_response": {
    "phone_number": "15552273726",
    "iso_country_code": "US",
    "sender_id": "222222",
    "mo_message": "MO message content."
  "sub_resource": "mo_sms",
  "reference_id": "0143D53D86A2030BE20025B600000002"

Authenticate callbacks from Telesign

You can read about how to set up authenticated callbacks on the Authentication page here: Authenticated callbacks with the transaction callback service.

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. You need at least one phone number if you want to receive messages. Speak with our Customer Support Team to purchase one or more phone numbers to use as sender ID.

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.

Have Telesign handle opt-out requests

Telesign can handle opt-out requests for you. To get started, speak with our Customer Support Team. You must have your own sender ID (long code or short code) from Telesign to use this service. Refer to the Buy a phone number (Sender ID) section for more details.

Our Customer Support Team will be able to configure basic opt-out requirements for you. Call to learn more.

You will walkthrough the following steps with our Customer Support Team:

  1. Purchase a sender ID (either long code or short code phone number) from Telesign.
  2. Send the sender ID purchased from Telesign in each request. Alternatively, Telesign can configure your account so that the purchased sender ID is used in applicable destination(s).
  3. Your dedicated sender ID can be configured to automatically opt-out end users.
  4. Conduct your SMS program.

The basic workflow is:

  1. You send SMS messages to your end users.
  2. An end-user opts out by replying "STOP".
  3. Telesign unsubscribes the end user's phone number from future messages sent with your sender ID.
  4. If the end user sends "START" to your sender ID, they are removed from the opt-out list, however they must go through your opt-in flow again in order to subscribe to message services.

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. Certain elements of the auto response are customizable, however the auto responses cannot be turned off.

Did this page help you?