> **Community source release (MIT).** Self-host using your own credentials. No NabuxAI production accounts or hosted-service access are included.

# WhatsApp MCP by Nabux

**Multi-user, multi-number WhatsApp MCP Gateway powered by Meta's official WhatsApp Cloud API.**

> Official API, Nabux gateway: WhatsApp messaging and webhook operations use Meta's supported WhatsApp Business Platform / Cloud API. The MCP server itself is built and operated by Nabux; it is not a Meta-authored MCP server.

Production target: **https://wa.nabuxai.com**  
MCP endpoint: **https://wa.nabuxai.com/mcp**  
Webhook callback: **https://wa.nabuxai.com/webhook**

## What this gateway does

- Onboards WhatsApp Business accounts through **Meta Embedded Signup**.
- Supports multiple users and multiple WhatsApp Business phone numbers.
- Keeps Meta access tokens encrypted at rest on the Nabux server.
- Exposes OAuth 2.1 + PKCE for ChatGPT, Claude, Cursor and other MCP clients.
- Receives Meta WhatsApp webhooks, verifies `X-Hub-Signature-256`, and stores messages/status events.
- Lets an authenticated MCP client search only its own webhook-backed inbox/history.
- Sends text, templates and media through the official Cloud API.
- Enforces a local 24-hour check before free-form text/media sends; use approved templates to start/reopen opted-in conversations.
- Exposes an opaque Account Key for trusted Nabux server-to-server integrations.

It does **not** use WhatsApp Web scraping, browser automation, cookies, QR-linked-device reverse engineering, private APIs or user passwords.

## Architecture

```text
Customer browser
  -> wa.nabuxai.com/connect
  -> Meta Embedded Signup
  -> WhatsApp Business Account / phone number
  -> encrypted token vault (SQLite /data)

WhatsApp customer
  -> Meta WhatsApp Cloud API
  -> POST https://wa.nabuxai.com/webhook
  -> signature verification
  -> contacts + messages + statuses DB

ChatGPT / Claude / Cursor
  -> OAuth 2.1 + PKCE
  -> https://wa.nabuxai.com/mcp
  -> owner-isolated MCP tools

Trusted Nabux backend
  -> INTERNAL_SERVICE_TOKEN
  -> /internal/v1/...
```

## MCP tools

### Accounts / metadata
- `whatsapp_accounts`
- `whatsapp_profile`
- `whatsapp_list_templates`
- `whatsapp_register_phone`

### Webhook-backed data
- `whatsapp_list_contacts`
- `whatsapp_list_conversations`
- `whatsapp_get_conversation`
- `whatsapp_search_messages`
- `whatsapp_recent_messages`
- `whatsapp_media_metadata`

### Messaging
- `whatsapp_send_text`
- `whatsapp_send_template`
- `whatsapp_send_media`
- `whatsapp_mark_read`

`whatsapp_send_text` and `whatsapp_send_media` require the gateway to have observed an inbound message from that contact in the previous 24 hours. To initiate/reopen a conversation, use an approved template and only message recipients who have provided the required opt-in.

## Data collection model

This gateway collects data delivered to your WhatsApp Business phone number through **official Meta webhooks**. It can therefore search and analyze messages received after the webhook is active, plus outbound messages sent through this gateway.

It is intentionally **not** a WhatsApp personal-history scraper. It cannot pull arbitrary old personal chats/groups from WhatsApp Web. If a separate personal collector is ever added, keep it isolated from this official Business gateway and clearly label it unofficial.

## Required Meta setup

Create/configure a Meta app with WhatsApp Business Platform and Embedded Signup.

Required production capabilities depend on your Meta app/business setup. For a multi-customer Embedded Signup release, Meta's current official guidance requires App Review/Advanced Access for the relevant WhatsApp/Business permissions. Meta's Embedded Signup flow returns the WABA/phone information, and this gateway subscribes the selected WABA to the app's webhook after connection.

Configure the webhook callback:

```text
https://wa.nabuxai.com/webhook
```

Use the same secret value in Meta's webhook **Verify Token** field and the server variable:

```text
WA_VERIFY_TOKEN=<random-secret>
```

