WhatsApp Business API for password reset otp

Use case overview

Sends a one-time recovery code through a WhatsApp authentication template when the user starts password reset. The copy-code button speeds up entry in your recovery form.

Template example

{{1}} is your verification code. For your security, do not share this code with anyone.

[Copy code]

Authentication templates require the OTP in two API places — body and copy-code button. Body-only sends return sent: false.

Variables and purpose

• {{1}} — one-time password recovery code (digits)

Filled-in example

123456 is your verification code. For your security, do not share this code with anyone.

[Copy code]

When to use it

• forgot password
• account recovery
• security

Business value

• User requests password reset and provides their phone number
• System generates a one-time recovery code and resolves the recipient phone
• Authentication template is built with the code in body and copy-code button
• WhatsApp message is delivered to the user
• User submits the code; backend validates it and allows setting a new password

Workflow

1. User requests password reset and enters their phone.
2. Backend generates a recovery code and sends the template.
3. User copies the code from WhatsApp and submits it.
4. Backend validates and unlocks the password reset step.
5. Delivery progress is reported asynchronously — typically sent, then delivered (or failed/undelivered).
6. Your system receives status via webhook (hooks[]) or polls GET …/hookInfo?messageId=<id> and handles failures if needed.

Technical implementation

Prerequisites

• Approved authentication template (copy-code) on 1MSG channel.
• User phone linked to the account, international format without +.
• Backend issues OTP, sends body + button, validates before password change.

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_CODE = "___";    // {{1}} otp code

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, code }) {
  assertConfigured({
    CHANNEL_ID,
    API_TOKEN,
    TEMPLATE_NAME,
    TEMPLATE_NAMESPACE,
    TEMPLATE_LANGUAGE,
    phone,
    code,
  });

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

  // params carries body and button blocks.
  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(code) }, // {{1}} otp code
        ],
      },
      {
        type: "button",
        sub_type: "url",
        index: "0",
        parameters: [{ type: "text", text: String(code) }],
      },
    ],
  };

  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;
}

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

module.exports = { sendTemplateMessage };

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