WhatsApp Business API for appointment booking — whatsapp flow

Use case overview

This scenario sends a WhatsApp Flow entry point with sendFlow during the 24-hour customer service window. A personalised greeting plus Book now CTA opens the published flow form.

Template example

Hi {{1}}, book your appointment:

Flow id and CTA label are defined in the integration contract; replace the example flow id with your published Flow.

Variables and purpose

• {{1}} — customer name in the flow invitation text

Filled-in example

Hi Alex, book your appointment:

When to use it

• service appointments

Business value

• Client message or booking intent keeps the WhatsApp session window open
• Backend resolves the customer name and published flow id
• sendFlow delivers the flow CTA with personalised greeting text
• Client completes the Meta Flow form inside WhatsApp
• Booking data returns to CRM or calendar integration via flow completion webhook

Workflow

1. A client expresses booking intent while the session is open.
2. Your backend resolves the customer name and flow id.
3. sendFlow sends the greeting with the Book now CTA.
4. The client completes the flow form and booking data returns to your system.
5. Delivery progress is reported asynchronously — typically sent, then delivered (or failed/undelivered).
6. Your system receives status via webhook (hooks[]) or polls delivery status and handles failures if needed.

Technical implementation

Prerequisites

• An open WhatsApp session window and a published Meta Flow id.
• 1MSG channel with sendFlow access and a backend flow token.

Code examples

#!/usr/bin/env node

// === Configuration (replace "___" placeholders) ===
const API_BASE_URL = "https://api.1msg.io"; // production 1MSG API base URL
const CHANNEL_ID = "___";                   // channel ID from 1MSG dashboard
const API_TOKEN = "___";                    // channel JWT token (Bearer)



// === Test data ===
const TEST_PHONE = "___";            // client phone in international format · requires open 24-hour session window
const FLOW_TOKEN = "___";                 // flow token from your backend
const TEST_CUSTOMERNAME = "___";    // {{1}} customer name

function normalizePhone(phone) {
  return String(phone).replace(/\D/g, "");
}

async function sendFlowMessage({ phone, flowToken, customerName }) {
  const url = `${API_BASE_URL}/${CHANNEL_ID}/sendFlow`;
  const requestBody = {
    phone: normalizePhone(phone),
    body: `Hi ${customerName}, book your appointment:`,
    flowId: "1234567890",
    flowToken,
    flowCta: "Book now",
    flowAction: "navigate",
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });

  const raw = await res.text();
  let data;
  try {
    data = JSON.parse(raw);
  } catch {
    data = null;
  }

  if (!res.ok || !data || data.sent !== true) {
    console.error("Send failed.");
    console.error(raw);
    process.exit(1);
  }

  console.log("Message sent to client.");
  return data;
}

if (require.main === module) {
  sendFlowMessage({
    phone: TEST_PHONE,
    flowToken: FLOW_TOKEN,
    customerName: TEST_CUSTOMERNAME,
  }).catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { sendFlowMessage };

Immediate API response (synchronous)

• HTTP 2xx and JSON "sent": true mean 1MSG accepted the message for sending — not that it already reached the customer's phone.
• Save the `id` field from the response (value looks like wamid.…). Use it to correlate delivery callbacks or polling.
• The response may also include message and description — informational only.

Delivery status (asynchronous)

• Register a webhook (POST …/webhook) so 1MSG POSTs delivery updates to your HTTPS endpoint in a separate `hooks[]` payload (sent, delivered, read, or failed/undelivered when applicable).
• Optionally poll: GET {base}/{channel}/hookInfo?messageId=<id from sendTemplate>.
• In practice, delivery often completes within a few seconds — but that is not guaranteed by the API contract.

Common errors

• Session window closed (no client message within 24 hours)
• Invalid or non-normalized phone number
• Missing or invalid message body / media URL
• Delivery failure — check status webhook and retry policy

FAQ

• Do I need a template? No — this scenario uses a session message inside the 24-hour customer service window.
• When does the session window close? If the client has not written or replied within 24 hours, sendMessage will fail until a template reopens the chat.
• How do I check delivery? sent: true only confirms acceptance. Track delivery via webhook hooks[] or polling.
• What if the message is not delivered? Log the failed/undelivered hook, verify the session window, then retry or use a template.
• Can I connect this to my CRM or backend? Yes — trigger the API call from your inbound webhook or workflow engine.

Related

• Knowledge base
• Creating a template
• Sending a template
• SDK