Receive an SMS

In this SMS API Quickstart, we’ll show you how to receive and handle inbound SMS messages using webhooks, Flow Builder and the MessageBird SMS API.

We’ll walk you through the following steps:

1. Purchase a Virtual Mobile Number from MessageBird
2. Set up a Webhook Handler
3. Set up a flow in Flow Builder

Step 1: Purchase your SMS-enabled Virtual Mobile Number

1. Go to the Numbers section in your Dashboard and click Buy a number
2. Pick the country in which you and your customers are located, and make sure the SMS capability is selected.
3. Choose one number from the selection.

Step 2: Set up your Webhook Handler

You can set up your SMS handler with any HTTP method, but we strongly recommend you to use POST. The method you specify in your application must be the same that you'll configure later in Flow Builder. MessageBird sends inbound SMS as form-encoded requests so you can read the input just as if it were an HTML form submitted by a user of your application.

There are a variety of fields, but most applications only need the following two:

• The originator is the phone number that sent the message to you. It will be provided in the international format with country code.
• The payload is the content of the message.

Your application can return any or even an empty response to a webhook. You should make sure that you don’t return an HTTP error status code.

If you want to reply to the message, simply follow the instructions for sending SMS using your programming language and add the originator from the webhook to the recipients parameter of the outgoing message.

If you want to set up a test environment, you can use a Tunnelling provider such as Ngrok. Read more about setting up Ngrok in this tutorial.

Step 3: Set up Flow Builder

Now, let’s head over to Flow Builder and select the Call HTTP endpoint with SMS template:

1. Select your SMS-enabled Virtual Mobile Number that you purchased in Step One
2. Select POST as the Method
3. Enter your Webhook URL and make sure the URL ends with /webhook
4. Hit publish to activate your flow.

Congrats! You can now programmatically handle inbound SMS with Flow Builder, webhooks, and the SMS API.