WhatsApp message types

WhatsApp gives you a fixed set of message types to build a conversation from. Some are plain — text, an image, a document. Others are interactive: reply buttons, scrollable lists, call-to-action links, and multi-screen flows that open inside the chat. Knowing what each one looks like, and what it’s good for, is most of what it takes to design a conversation that feels natural. These are platform building blocks — they exist on WhatsApp itself, whatever tool you use to send them. The code samples on this page show how each maps to a function in a Paige bot, so you can use them directly, but the shape of each message type is the same everywhere.

Interactive messages — buttons, list menus, URL buttons, and flows — are billed as “interactive” messages by WhatsApp. Plain text and media messages are billed as regular messages. Check the Meta pricing page for the current rates for your region.

Message types in detail

Send a plain text message. Supports newlines using \n.

await sendText(conversationId, to, "Hello! How can I help you today?");

Parameters:

conversationId — the conversation ID from your database
to — the recipient’s phone number (e.g. "27821234567")
text — the message body; use \n for line breaks

Text messages are the simplest message type and work in all WhatsApp clients. Use them for confirmations, plain responses, and any message that does not need user input.

Send up to three quick-reply buttons below a message body. Each button has an id (used in your code logic) and a title (shown to the user).

await sendInteractiveButtons(
  conversationId,
  to,
  "What would you like to do?",
  [
    { id: "book_demo", title: "Book a demo" },
    { id: "get_support", title: "Get support" },
    { id: "learn_more", title: "Learn more" },
  ]
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
bodyText — the message text shown above the buttons
buttons — array of up to 3 button objects, each with id and title
botNumber — optional. Your bot’s own WhatsApp number, recorded against the logged message. Your handler already has it; pass null if you don’t.
header — optional. See Headers and footers.
footer — optional. Small print under the message.

When the user taps a button, your webhook receives an interactive message with message.interactive.button_reply.id set to the button’s id. Use that value in your state handler to branch the conversation.

Button titles are limited to 20 characters. Button IDs are limited to 256 characters and must be unique per message.

Send a list menu — a scrollable list of options the user selects from by tapping “View Options”. Lists support more items than buttons and work well for menus with 4 or more choices.

await sendMenu(
  conversationId,
  to,
  "Choose a service:",
  [
    { id: "service_web", title: "Web design", description: "Custom websites" },
    { id: "service_seo", title: "SEO", description: "Search optimisation" },
    { id: "service_ads", title: "Paid ads", description: "Google & Meta ads" },
  ]
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
bodyText — the message text shown above the list button
menuRows — array of row objects, each with id, title, and optional description
botNumber — optional. Your bot’s own WhatsApp number, recorded against the logged message. Pass null if you don’t have it.
header — optional. See Headers and footers.
footer — optional. Small print under the message.

When the user selects a row, your webhook receives message.interactive.list_reply.id set to the row’s id.

Send a call-to-action button that opens a URL when tapped. Use this for links to web pages, booking portals, payment links, or any external resource.

await sendURLButton(
  conversationId,
  to,
  "Your booking is confirmed. View the details below.",
  "View booking",
  "https://example.com/bookings/abc123"
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
bodyText — the message text shown above the button
buttonText — the button label
url — the URL to open
botNumber — optional. Your bot’s own WhatsApp number, recorded against the logged message. Pass null if you don’t have it.
header — optional. See Headers and footers.
footer — optional. Small print under the message.

URL buttons open in the in-app browser inside WhatsApp. They do not generate a reply to your webhook when tapped.

Send an image with an optional caption. The image must be accessible via a public URL.

await sendImage(
  conversationId,
  to,
  "https://example.com/images/product.jpg",
  "Our latest model — available now."
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
imageUrl — public URL of the image (JPEG or PNG)
caption — optional caption displayed below the image

Supported formats are JPEG and PNG. Images must be under 5 MB. If you omit the caption, pass null as the fourth argument.

Send a file (PDF or other document type) with a filename and optional caption. The file must be accessible via a public URL.

await sendPDF(
  conversationId,
  to,
  "https://example.com/files/invoice.pdf",
  "invoice_march_2025.pdf",
  "Your invoice for March 2025."
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
pdfUrl — public URL of the file
fileName — the filename shown to the user (e.g. "invoice.pdf")
caption — optional caption shown below the document

Documents appear in WhatsApp with a download button. PDF is the most common format. Files must be under 100 MB.

Ask the user to share their location. WhatsApp displays a “Send location” button that opens the native location picker.

await sendLocationRequest(
  conversationId,
  to,
  "Please share your location so we can find the nearest branch."
);

Parameters:

conversationId — the conversation ID
to — recipient phone number
bodyText — the message text shown above the “Send location” button

When the user shares their location, your webhook receives a location message containing latitude, longitude, and optionally name and address. Access these via message.location.latitude and message.location.longitude.

Your bot does not send voice notes, but it can receive and transcribe them. When a user sends a voice note, the AI bot template automatically transcribes the audio to text using OpenAI and passes the transcript into your conversation handler as if it were a plain text message. Your existing state handlers process voice notes without any changes on your part.

// Voice notes are handled automatically by the AI bot template.
// The transcript is passed to your state handler as a plain text message.
// No additional code is required on your end.

Voice note transcription requires an OpenAI API key stored as a secret in your project. See Secrets for how to add one.

Send a Meta-approved message template to a user who has not messaged you recently (outside the 24-hour window) or for proactive outbound notifications.

await sendTemplate(
  to,
  "appointment_reminder",
  "en",
  [
    {
      type: "body",
      parameters: [
        { type: "text", text: "Sarah" },
        { type: "text", text: "tomorrow at 3pm" },
      ],
    },
  ]
);

Parameters:

to — recipient phone number
templateName — the approved template name
languageCode — language code (e.g. "en", "en_US", "es")
components — array of component objects with variable values

Templates must be approved by Meta before they can be sent. See Message Templates for how to create and manage them.

Headers and footers

The three interactive senders — sendInteractiveButtons, sendMenu, and sendURLButton — each take an optional header and footer. They let you put a product photo above the buttons and a line of small print below them, all in one bubble instead of two or three separate messages.

botNumber comes before header and footer. All three senders take the same trailing order — …, botNumber, header, footer. Pass null for botNumber if you don’t have it rather than shifting the header into its place.

await sendInteractiveButtons(
  conversationId,
  to,
  "Margherita Pizza — R89",
  [
    { id: "order_marg", title: "Order" },
    { id: "skip", title: "Skip" },
  ],
  botNumber,
  { type: "image", slug: "pizza-margherita" },
  "Prices include VAT"
);

An object. Its type decides what kind of header you get. A text header is a short bold line above the body:

{ type: "text", text: "Today's specials" }

A media header uses image, video, or document as its type, and supplies the file one of three ways:

Key	What you give it	When to use it
`link`	A public URL	The file lives somewhere on the web already
`mediaId`	A Meta media ID	You’ve already uploaded the file to Meta
`slug`	The name of a file in your project’s Paige media library	Anything you uploaded through the chat paperclip — this is usually the one you want

{ type: "image", link: "https://example.com/pizza.jpg" }
{ type: "image", mediaId: "1234567890" }
{ type: "image", slug: "pizza-margherita" }

A slug is resolved for you at send time, including re-uploading the file if Meta has expired its copy — you don’t need to track media IDs yourself. See Media and storage for how files get into the library.

A header that can’t be used — no type, a text header with no text, a media header with none of link, mediaId, or slug — is simply left off the message. The send still goes through; you just get the message without a header.

A plain string, shown as small grey text under the message body. No object, no formatting options:

"Prices include VAT"

sendFlow does not take a header or footer. Flow messages are limited to their body text and call-to-action button.

Carousel messages

You can also send a carousel of up to 10 cards, each with an image, body text, and quick-reply buttons. Carousels are useful for product listings, plan comparisons, or multi-item promotions.

await sendCarousel(
  conversationId,
  to,
  "Here are our current plans:",
  [
    {
      imageUrl: "https://example.com/images/starter.jpg",
      bodyText: "Starter — $29/month. Up to 1,000 conversations.",
      buttons: [{ id: "plan_starter", title: "Choose Starter" }],
    },
    {
      imageUrl: "https://example.com/images/pro.jpg",
      bodyText: "Pro — $79/month. Unlimited conversations.",
      buttons: [{ id: "plan_pro", title: "Choose Pro" }],
    },
  ]
);

Each card in the cards array takes imageUrl, bodyText, and a buttons array. Button clicks are returned via the webhook as interactive messages with button_reply.

Sending a WhatsApp Flow

To open a multi-screen WhatsApp Flow from within a conversation, use sendFlow. The user taps the call-to-action button and the flow opens inline in WhatsApp.

await sendFlow(
  conversationId,
  to,
  {
    flow_id: "1234567890",
    flow_cta: "Book now",
    body_text: "Fill in your details to complete your booking.",
    screen: "BOOKING_SCREEN",
  }
);

Unlike the other interactive senders, sendFlow takes no header or footer — a flow message is its body text and its call-to-action button, nothing more. For the thinking behind when to use a flow, see Thinking in flows. For how to create and publish one in Paige, see Flows.

Foundations

WhatsApp platform

WhatsApp message types

Message types in detail

Headers and footers

`header`

`footer`

Carousel messages

Sending a WhatsApp Flow

​Message types in detail

​Headers and footers

​header

​footer

​Carousel messages

​Sending a WhatsApp Flow

Message types in detail

Headers and footers

`header`

`footer`

Carousel messages

Sending a WhatsApp Flow