WhatsApp API Documentation

Introduction

This API allows you to interact with WhatsApp programmatically to send messages, media files, locations, polls, reactions, and perform other messaging operations.

The API uses a RESTful architecture with JSON request/response formats and supports all major WhatsApp features. All endpoints require authentication via an API key passed in the request headers.

Note: This API requires an active WhatsApp session and proper API key authentication. All URLs are dynamically generated based on your current window location.

Authentication

All API requests must include an X-API-Key header with a valid API key associated with an active WhatsApp session.

// Example request headersheaders: {
            'X-API-Key':
            'your-api-key-here',
            'Content-Type':
            'application/json'
            }
            
              
            

Without a valid API key, requests will return a 401 Unauthorized error. You can obtain an API key by registering your application with the WhatsApp Business API.

Send Text Message

POST /api/whatsapp/send/text

Send a text message to a phone number or WhatsApp group.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication
Content-Type	String	Required	Must be `application/json`

Request Body (JSON)

Parameter	Type	Required	Description
number	String	Optional*	Recipient phone number (with country code, without '+' or spaces)
group	String	Optional*	Group ID for sending to a WhatsApp group
message	String	Required	Text message content

* Either number or group must be provided

Example Request

// JavaScript Fetch API exampleconst response =
              awaitfetch('', { method: 'POST', headers: {
              'X-API-Key':
              'your-api-key-here',
              'Content-Type':
              'application/json' }, body:
              JSON.stringify({
              number:
              '1234567890',
              message:
              'Hello from WhatsApp API!'
              }) });
              
                
              

Example Response

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

Send Photo

POST /api/whatsapp/send/photo

Send one or multiple images (up to 10) to a phone number or WhatsApp group.

Request Format

This endpoint uses multipart/form-data for file uploads.

Parameters

