New route notification for dispatchers (API)

The scenario sends a manager or dispatcher contact a personalized WhatsApp template when a new delivery route or trip is created.

Try the demo View code example

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

{{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
“Route details”
button — fixed in the Meta template

WhatsApp Business API for new route or trip notification

When to use it

Reach for this scenario when your TMS creates or publishes a delivery route or trip and the responsible manager or dispatcher must know before they refresh email or log into the desktop portal. It fits fleet dispatch hubs alerting hub managers, B2B logistics teams notifying partner dispatchers about assigned trips, and integrators wiring TMS route-created webhooks into WhatsApp outbound.

Fewer missed departures

Route number, name and schedule summary arrive as four body variables on the manager's WhatsApp (MANAGER_PHONE), so assignment details land in a channel they check on the road instead of a portal tab they open too late.

Less time checking the portal

The static Route details URL button is fixed in the approved Meta template and opens the logistics portal from the message, so the manager does not hunt for the trip in the TMS first.

No manual dispatcher alerts

The TMS route-created event resolves the manager phone and route fields, then sends the personalised template automatically — no one retypes route context or remembers to ping the field team.

Fleet and OMS follow-up

Delivery result is logged after send, so fleet operations or the OMS can track which route notifications reached the responsible contact and retry on failure per platform rules.

Workflow

Trigger
The TMS creates or publishes a route and fires an event.
event · triggered
Capture event
The system resolves the manager phone and route fields.
phone: "+…"
Build & send
A personalized template message is built with four body variables and a static URL button.
POST /sendTemplate
Delivered
The manager contact receives the WhatsApp update and can open route details via the button.
delivered
Status tracked
Delivery result is logged; errors are handled according to platform rules.
status: "read"

Technical implementation

Prerequisites

1MSG API Key · How to get API Key
WhatsApp Business account · How to Connect WABA
WhatsApp Template · How to Approve WABA Template
Customer opt-in · How to Manage Customers Consent

Code examples

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===

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

TEMPLATE_NAME="___"                        # approved template name
TEMPLATE_NAMESPACE="___"                   # template namespace (required — send fails without it)
TEMPLATE_LANGUAGE="___"                    # template language code, e.g. "en"



# === Test data ===
MANAGER_PHONE="___"                 # manager phone in international format
TEST_MANAGERNAME="___"         # {{1}} manager name
TEST_TICKETNUMBER="___"         # {{2}} ticket number
TEST_TOPIC="___"         # {{3}} topic or subject
TEST_NEXTSTEP="___"         # {{4}} next step

PHONE_NORM="$(printf '%s' "$MANAGER_PHONE" | tr -cd '0-9')"

for pair in "CHANNEL_ID=$CHANNEL_ID" "API_TOKEN=$API_TOKEN" \
            "TEMPLATE_NAME=$TEMPLATE_NAME" "TEMPLATE_NAMESPACE=$TEMPLATE_NAMESPACE" \
            "TEMPLATE_LANGUAGE=$TEMPLATE_LANGUAGE" "MANAGER_PHONE=$MANAGER_PHONE" \
            "TEST_MANAGERNAME=$TEST_MANAGERNAME" \
            "TEST_TICKETNUMBER=$TEST_TICKETNUMBER" \
            "TEST_TOPIC=$TEST_TOPIC" \
            "TEST_NEXTSTEP=$TEST_NEXTSTEP"; do
    val="${pair#*=}"
    if [ -z "$val" ] || [ "$val" = "___" ]; then
        echo "Missing configuration value: ${pair%%=*}" >&2
        exit 1
    fi
done

if [ -z "$PHONE_NORM" ]; then
    echo "Error: phone number has no digits after normalization" >&2
    exit 1
fi

URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendTemplate"

# params carries body ONLY. Button text is fixed in the Meta template — no button param.

# {{1}} manager name → ${TEST_MANAGERNAME}
# {{2}} ticket number → ${TEST_TICKETNUMBER}
# {{3}} topic or subject → ${TEST_TOPIC}
# {{4}} next step → ${TEST_NEXTSTEP}
read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "template": "${TEMPLATE_NAME}",
  "namespace": "${TEMPLATE_NAMESPACE}",
  "language": { "policy": "deterministic", "code": "${TEMPLATE_LANGUAGE}" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "${TEST_MANAGERNAME}" },
        { "type": "text", "text": "${TEST_TICKETNUMBER}" },
        { "type": "text", "text": "${TEST_TOPIC}" },
        { "type": "text", "text": "${TEST_NEXTSTEP}" }
      ]
    }

  ]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${API_TOKEN}" \
    -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
    *'"sent":true'*) ok=1 ;;
    *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
    echo "Message sent to manager."
    echo "API response: $BODY"
else
    echo "Send failed. HTTP status: $HTTP_CODE" >&2
    echo "$BODY" >&2
    exit 1
fi

Response and delivery status

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 (looks like wamid.…) to correlate delivery callbacks.

200 OKResponse

{
  "sent": true,
  "message": "Sent to [email protected]",
  "description": "Message has been sent to the provider",
  "id": "wamid.HBgLMzgwNjM5..."
}

sent
Accepted for sending — not yet on the customer's phone
id
Store it; delivery callbacks and hookInfo are keyed on this

Delivery statuses and webhooks →

Common errors

Status	API response	Cause	Fix
200	Message was not sent: template is not defined	namespace, template or language is missing from the request body.	Send all three. Take namespace and the exact template name from GET /templates; language is an object: {"policy": "deterministic", "code": "en"}.
200	template name (…) does not exist in <language>	The template is approved in a different language than the one requested.	Use the exact language code the template was approved in (for example es_MX is not the same as es). Check it in GET /templates.
200	Message was not sent: provide chatId, phone, bsuid, or username	No recipient the channel could resolve.	Pass exactly one recipient: phone (country code plus number, digits only), chatId (for example [email protected]) or bsuid.