Documentazione
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

Unsupported WhatsApp message types

WhatsApp carries content Bird's API does not model, from emoji reactions to catalog orders. Rather than dropping such a message or delivering it empty, Bird records it with an unsupported arm that names the WhatsApp content type. The message is visible in the WhatsApp log and reaches your webhook like any other.

What an unsupported message carries

unsupported.type carries WhatsApp's own type string for what arrived, and it is the only content on the message. The envelope around it is unchanged:
Esempio di codice
{
  "id": "wam_01kyh0w4ujnz2x8p1s5dci0vlg",
  "direction": "inbound",
  "from": { "phone_number": "+14155550100" },
  "to": { "phone_number": "+13124495569" },
  "status": "received",
  "unsupported": { "type": "reaction" },
  "created_at": "2026-08-25T09:31:20Z"
}
typeWhat the contact sent
reactionAn emoji reaction on one of your messages
interactiveInteractive content whose reply shape the API could not read as a tap
buttonA button tap the API could not read as a reply
orderA cart or order placed from a product catalog
systemA system notice about the conversation, such as a contact changing their phone number
unsupportedWhatsApp's own unsupported type, for a message its own clients cannot render
unsupported is not a placeholder in that table. WhatsApp reports a content type of its own by that name when one of its clients sends something the others cannot display, and that arrives as this value.
The list is open. WhatsApp adds content types over time, so treat a type you do not recognize as a future type rather than an error: log it and move on rather than failing the read.

The webhook payload

whatsapp.received fires for an unsupported message too, carrying the same arm:
Esempio di codice
{
  "type": "whatsapp.received",
  "timestamp": "2026-08-25T09:31:20.774Z",
  "data": {
    "whatsapp_id": "wam_01kyh0w4ujnz2x8p1s5dci0vlg",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
    "direction": "inbound",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "unsupported": { "type": "reaction" },
    "tags": null,
    "metadata": null
  }
}
An endpoint that switches on the content field it finds should have a default branch, and this arm is what lands in it. Acknowledge the webhook with a 2xx either way: retrying it changes nothing, since the content will not become modelled between attempts.

What an unsupported message still does

The message counts as an inbound message in every way that does not depend on its content:
  • It resets the customer service window to a fresh 24 hours, so a reaction to one of your messages reopens free-form replies.
  • It appears in the message list and the WhatsApp log, with its type shown rather than a blank row.
  • It is never charged. No inbound message is priced.
What you cannot do is read the content. A reaction does not tell you which emoji or which message it was placed on, and an order does not carry the cart. Where that detail matters, ask the contact in words, or use a reply button or list menu so the answer arrives on a modelled arm you can act on.

Things to watch

  • Do not treat the arm as an error. The message was received successfully; only its content is unmodelled. Alerting on it means alerting every time a contact reacts with a thumbs up.
  • A system type can mean the contact changed number. Meta documents a phone-number change as one of the events that raises a system message, and it regenerates the contact's business-scoped user ID at the same time. The arm names the type and nothing else, so treat it as a prompt to re-establish who you are talking to.
  • Store the type verbatim. A future type resolves to a name you have no code for yet, and keeping the raw value is what lets you find those messages once you do.

Next steps