# WAMCP — WhatsApp Infrastructure for Your Agents (Full LLM Context)

## Product summary

WAMCP is the controlled infrastructure that lets you safely give your own AI agents (Claude, Grok, Cursor, Codex, custom) access to WhatsApp. You pair once. Then from a simple settings portal you create named agents, set precise per-agent permissions, and toggle access at any time. Your WhatsApp stays yours — WAMCP is only the reliable, audited bridge.

Core capabilities:
- Named MCP credentials with independent toggles (send / read / provision)
- MCP Streamable HTTP (primary for agents) + REST API + webhooks
- Full sync, notification watching, audit, health monitoring
- Minimal mobile-first owner portal (no chat UI)
- Self-chat MFA and pairing-code gated actions for security

**Also known as:** Whatsmeow Bot (technical/backend name in docs and OpenAPI).

**Search terms:** WhatsApp MCP, WhatsApp API for AI agents, Model Context Protocol WhatsApp, WhatsApp automation API, white-label WhatsApp platform, Cursor WhatsApp MCP, Claude WhatsApp integration.

## Core capabilities

- WhatsApp multi-device pairing via QR code or 8-digit pairing code
- 33 MCP tools for messaging, sync, notifications, session lifecycle, and audit
- 4 MCP resources: whatsapp://session, whatsapp://sync, whatsapp://notifications/unread, whatsapp://messages/{chat_jid}
- REST API for synchronous connect, send, history, and MCP credential management
- Supabase PostgreSQL for sessions (PGStore), message history, notifications, and realtime event bus
- Cloudflare R2 for public media URLs on inbound/outbound attachments
- Agent handoff without re-pairing: API session_handoff or WhatsApp self-chat /connect MFA
- Sync tracking with whatsapp_wait_for_sync and session protection during history sync
- User PWA portal at /portal: install after sync, compose when allow_send, agent invites, MCP revoke/rotate, tenant-scoped audit, export/delete (pairing-gated), push alerts, WebAuthn
- MCP audit: every tool call recorded with tenant, IP, success, latency

## Authentication model

| Credential | Header | Purpose |
|------------|--------|---------|
| tnt_... | X-Tenant-Key | Start connect flows for a tenant |
| wbot_... | X-API-Key | REST operations for a paired phone |
| mcp_... | Authorization Bearer | MCP tool calls at POST /mcp |
| ADMIN_MASTER_TOKEN | X-Admin-Token | Tenant provisioning and admin audit |

## MCP tool categories

Messaging: whatsapp_send_message, whatsapp_reply_to_message, whatsapp_send_reaction, whatsapp_send_typing, whatsapp_list_messages, whatsapp_search_messages, whatsapp_get_chat, whatsapp_mark_chat_read, whatsapp_download_media, whatsapp_list_chats, whatsapp_list_contacts, whatsapp_list_groups, whatsapp_get_group_members

Session: whatsapp_get_session_status, whatsapp_get_sync_status, whatsapp_wait_for_sync, whatsapp_health_check, whatsapp_resolve_recipient, whatsapp_get_mcp_connection, whatsapp_rotate_mcp_token, whatsapp_get_audit_log

Notifications: whatsapp_list_notifications, whatsapp_watch_notifications, whatsapp_get_unread_notification_count, whatsapp_mark_notification_read, whatsapp_mark_all_notifications_read

Lifecycle (allow_provision=true): whatsapp_reconnect, whatsapp_disconnect, whatsapp_connect_code, whatsapp_connect_qr, whatsapp_connect_kit, whatsapp_connect_status, whatsapp_enable_mcp

## Recommended agent workflow

1. Discover: GET https://wamcp.up.railway.app/docs/agent-playbook
2. Pair: POST https://wamcp.up.railway.app/api/session/connect/kit with X-Tenant-Key
3. Poll: GET https://wamcp.up.railway.app/api/session/connect/status?uuid=... every 3s until status=success
4. MCP config: use mcp_connection from poll response (auto-enabled)
5. Sync: whatsapp_wait_for_sync then whatsapp_health_check
6. Listen: whatsapp_watch_notifications
7. Reply: whatsapp_get_chat → whatsapp_resolve_recipient → whatsapp_reply_to_message
8. Debug: whatsapp_get_audit_log, whatsapp_rotate_mcp_token on 401

## Key HTTP routes

- GET https://wamcp.up.railway.app/ — Platform landing (WAMCP)
- GET https://wamcp.up.railway.app/guides/agents — AI agent onboarding (9 steps)
- GET https://wamcp.up.railway.app/guides/mcp — MCP reference (33 tools)
- GET https://wamcp.up.railway.app/guides/skills — Ready skills & starters (simple for humans + extremely detailed examples, prompts, custom functions)
- GET https://wamcp.up.railway.app/guides/api — REST API guide
- GET https://wamcp.up.railway.app/guides/portal — Owner settings & agent access guide (you stay in control)
- GET https://wamcp.up.railway.app/guides/compare — WAMCP vs basic WhatsApp APIs
- GET https://wamcp.up.railway.app/portal — Minimal owner settings (named agent access + control; noindex shell)
- GET https://wamcp.up.railway.app/connect — Pairing UI
- GET https://wamcp.up.railway.app/docs — Swagger UI
- GET https://wamcp.up.railway.app/docs/agent-playbook — JSON playbook
- POST https://wamcp.up.railway.app/mcp — MCP Streamable HTTP

## Infrastructure stack

WhatsApp Web ↔ Go whatsmeow client ↔ Supabase Postgres + Realtime ↔ Agent host (MCP) / Partner backend (REST)

Sessions and Signal keys are stored in Postgres via PGStore (not local SQLite). Media is uploaded to R2 with media_url + r2_key; history purge deletes R2 objects.

## Agent handoff

When a session is already live, connect endpoints return status=session_handoff with mcp_connection instead of starting a new pairing flow. Users can also send /connect in WhatsApp self-chat for MFA-based credential delivery to additional agents.

## Links

- llms.txt: https://wamcp.up.railway.app/llms.txt
- robots.txt: https://wamcp.up.railway.app/robots.txt
- sitemap: https://wamcp.up.railway.app/sitemap.xml