API reference

Flows, QR codes & analytics

Build native interactive in-chat forms with WhatsApp Flows, generate scan-to-chat QR codes, and query rich WABA messaging metrics.

whatsapp.flows

WhatsApp Flows allow businesses to build rich, native multi-screen experiences (forms, surveys, appointment booking, lead generation, customer support) directly inside WhatsApp without redirecting to a browser.

1. Create a Flow

whatsapp.flows.create(input: CreateFlowInput): Promise<WhatsappResponse<{ id: string; success?: boolean }>>

create-flow.ts

const { data: flow, error } = await whatsapp.flows.create({
  name: "appointment_booking_v1",
  categories: ["APPOINTMENT_BOOKING"],
  // Optional: Supply initial JSON definition or endpoint URI for data exchange flows
  endpointUri: "https://example.com/api/whatsapp/flows/data-exchange",
});

if (flow) {
  console.log("Created Flow ID:", flow.id);
}

2. Update Flow JSON Asset

whatsapp.flows.updateJson(flowId: string, flowJson: object): Promise<WhatsappResponse<{ success: boolean }>>

Uploads the Flow JSON layout definition specifying screens, inputs, and actions:

update-flow-json.ts

await whatsapp.flows.updateJson("flow_id_12345", {
  version: "3.1",
  screens: [
    {
      id: "APPOINTMENT_SCREEN",
      title: "Select Service",
      data: {},
      layout: {
        type: "SingleColumnLayout",
        children: [
          {
            type: "Dropdown",
            name: "service_type",
            label: "Select Service",
            required: true,
            "data-source": [
              { id: "consult", title: "General Consultation" },
              { id: "teeth_clean", title: "Teeth Cleaning" },
            ],
          },
          {
            type: "Footer",
            label: "Book Now",
            "on-click-action": {
              name: "complete",
              payload: { service: "${form.service_type}" },
            },
          },
        ],
      },
    },
  ],
});

3. Publish, Deprecate & Delete Flows

// Publish a flow (makes it available to send to customers)
await whatsapp.flows.publish("flow_id_12345");

// List all flows
const { data: flows } = await whatsapp.flows.list();

// Deprecate or delete
await whatsapp.flows.deprecate("flow_id_12345");
await whatsapp.flows.delete("flow_id_12345");

4. Send Flow to Customer

await whatsapp.messages.sendFlow("15551234567", {
  flowId: "flow_id_12345",
  cta: "Start Booking",
  headerText: "Book Your Visit",
  bodyText: "Tap the button below to choose your date and time:",
  footerText: "Appointments available this week",
  flowActionPayload: {
    screen: "APPOINTMENT_SCREEN",
  },
});

whatsapp.qrCodes

Generate deep-link QR codes that launch a direct WhatsApp chat with your business phone number and pre-fill an introductory message.

create

whatsapp.qrCodes.create(input: { prefilledMessage: string }, opts?): Promise<WhatsappResponse<WhatsappQrCode>>

qr-codes.ts

const { data: qr, error } = await whatsapp.qrCodes.create({
  prefilledMessage: "Hello! I saw your flyer and would like a quote.",
});

if (qr) {
  console.log("QR Code identifier:", qr.code);
  console.log("Deep link URL:", qr.deep_link_url); // https://wa.me/message/...
  console.log("QR Image URL (PNG):", qr.qr_image_url);
}

list, get, update & delete

// List all QR codes
const { data: codes } = await whatsapp.qrCodes.list();

// Get specific QR code
const { data: code } = await whatsapp.qrCodes.get("QR_CODE_ID");

// Update prefilled message
await whatsapp.qrCodes.update("QR_CODE_ID", {
  prefilledMessage: "Updated campaign message",
});

// Delete QR code
await whatsapp.qrCodes.delete("QR_CODE_ID");

whatsapp.analytics

Retrieve granular messaging metrics, conversation breakdown counts, and pricing analytics for your WhatsApp Business Account.

analytics.ts

const query = {
  start: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000), // 30 days ago
  end: new Date(),
  granularity: "DAY" as const, // "HALF_HOUR" | "DAY" | "MONTH"
};

// 1. Messaging analytics (sent, delivered)
const { data: messagingData } = await whatsapp.analytics.getMessagingAnalytics(query);

// 2. Conversation analytics (user-initiated, business-initiated)
const { data: convData } = await whatsapp.analytics.getConversationAnalytics(query);

// 3. Pricing analytics (cost per category)
const { data: pricingData } = await whatsapp.analytics.getPricingAnalytics(query);

Flow Categories

Parameter	Type	Description
SIGN_UP	FlowCategory	Account creation and customer onboarding forms.
SIGN_IN	FlowCategory	Login and authentication verification.
APPOINTMENT_BOOKING	FlowCategory	Scheduling, reservations, and time-slot booking.
LEAD_GENERATION	FlowCategory	Collecting customer contact information and interest surveys.
CONTACT_US	FlowCategory	Customer inquiry and contact forms.
CUSTOMER_SUPPORT	FlowCategory	Support tickets, issue reporting, and troubleshooting flows.
SURVEY	FlowCategory	Feedback questionnaires and NPS ratings.
OTHER	FlowCategory	Custom business-specific forms.