WhatsApp Business API for lead qualification through key questions

Use case overview

This use case sends a new lead an approved WhatsApp template with a personalized greeting: the message substitutes the lead's name and product or source context, and the «Начать» (Start) quick-reply button opens a short qualification flow. After the button is tapped, within the 24-hour session window the system asks follow-up questions one at a time and records each answer via webhook.

Template example

Hello, {{1}}! To find the right solution for {{2}} faster, please answer a few short questions. Tap «Начать» — it takes a couple of minutes.

[Start]

Variables and purpose

• {{1}} — lead or recipient name
• {{2}} — product interest or lead source context (where the request came from, which area is of interest)

Filled-in example

Hello, Alexey! To find the right solution for WhatsApp messaging faster, please answer a few short questions. Tap «Начать» — it takes a couple of minutes.

[Start]

When to use it

• sales and lead generation: first contact with a new lead from a form, ad, or crm when you need to collect a structured profile (budget, timeline, company size, use case) before handing off to sales. suitable for development teams, small product groups, and agencies integrating whatsapp into the qualification funnel.

Business value

• capture a new lead event with name and optional product or source context
• send a cold-start template that opens the chat and offers a Start action
• receive the Start tap via webhook and send the first qualifying question
• capture each subsequent answer via webhook and advance to the next question
• persist the completed qualification profile and hand off to sales or CRM

Workflow

1. When a new lead appears, the system sends a personalized template greeting and an invitation to start a short qualification flow.
2. The lead taps «Начать» — the event arrives via webhook and a session opens in the 24-hour WhatsApp window.
3. Within the session the integrator sends follow-up questions one at a time (budget, timeline, company size, use case).
4. Each answer is captured via webhook and stored in the qualification profile.
5. After all key fields are collected the profile is passed to CRM or sales for follow-up.
6. Delivery progress is reported asynchronously — typically sent, then delivered (or failed/undelivered).
7. Your system receives status via webhook (hooks[]) or polls GET …/hookInfo?messageId=<id> and handles failures if needed.

Technical implementation

Prerequisites

• An approved WhatsApp template with two body variables and one «Начать» quick-reply button
• A 1MSG account with access to the template send API and a configured webhook for incoming messages
• Integration with CRM or an internal system to record answers and pass the profile to sales
• The generated handleIncomingMessage matches inbound text to template button labels — a starting point; replace with your production router.

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)

const TEMPLATE_NAME = "___";                // approved template name
const TEMPLATE_NAMESPACE = "___";           // template namespace (422 without it)
const TEMPLATE_LANGUAGE = "___";            // template language code, e.g. "en"



// === Test data ===
const TEST_PHONE = "___";            // client phone in international format
const TEST_LEADNAME = "___";    // {{1}} lead name
const TEST_PRODUCTCONTEXT = "___";    // {{2}} product context

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

function assertConfigured(values) {
  for (const [key, value] of Object.entries(values)) {
    if (value === "___" || value === "" || value === undefined || value === null) {
      throw new Error(`Missing configuration value: ${key}`);
    }
  }
}

async function sendTemplateMessage({ phone, leadName, productContext }) {
  assertConfigured({
    CHANNEL_ID,
    API_TOKEN,
    TEMPLATE_NAME,
    TEMPLATE_NAMESPACE,
    TEMPLATE_LANGUAGE,
    phone,
    leadName,
    productContext,
  });

  const url = `${API_BASE_URL}/${CHANNEL_ID}/sendTemplate`;

  // params carries body and button blocks (dynamic buttons).
  const requestBody = {
    phone: normalizePhone(phone),
    template: TEMPLATE_NAME,
    namespace: TEMPLATE_NAMESPACE,
    language: {
      policy: "deterministic",
      code: TEMPLATE_LANGUAGE,
    },
    params: [
      {
        type: "body",
        parameters: [
          { type: "text", text: String(leadName) }, // {{1}} lead name
          { type: "text", text: String(productContext) }, // {{2}} product context
        ],
      },
    ],
  };

  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. API response:");
    console.error(raw);
    process.exit(1);
  }

  console.log("Message sent to client.");
  console.log("API response:", raw);
  return data;
}

function handleIncomingMessage(message) {
  const text = (message && (message.text || message.body || "")).trim();
  // Meta quick_reply label (from template.txt) → route key (code_contract.ref) "start_qualification"
  if (text === "Начать") {
    console.log("Reply received: start_qualification");
    return { status: "start_qualification" };
  }
  console.log("Free-text reply — handle separately.");
  return { status: "other" };
}

if (require.main === module) {
  sendTemplateMessage({
    phone: TEST_PHONE,
    leadName: TEST_LEADNAME,
    productContext: TEST_PRODUCTCONTEXT,
  }).catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { sendTemplateMessage, handleIncomingMessage };

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

• Invalid or non-normalized phone number
• Unapproved or missing template name / namespace
• No customer opt-in for WhatsApp business messages
• Template variable count mismatch (422 from API)
• Delivery failure — check status webhook and retry policy

FAQ

• Do I need an approved template? Yes — cold-start WhatsApp messages require a Meta-approved template.
• Can I customize the message text? Body variables are dynamic; fixed text and button labels are set in the Meta template.
• How do I check delivery? sent: true only confirms acceptance. Track delivery via webhook hooks[] or GET …/hookInfo?messageId=<id>.
• What if the message is not delivered? Log the failed/undelivered hook, verify opt-in and template status, then retry or fall back to another channel.
• Can I connect this to my CRM or backend? Yes — trigger the API call from your platform webhook or event handler.

Related

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