Whatsapp API documentation

Full documentation

The REST API allows you to receive and send messages through your WhatsApp account. Sign up now

Parameters in GET queries pass query string. Parameters in POST requests — through the JSON-encoded request body. The authorization token is always passed to query string (?token=xxxxxx).

The WhatsApp API is based on the WhatsApp WEB protocol and excludes the ban both when using libraries from mgp25 and the like. Despite this, your account can be banned by anti-spam system WhatsApp after several clicking the "block" button.

Business API documentation

GET /status

Get the account status and QR code for authorization. Reauthorization is necessary only in case of changing the device or manually pressing "Logout on all devices" on the phone. Keep the WhastsApp application open during authorization.

.

init	Initial status
loading	The system is still loading, try again in 1 minute
got qr code	There is a QR code and you need to take a picture of it in the Whatsapp application by going to Menu -> WhatsApp Web -> Add. QR code is valid for one minute. Example showing base64 images on a page . Manually easier to get QR-code as an image
authenticated	Authorization passed successfully

Server response example:

{
    "accountStatus": "got qr code",
    "qrCode": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ....."
}

GET /qr_code

Direct link to QR-code in the form of an image, not base64.

POST /group

Creates a group and sends the message to the created group. If the host is iPhone, then the presence of all in the contact list is required.

The group will be added to the queue for sending and sooner or later it will be created, even if the phone is disconnected from the Internet or the authorization is not passed.

2 Oct 2018 update: chatId parameter will be returned if group was created on your phone within 20 seconds.

Request parameters:

groupName	Group name, string, mandatory.
phones	An array of phones starting with the country code. You do not need to add your number. USA example: ['17472822486'].
messageText	Message text, string

Request example:

{
    "phones": ["17472822486","79680565372"],
    "messageText": "Safari is the new IE",
    "groupName": "Browsers",
}

POST /sendMessage

Send a message to a new or existing chat. The message will be added to the queue for sending and delivered even if the phone is disconnected from the Internet or authorization is not passed.

Only one of two parameters is needed to determine the destination - chatId or phone.

Request parameters:

phone	Required if chatId is not set	A phone number starting with the country code. You do not need to add your number. USA example: 17472822486.
chatId	Required if phone is not set	Chat ID from the message list. Examples: 79633123456@c.us for private messages and 79680561234-1479621234@g.us for the group. Used instead of the phone parameter.
body	Required	Message text, UTF-8 or UTF-16 string with emoji 🍏

Request examples:

{
    "phone": "17472822486",
    "body": "Hello, world! 🍏"
}

{
    "chatId": "17472822486@c.us",
    "body": "Hello, world!"
}

Server response example:

{
    "sent": true,
    "message": "ok"
}

POST /sendFile

Send a file to a new or existing chat.

Only one of two parameters is needed to determine the destination - chatId or phone.

Request parameters:

phone	Required if chatId is not set	The same as POST /sendMessage
chatId	Required if phone is not set	The same as POST /sendMessage
body	Required	HTTP link https://upload.wikimedia.org/wikipedia/ru/3/33/NatureCover2001.jpg Or base64-encoded file with mime data, for example data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ... File in form-data input field
filename	Required	File name, for example 1.jpg or hello.xlsx
caption	Optional	Text under the photo

Request examples:

{
    "chatId": "17472822486@c.us",
    "body": "https://upload.wikimedia.org/wikipedia/ru/3/33/NatureCover2001.jpg",
    "filename": "cover.jpg"
}

{
    "phone": "17472822486",
    "body": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAMAAACeL25MAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyNpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuNi1jMTQwIDc5LjE2MDQ1MSwgMjAxNy8wNS8wNi0wMTowODoyMSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENDIChNYWNpbnRvc2gpIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkI3OEY5RkZENjkwQjExRTg4NENBQjE1QkFGNzEzOEQ5IiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkI3OEY5RkZFNjkwQjExRTg4NENBQjE1QkFGNzEzOEQ5Ij4gPHhtcE1NOkRlcml2ZWRGcm9tIHN0UmVmOmluc3RhbmNlSUQ9InhtcC5paWQ6Qjc4RjlGRkI2OTBCMTFFODg0Q0FCMTVCQUY3MTM4RDkiIHN0UmVmOmRvY3VtZW50SUQ9InhtcC5kaWQ6Qjc4RjlGRkM2OTBCMTFFODg0Q0FCMTVCQUY3MTM4RDkiLz4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz60+8CVAAAADFBMVEX/zc2ampr/ZmYwMDB/wIlPAAAAGUlEQVR42mJgZmQAQkYGBgYmJiYwwQgQYAAAzQAVpgHCIgAAAABJRU5ErkJggg==",
    "filename": "4x4pixel.jpg"
}

