Whatsapp API

Обработка входящих (Webhook) - [Create]

denis716@undisclosed.example.com (denis716) — Thu, 22 Jan 2026 14:02:04 +0000

Обработка входящих (Webhook)

Webhook служит для обработки входящих событий, ответов на асинхронные запросы и информацию об ошибках. Например, при приеме входящего сообщения в мессенджере, на указанный webhook отправляется POST-запрос:

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id" : "3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

Для подтверждения успешного приема события, webhook должен отправить JSON-объект, в котором должен быть указан идентификатор входящего события и статус OK

{
  "result" : "OK",
  "id" : 18
}

Если система не получит в ответ корректного сообщения, то запрос повторится 3 раза, через каждые 20 секунд.

Установка Webhook-a

Установка Webhook в личном кабинете

Для установки ссылки на обработчик Webhook, зайдите в личный кабинет, выберите блок привязанного Whatsapp-месенджера, нажмите 3 точки и выберите редактировать.

В открывшемся окне укажите ссылку на скрипт-обработчик Webhook-a

Нажмите «Сохранить»

Установка Webhook через API

Для установления или деактивации WebHook-a по API используйте метод set-hook. Инициируем POST-запрос на адрес:

https://whatsgate.ru/api/v1/set-hook

В теле запроса передается объект:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "callback": "https://callback.my/script.handler"
}

WhatsappID - идентификатор Whatsapp в системе
callback - URL обработчика обработчика входящих событий

Объект успешного ответа на запрос

{
  "result": "OK"
}

Типы событий

Ready

Событие отправляется после авторизации, когда клиент полностью готов к отправке и приему сообщений. Статус сессии изменяется с AUTH на READY. Поле event_action содержит строку «ready» Поле event_data содержит данные об авторизованном аккаунте - его номер и имя.

pushname - имя клиента в мессенджере
number - номер авторизованного телефона
id - whatsapp идентификатор в формате @c.us

{
  "id":19,
  "whatsapp_id" : "191b80a9238",
  "event_action" : "ready",
  "event_date" : "2023-01-24 18:29:37",
  "status_code" : null,
  "event_data" :
  {
    "pushname": "vasya",
    "number" : "79991234567",
    "id" : "79991234567@c.us"
  }
}

Message

Событие отправляется при любом входящем сообщении в чате или группе. Поле event_action содержит строку «message» Поле event_data содержит объект сообщения

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"message",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

Sent

Событие отправляется после успешной доставки сообщения, в том случае, если была отправлена асинхронная команда отправки сообщения.

Поле event_action содержит строку «sent» Поле event_data содержит объект сообщения, которое было доставлено

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"sent",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

Ack

Событие отправляется при изменении статуса сообщения в чате или группе. Поле event_action содержит строку «ack» Поле event_data содержит объект сообщения, статус которого был изменен. Статус сообщения содержится в объекте сообщения, в поле ack и может принимать следующие значения: 1 - отправлено, 2 - доставлено, 3 - прочитано

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"ack",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79999999999@c.us",
       "to":"79991112233@c.us",
       "isForwarded":false
    }
  }
}

Disconnect

Событие отправляется, когда клиент отсоединяется и закрывается. Это происходит в случаях, когда Вы удаляете клиент из личного кабинета сервиса, или отзываете привязку в приложении Whatsapp на телефоне. Поле event_action содержит строку «disconnect» Поле event_data содержит объект с полем reason, в котором указана причина дисконнекта.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"disconnect",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "reason": "Client disconnected"
  }
}

Error

Событие отправляется когда происходит какая-либо ошибка. Например, когда Вы пытаетесь асинхронно отправить сообщение не из своего контакт-листа на тарифе Light. Поле event_action содержит строку «error» Поле event_data содержит объект с описанием ошибки.

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"error",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "error":"Specified number not in your contact list"
  }
}

Create

Событие отправляется при любом исходящем сообщении в чате или группе. Это позволяет через webhook отслеживать отправленные сообщения, в том числе и с мобильного клиента, и из других связанных приложений.

Поле event_action содержит строку «create»

Поле event_data содержит объект сообщения

