> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Inbound Message Webhook Examples

> Handle inbound WhatsApp message types with annotated payload examples.

<Note>For the exhaustive schema-derived catalog, see [all examples](/en/api-reference/guides/examples/webhook-examples/webhook-payload-examples).</Note>

## What it is

Handle inbound WhatsApp message types with annotated payload examples.

## Before you begin

* Create a public HTTPS endpoint in your application.
* Configure a YCloud webhook endpoint for the event types you need.
* Store the endpoint signing secret securely.
* Make event processing idempotent.

## How it works

YCloud sends an HTTP `POST` request when the event occurs. Verify the signature, durably record the event, return a `2xx` response, and process slow work asynchronously.

## Request

The scenarios below show requests delivered to your webhook URL. Treat the event `id` as the delivery identifier and use `type` to route the payload.

## Response

Return a `2xx` status after accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

<Note>For endpoint setup, signature validation, and retry behavior, see [Configure webhooks](/en/api-reference/guides/api-fundamentals/configure-webhooks).</Note>

## Inbound unsupported message

In this case, your webhook endpoint received an inbound unsupported message:

* `type` is set to `unsupported`.
* `errors` explains why the message is unsupported or unavailable.
* `unsupported.type` identifies the message category, such as `poll_creation`, `poll_update`, `edit`, or `pin`.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f8709b741c165b4342a714",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "errors": [
       {
          "code": 131051,
          "title": "Message type unknown",
          "message": "Message type unknown",
          "error_data": {
             "details": "Message type is currently not supported."
          }
       }
     ],
     "type": "unsupported",
     "unsupported": {
       "type": "poll_update"
     }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* Error `131051` with `Message type unknown` means that WhatsApp Cloud API does not support the message type.
* Error `131060` with `This message is currently unavailable.` means that WhatsApp could not provide the message content.
* `unsupported.type` identifies the general category. It does not contain the original message content.
* See [Unsupported messages in Inbox](/en/documentation/inbox/unsupported-messages-in-inbox) for a readable list of message types. See Meta's [unsupported messages webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/unsupported) for the current payload contract.

## Inbound Text message

In this case, your webhook endpoint received an inbound text message:

* Contains plain text that the user sent.
* Contains the mentioned message information in `context`.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* **Inbound messages are those sent from customers to your business phone numbers.**
* The `context` (optional) contains the mentioned message information, typically used to reply to a previous message sent by the user or your business.
  * `context.from` is the WhatsApp ID (phone number without the '+' prefix) of the user who sent the mentioned message.
  * `context.id` is the original ID of the mentioned message on WhatsApp’s platform, starting with `wamid.`.

## Inbound Text message triggered by click to WhatsApp Ads

In this case, your webhook endpoint received an inbound text message triggered by click to WhatsApp Ads:

* Contains plain.
* Contains information about the Ad.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkn26qar3nOB8md",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f872f6741c165b4342a751",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "OK"
    },
    "referral": {
      "source_url": "https://fb.me/xxx",
      "source_type": "ad",
      "source_id": "MEDIA-ID",
      "headline": "Chat with us",
      "media_type": "image",
      "image_url": "https://scontent.xx.fbcdn.net/v/t45.1600-4/xxx.jpg",
      "ctwa_clid": "feRgX__yiYtsI1HhjI2FRjyKInYlrU9cm9ml-Yl1MXp_fJy6Mwp-adZ-yLqOWX5CiZJYtjQERgKbAUetcwFXb_6FUYyOl9Kc6HFOBCd"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `referral` contains information about the Ad. See also [Ads that Click to WhatsApp](https://www.facebook.com/business/help/447934475640650).

## Inbound Image message

In this case, your webhook endpoint received an inbound image message:

* Contains an image URL.
* Contains caption to describe this image.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkv5wsCJItpaH01",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87878509703399f3fd3d0",
    "wamid": "wamid.HBgNODi...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "image",
    "image": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/592623615738103?sig=t%3D1677228150%2Cs%3D0aa4810392602afb2a91e28e54223c4c0e638bba298f19f07a6c3a2ccf6bdf1e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc4Nzg1MDk3MDMzOTlmM2ZkM2QwIiwibWltZVR5cGUiOiJpbWFnZS9qcGVnIiwic2hhMjU2IjoiTGVScFFKcS9oNEhUam1QOHNtRkpRRXdZQm5rR0JVdDFjeDRxekZjblVoUT0ifQ",
      "caption": "Go for a walk.",
      "id": "592623615738103",
      "sha256": "LeRpQJq/h4HTjmP8smFJQEwYBnkGBUt1cx4qzFcnUhQ=",
      "mime_type": "image/jpeg"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `image.link` can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within 30 days.

## Inbound Video message

In this case, your webhook endpoint received an inbound video message:

* Contains a video URL.
* Contains caption to describe this video.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkwhYtqMPmYdsN3",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87991741c165b4342a797",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "video",
    "video": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/919306472440541?sig=t%3D1677228430%2Cs%3D481b972ebc10e6b384f11274ba59e64b8c355543ea0b30e066b209361212abad&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODc5OTE3NDFjMTY1YjQzNDJhNzk3IiwibWltZVR5cGUiOiJ2aWRlby9tcDQiLCJzaGEyNTYiOiJ4RHpyU1R1YnZURm53MytzMVdJbEFiSUZLanpBS2k1dFZWaVFOVjhKV3BnPSJ9",
      "caption": "Go for a walk.",
      "id": "919306472440541",
      "sha256": "xDzrSTubvTFnw3+s1WIlAbIFKjzAKi5tVViQNV8JWpg=",
      "mime_type": "video/mp4"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `video.link` can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within 30 days.

## Inbound Audio message

In this case, your webhook endpoint received an inbound audio message:

* Contains an audio URL.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEl1TDAcquZUxzLn",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87cd3509703399f3fd3f2",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "audio",
    "audio": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/712063723747110?sig=t%3D1677229265%2Cs%3D5c6a65172ef8caa7bc969dacb831d6e15362fd7a5b6be7aa994aa83cdd15fc4e&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdjZDM1MDk3MDMzOTlmM2ZkM2YyIiwibWltZVR5cGUiOiJhdWRpby9tcGVnIiwic2hhMjU2IjoiQWtSWkR5dEx5MkkxSzFkT2VMNnBRT2pZblBwcGdqdFNDTzlNUStDcnkwUT0ifQ",
      "id": "712063723747110",
      "sha256": "AkRZDytLy2I1K1dOeL6pQOjYnPppgjtSCO9MQ+Cry0Q=",
      "mime_type": "audio/mpeg"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `audio.link` can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within 30 days.

## Inbound Document message

In this case, your webhook endpoint received an inbound document message:

* Contains a document URL.
* Contains caption to describe this document.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEkz3y7V6TCqgkbK",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f87b2e741c165b4342a79b",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "document",
    "document": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/948915536111569?sig=t%3D1677228843%2Cs%3D6eb8b4fc2796bae9f2e95702fbbd4d211cace96bc5c934a12d97704140e47a16&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmODdiMmU3NDFjMTY1YjQzNDJhNzliIiwibWltZVR5cGUiOiJhcHBsaWNhdGlvbi9wZGYiLCJzaGEyNTYiOiJFcHZDdHpUallkcTRleG1xc2ZHYmVpK1NUZ1h4VnFUQzJ0b2laODB2bW5rPSJ9",
      "caption": "PDF example",
      "filename": "sample.pdf",
      "id": "948915536111569",
      "sha256": "EpvCtzTjYdq4exmqsfGbei+STgXxVqTC2toiZ80vmnk=",
      "mime_type": "application/pdf"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `document.link` can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within 30 days.

## Inbound Sticker message

In this case, your webhook endpoint received an inbound sticker message:

* Contains a sticker URL.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc1678741c165b4342b38e",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "sticker",
    "sticker": {
      "link": "https://api.ycloud.com/v2/whatsapp/media/download/729118992174848?sig=t%3D1677465205%2Cs%3Dbc0d582e37cc701d5d090c1d11aa7eaed9b3f8e83925425a82d0aaab8b7da258&payload=eyJ3YWJhSWQiOiIxMDY2ODE3NzIxOTE4NzQiLCJpbmJvdW5kTWVzc2FnZUlkIjoiNjNmYzE2Nzg3NDFjMTY1YjQzNDJiMzhlIiwibWltZVR5cGUiOiJpbWFnZS93ZWJwIiwic2hhMjU2IjoiUlpFRWw1SFZXVDRTNkMwUG9PZ2pZQ1FWRFdzNWVzSU1Kc2pjRFlJODBaRT0ifQ",
      "id": "729118992174848",
      "sha256": "RZEEl5HVWT4S6C0PoOgjYCQVDWs5esIMJsjcDYI80ZE=",
      "mime_type": "image/webp"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `sticker.link` can be directly accessed in a few minutes for the convenience of the consumer, but you should always include an `X-API-Key` header to download this file within 30 days.

## Inbound Location message

In this case, your webhook endpoint received an inbound location message:

* Contains latitude and longitude of the place.
* Contains name, address, and URL of the place.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63fc18ae509703399f3fe000",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "location",
    "location": {
      "latitude": 1.40435,
      "longitude": 103.79304,
      "name": "Singapore Zoo",
      "address": "80 Mandai Lake Road Singapore 72",
      "url": "https://www.zoo.com.sg"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Inbound Contacts message

In this case, your webhook endpoint received an inbound contacts message:

* Contains one contact with addresses, birthday, emails, name, phones, and other contact fields.
* Contains `origin: contact_request` when the user shared the contact in response to a request-contact-info message.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "street": "<ADDRESS_STREET>",
            "city": "<ADDRESS_CITY>",
            "state": "<ADDRESS_STATE>",
            "zip": "<ADDRESS_ZIP>",
            "country": "<ADDRESS_COUNTRY>",
            "country_code": "<ADDRESS_COUNTRY_CODE>",
            "type": "HOME"
          }
        ],
        "birthday": "2001-01-01",
        "emails": [
          {
            "email": "joe@example.com",
            "type": "WORK"
          }
        ],
        "name": {
          "formatted_name": "<CONTACT_FORMATTED_NAME>",
          "first_name": "<CONTACT_FIRST_NAME>",
          "last_name": "<CONTACT_LAST_NAME>",
          "middle_name": "<CONTACT_MIDDLE_NAME>",
          "suffix": "<CONTACT_SUFFIX>",
          "prefix": "<CONTACT_PREFIX>"
        },
        "org": {
          "company": "<CONTACT_ORG_COMPANY>",
          "department": "<CONTACT_ORG_DEPARTMENT>",
          "title": "<CONTACT_ORG_TITLE>"
        },
        "phones": [
          {
            "phone": "+447901614024",
            "wa_id": "447901614024",
            "type": "WORK"
          }
        ],
        "origin": "contact_request",
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Inbound Reaction message

In this case, your webhook endpoint received an inbound reaction message:

* Contains the message ID that the user reacts to.
* Contains the emoji.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `emoji` is present when the user reacts to a message with an emoji. If not, it indicates that the user removed the emoji on a message.

## Inbound Template Button message

In this case, your webhook endpoint received an inbound template button message:

* Contains the button `text` of the template you used when sending a template message.
* Contains the button `payload` that you provided when sending a template message.
* Contains the wamid (`context.wamid`) of the template message you sent.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "button",
    "button": {
      "payload": "more_about_marketing_friday",
      "text": "Learn more"
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Inbound Interactive List Reply message

In this case, your webhook endpoint received an inbound Interactive List Reply message:

* The `interactive` field contains the list reply that the user clicked on an interactive message you previously sent.
* The `context` field contains information about the interactive message you previously sent to the user.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-messaging-interactivelist-select.png) Click the button to select one item.

![](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-listreply.png) The recipient replies to your message by selecting one of the items in your previously sent interactive message.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f73942741c165b43429f86",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "<LIST_SECTION_2_ROW_1_ID>",
        "title": "<SECTION_2_ROW_1_TITLE>",
        "description": "<SECTION_2_ROW_1_DESC>"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `context` contains information about the interactive message you previously sent.
  * `context.from` is the WhatsApp ID (phone number without the '+' prefix) of who sent the interactive message.
  * `context.id` is the original message ID on WhatsApp’s platform, starting with `wamid.`.

## Inbound Interactive Button Reply message

In this case, your webhook endpoint received an inbound Interactive Button Reply message:

* The `interactive` field contains the button reply that the user clicked on an interactive message you previously sent.
* The `context` field contains information about the interactive message you previously sent to the user.

![example-inboundmessage-buttonreply.png](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-buttonreply.png)

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "<UNIQUE_BUTTON_ID_2>",
        "title": "<BUTTON_TITLE_2>"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* The `context` contains information about the interactive message you previously sent.
  * `context.from` is the WhatsApp ID (phone number without the '+' prefix) of who sent the interactive message.
  * `context.id` is the original message ID on WhatsApp’s platform, starting with `wamid.`.

## Inbound Interactive Flow Response message

Upon flow completion a response message will be sent to the WhatsApp chat. You will receive it in the same way as you receive all other messages from the user - via message webhook. `response_json` field will contain flow-specific data.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "flow",
        "body": "Sent",
        "response_json": "{\"flow_token\": \"<FLOW_TOKEN>\", \"optional_param1\": \"<value1>\", \"optional_param2\": \"<value2>\"}"
      }
    },
    "context": {
      "from": "447901614024",
      "id": "wamid.HBgNODr..."
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* `interactive.type` is always `nfm_reply`. `interactive.name` is always `flow`. `interactive.body` is always `Sent`.
* `interactive.response_json` is flow-specific data. The structure is either defined in flow JSON (see [Complete action](https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson#complete-action)) or, if flow is using an endpoint, controlled by endpoint (see Final Response Payload in [Data Exchange Request](https://developers.facebook.com/docs/whatsapp/flows/guides/implementingyourflowendpoint#data_exchange_request)). Parse the `interactive.response_json` JSON string to a JSON object, where its values' data type can be various. Typically, the values are plain text, except:
  * When it originates from a [CheckboxGroup](https://developers.facebook.com/docs/whatsapp/flows/reference/components#checkbox) component, the value is a list of strings.
  * When it originates from an [OptIn](https://developers.facebook.com/docs/whatsapp/flows/reference/components#opt) component, the value is a boolean, that is `true` or `false`. Currently, if present, the value must be `true` since there will be no such key included in the `response_json` if the user didn't choose opt in.
  * When it originates from a [DatePicker](https://developers.facebook.com/docs/whatsapp/flows/reference/components#dp) component, the value is a string representing Unix timestamp in milliseconds, such as `"1725936737548"`(i.e., 2024-09-10T02:52:17.548Z). Since [Flow JSON version 5.0](https://developers.facebook.com/docs/whatsapp/flows/changelogs#august-13th--2024-release) , dates will be set in "yyyy-MM-dd" format, which makes the values unrelated to time zones.
* To send a message with a Flow, see [Flow template message](/en/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#flow-template-message), and [Interactive Flow message](/en/api-reference/guides/examples/api-examples/whatsapp-messaging-examples#interactive-flow-message).

## Inbound System message

In this case, your webhook endpoint received an inbound system message:

* The `type` is set to `system`, and `system.type` is set to `user_changed_number`.
* A user changes their phone number on WhatsApp, and `wa_id` is the new WhatsApp ID (phone number without the `+` prefix).
* `user_id` is the new BSUID. `parent_user_id` is included only when parent BSUIDs are enabled.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "system",
    "system": {
      "body": "User A changed from 123456789 to 987654321",
      "wa_id": "987654321",
      "user_id": "US.13491208655302741919",
      "parent_user_id": "US.ENT.11815799212886844831",
      "type": "user_changed_number"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Inbound Order message

In this case, your webhook endpoint received an inbound order message when a customer adds one or more products to their cart and submits an order:

* Contains information about the product ordered.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "order",
    "order": {
      "catalog_id": "the-catalog_id",
      "product_items": [
        {
          "product_retailer_id": "the-product-SKU-identifier",
          "quantity": "number-of-item",
          "item_price": "unitary-price-of-item",
          "currency": "price-currency"
        }
      ],
      "text": "text-message-sent-along-with-the-order"
    },
    "context": {
      "from": "16315551234",
      "id": "wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

Route the event by `type`, deduplicate it by `id`, and move slow or failure-prone work to an asynchronous processor.

## Inbound Product Inquiry message

In this case, your webhook endpoint received an inbound text message when a customer inquiries a product:

* Contains information about the product.

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "text",
    "text": {
      "body": "Can I get this in another color?"
    },
    "context": {
      "referred_product": {
        "catalog_id": "catalog-ID",
        "product_retailer_id": "product-ID"
      }
    }
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* A Product Inquiry Message is received when a user is asking for more information about a specific product. These can be received in two scenarios:
  * When a customer replies to [Single or Multi-Product Messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/share-products).
  * When a customer accesses a business’ catalog through another entry point, navigates to a Product Details Page, and clicks Message Business about this Product.

## Inbound Request Welcome message

You can be notified by webhook whenever a WhatsApp user opens a chat with you for the first time. This can be useful if you want to reply to these users with a special welcome message of your own design.

If you enable this feature and a user opens a chat, typically when a user taps a [universal link](https://faq.whatsapp.com/425247423114725) (**wa.me** or **api.whatsapp.com** links), the WhatsApp client checks for an existing message thread between the user and your business phone number. If there is none, the client triggers a `request_welcome` webhook. You can then respond to the user with your own welcome message.

![example-inboundmessage-welcomemessage](https://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/api-docs/sample/example-inboundmessage-welcomemessage.png)

### Request

```shell theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eF6mVJUj5OWfKXMD",
  "type": "whatsapp.inbound_message.received",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappInboundMessage": {
    "id": "63f71fb8741c165b434292fb",
    "wamid": "wamid.HBgNOD...",
    "wabaId": "WABA-ID",
    "from": "CUSTOMER-PHONE-NUMBER",
    "fromUserId" : "US.13491208655302741918",
    "fromParentUserId": "US.ENT.11815799212886844830",
    "customerProfile": {
      "name": "Joe",
      "username": "@JoeJoe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "request_welcome"
  }
}'
```

### Response

Acknowledge the delivery after durably accepting the event.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 200 OK
```

### Explanation

* To enable this feature for a phone number, navigate to Meta **WhatsApp Manager** > **Phone Numbers** > **Settings** > **Automations**.
* To test `request_welcome` message, if you already have a chat thread going with the business phone number, you must first delete the chat.
* This feature only triggers an inbound `request_welcome` message, and does not reply any message automatically. It's up to you whether to reply a welcome message.

<br />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.