API Documentation

Complete reference for the WAPDeskPro REST API. Send WhatsApp messages, media files, bulk campaigns and set up webhooks โ€” all via simple HTTP requests.

Overview

WAPDeskPro provides a REST API that lets you send WhatsApp messages programmatically. You connect your WhatsApp number by scanning a QR code, then use your API token to send messages via HTTP POST requests from any programming language or tool.

Free Trial: Send messages to up to 30 unique recipients for free โ€” no credit card required. Create your account โ†’

Authentication

All API requests require a Bearer token in the Authorization header. You can find your API token in the dashboard under Settings โ†’ API Token.

Authorization: Bearer YOUR_API_TOKEN
Keep your API token secret. Never expose it in frontend JavaScript or public repositories.

Base URL

All endpoints are relative to your server's base URL:

https://wapdeskpro.com/api

If you are self-hosting, replace with your own domain.

Send Text Message

POST /api/send Send a plain text WhatsApp message

Request Body

ParameterTypeRequiredDescription
phone_idstringRequiredYour connected WhatsApp phone ID from the dashboard
tostringRequiredRecipient phone number with country code (e.g. 919876543210)
messagestringRequiredText content to send

Example Request

curl -X POST https://wapdeskpro.com/api/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "to": "919876543210",
    "message": "Hello! Your order has been confirmed."
  }'

Example Response

200 OK
{
  "success": true,
  "message_id": "3EB0C767D9B1A37B4A89",
  "to": "919876543210",
  "status": "sent"
}

Send Image

POST /api/send-image Send an image with optional caption

Request Body

ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
tostringRequiredRecipient phone number
urlstringRequiredPublicly accessible image URL (JPG, PNG, WEBP)
captionstringOptionalCaption text below the image
curl -X POST https://wapdeskpro.com/api/send-image \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "to": "919876543210",
    "url": "https://example.com/product.jpg",
    "caption": "Check out our new product! ๐ŸŽ‰"
  }'

Send Video

POST /api/send-video Send a video file
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
tostringRequiredRecipient phone number
urlstringRequiredPublicly accessible video URL (MP4)
captionstringOptionalCaption text
curl -X POST https://wapdeskpro.com/api/send-video \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "to": "919876543210",
    "url": "https://example.com/demo.mp4",
    "caption": "Watch our product demo"
  }'

Send Document

POST /api/send-document Send a PDF or document file
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
tostringRequiredRecipient phone number
urlstringRequiredURL to PDF/DOCX/XLSX file
filenamestringOptionalDisplay filename (e.g. invoice.pdf)
curl -X POST https://wapdeskpro.com/api/send-document \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "to": "919876543210",
    "url": "https://example.com/invoice.pdf",
    "filename": "Invoice_2025.pdf"
  }'

Send Audio

POST /api/send-audio Send an audio message
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
tostringRequiredRecipient phone number
urlstringRequiredURL to MP3/OGG/WAV file

Send Location

POST /api/send-location Share a GPS location pin
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
tostringRequiredRecipient phone number
latnumberRequiredLatitude (e.g. 28.6139)
lngnumberRequiredLongitude (e.g. 77.2090)
namestringOptionalLocation name label
curl -X POST https://wapdeskpro.com/api/send-location \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "to": "919876543210",
    "lat": 28.6139,
    "lng": 77.2090,
    "name": "Our Store โ€” New Delhi"
  }'

Bulk Send

Send a message to multiple recipients in one request. WAPDeskPro adds a random delay between messages to simulate natural human behavior and reduce ban risk.

POST /api/bulk-send Send message to multiple recipients
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
numbersarrayRequiredArray of phone numbers with country code
messagestringRequiredText message to send
delaynumberOptionalDelay between messages in ms (default: 2000)
curl -X POST https://wapdeskpro.com/api/bulk-send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "numbers": ["919876543210", "918765432109", "917654321098"],
    "message": "๐ŸŽ‰ Sale starts today! Visit our store.",
    "delay": 3000
  }'

Google Sheets Integration

Import contacts directly from a Google Sheet. The sheet must have phone numbers in the first column. Make the sheet publicly readable, then provide the sheet ID.

The Google Sheet must be set to "Anyone with the link can view" for this to work.
POST /api/bulk-sheets Send message to contacts from Google Sheet
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
sheet_idstringRequiredGoogle Sheet ID from the URL
messagestringRequiredMessage to send to all contacts

List Connected Phones

GET /api/phones Get all connected WhatsApp numbers
curl https://wapdeskpro.com/api/phones \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response
{
  "success": true,
  "phones": [
    {
      "phone_id": "ph_abc123",
      "number": "919876543210",
      "name": "Business Line",
      "status": "connected",
      "plan": "pro"
    }
  ]
}

Phone Status

GET /api/phones/:phone_id/status Check if a phone is connected
curl https://wapdeskpro.com/api/phones/ph_abc123/status \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Response
{
  "phone_id": "ph_abc123",
  "status": "connected",
  "battery": 87,
  "last_seen": "2025-04-16T10:30:00Z"
}

Webhooks

Set up a webhook URL to receive incoming WhatsApp messages in real time. WAPDeskPro will send a POST request to your URL whenever a message is received on your connected number.

POST /api/webhook/set Set webhook URL for a phone
ParameterTypeRequiredDescription
phone_idstringRequiredConnected WhatsApp phone ID
webhook_urlstringRequiredYour server URL to receive events
curl -X POST https://wapdeskpro.com/api/webhook/set \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_id": "ph_abc123",
    "webhook_url": "https://yourserver.com/whatsapp-hook"
  }'

