Skip to content
PowerAPI Whatsapp
Start free

Developers

PowerAPI Whatsapp API

A REST API to connect WhatsApp numbers, send messages and automate conversations. All requests and responses are JSON.

Base URL https://powerapiwa.com/api/v1

Authentication

Every request needs your API key from Settings → API key, sent in the x-api-key header (or Authorization: Bearer <key>). An instance is one connected WhatsApp number; its instance_id is shown on the number's page.

curl https://powerapiwa.com/api/v1/me \
  -H "x-api-key: YOUR_API_KEY"

Errors & limits

Errors return {"success": false, "error": "..."} with a meaningful status code.

StatusMeaning
401Missing or invalid API key
402Plan expired
403Feature not included in your plan / instance limit reached
404Instance or endpoint not found
422Invalid message payload
429Daily message limit reached or more than 300 requests/minute
502WhatsApp session error (e.g. not connected)

Instances

GET /instances

List instances

Returns all WhatsApp numbers on your account with their status (created, starting, qr, authenticated, connected, disconnected, stopped).

POST /instances

Create an instance

Creates an instance and starts its session. Body: {"name": "Support line"}. Then fetch the QR code or request a pairing code.

GET /instances/:instance_id

Get instance status

Returns live status, phone number and push name.

GET /instances/:instance_id/qr

Get QR code

Returns {"qr": "2@..."} — render it with any QR library, or use /qr.png for an image.

POST /instances/:instance_id/pairing-code

Request a pairing code

Body {"phone": "919876543210"}. Enter the returned code in WhatsApp → Linked devices → Link with phone number.

POST /instances/:instance_id/start

Start / restart / logout

Also available: /restart and /logout. DELETE /instances/:instance_id removes the instance.

Send messages

POST /instances/:instance_id/send

Send a message

to is a phone number with country code (10 digit numbers get the default country code) or a chat id such as 1203630…@g.us for groups. type is one of: text, media_url, media, location, poll, contact.

Text

{"to": "919876543210", "type": "text",
 "message": "Hello 👋"}

Media from URL

{"to": "919876543210", "type": "media_url",
 "url": "https://example.com/invoice.pdf",
 "caption": "Your invoice"}

Media (base64)

{"to": "919876543210", "type": "media",
 "mimetype": "image/png", "data": "iVBORw0KG…",
 "filename": "photo.png", "caption": "Look!"}

Location

{"to": "919876543210", "type": "location",
 "latitude": 12.9716, "longitude": 77.5946,
 "description": "Our store"}

Poll

{"to": "919876543210", "type": "poll",
 "poll_name": "Pick a slot",
 "poll_options": ["10 AM", "2 PM", "5 PM"],
 "allow_multiple": false}

Contact card

{"to": "919876543210", "type": "contact",
 "contact": "919812345678"}

Response

{"success": true, "message": {"id": "66f…", "status": "sent",
  "wa_message_id": "[email protected]_3EB0…", "chat_id": "[email protected]", …}}
POST /instances/:instance_id/check-number

Check if a number is on WhatsApp

{"number": "919876543210"}  →  {"success": true, "registered": true}

Message status

GET /messages

List messages

Query: instance_id, direction (in|out), page, limit (max 100).

GET /messages/:id

Get one message

Look up by our id or by wa_message_id. Status moves sent → delivered → read as receipts arrive.

Webhooks

Set a webhook URL per instance in the dashboard or via PUT /instances/:instance_id/webhook with {"url": "https://…", "events": ["message", "message_ack"]}. We POST:

{
  "event": "message",
  "instance_id": "pw4f2a9c…",
  "timestamp": 1767225600,
  "data": { "message": { "from": "[email protected]", "body": "Hi", "type": "chat", … } }
}

Verify the X-PowerAPI-Signature header — an HMAC-SHA256 of the raw body using the instance's webhook secret:

# Python
import hmac, hashlib
expected = hmac.new(secret.encode(), request.get_data(), hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, request.headers["X-PowerAPI-Signature"])

WhatsApp endpoints

Every WhatsApp Web capability is available through the passthrough route — the request body is forwarded unchanged. Sending endpoints count towards your daily limit.

{METHOD} https://powerapiwa.com/api/v1/instances/:instance_id/wa/{category}/{action}

