API Documentation

Send WhatsApp messages from your own number with simple HTTP requests. No SDK required — works from browser, cURL, PHP, Python, Node.js, Google Sheets, and more.

Send a text message One GET request — the fastest way to start Send image or PDF Media from a public URL with optional caption Check connection status See if WhatsApp is linked and daily usage Advanced topics REST API, groups, webhooks & more

Quick start

Send your first message with a GET request:

Successful response:

JSON{ "success": true, "message": "Message sent" }

Base URL

All API requests are made to your MessageAPI instance:

Paths in this document are relative to the base URL above.

Authentication

Every API request requires your API key. Pass it in one of two ways:

Method	Example
Query parameter	`?apikey=msg_your_key_here`
HTTP header	`X-API-Key: msg_your_key_here`

Keep your API key secret. Never expose it in public client-side code.

Tip: prefer the X-API-Key header over query params to keep your key out of logs and browser history.

Prerequisites

Before calling the API, ensure the following:

WhatsApp is connected in Settings (QR scan). Sending fails with HTTP 400 while disconnected.
Your account has an active trial or paid subscription. Expired accounts return HTTP 403.
You have an API key from Settings. It is required on every request.

Endpoints overview

Two interfaces are available: a simple GET API at /send.php and a JSON REST API under /api/v1/. Authentication is the same for both.

Method	Path	Description
`GET`	`/send.php`	Send text, image or PDF via query parameters
`POST`	`/api/v1/send`	Send a text message (JSON body)
`POST`	`/api/v1/send/image`	Send an image from a public URL
`POST`	`/api/v1/send/document`	Send a PDF from a public URL
`GET`	`/api/v1/status`	WhatsApp connection status and daily usage
`GET`	`/api/v1/messages/:id`	Check delivery status of a sent message

Response format

Every endpoint returns JSON. Successful operations use HTTP 200. Client and server errors use 4xx codes with a descriptive message.

Success (HTTP 200)

JSON{ "success": true, "message": "Message sent", "messageId": "550e8400-e29b-41d4-a716-446655440000" }

Every send endpoint returns a messageId. Use it with GET /api/v1/messages/:id to check delivery status.

Error (4xx)

JSON{ "error": "recipient is required" }

When a send attempt fails after the message is logged, the error response may include messageId as well.

Example — missing parameter:

HTTP 400{ "error": "text is required" }

Send text message

GET /send.php

Send a plain-text WhatsApp message. The simplest integration — a single GET request.

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone with country code, no + (e.g. 12125551234) or group ID (e.g. 120363...@g.us)
`apikey`	string	Yes	Your API key
`text`	string	Yes	Message body

cURL

Send image

GET /send.php

Send an image from a direct public URL. Optional caption with the text parameter.

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone or group ID (120363...@g.us)
`apikey`	string	Yes	Your API key
`file`	string	Yes	Direct public URL to the image (.jpg, .png, etc.)
`text`	string	No	Caption text

If the image URL contains & or ?, encode it with encodeURIComponent() before adding it to the request. Use direct image links — stock photo sites often block downloads.

Send PDF document

GET /send.php

Send a PDF document from a direct public URL.

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone or group ID (120363...@g.us)
`apikey`	string	Yes	Your API key
`document`	string	Yes	Direct public URL to a PDF file
`filename`	string	No	Display name (default: document.pdf)

Check connection status

GET /api/v1/status

Check whether WhatsApp is connected and how many messages you have sent in the rolling 24-hour window.

Or pass the API key as a header:

Response example:

JSON{ "connected": true, "phone": "12125551234", "dailyLimit": 50, "messagesToday": 12 }

Response fields:

Field	Type	Description
`connected`	boolean	true if WhatsApp is linked and ready to send
`phone`	string	Connected number (country code, no +), or null
`dailyLimit`	integer \| null	Daily cap for your plan. null on Unlimited
`messagesToday`	integer	Messages sent in the last 24 hours

dailyLimit is null on the Unlimited plan (no cap). Trial: 50/day · Personal: 150/day.

Message delivery status

GET /api/v1/messages/:id

After sending a message, use the returned messageId to check whether it was delivered or failed.

Requires the X-API-Key header. You can only query messages sent by your own account.

Response example:

JSON{ "id": "550e8400-e29b-41d4-a716-446655440000", "recipient": "12125551234", "type": "text", "status": "sent", "error": null, "createdAt": "2026-05-26T23:00:00.000Z" }

Status values

Field	Description
`pending`	Send in progress
`sent`	Delivered to WhatsApp successfully
`failed`	Send failed — see `error`

Errors & limits

Rate limits

Limits apply per account on a rolling 24-hour window. The status endpoint returns your current usage.