Server response example:

{
    "sent": true,
    "message": "ok"
}

GET /messages

Get a list of messages. To receive only new messages, pass the lastMessageNumber parameter from the last query.

Files from messages are guaranteed to be stored only for 30 days and can be deleted. Download the files as soon as you get to your server.

Request parameters:

lastMessageNumber	The lastMessageNumber parameter from the last response
last	Displays the last 100 messages. If this parameter is passed, then lastMessageNumber is ignored.

Server response example:

// GET /messages?lastMessageNumber=99:
{
    "messages:" [{
        //unique id
        "id": "false_17472822486@c.us_DF38E6A25B42CC8CCE57EC40F",
        //text message for type "chat" or link to download the file for "ptt", "image", "audio" and "document"
        "body": "Ok!",
        //type of the message - "chat" - text, "image" - image, "ptt" - voice, "document" - text document, "audio" - audio file, "call_log" - call
        "type": "chat",
        //Sender name
        "senderName": "Ilya",
        //true - outgoing, false - incoming
        "fromMe": true,
        //Author ID of the message, useful for groups
        "author": "17472822486@c.us",
        //send time, unix timestamp
        "time": 1504208593,
        //chat ID
        "chatId": "17472822486@c.us",
        //sequence number of the message in the database
        "messageNumber": 100
    }, {
        //...
    }],
    "lastMessageNumber": 199 //next query should be /messages?lastMessageNumber=199
}

POST /webhook

Sets the URL for receiving webhook notifications of new messages and message delivery events (ack).

Request parameters:

webhookUrl

Http or https URL for receiving notifications. For testing, we recommend using requestb.in.

Server response example:

{
    "set": true,
    "webhookUrl": "https://requestb.in/1f9aj261"
}

Example of a webhook notification:

{ // It has the same JSON payload as /messages has
  // Sending to POST JSON body
    "messages": [{
        //unique id
        "id": "false_17472822486@c.us_DF38E6A25B42CC8CCE57EC40F",
        //text message for type "chat" or link to download the file for "ptt", "image", "audio" and "document"
        "body": "Ok!",
        //type of the message - "chat" - text, "image" - image, "ptt" - voice, "document" - text document, "audio" - audio file, "call_log" - call
        "type": "chat",
        //Sender name
        "senderName": "Ilya",
        //true - outgoing, false - incoming
        "fromMe": true,
        //Author ID of the message, useful for groups
        "author": "17472822486@c.us",
        //send time, unix timestamp
        "time": 1504208593,
        //chat ID
        "chatId": "17472822486@c.us",
        //sequence number of the message in the database
        "messageNumber": 100
    }, {
        //...
    }],
    "ack": [{//message delivered
        "id": "false_17472822486@c.us_DF38E6A25B42CC8CCE57EC40F",
        "queueNumber": 100
        "chatId": "17472822486@c.us",
        "status": "delivered",
    },{//message viewed
        "id": "false_17472822486@c.us_DF38E6A25B42CC8CCE57EC40F",
        "queueNumber": 100
        "chatId": "17472822486@c.us",
        "status": "viewed",
    }, {
        //...
    }],
}

GET /webhook

Returns current webhook url.

Server response example:

{
    "set": true,
    "webhookUrl": "https://requestb.in/1f9aj261"
}

POST /settings/ackNotificationsOn

Turn on/off ack (message delivered and message viewed) notifications in webhooks. GET method works for the same address.

Request parameters:

ackNotificationsOn

1 (true) or 0 (false) .

GET /logout

Logout from WhatsApp Web to get new QR code.

Server response example:

{
    "result": "Logout request sent to WhatsApp"
}

GET /reboot

Reboot your WhatsApp instance.

Server response example:

{
    "success": true
}

GET /showMessagesQueue

Get outbound messages queue.

Server response example:

{
   "totalMessages":2,
   "first100":[
      {
         "id":1,
         "body":"Hey!",
         "type":"text",
         "chatId":"79600005372@c.us",
         "last_try":1528320463436,
         "metadata":"{}"
      },
   ]
}

GET /clearMessagesQueue

Clear outbound messages queue. This method is needed when you accidentally sent thousands of messages in a row.

Server response example:

{
   "message":"Cleared 2 messages",
   "messageTextsExample":[
      "Hello world",
      "Hello world"
   ]
}