Client

GET /wa/client/getClassInfo

Get current connection information

POST /wa/client/acceptInvite

Accept an invitation to join a group

{
  "inviteCode": ""
}
POST /wa/client/archiveChat

Archive the chat

{
  "chatId": ""
}
POST /wa/client/createGroup

Create a new group

{
  "title": "Group name",
  "participants": [],
  "options": {}
}
POST /wa/client/getBlockedContacts

Get all blocked contacts by host account

POST /wa/client/getChatById

Get the chat

{
  "chatId": ""
}
POST /wa/client/getChatLabels

Get all labels assigned to the chat

{
  "chatId": ""
}
GET /wa/client/getChats

Get all current chats — Retrieve all chats for the given session ID.

POST /wa/client/getChats

Get all current chats with optional search parameters — Retrieve all chats for the given session ID with optional search parameters.

{
  "searchOptions": {
    "since": 1746618541,
    "unread": true
  }
}
POST /wa/client/getChatsByLabelId

Get all chats for a specific label

{
  "labelId": ""
}
POST /wa/client/getCommonGroups

Get the contact's common groups — Get the contact's common groups with you. Returns empty array if you don't have any common group.

{
  "contactId": ""
}
POST /wa/client/getContactById

Get the contact

{
  "contactId": ""
}
GET /wa/client/getContacts

Get all current contacts

POST /wa/client/getInviteInfo

Return invite information — Return an object with information about the invite code

{
  "displayName": ""
}
POST /wa/client/getLabelById

Get the label

{
  "labelId": ""
}
POST /wa/client/getLabels

Get all current labels

POST /wa/client/addOrRemoveLabels

Change labels in chats

{
  "labelIds": [],
  "chatIds": []
}
POST /wa/client/getNumberId

Get the registered WhatsApp ID for a number — Return null if the number is not registered on WhatsApp

{
  "number": "6281288888888"
}
POST /wa/client/isRegisteredUser

Check if a given ID is registered in WhatsApp

{
  "number": "6281288888888"
}
POST /wa/client/getProfilePicUrl

Return the contact ID's profile picture URL

{
  "contactId": "[email protected]"
}
GET /wa/client/getState

Get the current connection state for the client

POST /wa/client/markChatUnread

Mark the chat as unread

{
  "chatId": ""
}
POST /wa/client/muteChat

Mute the chat — Mute this chat forever, unless a date is specified

{
  "chatId": "",
  "unmuteDate": "1733489397"
}
POST /wa/client/pinChat

Pin the chat

{
  "chatId": "[email protected]"
}
POST /wa/client/searchMessages

Search for messages

{
  "query": "",
  "options": {
    "limit": 10,
    "page": 1
  }
}
POST /wa/client/sendMessage counts as message

Send a message to a specific chatId

{
  "chatId": "[email protected]",
  "contentType": "string",
  "content": "Hello World!"
}
POST /wa/client/sendPresenceAvailable

Mark the client as online

POST /wa/client/sendPresenceUnavailable

Mark the client as unavailable

POST /wa/client/sendSeen

Mark the chat as seen

{
  "chatId": "[email protected]"
}
POST /wa/client/setDisplayName

Set the current user — This is the name shown to WhatsApp users that have not added you as a contact beside your number in groups and in your profile.

{
  "pictureMimetype": "image/png",
  "pictureData": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX +/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII="
}
POST /wa/client/setProfilePicture

Set the current user\'s profile picture

{
  "pictureMimetype": "image/png",
  "pictureData": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX +/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII="
}
POST /wa/client/setStatus

Set the current user's status message

{
  "status": "I'm running WWebJS Api"
}
POST /wa/client/unarchiveChat

Changes archive state of the chat

{
  "chatId": "[email protected]"
}
POST /wa/client/unmuteChat

Unmute the chat

{
  "chatId": "[email protected]"
}
POST /wa/client/unpinChat

Unpin the chat

{
  "chatId": "[email protected]"
}
GET /wa/client/getWWebVersion

Return the version of WhatsApp Web currently being run

DELETE /wa/client/deleteProfilePicture

Delete the current user's profile picture

POST /wa/client/setAutoDownloadAudio

Set auto load download audio flag

