WhatsApp Send Platform

Overview

The platform is two things that share one goal — making it safe and fast for any Customapp project to send WhatsApp messages without every project owning its own WhatsApp Business Account, Meta token, or webhook.

Everything downstream of "who is allowed to send what to whom" is enforced the same way whether the key was handed out by an admin's CLI years ago or created by someone in the portal five minutes ago — they both end up as an entry in the same store that the send Lambda checks on every single request.

Architecture

There are two independent paths through the system that only meet at two points: the shared config the portal writes and the send Lambda reads, and the shared database both write their logs/state into. That separation is deliberate — the portal never sees the Meta access token, and the send path never touches the portal's database directly (it only reads the small allowlist config).

Walking through it

1. Sending a message starts with your app calling POST /v1/send on API Gateway with your x-api-key. API Gateway checks the key exists, isn't disabled, and hasn't blown its daily quota — all before your request ever reaches Lambda code.
2. The whatsapp-send Lambda looks the key up in a small Secrets Manager secret (whatsapp/sender-keys) to get its allowlist and default country code, checks your recipient against it, sanitizes the message text/template params (Meta rejects raw newlines), and calls the Meta Cloud API with the shared token from a separate secret (whatsapp/sender-token) — kept apart so allowlist churn never touches the actual credential.
3. Every outcome — sent, denied, or errored — is written as one structured JSON log line. A CloudWatch Logs subscription filter forwards matching lines to the audit-subscriber Lambda, which inserts a row into wa_send_audit. This is entirely decoupled from the send path — if Supabase is slow or down, your send still succeeds; only the usage dashboard lags.
4. Managing your account is a separate flow: your browser talks to the portal through send.customapp.co.za (a CloudFront distribution in front of a Lambda Function URL), which handles signup, login sessions, key/allowlist CRUD, usage queries, and admin actions — all backed by the wa_platform schema in the same Supabase project.
5. When you create or edit a key in the portal, it calls the same lib/provisioning.js module a platform admin's CLI (wa-admin) uses, so a key created in the browser and a key created from the command line can never race each other into a lost update. That module writes to both API Gateway (so the key can authenticate at all) and the sender-keys secret (so whatsapp-send knows the allowlist) — the dashed purple arrow above is that secret being read back on every single send.

What happens to a single send request

Zooming into the "Lambda: whatsapp-send" box above — this is the exact decision path every POST /v1/send call goes through, in order.

Account & key lifecycle

Two related but separate lifecycles: your account (one per organisation/project, needs one-time approval) and your API keys (as many as you want once your account is active, each with its own allowlist).

Getting started

1. Sign up at send.customapp.co.za/signup.html with your organisation/project name, email, and a password. This creates your account in pending state.
2. Wait for approval. A platform admin reviews new accounts in /admin.html. There's no self-approval by design — it's the one manual gate on an otherwise fully self-service platform. Ping whoever manages the platform if it's urgent.
3. Log in once you're active — you'll land on the dashboard.
4. Create an API key: give it a name (e.g. production, ci), a comma-separated allowlist of recipient numbers in E.164 without the + (e.g. 27833777500), and a default country code for local-format numbers. The key's actual value is shown once — copy it immediately, the portal never displays it again (only its API Gateway id, for management).
5. Send a test message — see the next section — with "dryRun": true first if you want to validate the key/allowlist without actually sending.

Sending messages

Base URL: https://wa.customapp.co.za. Auth header: x-api-key: <your key>. One endpoint, discriminated by mode. to is E.164 without the leading +.

Free-form text ("notify")

Sends free text if you're inside Meta's 24-hour customer-service window, and automatically falls back to an approved template if you're outside it — this is what almost every integration should use.

# curl
curl -X POST "https://wa.customapp.co.za/v1/send" \
  -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"mode":"notify","to":"27833777500","text":"Build #123 passed ✅"}'

Approved template

curl -X POST "https://wa.customapp.co.za/v1/send" -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"mode":"template","to":"27833777500","template":"booking_confirmation","params":["2026-07-18 | 08:20 | FRONT"]}'

Call-to-action button

