API Reference

The WSAPI provides a RESTful HTTP API for sending WhatsApp messages, managing contacts, groups, chats, and more. All requests are authenticated and use JSON payloads.

Base URL

https://api.wsapi.chat

All API requests use HTTPS encryption.

Authentication

Every request requires two headers:

Header	Description
`X-Api-Key`	Your account API key
`X-Instance-Id`	The target WhatsApp instance identifier

curl -X GET https://api.wsapi.chat/chats \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID"

Keep your API key secret. Rotate it immediately if you suspect exposure.

Request format

Method: Use the appropriate HTTP method (GET, POST, PUT, DELETE)
Headers: Include authentication headers and Content-Type: application/json
Body: JSON-formatted request body for POST and PUT requests

Example: Send a text message

curl -X POST https://api.wsapi.chat/messages/text \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Instance-Id: YOUR_INSTANCE_ID" \
  -d '{
    "to": "1234567890@s.whatsapp.net",
    "message": "Hello from WSAPI!"
  }'

Response codes

Code	Meaning
`200`	Success — response body contains the result
`201`	Created — resource was created successfully
`202`	Accepted — request accepted for asynchronous processing
`204`	No Content — request succeeded with no response body
`400`	Bad Request — invalid parameters or payload
`401`	Unauthorized — invalid or missing API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource doesn’t exist
`409`	Device Not Paired — instance is not connected to WhatsApp
`429`	Rate Limited — too many requests
`500`	Server Error — something went wrong on our end

Phone number format

WhatsApp uses the JID (Jabber ID) format for phone numbers:

Individual chats: {countryCode}{number}@s.whatsapp.net (e.g., 1234567890@s.whatsapp.net)
Group chats: {groupId}@g.us

Do not include the + prefix in phone numbers. Use the raw digits with country code.

Resources

The API is organized into the following resource groups:

Messages

Send text, media, documents, stickers, locations, contacts, and reactions

Chats

List, archive, pin, mute, and manage chat settings

Contacts

List, create, update contacts and retrieve profile pictures

Groups

Create groups, manage participants, update settings and invite links

Session

Get QR codes, pairing codes, connection status, and logout

Instance

Manage instance settings, restart, and update configuration

Account

Get and update your WhatsApp profile name, picture, status, and presence

Media

Download and manage media files

Newsletters

Newsletter and channel management

Status

Status and stories posting

Calls

Call management

Communities

Community and sub-group management

Tools

OpenAPI Spec — available for download and import into API clients
Interactive Playground — test endpoints directly from the API Reference pages

Browse the full endpoint list in the sidebar, or use the interactive playground to make test requests.

Overview

Endpoints

Base URL

Authentication

Request format

Example: Send a text message

Response codes

Phone number format

Resources

Messages

Chats

Contacts

Groups

Session

Instance

Account

Media

Newsletters

Status

Calls

Communities

Tools

​Base URL

​Authentication

​Request format

​Example: Send a text message

​Response codes

​Phone number format

​Resources

Messages

Chats

Contacts

Groups

Session

Instance

Account

Media

Newsletters

Status

Calls

Communities

​Tools

Base URL

Authentication

Request format

Example: Send a text message

Response codes

Phone number format

Resources

Tools