# 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": ""
     }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lipachat.com/api/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.