{
  "id":18,
  "whatsapp_id":"191b80a9238",
  "event_action":"create",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "_id":"3EB0436AE1E682FF3A37",
       "id":"true_79999999999@c.us_3EB0436AE1E682FF3A37",
       "ack":1,
       "hasMedia":false,
       "mediaKey":"",
       "body":"212",
       "type":"chat",
       "timestamp":1662575377,
       "from":"79991112233@c.us",
       "to":"79999999999@c.us",
       "isForwarded":false
    }
  }
}

Объект сообщения

{
   "_id":"3EB0436AE1E682FF3A37",
   "id":"false_79999999999@c.us_3EB0436AE1E682FF3A37",
   "ack":1,
   "hasMedia":false,
   "mediaKey":"",
   "body":"212",
   "type":"chat",
   "timestamp":1662575377,
   "from":"79999999999@c.us",
   "to":"79991112233@c.us",
   "isForwarded":false,
   "quoted": {
       "_id": "3EB07621A4D08F9F59E0",
       "from": "79537226631@c.us",
       "type": "chat",
       "body": "Hello!"
   }
}

Поля объекта сообщения:

_id - идентификатор сообщения в WhatsApp.
id - идентификатор сообщения в Whatsapp, который можно указывать при отправке в поле «quote», для указания того, что сообщение является ответом на указанное сообщение.
ack - (int) флаг, показывающий, было ли сообщение просмотрено получателем, принимает следующие значения: 1 - отправлено, 2 - доставлено, 3 - прочитано
hasMedia - флаг, указывающий на то, содержит ли сообщение медиа-файл
mediaKey - ключ медиа-файла, который необходимо указать в методе get-media для получения media-файла.
body - текст сообщения
type - тип сообщения
timestamp - дата сообщения в формате unix-timestamp
from - указывает идентификатор отправителя сообщения
to - указывает идентификатор получателя сообщения
isForwarded - признак того, было ли сообщение перенаправлено с другого чата
quoted - Если данное сообщение цитирует (является ответом на) сообщение, то в поле quoted находится объект, с параметрами цитируемого сообщения.
- _id - Идентификатор цитируемого сообщения
- from - Идентификатор автора цитируемого сообщения
- type - Тип цитируемого сообщения
- body - Текст цитируемого сообщения

Код PHP для обработки запроса webhook

<?php
 
//буферизируем вывод
ob_start();
 
var_dump('----------------------' . date('d.m.Y H:i:s') . '----------------');
 
// вытаскиваем данные запроса
$input = file_get_contents('php://input');
$input_data = json_decode($input, true);
 
var_dump($input_data);
 
if($input_data['event_action'] == 'message') {
    //@TODO обрабатываем входящее сообщение
 
}
 
if($input_data['event_action'] == 'ack') {
 
    //@TODO обрабатываем получение или доставку
 
    if($input_data['event_data']['message']['ack'] == 2) {
        //@TODO доставка
    }
    if($input_data['event_data']['message']['ack'] == 3) {
        //@TODO прочитано
    }
}
 
//сохраняем лог
$fo = fopen('webhook.log', 'a');
fwrite($fo, ob_get_clean());
fclose($fo);
 
//формируем и выводим ответ
$answer_data = [
    'id' => $input_data['id'],
    'result' => 'OK'
];
 
echo json_encode($answer_data);
?>

Обработка входящих (events-get) - [Объект в теле запроса]

denis716@undisclosed.example.com (denis716) — Thu, 22 Jan 2026 13:59:38 +0000

Обработка входящих (events-get)

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

входящие сообщения (action = message)
просмотр сообщения (action = ack)
входящий медиа-файл (action = media)
отправка сообщения (action = sent) событие происходит только при асинхронной отправке сообщения
ошибка (action = error)
отсоединение Whatsapp и удаление сессии (action = disconnect)

Команда отправки

Для получения списка событий инициируется POST-запрос на адрес:

https://whatsgate.ru/api/v1/events-get

Объект в теле запроса

В теле запроса передается объект:

{
  "WhatsappID" : "XXXXXXXXXXXXX",
  "date" : "YYYY-MM-DD HH:MM:SS",
  "action" : "message",
  "page_cnt" : "10",
  "page" : "1"
}

все указанные поля в данном объекте являются необязательными, т.е. для получения полного списка событий достаточно передать пустой объект. Поля WhatsappID и action - являются фильтрами, поле date ограничивает события указанной датой. Дата используется следующим образом: при получении событий, мы анализируем дату последнего события, и передаем ее в следующем запросе в поле date для получения свежих событий.

