API reference

whatsapp.messages

Send every message type supported by the WhatsApp Cloud API: text, media, templates, interactive buttons/lists/CTA, carousels, catalogs, location, contacts, flows, and reactions.

Every method in this module returns a Promise<WhatsappResponse<SendMessageResult>> following the { data, error } contract. The recipient phone number must be in international format without leading plus (e.g. 15551234567).

Optional third parameter: opts (SendOptions)

Every message-sending method accepts an optional trailing opts object (SendOptions):

{
  phoneNumberId?: string;                       // Override the sender phone number for this call
  replyToMessageId?: string;                    // Send as a contextual quote reply to a specific inbound message
  recipientType?: "individual" | "group";       // Use "group" when `to` is a group ID from whatsapp.groups
  bizOpaqueCallbackData?: string;               // Opaque string (max 512 chars) echoed back in status webhooks
}
New in 1.1.0. sendTemplate and sendReaction can now reply to a message too, and every send method supports recipientType and bizOpaqueCallbackData. Try the options in the Playground.

Sending to a BSUID or a group

Users who adopt a WhatsApp username may not expose a phone number. Pass their business-scoped user ID (BSUID, e.g. US.13491208655302741918) as to to any send method and it is routed to the API's recipient field automatically. Use the isBsuid() helper to tell the two apart. To message a group, pass the group ID with recipientType: "group":

import { isBsuid } from "wapi-cloud";

// BSUID recipient (no phone number needed)
const { data } = await whatsapp.messages.sendText("US.13491208655302741918", {
  body: "Hi there!",
});
console.log(data?.userId); // BSUID echoed back by Meta (data.waId is empty for BSUID sends)

// Group recipient
await whatsapp.messages.sendText(
  "120363012345678901@g.us",
  { body: "Hello team!" },
  { recipientType: "group" }
);

// Echo your own correlation data back in status webhooks
await whatsapp.messages.sendText(
  "15551234567",
  { body: "Order shipped" },
  { bizOpaqueCallbackData: "order-8821" }
);

sendText

whatsapp.messages.sendText(to: string, options: TextMessageOptions, opts?): Promise<WhatsappResponse<SendMessageResult>>
const { data, error } = await whatsapp.messages.sendText("15551234567", {
  body: "Hello from wapi-cloud! Check out https://github.com/niyassby/wapi-cloud",
  previewUrl: true, // Generate a web preview card for URLs in the text
});

if (data) console.log("Message ID:", data.messageId, "WA ID:", data.waId);

reply (Contextual quote reply)

whatsapp.messages.reply(to: string, messageId: string, options: TextMessageOptions, opts?): Promise<WhatsappResponse<SendMessageResult>>

Convenience method that quotes a specific inbound message ID when sending a text reply:

await whatsapp.messages.reply(
  "15551234567",
  "wamid.HBgLM...", // Inbound message ID to quote
  { body: "Thanks for your inquiry! We are processing your request." }
);

Media Messages (Images, Video, Audio, Document, Sticker)

Media methods accept either a hosted public HTTPS link or a mediaId returned from whatsapp.media.upload():

media-messages.ts
// 1. Send Image
await whatsapp.messages.sendImage("15551234567", {
  link: "https://example.com/receipt.jpg",
  caption: "Your purchase receipt for Order #8821",
});

// 2. Send Document (with custom filename)
await whatsapp.messages.sendDocument("15551234567", {
  mediaId: uploadedDocId,
  filename: "Financial_Report_2026.pdf",
  caption: "Q2 Financial Summary",
});

// 3. Send Video
await whatsapp.messages.sendVideo("15551234567", {
  link: "https://example.com/demo.mp4",
  caption: "Product walkthrough video",
});

// 4. Send Audio (voice notes / audio files)
await whatsapp.messages.sendAudio("15551234567", {
  link: "https://example.com/audio-message.ogg",
});

// 5. Send Sticker (WebP format)
await whatsapp.messages.sendSticker("15551234567", {
  mediaId: stickerMediaId,
});

sendInteractive (Buttons, Lists, CTA URL)

Interactive messages provide structured UI elements in the chat window:

1. Quick-reply buttons (1 to 3 buttons)

await whatsapp.messages.sendInteractive("15551234567", {
  type: "button",
  header: "Appointment Confirmation",
  body: "Would you like to confirm your appointment for tomorrow at 3:00 PM?",
  footer: "Reply by selecting an option below",
  buttons: [
    { id: "btn_confirm", title: "Confirm ✅" },
    { id: "btn_reschedule", title: "Reschedule 📅" },
    { id: "btn_cancel", title: "Cancel ❌" },
  ],
});

2. Interactive List menu (up to 10 rows across sections)

