GATE Watcher — WhatsApp Business

Self-hosted daemon that connects to the WhatsApp Business Cloud API and pushes message events to GATE cloud for security processing. Your access token never leaves your machine.

How it works

Meta Cloud API                  Your Machine (Watcher)              GATE Cloud
┌──────────────┐  webhook POST  ┌──────────────────────┐        ┌──────────────────┐
│ WhatsApp     │───────────────>│ Local webhook server  │───────>│ Security pipeline │
│ Business API │                │ (token stays HERE)    │<───────│ (redact, policy,  │
└──────────────┘                │                       │ poll   │  audit, forward)  │
                                └──────────────────────┘        └──────────────────┘

Quick Start (CLI)

cd gate-watcher-whatsapp-business
npm install

# Create .env (or pass env vars directly)
cp .env.example .env
# Fill in GATE_KEY, GATE_INTEGRATION_ID, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID

npm start

The watcher starts a local webhook server (default port 3100). Point your Meta webhook URL to your public address (e.g. via ngrok).

Embed in Your App (SDK)

npm install @anura-gate/watcher-whatsapp-business

const { GateWhatsAppBusinessWatcher } = require("@anura-gate/watcher-whatsapp-business");

const watcher = new GateWhatsAppBusinessWatcher({
  gateKey: "gk-xxx",
  integrationId: "int_xxx",
  accessToken: "EAAxxxxx",
  phoneNumberId: "1234567890",
  verifyToken: "my-secret-verify-token",
  webhookPort: 3100,
});

watcher.on("webhook_listening", (port, verifyToken) => {
  console.log(`Webhook listening on port ${port} (verify token: ${verifyToken})`);
  console.log("Point Meta to: https://your-domain.com/webhook");
});

watcher.on("ready", (phoneInfo) => {
  console.log(`WhatsApp Business connected: ${phoneInfo.display_phone_number}`);
});

// Every incoming message after GATE security processing
watcher.on("message", (message, result) => {
  console.log(`From: ${message.from}, Text: ${message.text?.body}`);
  console.log(`Security actions: ${result.securityActions}`);
  console.log(`Blocked: ${result.blocked}`);
});

// Message status updates (sent, delivered, read, failed)
watcher.on("status_update", (status, result) => {
  console.log(`Message ${status.id}: ${status.status}`);
});

watcher.on("action_result", ({ action, success, error }) => {
  console.log(`${action}: ${success ? "done" : error}`);
});

await watcher.start();

// Later...
await watcher.stop();

SDK Events

| Event | Args | Description | |---|---|---| | webhook_listening | (port, verifyToken) | Local webhook server started | | webhook_verified | — | Meta successfully verified the webhook | | ready | (phoneInfo) | Connected and webhook verified | | message | (message, result) | Incoming message processed by GATE | | status_update | (status, result) | Message delivery status update | | action | (action) | Outbound action received from GATE queue | | action_result | ({ actionId, action, success, result, error }) | Outbound action completed | | gate_error | ({ path, status, error }) | GATE API call failed | | limit_reached | (type) | Plan limit hit | | stopped | — | Watcher fully shut down |

SDK Options

| Option | Required | Default | Description | |---|---|---|---| | gateKey | Yes | — | Virtual key (gk-xxx) | | integrationId | Yes | — | Integration ID (int_xxx) | | accessToken | Yes | — | Meta permanent access token (EAAxxxxx) | | phoneNumberId | Yes | — | WhatsApp Business phone number ID | | gateUrl | No | "https://anuragate.com" | GATE cloud URL | | verifyToken | No | random | Webhook verify token for Meta handshake | | webhookPort | No | 3100 | Local webhook server port | | heartbeatInterval | No | 30000 | ms between heartbeats | | pollInterval | No | 3000 | ms between outbound polls | | sessionId | No | — | Session ID for multi-tenant use | | sessionLabel | No | — | Human-readable session label | | sessionMetadata | No | {} | Arbitrary metadata for the session |

Setup

1. Create a Meta Business Account and a WhatsApp Business app in the Meta Developer Portal
2. Add the WhatsApp product to your app
3. Go to WhatsApp → API Setup to get your Phone Number ID and generate a Permanent Access Token
4. Start the watcher — it will listen for webhook events on webhookPort
5. Expose the webhook port publicly (e.g. ngrok http 3100) and configure it in Meta → WhatsApp → Configuration → Webhook URL: https://your-domain/webhook
6. Set the Verify Token to match your verifyToken option
7. Subscribe to webhook fields: messages
8. Go to GATE Dashboard → Integrations → Add Integration, select WhatsApp Business, copy the Integration ID
9. Copy your Virtual Key from the Keys page

Environment Variables

| Variable | Required | Description | |---|---|---| | GATE_KEY | Yes | Your GATE virtual key | | GATE_INTEGRATION_ID | Yes | Integration ID from the dashboard | | WHATSAPP_ACCESS_TOKEN | Yes | Meta permanent access token | | WHATSAPP_PHONE_NUMBER_ID | Yes | WhatsApp Business phone number ID | | WHATSAPP_VERIFY_TOKEN | No | Webhook verify token (auto-generated if omitted) | | WHATSAPP_WEBHOOK_PORT | No | Local webhook server port (default: 3100) | | GATE_URL | No | Custom GATE cloud URL | | WEB_PORT | No | Port for the dev dashboard (CLI only) |

Security model

• Meta access token stored in .env on YOUR machine
• GATE cloud never sees or stores your credentials
• All message content passes through GATE's security pipeline
• Webhook runs locally — Meta pushes directly to your machine
• Billing, limits, and security enforced server-side