WhatsappID - фильтр по идентификатору WhatsApp, используется для точного совпадения и возвращает в результате события для указанной сессии. Если не указывать, то система вернет события для всех сессий, в том числе и удаленных.
date - ограничивает события указанной датой. Дата используется следующим образом: при получении событий, мы анализируем дату последнего события, и передаем ее в следующем запросе в поле date для получения свежих событий.
action - фильтр по типу события. Может принимать одно из указанных значений:
- message - входящее сообщение.
- ack - просмотр сообщения.
- media - входящий медиа-файл.
- sent - сообщение отправлено (событие происходит только при асинхронной отправке сообщения)
- error - ошибка
- disconnect - отсоединение Whatsapp и удаление сессии
- create - исходящее сообщение
page_cnt - максимальное количество событий, возвращаемых на одной странице запроса. По умолчанию - 10, максимальное значение - 100.
page - номер страницы запроса. По умолчанию - 1

Объект ответа на запрос

Объект успешного ответа на запрос

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     // 
  ]
}

result - при успешном выполнении запроса содержит «OK»
pages - количество страниц при указанных фильтрах
elements - количество элементов в результате при указанных фильтрах (количество событий)
page - номер текущей страницы
data - содержит массив объектов, представляющих событие.

Работа с медиа-файлами (устаревший)

denis716@undisclosed.example.com (denis716) — Thu, 22 Jan 2026 13:41:47 +0000

Данная команда является устаревшей и будет со временем удалена.

Используйте метод get-messagemedia

Работа с медиа-файлами (устаревший)

Данная команда позволяет получить медиа-файл, присланный в полученном сообщении. Если у сообщения есть медиа-файл, то поле сообщения «hasMedia» будет установлено в true, и в поле «mediaKey» будет находится идентификатор медиа-файла, который используется в данной команде.

Команда отправки

Для отправки сообщения инициируется POST-запрос на адрес:

https://whatsgate.ru/api/v1/get-media

Объект в теле запроса

В теле запроса передается объект:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "mediaKey": "TuM9wXQZBmERUCzwnIZe80GwZ5lPDIDsNE+vewnAxho="
}

WhatsappID - идентификатор Whatsapp в системе
mediaKey - идентификатор меди-файла

Объект ответа на запрос

Объект успешного ответа на запрос

{
  "result": "OK",
  "media": {
    "mimetype": "image/jpeg",
    "filename" : "image.jpg",
    "data": "<base64_encoded_data>"
  }
}

В ответе, в поле «media» передается объект медиа-файла

API

denis716@undisclosed.example.com (denis716) — Thu, 22 Jan 2026 12:01:37 +0000

API

Описание основного API сервиса

Работа с медиа-файлами

denis716@undisclosed.example.com (denis716) — Thu, 22 Jan 2026 11:53:20 +0000

Работа с медиа-файлами

Данная команда позволяет получить медиа-файл из любого сообщения. Если у сообщения есть медиа-файл, то поле сообщения «hasMedia» будет установлено в true, и для получения медиа-файла необходимо указать полный id этого сообщения в формате false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4

Команда отправки

Для отправки сообщения инициируется POST-запрос на адрес:

https://whatsgate.ru/api/v1/get-messagemedia

Объект в теле запроса

В теле запроса передается объект:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "MessageID": "false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4"
}

WhatsappID - идентификатор Whatsapp в системе
MessageID - идентификатор сообщения

Объект ответа на запрос

Объект успешного ответа на запрос

{
  "result": "OK",
  "media": {
    "mimetype": "image/jpeg",
    "filename" : "image.jpg",
    "data": "<base64_encoded_data>"
  }
}

В ответе, в поле «media» передается объект медиа-файла

Если сообщение не найдено, или в сообщении нет медиа - в ответе вернется ошибка

Создание сессии по API - [Объект в теле запроса при ...

denis716@undisclosed.example.com (denis716) — Fri, 12 Apr 2024 10:24:57 +0000

Создание сессии по API

Команда открывает сессию WhatsApp для привязки к сервису. После открытия сессии необходимо авторизовать WhatsApp через мобильное приложение и QR-код. Если сессия не нужна, то ее необходимо закрыть командой session-delete

Команда отправки

Для отправки сообщения инициируется POST-запрос на адрес:

https://whatsgate.ru/api/v1/session-create

Объект в теле запроса при авторизации по QR

В теле запроса передается объект:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler"
}

