Whatsapp Telegram

WhatsApp & Telegram messaging

You are wiring code that pushes messages to real customers. Both platforms have sharp, silent rules: code that passes in testing 403s or drops in production. This skill is the transport pipe — endpoints, auth, windows, rate limits, webhooks. The words you send are out of scope (that is ../customer-support/SKILL.md).

Pick your platform

You can ship both — but the rules do not transfer. WhatsApp's 24-hour window and template gate have no Telegram equivalent; Telegram's 30 msg/s ceiling has no WhatsApp equivalent.

WhatsApp Cloud API

Env + endpoint

Never hardcode credentials. Four values come from the Meta App + WhatsApp Business Account (WABA):

WA_TOKEN=...            # Bearer access token (System User token in prod, not a temp one)
WA_PHONE_NUMBER_ID=...  # the sending number's ID, not the phone number itself
WA_WABA_ID=...          # WhatsApp Business Account ID (for template management)
WA_APP_SECRET=...       # app secret, used to verify inbound webhook signatures

Send endpoint, with the version pinned in the path:

POST https://graph.facebook.com/v25.0/{WA_PHONE_NUMBER_ID}/messages
Authorization: Bearer ${WA_TOKEN}
Content-Type: application/json

Pin the version (v25.0 is current, announced 2026-02-18; v24.0 is the lowest still supported). Why: a versionless URL drifts onto whatever Meta defaults to and breaks payload shape without warning. Never call graph.facebook.com/{id}/messages bare.

The 24-hour customer-service window (the load-bearing rule)

A free-form message can ONLY be sent inside a 24-hour window that the user opened by messaging you. Outside that window you MUST send a pre-approved template to re-engage — a free-form send out-of-window fails with error #131047 (re-engagement message required).

So branch on window state before every send: in-window → free-form is fine; otherwise → reach for a template.

Send free-form text (in-window)

curl -sS -X POST "https://graph.facebook.com/v25.0/${WA_PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer ${WA_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"34699999999","type":"text","text":{"body":"Your order #1234 shipped."}}'

const res = await fetch(
  `https://graph.facebook.com/v25.0/${process.env.WA_PHONE_NUMBER_ID}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WA_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      to: "34699999999",
      type: "text",
      text: { body: "Your order #1234 shipped." },
    }),
  },
);
const data = await res.json();
const messageId = data.messages?.[0]?.id; // capture it — your only handle for delivery tracing

Always log messages[0].id from the response. It is the only key that ties a send to the later delivery/read webhook.

Send a template (out-of-window or any business-initiated message)

const body = {
  messaging_product: "whatsapp",
  to: "34699999999",
  type: "template",
  template: {
    name: "appointment_reminder",      // must be APPROVED in WhatsApp Manager first
    language: { code: "ca" },
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", text: "Maria" },
          { type: "text", text: "dimarts a les 10:00" },
        ],
      },
    ],
  },
};

Templates are created and approved via WhatsApp Business Manager or the POST /{WA_WABA_ID}/message_templates API before they can be sent. Variable order in parameters must match the {{1}} {{2}} placeholders in the approved template body.

Template categories + cost

Four categories: marketing, utility, authentication, service. Category drives both policy and price.

Billing changed on 2025-07-01: conversation-based pricing is deprecated, replaced by per-message pricing — you are billed per delivered template message, rate by category + recipient country. Free-form messages inside an open window are free; utility templates inside an open window are free. Do not reason about old "per-conversation" pricing — it is gone. Full category/price table → references/whatsapp-cloud-api.md.

Policy note: since 2026-01-15 Meta prohibits general-purpose AI assistants (open ChatGPT-wrapper bots) on WhatsApp. Business automation is fine; a generic chatbot is not. For conversational design see ../customer-support/SKILL.md.

Inbound webhook

1. GET verify — Meta calls your callback URL once with hub.mode, hub.verify_token, hub.challenge. If hub.verify_token matches your configured token, echo back hub.challenge (plain, 200).
2. POST events — every event POST carries X-Hub-Signature-256: sha256=<hmac>. Compute HMAC-SHA256(rawBody, WA_APP_SECRET) and compare. Reject unsigned/mismatched bodies — without this anyone can forge inbound events.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyMeta(rawBody: string, header = ""): boolean {
  const expected =
    "sha256=" + createHmac("sha256", process.env.WA_APP_SECRET!).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}

For retry/idempotency/dedupe patterns of the receiver itself, this is the WhatsApp-specific setup only — generic receiver design → webhooks.

Telegram Bot API

Token + base URL

Get a token from @BotFather. Every method is an HTTP call:

https://api.telegram.org/bot${TG_TOKEN}/<METHOD>

Token from env (TG_TOKEN), never inline — it embeds in the URL and leaks in logs. Current Bot API is 10.0 (released 2026-05-08).

sendMessage

curl -sS "https://api.telegram.org/bot${TG_TOKEN}/sendMessage" \
  -d chat_id=123456789 \
  --data-urlencode "text=Build *passed* ✅" \
  -d parse_mode=MarkdownV2

await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/sendMessage`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ chat_id: 123456789, text: "Build passed", parse_mode: "HTML" }),
});

parse_mode is HTML | MarkdownV2 | Markdown (legacy). MarkdownV2 requires escaping the reserved set _*[]()~\>#+-=|{}.!with a backslash, or the call 400s. HTML is safer for dynamic text. Text cap is **4096 chars** per message — split longer payloads into chunks. Escape table + chunking →references/telegram-bot-api.md`.