# Receive an SMS message using Infobip API

In this tutorial, you will learn how to send an SMS message from your handset to a webhook that you have configured. This will simulate a scenario in which an end user can reply to an SMS and their message gets stored in a third-party application that you manage.

The tutorial assumes basic familiarity with APIs. It is important however that you are faimiliar with the webhook technology and how to utilize it for this project. For the ease of replicating the scenario, we have used a free online webhook tool, [HookRelay](https://www.hookrelay.dev/).

## Prerequisites

* [Infobip account](https://portal.infobip.com/login/?callback=https%3A%2F%2Fportal.infobip.com%2F). If you do not have one create a [free trial account](https://www.infobip.com/signup).
* The [SMS Sender](https://www.infobip.com/docs/sms/get-started#senders). If you are in the free trial period, you can use Infobip's test sender, `ServiceSMS`.
   If you want to configure your custom sender, request a new number or an alphanumeric sender through the [Infobip account](https://portal.infobip.com/channels-and-numbers/channels/sms/overview) or using [Infobip Numbers API](https://www.infobip.com/docs/api/platform/numbers).
* Ability to [send an SMS](https://www.infobip.com/docs/tutorials/send-your-first-sms-message-using-infobip-api).
* A webhook that will listen to incoming events.

## Implementation

1. Buy a number capable of receiving incoming SMS traffic.
2. Set up a webhook.
3. Add webhook details to the number you've purchased.
4. Receive an SMS on your webhook.

### Buy a number

To buy a number, you'll need to log into your Infobip account. If using the Infobip test sender, skip this section.

1. Expand the __Channels and Numbers__ icon on the left-hand side menu, and select __Numbers__.
2. On the __Numbers__ screen, click __Buy Number__.
3. Set up your number preferences, like a country, number type, etc.
4. Once you chose all details, click __Buy__ to finalize the purchase.

### Set up a webhook

For the purpose of this guide, we will use a simple online webhook tool, [HookRelay](https://www.hookrelay.dev/). This section will show you how to create and account and configure the webhook with HookRelay.

#### Step 1. Sign in with git credentials

Sign in to [HookRelay](https://www.hookrelay.dev/) with your GitHub or GitLab credentials. Once logged in, you'll access a dashboard where you can start creating webhooks.

#### Step 2. Create a webook

To create an inbound webhook, from your dashboard, click the __New Hook__ button on the top right. That will take you to the configuration screen where all you need providing is a descriptive name for your webhook, e.g. __Infobip Receive SMS__ and to make sure it's able to receive incoming traffic.

Once you click the __Create hook__ button, you'll be able to view and copy its URL that you will need to add to your number configuration in your Infobip account.

### Configure your number with webhook details

Head back to your Infobip account and access your number configuration page (Channels and Numbers > Numbers). If using the Infobip test sender, configure that number.

1. Select the number and click the __SMS__ tab.
2. Under __Keywords__, click the plus icon to add a keyword.
3. Use the __Forwarding action__ dropdown to select the __Forward to HTTP__ option.
4. Under __URL__ provide the URL of the webhook that you have created.
5. Select __MO_JSON_2__ as a __Renderer Type__.
6. Click __CONFIGURE__ to save configuration.

### Receive an SMS on your webhook

Now that we have everything configured, to test that all works as expected, [send an SMS](https://www.infobip.com/docs/tutorials/send-your-first-sms-message-using-infobip-api) from your handset to the number you have purchased. This should trigger an event, and you should see your message in JSON format arriving at your webhook.

```bash
{
  "results": [
    {
      "from": "447415774432",
      "to": "447491163443",
      "text": "SEND10",
      "cleanText": "",
      "keyword": "SEND10",
      "receivedAt": "2025-03-13T11:43:00.603+0000",
      "smsCount": 1,
      "messageId": "2491729790183409612",
      "pairedMessageId": null,
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      },
      "callbackData": null
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}
```

## Useful links

- [SMS API reference](https://www.infobip.com/docs/api/channels/sms)
- [SMS](https://www.infobip.com/docs/sms)
- [Response status and error codes](https://www.infobip.com/docs/essentials/api-essentials/response-status-and-error-codes)
- [Deliverability](https://www.infobip.com/docs/sms/deliverability)
- Infobip Broadcast
- [Infobip SDKs](https://www.infobip.com/docs/sdk)