Developer Documentation

WhatsApp API Reference

Complete reference for the WhatsApp Messaging REST API. Covers authentication, all endpoints, code examples in cURL, Python, and JavaScript, error handling, and rate limits.

Subscribe on RapidAPIView OpenAPI Spec

Getting Started

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

  1. 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. 2
    Create a Session
    Call POST /v1/sessions with a name for your session. A session represents one WhatsApp account.
  3. 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. 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.

HeaderValueRequired
x-rapidapi-keyYour RapidAPI keyYes
x-rapidapi-hostwhatsapp-messaging-bot.p.rapidapi.comYes
Content-Typeapplication/jsonFor 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.

MethodPathDescription
GET/v1/sessionsList all sessions
POST/v1/sessionsCreate a new session
GET/v1/sessions/{session}Get session details
DELETE/v1/sessions/{session}Delete a session
POST/v1/sessions/startStart a session
POST/v1/sessions/stopStop a session
GET/v1/{session}/auth/qrGet QR code image for authentication
GET/v1/{session}/auth/pairing-codeRequest pairing code (phone number auth)
POST/v1/sessions/logoutLog 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

Messages

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

MethodPathDescription
POST/v1/sendTextSend a text message
POST/v1/sendImageSend an image with optional caption
POST/v1/sendFileSend any file (PDF, DOCX, etc.)
POST/v1/sendVideoSend a video message
POST/v1/sendVoiceSend a voice note
POST/v1/sendLocationSend a location pin
POST/v1/sendContactVcardShare a contact card
POST/v1/sendPollSend a poll
POST/v1/replyReply to a message
POST/v1/sendSeenMark message as read
POST/v1/startTypingStart typing indicator
POST/v1/stopTypingStop 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": "Hello! 👋",
    "session": "default"
  }'

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

TypechatId ExampleNotes
Individual1234567890Phone number only — country code auto-detected
Group120363024802736123@g.usObtain from GET /v1/sessions/{session}/groups
Channel120363024802736123@s.whatsapp.netObtain from channel search endpoint

Groups

Create, manage, and configure WhatsApp Groups via API.

MethodPathDescription
GET/v1/sessions/{session}/groupsList all groups
POST/v1/sessions/{session}/groupsCreate 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}/leaveLeave a group
PUT/v1/sessions/{session}/groups/{groupId}/subjectUpdate group name
PUT/v1/sessions/{session}/groups/{groupId}/descriptionUpdate group description
POST/v1/sessions/{session}/groups/{groupId}/participants/addAdd participants
POST/v1/sessions/{session}/groups/{groupId}/participants/removeRemove participants
POST/v1/sessions/{session}/groups/{groupId}/admin/promotePromote to admin
POST/v1/sessions/{session}/groups/{groupId}/admin/demoteDemote 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).

MethodPathDescription
GET/v1/sessions/{session}/channelsList subscribed channels
POST/v1/sessions/{session}/channelsCreate 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/previewGet channel preview messages

Contacts

Check WhatsApp registration status.

MethodPathDescription
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.

MethodPathDescription
POST/v1/sessions/{session}/presenceSet session presence (online/offline/typing/recording/paused)
GET/v1/sessions/{session}/presenceGet all chats presence
POST/v1/startTypingStart typing indicator in a chat
POST/v1/stopTypingStop typing indicator in a chat
POST/v1/sendSeenMark 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 CodeMeaningRecommendation
400Bad RequestFix request body / query params
401UnauthorizedCheck your x-rapidapi-key
404Not FoundVerify session name / resource ID
409ConflictSession name already exists — use a different name
429Too Many RequestsImplement exponential backoff; upgrade plan
500Internal Server ErrorRetry with backoff; contact support if persistent

Rate Limits

Limits apply per API key per plan.

PlanRequests / MonthReq / SecondSessions
Basic (Free)100101
Pro1,000103
Ultra10,0002010
Mega50,00025Unlimited
⚠ī¸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.jsonView 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?

Webhook support (incoming messages) is available on Pro and above plans. Contact support for configuration details.

Still have questions?

Contact Support