curl -X POST "https://wa.customapp.co.za/v1/send" -H "x-api-key: $KEY" -H "content-type: application/json" \
  -d '{"mode":"cta","to":"27833777500","body":"Your report is ready","buttonText":"Open","url":"https://…"}'

Add "dryRun": true to any of the above to validate the key/allowlist/payload without actually sending (returns a fake id). GET /v1/health needs no key and returns {"status":"ok","version":"…"}.

Other languages

It's plain HTTPS + JSON — any language works:

# Python
import requests
requests.post(f"{URL}/v1/send", headers={"x-api-key": KEY},
              json={"mode": "notify", "to": "27833777500", "text": "from python"})

Node client

const { createWhatsAppClient } = require('.../clients/whatsapp-node');
const wa = createWhatsAppClient({ url: process.env.WHATSAPP_SEND_URL, apiKey: process.env.WHATSAPP_SEND_KEY });
await wa.notify('27833777500', 'Nightly job done');

MCP (Cursor / Claude Code)

The MCP server sends through the same endpoint with its own allowlist-scoped key, so an AI agent can't text arbitrary numbers. Add to ~/.cursor/mcp.json:

{ "mcpServers": { "whatsapp": {
  "command": "node",
  "args": ["/ABS/PATH/whatsapp-service/mcp/server.js"],
  "env": { "WHATSAPP_SEND_URL": "<url>", "WHATSAPP_SEND_KEY": "<mcp-key>" }
} } }

Exposes whatsapp_notify, whatsapp_send_template, whatsapp_send_cta.

Meta error codes you'll actually see

Managing your account

Everything below lives on the dashboard at send.customapp.co.za/dashboard.html once your account is active.

Portal API reference

For platform admins

Admins get an extra admin link to /admin.html. There's deliberately no self-service way to become an admin — it's granted with a direct SQL insert into wa_platform.wa_admins by whoever operates the platform (see docs/PLATFORM-OPERATIONS.md in the repo).

All account/key/allowlist changes — self-service or admin — are recorded in wa_platform.wa_events and shown on the admin page's event log, so there's always an answer to "who changed this and when".

Security & data handling

• The portal never sees or stores the Meta access token — it only manages the API-Gateway-key ↔ allowlist mapping, kept in a separate secret (whatsapp/sender-keys) from the token itself (whatsapp/sender-token).
• The wa_platform Postgres schema has Row-Level Security enabled and is only ever accessed with the Supabase service-role key from inside the portal Lambda — it's never exposed to the browser directly, and the anonymous/authenticated Postgres roles have no grants on it at all.
• All infrastructure runs in af-south-1 (Cape Town), including the shared self-hosted Supabase stack, for POPIA data-residency reasons.
• Sign-in uses Supabase Auth (shared GoTrue instance across several Customapp products). Public self-registration is disabled stack-wide, so account creation goes through the portal's own /api/signup, which uses the Auth admin API server-side instead.
• Personal API tokens are stored as one-way hashes, shown to you exactly once at creation time, same as API keys.
• Every send — successful, denied, or errored — is audited asynchronously and can't be lost by a client that doesn't check its own response (it's server-side, off the request path).

FAQ

My account has been pending for a while — what do I do?

Approval is a manual, one-time step by a platform admin (see For admins). Reach out to whoever operates the platform if it's been longer than expected.

Can I widen my allowlist to "send to anyone"?

Ask a platform admin for a wildcard (*) allowlist if your use case genuinely needs it (e.g. customer-facing transactional notifications). It's not self-service by default because a leaked wildcard key is a much bigger blast radius than a leaked scoped one.

Do I need to handle replies?

No — this number is send-only from your integration's point of view. Incoming replies and delivery-status webhooks are routed elsewhere. Write your messages as no-reply notifications.

My send succeeded but isn't showing in Usage yet

The usage dashboard is fed by an asynchronous CloudWatch → Lambda → Supabase pipeline (see the architecture diagram) that can lag by a few seconds. It never affects whether your message actually sent — check the 200 response and messageId from /v1/send itself as the source of truth.

Where's the source code?

The whatsapp-service repository — see docs/USAGE.md for the consumer-facing reference this guide is built on, and docs/PLATFORM-OPERATIONS.md for the deploy/operate runbook.