{
  "flag": true
}
POST /wa/client/setAutoDownloadDocuments

Set auto load download documents flag

{
  "flag": true
}
POST /wa/client/setAutoDownloadPhotos

Set auto load download photos flag

{
  "flag": true
}
POST /wa/client/setAutoDownloadVideos

Set auto load download videos flag

{
  "flag": true
}
POST /wa/client/syncHistory

Sync chat history

{
  "chatId": "[email protected]"
}
POST /wa/client/getContactDeviceCount

Get user device count — Each WaWeb Connection counts as one device, and the phone (if exists) counts as one device. So for a non-enterprise user with one WaWeb connection it should return "2"

{
  "userId": ""
}
POST /wa/client/getCountryCode

Get the country code

{
  "number": ""
}
POST /wa/client/getFormattedNumber

Get the formatted number

{
  "number": ""
}
POST /wa/client/openChatWindow

Open the chat window

{
  "chatId": "[email protected]"
}
POST /wa/client/openChatWindowAt

Open the chat window to the position of the message

{
  "messageId": "[email protected]_3A40CB10BC3680B1EE"
}
POST /wa/client/resetState

Force reset of connection state for the client

POST /wa/client/setBackgroundSync

Change the background synchronization setting — NOTE: This action will take effect after you restart the client

{
  "flag": true
}
POST /wa/client/getContactLidAndPhone

Get contact lid and phone — Retrieve the contact lid and phone number for a specific chat

{
  "userIds": [
    "[email protected]"
  ]
}
POST /wa/client/getChannelByInviteCode

Get channel by invite code

{
  "inviteCode": ""
}
GET /wa/client/getChannels

Get channels from the client — Retrieve a list of channels from the client

POST /wa/client/createChannel

Create a new channel

{
  "title": "My New Channel",
  "options": {
    "description": "This is my new channel"
  }
}
POST /wa/client/subscribeToChannel

Subscribe to a channel

{
  "channelId": "XXXXXXXXXX@newsletter"
}
POST /wa/client/unsubscribeFromChannel

Unsubscribe from channel

{
  "channelId": "XXXXXXXXXX@newsletter",
  "options": {
    "deleteLocalModels": true
  }
}
POST /wa/client/searchChannels

Search channels

{
  "searchOptions": {
    "searchText": "",
    "countryCodes": [
      "US",
      "CA"
    ],
    "skipSubscribedNewsletters": true,
    "view": 0,
    "limit": 10
  }
}

Chat

POST /wa/chat/getClassInfo

Get the chat

{
  "chatId": "[email protected]"
}
POST /wa/chat/clearMessages

Clear all messages from the chat

{
  "chatId": "[email protected]"
}
POST /wa/chat/clearState

Stop typing or recording in chat immediately

{
  "chatId": "[email protected]"
}
POST /wa/chat/delete

Delete the chat

{
  "chatId": "[email protected]"
}
POST /wa/chat/fetchMessages

Load chat messages — Messages sorted from earliest to latest

{
  "chatId": "[email protected]",
  "searchOptions": {
    "limit": 10,
    "fromMe": true
  }
}
POST /wa/chat/getContact

Get the contact

{
  "chatId": "[email protected]"
}
POST /wa/chat/sendStateRecording

Simulate recording audio — Simulate recording audio in chat. This will last for 25 seconds

{
  "chatId": "[email protected]"
}
POST /wa/chat/sendStateTyping

Simulate typing in chat — Simulate typing in chat. This will last for 25 seconds.

{
  "chatId": "[email protected]"
}
POST /wa/chat/sendSeen

Set the message as seen

{
  "chatId": "[email protected]"
}
POST /wa/chat/markUnread

Mark this chat as unread

{
  "chatId": "[email protected]"
}
POST /wa/chat/syncHistory

Sync chat history

{
  "chatId": "[email protected]"
}
POST /wa/chat/getLabels

Return all labels — Return array of all labels assigned to this chat

{
  "chatId": "[email protected]"
}
POST /wa/chat/changeLabels

Add or remove labels

{
  "chatId": "[email protected]",
  "labelIds": [
    0,
    1
  ]
}

Group Chat

POST /wa/groupChat/getClassInfo

Get the group

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/addParticipants

Add the participants — Add a list of participants by ID to the group

