WhatsApp over API

Infobip WhatsApp API (opens in a new tab) is a scalable solution that enables businesses to programmatically send and receive messages by integrating WhatsApp as their communication channel. It provides a reliable way to interact with customers over WhatsApp, while maintaining data protection and compliance through end-to-end encryption.

The API supports a range of message types, including simple text messages, interactive buttons, and rich media (for example, images, videos). Businesses can use the API to manage communication across the customer journey, from sending onboarding messages and notifications to facilitating two-way customer support conversations.

Additionally, you can enable URL shortening and tracking (opens in a new tab) for buttons in template messages. This feature is available only for templates created through the API (opens in a new tab). To use this feature, you must register a custom domain (opens in a new tab) beforehand, activate URL shortening and tracking during template registration, and define static or dynamic links within the template. The shortening and tracking process is handled automatically during message delivery, providing valuable insights into customer engagement.

To get started, refer to the Authentication guide (opens in a new tab) to secure your connection with Infobip. To ensure your incoming traffic is properly connected to your API, refer to the instructions in the Edit configuration section.

Message templates

Message templates are pre-approved messages that allow businesses to communicate with customers outside the permitted 24-hour messaging window. They are used to initiate marketing, utility and authentication conversations with customers who have either not messaged you yet or have not done so in the last 24 hours.

Templates must be approved by WhatsApp before they can be used. If your business has completed business verification (opens in a new tab), they will be approved immediately. Otherwise, it may take up to 24 hours to receive a response.

Keep in mind that templates can also be deactivated based on customer engagements or feedback. If a template's quality rating drops or it it violates WhatsApp business messaging policy (opens in a new tab), it will be disabled. You will not be able to use it again until you resolve the quality issues.

For more information about the types of content allowed in templates, refer to the Message types section.

Manage templates

Using Infobip WhatsApp API (opens in a new tab) you can create, modify, send, retrieve or delete your templates.

Create a template

To create a template and upload media files during registration, use the following API request:

If you have completed business verification (opens in a new tab), the template is approved immediately. Otherwise, you will receive feedback about the template within 24 hours.

Modify a template

You can edit a template that is in APPROVED, REJECTED, or PAUSED status. Once edited, the template will be submitted for review and must be approved again before it can be sent to end users. To modify a template, use the following API request:

Send a template

When sending a template message, all parameters must match exactly to ensure that the template renders correctly on devices. The following rules apply:

• The number of placeholders in the template must match the number of parameters in the template data.
• The number of parameters specified in the API call must match the number of parameters in the template.

Additionally, you can send multiple template messages in a single API request, providing flexibility in your communication strategy.

If your WhatsApp messages do not reach your customers, you can enable the failover to SMS option for message templates (smsFailover). This ensures that the message will still be delivered through SMS if it fails on WhatsApp.

To send a template, use the following API request:

Retrieve a template

To retrieve a single template or all the templates, along with their statuses, use the following API request:

Delete a template

If you want to delete a template, be aware that this will also delete all registered languages. The template will be removed for all senders under the same WhatsApp Business Account (WABA). Messages sent before deletion will still attempt delivery for 30 days. You cannot reuse the template name for 30 days after deletion.

To delete a template, use the following API request:

Shorten and track template button URLs

In addition to supporting various message types, you can now shorten and track static and dynamic button URLs during template registration (creation) over the API (opens in a new tab).

To enable this feature, ensure that during template creation you:

• Choose and register (opens in a new tab) a custom domain.
• Activate URL shortening and tracking during template registration by adding the custom domain under the shorteningOptions object. You also need to define the dynamic URL separately within the template structure.

After the template is registered and you are ready to sent the template, define the dynamic part of the URL and add the custom domain under urlOptions (if you are using a static link, you do not need to define anything). Each link receives a dynamic ID when the message is sent, which allows Infobip to track customer clicks.

For more information on setting up URL shortening, refer to the URL shortening and tracking (opens in a new tab) page.

Sample request - Create a template with trackable shortened button URL

{
  "name": "media_template_with_dynamic_url_button",
  "language": "en",
  "category": "MARKETING",
  "structure": {
    "body": {
      "text": "bodycontent"
    },
    "buttons": [
        {
            "text": "visit website",
            "url": "https://www.infobip.com/{{1}}",
            "example": "https://www.infobip.com/docs",
            "type": "URL"
        }
    ],
    "shorteningOptions": {
                "customDomain": "client.customDomain.com"
            },
    "type": "MEDIA"
  },
}

The shorteningOptions object defines the URL shortening settings for the template, including the customDomain property, which is necessary for generating trackable shortened URLs. It is advisable not to modify this object outside the Infobip system, as this could result in errors.

Sample request - Send a template with a trackable shortened button URL

{
  "messages": [
    {
      "from": "441134960000",
      "to": "441134960001",
      "messageId": "a28dd97c-1ffb-4fcf-99f1-0b557ed381da",
      "content": {
        "templateName": "media_template_with_dynamic_url_button",
        "templateData": {
          "body": {
            "placeholders": []
          },
          "buttons": [
            {
              "type": "URL",
              "parameter": "docs"
            }
          ]
        },
        "language": "en"
      },
      "urlOptions": {
        "shortenUrl": true,
        "trackClicks": true,
        "trackingUrl": "https://client.customDomain.com/click-report",
        "customDomain": "client.customDomain.com"
      }
    }
  ]
}

Application and entity assignment

