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

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

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

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

POST /api/send-video Send a video file

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

POST /api/send-document Send a PDF or document file

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

POST /api/send-audio Send an audio message

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

POST /api/send-location Share a GPS location pin

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.

POST /api/bulk-send Send message to multiple recipients

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.

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

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

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

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
  }
}

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

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

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

Sending too many messages too fast may result in your WhatsApp number being temporarily restricted. Always use delays in bulk campaigns.