WhatsApp Inbound Message Webhook Examples

🚧
Prerequisites
Make sure that your webhook endpoint is listening for whatsapp.inbound_message.received events. See also Configure Webhooks, Retrieve a webhook endpoint API.

Inbound Text message with mention

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.

Note:

Inbound messages are those sent from customers to your business phone numbers.
The context 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 mentioned message on WhatsApp’s platform.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-text' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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",
        "customerProfile": {
            "name": "Joe"
        },
        "to": "BUSINESS-PHONE-NUMBER",
        "sendTime": "2023-02-22T12:00:00.000Z",
        "type": "text",
        "text": {
            "body": "OK"
        },
        "context": {
            "from": "447901614024",
            "id": "wamid.HBgNODr..."
        }
    }
}'

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.

Note:

The referral contains information about the Ad. See also Ads that Click to WhatsApp.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-textfromad' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Image message

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

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

Note:

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 a month.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-image' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Video message

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

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

Note:

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 a month.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-video' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Audio message

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

Contains an audio URL.

Note:

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 a month.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-audio' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Document message

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

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

Note:

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 a month.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-document' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Sticker message

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

Contains a sticker URL.

Note:

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 a month.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-sticker' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

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.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-location' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Contacts message

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

Contains 1 contact with addresses, birthday, emails, name, phones, etc.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-contacts' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "contactsF",
    "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": "[email protected]",
            "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"
          }
        ],
        "urls": [
          {
            "url": "<CONTACT_URL>",
            "type": "WORK"
          }
        ]
      }
    ]
  }
}'

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.

Note:

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.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-reaction' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "reaction",
    "reaction": {
      "message_id": "wamid.HBgNODYxNTcwMDA3NzE0NRUCABIYIEYyMzY3OUJBMzY2RkFFQkRDQjYyQ0Q5RDE1QjA2RUYyAA==",
      "emoji": "👍"
    }
  }
}'

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.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-button' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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..."
    }
  }
}'

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.

Note:

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.

Click the button to select one item.

The recipient replies to your message by selecting one of the items in your previously sent interactive message.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-listreply' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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..."
    }
  }
}'

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.

Note:

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.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-buttonreply' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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..."
    }
  }
}'

Inbound Unsupported message

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

type is set to unsupported.
Contains errors to describe why this message is unsupported.

Note:

This event occurs when the user sends an unsupported message to you. For example:
- If a user deletes a message (for everyone, not for me only), you will receive a webhook with an error code for an unsupported message type.
- Poll messages are not supported.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-unsupported' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "to": "BUSINESS-PHONE-NUMBER",
    "sendTime": "2023-02-22T12:00:00.000Z",
    "type": "unsupported",
    "errors": [
      {
        "code": "131051",
        "title": "Message type is currently not supported."
      }
    ]
  }
}'

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 the wa_id is the new WhatsApp ID (phone number without the '+' prefix).

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-system' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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",
      "type": "user_changed_number"
    }
  }
}'

Inbound Order message

In this case, your webhook endpoint received an inbound order message when a customer places an order:

Contains information about the product ordered.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-order' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
    }
  }
}'

Inbound Product Enquiry message

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

Contains information about the product.

Note:

A Product Enquiry 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.
- When a customer accesses a business’ catalog through another entry point, navigates to a Product Details Page, and clicks Message Business about this Product.

Code sample:

curl --location --request POST 'https://YOUR-WEBHOOK-ENDPOINT-URL/example-inboundmessage-productenquiry' \
--header 'X-API-Key: YOUR-API-KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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",
    "customerProfile": {
      "name": "Joe"
    },
    "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"
      }
    }
  }
}'

🚧Prerequisites

Inbound Text message with mention

Inbound Text message triggered by click to WhatsApp Ads

Inbound Image message

Inbound Video message

Inbound Audio message

Inbound Document message

Inbound Sticker message

Inbound Location message

Inbound Contacts message

Inbound Reaction message

Inbound Template Button message

Inbound Interactive List Reply message

Inbound Interactive Button Reply message

Inbound Unsupported message

Inbound System message

Inbound Order message

Inbound Product Enquiry message

🚧
Prerequisites