API reference

whatsapp.templates

Create, list, auto-paginate, fetch, update, and delete message templates including media carousels and catalog templates. Requires businessAccountId.

WhatsApp Message Templates are required to initiate conversations with customers outside the 24-hour service window. Once created, templates go through Meta's automated and human approval before they can be sent.

create

whatsapp.templates.create(input: CreateTemplateInput): Promise<WhatsappResponse<{ id: string; status: string; category: string }>>

1. Standard text & quick-reply template

create-template.ts

const { data, error } = await whatsapp.templates.create({
  name: "order_status_v1",
  category: "UTILITY",
  language: "en_US",
  components: [
    {
      type: "HEADER",
      format: "TEXT",
      text: "Order {{1}} Update",
      example: { header_text: ["#1001"] },
    },
    {
      type: "BODY",
      text: "Hello {{1}}, your order has been {{2}}.",
      example: { body_text: [["John Doe", "shipped"]] },
    },
    {
      type: "FOOTER",
      text: "Thank you for shopping with Acme Store",
    },
    {
      type: "BUTTONS",
      buttons: [
        { type: "QUICK_REPLY", text: "Track Order" },
        { type: "URL", text: "Visit Store", url: "https://example.com/order/{{1}}", example: ["1001"] },
        { type: "PHONE_NUMBER", text: "Call Support", phone_number: "+15551234567" },
      ],
    },
  ],
});

if (!error) {
  console.log("Created template ID:", data.id, "Status:", data.status);
}

2. Media Carousel template (2 to 10 cards)

Create templates with horizontal swipeable media cards containing buttons:

await whatsapp.templates.create({
  name: "product_carousel_deal",
  category: "MARKETING",
  language: "en_US",
  components: [
    {
      type: "BODY",
      text: "Check out our top deals today:",
    },
    {
      type: "CAROUSEL",
      cards: [
        {
          components: [
            { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::..."] } },
            { type: "BODY", text: "Summer Sneakers - 30% Off" },
            { type: "BUTTONS", buttons: [{ type: "QUICK_REPLY", text: "Buy Now" }] },
          ],
        },
        {
          components: [
            { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::..."] } },
            { type: "BODY", text: "Running Shorts - 20% Off" },
            { type: "BUTTONS", buttons: [{ type: "QUICK_REPLY", text: "Buy Now" }] },
          ],
        },
      ],
    },
  ],
});

3. Single-Product Catalog Template (SPM)

await whatsapp.templates.create({
  name: "spm_product_template",
  category: "MARKETING",
  language: "en_US",
  components: [
    { type: "HEADER", format: "PRODUCT" },
    { type: "BODY", text: "Special deal on {{1}}! Tap below to view details in WhatsApp." },
    { type: "BUTTONS", buttons: [{ type: "SPM" }] },
  ],
});

list & listAll

whatsapp.templates.list(params?: ListTemplatesParams): Promise<WhatsappResponse<PaginatedResult<WhatsappTemplate>>>

// 1. Fetch a single page
const { data } = await whatsapp.templates.list({
  limit: 25,
  status: "APPROVED", // "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED"
});
data?.items.forEach((t) => console.log(t.name, t.category, t.status));

// 2. Auto-paginate through all templates across every page
for await (const template of whatsapp.templates.listAll()) {
  console.log("Template:", template.name, "Language:", template.language);
}

get

whatsapp.templates.get(templateId: string): Promise<WhatsappResponse<WhatsappTemplate>>

const { data: template } = await whatsapp.templates.get("1234567890");
console.log(template?.name, template?.status, template?.components);

update

whatsapp.templates.update(templateId: string, patch: UpdateTemplateInput): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.templates.update("1234567890", {
  components: [
    {
      type: "BODY",
      text: "Updated text: Hello {{1}}, your package has been delivered!",
    },
  ],
});

delete

whatsapp.templates.delete(nameOrId: string): Promise<WhatsappResponse<{ success: boolean }>>

await whatsapp.templates.delete("order_status_v1");

Template Categories

Parameter	Type	Description
UTILITY	Transactional	Account alerts, order confirmations, shipping updates, reminders, and customer service follow-ups.
MARKETING	Promotional	Promotions, product offers, announcements, welcome messages, and newsletter updates.
AUTHENTICATION	Security & OTP	One-time passcodes, identity verification codes, and password recovery verification.