await whatsapp.messages.sendInteractive("15551234567", {
  type: "list",
  header: "Support Menu",
  body: "Please choose a department to connect with:",
  footer: "Available 24/7",
  buttonText: "View Options",
  sections: [
    {
      title: "Technical Support",
      rows: [
        { id: "dept_cloud", title: "Cloud Infrastructure", description: "Servers, uptime, scaling" },
        { id: "dept_api", title: "API Integration", description: "Webhooks, SDK questions" },
      ],
    },
    {
      title: "Billing & Sales",
      rows: [
        { id: "dept_billing", title: "Invoices & Payments", description: "View or update payment info" },
      ],
    },
  ],
});

3. CTA URL Button (Open web link)

await whatsapp.messages.sendInteractive("15551234567", {
  type: "cta_url",
  header: "New Release",
  body: "wapi-cloud v1.0 is now live with full TypeScript support!",
  footer: "Documentation & Examples",
  displayText: "Read Documentation",
  url: "https://github.com/niyassby/wapi-cloud",
});

sendTemplate

Sends pre-approved message templates with dynamic variable substitutions:

await whatsapp.messages.sendTemplate("15551234567", {
  name: "order_status_update",
  language: "en_US",
  components: [
    {
      type: "header",
      parameters: [{ type: "text", text: "ORDER-991" }],
    },
    {
      type: "body",
      parameters: [
        { type: "text", text: "Alex" },
        { type: "text", text: "Shipped" },
      ],
    },
    {
      type: "button",
      sub_type: "quick_reply",
      index: 0,
      parameters: [{ type: "payload", payload: "TRACK_PACKAGE" }],
    },
  ],
});

sendCatalogTemplate (Single-Product Template SPM)

Sends an approved single-product message template where product details are fetched from your Meta catalog automatically:

await whatsapp.messages.sendCatalogTemplate("15551234567", {
  name: "featured_product_promo",
  language: "en_US",
  catalogId: "1234567890",
  productRetailerId: "SKU-9921",
  bodyParams: [{ type: "text", text: "20% Discount" }],
});

sendCarouselTemplate (Template with Media Cards)

Sends an approved media-card carousel template with 2 to 10 swipeable cards:

await whatsapp.messages.sendCarouselTemplate("15551234567", {
  name: "holiday_promotions",
  language: "en_US",
  bodyParams: [{ type: "text", text: "Exclusive Member Deals" }],
  cards: [
    {
      headerType: "image",
      headerMediaId: "media_id_1",
      bodyParams: [{ type: "text", text: "Deal 1: 30% Off Shoes" }],
      buttons: [
        {
          subType: "url",
          index: 0,
          parameters: [{ type: "text", text: "shoes-sale" }],
        },
      ],
    },
    {
      headerType: "image",
      headerMediaId: "media_id_2",
      bodyParams: [{ type: "text", text: "Deal 2: Buy 1 Get 1 Shirts" }],
      buttons: [
        {
          subType: "url",
          index: 0,
          parameters: [{ type: "text", text: "shirts-sale" }],
        },
      ],
    },
  ],
});

sendLocation & sendLocationRequest

location.ts
// 1. Send specific location pin
await whatsapp.messages.sendLocation("15551234567", {
  latitude: 37.4849,
  longitude: -122.1483,
  name: "Meta Headquarters",
  address: "1 Hacker Way, Menlo Park, CA 94025",
});

// 2. Request user to share their current live location
await whatsapp.messages.sendLocationRequest("15551234567", {
  body: "Please share your current location so our courier can find you:",
});

sendContacts

await whatsapp.messages.sendContacts("15551234567", [
  {
    name: {
      formattedName: "Sarah Connor",
      firstName: "Sarah",
      lastName: "Connor",
    },
    phones: [
      { phone: "+15550192834", type: "WORK", waId: "15550192834" },
    ],
    emails: [
      { email: "sarah@example.com", type: "WORK" },
    ],
  },
]);

sendFlow (Interactive WhatsApp Flows v3)

Launches an interactive native form screen directly inside the chat:

await whatsapp.messages.sendFlow("15551234567", {
  flowId: "9876543210",
  cta: "Book Appointment",
  headerText: "Dentist Booking",
  bodyText: "Tap below to select your service and preferred time slot:",
  footerText: "Fast and easy booking",
  flowActionPayload: {
    screen: "APPOINTMENT_SELECTION",
    data: { serviceId: "clean-01" },
  },
});

// Let your Flow endpoint supply the first screen, and test an unpublished Flow
await whatsapp.messages.sendFlow("15551234567", {
  flowId: "9876543210",
  cta: "Open",
  bodyText: "Continue in the form",
  flowAction: "data_exchange",
  flowToken: "session-42",
  mode: "draft",
});