Subscribe the WhatsApp Business Account webhook fields needed for messages. The gateway accepts message and delivery/read/status events and verifies Meta's request signature before ingestion.

## Environment variables

Copy `.env.example` and set secrets in Coolify rather than committing them.

```bash
APP_NAME="WhatsApp MCP by Nabux"
PUBLIC_BASE_URL=https://wa.nabuxai.com
APP_SECRET_KEY=<random-32+-char-secret>

WA_APP_ID=<meta-app-id>
WA_APP_SECRET=<meta-app-secret>
WA_EMBEDDED_CONFIG_ID=<embedded-signup-configuration-id>
WA_GRAPH_VERSION=v26.0
WA_GRAPH_BASE=https://graph.facebook.com
WA_VERIFY_TOKEN=<random-webhook-verify-token>
WA_WEBHOOK_PATH=/webhook

INTERNAL_SERVICE_TOKEN=<random-server-to-server-secret>
```

Generate secrets locally/server-side, for example:

```bash
python -c "import secrets; print(secrets.token_urlsafe(48))"
```

Never commit `WA_APP_SECRET`, Meta access tokens, `APP_SECRET_KEY`, or `INTERNAL_SERVICE_TOKEN`.

## Coolify deployment

Deploy this branch as a separate service:

```text
Repository: NabuxAi/TelegramMCP
Branch: feature/whatsapp-mcp-gateway
Compose file: docker-compose.coolify.yml
Domain: wa.nabuxai.com
Container port: 8000
```

Set all environment variables in Coolify and attach persistent storage to `/data` (the provided compose file creates `whatsapp-mcp-data`).

After deployment:

1. Open `https://wa.nabuxai.com/`.
2. Click **Connect WhatsApp**.
3. Complete Meta Embedded Signup.
4. Confirm the dashboard shows the phone number and `wa_...` Account Key.
5. In Meta Webhooks, verify `https://wa.nabuxai.com/webhook` using `WA_VERIFY_TOKEN`.
6. Send a WhatsApp message to the connected Business number.
7. Connect an MCP client to `https://wa.nabuxai.com/mcp`.
8. Call `whatsapp_list_conversations` and `whatsapp_get_conversation`.
9. Reply with `whatsapp_send_text` while the 24-hour customer-service window is open.
10. Test an approved template with `whatsapp_send_template`.

## Embedded Signup notes

The `/connect` page uses Meta's Facebook JavaScript SDK and an Embedded Signup configuration ID. It listens for the `WA_EMBEDDED_SIGNUP` completion event and combines the returned WABA/phone information with the exchangeable authorization code. The server then:

1. exchanges the code for an access token;
2. verifies access to the selected WABA;
3. subscribes the app to the WABA;
4. discovers its phone numbers;
5. stores the token encrypted for each connected phone number.

A newly onboarded phone number may still need Cloud API registration/two-step verification according to its state. The MCP tool `whatsapp_register_phone(pin)` performs the official registration call with a six-digit PIN.

## Security model

- Meta access tokens: Fernet-encrypted using a key derived from `APP_SECRET_KEY`.
- MCP bearer/refresh tokens: SHA-256 hashes only in the database.
- Browser session: signed HttpOnly/Secure cookie.
- Embedded Signup completion: short-lived same-site connect-state cookie.
- Webhooks: `X-Hub-Signature-256` HMAC verification using the Meta app secret.
- MCP data access: every account lookup is constrained to the authenticated local owner.
- Internal API: separate `INTERNAL_SERVICE_TOKEN`.
- No Meta token is returned to ChatGPT/Claude/Cursor.

## Official API vs. ban risk

Using WhatsApp Cloud API removes the risk associated with reverse-engineered WhatsApp Web/private-protocol automation, but it does not guarantee that an account can never be restricted. Businesses still need to follow Meta/WhatsApp messaging, opt-in, template, commerce and quality policies.

## Current scope / next additions

Useful next modules after first production E2E:
- webhook media download + encrypted/object-storage archive;
- semantic/vector search over stored conversations;
- template creation/management tools;
- conversation labels/CRM notes;
- NabuGen WhatsApp destination adapter;
- optional Coexistence-specific Embedded Signup configuration;
- retention controls and per-owner data deletion.