> For the complete documentation index, see [llms.txt](https://docs.lipachat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lipachat.com/api/webhooks.md).

# Webhooks

## Overview

This section explains how to set up webhook endpoints to receive:

* Inbound Messages (text, media, interactive, etc.)
* Optional Message Status Updates (e.g., delivered, read, failed)

Having both webhooks enabled ensures you can process incoming customer messages and track the lifecycle of messages you send.

## Inbound Message Webhooks

#### Configuring the Inbound Webhook

{% stepper %}
{% step %}
**Navigate to Settings**

In your application or developer dashboard, set the **Inbound Webhook URL** (e.g., `https://example.com/webhook/whatsapp/inbound`).
{% endstep %}

{% step %}
**Receive Webhooks**

All incoming WhatsApp messages (new messages and replies) will trigger a POST to your inbound webhook URL.
{% endstep %}
{% endstepper %}

#### Supported Inbound Message Types

Inbound messages can contain various content types:

* Text
* Media (image, video, audio, document)
* Sticker
* Location
* Contact
* Interactive
  * List response
  * Button response

Check the `type` field in the webhook payload to determine what the user has sent.

#### Sample Webhooks Incoming Messages

{% tabs %}
{% tab title="Text" %}

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "TEXT",
     "text": "Text Content"
}
```

{% endtab %}

{% tab title="Image" %}

```json
{
     "messageId": "c94ced08-5f40-46b7-a88d-7d4fbe113fe9",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "IMAGE",
     "image": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Video" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "VIDEO",
     "video": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Audio" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "AUDIO",
     "audio": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}

{% tab title="Document" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "DOCUMENT",
     "document": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Location" %}

```json
{
     "to": "",
     "from": "",
     "type": "LOCATION",
     "location": {
          "name": "",
          "address": "Kiambu Road",
          "latitude": "",
          "longitude": ""
     },
     "messageId": "WA_MESSAGE_ID",
     "profileName": "CUSTOMER_NAME"
}
```

{% endtab %}

{% tab title="Contact" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "CONTACTS",
     "contacts": [
          {
               "addresses": null,
               "birthday": null,
               "emails": null,
               "name": {
                    "suffix": null,
                    "prefix": null,
                    "formatted_name": "",
                    "first_name": "",
                    "last_name": "",
                    "middle_name": null
               },
               "org": null,
               "phones": [
                    {
                         "phone": "PHONE NUMBER",
                         "type": "MOBILE",
                         "wa_id": "PHONE NUMBER"
                    }
               ],
               "urls": null
          }
     ]
}
```

{% endtab %}

{% tab title="Sticker" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "STICKER",
     "sticker": {
          "caption": null,
          "url": "HTTPS URL"
     }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Interactive List" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "list_reply",
          "list_reply": {
               "id": "NAIROBI_WATER",
               "title": "Nairobi Water"
          }
     }
}
```

{% endtab %}

{% tab title="Interactive Buttons" %}

```json
{
     "messageId": "WA_MESSAGE_ID",
     "from": "CUSTOMER_PHONE_NUMBER",
     "to": "WHATSAPP_NUMBER",
     "profileName": "CUSTOMER_NAME",
     "type": "INTERACTIVE",
     "interactive": {
          "type": "button_reply",
          "button_reply": {
               "id": "1",
               "title": "YES"
          }
     }
}
```

{% endtab %}
{% endtabs %}

## Message Status Callbacks

#### What Are Status Callbacks?

When you send a message or manage a template, our service can notify your application of changes via HTTP POST requests to a separate webhook URL. There are two main categories:

* Message Delivery Status: Track whether your outbound message was sent, delivered, read, or failed.
* Template Status: Track changes in your message template approval status (e.g., approved, rejected, paused).

#### Configuring Status Callbacks

 Navigate to Settings: Set the Status Callback URL (e.g.,`https://example.com/webhook/whatsapp/status`).

Possible status values include:

* SENT
* DELIVERED
* READ
* DELETED
* FAILED

#### Sample JSON: Message Delivery Status

```json
{
     "event": "MESSAGE_STATUS",
     "messageStatus": {
          "waId": "",
          "messageId": "",
          "conversationId": "",
          "status": "DELIVERED",
          "statusDesc": "",
          "timestamp": 1749062767
     }
}
```

For outbound messages, the <mark style="color:blue;">**messageId**</mark> corresponds to the ID included in the request

## Template Status Updates

We also send callbacks when your WhatsApp message templates change status. Possible status values include:

* **APPROVED**: The template is approved and ready for use.
* **REJECTED**: The template has been denied—check for policy violations.
* **PAUSED**: The template is temporarily suspended, often pending manual review.

statusDescription will contain the reason why a template has been rejected or paused.

**Sample JSON: Template Status Update**

```json
{
     "event": "TEMPLATE_STATUS",
     "templateStatus": {
          "status": "APPROVED",
          "templateId": "",
          "templateName": "",
          "statusDescription": ""
     }
}
```