WhatsApp inbound messages
When using WhatsApp for two-way communication, inbound messages are delivered to your webhook endpoint in real time. These messages represent user-initiated actions such as replies, media uploads, or button interactions.
Receive inbound messages
To receive inbound messages using the API:
- Your webhook must be configured and accessible.
- You must grant permission to the Infobip platform.
- Use authorization headers to secure your endpoint.
Messages are delivered using the HTTPS POST requests with a JSON payload.
Inbound message types
WhatsApp supports the following inbound message types:
| Message type | Description |
|---|---|
| Text | Standard user-sent messages |
| Image / Video / Audio | Media files sent from the user's device |
| Voice | Recorded voice notes |
| Document | Uploaded files (for example, .pdf, .docx, .xlsx) |
| Location | Static location pins |
| Contact | vCard-format contact cards |
| Button reply | Quick reply button interaction |
| List reply | List item selected by the user |
| Order message | Order interaction related to WhatsApp Payments |
| Sticker / Other media | Other media types, such as stickers or unsupported formats |
Media can be downloaded or deleted within 7 days using the WhatsApp API.
Manage inbound media
Inbound media files sent by users, such as images, videos, audio, or documents, are stored temporarily and can be managed through the API.
- Media is stored for up to 7 days.
- During this time, you can download or delete media as needed.
- After 7 days, media is deleted automatically and becomes inaccessible.
Quoted messages [#quoted-messages-inbound-messages]
Users can quote a previous message to indicate a reply context.
When a user replies to a specific message, the inbound payload includes a context object. This object contains:
id: ID of the quoted messagefrom: the WhatsApp ID of the sender of the quoted message
Quoting is only supported for messages sent by your business (outbound messages). Replies to inbound messages or messages older than 4 days may not be resolved.
Referral messages [#referral-inbound-messages]
When a user clicks a Click-to-WhatsApp ad or post on Facebook on Instagram and sends a message, WhatsApp includes referral metadata in the message payload.
This includes:
- Source type (ad or organic post)
- Facebook ad ID
- Ad URL, headline, and body
- Unique per-click identifier
- Media info (if applicable)
Product context [#product-question-inbound-messages]
When a user replies to a product or multi-product message, WhatsApp includes product metadata in the inbound message. This helps you identify:
- Product ID
- Product name
- Catalog ID
- Thumbnail or image data
Mark messages as read [#additional-functionality-inbound-messages]
The mark-as-read feature allows you to programmatically mark an inbound message as acknowledged. This updates the message status in the user's WhatsApp client.
This feature is disabled by default. To enable it, contact your account manager or Support.
Once enabled, use the Mark as read API request to mark inbound messages as read.