API Documentation — WhatsApp Messaging API | WhatsApp API by Retention Stack

Getting Started

From zero to your first WhatsApp message in under 5 minutes.

1
Subscribe on RapidAPI
Head to the RapidAPI listing and subscribe to the free Basic plan (no credit card required). You'll receive an x-rapidapi-key header value.
2
Create a Session
Call POST /v1/sessions with a name for your session. A session represents one WhatsApp account.
3
Authenticate via QR Code
Fetch the QR code image from GET /v1/{session}/auth/qr and scan it with WhatsApp on your phone.
4
Send Your First Message
Call POST /v1/sendText with a chatId (phone number), text, and session name.

Authentication

All requests require two headers provided by RapidAPI.

Header	Value	Required
x-rapidapi-key	Your RapidAPI key	Yes
x-rapidapi-host	whatsapp-messaging-bot.p.rapidapi.com	Yes
Content-Type	application/json	For POST/PUT/PATCH

💡Your API key is available on the RapidAPI dashboard after subscribing. Never expose it in client-side code — always call the API from your server.

Base URL & Versioning

https://whatsapp-messaging-bot.p.rapidapi.com/v1

All endpoints are prefixed with /v1. The current stable API version is v1. Breaking changes will result in a new version prefix (/v2).

Sessions

A session = one authenticated WhatsApp account. You must create and authenticate a session before sending messages.

Method	Path	Description
GET	/v1/sessions	List all sessions
POST	/v1/sessions	Create a new session
GET	/v1/sessions/{session}	Get session details
DELETE	/v1/sessions/{session}	Delete a session
POST	/v1/sessions/start	Start a session
POST	/v1/sessions/stop	Stop a session
GET	/v1/{session}/auth/qr	Get QR code image for authentication
GET	/v1/{session}/auth/pairing-code	Request pairing code (phone number auth)
POST	/v1/sessions/logout	Log out the session

Create Session

create_session.sh

curl -X POST "https://whatsapp-messaging-bot.p.rapidapi.com/v1/sessions" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com" \
  -H "Content-Type: application/json"

Get QR Code

get_qr.sh

curl -G "https://whatsapp-messaging-bot.p.rapidapi.com/v1/{session}/auth/qr" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com" \
  --data-urlencode "format=binary"
# Returns a PNG image you can display for scanning

Webhooks

Receive real-time events from a WhatsApp session via HTTP POST to your server.

Method	Path	Description
POST	/v1/sessions/{session}/webhooks	Register a webhook URL for a session
DELETE	/v1/sessions/{session}/webhooks	Remove a registered webhook URL

Register a Webhook

add_webhook.sh

curl -X POST "https://whatsapp-messaging-bot.p.rapidapi.com/v1/sessions/{session}/webhooks"   -H "x-rapidapi-key: YOUR_API_KEY"   -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com"   -H "Content-Type: application/json"   -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "events": ["message", "session.status"]
  }'

Request body fields

webhookUrl (required) — The HTTPS URL that will receive POST requests for each event.
events — Array of event names to subscribe to. Defaults to ["message"] if omitted.
hmacKey — Optional secret key. When set, each request includes an X-Webhook-Hmac signature header for verification.
retries — Optional retry config: { policy: "exponential", delaySeconds: 2, attempts: 5 }
customHeaders — Optional array of { name, value } headers added to every webhook request (e.g. for token auth).

Supported `events` values

Event	Description
session.status	Session state changes: STARTING, SCAN_QR_CODE, AUTHENTICATED, STOPPED, FAILED
message	New incoming messages only
message.any	All messages — both incoming and outgoing
message.reaction	Reactions added to messages
message.ack	Message delivery and read acknowledgements
message.waiting	Waiting for message delivery confirmation
message.revoked	Messages that were deleted or recalled
message.edited	Messages that were edited after sending
chat.archive	Chat archived or unarchived
group.v2.join	Joined a group (new API)
group.v2.leave	Left a group (new API)
group.v2.update	Group settings updated (new API)
group.v2.participants	Participant added or removed (new API)
group.join	Joined a group (legacy)
group.leave	Left a group (legacy)
presence.update	Contact's online/offline/typing status changed
poll.vote	A vote was cast on a poll
poll.vote.failed	A poll vote attempt failed
call.received	Incoming call received
call.accepted	Call was accepted
call.rejected	Call was rejected
label.upsert	Label created or updated
label.deleted	Label deleted
label.chat.added	Label applied to a chat
label.chat.deleted	Label removed from a chat
event.response	Event response received
event.response.failed	Event response failed
engine.event	Internal engine-level event