Parameter	Type	Required	Description
photos	File[]	Required	Image files (max 10, must be image/*)
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
caption	String	Optional	Caption for the image(s)
viewOnce	Boolean	Optional	If true, sends as view-once media (default: false)

* Either number or group must be provided

Example Request

// JavaScript fetch with FormDataconst formData =
              new FormData(); formData.append('photos', photoFile); formData.append('number',
              '1234567890'); formData.append('caption',
              'Check out this image!');
              formData.append('viewOnce', 'false');

              const response =
              awaitfetch('', { method: 'POST', headers: {
              'X-API-Key':
              'your-api-key-here'
              }, body: formData });
              
                
              

Example Response

              {
              "success": true,
              "sent": 3,
              "messages": [
              "Message ID 1",
              "Message ID 2",
              "Message ID 3"
              ] }
            

Send Video

POST /api/whatsapp/send/video

Send one or multiple videos (up to 5) to a phone number or WhatsApp group.

Request Format

This endpoint uses multipart/form-data for file uploads.

Parameters

Parameter	Type	Required	Description
videos	File[]	Required	Video files (max 5, must be video/*)
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
caption	String	Optional	Caption for the video(s)
gif	Boolean	Optional	If true, sends as GIF (default: false)
viewOnce	Boolean	Optional	If true, sends as view-once media (default: false)

Example Request

// Send video as GIFconst formData =
              new FormData(); formData.append('videos', videoFile); formData.append('number',
              '1234567890'); formData.append('gif',
              'true'); formData.append('caption',
              'Funny GIF!');

              const response =
              awaitfetch('', { method: 'POST', headers: {
              'X-API-Key':
              'your-api-key-here'
              }, body: formData });
              
                
              

Send Audio

POST /api/whatsapp/send/audio

Send audio files or voice notes to a phone number or WhatsApp group.

Request Format

This endpoint uses multipart/form-data for file uploads.

Parameters

Parameter	Type	Required	Description
audios	File[]	Required	Audio files (max 5, must be audio/*)
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
voice	Boolean	Optional	If true, sends as WhatsApp voice note (default: false)

Example Request

// Send as voice noteconst formData =
              new FormData(); formData.append('audios', audioFile); formData.append('number',
              '1234567890'); formData.append('voice',
              'true');

              const response =
              awaitfetch('', { method: 'POST', headers: {
              'X-API-Key':
              'your-api-key-here'
              }, body: formData });
              
                
              

Send File

POST /api/whatsapp/send/file

Send documents and files to a phone number or WhatsApp group.

Request Format

This endpoint uses multipart/form-data for file uploads.

Parameters

Parameter	Type	Required	Description
files	File[]	Required	Files to send (max 5, any type)
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
caption	String	Optional	Caption for the file(s)

Example Request

// Send PDF documentconst formData =
              new FormData(); formData.append('files', pdfFile); formData.append('number',
              '1234567890'); formData.append('caption',
              'Important document');

              const response =
              awaitfetch('', { method: 'POST', headers: {
              'X-API-Key':
              'your-api-key-here'
              }, body: formData });
              
                
              

Send Location

POST /api/whatsapp/send/location

Send a location with latitude and longitude coordinates to a phone number or WhatsApp group.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication
Content-Type	String	Required	Must be `application/json`

Request Body (JSON)

Parameter	Type	Required	Description
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
location.degreesLatitude	Number	Required	Latitude coordinate (e.g., 40.7128)
location.degreesLongitude	Number	Required	Longitude coordinate (e.g., -74.0060)

* Either number or group must be provided

Example Request

// Sending location coordinates for New York Cityconst response =
              awaitfetch('', { method: 'POST', headers: {
              'Content-Type':
              'application/json',
              'X-API-Key':
              'your-api-key-here' }, body:
              JSON.stringify({
              number:
              '1234567890',
              location: {
              degreesLatitude:
              40.7128,
              degreesLongitude:
              -74.0060
              } }) });
              
                
              

Send Poll

POST /api/whatsapp/send/poll

Create and send a poll to a phone number or WhatsApp group.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication
Content-Type	String	Required	Must be `application/json`

Request Body (JSON)

Parameter	Type	Required	Description
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for sending to a group
name	String	Required	Poll question/title
values	Array	Required	Array of poll options (minimum 2)
selectableCount	Number	Optional	Number of options users can select (default: 1)
toAnnouncementGroup	Boolean	Optional	For announcement groups (default: false)

Example Request

// Create a pollconst response =
              awaitfetch('', { method: 'POST', headers: {
              'Content-Type':
              'application/json',
              'X-API-Key':
              'your-api-key-here' }, body:
              JSON.stringify({
              group:
              'group-id-here',
              name:
              'What is your favorite programming language?', values: ['JavaScript', 'Python',
              'Java',
              'C++'],
              selectableCount:
              1
              }) });
              
                
              

Add Reaction NEW

POST /api/whatsapp/message/react

Add an emoji reaction to a specific message.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication
Content-Type	String	Required	Must be `application/json`

Request Body (JSON)

Parameter	Type	Required	Description
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for reacting in a group
messageKey	String	Required	The message key/ID to react to
emoji	String	Optional	Emoji to add (empty string removes reaction)

Example Request

// Add a reaction to a messageconst response =
              awaitfetch('', { method: 'POST', headers: {
              'Content-Type':
              'application/json',
              'X-API-Key':
              'your-api-key-here' }, body:
              JSON.stringify({
              number:
              '1234567890',
              messageKey:
              'message-id-here',
              emoji: '👍'
              }) });
              
                
              

Delete Message

POST /api/whatsapp/message/delete

Delete a specific message for everyone.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication
Content-Type	String	Required	Must be `application/json`

Request Body (JSON)

Parameter	Type	Required	Description
number	String	Optional*	Recipient phone number
group	String	Optional*	Group ID for deleting in a group
messageKey	String	Required	The message key/ID to delete

Example Request

// Delete a messageconst response =
              awaitfetch('', { method: 'POST', headers: {
              'Content-Type':
              'application/json',
              'X-API-Key':
              'your-api-key-here' }, body:
              JSON.stringify({
              group:
              'group-id-here',
              messageKey:
              'message-id-here'
              }) });
              
                
              

Get Groups

GET /api/whatsapp/get/groups

Retrieve a list of all WhatsApp groups for the authenticated session.

Request Headers

Header	Type	Required	Description
X-API-Key	String	Required	Your API key for authentication

Example Request

// Get all WhatsApp groupsconst response =
              awaitfetch('', { method: 'GET', headers: {
              'X-API-Key':
              'your-api-key-here'
              } });

              const data =
              await response.json(); console.log(data.groups);
              
                
              

Example Response

              {
              "groups": [ {
              "id":
              "group-id-1",
              "name":
              "Family Group",
              "participants":
              15
              }, {
              "id":
              "group-id-2",
              "name":
              "Work Team",
              "participants":
              8
              } ] }
            

Error Handling

The API returns appropriate HTTP status codes and error messages to help you debug issues.

Common Error Codes

Status Code	Description	Resolution
400	Bad Request	Check required parameters and request format
401	Unauthorized	Invalid or missing X-API-Key header
404	Not Found	Session not found with provided API key
413	Payload Too Large	File size exceeds limits
415	Unsupported Media Type	Invalid file type for the endpoint
429	Too Many Requests	Rate limit exceeded, add delays between requests
500	Internal Server Error	Server error, check error message for details

Error Response Format

            {
            "error":
            "Error description here"
            }
          

Code Examples

Here are some complete examples using the API with dynamic URLs:

Full JavaScript Client

// Complete WhatsApp API Client Exampleclass WhatsAppAPI {
            constructor(apiKey, baseUrl =
            window.location.origin) {
            this.apiKey = apiKey;
            this.baseUrl = baseUrl; }

            asyncsendText(number, message, group =
            null) {
            const payload = group ? { group, message }
            : { number, message };

            const response =
            awaitfetch(`${this.baseUrl}/api/whatsapp/send/text`, { method: 'POST', headers: {
            'X-API-Key':
            this.apiKey,
            'Content-Type':
            'application/json' }, body:
            JSON.stringify(payload) });
            returnawait response.json(); }

            asyncsendPhoto(jid, photoFile, caption =
            '', viewOnce =
            false, isGroup =
            false) {
            const formData =
            new FormData(); formData.append('photos', photoFile); formData.append(isGroup ? 'group' :
            'number', jid); formData.append('caption', caption); formData.append('viewOnce', viewOnce.toString());

            const response =
            awaitfetch(`${this.baseUrl}/api/whatsapp/send/photo`, { method: 'POST', headers: {
            'X-API-Key':
            this.apiKey }, body: formData });
            returnawait response.json(); }

            asyncsendReaction(jid, messageKey, emoji =
            '', isGroup =
            false) {
            const payload = { [isGroup ?
            'group' :
            'number']: jid, messageKey, emoji };

            const response =
            awaitfetch(`${this.baseUrl}/api/whatsapp/message/react`, { method: 'POST', headers: {
            'X-API-Key':
            this.apiKey,
            'Content-Type':
            'application/json' }, body:
            JSON.stringify(payload) });
            returnawait response.json(); }

            asyncgetGroups() {
            const response =
            awaitfetch(`${this.baseUrl}/api/whatsapp/get/groups`, { headers: { 'X-API-Key':
            this.apiKey } });
            returnawait response.json(); } }

            // Usage example
            (async () => {
            const whatsapp =
            newWhatsAppAPI('your-api-key-here');

            // Send a text messageawait whatsapp.sendText('1234567890',
            'Hello from API!');

            // Get all groupsconst groups =
            await whatsapp.getGroups(); console.log('Groups:', groups); })();
            
              
            

Python Example

# Python requests exampleimport requests
            import json API_KEY =
            'your-api-key-here' BASE_URL =
            ''# Send text messagedefsend_text(number, message): url =
            f"{BASE_URL}/api/whatsapp/send/text"
            headers = {
            'X-API-Key': API_KEY,
            'Content-Type':
            'application/json'
            } payload = {
            'number': number,
            'message': message } response =
            requests.post(url, headers=headers,
            json=payload) return response.json()

            # Send photodefsend_photo(number, photo_path,
            caption=''): url =
            f"{BASE_URL}/api/whatsapp/send/photo"
            headers = {'X-API-Key': API_KEY}

            withopen(photo_path,
            'rb') as f:
            files = {'photos': f} data = {'number': number, 'caption': caption} response
            = requests.post(url, headers=headers,
            files=files, data=data)

            return response.json()

            # Get groupsdefget_groups(): url =
            f"{BASE_URL}/api/whatsapp/get/groups"
            headers = {'X-API-Key': API_KEY}
            response = requests.get(url,
            headers=headers) return response.json()
            
              
            

Base URL

Text Message

Photo

Video

Audio

File

Location

Poll

Reactions

Introduction

Authentication

Send Text Message

Request Headers

Request Body (JSON)

Example Request

Example Response

Send Photo

Request Format

Parameters

Example Request

Example Response

Send Video

Request Format

Parameters

Example Request

Send Audio

Request Format

Parameters

Example Request

Send File

Request Format

Parameters

Example Request

Send Location

Request Headers

Request Body (JSON)

Example Request

Send Poll

Request Headers

Request Body (JSON)

Example Request

Add Reaction NEW

Request Headers

Request Body (JSON)

Example Request

Delete Message

Request Headers

Request Body (JSON)

Example Request

Get Groups

Request Headers

Example Request

Example Response

Error Handling

Common Error Codes

Error Response Format

Code Examples

Full JavaScript Client

Python Example