# lingtai-whatsapp

> [!IMPORTANT]
> **Deprecated standalone repository.** The current LingTai whatsapp MCP server is maintained inside [`Lingtai-AI/lingtai-kernel`](https://github.com/Lingtai-AI/lingtai-kernel) at `src/lingtai/mcp_servers/whatsapp/` and is shipped with the LingTai kernel/wheel.
>
> This repository is kept only as a historical/compatibility snapshot for older standalone deployments. Do not start new integrations here; update the in-kernel implementation instead.


LingTai MCP server for the official Meta WhatsApp Business Platform / Cloud API.

This package intentionally targets the **official WhatsApp Cloud API only**. It does **not** implement or recommend unofficial WhatsApp Web bridges (Baileys/whatsmeow style), because those violate WhatsApp's Terms of Service and can ban numbers.

> **MCP / LICC contract spec:** see the `lingtai-anatomy` skill, `reference/mcp-protocol.md`, for the canonical specification of the catalog → registry → activation chain, environment-variable injection, and the LICC v1 inbox callback protocol. The canonical client implementation is `lingtai.core.mcp.licc.push_inbox_event` in `lingtai-kernel`; `src/lingtai_whatsapp/licc.py` in this repo is a compatibility wrapper that delegates to the kernel helper when available and falls back to the LICC v1 filesystem writer for standalone or pre-upgrade environments.

## Install

```bash
pip install lingtai-whatsapp
```

For local development before the first PyPI release:

```bash
pip install -e .
```

`src/lingtai_whatsapp/licc.py` is vendored from the first-party LingTai MCP repos and implements the LICC v1 inbox callback contract. Keep it synchronized with sibling packages (`lingtai-telegram`, `lingtai-feishu`, `lingtai-wechat`, `lingtai-imap`) when the protocol changes.

## What it provides

- MCP stdio server: `python -m lingtai_whatsapp`
- Omnibus `whatsapp` tool with actions: `send`, `reply`, `react`, `check`, `read`, `search`, `contacts`, `add_contact`, `remove_contact`, `templates`, `accounts`, `status`
- LICC v1 inbox callback for inbound WhatsApp messages
- Local message/contact persistence under the hosted agent directory
- Optional stdlib HTTP webhook receiver for Meta GET verification + signed POST callbacks
- MCP resources for setup/onboarding/status:
  - `lingtai://manifest`
  - `lingtai://skills/whatsapp`
  - `lingtai://docs/configuration`
  - `lingtai://docs/troubleshooting`
  - `lingtai://status`
  - `lingtai://onboarding/whatsapp`
  - `lingtai://onboarding/html-template`

## Configuration

Set `LINGTAI_WHATSAPP_CONFIG` to a JSON file. LingTai normally wires this through `init.json`'s `mcp.whatsapp.env` entry.

```json
{
  "accounts": [
    {
      "alias": "main",
      "access_token": "EAAG...",
      "phone_number_id": "123456789",
      "waba_id": "987654321",
      "app_secret": "...",
      "verify_token": "choose-a-random-webhook-token",
      "api_version": "v20.0",
      "display_phone_number": "+1 555 0100",
      "webhook": {
        "public_url": "https://example.com/webhooks/whatsapp",
        "host": "127.0.0.1",
        "port": 8088,
        "path": "/webhooks/whatsapp"
      },
      "templates": [
        {"name": "hello_world", "language": "en_US"}
      ]
    }
  ]
}
```

Required per account:

| Field | Purpose |
| --- | --- |
| `alias` | Local LingTai account name. Defaults to `default` if omitted. |
| `access_token` | Meta system-user/permanent access token with WhatsApp messaging permissions. |
| `phone_number_id` | Meta phone number id used by `/{phone_number_id}/messages`. |
| `waba_id` or `business_account_id` | WhatsApp Business Account id for operator reference/onboarding. |
| `app_secret` | Used to verify `X-Hub-Signature-256` on webhook POST callbacks. |
| `verify_token` | Random operator-chosen token used for Meta webhook GET verification. |

Optional:

- `api_version` defaults to `v20.0`.
- `display_phone_number` is informational only.
- `webhook` starts a local HTTP listener when `port` is present.
- `templates` is a local list of approved template names/languages the agent can inspect with `whatsapp(action="templates")`.

Secrets are plaintext by LingTai addon convention, but all tool/resource status results are redacted: access tokens, app secrets, and verify tokens are never echoed.

## LingTai activation

When used as a curated LingTai MCP, the agent's `init.json` should include:

```json
{
  "addons": ["whatsapp"],
  "mcp": {
    "whatsapp": {
      "type": "stdio",
      "command": "/Users/<you>/.lingtai-tui/runtime/venv/bin/python",
      "args": ["-m", "lingtai_whatsapp"],
      "env": {
        "LINGTAI_WHATSAPP_CONFIG": ".secrets/whatsapp.json"
      }
    }
  }
}
```

Then create `.secrets/whatsapp.json` using the schema above and run `system(action="refresh")` from the agent.

## Public MCP identity metadata

On startup, `lingtai-whatsapp` writes a non-secret identity document to:

```text
<agent_dir>/system/mcp_identities/whatsapp.json
```

This file maps local account aliases to non-secret WhatsApp Business identity fields such as `phone_number_id`, `waba_id` / `business_account_id`, `display_phone_number`, `api_version`, `last_verified_at`, `template_count`, and `contact_count`. It never contains `access_token`, `app_secret`, `verify_token`, message contents, individual contact `wa_id`s, webhook signatures, or template parameter values. Agents can use it to answer questions like “which local LingTai agent owns this WhatsApp business number?” without inspecting `.secrets/whatsapp.json` or mining logs.

`whatsapp(action="accounts")` also returns the same non-secret `details` list plus `identity_path` for live inspection.

## Webhook setup

Meta requires a public HTTPS callback URL for inbound WhatsApp messages and delivery statuses. This MCP can run a local HTTP server if the first account's config includes `webhook.port`:

```json
"webhook": {
  "public_url": "https://example.com/webhooks/whatsapp",
  "host": "127.0.0.1",
  "port": 8088,
  "path": "/webhooks/whatsapp"
}
```

Expose that local listener with your preferred HTTPS reverse proxy/tunnel (Cloudflare Tunnel, ngrok, Caddy, nginx, etc.), then configure Meta's callback URL to `public_url` and verify it with the same `verify_token` stored in config.

Webhook behavior:

- `GET <path>?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...` returns the challenge when the token matches.
- `POST <path>` validates `X-Hub-Signature-256` when `app_secret` is present, stores incoming messages, and pushes LICC inbox events to the hosting LingTai agent.
- For multi-account configs, inbound POSTs are routed by `metadata.phone_number_id`; unknown phone ids fall back to the default account.

## WhatsApp Cloud API constraints

- Free-form business replies are allowed only within the 24-hour customer-service window after a user's message.
- Outside the 24-hour window, use an approved message template.
- The Cloud API is for WhatsApp Business accounts; ordinary personal WhatsApp Web sessions are intentionally out of scope.

## Development

```bash
python -m pytest -q
```

The tests avoid real network calls. The send path uses Meta's Graph API only when credentials are present and the tool action is invoked.