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.

Guides for building a Whatsapp bot on PHP or on Python

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"
   ]
}

See more in Full documentation


Sign up for WhatsApp API account