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 or the SMS Verify API.
You can read about Inbound SMS in the following sections:
The expected response is HTTP 200.
Service Setup
To receive MO messages from end users, you need to set up the following:
- Create a private URI on your web server for receiving callback notifications from TeleSign.
- Provide TeleSign with your private URI.
- Allow 1 business day for setup to be completed.
- You will receive callback notifications after an end user sends MO messages to your dedicated short or long code.
- If TeleSign is unable to deliver a callback notification on the first attempt, the TeleSign server waits 30 seconds, then tries again. If the second attempt fails, the server waits an additional 5 minutes and then makes a final attempt.
- TeleSign expects an HTTP 200 response. For every non HTTP 200 status response returned, TeleSign will do a retry.
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:
- Establish a TRx or Rx bind with TeleSign.
- Have your Technical Account Manager enable Inbound Messaging for you.
- You will receive messages after an end user sends MO messages to your dedicated short or long code.
- 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 parameters:
| Value | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| reference_id | 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. | ||||||||
| sub_resource | The subresource accessed; it is set to mo_sms. | ||||||||
| errors | 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. | ||||||||
| status |
|
||||||||
| submit_timestamp | An ISO 8601 UTC timestamp indicating when the callback was sent. | ||||||||
| user_response |
|
||||||||
| mo_price | Returns the price of the mo message you sent. This feature must be enabled by your Technical Account Manager. |
{
"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": "13392273726",
"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 Get Status / Verify Transaction API.
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 your Technical Account Manager (TAM) 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 your Technical Account Manager (TAM). 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.
Your TAM will be able to configure basic opt-out requirements for you. Call to learn more.
You will walkthrough the following steps with your TAM:
- Purchase a sender ID (either long code or short code phone number) from TeleSign.
- 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).
- Your dedicated sender ID can be configured to automatically opt-out end users.
- Conduct your SMS program.
The basic workflow is:
- You send SMS messages to your end users.
- An end-user opts out by replying “STOP”.
- TeleSign unsubscribes the end user’s phone number from future messages sent with your sender ID.
- 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
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.