API Endpoint: api.wazaap.co
Request parameters are GET.
Responses are in JSON format. (except for status code 500 and 503)

A status is returned on all requests, in case it's ERROR, there's a code returned.
General errors: INVALID_API_KEY, NO_SUBSCRIPTION, INVALID_PHONE_NUMBER, SESSION_NOT_FOUND, INTERNAL_ERROR
We can help you integrate for free! Contact us for details.
Download PHP example
Download Python example

Create Session

/create-session
Creates WhatsApp session.

Created sessions.

Use /session/ping method below to keep sessions alive. Sessions time out after 600 seconds.

SCAN_QR will be returned for the first authentication.
LOGGED_IN will be returned if logged in using previous cookies.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number with country code 18501234567

Responses

{
  "status": "LOGGED_IN"
}
Logged in successfully using existing cookies.

{
  "status": "SCAN_QR",
  "qrCode": "QR_CODE_TEXT",
  "qrCodeUrl": "QR_CODE_IMAGE_URL"
}
Scan QR code to continue. qrCode value is not base64, but text.
You can also use generated QR code image from qrCodeUrl
Use /is-logged-in method below to get latest QR code data. It's updated every 20 seconds.

Errors

DEVICE_LIMIT_EXCEEDED Your subscription's maximum device limit is exceeded.

SESSION_RUNNING A session with this number is already running.

INTERNAL_ERROR The most common cause for that error is, connection to device is timing out. Try calling delete-cookies and try again.

List Sessions

/list-sessions
Lists running sessions.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..

Responses

{
  "status": "SUCCESS",
  "sessions": [
    {
      "phone": "18501234567",
      "loggedIn": true
    },
    {
      "phone": "18501234567",
      "loggedIn": false,
      "qrCode": "QR_CODE_TEXT",
      "qrCodeUrl": "QR_CODE_IMAGE_URL"
    }
  ]
}
Returns list of sessions. Latest QR code data is retrieved if loggedIn is false.

Hint: Use /ping to see if a session is running. If status is success, it means it's running.

Delete Cookies

/delete-cookies
Deletes authentication cookies from server. You must scan QR code again when creating new session. Also, you must call this method after closing WhatsApp Web session from your phone else create-session will return INTERNAL_ERROR

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS"
}

Errors

COOKIES_NOT_FOUND Authentication cookies don't exist. SESSION_RUNNING This session is running. Please close it first.

Get Login Status

/session/is-logged-in
Returns login status.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS",
  "loggedIn": false,
  "qrCode": "QR_CODE_TEXT",
  "qrCodeUrl": "QR_CODE_IMAGE_URL"
}

Load Messages

/session/load-messages
Returns last 50 messages of a given chat.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
recipient Required Group ID or phone number 18501234568

Responses

{
	"status": "SUCCESS",
	"messages": [{
		"id": "ABCDEF0123456780",
		"chat": "18501234567-1603741350",
		"timestamp": 1603741350,
		"message": "hello"
		"fromMe": true,
		"replied": null,
		"media": false,
		"participant": "18501234567",
	},
	{
		"id": "ABCDEF0123456789",
		"chat": "18501234567-1603741350",
		"timestamp": 1603741355,
		"message": "img caption"
		"fromMe": false,
		"replied": {
			"id": "ABCDEF0123456780",
			"message": "hello",
			"media": false,
			"sender": "18501234567"
		},
		"media": true,
		"mediaURL": "<encrypted media url>",
		"mediaKey": "<encryption key>",
		"participant": "18501234567",
	}]
}
Decryption example: whatsapp-media-decrypt

Get Details

/session/get-details
Returns device and chat information.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS",
  "user": {
      "jid": "[email protected]",
      "name": "Wazaap Bot",
      "phone": {
        "wa_version": "2.20.197.17",
        "mcc": "123",
        "mnc": "001",
        "os_version": "10",
        "device_manufacturer": "Samsung",
        "device_model": "herolte",
        "os_build_number": "os_build_number"
      },
      "imgUrl": "Profile picture URL"
  },
  "chats": [
    {
      "jid": "18501234568",
      "name": "test user 2",
      "isGroup": false,
      "unreadCount": 17
    },
    {
      "jid": "18501234567-1603741350",
      "name": "test group 1",
      "isGroup": true,
      "unreadCount": 0
    }
  ]
}
Chats are ordered by latest on top.

