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
-
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.
-
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.
-
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.
- If you have not already done so, set up your SMPP integration with Telesign; see SMPP protocol for detailed instructions.
- Establish a Transceiver (TRX) or Receiver (RX) bind with Telesign.
- 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.
- 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.
| Property | Type | Description |
|---|---|---|
| reference_id | string | 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 | string | The subresource accessed; it is set to mo_sms. |
| errors | object | 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.code | string | A 4-digit status code telling you the outcome of the request. |
| status.description | string | A text description for the specified status code. |
| status.updated_on | string | A timestamp indicating when the status was last updated. |
| submit_timestamp | string | An ISO 8601 UTC timestamp indicating when the callback was sent. |
| user_response.action | string | The 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.keyword | string | This is an optional property, present only for start/stop/help action related keywords (not generic). Specific 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 "arrêt" can use a response template that's in French. |
| user_response.phone_number | string | The end user's phone number, including the country code. |
| user_response.iso_country_code | string | A 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_id | string | 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. |
| user_response.mo_message | string | Content of the message sent by end user. |
| price | string | Returns 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": "arrêt",
"sender_id": "6281298636572",
"phone_number": "11234567890",
"price": "0.0108",
"mo_message": "arrêt"
}
}
Updated 2 months ago