WhatsUp Mind

Authentication

All agent endpoints use Bearer token authentication. Admin endpoints use the X-Admin-Key header.

Authorization: Bearer wha_your_api_key_here    (Agent endpoints)
X-Admin-Key: your_admin_key                    (Admin endpoints)

Agent Endpoints

POST /api/mcp/tools

List all available WhatsApp tools and their parameter schemas.

POST /api/mcp/call

Call a WhatsApp tool. Body: {"tool": "tool_name", "arguments": {...}}

Quick start: First call /api/mcp/tools to discover available tools, then use /api/mcp/call to execute them.

curl -X POST https://whatsupmind.com/api/mcp/call \
  -H "Authorization: Bearer wha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tool": "send_message", "arguments": {"recipient": "1234567890", "message": "Hello!"}}'

Available Tools

search_contacts

Search contacts by name or phone number

list_chats

List chats with filtering, sorting, pagination

list_messages

Get messages with date/sender/content filters

get_chat

Get chat metadata by JID

get_direct_chat_by_contact

Find chat by phone number

get_contact_chats

Get all chats involving a contact

get_last_interaction

Most recent message with a contact

get_message_context

Get surrounding messages for context

send_message

Send a text message to a person or group

send_file

Send image, video, or document

send_audio_message

Send audio as a voice message

download_media

Download media from a message

Polling for New Messages

WhatsUp Mind does not support webhooks. Agents must poll for new messages at regular intervals.

Recommended: Poll list_messages with the after parameter every 3 minutes. Use 1 minute for time-sensitive workflows. Never poll more frequently than every 30 seconds. Each poll is a fast local query — no external API calls are made.

curl -X POST https://whatsupmind.com/api/mcp/call \
  -H "Authorization: Bearer wha_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_messages","arguments":{"limit":50,"after":"2026-03-29T10:00:00"}}'

Admin Endpoints

POST /api/admin/accounts

Create a new WhatsApp account. Body: {"account_id": "name"}

GET /api/admin/accounts

List all accounts with status info.

DELETE /api/admin/accounts/{id}

Delete an account and stop its bridge.

GET /api/admin/accounts/{id}/health

Check bridge health for an account.

POST /api/admin/accounts/{id}/start

Start the bridge process for an account.

POST /api/admin/accounts/{id}/stop

Stop the bridge process for an account.

GET /api/admin/accounts/{id}/api-key

Retrieve the API key for an account.

POST /api/admin/accounts/{id}/sync

Trigger a WhatsApp history sync to pull in group chats.

Key Concepts

JID — WhatsApp identifier. Contacts: phone@s.whatsapp.net. Groups: id@g.us.
Phone numbers — Digits only with country code, no + or symbols. Example: 14155551234.
Pagination — Use limit and page (0-indexed) on list endpoints.
Dates — ISO-8601 format: 2026-03-29T10:30:00.
Multi-tenant — Each API key maps to one WhatsApp account.

MCP Protocol (SSE)

For MCP-native clients, connect via Server-Sent Events:

GET /sse

SSE transport endpoint. Requires Bearer auth. Returns a message endpoint URL for bidirectional communication.

WhatsUp Mind

WhatsApp API for AI Agents

🚀 Get Started

📱 How It Works