lingtai-whatsapp

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

pip install lingtai-whatsapp

For local development before the first PyPI release:

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.

Related MCP server: WA MCP

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.

{
  "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:

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:

{
  "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:

<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_ids, 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:

"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

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.