Webhook Payload

When a message is received, WAPDeskPro sends this JSON payload to your webhook URL:

{
  "event": "message.received",
  "phone_id": "ph_abc123",
  "from": "919876543210",
  "message": {
    "id": "3EB0C767D9B1",
    "type": "text",
    "text": "Hello, I need help with my order",
    "timestamp": 1713254400
  }
}
Your webhook endpoint must respond with HTTP 200 within 10 seconds, otherwise WAPDeskPro will retry the delivery.

AI Auto-Reply Configuration

Configure the AI bot for a phone via API. The bot automatically replies to incoming messages using Google Gemini or OpenAI GPT. Available on Pro plan only.

POST /auth/ai-config Save AI bot configuration for a phone
ParameterTypeRequiredDescription
phone_idstringRequiredPro phone ID to configure
providerstringRequiredgemini or openai
modelstringOptionalModel ID (e.g. gemini-2.5-flash)
api_keystringRequiredYour Gemini or OpenAI API key
system_promptstringOptionalInstructions for how the AI should respond
is_enabledbooleanOptionalEnable or disable the bot

MCP Server (Claude & AI agents)

WapDeskPro includes a Model Context Protocol (MCP) server, so Claude and other MCP clients can read and send WhatsApp messages for one of your numbers. Every tool calls the REST API on this page, so authentication and plan limits are the same. MCP tools are available on all plans. Overview and setup walkthrough: WhatsApp MCP for Claude.

POST https://wapdeskpro.com/mcp Streamable HTTP, stateless
EndpointPurpose
POST /mcpMCP JSON-RPC endpoint. GET and DELETE return 405 (no sessions, no SSE stream).
/.well-known/oauth-protected-resource/mcpProtected resource metadata
/.well-known/oauth-authorization-serverAuthorization server metadata
/authorize, /token, /register, /revokeOAuth endpoints (with dynamic client registration)

Authentication

1. OAuth 2.1 (recommended). Add https://wapdeskpro.com/mcp as a custom connector in Claude (Settings โ†’ Connectors). The client registers itself and opens the WapDeskPro login page; the user logs in, chooses one WhatsApp number and clicks Allow.

  • Authorization code with PKCE (S256) and refresh tokens. Scope: whatsapp.
  • Access tokens last 1 hour; refresh tokens last 90 days and rotate on each use. Tokens are stored as SHA-256 hashes.
  • A token is bound to the chosen number. Unauthenticated requests get 401 with a WWW-Authenticate header pointing to the resource metadata.

2. API token headers (clients without OAuth). Send these with every request to /mcp:

x-maytapi-key: <phone token or product admin token>
x-product-id:  <product_id>
x-phone-id:    <phone_id>

Invalid credentials return 401 with JSON-RPC error -32001. Find the values in the dashboard under AI Agent โ†’ API & MCP โ†’ Developer options.

Client setup

Claude Code (then run /mcp to log in):

claude mcp add --transport http wapdeskpro https://wapdeskpro.com/mcp

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "wapdeskpro": { "url": "https://wapdeskpro.com/mcp" }
  }
}
Coming soon: a local stdio package for Claude Desktop and Cursor, configured with WA_API_URL, WA_PRODUCT_ID, WA_PHONE_ID and WA_API_KEY.

Tools

ToolInputsNotes
whatsapp_statusโ€”Connection, number, name, plan
list_conversationssearch?Contacts newest first; message and AI counts, ai_paused, crm_status
read_chatcontact, limit? (1โ€“500, default 50)Oldest first; sender is customer / AI / agent
send_messageto, text, pause_ai?Text only. New numbers count toward the plan recipient limit
ai_replycontactConfigured AI agent replies to the latest message
set_ai_pausedcontact, pausedHuman takeover per contact
get_agent_configโ€”AI on/off, provider, model, prompt, CRM / Sheet sync
set_agent_enabledenabledAI auto-reply on/off for the number
push_contact_to_crmcontactSends to the configured Google Sheet / CRM webhook
list_groupssearch?id, name, member count
send_group_messagegroup (id or name), textA group counts as one recipient
get_activitysince?, until? (ISO 8601), include_messages?Default last 24 h; up to 1,000 messages
search_messagesquery, since?, limit? (1โ€“500)Newest first
export_chatcontact?, format? (txt / csv / json)All contacts if contact is omitted

Phone numbers use country code + digits only, e.g. 919876543210. Group ids look like 120363012345678901@g.us.

WapDeskPro is an unofficial WhatsApp Web based API (Baileys), not affiliated with Meta. Keep tool approval on for the sending tools and avoid unsolicited bulk messages.

Error Codes

CodeMeaningAction
400Bad RequestCheck required parameters
401UnauthorizedInvalid or missing API token
403ForbiddenFeature not available on your plan
404Not FoundPhone ID not found or not connected
429Rate LimitedSlow down requests, add delay
500Server ErrorTry again; contact support if persists

Rate Limits

  • Trial plan: Max 30 unique recipients total
  • Pro plan: No recipient limit. Recommended: 1 message every 2โ€“5 seconds to avoid WhatsApp flagging
  • Bulk send: Built-in random delay (2โ€“5s) between messages by default
  • API requests: 100 requests/minute per token
Sending too many messages too fast may result in your WhatsApp number being temporarily restricted. Always use delays in bulk campaigns.