Receiving messages: Introduction

Learn how to receive SMS messages sent by your customers.

Besides sending SMS to your customers, you will also need an elegant solution for your customers to contact you back. After all, real dialog happens only when messages flow in both directions. Having an option to receive SMS from your customers can open a whole new range of possibilities for your organization!

One time setup for receiving messages consists of three easy steps.

  1. Purchase number for receiving messages
  2. Setup Configuration container
  3. Setup Action method

Receiving messages

After the three-step setup you can start receiving incoming messages by using one of the two available methods:

  1. Forward method - messages are forwarded to your system in real time
  2. Pull method - messages can be collected by API call

Step 1: Purchase phone number for receiving messages

In order to receive messages, you will need a number which has the ability to receive messages.

There are two basic types of numbers:

  • Virtual Long Number (VLN) - a standard looking phone number most often not different than any other personal phone number (e.g. 441212859469).
  • Short code - number containing fewer digits than VLN and therefore more distinctive looking, with no country and network prefix, great for getting extra attention from your customers (e.g. 32456).

Both types of numbers best operate on a country level so you might need to get multiple numbers if your organization operates in multiple countries.

Phone number API

Use Phone number API to purchase and manage your numbers.

Short code

Short codes cannot be purchased over API. Please contact your Account Manager for more information.

Step 2: Configuration container setup

Each number you own can be configured to handle different scenarios for receiving messages. Rules are set on the Configuration level and delivery methods for each rule are set on the Action level.

Each number can have one or more Configurations and each Configuration can be associated with the keyword. Keywords must be unique on the number level.

First word of each received message is compared against Configuration keywords, and if matched, the message delivery method described within the Configuration Action will be used to deliver the message.


Your company would like to hear if the customers like your latest service so you decide to send out a message with a simple yes or no question.

Dear customers, we were wondering if you liked our latest product. Please answer to this message with a simple YES or NO and add an additional comment if you have one.

Consider the following setup of your number on the Infobip platform.

Now let’s see what would happened when you receive different replies from your customers.

Oh YES, of course, I love your product! Keep up the good work!

This message would match Configuration 1 since it does not start with YES or NO keywords. On the Action level the Pull method is defined, which means that you will be able to access this messages by calling the Pull API method.

Let’s examine this reply

YES! I love your product. Thank you.

The message starts with the keyword YES which means that Configuration 2 will be used to handle the incoming message. The Action inside Configuration 2 has a Forward URL defined so Infobip platform will initiate a HTTP POST or HTTP GET request and send the message inside of the request body in JSON format if you choose POST, or through the URL parameters (query string) if you choose GET.

In order for this to work you need to set up a web page which will listen for requests and accept received messages. The URL of the page needs to be provided during the Action setup.

Configuration container API

We offer a complete set of Configuration management tools over our API. Visit the Configuration documentation to learn more.

Step 3: Action setup

Actions “live” inside Configuration containers. When creating a new Action you must choose one of two possible message delivery methods: 1. Pull 2. Forward

There can only be one Action inside of each Configuration container. If an incoming message matches the rule of the Configuration container, the selected Action delivery method will be used to deliver the incoming message to your platform.

Action API

We offer a complete set of Action management tools over our API. Visit the Action documentation to learn more.

Pull method

Pull method means that all messages received at your number will be saved in thr Infobip message inbox. Messages that we collect will patiently sit there until you decide to collect them. Messages can be collected by calling our Pull API method.

Pull API method

Messages can be collected over the Pull API method only once! This means that with each API call you will only get the messages that arrived after the previous API call.

HTTP Forward method

With this method, you can receive incoming messages in real-time. In order for this to work, you need to expose a web page and listen for an HTTP request. URL of the page must be provided during the Action setup process.

Every time a new message is received on your number, we will initiate an HTTP request which will contain the received message.

Forward method

Find out how to receive forwarded messages at the Receive forwarded messages documentation page.