name - наименование WhatsApp в системе (для удобства распознавания)
callback - URL обработчика обработчика входящих событий (необязательное, можно установить позже методом set-hook

Объект в теле запроса при авторизации по CODE

В теле запроса передается объект:

{
  "name" : "My WhatsApp",
  "callback" : "https://callback.my/script.handler",
  "auth_type" : "CODE",
  "number" : "79999999999"
}

name - наименование WhatsApp в системе (для удобства распознавания)
callback - URL обработчика обработчика входящих событий (необязательное, можно установить позже методом set-hook
auth_type - Тип авторизации - по коду. При этом становится обязательным указание номера телефона, который будет авторизован по коду
number - номер подключаемого телефона в формате 7XXXXXXXXXX

Объект ответа на запрос

Объект успешного ответа на запрос

{
  "result": "OK",
  "data" : {
     "id": 151,
     "name": "My WhatsApp",
     "unique_id": "6345454545454",
     "status": "PENDING",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "qr": null,
     "status_name": "Инициализация",
     "pushname": null,
     "wid": null,
     "qr_link": "https://whatsgate.ru/qr/6345454545454"
  }
}

result - при успешном выполнении запроса содержит «OK».
data - содержит объект созданной сессии, в котором указан ее уникальный идентификатор unique_id, и ссылка на авторизацию по QR-коду qr_link
qr или code зависит от типа указанной авторизации. Если был выбран тип авторизации по коду, то код будет находится в поле code. Поле qr_link будет вести на страницу с кодом авторизации.

Окно авторизации по QR-коду

Окно авторизации по QR-коду открывается по ссылке:

https://whatsgate.ru/qr/<unique_id>

Для удобства, данная ссылка передается в поле qr_link при создании сессии. QR-код, содержащийся в этом окне периодически обновляется, а так же изменяется на изображение успешной авторизации или ошибки.

Встраивание страницы с QR

Данную страницу возможно встраивать в собственное приложение посредством iframe, и принимать от нее сообщения в родительской странице. Пример встраивания:

<h1>Test code QR</h1>

<iframe src="https://whatsgate.ru/qr/6345454545454" width="310" height="310" style="border: none;">

</iframe>

<div class="log" id="log">

</div>

<script>
    window.addEventListener("message", function(event) {

        console.log(event);

        if (event.origin !== 'https://whatsgate.ru') {
            // что-то пришло с неизвестного домена. Давайте проигнорируем это
            return;
        }

        if(typeof event.data !== 'object') {
            // сообщение должно быть объектом. 
            return;
        }

        if(!('module' in event.data) && event.data.module !== 'qr'){
            // в объекте должно быть поле module со значением qr
            return;
        }

        //если мы здесь, значит сообщение верное, выведем его значение
        console.log( "received: " + event.data.message);
        //добавим сообщение в лог на родительской странице
        document.getElementById('log').append("received: " + event.data.message, document.createElement("br"));
    });
</script>

Объект сообщения содержится в поле event.data и имеет следующий формат:

{
  "module" : "qr",
  "message" : "<message>"
}

module - всегда имеет значение qr, чтобы идентифицировать нужные сообщения
message - могут быть следующие значения:
- loading - инициализация сессии и загрузка qr-кода. Отправляется в начале загрузки страницы
- qr - выдан и отображен qr-код. Сообщение приходит каждый раз, когда код меняется на новый.
- success - устройство успешно авторизовано в сессии, qr-код скрывается.
- error - произошла ошибка при авторизации устройства. Нужно попробовать еще раз.
- broken - попытка открыть окно с идентификатором несуществующей или закрытой сессии.

Отправка признака печати - создано

denis716@undisclosed.example.com (denis716) — Thu, 04 Apr 2024 17:45:34 +0000

Отправка признака печати

Признак печати отправляется с указанием контакта, после указанный абонент в течение 15 секунд будет видеть у номера статус «печатает»

Команда отправки

Для отправки сообщения инициируется POST-запрос на адрес:

https://whatsgate.ru/api/v1/typing

Объект в теле запроса

В теле запроса передается объект:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "recipient": {
    "id": "79999999999@c.us"
  }
}

WhatsappID - идентификатор Whatsapp в системе
recipient - объект получателя

Объект ответа на запрос

Объект успешного ответа на запрос

{
  "result": "OK"
}