sendReaction

// Add reaction emoji
await whatsapp.messages.sendReaction("15551234567", {
  messageId: "wamid.HBgLM...",
  emoji: "👍",
});

// Remove reaction by passing an empty string
await whatsapp.messages.sendReaction("15551234567", {
  messageId: "wamid.HBgLM...",
  emoji: "",
});

Commerce Messages (sendProduct, sendProductList, sendCatalog, sendProductCarousel)

commerce-messages.ts
// 1. Single Product
await whatsapp.messages.sendProduct("15551234567", {
  catalogId: "1234567890",
  productRetailerId: "ITEM-101",
  body: "Check out this item!",
  footer: "In stock",
});

// 2. Multi-Product List
await whatsapp.messages.sendProductList("15551234567", {
  catalogId: "1234567890",
  header: "Electronics Sale",
  body: "Select a device to view specs:",
  sections: [
    { title: "Phones", productRetailerIds: ["PHONE-A", "PHONE-B"] },
    { title: "Audio", productRetailerIds: ["AUDIO-X"] },
  ],
});

// 3. Browse Full Catalog
await whatsapp.messages.sendCatalog("15551234567", {
  body: "Browse our entire inventory right here on WhatsApp:",
});

// 4. Product Carousel (2 to 10 products)
await whatsapp.messages.sendProductCarousel("15551234567", {
  body: "Recommended for you:",
  cards: [
    { catalogId: "1234567890", productRetailerId: "ITEM-101" },
    { catalogId: "1234567890", productRetailerId: "ITEM-102" },
  ],
});

sendMediaCarousel (Image/Video Carousel with Buttons)

await whatsapp.messages.sendMediaCarousel("15551234567", {
  body: "Swipe through our new arrivals:",
  cards: [
    {
      type: "cta_url",
      headerType: "image",
      headerMedia: { link: "https://example.com/jacket.jpg" },
      body: "Winter Jacket - $89",
      displayText: "Buy Online",
      url: "https://example.com/store/jacket",
    },
    {
      type: "cta_url",
      headerType: "image",
      headerMedia: { link: "https://example.com/boots.jpg" },
      body: "Leather Boots - $120",
      displayText: "Buy Online",
      url: "https://example.com/store/boots",
    },
  ],
});

markAsRead & typing indicator

whatsapp.messages.markAsRead(messageId: string, opts?: { phoneNumberId?: string; typingIndicator?: boolean }): Promise<WhatsappResponse<{ success: boolean }>>
whatsapp.messages.showTyping(messageId: string, opts?: { phoneNumberId?: string }): Promise<WhatsappResponse<{ success: boolean }>>

markAsRead marks an inbound message as read. Pass typingIndicator: true (or use the showTyping shorthand) to also show the "typing…" indicator, which WhatsApp clears after about 25 seconds or when you send a reply. For group messages, each message must be marked separately.

// Mark as read only
await whatsapp.messages.markAsRead("wamid.HBgLM...");

// Mark as read and show "typing…" while you prepare a reply
await whatsapp.messages.showTyping("wamid.HBgLM...");
// same as:
await whatsapp.messages.markAsRead("wamid.HBgLM...", { typingIndicator: true });

sendMarketingTemplate (Marketing Messages API)

whatsapp.messages.sendMarketingTemplate(to: string, options: SendMarketingTemplateOptions, opts?: SendOptions): Promise<WhatsappResponse<SendMessageResult>>

Sends an approved MARKETING template through the Marketing Messages API (/marketing_messages). It takes the same options as sendTemplate plus:

ParameterTypeDescription
productPolicy"CLOUD_API_FALLBACK" | "STRICT"With "STRICT", Meta never falls back to the regular Cloud API when your number is not onboarded to Marketing Messages.
messageActivitySharingbooleanPer-message override of whether read/engagement activity is shared for optimisation.
await whatsapp.messages.sendMarketingTemplate("15551234567", {
  name: "summer_sale",
  language: "en_US",
  productPolicy: "STRICT",
  messageActivitySharing: true,
});

sendCallPermissionRequest

whatsapp.messages.sendCallPermissionRequest(to: string, options: { bodyText: string }, opts?: SendOptions): Promise<WhatsappResponse<SendMessageResult>>

Asks the user for permission to call them. Once they accept, you can start a call with whatsapp.calls.connect.

await whatsapp.messages.sendCallPermissionRequest("15551234567", {
  bodyText: "May we call you about your order?",
});

Root shortcuts

// Direct sugar on the main client
await whatsapp.send("15551234567", { body: "Quick message" });
await whatsapp.sendTemplate("15551234567", { name: "alert", language: "en" });