You can assign applicationID and entityID to templates during creation, editing, and retrieval, making the process of managing templates assigned to specific applications or entities flexible.

Sample request

{
  "name": "text_template",
  "language": "en",
  "category": "MARKETING",
  "allowCategoryChange": false,
  "structure": {
    "body": {
      "text": "body {{1}} content",
      "examples": [
        "example"
      ]
    },
    "type": "TEXT"
  }
 "platform": {
     "entityId": "test-entity",
     "applicationID": "test-application"
 }
}

To learn more about applications and entities, refer to the Application and entity management (opens in a new tab) article.

Event subscription

When using WhatsApp, subscriptions allow you to track and receive notifications for specific events during communication. These events, such as message delivery or user interactions, trigger notifications that are sent to your designated webhook, helping you monitor the progress and status of WhatsApp messages. Once a template is tied to a particular applicationID or entity ID, you can create a subscription to receive template updates.

For WhatsApp, you can track the following event types:

• DELIVERY: Indicates that the message was successfully delivered to the recipient.
• CLICK: Tracks when a user clicks on a button or link within the message.
• SEEN: Confirms that the recipients has seen the message.
• ACCOUNT_REGISTRATION: Notifies you when an account registration occurs.
• TEMPLATE_UPDATE: Provides updates when a message template changes.
• PAYMENT_STATUS: Monitors the status of payment-related messages.

To set up event notification, use the Subscriptions management API (opens in a new tab), where you can define subscription rules specifying which events to track and which webhooks should receive notifications. You can create multiple subscriptions to manage different events or route notifications to different webhooks.

For more details, refer to the Subscriptions management (opens in a new tab) page.

WhatsApp Flows

WhatsApp Flows is a dynamic, customizable feature that enables businesses to create structured, interactive customer journeys tailored to specific user segments. Flows can be adapted to meet various industry-specific needs, such as onboarding new users, offering product recommendations, or addressing support inquiries.

The first step in using WhatsApp Flows is to initiate a conversation with the customer using WhatsApp. This can be done through ads that click to WhatsApp and by using additional entry points, such as QR codes, websites, or in-app entry. Once the customer initiates the conversation, businesses can offer an in-store-like experience directly within WhatsApp, replicating website or channel journeys. Alternatively, businesses can proactively engage customers by sending template messages (opens in a new tab), which activate flows when the customer responds. This approach is especially useful for businesses that have customers opt-in for marketing or utility messages.

Flow components

WhatsApp Flows support various interactive elements, including text fields, radio buttons, checkboxes, and menus. These components can be combined to create interactive screens that guide customers through specific journeys, such as selecting product categories, attributes, and item details.

To quickly configure and preview a basic flow, you can use Meta's Playground (opens in a new tab), which provides a library of components, layouts, and connectors that can be combined with customer data. Additionally, the Flow Builder UI within WhatsApp Manager (opens in a new tab) allows flow design (you will need access to your WhatsApp Business Account to use this feature).

If you are using Flow Builder, after designing your flow, you can launch it using the API (opens in a new tab) or through Answers (opens in a new tab). However, if you are using Meta's Playground without access to your WhatsApp Business Account, you will need to create Flow templates (opens in a new tab) and add WhatsApp Flow JSON before launching your flow through either of those options.

Flow actions

WhatsApp Flow actions refer to a series of API requests that allow businesses to create, modify, and manage customer journeys within the WhatsApp business platform. Each action corresponds to a specific API endpoint, enabling you to create a flow, update its structure, or publish it for customer interactions. These API requests are essential for managing the lifecycle of your flows, from initial setup to handling responses. Below is an overview of the available API actions, guiding you through the process of setting up and maintaining your WhatsApp Flows efficiently.

Free-form messages

You can send free-form messages only within the permitted messaging window. To send messages outside this window, you must use WhatsApp-approved templates.

Before sending any WhatsApp messages, ensure you are familiar with messaging limitations and supported file types.

You can send the following free-form messages over API:

Inbound messages

When using WhatsApp for two-way communication, incoming messages are forwarded to your system in real-time.

To forward messages from the Infobip web interface to an API endpoint, ensure that the API endpoint has the relevant permissions. Use additional authorization headers to secure the connection.

Customers can send (opens in a new tab) you the following types of messages:

Download media

You can download inbound media sent by end users using the following API request:

Quotes

End users can quote messages to indicate that they are replying to that message.

Every incoming (opens in a new tab) message that is quoted by a customer has context, which consists of an ID. The ID consists of a messageId of the quoted message and a from parameter that indicates the sender number.

Quoting works only when replying to outbound (MT) messages. The system can only match replies to outbound messages and caches these for up to 4 days. If a reply references an inbound message or is older than 4 days, it may not be matched correctly.

Mark as read

The feature to mark incoming messages as read, indicating to your customers that their message has been acknowledged and that they can expect a response, is disabled by default. To enable it, please contact your account manager or reach out to our Support.

Once the feature is enabled, you can mark incoming messages as read using the following API request:

Delete media

Media that is sent by customers are cached for 30 days. After this period, the media is deleted automatically.

You can delete the media using the following API request:

Delivery reports

Use the API to track the performance of your communications. The following reports are forwarded to a defined endpoint:

• Delivery reports (opens in a new tab)
• Seen messages reports (opens in a new tab)

Alternatively, you can specify the endpoint for each message by using the notifyURL parameter. This allows you to customize where message status reports are sent for individual messages, overriding any global configuration settings.