Skip to content

A glossary story9 chapters · 5 min read

WhatsApp Message Types

Every kind of message the WhatsApp Cloud API can send or receive, from text, media and location to interactive, reaction and template messages.

Also called: Message types · Cloud API message types · WhatsApp message formats

Reviewed

Follow along

Which types can you send, receive — and when?

9 / 9
Which types can you send, receive — and when?. 9 rows by 3 columns. Each cell is a button: activate it to read its note, and use the arrow keys to move between cells.
Business sendsArrives by webhookOutside 24h window
Text
Media
Location
Contacts
Interactive
Reaction
Template
System
Unsupported

Hover, tap or arrow-key through the cells — a dot in the corner means there is a note.

Unsupported by Arrives by webhook

YesLimited

Content the API cannot show; reply asking for another format.

Legend — press one to highlight its cells

Nine message families against three questions: can a business send it, how does it arrive by webhook, and is it allowed after the 24-hour window closes? Tap any cell for the detail.

Row 9 of 9. Unsupported × Arrives by webhook: Yes. Content the API cannot show; reply asking for another format.

Chapter 1 · The scenario

Example: One booking, six message types

A Kochi travel agency handles a houseboat booking in one thread. A utility template confirms the enquiry and reaches the customer outside any window; the customer replies, which opens one. The agent then sends a document message with the itinerary PDF, a location message with the jetty pin and a reply-button message asking 'Veg or non-veg lunch?'. The customer's tap arrives as type: interactive with a button_reply, and later a 👍 on the itinerary arrives as type: reaction pointing at the PDF's wamid. Each type did one job, and none needed a workaround.

— One booking, six message types

Chapter 2 · What is WhatsApp message types?

WhatsApp message types are the formats a business can send and receive through the WhatsApp Cloud API. Every outbound request to the messages endpoint sets a type — text, image, video, audio, document, sticker, location, contacts, interactive, reaction or template — and carries an object of the same name holding the content. Every inbound Messages Webhook works the same way in reverse, so one field tells your code what it is holding.

The types group into families. A Text Message is plain words, up to 4,096 characters. A Media Message sends a file by media ID or link: an Image Message, a video, an audio file or Voice Note, a Document Message or a sticker. A Location Message shares a pin and a Contacts Message a contact card. An Interactive Message collects a choice with reply buttons, a list, a URL button, a location request or a WhatsApp Flow. A Reaction Message pins an emoji to an earlier message, and a Message Template is the pre-approved format that can open a conversation.

Two rules cut across all of them. First, only a template may be sent when no 24-hour customer service window is open; every other type is free-form and needs the customer to have written in the last 24 hours. Second, the inbound side has types a business never sends: button when a customer taps a template's quick reply, interactive for reply-button, list and Flow answers, order for a cart, system for platform notices such as a number change (a System Message), and unsupported for content the API cannot represent, which has its own page as Unsupported Message Type.

Key takeaways

  • WhatsApp message types are the formats the Cloud API sends and receives, chosen by the type field of each message.
  • Businesses can send text, image, video, audio, document, sticker, location, contacts, interactive, reaction and template messages.
  • Only templates may be sent outside the 24-hour window; every other type needs the customer to have written in the last 24 hours.
  • Inbound webhooks add types a business never sends: button for template taps, order, system and unsupported.
  • Choose by job: text to talk, media to show, interactive to collect a choice, a template to start the conversation.

Chapter 3 · How it unfolds

How does WhatsApp message types work?

  1. Check whether a window is open

    If the customer has not written in the last 24 hours, the only option is a template. Inside the window, every type is available.

  2. Match the type to the job

    Text to answer, media to show or attach, location and contacts to share details, interactive to collect a choice, a reaction to acknowledge without adding a bubble.

  3. Set `type` and its object

    The request names the type and nests the content under the same key, for example "type": "document" with a document object holding the media ID, filename and caption.

  4. Branch inbound on `type`

    Handle every inbound type explicitly — including button, interactive, order, system and unsupported — and reply gracefully to anything you do not automate.

  5. Track each send's status

    Every outbound type returns a wamid and produces status webhooks. Reactions are the exception that proves the rule: they only ever report sent.

