messengers API documentation

hand

We regret to inform you that this article has lost its relevance. Perhaps, the described service is no longer available, or the API working conditions have changed.

Now the Chat API offers the most accessible and automated messengers Business API on the market with Shared Team Inbox, No-Code Chatbot Builder, ready-to-use apps integrations and other features.

This is a reliable way to introduce more than 2 billion messenger audience to your business or product: customer engagement on messengers made simple.

The actual documentation is located here

Thank you for visiting us. Best Regards!

Full documentation


The REST API allows you to receive and send messages through your messengers 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 messengers API is based on the messengers 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 messengers 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 messengers application by going to Menu -> messengers 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: [email protected] for private messages and [email protected] 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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]_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": "[email protected]",
        //send time, unix timestamp
        "time": 1504208593,
        //chat ID
        "chatId": "[email protected]",
        //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": "[email protected]_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": "[email protected]",
        //send time, unix timestamp
        "time": 1504208593,
        //chat ID
        "chatId": "[email protected]",
        //sequence number of the message in the database
        "messageNumber": 100
    }, {
        //...
    }],
    "ack": [{//message delivered
        "id": "[email protected]_DF38E6A25B42CC8CCE57EC40F",
        "queueNumber": 100
        "chatId": "[email protected]",
        "status": "delivered",
    },{//message viewed
        "id": "[email protected]_DF38E6A25B42CC8CCE57EC40F",
        "queueNumber": 100
        "chatId": "[email protected]",
        "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 messengers Web to get new QR code.

Server response example:
{
    "result": "Logout request sent to messengers"
}

GET /reboot

Reboot your messengers 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":"[email protected]",
         "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"
   ]
}