Daily message limits depend on your plan:

Plan	Daily limit
Trial	50 messages
Personal	150 messages
Unlimited	No limit

Error (4xx)

HTTP code	Meaning
`400`	Bad request — missing params, WhatsApp not connected, invalid URL
`401`	Invalid or missing API key
`403`	Subscription inactive or expired
`429`	Daily message limit reached

Personal plan allows up to 5 recipients (no groups). Unlimited supports any recipient and groups.

Advanced topics

REST API (JSON)

For integrations that prefer POST requests with JSON bodies and header authentication.

All REST endpoints require the X-API-Key header and Content-Type: application/json.

POST /api/v1/send

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone or group ID
`to`	string	No	Alias for recipient (REST only)
`text`	string	Yes	Message body

POST /api/v1/send/image

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone or group ID
`file`	string	Yes	Direct public URL to the image
`image`	string	No	Alias for file (REST image endpoint)
`text` / `caption`	string	No	Caption text

POST /api/v1/send/document

Parameter	Type	Required	Description
`recipient`	string	Yes	Phone or group ID
`document`	string	Yes	Direct public URL to a PDF file
`filename`	string	No	Display name (default: document.pdf)

Send to groups

Use the same endpoints as for individual chats. Set recipient to the group ID (120363...@g.us) instead of a phone number.

Your connected number must be a group admin and stay in the group. Group messages count toward your daily limit.

Get the Group ID

In WhatsApp, open the group → Invite via link → copy the link.
In Settings, open Message groups, paste the link, and copy the result.

Send text to a group

Parameter	Required	Description
`recipient`	Yes	Group ID from Settings (e.g. 120363...@g.us)
`apikey`	Yes	Your API key
`text`	Yes	Message body

Send image or PDF to a group

Same parameters as Send image or Send PDF — only change recipient to the group ID.

REST API

Webhooks

With the Unlimited plan, MessageAPI can POST events to your server. Configure the webhook URL in Settings.

Available on the Unlimited plan only. WhatsApp must stay connected for incoming messages. Text messages only (v1).

Example handler

Download a minimal PHP script that logs each webhook request to a file. Upload it to your server, paste the URL in Settings, and use Test incoming to verify.

Download webhook-logger.php

Disconnect alerts

All plans can receive an email when WhatsApp disconnects. Enable or disable this in Settings → WhatsApp Connection. Unlimited accounts also receive a session.disconnected webhook event.

Event types

Event	Description
`message.received`	Someone sent a text message to your WhatsApp
`message.sent`	An outbound message was delivered successfully
`message.failed`	An outbound message failed to send
`session.disconnected`	WhatsApp disconnected and could not be restored automatically

Incoming message payload

Every delivery is a POST with Content-Type: application/json:

JSON{ "event": "message.received", "timestamp": "2026-05-26T23:00:00.000Z", "message": { "id": "3EB0...", "from": "12125551234", "fromJid": "12125551234@s.whatsapp.net", "pushName": "Juan", "isGroup": false, "groupId": null, "participant": null, "type": "text", "text": "Hello" } }

For group messages, isGroup is true, groupId is set, and participant is the sender's number.

Delivery status payload

After each send via the API, MessageAPI can notify your webhook when the message is sent or fails:

JSON — message.sent{ "event": "message.sent", "timestamp": "2026-05-26T23:00:00.000Z", "message": { "id": "550e8400-e29b-41d4-a716-446655440000", "recipient": "12125551234", "type": "text", "status": "sent", "error": null, "createdAt": "2026-05-26T23:00:00.000Z" } }

JSON — message.failed{ "event": "message.failed", "timestamp": "2026-05-26T23:00:01.000Z", "message": { "id": "550e8400-e29b-41d4-a716-446655440000", "recipient": "12125551234", "type": "text", "status": "failed", "error": "WhatsApp not connected. Scan QR code in Settings.", "createdAt": "2026-05-26T23:00:00.000Z" } }

The message.id matches the messageId returned by send endpoints and the status query.

Disconnect payload

JSON — session.disconnected{ "event": "session.disconnected", "timestamp": "2026-05-26T23:00:00.000Z", "session": { "phone": "12125551234", "reason": "connection_lost", "status": "disconnected" } }

reason is logged_out when WhatsApp was unlinked from another device, or connection_lost when the session could not be restored automatically.

Your endpoint

Respond with HTTP 200 to acknowledge receipt.
Use HTTPS in production.
Use Send test in Settings to verify your integration.
Use Test delivery in Settings to simulate a message.sent event.

Responsible use

Messages are sent from your own WhatsApp number. WhatsApp enforces its own limits and may restrict accounts that send unsolicited or high-volume messages.