Inbound SMS - Get started

This page explains how to set up Telesign Inbound SMS to receive messages from your end users. Inbound SMS messages are also known as Mobile Originated (MO) messages.

πŸ“˜

NOTE:

For sending outbound SMS messages, see SMS - Overview or SMS Verify - Overview.

Before you begin

Make sure you have the following ready:

  • Telesign phone number: You need a phone number (either long or short code) purchased from Telesign to serve as the destination for inbound messages. See How do I purchase a phone number for my account? for details on how to get a Telesign phone number.
  • Enable SMS or SMS Verify: Either SMS or SMS Verify must be enabled for your account for you to use Inbound SMS. If you are a full-service customer, contact [email protected] to enable one of these products. If you are a self-service customer, these products are already enabled for your account.

Service setup for HTTPS

  1. Enable Inbound SMS: If you have a self-service account, sign into your account and select SMS then Manage settings in the Telesign portal and toggle SMS 2-Way Inbound Enabled to "Enabled". If you have a full-service account, ask our Customer Support Team to enable Inbound SMS for your account.

  2. Enable notifications: If you have not already done so, set up a Transaction Callback Service to receive notifications from Telesign, including MO message notifications. See Transaction Callback Service to learn how to set this up.

  3. Set up handling of MO message notifications: The schema for MO message notifications is not the same as the example notification schema shown on Transaction Callback Service, so use the details in the Schema section on this page to handle these notifications.

Service setup for SMPP

πŸ“˜

NOTE:

SMPP integration is available for full-service accounts only.

  1. If you have not already done so, set up your SMPP integration with Telesign; see SMPP protocol for detailed instructions.
  2. Establish a Transceiver (TRX) or Receiver (RX) bind with Telesign.
  3. Ask our Customer Support Team to enable Inbound SMS for your account. Telesign sends notifications with this service after an end user sends MO messages to your dedicated short or long code. If your bind is down, Telesign will deliver these notifications to you once your bind is re-established.
  4. Handle these notifications using the information in the Inbound SMS section of SMPP Protocol.

πŸ“˜

NOTE:

If your Telesign integration uses SMPP, you can only receive MO message notifications via SMPP. You won't ever receive these notifications via HTTPS.

Automatic response to compliance keywords

Due to compliance requirements in the United States and Canada, Telesign allows you to handle certain keywords by automatically responding when messages containing those keywords are sent in reply to your MO messages. These behaviors are for the US and Canada only. Certain elements of the auto response are customizable but the auto responses cannot be turned off.

Schema

Callback responses

When you check callback notifications to retrieve messages from end users, each callback notification's JSON response contains an Authorization header (see Authenticate callbacks) and a response that contains the following properties:

PropertyTypeDescription
reference_idstringA 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_resourcestringThe subresource accessed; it is set to mo_sms.
errorsobjectA 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.codestringA 4-digit status code telling you the outcome of the request.
status.descriptionstringA text description for the specified status code.
status.updated_onstringA timestamp indicating when the status was last updated.
submit_timestampstringAn ISO 8601 UTC timestamp indicating when the callback was sent.
user_response.actionstringThe acton that was triggered in response to specific keywords in a MO message. Some keywords will trigger automatic responses. Can be "start", "stop", "help", or generic. Refer to [Inbound SMS - Action-to-keyword mapping] for a complete list of actions and the associated keywords.
user_response.keywordstringSpecific words in an MO message from an end user that triggers certain actions. Each keyword can have different response template so the keyword "STOP" can use a response template that's in English while the keyword "ARREST" can use a response template that's in French.
user_response.phone_numberstringThe end user's phone number, including the country code.
user_response.iso_country_codestringA two letter country code representing the country the phone number is associated with. You can see a complete list in Country Codes and Dialing Codes.
user_response.sender_idstringShort 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.
user_response.mo_messagestringContent of the message sent by end user.
pricestringReturns the price of the MO message you sent. This feature must be enabled by our Customer Support Team.

Example

This is an example payload of an MO message notification received via HTTPS.

{
  "sub_resource": "mo_sms",
  "submit_timestamp": "2022-10-04T12:12:34.390000Z",
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "status": {
    "updated_on": "2022-10-04T12:12:34.473702Z",
    "description": "Delivered to customer",
    "code": 1500
  },
  "errors": [],
  "user_response": {
    "action": "stop",
    "iso_country_code": "US",
    "keyword": "ARRET",
    "sender_id": "6281298636572",
    "phone_number": "11234567890",
    "price": "0.0108",
    "mo_message": "ARRET"
  }
}