WhatsApp API Documentation

Complete reference for the WhatsApp REST API. Authentication, endpoints, webhooks, error codes, and code examples.

Authentication

All API requests require an API key passed in the Authorization header. Your API key is generated when you create an instance and can be found in your dashboard.

Authorization: Bearer YOUR_API_KEY

Requests without a valid API key return a 401 Unauthorized error. API keys are scoped to instances — each instance has its own key.

Base URL

https://api2whats.com

All endpoints are relative to this base URL. Use HTTPS only — HTTP requests are rejected.

Send Text Message

Send a text message to a WhatsApp number.

POST /send-text

Request body:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

Parameters:

• to (string, required) — Recipient phone number with country code, no + or spaces
• message (string, required) — Text content, supports Unicode and emoji

Response:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

Send Image

Send an image via URL or Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

Parameters:

• to (string, required) — Recipient phone number
• image (string, required) — Image URL or Base64-encoded string
• caption (string, optional) — Text caption below the image

Send Video

Send a video file.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

Send Audio

Send an audio file (voice note or audio clip).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

Send Sticker

Send a sticker image (WebP or PNG format).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

Send Document

Send a file attachment (PDF, DOCX, XLSX, etc.).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

Parameters:

• to (string, required) — Recipient phone number
• document (string, required) — Document URL or Base64-encoded string
• filename (string, optional) — Display filename (defaults to URL filename)

Send Location

Send a geographic location pin.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

Webhook Configuration

Webhooks let your server receive incoming messages in real time. Set your webhook URL via the API:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

When someone sends a message to your connected number, the API sends a POST request to your URL:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

Verify incoming webhooks using the X-Signature header included with every request.

Instance Management

Check the connection status of your WhatsApp instance:

GET /instance/status

Response:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

Error Codes

Rate Limits

Rate limits vary by plan:

• Basic — 100 requests/minute
• Professional — 300 requests/minute
• Enterprise — 1000 requests/minute

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating when you can retry.

Code Samples

Working examples in PHP, Python, JavaScript, and cURL are available in our code samples section. Each sample is a complete, runnable script.

Pagination and Limits

When listing resources (instances, message history), the API supports pagination via query parameters:

GET /messages?page=1&limit=50

Response:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

Default page size is 50. Maximum is 100. Use the page and limit query parameters to navigate through results.

Batch Sending

Send messages to multiple recipients in a single API call. This is more efficient than making individual requests for each recipient.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

Batch sending applies rate limiting automatically. The response includes per-message status so you know which messages succeeded and which failed.

Media Upload Guidelines

When sending media, follow these guidelines for optimal delivery:

• Images — JPEG or PNG, max 5MB via Base64, larger via URL. Recommended dimensions: 1200x630 for landscape, 600x600 for square.
• Videos — MP4 format, max 16MB. H.264 encoding recommended for best compatibility.
• Documents — PDF, DOCX, XLSX, PPTX, TXT. Max 100MB via URL.
• Audio — MP3 or OGG format. Max 16MB.
• Stickers — WebP or PNG, 512x512 pixels, max 500KB.
• Locations — Latitude/longitude coordinates with optional name and address.

For Base64 encoding, include the data URI prefix: data:image/jpeg;base64,/9j/4AAQ.... For URLs, ensure the URL is publicly accessible and returns the correct Content-Type header.

Environment Variables

Store your API key and configuration in environment variables, not in your code:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

Never commit your .env file to version control. Add it to .gitignore. Use your deployment platform's environment variable settings for production.

Versioning

The API is versioned via URL path. The current version is v1 (the default). When we introduce breaking changes, we will release a new version and maintain the old one for at least 12 months.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

Changelog

We maintain a public changelog for all API changes. Subscribe to the changelog RSS feed or follow us on GitHub to stay updated. Major changes are announced via email to all registered users at least 30 days before deployment.

Need Help?

Check the FAQ for common questions. For specific issues, contact our support team. We respond within 24 hours.

FAQ

What is the maximum message length?

Text messages support up to 4,096 characters. For longer content, consider sending a document or splitting the message across multiple sends.

Can I send messages to groups?

Currently, the API supports 1-on-1 messaging only. Group messaging is on our roadmap for a future release.

How fast are messages delivered?

Most messages are delivered within 1-3 seconds. Delivery time depends on the recipient's network connection and device status. Messages to offline devices are queued by WhatsApp and delivered when the device comes online.

Is there a free tier?

You can create an account and explore the dashboard for free. Paid plans start at $9.99/month for API access and message sending. Contact us for trial access.

What happens if my API key is compromised?

Immediately revoke the compromised key from your dashboard and generate a new one. All active sessions using the old key will be terminated. We recommend rotating API keys periodically and storing them in environment variables.

Can I use the API for bulk messaging?

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

Status Page

Check our system status and historical uptime at our status page. We provide real-time updates during incidents and post detailed post-mortems for any service disruptions.