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.
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
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
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Your connected WhatsApp phone ID from the dashboard |
| to | string | Required | Recipient phone number with country code (e.g. 919876543210) |
| message | string | Required | Text 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
{
"success": true,
"message_id": "3EB0C767D9B1A37B4A89",
"to": "919876543210",
"status": "sent"
}
Send Image
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| to | string | Required | Recipient phone number |
| url | string | Required | Publicly accessible image URL (JPG, PNG, WEBP) |
| caption | string | Optional | Caption 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| to | string | Required | Recipient phone number |
| url | string | Required | Publicly accessible video URL (MP4) |
| caption | string | Optional | Caption 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| to | string | Required | Recipient phone number |
| url | string | Required | URL to PDF/DOCX/XLSX file |
| filename | string | Optional | Display 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| to | string | Required | Recipient phone number |
| url | string | Required | URL to MP3/OGG/WAV file |
Send Location
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| to | string | Required | Recipient phone number |
| lat | number | Required | Latitude (e.g. 28.6139) |
| lng | number | Required | Longitude (e.g. 77.2090) |
| name | string | Optional | Location 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| numbers | array | Required | Array of phone numbers with country code |
| message | string | Required | Text message to send |
| delay | number | Optional | Delay 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| sheet_id | string | Required | Google Sheet ID from the URL |
| message | string | Required | Message to send to all contacts |
List Connected Phones
curl https://wapdeskpro.com/api/phones \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"success": true,
"phones": [
{
"phone_id": "ph_abc123",
"number": "919876543210",
"name": "Business Line",
"status": "connected",
"plan": "pro"
}
]
}
Phone Status
curl https://wapdeskpro.com/api/phones/ph_abc123/status \
-H "Authorization: Bearer YOUR_API_TOKEN"
{
"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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Connected WhatsApp phone ID |
| webhook_url | string | Required | Your 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
}
}
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone_id | string | Required | Pro phone ID to configure |
| provider | string | Required | gemini or openai |
| model | string | Optional | Model ID (e.g. gemini-2.5-flash) |
| api_key | string | Required | Your Gemini or OpenAI API key |
| system_prompt | string | Optional | Instructions for how the AI should respond |
| is_enabled | boolean | Optional | Enable 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.
| Endpoint | Purpose |
|---|---|
| POST /mcp | MCP JSON-RPC endpoint. GET and DELETE return 405 (no sessions, no SSE stream). |
| /.well-known/oauth-protected-resource/mcp | Protected resource metadata |
| /.well-known/oauth-authorization-server | Authorization server metadata |
| /authorize, /token, /register, /revoke | OAuth 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" }
}
}
Tools
| Tool | Inputs | Notes |
|---|---|---|
| whatsapp_status | โ | Connection, number, name, plan |
| list_conversations | search? | Contacts newest first; message and AI counts, ai_paused, crm_status |
| read_chat | contact, limit? (1โ500, default 50) | Oldest first; sender is customer / AI / agent |
| send_message | to, text, pause_ai? | Text only. New numbers count toward the plan recipient limit |
| ai_reply | contact | Configured AI agent replies to the latest message |
| set_ai_paused | contact, paused | Human takeover per contact |
| get_agent_config | โ | AI on/off, provider, model, prompt, CRM / Sheet sync |
| set_agent_enabled | enabled | AI auto-reply on/off for the number |
| push_contact_to_crm | contact | Sends to the configured Google Sheet / CRM webhook |
| list_groups | search? | id, name, member count |
| send_group_message | group (id or name), text | A group counts as one recipient |
| get_activity | since?, until? (ISO 8601), include_messages? | Default last 24 h; up to 1,000 messages |
| search_messages | query, since?, limit? (1โ500) | Newest first |
| export_chat | contact?, 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.
Error Codes
| Code | Meaning | Action |
|---|---|---|
| 400 | Bad Request | Check required parameters |
| 401 | Unauthorized | Invalid or missing API token |
| 403 | Forbidden | Feature not available on your plan |
| 404 | Not Found | Phone ID not found or not connected |
| 429 | Rate Limited | Slow down requests, add delay |
| 500 | Server Error | Try 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