Messages

Send any WhatsApp message type to contacts, groups, or channels.

Method	Path	Description
POST	/v1/sendText	Send a text message
POST	/v1/sendImage	Send an image with optional caption
POST	/v1/sendFile	Send any file (PDF, DOCX, etc.)
POST	/v1/sendVideo	Send a video message
POST	/v1/sendVoice	Send a voice note
POST	/v1/sendLocation	Send a location pin
POST	/v1/sendContactVcard	Share a contact card
POST	/v1/sendPoll	Send a poll
POST	/v1/reply	Reply to a message
POST	/v1/sendSeen	Mark message as read
POST	/v1/startTyping	Start typing indicator
POST	/v1/stopTyping	Stop typing indicator

Send Text Message

send_text.py

curl -X POST "https://whatsapp-messaging-bot.p.rapidapi.com/v1/sendText" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "1234567890",
    "text": "Check this out: https://example.com",
    "session": "default",
    "linkPreview": true,
    "linkPreviewHighQuality": true
  }'

Send Image

send_image.sh

curl -X POST "https://whatsapp-messaging-bot.p.rapidapi.com/v1/sendImage" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "1234567890",
    "session": "default",
    "file": {
      "url": "https://example.com/photo.jpg",
      "mimetype": "image/jpeg"
    },
    "caption": "Check this out!"
  }'

chatId Formats

Type	chatId Example	Notes
Individual	1234567890	Phone number only — country code auto-detected
Group	120363024802736123@g.us	Obtain from GET /v1/sessions/{session}/groups
Channel	120363024802736123@s.whatsapp.net	Obtain from channel search endpoint

Link Preview Support (sendText)

The /v1/sendText endpoint supports automatic link preview generation:

linkPreview (boolean, optional): Set to true to enable link preview for any URLs in your message text.
linkPreviewHighQuality (boolean, optional): Set to true to enable high-quality link previews (requires additional upload to WhatsApp servers).

Example: Sending a message with URL "Check this: https://example.com" with linkPreview: true will generate and display a preview card in WhatsApp.

Groups

Create, manage, and configure WhatsApp Groups via API.

Method	Path	Description
GET	/v1/sessions/{session}/groups	List all groups
POST	/v1/sessions/{session}/groups	Create a new group
GET	/v1/sessions/{session}/groups/{groupId}	Get group details
DELETE	/v1/sessions/{session}/groups/{groupId}	Delete a group
POST	/v1/sessions/{session}/groups/{groupId}/leave	Leave a group
PUT	/v1/sessions/{session}/groups/{groupId}/subject	Update group name
PUT	/v1/sessions/{session}/groups/{groupId}/description	Update group description
POST	/v1/sessions/{session}/groups/{groupId}/participants/add	Add participants
POST	/v1/sessions/{session}/groups/{groupId}/participants/remove	Remove participants
POST	/v1/sessions/{session}/groups/{groupId}/admin/promote	Promote to admin
POST	/v1/sessions/{session}/groups/{groupId}/admin/demote	Demote from admin

Create Group

create_group.sh

curl -X POST "https://whatsapp-messaging-bot.p.rapidapi.com/v1/sessions/{session}/groups" \
  -H "x-rapidapi-key: YOUR_API_KEY" \
  -H "x-rapidapi-host: whatsapp-messaging-bot.p.rapidapi.com" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Team",
    "participants": [
      {"id": "1234567890@c.us"},
      {"id": "9876543210@c.us"}
    ]
  }'