{
  "chatId": "[email protected]",
  "participantIds": [
    "[email protected]"
  ],
  "options": {
    "sleep": [
      250,
      500
    ],
    "comment": ""
  }
}
POST /wa/groupChat/demoteParticipants

Demote the participants — Demote participants by ID to regular users

{
  "chatId": "[email protected]",
  "participantIds": [
    "[email protected]"
  ]
}
POST /wa/groupChat/getInviteCode

Get the invite code — Get the invite code for a specific group

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/leave

Leave the group

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/promoteParticipants

Promote the participants — Promote participants by ID to admins

{
  "chatId": "[email protected]",
  "participantIds": [
    "[email protected]"
  ]
}
POST /wa/groupChat/removeParticipants

Remove the participants — Remove a list of participants by ID to the group

{
  "chatId": "[email protected]",
  "participantIds": [
    "[email protected]"
  ]
}
POST /wa/groupChat/revokeInvite

Invalidate the invite code — Invalidate the current group invite code and generates a new one

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/setDescription

Update the group description

{
  "chatId": "[email protected]",
  "description": ""
}
POST /wa/groupChat/setInfoAdminsOnly

Update the info group settings

{
  "chatId": "[email protected]",
  "adminsOnly": true
}
POST /wa/groupChat/setMessagesAdminsOnly

Update the message group settings

{
  "chatId": "[email protected]",
  "adminsOnly": true
}
POST /wa/groupChat/setSubject

Update the group subject

{
  "chatId": "[email protected]",
  "subject": ""
}
POST /wa/groupChat/setPicture

Set the group picture

{
  "chatId": "[email protected]",
  "pictureMimeType": "",
  "pictureData": ""
}
POST /wa/groupChat/deletePicture

Delete the group picture

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/getGroupMembershipRequests

Get the membership requests

{
  "chatId": "[email protected]"
}
POST /wa/groupChat/approveGroupMembershipRequests

Approve membership request

{
  "chatId": "[email protected]",
  "options": {
    "requesterIds": [],
    "sleep": [
      250,
      500
    ]
  }
}
POST /wa/groupChat/rejectGroupMembershipRequests

Reject membership request

{
  "chatId": "[email protected]",
  "options": {
    "requesterIds": [],
    "sleep": [
      250,
      500
    ]
  }
}

Message

POST /wa/message/getClassInfo

Get message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/delete

Delete a message from the chat

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999",
  "everyone": true,
  "clearMedia": true
}
POST /wa/message/downloadMedia

Download attached message media

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/downloadMediaAsData

Download attached message media as binary data

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/forward counts as message

Delete a message from the chat

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999",
  "destinationChatId": "[email protected]"
}
POST /wa/message/getInfo

Get information about message delivery status — May return null if the message does not exist or is not sent by you.

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getMentions

Get the contacts mentioned

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getOrder

Get the order details

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getPayment

Get the payment details

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getQuotedMessage

Get the quoted message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/react

React with an emoji

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999",
  "reaction": "👍"
}
POST /wa/message/reply counts as message

Send a message as a reply

{
  "messageId": "3A80E857F9B44AF60C2C",
  "chatId": "[email protected]",
  "contentType": "string",
  "content": "Reply text!"
}
POST /wa/message/star

Star the message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/unstar

Unstar the message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getReactions

Get the reactions associated

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getGroupMentions

Get groups mentioned in this message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/edit

Edit the message

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999",
  "content": "",
  "options": {}
}
POST /wa/message/getContact

Get the contact

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}
POST /wa/message/getPollVotes

Get poll vote results for a message with a poll — May return null if the message does not exist or is not a poll.

{
  "chatId": "[email protected]",
  "messageId": "ABCDEF999999999"
}

Contact

POST /wa/contact/getClassInfo

Get the contact

{
  "contactId": "[email protected]"
}
POST /wa/contact/block

Block contact

{
  "contactId": "[email protected]"
}
POST /wa/contact/getAbout

Get the contact's current info — Get the Contact's current 'about' info. Returns null if you don't have permission to read their status.

{
  "contactId": "[email protected]"
}
POST /wa/contact/getChat

Get the chat — Get the chat that corresponds to the contact. Will return null when getting chat for currently logged in user.

