Документация

Полная документация


REST API позволяет принимать и отправлять сообщения через аккаунт WhatsApp. Зарегистрировать аккаунт WhatsApp API

Параметры в GET запросах передавайте через query string. Параметры в POST запросах — через JSON-encoded тело запроса. Токен авторизации всегда передается в query string (?token=xxxxxx).

К каждому запросу необходимо прибавить токен в GET параметре token.

API WhatsApp работает на основе протокола WhatsApp WEB и исключает бан как при использовании библиотек от mgp25 и подобных. Несмотря на это, Ваш аккаунт может быть забанен анти-спам системой WhatsApp после нескольких нажатий кнопки "в спам".

Руководства по созданию Whatsapp бота на PHP и на Python


GET /status

Получить статус аккаунта и QR код для авторизации. Повторная авторизация нужна только в случае смены устройства или ручного нажатия "Выйти из всех устройств" на телефоне. Держите приложение WhastsApp открытым во время авторизации.

.
init это начальный статус
loading загрузка, повторите через 30 секунд
got qr code есть QR код и нужно его сфотографировать в приложении Whatsapp перейдя в Меню > WhatsApp Web > Добавить. QR код действителен в течении одной минуты. Пример отображения base64 картинки на странице.
Вручную проще получить изображение QR-кода
authenticated авторизация пройдена успешно
Пример ответа:
{
    "accountStatus": "got qr code",
    "qrCode": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ....."
}

GET /qr_code

Прямая ссылка на QR-код в виде изображения, а не base64.

POST /group

Создание группы и отправка сообщения в созданную группу. Если хост iPhone, то наличие всех в списке контактов обязательно.

Группа будет добавлена в очередь на отправку и рано или поздно создана, даже если телефон отключен от интернета или авторизация не пройдена.

Обновление от 2 октября 2018: параметр chatId будет заполнен, если удалось создать группу на вашем телефоне в течении 20 секунд.

Параметры:
groupName Название группы, строка, обязательное.
phones Массив телефонов, начинающийся с кода страны. Свой номер добавлять не надо.
Для России и Казахстана это всегда 7, затем 10 цифр. Пример: 79995253422.
messageText Текст сообщения, строка
Пример запроса:
{
    "phones": ["17162266665","79680565372"],
    "messageText": "Safari is the new IE",
    "groupName": "Browsers",
}

POST /sendMessage

Отправка сообщения в новый или существующий чат. Сообщение будет добавлено в очередь на отправку и доставлено даже если телефон отключен от интернета или авторизация не пройдена.

Нужен только один из двух параметров для определения адресата - chatId или phone.

Параметры:
phone Обязателен если не указан chatId Номер телефона, начинающийся с кода страны. Для России и Казахстана это всегда 7, затем 10 цифр. Сообщения на номера телефона с 8 не будут доставлены. Пример: 79995253422.
chatId Обязателен если не указан phone ID чата из списка сообщений. Примеры: 79633123456@c.us для личных сообщений и 79680561234-1479621234@g.us для группы. Используется вместо параметра phone
body Обязателен Текст сообщения, любая строка включая emoji 🍏
Примеры запросов:
{
    "phone": "17162266665",
    "body": "Hello, brother! 🍏"
}
{
    "chatId": "17162266665@c.us",
    "body": "Hello, brother!"
}
Пример ответа:
{
    "sent": true,
    "message": "ok"
}

POST /sendFile

Отправка файла в новый или существующий чат. Сообщение будет добавлено в очередь на отправку и доставлено даже если телефон отключен от интернета или авторизация не пройдена.

Нужен только один из двух параметров для определения адресата - chatId или phone.

