Inbound SMS

When an end-user sends an SMS from their device to a Phone Number or Short Code they have sent an Inbound SMS. Inbound SMS, for historical reasons, is referred to as Mobile Originated (MO) SMS.

Sending an SMS message is only one way to deliver your message to a recipient; in order to increase the interaction, two-way communication is required. In this tutorial, we show you how to receive an SMS and verify the details of the interaction between the recipient and your application.

Inbound SMS API enables the automation of the process of retrieving responses sent by customers to the messages you sent to them. For this reason, it allows the creation of processes to interact with users through the delivery channel: SMS.

The term MO (mobile originated) message stands for a mobile message routed from an end user’s mobile device and delivered to a mobile phone or an application. More precisely, this is a message that a customer/subscriber sends from a mobile phone to a web application or platform. For example, you send the following SMS message to your customer waiting for a response from them: “Send PIZZA to 7878 for 30% off your next order!

This means that MO message is the first step in the SMS marketing journey after the marketer informs customers they can participate and win or get some benefit by sending a message with a specific keyword to a dedicated short code.

A SMS Keyword is designed for mobile users to receive back a communication when they text a specific Keyword or Phrase to a specific shortcode or long code. The keyword will trigger an auto-reply text message that is tied to your campaign. It is one of the most commonly used SMS Marketing Strategies today.

A Keyword is a unique term (letters and/or numbers) that people can use to communicate with you via a short code or long code. For example, if a Concert Company asks you to text TICKET to 12324 to enter into a free ticket giveaway, the SMS keyword is TICKET.

Shortcode: shorter than full telephone numbers, they can be used to address SMS messages. They are typically 4 or 5 digits long and are designed to be easier to read and remember. SMS short codes are most often used by companies for marketing and security or organizations for urgent information dissemination.

Long code: a long code number is a standard phone number used to send and receive voice calls and SMS messages. Phone numbers are typically called “long codes” (10-digit numbers in many countries) when comparing them with SMS short codes (5-6 digit numbers). Typically, a long code is used by courier companies, banks, airlines and other service sectors for customer service related communication.

Once the previous terms are understood, we proceed to explain the interaction between the end user and the campaign in the following example:

If Cinema Theater wants to reward its loyal customers with a special discount SMS voucher, it can organize and market this SMS marketing campaign by sending SMS info to those customers who have already opted in to receive notifications from their favourite Cinema Theater place. The next step is MO message, coming from the customer who wants to participate. He needs to send a keyword to a specific number to participate and win.

This API provides the ability to optionally set prefixes in your Campaigns. For example, once you create a new forward process, you set the keyword: PLAY and the prefix: MUSIC, the end user must send MUSIC PLAY to obtain discounts on the music streaming platform. When you create another forward process, you can not set the same keyword while the process is active but you can set the same prefix in different processes. Therefore, the keyword is unique by process and code (origin). For example:

• Forward Process 1 : (Keyword: PLAY, Prefix: MUSIC)

• Forward Process 2 : (Keyword: STOP, Prefix: MUSIC)

📘

NOTE

The prefix must be written before the keyword.

In addition, this API allows you to deactivate the processes, that is, turn off the campaign to not receive messages and record the interactions of the end users who register through the campaign to obtain discounts, prizes, coupons, etc. This helps you not to delete the campaign and only deactivate it, you can even reactivate the campaign if you desire.

📘

NOTE

If the campaign is deactivated, the process information will not be sent through the Callback URL.

Once you understand the purpose of this API, the Digital Engagement API platform provides the ability to route incoming messages destined for an external service that processes those messages with your business rules. Finally, the messages can be sent back through the platform. This process is called Forward.

Forward process in this API basically receives an SMS message from an end user, evaluates it and depending on the result the message is redirected to another process.

This process allows you to publish alerts and events in callbacks through the url parameter. For more information to set the callback service on which the Delivery report will be sent goes to the Callback URL (MO) section.

Creating Forward

You are able to create a new Forward process through the SMS delivery channel.

When you create an SMS Forward process, the request body contains the following data:

HTTP Request : POST / forwards

{
  "description": "Process description",
  "channel": "SMS",
  "origins": [
    "1415"
  ],
  "name": "Process name",
  "keywords": [
    "key1"
  ],
  "url": "http://www.mycallback.com"
}

The parameters presented in the request body example when creating the SMS Forward process are the following:

When you created the forward process, the response body contains the following data:

{
  "meta": {
    "timestamp": 1629693786128,
    "transactionId": "108de254-6fdb-4b4d-acd4-edf5a5ddc300",
    "explain": "Process created"
  },
  "data": {
    "id": 937,
    "description": "Process description",
    "channel": "SMS",
    "origins": [
      "1415"
    ],
    "active": true,
    "name": "Process name",
    "keywords": [
      "ACTION"
    ],
    "priority": 500,
    "url": "http://www.mycallback.com",
    "owner": "[email protected]",
    "operator": "[email protected]"
  }
}

The parameters presented in the response body example when creating the Forward process are the following:

Updating Forward

In order to update a Forward process PUT method might be used. Note that the PUT method is going to REPLACE the current data of the forward process for the data sent in the request (meaning fields not sent are going to be erased from the forward process).

To update a forward process, you need to pause, update and resume the forward process. To perform all three actions you need to provide the unique identifier of the forward process you want to pause, update and resume:

Pause Forward Process → HTTP Request : PATCH /processes/{id}/pause

Update Forward Process → HTTP Request : PUT /forwards/ {id}

Resume Forward Process → HTTP Request : PATCH /processes/{id}/resume

Getting Forward

You can get specific data from a Forward process previously created.

To get a forward process, you need to provide the unique identifier of the forward process you want to get the details of a single instance of this process.

HTTP Request : GET /forwards/{id}

Deleting Forward

You can delete a specific Forward process previously created.

To delete a forward process, you need to provide the unique identifier of the forward process you want to delete.

HTTP Request : DELETE /forwards/{id}

Example

In the following example, we are going to create a Forward process.

These instructions describe how you can create your first Forward process! Using cURL calls.

Before you can start using the Inbound SMS API, you need to complete the following steps:

Your API call must have the following components:

Create a Forward process

The steps to create a forward process using the Forward API are the following:

Update a Forward process

Once the forward process is created, we proceed to change the value of some parameters.

Before updating the forward process, we need to pause the process.

To Pause the forward process, we need to provide the API Key and unique identifier id of the forward process and place it in the cURL in FORWARD_ID:

Once the process is paused, we proceed to update the a forward process with the following steps:

Once the forward process is updated, we proceed to resume the process.

To Resume the forward process, we need to provide the API Key and unique identifier id of the forward process and place it in the cURL in FORWARD_ID:

All responses are returned in JSON format. We specify this by sending the Content-Type header.

Get a Forward process

Once the forward process is created, we proceed to get the information from a single forward process.

The steps to get a forward process are the following:

All responses are returned in JSON format. We specify this by sending the Content-Type header.

Delete a Forward process

Once the forward process is created, we proceed to delete the forward process.

The steps to delete a forward process are the following:

All responses are returned in JSON format. We specify this by sending the Content-Type header.