Errors

NOT_LOGGED_IN Session isn't logged in yet.

Send Message

/session/send
Sends a text, image or location message.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
recipient Required Phone number of recipient 18501234568
noresp Do not wait for server response [exists]
nocompose Do not set status to "typing" to save time [exists]
text Text or image caption hello
lat Latitude of location 34.123456
long Longitude of location 34.123456
type when POST jpg,png,pdf png
POST Request Body Base64 encoded file requests.post(..,
data=base64.b64encode(fileBytes))

Responses

{
  "status": "SUCCESS"
}

Errors

INVALID_MESSAGE_TYPE Invalid arguments. INVALID_LOCATION Location couldn't be parsed. INVALID_RECIPIENT Recipient is invalid.
This method doesn't totally validate the recipient. If invalid recipient values are passed, WhatsApp application might crash, requiring a restart.
Passing wrong type might crash the session.

Mark as Read

/session/mark-read
Mark a chat as read.
Chats are already marked as read when sending a message to them.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
recipient Required ID of chat 18501234567

Responses

{
  "status": "SUCCESS"
}

Errors

INVALID_RECIPIENT Recipient is invalid.

Create Group

/session/create-group
Creates a WhatsApp group.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
title Required Group title test group
recipients Required Comma (,) seperated list of recipients 18501234568,18501234569

Responses

{
  "status": "SUCCESS",
  "jid": "18501234567-1603741350"
}

Errors

INVALID_RECIPIENT Recipient is invalid. Groups aren't allowed as recipients in this method
INVALID_TITLE Title length must be between 1-20.

Get Remote Details

/session/get-remote-details
Get information about a WhatsApp(?) number.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
recipient Required Target number 18501234568

Responses

{
  "status": "SUCCESS"
  "exists": true,
  "profile_picture": "Profile picture URL",
  "wp_status": "user status text"
}
{
  "status": "SUCCESS"
  "exists": false
}

Errors

INVALID_RECIPIENT Recipient is invalid. Groups aren't allowed as recipients in this method.

Change Profile Picture

/session/change-profile-pic
Change your profile picture.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
POST Request Body Required Base64 encoded file requests.post(..,
data=base64.b64encode(fileBytes))

Responses

{
  "status": "SUCCESS"
}

Errors

INVALID_MEDIA Invalid media.

Ping Session

/session/ping
Ping session in order to prevent timeout.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS"
}

Close Session

/session/close
Logouts from WhatsApp and closes session.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS"
}

Add Webhook

/session/add-webhook
Adds webhook for incoming messages.
You might want to put a secret and phone number in parameters like this:
https://example.com/receive.php?secret=123456&phone=18501234567

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
webhookid Required Unique webhook id hello_world
webhookurl Required Webhook URL https://example.com/webhook.php
messagefrom Sender number 18501234568
messagecontains Message contains hello

Responses

{
  "status": "SUCCESS"
}

Errors

INVALID_FILTER_FROM
Invalid messagefrom parameter.

INVALID_WEBHOOK_URL
Invalid webhook URL. It should start with http:// or https://

INVALID_WEBHOOK_ID
webhookid is missing.

WEBHOOK_ID_EXISTS
webhookid is already existing.


List webhooks

/session/list-webhooks
Lists webhook IDs.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567

Responses

{
  "status": "SUCCESS"
  "webhooks": ["hello_world"]
}

Delete webhooks

/session/delete-webhook
Deletes webhook by ID.

Request

Parameter # Description Example
apikey Required API key obtained from member panel sPvWA4WpYmU..
phone Required Phone number of session 18501234567
webhookid Required Unique webhook ID hello_world

Responses

{
  "status": "SUCCESS"
}

Errors

INVALID_WEBHOOK_ID
webhookid is missing.


Webhook responses

New messages are sent to your webhook URL with parameters below.

Request body (POST)

Parameter # Description Example
id Always Message ID ABCDEF0123456789
chat Always Chat JID 18501234567, or 18501234567-1603741350 for groups.
timestamp Always Message unix timestamp 1603741350
message Message text hello
media Boolean value of message containing a media or not true
participant if chat is a group Sender of message (in the group) 18501234567

Response

Your webhook should return HTTP 200.