AI Agents Guide

Start in about a minute

9-step onboarding from pairing WhatsApp to your first agent message. Works with Claude, Cursor, Grok and any MCP client.

Pair WhatsApp MCP reference Ready skills

Canonical source: /docs/agent-playbook (JSON). Human-readable guide below.

9-step workflow

Discover — Load /docs/agent-playbook or the MCP reference.
Pair — POST /api/session/connect/kit with X-Tenant-Key: tnt_... or send the user to /connect.
Poll — GET /api/session/connect/status?uuid=... every 3 seconds until status=success.
Configure MCP — Copy mcp_connection.cursor_mcp_example into your agent host (MCP auto-enables on success).
Wait for sync — Call whatsapp_wait_for_sync, then whatsapp_health_check.
Listen — Use whatsapp_watch_notifications for event-driven loops.
Respond — whatsapp_get_chat → whatsapp_resolve_recipient → whatsapp_reply_to_message.
Debug — whatsapp_get_audit_log or whatsapp_rotate_mcp_token on 401.
Owner settings — After sync, the account owner receives a one-time self-chat link to install the minimal settings portal for named MCP access management (guide).
Production skills — Go to /skills for reactive loops, inbox triage, scheduled delivery, memory recall, group tools + reusable patterns (approval gate, audit transparency). Simple for humans + exhaustive sequences + traces for agents.

Ready skills for instant start

New to this? Go to /skills and copy a complete starter prompt + config for Claude, Cursor, or Grok. Takes minutes. All examples are written so a non-technical person can get real value immediately while the technical docs underneath are exhaustive.

Owner settings portal

For the WhatsApp account owner — minimal access control only (not a chat UI). See the portal guide for full detail. Use the official WhatsApp app for chatting.

Sync completes → bot sends /portal/install?token=pit_... to self-chat (once).
User installs PWA to home screen and signs in with pairing code, then enables passkey/biometrics.
Optional: Face ID / fingerprint via WebAuthn.
Enable push for disconnect, new messages, and MCP agent activity.

Manage MCP permissions, view live agent connections, and audit history from /portal.

Credentials

Credential	Header	Use
`tnt_...`	`X-Tenant-Key`	Start connect flows for a white-label tenant
`wbot_...`	`X-API-Key`	REST send, history, session, MCP enable
`mcp_...`	`Authorization: Bearer`	All MCP tool calls at `POST /mcp`
Admin token	`X-Admin-Token`	Create tenants, audit, protected docs

Reactive message loop (MCP)

# 1. Block until a new notification or timeout
whatsapp_watch_notifications { "wait_seconds": 30 }

# 2. Inspect the chat referenced in message_in payload
whatsapp_get_chat { "chat_jid": "5511999999999@s.whatsapp.net" }

# 3. Reply quoting the stored message_id
whatsapp_reply_to_message {
  "message_id": "3EB0...",
  "content": "Thanks — we received your message."
}

Agent handoff (already paired)

Skip re-pairing when WhatsApp is already online.

API / MCP handoff

Call any connect endpoint while the session is live — response status is session_handoff with full mcp_connection.

POST https://wamcp.up.railway.app/api/session/connect/kit
# or MCP: whatsapp_connect_kit / whatsapp_reconnect

Self-chat MFA

User sends /connect in WhatsApp “message yourself”. Only the account owner can trigger live IsFromMe self-chat — bot replies with MCP token, API key, and config JSON.

Troubleshooting

401 MCP — Rotate with whatsapp_rotate_mcp_token or re-fetch /api/mcp/connection.
409 offline — whatsapp_reconnect or ask user to complete pairing on phone.
sync_protected — Wait for whatsapp_wait_for_sync; do not disconnect mid-sync.
Recipient errors — Always call whatsapp_resolve_recipient when you only have phone digits.

Ready to give it a try?

Pair in ~60s and paste the MCP block into your agent.

Connect WhatsApp