Inbox
Receive and reply to WhatsApp direct messages
Inbox
Included — Inbox (DMs, comments, reviews) is bundled with every paid account on the Usage plan.
All WhatsApp features (broadcasts, sequences, DM conversations) are included with the Usage plan. WhatsApp DM conversations are available through the unified Inbox API, which aggregates conversations across all supported platforms.
Direct Messages
| Feature | Supported |
|---|---|
| List conversations | Yes |
| Fetch messages | Yes |
| Send text messages | Yes |
| Send attachments | Yes (images, videos, documents, audio) |
| Send voice notes | Yes — pass voiceNote: true on an audio attachment to render as a true voice message (waveform, autoplay, profile-picture bubble). The file must be .ogg encoded with the OPUS codec (mono); dashboard mic recordings are transcoded server-side. Omitting the flag sends as a basic audio attachment (still shows a microphone icon when the codec is Opus, but without the voice-message UI). |
| Send interactive messages | Yes (reply buttons, list, CTA URL, flow) via the interactive / buttons fields |
| Send commerce messages | Yes (single product, product list, catalog, carousel) via interactive, see Commerce Messages |
| Send location & contact cards | Yes via the location / contacts fields |
| Reply to a specific message | Yes via replyTo (the quoted message's platformMessageId) |
| React to a message | Yes (emoji) via Add message reaction |
| Typing indicator | Yes via Send typing indicator |
| Archive/unarchive | Yes |
Attachment Support
| Type | Supported | Max Size |
|---|---|---|
| Images | Yes | 5 MB |
| Videos | Yes | 16 MB |
| Documents | Yes | 100 MB |
| Audio | Yes | 16 MB |
Commerce Messages
Send products from your Meta catalog and rich carousels with POST /v1/inbox/conversations/{conversationId}/messages using the interactive field. Like all interactive messages, these are session messages: they require an open 24-hour customer service window.
Product, product list, catalog, and product-carousel messages need a Meta catalog connected to your WABA in Commerce Manager. Media carousels need no catalog.
Single product card. body is optional; the product image is the header.
{
"accountId": "abc123",
"interactive": {
"type": "product",
"body": {"text": "Back in stock!"},
"action": {
"catalog_id": "194836987003835",
"product_retailer_id": "sku-blue-tshirt"
}
}
}Up to 30 products in up to 10 sections. A text header is required.
{
"accountId": "abc123",
"interactive": {
"type": "product_list",
"header": {"type": "text", "text": "Our summer picks"},
"body": {"text": "Tap to browse"},
"action": {
"catalog_id": "194836987003835",
"sections": [
{
"title": "T-shirts",
"product_items": [
{"product_retailer_id": "sku-blue-tshirt"},
{"product_retailer_id": "sku-red-tshirt"}
]
}
]
}
}
}A "View catalog" button. The thumbnail is optional (defaults to your catalog's first item), and action may be omitted entirely.
{
"accountId": "abc123",
"interactive": {
"type": "catalog_message",
"body": {"text": "Browse our full catalog"},
"action": {
"name": "catalog_message",
"parameters": {"thumbnail_product_retailer_id": "sku-blue-tshirt"}
}
}
}2 to 10 swipeable cards. Media cards carry an image or video header plus a CTA URL button (no catalog needed); product cards reference catalog items and must all share one catalog_id. Cards must be all product or all media. card_index is filled sequentially when omitted.
{
"accountId": "abc123",
"interactive": {
"type": "carousel",
"body": {"text": "New arrivals this week"},
"action": {
"cards": [
{
"card_index": 0,
"type": "cta_url",
"header": {"type": "image", "image": {"link": "https://example.com/a.jpg"}},
"body": {"text": "The classic"},
"action": {"name": "cta_url", "parameters": {"display_text": "Shop now", "url": "https://example.com/a"}}
},
{
"card_index": 1,
"type": "cta_url",
"header": {"type": "image", "image": {"link": "https://example.com/b.jpg"}},
"action": {"name": "cta_url", "parameters": {"display_text": "Shop now", "url": "https://example.com/b"}}
}
]
}
}
}Receiving orders: when a customer submits a cart from any commerce message, message.received fires with metadata.order (catalog_id, optional customer note in text, and product_items with product_retailer_id, quantity, item_price, currency). When a customer taps "Message business" on a product, their message carries metadata.referredProduct with the catalog_id and product_retailer_id they asked about. Both render natively in the dashboard inbox, and the composer's interactive drawer can send products, catalogs, and media carousels directly.
Webhooks
WhatsApp emits the full set of message + delivery lifecycle webhooks:
| Event | When it fires |
|---|---|
message.received | New incoming WhatsApp message |
message.sent | Outgoing message is sent |
message.delivered | Outgoing message is delivered to the recipient |
message.read | Recipient reads an outgoing message |
message.failed | Outgoing message fails to deliver, the payload error object carries the Cloud API error code (e.g. 131026 recipient phone not reachable) |
message.deleted | The business deletes a previously-sent outgoing message via DELETE /v1/inbox/conversations/{conversationId}/messages/{messageId} |
reaction.received | A participant adds or removes an emoji reaction. reaction.emoji is empty on removal (the Cloud API does not report which emoji was removed) |
Subscribe via Create webhook settings. See the Webhooks page for payload details.
Note: WhatsApp Cloud API does not expose incoming-message edits or recipient-side unsends, so message.edited and incoming-side message.deleted are not emitted. These are platform limitations.
Notes
- 24-hour window: Free-form messages only within 24 hours of customer's last message
- Templates: Required to initiate or re-initiate conversations outside the window
- Delivery tracking: Messages have sent/delivered/read status updates via webhooks
See Inbox API Reference for endpoint details.