Send an interactive list with WhatsApp API

As an outcome of this guide, you will be able to leverage Infobip WhatsApp API and send an interactive WhatsApp message delivered to your handset.

Scenario overview

The WhatsApp sender sends a message with an image and a list of options a user can select. Once the user clicks on an option, a reply is sent back to the WhatsApp sender. That, in turn, can trigger an appropriate series of actions and responses, but this is out of scope for this guide. We will, however, discuss briefly how to intercept an incoming message with a webhook to see a user's reply.

Prerequisites

• Infobip account (opens in a new tab). If you do not have one, create a free trial account (opens in a new tab).
• Infobip API key with the whatsapp:message:send scope. Find out more about scopes in API Authorization.
• Your favorite HTTP client. In this example, we use cURL. You can also choose an official Infobip SDK in your preferred programming language.
• Sender. If in a free trial period, you can use Infobip test sender, 447860099299 and activate it (opens in a new tab). If you want to configure a custom sender, request a new number or an alphanumeric sender through your Infobip account (opens in a new tab) or use the Infobip Numbers API (opens in a new tab).
• Destination - a phone number to which the message will be sent. In a free trial period, you can only send messages to a verified phone number.

Limitations

With WhatsApp, you can only send a message to your customer if they have contacted you first. This opens a 24-hour window for two-way communication. Otherwise, use a template message (opens in a new tab).

Difficulty level

This guide assumes basic familiarity with APIs. It is important, however, that you are familiar with the webhook technology, if you wish to catch a user response. For ease of replicating the scenario, we have used a free online webhook tool, HookRelay (opens in a new tab). You may replace HookRelay with your own hook server if you need to process your events programmatically.

Summary of the steps

• Buy or configure an existing WhatsApp number capable of receiving incoming traffic.
• Set up a webhook.
• Add webhook details to the number you've purchased or configured.
• Send a WhatsApp message with an interactive list. The webhook will catch the response.

Buy a number

To buy a number, you'll need to log into your Infobip account (opens in a new tab).

1. Expand the Channels and Numbers icon on the left-hand side menu, and select Channels.
2. Select WhatsApp and click Register Sender.
3. From the Register a WhatsApp sender screen, select the option you wish to choose for sender registration.
4. Set up your number preferences, like a country, number type, etc.

You're all set for now. Once a webhook is configured, you'll come back to the number config to add its URL.

Set up a webhook

For the purpose of this guide, we will use a simple online webhook tool, HookRelay (opens in a new tab). This section will show you how to create an account and configure the webhook with HookRelay.

Step 1. Sign in with git credentials

Sign into HookRelay (opens in a new tab) with your GitHub or GitLab credentials.

Step 2. Create a webhook

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 WhatsApp List Response.

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 WhatsApp sender.

Add webhook URL to a WhatsApp sender

Head back to your Infobip account (opens in a new tab) and access your WhatsApp sender configuration page (Channels and Numbers > WhatsApp).

1. Select Senders and click the kebab (three-dot) menu on the WhatsApp sender's tile to select Edit configuration.
2. Under Keywords add a new one or edit the existing default one.
3. Under the Forwarding action section, select Forward to HTTP and add the webhook's URL to the URL field.
4. Click Save.

That's about it for the webhook configuration. Let's now move to creating a WhatsApp message with an interactive list.

Send a WhatsApp message

We are going to send a message with an interactive list consisting of 4 options. We'll use the Send WhatsApp interactive list message (opens in a new tab) endpoint.

To make it easier to visualize, the image below indicates which parts of the WhatsApp interactive list are driven from which fields in our WhatsApp API.

Key points:

• The to field must include a number in the international format, e.g. 447415074332.
• If using a free trial account, the phone number you use must be the same phone number you've registered on signup.

curl -L 'https://{baseUrl}/whatsapp/1/message/interactive/list' \
-H 'Authorization: {authorization}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "from": "447860099299",
  "to": "447415774332",
  "content": {
    "body": {
      "text": "Dear Developer, select a ticket for our annual Shift conference. Tickets include access to sessions, the event app, and talk recordings."
    },
    "action": {
      "title": "See Tickets",
      "sections": [
        {
          "title": "Choose one ticket.",
          "rows": [
            {
              "id": "1",
              "title": "Regular Student",
              "description": "32€ + VAT"
            },
            {
              "id": "2",
              "title": "Regular Standard",
              "description": "192€ + VAT"
            },
            {
              "id": "3",
              "title": "Regular All Access",
              "description": "216€ + VAT"
            },
            {
              "id": "4",
              "title": "Regular Virtual",
              "description": "56€ + VAT"
            }
          ]
        }
      ]
    },
    "header": {
      "type": "TEXT",
      "text": "Get Your Tickets!"
    },
    "footer": {
      "text": "Join us at Shift!"
    }
  }
}'

Add multiple recipients and multiple messages

If you want to send multiple messages to multiple recipients in one request, use a WhatsApp template message (opens in a new tab)

Track message delivery

Once you send the request, you should receive a WhatsApp message on the handset you've specified in the to field and see a 200 OK response.

{
  "to": "441134960001",
  "messageCount": 1,
  "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",
  "status": {
    "groupId": 1,
    "groupName": "PENDING",
    "id": 7,
    "name": "PENDING_ENROUTE",
    "description": "Message sent to next instance"
  }
}

The response informs you that the message has successfully been queued within the Infobip platform and will be then sent to Meta depending on the throughput.

If you want to know whether it's been delivered to the recipient, use the Delivery Report (opens in a new tab) feature.

Troubleshoot and analyze your message

For troubleshooting and analytics, use the auto-generated messageId to view the message and its details.

Catch the answer

Once a user selects an option from the list, your webhook that's listening to that event will catch the reply. The message object will tell you which option has been selected and sent as an answer.

{
  "results": [
    {
      "from": "447415774332",
      "to": "447860099299",
      "integrationType": "WHATSAPP",
      "receivedAt": "2022-08-18T09:30:52.516+0000",
      "messageId": "ABEGRHQVd0QyAhCEOHQDx2_nQGlWh5eTJdht",
      "pairedMessageId": "e5ee7f2a-5d43-46e1-9e9c-08c83e1ae935",
      "callbackData": null,
      "message": {
        "id": "2",
        "title": "Regular Standard",
        "description": "192€ + VAT",
        "context": {
          "from": "447860099299",
          "id": "e5ee7f2a-5d43-46e1-9e9c-08c83e1ae935"
        },
        "type": "INTERACTIVE_LIST_REPLY"
      },
      "contact": {
        "name": "Joanna Suau"
      },
      "price": {
        "pricePerMessage": 0.0,
        "currency": "EUR"
      }
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}