REST API

REST API reference

Pairing, send, history, MCP credentials and tenant flows. Interactive docs at /docs.

Public endpoints

Method	Path	Auth	Description
GET	`/health`	—	Liveness
GET	`/connect`	—	Pairing UI (QR / code + MCP copy)
POST	`/api/session/connect/kit`	Tenant	QR + code + image (best for agents)
POST	`/api/session/connect/code`	Tenant	8-digit pairing code
GET	`/api/session/connect/status`	Tenant / API key	Poll pairing; returns MCP on success
POST	`/api/send`	`wbot_...`	Send text or media
GET	`/api/history`	`wbot_...`	Message history with filters
GET	`/api/mcp/connection`	`wbot_...`	MCP config block
POST	`/mcp`	`mcp_...`	MCP Streamable HTTP transport

Data & write operations — full MCP parity

Every MCP tool has a REST equivalent under /api/*, authenticated with the wbot_ API key. Build WhatsApp-Web-style clients, dashboards, and enterprise tools directly over HTTP. All calls are tenant-scoped and audited. See /docs for parameters and schemas.

Method	Path	Description	MCP tool
GET	`/api/messages`	List stored messages (filters, cursor)	`whatsapp_list_messages`
GET	`/api/messages/search`	Full-text search	`whatsapp_search_messages`
POST	`/api/send/reply`	Quoted reply	`whatsapp_reply_to_message`
POST	`/api/send/typing`	Typing indicator	`whatsapp_send_typing`
POST	`/api/messages/reaction`	React with emoji	`whatsapp_send_reaction`
POST	`/api/messages/edit`	Edit a sent message	`whatsapp_edit_message`
POST	`/api/messages/delete`	Revoke a sent message	`whatsapp_delete_message`
POST	`/api/messages/forward`	Forward to same/other chat	—
POST	`/api/messages/schedule`	Schedule future delivery	`whatsapp_schedule_message`
GET	`/api/messages/media`	Media URL or download bytes	`whatsapp_download_media`
GET	`/api/chats`	List conversations	`whatsapp_list_chats`
GET	`/api/chats/detail`	One chat summary	`whatsapp_get_chat`
GET	`/api/chats/interacted`	Windowed activity digest (+ needs_reply)	`whatsapp_list_interacted_chats`
POST	`/api/chats/read`	Mark chat read	`whatsapp_mark_chat_read`
GET	`/api/chats/stats`	Per-chat statistics	`whatsapp_get_chat_stats`
GET	`/api/contacts`	List contacts	`whatsapp_list_contacts`
GET	`/api/contacts/resolve`	Resolve to JID	`whatsapp_resolve_recipient`
GET	`/api/contacts/check`	Check WhatsApp registration	`whatsapp_check_number`
GET	`/api/groups`	List groups	`whatsapp_list_groups`
GET	`/api/groups/members`	Group members	`whatsapp_get_group_members`
POST	`/api/groups/create`	Create group	`whatsapp_create_group`
POST	`/api/groups/participants`	Add/remove/promote/demote	`whatsapp_update_group_participants`
GET	`/api/groups/invite`	Invite link (reset optional)	`whatsapp_get_group_invite_link`
GET	`/api/groups/subject-history`	Rename history	`whatsapp_get_group_subject_history`
GET	`/api/notifications`	List notifications	`whatsapp_list_notifications`
GET	`/api/notifications/stream`	SSE push stream	`whatsapp_watch_notifications`
POST	`/api/notifications/read`	Mark one read	`whatsapp_mark_notification_read`
POST	`/api/notifications/cleanup`	Bulk mark-read/delete by filter	`whatsapp_cleanup_notifications`
GET	`/api/session/sync`	Sync status	`whatsapp_get_sync_status`
GET	`/api/session/wait-sync`	Block until synced	`whatsapp_wait_for_sync`
GET	`/api/stats/overview`	Cross-chat analytics	`whatsapp_get_overview_stats`
GET	`/api/audit`	Tool audit log	`whatsapp_get_audit_log`

Connect kit flow

# Start
curl -X POST https://zap.zaptdev.com/api/session/connect/kit \
  -H "X-Tenant-Key: tnt_..." \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"5511999999999"}'

# Poll (every 3s)
curl "https://zap.zaptdev.com/api/session/connect/status?uuid=UUID" \
  -H "X-Tenant-Key: tnt_..."

# Optional QR image
curl "https://zap.zaptdev.com/api/session/connect/kit-image?uuid=UUID" \
  -H "X-Tenant-Key: tnt_..." -o kit.png

Send message

curl -X POST https://zap.zaptdev.com/api/send \
  -H "X-API-Key: wbot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511888888888@s.whatsapp.net",
    "content": "Hello from REST API"
  }'

# With media
curl -X POST https://zap.zaptdev.com/api/send \
  -H "X-API-Key: wbot_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511888888888@s.whatsapp.net",
    "content": "See attached",
    "media_url": "https://example.com/doc.pdf",
    "media_type": "document"
  }'

History query

curl "https://zap.zaptdev.com/api/history?limit=25&chat_jid=5511999999999@s.whatsapp.net" \
  -H "X-API-Key: wbot_..."

SaaS tenant provisioning (before numbers)

Create a tenant, put WAMCP_TENANT_ID and WAMCP_TENANT_KEY in your app .env, then connect numbers with that key.

# Public self-service (rate-limited)
curl -X POST https://zap.zaptdev.com/api/tenants \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp WhatsApp","slug":"acme"}'
# Save id + tenant_key (tnt_...) — shown once

# Add a WhatsApp number under that tenant
curl -X POST https://zap.zaptdev.com/api/session/connect/kit \
  -H "X-Tenant-Key: $WAMCP_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"5511999999999"}'

# Or UI: https://zap.zaptdev.com/connect (step 1 create tenant, step 2 link number)

# Platform admin (optional)
curl -X POST https://zap.zaptdev.com/api/admin/tenants \
  -H "X-Admin-Token: $ADMIN_MASTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug":"acme","name":"Acme Corp WhatsApp"}'

HTTP status codes

401 — Missing or invalid tenant key, API key, or MCP token.
403 — Connect UUID belongs to another tenant.
408 — Pairing code not ready yet; keep polling.
409 — WhatsApp offline; reconnect or re-pair.