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.

📘

NOTE:

The expected response is HTTP 200.

Service setup

Before you begin

Make sure you have the following ready:

• Telesign phone number: You need a phone number 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.
• Transaction callback service: The web service you have set up to receive transaction status callbacks from Telesign is also used to receive inbound SMS. See Transaction callback service to learn how to set this up.

Steps

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

If you have a self-service account:

1. Go to SMS > Settings in the Telesign portal and toggle SMS 2-Way Inbound Enabled to "Enabled".

If you have a full-service account:

1. Ask our Customer Support Team to enable Inbound SMS for your account.

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:

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 phone numbers to use as sender IDs.

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.

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:

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

📘

NOTE:

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.