Channels

Broadcast to unlimited subscribers with WhatsApp Channels (broadcast-only).

Method	Path	Description
GET	/v1/sessions/{session}/channels	List subscribed channels
POST	/v1/sessions/{session}/channels	Create a channel
GET	/v1/sessions/{session}/channels/{channelId}	Get channel details
DELETE	/v1/sessions/{session}/channels/{channelId}	Delete a channel
GET	/v1/sessions/{session}/channels/{channelId}/messages/preview	Get channel preview messages

Contacts

Check WhatsApp registration status.

Method	Path	Description
GET	/v1/contacts/check-exists?phone={phone}&session={session}	Check if phone number is on WhatsApp

ℹ️Use the check-exists endpoint before messaging to avoid sending to non-WhatsApp numbers, which saves quota.

Presence

Set typing indicators, read receipts, and online status.

Method	Path	Description
POST	/v1/sessions/{session}/presence	Set session presence (online/offline/typing/recording/paused)
GET	/v1/sessions/{session}/presence	Get all chats presence
POST	/v1/startTyping	Start typing indicator in a chat
POST	/v1/stopTyping	Stop typing indicator in a chat
POST	/v1/sendSeen	Mark messages as read

Error Handling

All errors return a consistent JSON body.

errors.json

// All errors follow this shape:
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "chatId is required"
}

// HTTP status codes used:
// 400 Bad Request      — invalid or missing parameters
// 401 Unauthorized     — missing or invalid API key
// 404 Not Found        — session or resource not found
// 409 Conflict         — session already exists
// 429 Too Many Reqs    — rate limit exceeded
// 500 Internal Error   — server-side error (retry)

HTTP Code	Meaning	Recommendation
400	Bad Request	Fix request body / query params
401	Unauthorized	Check your x-rapidapi-key
404	Not Found	Verify session name / resource ID
409	Conflict	Session name already exists — use a different name
429	Too Many Requests	Implement exponential backoff; upgrade plan
500	Internal Server Error	Retry with backoff; contact support if persistent

Rate Limits

Limits apply per API key per plan.

Plan	Requests / Month	Req / Second	Sessions
Basic (Free)	100	10	1
Pro	1,000	10	3
Ultra	10,000	20	10
Mega	50,000	25	Unlimited

⚠️When you hit the rate limit you receive a 429 Too Many Requests response. Implement exponential backoff starting at 1 second.

OpenAPI / Swagger

Full OpenAPI 3.0 specification — browse, search, and test every endpoint interactively.

{ }

Interactive API Reference

Browse every endpoint, view request/response schemas, and use the live Try-it-out panel — all powered by the bundled OpenAPI 3.0 spec.

SessionsMessagesGroupsChannelsContactsPresence

The raw spec file is also available for download or import into Postman, Insomnia, or any OpenAPI-compatible toolchain:

Download openapi.json View on RapidAPI

FAQ

Do I need a WhatsApp Business account?

No. You just need a regular WhatsApp account on a phone number. Authenticate via QR code or pairing code through the API.

Can I run multiple WhatsApp numbers simultaneously?

Yes. Create one session per number. Basic allows 1 session, Pro allows 3, Ultra allows 10, and Mega is unlimited.

What happens if I exceed my monthly quota?

On the Basic plan, requests are hard-blocked once you hit 100/month. On Pro, Ultra, and Mega, overage billing kicks in automatically at the per-request rate shown in your plan.

Is there an SDK?

The API is a standard REST API — any HTTP library works. RapidAPI auto-generates code snippets for 30+ languages including Python, JavaScript, PHP, Ruby, Go, and more.

Does the API support webhooks / incoming messages?

Yes. POST to /v1/sessions/{session}/webhooks with a webhookUrl and an events array. The events field defaults to ["message"] if omitted. You can subscribe to 29 event types including message, message.any, message.reaction, session.status, presence.update, group.v2.join, call.received, and more. See the Webhooks section above for the full list.

Still have questions?

Contact Support

WhatsApp API Reference