Chapter 4 · The facts

WhatsApp message types: key facts and limits

Outbound typestext, image, video, audio, document, sticker, location, contacts, interactive, reaction, template
Inbound-only typesbutton, order, system, unsupported
Interactive subtypesbutton, list, cta_url, location_request_message, flow, product, product_list and more
Outside the 24-hour windowTemplate messages only
Text bodyUp to 4,096 characters
Reaction statusessent only — no delivered or read
EndpointPOST /{PHONE_NUMBER_ID}/messages for every type

Chapter 5 · In code

WhatsApp message types in code

// m = one item of value.messages[] from a messages webhook
export function describeInbound(m) {
  switch (m.type) {
    case "text":
      return "text: " + m.text.body;
    case "image":
    case "video":
    case "audio":
    case "document":
    case "sticker":
      return m.type + " media " + m[m.type].id;          // download by media ID within 7 days
    case "location":
      return "pin " + m.location.latitude + "," + m.location.longitude;
    case "contacts":
      return "contact card: " + m.contacts[0].name.formatted_name;
    case "interactive": {
      const reply = m.interactive[m.interactive.type];     // button_reply, list_reply or nfm_reply
      return m.interactive.type + " " + (reply?.id ?? "flow response");
    }
    case "button":
      return "template quick reply: " + m.button.payload;
    case "reaction":
      return "reaction " + (m.reaction.emoji ?? "removed") + " on " + m.reaction.message_id;
    case "order":
      return "order with " + m.order.product_items.length + " items";
    case "system":
      return "system notice: " + m.system.type;           // e.g. user_changed_number
    default:
      return "unhandled type: " + m.type;                  // unsupported or new: log it, reply politely
  }
}

One branch per inbound type, with a default for unsupported and future types.

Chapter 6 · Where it goes wrong

Common mistakes with WhatsApp message types

  • No branch for system or unsupported

    Handlers written for text and buttons crash or stay silent on everything else. Add a default branch that logs the type and replies politely.

  • Sending a free-form type too late

    Any type except template fails with error 131047 once 24 hours have passed since the customer's last message. Check the window before choosing the type.

  • Using text where a structured type fits

    A typed 'yes' or a numbered list in plain text is hard to route. A reply button or list row returns a stable ID your code can trust.

  • Confusing `button` with `interactive`

    A tap on a template quick reply arrives as type: button with a payload; a tap on an interactive reply button arrives as type: interactive with button_reply.id. Handle both.

Chapter 7 · Why it matters

Why does WhatsApp message types matter?

Choosing the type is the first design decision in any WhatsApp journey, and the wrong choice shows up as friction or failure: a bot that asks people to type 'yes' when a reply button would do, seven options squeezed into three buttons, an invoice pasted as text instead of sent as a PDF, or a follow-up that fails because a free-form type went out after the window closed. Developers also need the full inbound list so the webhook handler has a branch for every type — including the system and unsupported messages that nobody plans for.

Chapter 8 · What good teams do

Best practices for WhatsApp message types

  • Keep a table of every inbound type your handler supports and test each one from a real phone.
  • Use reply buttons for two or three choices and a list message for up to ten.
  • Send invoices and tickets as documents with a clear filename rather than as bare links.
  • Acknowledge photos and documents with a reaction when a full reply is not needed.

Chapter 9 · WhatsApp Message Types FAQs

WhatsApp Message Types FAQs

What types of messages can the WhatsApp Business API send?+
The Cloud API can send text, image, video, audio, document, sticker, location, contacts, interactive, reaction and template messages. Interactive covers reply buttons, lists, URL buttons, location requests and Flows.
Which WhatsApp message type can start a conversation?+
Only a message template. A business may message someone who has not written in the last 24 hours only with an approved template; once they reply, every other type is allowed again.
What is an unsupported message type on WhatsApp?+
It is an inbound message the Cloud API cannot represent, delivered with type unsupported and an error. Detect it and ask the customer to resend the content in another format.
Is a reaction a separate WhatsApp message type?+
Yes. A reaction is its own type, holding the message_id it applies to and an emoji. It appears on the original bubble rather than as a new message, and only reports a sent status.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms