WWhatsApp-Use

developer reference

WhatsApp-Use API and MCP.

Create a free API key, let the platform provision the hidden runtime, then call WhatsApp through REST or connect MCP through OAuth. The hosted agent harness uses the same account boundary and hidden runtime.

introduction

Introduction

WhatsApp-Use exposes one public platform endpoint. Your API key grants scoped access to a WhatsApp connection whose hidden runtime owns pairing, message access, MCP tools, hosted agent turns, and webhook delivery.

Base URLhttps://api.whatsapp-use.com
REST AuthAuthorization bearer API key
MCP AuthOAuth bearer token
Dashboardhttps://platform.whatsapp-use.com
Docshttps://docs.whatsapp-use.com
WhatsApp MCP/mcp/whatsapp
Agent MCP/mcp/agent

quickstart

Quickstart

Start with REST from any backend or connect a remote MCP client through OAuth. Modern clients can use client-ID metadata documents or dynamic registration, then authorization-code + PKCE. REST API keys and MCP OAuth grants are separate credential surfaces that can target the same hidden runtime.

RESTAny backend or script
export WHATSAPP_USE_BASE_URL="https://api.whatsapp-use.com"
export WHATSAPP_USE_API_KEY="wuse_live_..."

curl "$WHATSAPP_USE_BASE_URL/v1/me" \
  -H "Authorization: Bearer $WHATSAPP_USE_API_KEY"

curl "$WHATSAPP_USE_BASE_URL/v1/whatsapp/status" \
  -H "Authorization: Bearer $WHATSAPP_USE_API_KEY"
WhatsApp MCPRemote Streamable HTTP MCP
# Add this hosted MCP URL in a modern MCP client.
https://api.whatsapp-use.com/mcp/whatsapp

# Compatibility for stdio-only clients.
npx mcp-remote https://api.whatsapp-use.com/mcp/whatsapp
Agent MCPRemote Streamable HTTP MCP
# Add this hosted MCP URL in a modern MCP client.
https://api.whatsapp-use.com/mcp/agent

# Compatibility for stdio-only clients.
npx mcp-remote https://api.whatsapp-use.com/mcp/agent

auth

Authentication

Generate keys in the dashboard. Keys are shown once and should stay in your own backend or local secret manager. Send them towhatsapp-use-backend as an Authorization bearer token for HTTPS API routes. MCP clients use OAuth against the hosted remote MCP URL, not dashboard API keys.

# Generate a key
open https://api.whatsapp-use.com/app/keys

# Call the platform
curl "https://api.whatsapp-use.com/v1/me" \
  -H "Authorization: Bearer wuse_live_..."

rest

REST and OAuth reference

Public developer traffic enters through https://api.whatsapp-use.com. WhatsApp and hosted-agent runtime services are private implementation details; the backend validates credentials, records usage, and forwards signed internal requests to the correct connection runtime.

Platform REST

Account, runtime, usage, and webhook routes are served by whatsapp-use-backend and authenticate with dashboard API keys.

GET/v1/meAPI keyInspect the current API key, scopes, runtime health, and available endpoint paths.
GET/v1/usageAPI keyList usage records and summary counts for the current API key.
GET/v1/webhooks/endpointsAPI key / webhooks:manageList webhook endpoints configured for the current account.
POST/v1/webhooks/endpointsAPI key / webhooks:manageCreate a signed outbound webhook endpoint.
PATCH/v1/webhooks/endpoints/{endpoint_id}API key / webhooks:manageUpdate webhook endpoint metadata, event filters, or enabled state.
DELETE/v1/webhooks/endpoints/{endpoint_id}API key / webhooks:manageDelete a webhook endpoint.
POST/v1/webhooks/endpoints/{endpoint_id}/testAPI key / webhooks:manageSend a test delivery to a webhook endpoint.
GET/v1/webhooks/deliveriesAPI key / webhooks:manageList recent webhook delivery attempts.

WhatsApp REST

WhatsApp routes are proxied through whatsapp-use-backend into the hidden per-connection WhatsApp runtime.

GET/v1/whatsapp/statusAPI key / whatsapp:readRead pairing, connection, and runtime health.
POST/v1/whatsapp/pairAPI key / whatsapp:writeRequest a QR or pairing code from the hidden runtime.
GET/v1/whatsapp/pair/statusAPI key / whatsapp:readRead the latest pairing status and QR data.
GET/v1/whatsapp/syncAPI key / whatsapp:readRead changed conversations, contacts, and messages after a cursor.
GET/v1/whatsapp/conversationsAPI key / whatsapp:readList stored WhatsApp conversations.
GET/v1/whatsapp/contactsAPI key / whatsapp:readList stored WhatsApp contacts.
GET/v1/whatsapp/conversations/{conversation_id}/messagesAPI key / whatsapp:readList messages for a conversation.
GET/v1/whatsapp/media/{message_id}API key / whatsapp:readDownload stored media bytes for an ingested message.
POST/v1/whatsapp/messages/sendAPI key / whatsapp:writeSend a WhatsApp text message.
POST/v1/whatsapp/messages/reactAPI key / whatsapp:writeReact to or clear a reaction on a message.
POST/v1/whatsapp/messages/editAPI key / whatsapp:writeEdit a sent WhatsApp message.
POST/v1/whatsapp/messages/deleteAPI key / whatsapp:writeDelete or revoke a sent WhatsApp message.
POST/v1/whatsapp/messages/readAPI key / whatsapp:writeMark one or more messages as read.
POST/v1/whatsapp/conversations/{conversation_id}/readAPI key / whatsapp:writeMark a conversation as read.
POST/v1/whatsapp/groupsAPI key / whatsapp:writeCreate a WhatsApp group.
POST/v1/whatsapp/groups/{group_jid}/participantsAPI key / whatsapp:writeAdd, remove, promote, or demote group participants.
POST/v1/whatsapp/commandsAPI key / whatsapp:writeQueue a lower-level durable WhatsApp command.
GET/v1/whatsapp/commands/{command_id}API key / whatsapp:readRead command status and result.
POST/v1/whatsapp/unlinkAPI key / whatsapp:writeUnlink the paired WhatsApp device and clear runtime WhatsApp state.

Agent REST

Hosted agent routes are proxied through whatsapp-use-backend into the hidden agent harness runtime.

POST/v1/harness/sessionsAPI key / harness:runCreate a durable hosted-agent session.
GET/v1/harness/sessions/{session_id}API key / harness:readRead a session and its turns.
DELETE/v1/harness/sessions/{session_id}API key / harness:runClose a hosted-agent session.
POST/v1/harness/sessions/{session_id}/turnsAPI key / harness:runRun a hosted agent turn.
POST/v1/harness/sessions/{session_id}/turns/{turn_id}/cancelAPI key / harness:runCancel a running turn.
GET/v1/harness/sessions/{session_id}/eventsAPI key / harness:readList durable session events.
GET/v1/harness/sessions/{session_id}/events/streamAPI key / harness:readStream durable session events.
POST/v1/harness/sessions/{session_id}/eventsAPI key / harness:runAppend a durable session event.
GET/v1/harness/sessions/{session_id}/child-tasksAPI key / harness:readList child task records.
POST/v1/harness/sessions/{session_id}/child-tasksAPI key / harness:runCreate a child task record.
POST/v1/harness/sessions/{session_id}/child-tasks/{child_task_id}/cancelAPI key / harness:runCancel a child task record.
GET/v1/harness/tasksAPI key / harness:readList durable background tasks.
POST/v1/harness/tasksAPI key / harness:runCreate a durable background task.
PATCH/v1/harness/tasks/{task_id}API key / harness:runUpdate a durable background task.
POST/v1/harness/notifyAPI key / harness:runRecord and dispatch a user-facing notification.
POST/v1/harness/memory/searchAPI key / harness:readSearch harness memory.
POST/v1/harness/memory/writeAPI key / harness:runWrite a harness memory item.
GET/v1/harness/usageAPI key / harness:readRead harness usage counters.

MCP and OAuth

MCP clients use OAuth bearer tokens, not REST API keys. Both remote MCP endpoints are served by the public backend gateway.

POST/mcp/whatsappOAuth bearerRemote Streamable HTTP MCP endpoint for WhatsApp tools.
POST/mcp/agentOAuth bearerRemote Streamable HTTP MCP endpoint for hosted agent tools.
GET/.well-known/oauth-protected-resource/mcp/whatsappPublicProtected resource metadata for WhatsApp MCP.
GET/.well-known/oauth-protected-resource/mcp/agentPublicProtected resource metadata for Agent MCP.
GET/.well-known/oauth-authorization-server/oauthPublicOAuth authorization server metadata.
POST/oauth/registerPublicDynamic OAuth client registration for remote MCP clients.
GET/oauth/authorizeSessionAuthorization-code + PKCE approval flow.
POST/oauth/tokenOAuth clientExchange code or refresh token for MCP access.

conventions

Conventions

A few patterns apply across every tool. Read these once and the rest of the reference becomes a lot shorter.

Platform boundary

Developer traffic enters through whatsapp-use-backend. Hidden runtime services receive signed internal requests, not raw public API keys.

API keys

Keys are shown once at creation or rotation. The platform stores a peppered HMAC hash, not the raw bearer secret. Send keys from server-side code, SDKs, and HTTPS API calls. MCP clients use OAuth.

MCP OAuth

Modern remote MCP clients use OAuth authorization-code + PKCE with rotating refresh tokens. Client-ID metadata documents are preferred, dynamic registration remains available, and dashboard-created grants are only a manual testing path.

Runtime isolation

Each WhatsApp connection maps to its own hidden runtime. API keys and MCP grants are credentials attached to that connection; rotating or revoking them does not stop the runtime.

Memory

Agent memory lives behind whatsapp-use-agent-harness and uses HelixDB when configured. The model worker does not receive Helix credentials.

Webhooks

Runtime events are delivered to webhook endpoints configured in the dashboard. Deliveries are signed by whatsapp-use-backend.

connection

Connection tools

Pair the hidden runtime, inspect connector status, and read incremental WhatsApp state for the API key.

whatsapp_status

Get WhatsApp connection, pairing, and connector status.

whatsapp_request_pair

Start WhatsApp pairing and return the current pairing result.

whatsapp_pair_status

Read the current pairing status and QR data when available.

whatsapp_sync

Read changed conversations, contacts, and messages after a sync cursor.

messages

Message tools

List messages, download stored media, send text, mutate messages, and track the durable command outbox.

whatsapp_list_messages

List messages in a WhatsApp conversation. Requires a conversation_id returned by sync.

whatsapp_download_media

Download stored WhatsApp media for a message as base64 plus MIME metadata.

whatsapp_send_message

Send a WhatsApp text message through the runtime connector using conversation_id or contact_id.

whatsapp_react_to_message

React to a WhatsApp message, or clear the current reaction with an empty emoji.

whatsapp_edit_message

Edit a sent WhatsApp message by conversation_id or chat JID and wa_message_id.

whatsapp_delete_message

Delete or revoke a sent WhatsApp message.

whatsapp_mark_read

Mark one or more WhatsApp messages as read.

whatsapp_create_group

Create a WhatsApp group with an initial subject and participants.

whatsapp_update_group_participants

Add, remove, promote, or demote WhatsApp group participants.

whatsapp_unlink

Unlink the paired WhatsApp device and clear runtime WhatsApp state.

whatsapp_enqueue_command

Escape hatch for lower-level command kinds when a first-class tool is not enough.

whatsapp_command_status

Read a queued WhatsApp command status and result by command_id.

agent

Hosted agent MCP

OAuth-connected MCP clients can call the hosted agent harness MCP endpoint. It runs sessions, turns, durable events, and Helix-backed memory behind the platform boundary.

agent_create_session

Create a durable hosted-agent session for an API key runtime.

agent_get_session

Read a hosted-agent session and its turns.

agent_run_turn

Run a hosted agent turn with WhatsApp tools and harness memory available.

agent_list_events

Read durable session and turn events from the harness store.

agent_close_session

Close a hosted-agent session.

agent_memory_search

Search harness memory through the Helix-backed memory boundary.

agent_memory_write

Write memory through the harness API, not from the model worker.

agent_create_task

Create a durable hosted-agent background task.

agent_list_tasks

List durable hosted-agent background tasks.

agent_update_task

Update task state, title, goal prompt, trigger kind, or metadata.

agent_create_child_task

Create a child-task record under a hosted-agent session.

agent_list_child_tasks

List child-task records under a hosted-agent session.

agent_cancel_child_task

Cancel a child-task record under a hosted-agent session.

agent_notify_user

Record and dispatch a user-facing hosted-agent notification.

agent_schedule_reminder

Schedule or replace a hosted-agent reminder/check-in.

agent_cancel_reminder

Cancel a hosted-agent reminder/check-in.

notifications

Notifications

Runtime events are delivered through dashboard-configured webhooks. WhatsApp Use backend receives signed internal events from the hidden WhatsApp and agent runtimes, records delivery history, and signs outbound webhook requests.

whatsapp.message.sentAn outbound message was sent through the runtime.
whatsapp.command.completedA queued WhatsApp command completed.
whatsapp.command.failedA queued WhatsApp command failed.
whatsapp.connection.status_changedThe runtime connection or pairing state changed.
agent.session.createdA hosted agent session was created.
agent.session.closedA hosted agent session was closed.
agent.session.cancelledA hosted agent session was cancelled.
agent.turn.completedA hosted agent turn completed.
agent.turn.failedA hosted agent turn failed.
agent.turn.cancelledA hosted agent turn was cancelled.
agent.event.recordedA durable hosted-agent event was appended.
agent.child_task.startedA harness child task was created.
agent.child_task.cancelledA harness child task was cancelled.
agent.task.createdA hosted-agent background task was created.
agent.task.updatedA hosted-agent background task was updated.
agent.notification.deliveredThe harness accepted and dispatched an agent notification.
agent.reminder.scheduledA hosted-agent reminder was scheduled or replaced.
agent.reminder.cancelledA hosted-agent reminder was cancelled.

errors

Errors

Tool errors return a JSON body with a code, a human-readable message, and optional fields for validation issues. HTTP-style status codes are surfaced for parity.

401unauthorizedMissing or invalid API key.
403forbiddenThe key does not include the scope required for that endpoint.
404not_foundThe requested resource or runtime command does not exist.
409runtime_not_readyThe hidden runtime for the API key has not finished provisioning.
409whatsapp_not_pairedThe WhatsApp runtime has not completed pairing.
400invalid_requestMalformed JSON, missing fields, or invalid tool arguments.
429rate_limitedToo many requests. Back off and retry with exponential delay.
500server_errorUnexpected server error. Safe to retry after backoff.