Параметры:
phone Обязателен если не указан chatId Смотрите POST /sendMessage
chatId Обязателен если не указан phone Смотрите POST /sendMessage
body Обязателен Ссылка на файл, например https://upload.wikimedia.org/wikipedia/ru/3/33/NatureCover2001.jpg
Или файл в base64, например data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...
Или файл в поле формы
filename Обязательно Имя отправляемого файла, например 1.jpg или hello.xlsx
caption Не обязательно Текст под фотографией
Примеры запроса:
{
    "chatId": "17162266665@c.us",
    "body": "https://upload.wikimedia.org/wikipedia/ru/3/33/NatureCover2001.jpg",
    "filename": "cover.jpg"
}
{
    "phone": "17162266665",
    "body": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAMAAACeL25MAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyNpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuNi1jMTQwIDc5LjE2MDQ1MSwgMjAxNy8wNS8wNi0wMTowODoyMSAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENDIChNYWNpbnRvc2gpIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkI3OEY5RkZENjkwQjExRTg4NENBQjE1QkFGNzEzOEQ5IiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkI3OEY5RkZFNjkwQjExRTg4NENBQjE1QkFGNzEzOEQ5Ij4gPHhtcE1NOkRlcml2ZWRGcm9tIHN0UmVmOmluc3RhbmNlSUQ9InhtcC5paWQ6Qjc4RjlGRkI2OTBCMTFFODg0Q0FCMTVCQUY3MTM4RDkiIHN0UmVmOmRvY3VtZW50SUQ9InhtcC5kaWQ6Qjc4RjlGRkM2OTBCMTFFODg0Q0FCMTVCQUY3MTM4RDkiLz4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz60+8CVAAAADFBMVEX/zc2ampr/ZmYwMDB/wIlPAAAAGUlEQVR42mJgZmQAQkYGBgYmJiYwwQgQYAAAzQAVpgHCIgAAAABJRU5ErkJggg==",
    "filename": "4x4pixel.jpg"
}
Пример ответа:
{
    "sent": true,
    "message": "ok"
}

GET /messages

Получить список сообщений. Для получения только новых сообщений передайте параметр lastMessageNumber из последнего запроса.

Файлы из сообщений гарантированно хранятся лишь 10 дней и могут быть удалены. Скачивайте файлы сразу при получении на свой сервер.

Параметры:
lastMessageNumber Параметр lastMessageNumber из предыдущего запроса
last Отображает последние 100 сообщений. Если передан этот параметр, то lastMessageNumber игнорируется.
Пример ответа:
// GET /messages?lastMessageNumber=99:
{
    "messages:" [{
        //уникальный ID
        "id": "false_79500281111@c.us_DF38E6A25B42CC8CCE57EC40F",
        //текст сообщения для типа "chat" или ссылка на скачивание файла для "ptt", "image", "audio" и "document"
        "body": "Окей.",
        //Тип сообщения - "chat" - текстовое, "image" - изображение, "ptt" - голосовое, "document" - текстовый документ, "audio" - аудио файл, "call_log" - звонок
        "type": "chat",
        //Имя отправителя
        "senderName": "Ilya",
        //true - исходящее, false - входящее
        "fromMe": true,
        //ID автора сообщения, полезно для групп
        "author": "79500281111@c.us",
        //время отправления, unix timestamp
        "time": 1504208593,
        //ID чата
        "chatId": "79500281111@c.us",
        //порядковый номер сообщения в базе данных
        "messageNumber": 100
    }, {
        //...
    }],
    "lastMessageNumber": 199 //Следующий запрос должен быть /messages?lastMessageNumber=199
}

POST /webhook

Устанавливает URL для получения webhook уведомлений о новых сообщениях и о статусах доставки исходящих сообщений (ack).

Параметры:
webhookUrl Http или https URL для получения оповещений. Для тестирования рекомендуем использовать requestb.in.
Пример ответа:
{
    "set": true,
    "webhookUrl": "https://requestb.in/1f9aj261"
}
Пример webhook уведомления:

{ // 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

Возвращает текущий webhook url.

Пример ответа:
{
    "set": true,
    "webhookUrl": "https://requestb.in/1f9aj261"
}

POST /settings/ackNotificationsOn

Включить или выключить получение уведомлений о доставке и прочтении отправленных сообщений ack в webhook. Так же работает GET метод по тому же адресу.

Параметры:
ackNotificationsOn 1 (true) или 0 (false) .
Пример ответа:
{
    "set": true,
    "webhookUrl": "https://requestb.in/1f9aj261"
}

GET /logout

Выйти из аккаунта и запросить новый QR-код.

Пример ответа:
{
    "result": "Logout request sent to WhatsApp"
}

GET /reboot

Перезагрузить Ваш инстанс WhatsApp.

Пример ответа:
{
    "success": true
}

GET /showMessagesQueue

Показать список сообщений, которые стоят в очереди на отправку, но еще не отправлены.

Пример ответа:
{
   "totalMessages":2,
   "first100":[
      {
         "id":1,
         "body":"Hey!",
         "type":"text",
         "chatId":"79600005372@c.us",
         "last_try":1528320463436,
         "metadata":"{}"
      },
   ]
}

GET /clearMessagesQueue

Очистить очередь на отправку сообщений. Этот метод нужен когда вы случайно отправили тысячи сообщений подряд.

Пример ответа:
{
   "message":"Cleared 2 messages",
   "messageTextsExample":[
      "Hello world",
      "Hello world"
   ]
}