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 API - 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 API: Either SMS or SMS Verify API 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

Telesign sends you inbound messages from your end users as REST API requests to your Transaction Callback Service. The schema of the payloads of these responses is described below.

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"
  }
}