{
  "contactId": "[email protected]"
}
POST /wa/contact/unblock

Unblock the contact — Unblock the contact from WhatsApp.

{
  "contactId": "[email protected]"
}
POST /wa/contact/getFormattedNumber

Get the formatted phone number — Returns the contact's formatted phone number, ([email protected]) => (+1 (234) 5678-901).

{
  "contactId": "[email protected]"
}
POST /wa/contact/getCountryCode

Get the country code — Returns the contact's country code, ([email protected]) => (1).

{
  "contactId": "[email protected]"
}
POST /wa/contact/getProfilePicUrl

Get the profile picture URL — Get the contact's profile picture URL, if privacy settings allow it.

{
  "contactId": "[email protected]"
}
POST /wa/contact/getCommonGroups

Get the contact's common groups — Get the contact's common groups with you. Returns empty array if you don't have any common group.

{
  "contactId": "[email protected]"
}

Channel

POST /wa/channel/getClassInfo

Get the channel

{
  "chatId": "XXXXXXXXXX@newsletter"
}
POST /wa/channel/sendMessage counts as message

Sends a message to this channel

{
  "chatId": "XXXXXXXXXX@newsletter",
  "contentType": "string",
  "content": "Hello World!"
}
POST /wa/channel/fetchMessages

Load channel messages — Messages sorted from earliest to latest

{
  "chatId": "XXXXXXXXXX@newsletter",
  "searchOptions": {
    "limit": 10,
    "fromMe": true
  }
}
POST /wa/channel/sendSeen

Send seen status to the channel

{
  "chatId": "XXXXXXXXXX@newsletter"
}
POST /wa/channel/mute

Mute the channel

{
  "chatId": "XXXXXXXXXX@newsletter"
}
POST /wa/channel/unmute

Unmute the channel

{
  "chatId": "XXXXXXXXXX@newsletter"
}
POST /wa/channel/acceptChannelAdminInvite

Accept channel admin invite

{
  "chatId": "XXXXXXXXXX@newsletter"
}
POST /wa/channel/sendChannelAdminInvite

Sends a channel admin invitation to a user

{
  "chatId": "XXXXXXXXXX@newsletter",
  "userId": "[email protected]",
  "options": {
    "comment": "Hello"
  }
}
POST /wa/channel/revokeChannelAdminInvite

Revokes a channel admin invitation sent to a user by a channel owner

{
  "chatId": "XXXXXXXXXX@newsletter",
  "userId": "[email protected]"
}
POST /wa/channel/transferChannelOwnership

Transfers a channel ownership to another user — Note: the user you are transferring the channel ownership to must be a channel admin

{
  "chatId": "XXXXXXXXXX@newsletter",
  "newOwnerId": "[email protected]",
  "options": {
    "shouldDismissSelfAsAdmin": false
  }
}
POST /wa/channel/demoteChannelAdmin

Demotes a channel admin to a regular subscriber

{
  "chatId": "XXXXXXXXXX@newsletter",
  "userId": "[email protected]"
}
POST /wa/channel/getSubscribers

Gets the subscribers of the channel (only those who are in your contact list)

{
  "chatId": "XXXXXXXXXX@newsletter",
  "limit": 100
}
POST /wa/channel/setProfilePicture

Update a channel profile picture

{
  "chatId": "XXXXXXXXXX@newsletter",
  "newProfilePictureUrl": "string"
}
POST /wa/channel/setDescription

Update a channel description

{
  "chatId": "XXXXXXXXXX@newsletter",
  "newDescription": "This is the updated channel description"
}
POST /wa/channel/setSubject

Set the subject of the channel

{
  "chatId": "XXXXXXXXXX@newsletter",
  "newSubject": "New Channel Subject"
}
POST /wa/channel/setReactionSetting

Updates available reactions to use in the channel — Valid values for passing to the method are: 0 for NONE reactions to be available 1 for BASIC reactions to be available: 👍, ❤️, 😂, 😮, 😢, 🙏 2 for ALL reactions to be available

{
  "chatId": "XXXXXXXXXX@newsletter",
  "reactionCode": 1
}
POST /wa/channel/deleteChannel

Delete a channel you created

{
  "chatId": "XXXXXXXXXX@newsletter"
}