WhatsApp Business API for new route or trip notification

Use case overview

The scenario sends a manager or dispatcher contact a personalized WhatsApp template when a new delivery route or trip is created. The message includes the contact name, route or trip number, route name or region, and schedule summary. A static URL button opens route details in the logistics portal.

Template example

Hello, {{1}}! A new route #{{2}} has been created: "{{3}}". {{4}}.

[Route details]

The route details URL button is fixed in the Meta template — only body variables are sent via the API. Recipient is MANAGER_PHONE.

Variables and purpose

• {{1}} — manager or dispatcher contact name
• {{2}} — route or trip number
• {{3}} — route name or service region
• {{4}} — departure window, stop count, or next operational step

Filled-in example

Hello, Manager Anna! A new route #RT-8842 has been created: "North sector, 12 stops". Departure today at 8:00 AM from the hub at 5 Logistics Street..

[Route details]

When to use it

• fleet dispatch
• b2b logistics
• integrators

Business value

• TMS emits a new-route or trip-created event
• System resolves the manager phone and route summary fields
• Template message is built with four body variables and a static URL button
• Manager contact receives WhatsApp confirmation about the new route
• Route assignment status is logged for fleet or OMS follow-up

Workflow

1. The TMS creates or publishes a route and fires an event.
2. The system resolves the manager phone and route fields.
3. A personalized template message is built with four body variables and a static URL button.
4. The manager contact receives the WhatsApp update and can open route details via the button.
5. Delivery result is logged; errors are handled according to platform rules.
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

• A 1MSG account with WhatsApp Business API connected and an approved message template.
• Manager contact phone in international format (without + and spaces).
• Route data: contact name, route number, route label, schedule note.

Code examples

Node.js

#!/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 MANAGER_PHONE = "___";            // manager phone in international format
const TEST_MANAGERNAME = "___";    // {{1}} manager name
const TEST_TICKETNUMBER = "___";    // {{2}} ticket number
const TEST_TOPIC = "___";    // {{3}} topic or subject
const TEST_NEXTSTEP = "___";    // {{4}} next step

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

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

  // params carries body ONLY. Button text is fixed in the Meta template — no button param.
  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(managerName) }, // {{1}} manager name
          { type: "text", text: String(ticketNumber) }, // {{2}} ticket number
          { type: "text", text: String(topic) }, // {{3}} topic or subject
          { type: "text", text: String(nextStep) }, // {{4}} next step
        ],
      },
    ],
  };

  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 manager.");
  console.log("API response:", raw);
  return data;
}

if (require.main === module) {
  sendTemplateMessage({
    phone: MANAGER_PHONE,
    managerName: TEST_MANAGERNAME,
    ticketNumber: TEST_TICKETNUMBER,
    topic: TEST_TOPIC,
    nextStep: TEST_NEXTSTEP,
  }).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.

CTA

Ready to use new route or trip notification? Connect your 1MSG channel and run the code examples above.

Related

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