WhatsApp API Message Types: What You Can Send and Receive

When you start building on the Cloud API, the first payload is easy: a text message to your own phone. Then the product team asks for invoice PDFs, a map pin to the store, a voice note from the doctor, and a way to react to customer photos, and you need to know which of those the API supports, what limits apply, and which need a template.

This is the reference we wished existed: every WhatsApp API message type you can send, every type your webhook can receive, the key limits Meta publishes as of October 2026, and the rule that decides when each one is allowed. Payload examples are minimal and correct for the current Cloud API.

One envelope, many types

Every send goes to the same endpoint, POST /PHONE_NUMBER_ID/messages, and every payload shares the same envelope. The type field names the message type, and an object with the same name holds the content:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919811122233",
  "type": "text",
  "text": { "preview_url": true, "body": "Here is your order page: https://example.com/orders/A-48213" }
}

Three details from Meta's docs save debugging later:

• Always include the plus sign and country code. If you leave out the +, the API prepends your business number's country code, which can send the message to the wrong person.
• A 200 response means accepted, not delivered. Delivery and read status arrive later in status webhooks.
• Order isn't guaranteed. Two messages sent a second apart can arrive swapped. If order matters, wait for the first one's delivered status before sending the next.

recipient_type is individual for one-to-one chats, or group for groups created through Meta's Groups API.

The window rule decides what you can send

Every type below except templates is a service message, and service messages can only be sent while a customer service window is open: within 24 hours of the customer's last message or call to you. Outside the window, only an approved template goes through, and the API returns error 131047 for anything else.

Templates can carry media headers, buttons, locations and carousels, so most rich formats have a template equivalent for business-initiated sends. Our guide to the 24-hour window covers the timing details.

Everything you can send

Two quieter details. Audio sent with "voice": true and an OGG/OPUS file shows as a voice note with transcription, and from March 17, 2026 Meta sends a played status the first time the customer plays it. Reactions only ever trigger a sent status, never delivered or read.

Sending media: id or link

For any media type you either upload the file first and send its id, or send a public link. Meta recommends uploaded IDs for reliability. When you use a link, the Cloud API caches the file for 10 minutes and reuses it for identical links; add a query string if the file changed.

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919811122233",
  "type": "document",
  "document": {
    "id": "MEDIA_ID",
    "filename": "invoice-INV-2291.pdf",
    "caption": "Invoice INV-2291 for October"
  }
}

The filename sets the icon and the name the customer sees, so always include the extension. Video is the common trap: Android WhatsApp doesn't play H.264 "High" profile files with B-frames, so encode with the Main or Baseline profile. Our guide to sending media on the WhatsApp API goes deeper on uploads and formats.

Replies, reactions, read receipts and typing

Four small payloads make a bot or integration feel human.

Quote a message by adding a context object to any send:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919811122233",
  "context": { "message_id": "wamid.INBOUND_ID" },
  "type": "text",
  "text": { "body": "Yes, that size is in stock. Want me to reserve one?" }
}

You can't send a reaction as a quoted reply, and quoting fails if the original was deleted or has moved to long-term storage, which typically happens after 30 days.

React to a customer's message:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919811122233",
  "type": "reaction",
  "reaction": { "message_id": "wamid.INBOUND_ID", "emoji": "👍" }
}

Mark as read and show typing. One call sends blue ticks and, optionally, a typing indicator that clears when you reply or after 25 seconds:

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.INBOUND_ID",
  "typing_indicator": { "type": "text" }
}

Marking a message as read also marks earlier messages in that chat as read. Meta's guidance is to show the typing indicator only if you are actually about to respond.

Everything your webhook can receive

Inbound messages arrive on the messages webhook field with a type that tells you how to parse them:

Status updates for your own messages arrive on the same field but in a statuses array instead of messages, so check which array is present before parsing.

Two inbound events are limited. Customer edits (within 15 minutes of sending) and deletions (within two days) only produce edit and revoke webhooks for numbers onboarded through coexistence with the WhatsApp Business app. On a standard Cloud API number you won't be told. Our explainer on editing and deleting messages covers what is and isn't possible.

Build your parser to store the user's business-scoped ID as well as the phone number. With WhatsApp usernames rolling out through 2026, webhooks won't always include a phone number.

Where Tenashi fits

The Cloud API's type list is broad because it is built for automated, structured messaging at scale. Many teams need a smaller set done well: text, files and photos, quoted replies, and every message visible to the whole team.

Tenashi links your existing number with a QR scan and works alongside your phone, not through Meta's platform. Its API sends text up to 4,096 characters, media (images up to 5 MB, video 16 MB, PDFs and Office files 25 MB) and quoted replies with replyTo, to a phone number or into any DM or WhatsApp group by conversationId. Inbound DMs and group messages arrive as message.received webhooks, and sends work without templates or a 24-hour window. What it doesn't do: buttons, lists, Flows, carousels, templates or a green tick. Sends are deliberately paced, new chats are capped per number each day, and WhatsApp can still ban numbers that spam. For high-volume alerts, stay on Cloud API; the complete guide to the WhatsApp API compares both routes.

Read the API docs · Get started

FAQ

Which WhatsApp message types need a template?

Only business-initiated messages sent outside the 24-hour customer service window need a template. Inside the window you can send text, media, location, contacts, reactions and interactive messages freely. Outside it, the API accepts only approved templates, which can include media headers, buttons, locations and carousels as part of the template itself.

What file size can I send through the WhatsApp Cloud API?

Per Meta's docs as of October 2026: images up to 5 MB (JPEG or PNG), video up to 16 MB (MP4), audio up to 16 MB, documents up to 100 MB (PDF, Office files and TXT), and stickers up to 100 KB static or 500 KB animated, in WebP only. Captions allow up to 1,024 characters.

Can the WhatsApp API send voice notes?

Yes. Send an audio message with voice set to true and an OGG file encoded with the OPUS codec. WhatsApp shows it as a voice note with the play icon (for files of 512 KB or less) and transcription if the user has it enabled. Other audio formats are sent as basic audio files instead.

How do I reply to a specific customer message?

Add a context object with the original message's ID to your send payload. WhatsApp then shows your reply quoting that message. This works for any message type except reactions. Quoting fails if the original message was deleted or has moved to long-term storage, which typically happens after 30 days.

Can I react to customer messages with an emoji?

Yes. Send a reaction message with the ID of the customer's message and the emoji. The target message must be under 30 days old, must exist in the chat and can't itself be a reaction; otherwise the reaction fails with error 131009. Reactions only generate a sent status, never delivered or read.

---

Know the types, respect the window, and most WhatsApp integrations become routine. For a team inbox on the number you already use, get started with Tenashi.