@damiangilgonzalez/harness 1.3.7

package/skills/whatsapp-telegram/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: whatsapp-telegram
+description: "Use when wiring an app or agent to message customers over the WhatsApp Cloud API or a Telegram bot — order updates, OTP codes, reminders, alerts and broadcasts — or when debugging undelivered messages, 24-hour-window errors, rejected templates, webhook signature verification, or rate limits and their retry headers. NOT the reply content you send (that is `customer-support`)."
+tags: [whatsapp, telegram, messaging, cloud-api, bot-api]
+recommends: [customer-support, webhooks, automation-flows, chatbot, nodejs]
+origin: risco
+---
+
+# 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
+
+| If the customer is... | Use | Why |
+| --- | --- | --- |
+| already on WhatsApp, identity-verified, you have their phone number | WhatsApp Cloud API | Highest reach + trust; but **template-gated** and **billed per message**. |
+| an opt-in bot subscriber (clicked "Start") | Telegram Bot API | Free, instant, dev-friendly, no template gate, but reach = people who joined your bot. |
+
+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):
+
+```bash
+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).
+
+| Window state | What you may send | Cost |
+| --- | --- | --- |
+| Open (user messaged < 24h ago) | Any free-form text / media / interactive | Free |
+| Open | Utility template | Free (in-window) |
+| Closed (no recent user message) | **Approved template only** | Billed per message (marketing/auth rates) |
+| Closed + you send free-form | nothing — **#131047** | n/a |
+
+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)
+
+```bash
+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."}}'
+```
+
+```ts
+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)
+
+```ts
+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.
+
+```ts
+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
+
+```bash
+curl -sS "https://api.telegram.org/bot${TG_TOKEN}/sendMessage" \
+  -d chat_id=123456789 \
+  --data-urlencode "text=Build *passed* ✅" \
+  -d parse_mode=MarkdownV2
+```
+
+```ts
+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`.
+
+### Rate limits (the silent killer)
+
+- Broadcast ceiling: **~30 messages/second** across all chats.
+- Same chat: **~1 message/second**.
+- Exceed either → **HTTP 429** with a JSON `parameters.retry_after` (seconds). **Honor it**: sleep `retry_after` seconds, then retry. Do not blast-retry — you will be throttled harder.
+- Need more than 30/s? Enable **Paid Broadcasts** via @BotFather (up to 1000 msg/s, 0.1 Telegram Stars per excess message).
+
+```ts
+async function tgSend(payload: object, tries = 5): Promise<Response> {
+  for (let i = 0; i < tries; i++) {
+    const res = await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/sendMessage`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    if (res.status !== 429) return res;
+    const { parameters } = await res.json();
+    await new Promise((r) => setTimeout(r, (parameters?.retry_after ?? 1) * 1000));
+  }
+  throw new Error("Telegram: rate-limited after retries");
+}
+```
+
+### Inbound: setWebhook XOR getUpdates
+
+Pick exactly **one** — never run both, they conflict.
+
+- **setWebhook(url, ...)** — Telegram POSTs updates to your URL. Set a `secret_token`; Telegram echoes it back in the `X-Telegram-Bot-Api-Secret-Token` header — verify it. Optional `allowed_updates` (filter types) and `max_connections` (1–100, default 40).
+- **getUpdates** — long-poll loop, good for local dev / single-instance bots. Calling `getUpdates` while a webhook is set returns an error; call `deleteWebhook` first.
+
+Generic receiver design (retries, idempotency) → `webhooks`.
+
+---
+
+## Cross-cutting rules
+
+1. **Tokens from env only.** A leaked `WA_TOKEN` or `TG_TOKEN` is an account takeover. No inline secrets, ever.
+2. **Pin the Graph API version.** Versionless URLs drift and break payloads silently.
+3. **Respect windows and rate limits.** WhatsApp: branch on the 24h window. Telegram: honor `retry_after`.
+4. **Idempotency on retries.** A network retry can double-send; key sends on your own order/event id and dedupe.
+5. **Capture the response message id** (WhatsApp `messages[0].id`, Telegram `result.message_id`) — your only handle for delivery tracing.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Free-form WhatsApp send to a customer who hasn't messaged in days | Send an approved template to re-engage | Out-of-window free-form fails with **#131047**. |
+| `POST graph.facebook.com/{id}/messages` (no version) | `POST .../v25.0/{id}/messages` | Versionless drifts onto Meta's default and breaks payload shape. |
+| `Authorization: Bearer EAAxxx...` hardcoded | `Bearer ${process.env.WA_TOKEN}` | Hardcoded tokens leak in git/logs = account takeover. |
+| Retry immediately after a Telegram 429 | Sleep `retry_after` seconds, then retry | Blast-retrying gets you throttled harder, not faster. |
+| `setWebhook` AND a `getUpdates` loop | Pick exactly one | They conflict; `getUpdates` errors while a webhook is set. |
+| Process inbound WhatsApp POST without checking `X-Hub-Signature-256` | Verify HMAC-SHA256 with app secret | Unsigned events are forgeable; you'd act on spoofed messages. |
+| Reasoning about WhatsApp "per-conversation" cost | Per-**message** since 2025-07-01 | Conversation pricing is deprecated; estimates will be wrong. |
+| Sending raw user text as `MarkdownV2` | Escape reserved chars, or use `HTML` | Unescaped `.` `-` `!` etc. 400 the call. |
+
+## References
+
+- `references/whatsapp-cloud-api.md` — full payload shapes (text/template/media/interactive), template component JSON, error codes (#131047, #131026, #100, template errors), webhook payload + signature verify, pricing category table, 2026 policy.
+- `references/telegram-bot-api.md` — messaging method catalog, MarkdownV2 escape table, setWebhook + getUpdates examples, 429 backoff, Paid Broadcasts.

package/skills/whatsapp-telegram/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — whatsapp-telegram
+
+These cases are LLM-graded. `should_trigger` / `should_not_trigger` check that the skill's
+description and body route correctly: each `should_trigger` prompt (including a Catalan and a
+non-obvious error-code phrasing) must select this skill, while each `should_not_trigger` prompt
+must defer to the named sibling (`route_to`). The `capability` case is scored against its
+`must_include` rubric — a grader reads the skill body + references and confirms each bullet is
+satisfiable (pinned `v25.0` endpoint, env-sourced token, `messaging_product` body, 24h-window
+branch with #131047, captured message id). Run them with the repo's eval runner pointed at this
+skill directory; there is no live API call — grading is on the produced guidance, not on sending a
+real message.

package/skills/whatsapp-telegram/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: whatsapp-telegram
+
+should_trigger:
+  - prompt: "Send an order-confirmation WhatsApp message to a customer via the Cloud API"
+    why: Core WhatsApp Cloud API send — the central job of this skill.
+  - prompt: "My WhatsApp sends return error 131047, how do I re-engage the user?"
+    why: Non-obvious — #131047 is the closed-24h-window error; the fix is sending an approved template.
+  - prompt: "Build a Telegram bot that broadcasts alerts to subscribers and handle 429 retry_after"
+    why: Telegram send plus the rate-limit/backoff rule this skill owns.
+  - prompt: "Vull enviar una plantilla de WhatsApp d'avis de cita als clients"
+    why: Catalan phrasing for a WhatsApp template send (appointment-reminder template).
+  - prompt: "Set up the WhatsApp inbound webhook and verify the X-Hub-Signature-256 header"
+    why: Non-obvious WhatsApp-specific webhook setup (verify token + HMAC signature).
+  - prompt: "Should I use setWebhook or getUpdates for my Telegram bot?"
+    why: Telegram inbound decision — the two modes are mutually exclusive, a known footgun.
+  - prompt: "Why are my WhatsApp template blasts being billed per message now instead of per conversation?"
+    why: Non-obvious — pricing changed to per-message on 2025-07-01; agent must know the current model.
+
+should_not_trigger:
+  - prompt: "Write the actual support reply text and triage this angry customer"
+    route_to: customer-support
+    why: Content/tone and triage of the reply, not the transport pipe.
+  - prompt: "Plan our week's posts across LinkedIn, Instagram and TikTok"
+    route_to: social-publisher
+    why: Social content calendar and multi-platform posting, not 1:1 messaging APIs.
+  - prompt: "Write a cold first-touch DM sequence to prospects who never replied"
+    route_to: cold-outreach
+    why: First-touch outreach copy and cadence, not message delivery plumbing.
+  - prompt: "Design a generic webhook receiver with retries and idempotency for any provider"
+    route_to: webhooks
+    why: Abstract receiver design; this skill covers only WhatsApp/Telegram-specific setup.
+  - prompt: "When a Stripe payment succeeds, message the customer on WhatsApp — orchestrate the whole flow"
+    route_to: automation-flows
+    why: Cross-tool multi-step orchestration, not a single send implementation.
+
+capability:
+  - scenario: "Implement a function that messages a WhatsApp customer: send a free-form text if they messaged within the last 2 hours, otherwise send an approved template. Use the Cloud API."
+    must_include:
+      - "Endpoint pins the Graph version, e.g. https://graph.facebook.com/v25.0/{PHONE_NUMBER_ID}/messages"
+      - "Bearer token read from env (e.g. process.env.WA_TOKEN), never hardcoded"
+      - 'Body includes messaging_product: "whatsapp", to, and type'
+      - "Branches on the 24-hour window: in-window -> free-form text, out-of-window -> template"
+      - "Explains that out-of-window free-form fails with error #131047"
+      - "Captures the response message id (messages[0].id) for delivery tracing"

package/skills/whatsapp-telegram/references/telegram-bot-api.md

@@ -0,0 +1,91 @@
+# Telegram Bot API reference
+
+Base: `https://api.telegram.org/bot${TG_TOKEN}/<METHOD>`. Token from @BotFather, kept in env. Bot API 10.0 (2026-05-08). Facts accessed 2026-06-02.
+
+## Messaging method catalog
+
+| Method | Use |
+| --- | --- |
+| `sendMessage` | Text (≤4096 chars), `parse_mode`, `reply_markup`. |
+| `sendPhoto` | Photo by `photo` URL/file_id, `caption` ≤1024. |
+| `sendDocument` | Arbitrary file. |
+| `sendMediaGroup` | 2–10 items as an album. |
+| `editMessageText` | Edit a previously sent message (good for live status). |
+| `deleteMessage` | Remove a message. |
+| `answerCallbackQuery` | Acknowledge an inline-button tap (call within seconds or the client shows a spinner). |
+| `setMyCommands` | Register the `/` command menu. |
+
+Successful responses are `{ "ok": true, "result": {...} }`. Capture `result.message_id`.
+
+## MarkdownV2 escaping
+
+In `parse_mode=MarkdownV2`, escape these reserved chars with `\` everywhere they are literal text:
+
+```
+_ * [ ] ( ) ~ ` > # + - = | { } . !
+```
+
+```ts
+const escapeMdV2 = (s: string) => s.replace(/[_*[\]()~`>#+\-=|{}.!]/g, "\\$&");
+```
+Inside `pre`/`code` entities only `` ` `` and `\` need escaping. When in doubt for dynamic text, use `parse_mode=HTML` (escape only `< > &`).
+
+## 4096-char chunking
+```ts
+function chunk(text: string, max = 4096): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += max) out.push(text.slice(i, i + max));
+  return out;
+}
+```
+
+## Rate limits + 429 backoff
+
+- ~30 msg/s broadcast across chats; ~1 msg/s to the same chat.
+- 429 body: `{ "ok": false, "error_code": 429, "parameters": { "retry_after": 5 } }`. Sleep `retry_after` seconds, retry.
+- Paid Broadcasts (enable via @BotFather): up to 1000 msg/s, 0.1 Telegram Stars per message above the free tier.
+
+```ts
+async function call(method: string, payload: object, tries = 5): Promise<any> {
+  for (let i = 0; i < tries; i++) {
+    const res = await fetch(`https://api.telegram.org/bot${process.env.TG_TOKEN}/${method}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+    const json = await res.json();
+    if (json.ok) return json.result;
+    if (json.error_code === 429) {
+      await new Promise((r) => setTimeout(r, (json.parameters?.retry_after ?? 1) * 1000));
+      continue;
+    }
+    throw new Error(`Telegram ${method}: ${json.error_code} ${json.description}`);
+  }
+  throw new Error(`Telegram ${method}: rate-limited after ${tries} tries`);
+}
+```
+
+## Inbound: setWebhook XOR getUpdates (never both)
+
+### setWebhook
+```bash
+curl -sS "https://api.telegram.org/bot${TG_TOKEN}/setWebhook" \
+  -d url=https://example.com/tg \
+  -d secret_token=$(openssl rand -hex 16) \
+  --data-urlencode 'allowed_updates=["message","callback_query"]' \
+  -d max_connections=40
+```
+Telegram echoes the `secret_token` in the `X-Telegram-Bot-Api-Secret-Token` request header on each update — compare it and reject mismatches. `max_connections` range 1–100, default 40. `allowed_updates` filters update types.
+
+### getUpdates (long-poll, dev / single instance)
+```ts
+let offset = 0;
+for (;;) {
+  const updates = await call("getUpdates", { offset, timeout: 30 });
+  for (const u of updates) {
+    offset = u.update_id + 1; // ack: advance past processed updates
+    // handle u.message / u.callback_query
+  }
+}
+```
+Calling `getUpdates` while a webhook is set returns an error — `deleteWebhook` first. Run exactly one delivery mode.

package/skills/whatsapp-telegram/references/whatsapp-cloud-api.md

@@ -0,0 +1,103 @@
+# WhatsApp Cloud API reference
+
+Endpoint base: `https://graph.facebook.com/v25.0/{WA_PHONE_NUMBER_ID}/messages` (POST, `Authorization: Bearer ${WA_TOKEN}`). v25.0 current (2026-02-18); v24.0 is the floor. Facts accessed 2026-06-02.
+
+## Message payload shapes
+
+Every body starts with `messaging_product: "whatsapp"`, `to`, `type`.
+
+### text
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "text",
+  "text": { "preview_url": false, "body": "Your order shipped." } }
+```
+
+### template
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "template",
+  "template": {
+    "name": "order_update",
+    "language": { "code": "es" },
+    "components": [
+      { "type": "header", "parameters": [ { "type": "text", "text": "1234" } ] },
+      { "type": "body",   "parameters": [ { "type": "text", "text": "Maria" }, { "type": "currency", "currency": { "fallback_value": "€19.90", "code": "EUR", "amount_1000": 19900 } } ] },
+      { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "track/1234" } ] }
+    ]
+  } }
+```
+Parameter order MUST match the `{{1}} {{2}}` placeholders in the approved template.
+
+### image / document (media)
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "image",
+  "image": { "link": "https://example.com/receipt.png", "caption": "Receipt" } }
+```
+Use `link` (public URL) or a pre-uploaded `id` from the media endpoint.
+
+### interactive (buttons / list)
+```json
+{ "messaging_product": "whatsapp", "to": "34699999999", "type": "interactive",
+  "interactive": {
+    "type": "button",
+    "body": { "text": "Confirm your slot?" },
+    "action": { "buttons": [
+      { "type": "reply", "reply": { "id": "yes", "title": "Yes" } },
+      { "type": "reply", "reply": { "id": "no",  "title": "No" } }
+    ] } } }
+```
+Interactive messages are free-form → only deliver inside the open 24h window.
+
+## Common error codes
+
+| Code | Meaning | Fix |
+| --- | --- | --- |
+| 131047 | Re-engagement required (24h window closed) | Send an approved template, not free-form. |
+| 131026 | Message undeliverable | Recipient not on WhatsApp / number invalid / not opted in. |
+| 131051 | Unsupported message type | Check `type` + matching object key. |
+| 100 | Invalid parameter | Bad `to` format, missing `messaging_product`, malformed component. |
+| 132000–132xxx | Template errors | Param count mismatch, template paused/disabled, language mismatch. |
+| 80007 / 130429 | Rate limit hit | Back off; throttle send rate. |
+
+## Inbound webhook
+
+### GET verification (one-time, on subscribe)
+Meta calls `GET /your-callback?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...`. If `hub.verify_token` equals your configured value, respond `200` with the raw `hub.challenge` as the body.
+
+### POST event signature verify
+```ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function verifyMeta(rawBody: Buffer, header = ""): boolean {
+  const expected = "sha256=" + createHmac("sha256", process.env.WA_APP_SECRET!).update(rawBody).digest("hex");
+  const a = Buffer.from(expected, "utf8");
+  const b = Buffer.from(header, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+```
+Verify against the **raw** request body (not re-serialized JSON) or the HMAC will not match.
+
+### Event payload (inbound message)
+```json
+{ "object": "whatsapp_business_account",
+  "entry": [ { "id": "WABA_ID", "changes": [ { "field": "messages", "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "phone_number_id": "PHONE_NUMBER_ID" },
+    "contacts": [ { "wa_id": "34699999999" } ],
+    "messages": [ { "from": "34699999999", "id": "wamid.XXX", "timestamp": "1733400000", "type": "text", "text": { "body": "hi" } } ]
+  } } ] } ] }
+```
+An inbound `messages[]` entry opens (or refreshes) the 24h window for that `from`.
+
+## Pricing categories (per-message since 2025-07-01)
+
+| Category | When | Cost |
+| --- | --- | --- |
+| marketing | promos, offers, re-engagement | Paid per message, country rate. |
+| utility | order/account updates tied to a transaction | Free inside open window; paid out-of-window. |
+| authentication | OTP / login codes | Paid per message, country rate. |
+| service | free-form replies inside the window | Free. |
+
+Free-entry-point conversations (user taps an ad/CTA) are free for 72h. Rates vary by recipient country code; check the current Meta rate card.
+
+## Policy (2026)
+Since 2026-01-15, Meta prohibits general-purpose AI assistants (open ChatGPT-wrapper bots with no clear business purpose) on WhatsApp. Scoped business automation is allowed.

package/skills/whatsapp-telegram/scripts/verify.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — whatsapp-telegram integration gate. Read-only, never writes.
+#
+# Statically greps the integration code in the TARGET dir (arg 1, default: cwd) for the known
+# WhatsApp/Telegram footguns this skill warns about:
+#   1. Every WhatsApp Graph send URL pins a version — fail on a versionless graph.facebook.com call.
+#   2. No hardcoded WhatsApp bearer tokens (EAA...) or Telegram bot tokens (\d{8,10}:[A-Za-z0-9_-]{35}).
+#   3. A file that polls getUpdates must not also call setWebhook (mutually exclusive).
+#   4. Advisory: if a free-form WhatsApp send exists, a template-send path should exist too.
+#
+# Artifact-conditional: if no integration files are found, exit 0 with a [skip] (safe to run
+# anywhere — an empty/clean target NEVER fails). Exit non-zero ONLY on a real footgun, with paths.
+#
+# Portability: stock macOS bash 3.2 — no mapfile, no associative arrays, arrays initialised.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+TARGET="${1:-$(pwd)}"
+if [ ! -d "$TARGET" ]; then
+  skip "target '$TARGET' is not a directory — nothing to check"
+  exit 0
+fi
+
+# Collect candidate integration source files (skip deps / vcs / build output). Initialised array.
+FILES=()
+while IFS= read -r -d '' f; do
+  FILES+=("$f")
+done < <(find "$TARGET" \
+  \( -path '*/node_modules' -o -path '*/.git' -o -path '*/dist' -o -path '*/build' -o -path '*/.next' -o -path '*/vendor' \) -prune -o \
+  -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.mjs' -o -name '*.py' -o -name '*.go' -o -name '*.rb' -o -name '*.sh' -o -name '*.json' \) -print0 2>/dev/null)
+
+# Keep only files that actually touch one of the two platforms.
+RELEVANT=()
+for f in "${FILES[@]:-}"; do
+  [ -n "$f" ] || continue
+  if grep -Eql 'graph\.facebook\.com|api\.telegram\.org|messaging_product' "$f" 2>/dev/null; then
+    RELEVANT+=("$f")
+  fi
+done
+
+if [ "${#RELEVANT[@]:-0}" -eq 0 ]; then
+  skip "no WhatsApp/Telegram integration files found under $TARGET — nothing to check"
+  exit 0
+fi
+ok "scanning ${#RELEVANT[@]} integration file(s)"
+
+# ---- 1. WhatsApp Graph URL must pin a version ----
+HITS="$(grep -EnH 'graph\.facebook\.com/[^v"'"'"'\`/[:space:]]' "${RELEVANT[@]}" 2>/dev/null \
+  | grep -Ev 'graph\.facebook\.com/v[0-9]+' || true)"
+if [ -n "$HITS" ]; then
+  err "versionless graph.facebook.com URL (pin v25.0):"
+  printf '%s\n' "$HITS"
+else
+  ok "WhatsApp Graph URLs are version-pinned"
+fi
+
+# ---- 2. no hardcoded tokens ----
+# WhatsApp access tokens start EAA...; Telegram bot tokens look like 123456789:AA....(35 chars).
+TOK="$(grep -EnH "EAA[A-Za-z0-9_-]{20,}|[0-9]{8,10}:[A-Za-z0-9_-]{35}" "${RELEVANT[@]}" 2>/dev/null || true)"
+if [ -n "$TOK" ]; then
+  err "hardcoded token literal (move to an env var):"
+  printf '%s\n' "$TOK"
+else
+  ok "no hardcoded WhatsApp/Telegram token literals"
+fi
+
+# ---- 3. setWebhook and getUpdates not in the same file ----
+for f in "${RELEVANT[@]}"; do
+  if grep -Eql 'getUpdates' "$f" 2>/dev/null && grep -Eql 'setWebhook' "$f" 2>/dev/null; then
+    err "both getUpdates and setWebhook in one file (pick one): $f"
+  fi
+done
+if [ "$EXIT" -eq 0 ]; then ok "no getUpdates+setWebhook conflict"; fi
+
+# ---- 4. advisory: free-form send should pair with a template path ----
+if grep -Eql '"type"[[:space:]]*:[[:space:]]*"text"|type:[[:space:]]*"text"' "${RELEVANT[@]}" 2>/dev/null; then
+  if ! grep -Eql '"type"[[:space:]]*:[[:space:]]*"template"|type:[[:space:]]*"template"' "${RELEVANT[@]}" 2>/dev/null; then
+    skip "advisory: free-form WhatsApp send found but no template path — out-of-window sends will hit #131047"
+  fi
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found footguns"; fi
+exit "$EXIT"