Whatsapp API

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

denis716@undisclosed.example.com (denis716) — Thu, 24 Nov 2022 11:12:08 +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 и удаление сессии
page_cnt - максимальное количество событий, возвращаемых на одной странице запроса. По умолчанию - 10, максимальное значение - 100.
page - номер страницы запроса. По умолчанию - 1

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

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

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

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

Запросы к API

denis716@undisclosed.example.com (denis716) — Wed, 23 Nov 2022 22:53:54 +0000

Запросы к API

Запросы к API осуществляются на адрес

https://whatsgate.ru/api/v1/<команда>

Перечень команд управления инстансом Whatsapp:

send - отправка сообщений
seen - делает последние сообщения в чате просмотренными для собеседника
get-chats - запрос списка чатов
get-media - запрос медиа-файла
check - проверка зарегистрирован ли номер в Вотсап
events-get - запрос входящих событий для получения входящих сообщений

Перечень команд управления сессиями:

session-create - создание новой сессии Whatsapp
session-delete - удаление сессии Whatsapp с выходом из авторизации
sessions-get - получение списка сессий
set-name - изменение имени сессии
set-hook - установка webhook для получения входящих сообщений

Заголовки запроса

Авторизация в API производится в заголовке запроса X-Api-Key Также, обязательно наличие заголовка Content-type: application/json

X-Api-Key: YOUR_API_KEY
Content-type: application/json

Тело запроса

В теле запроса передается JSON - объект, обязательным параметром которого является WhatsappID

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "number": "79999999999"
}

Ответ на запрос

Если все прошло удачно, то в ответе на запрос будет указан код 200, в теле ответа будет находится JSON-объект. Поля JSON-объекта будут установлены в зависимости от переданной команды.

{
  "result": "OK",
  "data": true
}

При ошибке, кот ответа будет 500. Возвращаемый объект содержит следующие поля:

name - Наименование ошибки
message - Более подробная информация об ошибке
code - Код ошибки

{
  "name": "Unauthorized",
  "message": "Your request was made with invalid credentials.",
  "code": 0
}

Получение списка сессий - создано

denis716@undisclosed.example.com (denis716) — Mon, 17 Oct 2022 22:57:07 +0000

Получение списка сессий

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

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

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

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

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

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

{
  "WhatsappID" : "",
  "name" : "",
  "status" : "",
  "page_cnt" : "",
  "page" : ""
}

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

WhatsappID - фильтр по идентификатору WhatsApp, используется для точного совпадения и возвращает в результате одну сессию с указанным идентификатором.
name - фильтр по наименованию, срабатывает по неточному совпадению, т.е. по части вхождения строки.
status - фильтр по статусу сессии. Может принимать одно из указанных значений:
- AUTH - сессии в статусе авторизации.
- READY - сессии в рабочем состоянии.
- ERROR - сессии в статусе ошибки.
- CLOSED - закрытые сессии (по причине ошибки или по причине окончания оплаты по тарифу)
page_cnt - максимальное количество сессий, возвращаемых на одной странице запроса. По умолчанию - 50, максимальное значение - 100.
page - номер страницы запроса. По умолчанию - 1

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

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

{
  "result": "OK",
  "pages" : 1,
  "elements" : 2,
  "page" : 1,
  "data" : [
     {
        "id": 151,
        "name": "My WhatsApp 1",
        "unique_id": "6345454545454",
        "status": "AUTH",
        "callback": "",
        "date_add": "2022-10-11 19:30:14",
        "status_name": "Авторизация",
        "qr_link": "https://whatsgate.ru/qr/6345454545454"
     },
     {
        "id": 152,
        "name": "My WhatsApp 2",
        "unique_id": "6345454545455",
        "status": "READY",
        "callback": "",
        "date_add": "2022-10-12 10:35:01",
        "status_name": "Работает",
        "qr_link": ""
     },
  ]
}

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

Изменение имени сессии

denis716@undisclosed.example.com (denis716) — Mon, 17 Oct 2022 22:12:22 +0000

Изменение имени сессии

Команда изменяет имя name указанной сессии WhatsApp.

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

Для изменения имени сессии отправляется POST-запрос на адрес:

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

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

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

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "name": "new name"
}

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

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

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

{
  "result": "OK",
  "data":  {
     "id": 151,
     "name": "new name",
     "unique_id": "6345454545454",
     "status": "READY",
     "callback": "https://callback.my/script.handler",
     "date_add": "2022-10-11 19:30:14",
     "status_name": "Работает"
  }
}

data - объект сессии

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

denis716@undisclosed.example.com (denis716) — Wed, 12 Oct 2022 10:23:55 +0000

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

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

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

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

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

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

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

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

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

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

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

{
  "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": "Инициализация",
     "qr_link": "https://whatsgate.ru/qr/6345454545454"
  }
}

result - при успешном выполнении запроса содержит «OK».
data - содержит объект созданной сессии, в котором указан ее уникальный идентификатор unique_id, и ссылка на авторизацию по QR-коду 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 - попытка открыть окно с идентификатором несуществующей или закрытой сессии.

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

denis716@undisclosed.example.com (denis716) — Wed, 12 Oct 2022 10:20:43 +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":"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"
}

Типы событий

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":"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":"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 содержит объект сообщения, которое было прочитано

{
  "id":19,
  "whatsapp_id":"191b80a9238",
  "event_action":"ack",
  "event_date":"2022-09-07 18:29:37",
  "status_code":null,
  "event_data":
  {
    "message": 
    {
       "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"
  }
}

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

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

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

id - идентификатор сообщения в Whatsapp, который можно указывать при отправке в поле «quote», для указания того, что сообщение является ответом на указанное сообщение.
ack - флаг, показывающий, было ли сообщение просмотрено получателем
hasMedia - флаг, указывающий на то, содержит ли сообщение медиа-файл
mediaKey - ключ медиа-файла, который необходимо указать в методе get-media для получения media-файла.
body - текст сообщения
type - тип сообщения
timestamp - дата сообщения в формате unix-timestamp
from - указывает идентификатор отправителя сообщения
to - указывает идентификатор получателя сообщения
isForwarded - признак того, было ли сообщение перенаправлено с другого чата

Удаление сессии по API - создано

denis716@undisclosed.example.com (denis716) — Wed, 12 Oct 2022 10:13:22 +0000

Удаление сессии по API

Удаление сессии означает, что авторизация приложения WhatsApp разрывается, все данные сессии удаляются с серверов whatsgate, ресурс освобождается (т.е. если в вашем тарифе доступна 1 сессия, то без удаления сессии вы не сможете создать новую).

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

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

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

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

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

{
  "WhatsappID": "YOUR_WHATSAPP_ID"
}

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

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

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

{
  "result": "OK",
  "data": {
        "id": 456,
        "name": "My Whatsapp",
        "unique_id": "YOUR_WHATSAPP_ID",
        "status": "DESTROYING",
        "callback": null,
        "date_add": "2022-10-12 07:10:49",
        "status_name": "Удаляется"
    }
}