Whatsapp API api

Проверка зарегистрирован ли номер

anonymous@undisclosed.example.com (Anonymous) — Fri, 09 Sep 2022 11:10:34 +0000

Проверка зарегистрирован ли номер

Команда проверяет номер зарегистрирован ли он в Whatsapp.

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

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

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

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

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

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

WhatsappID - идентификатор Whatsapp в системе
number - номер телефона в формате только цифр, с указанием кода страны, например 79991112233

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

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

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

data - если true, то номер зарегистрирован в Whatsapp, если false - то нет.

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

anonymous@undisclosed.example.com (Anonymous) — 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 - содержит массив объектов, представляющих событие.

Информация о чатах

anonymous@undisclosed.example.com (Anonymous) — Wed, 06 Dec 2023 12:44:28 +0000

Информация о чатах

Команда получает информацию обо всех активных чатах в данном клиенте. В ответе выдает список контактов клиента, включая группы, а также список участников групп с правами.

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

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

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

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

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

{
  "WhatsappID": "YOUR_WHATSAPP_ID"
}

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

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

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

{
  "result": "OK",
  "data": [
    { ... CHAT_CONTACT_OBJECT ... }
    ...
  ]
}

data - поле data содержит массив объектов типа контакт чата или группа чата

Объект контакт чата

{
  "id" : "79991112233@c.us",
  "name" : "Василий",
  "isGroup" : false,
  "isReadOnly" : false,
  "unreadCount" : 0,
  "timestamp" : 1662710454,
  "pinned" : false,
  "isMuted" : false,
  "muteExpiration" : 0
}

id - идентификатор контакта
name - имя контакта
isGroup - является ли группой, для контакта false
isReadOnly - запрещена ли отправка сообщений данному получателю, true - запрещена, false - разрешена
unreadCount - количество непрочитанных сообщений в данном чате
timestamp - Время последней активности в данном чате в формате unix-timestamp
pinned - является ли чат закрепленным, true - да, false - нет
isMuted - отключены ли уведомления у данного чата, true - отключены, false - включены
muteExpiration - время в секундах, через которое уведомления будут включены снова, если они отключены

Объект группа чата

{
  "id" : "4239048293082@g.us",
  "name" : "Тестовая",
  "isGroup" : true,
  "isReadOnly" : false,
  "unreadCount" : 0,
  "timestamp" : 1662616476,
  "pinned" : false,
  "isMuted" : false,
  "muteExpiration" : 0
  "groupMetadata" : {... GROUP_METADATA_OBJECT ...}
 }

id - идентификатор группы
name - имя группы
isGroup - является ли группой, для группы true
isReadOnly - запрещена ли отправка сообщений в данную группу, true - запрещена, false - разрешена
unreadCount - количество непрочитанных сообщений в данной группе
timestamp - Время последней активности в данной группе в формате unix-timestamp
pinned - является ли группа закрепленной, true - да, false - нет
isMuted - отключены ли уведомления в данной группе, true - отключены, false - включены
muteExpiration - время в секундах, через которое уведомления будут включены снова, если они отключены
groupMetadata - объект метаданных группы

Объект метаданных группы

{
  "id" : "4239048293082@g.us",
  "creation" : 1658328976,
  "owner" : "79991112233@c.us",
  "size" : 3,
  "participants" : [
     { ... PARTICIPANT_OBJECT ...}
     ...
  ]
}

id - идентификатор группы
creation - дата создания группы в формате unix-timestamp
owner - идентификатор владельца группы
size - количество участников группы
participants - массив объектов участников группы

Объект участник группы

{
  "id" : "79156666555@c.us",
  "isAdmin" : true,
  "isSuperAdmin" : false
}

id - идентификатор контакта участника группы
isAdmin - является ли контакт администратором группы, true - да, false - нет
isSuperAdmin - является ли контакт супер-администратором группы, true - да, false - нет

Полный пример ответа

{
  "result":"OK",
  "data" : [
    { 
      "id" : "79999999999@c.us", 
      "name" : "+7 999 999-99-99", 
      "isGroup" : false,
      "isReadOnly" : false,
      "unreadCount" : 0,
      "timestamp" : 1662710454,
      "pinned" : false,
      "isMuted" : false,
      "muteExpiration" : 0
    },
    {
      "id" : "4239048293082@g.us",
      "name" : "Тестовая",
      "isGroup" : true,
      "isReadOnly" : false,
      "unreadCount" : 0,
      "timestamp" : 1662616476,
      "pinned" : false,
      "isMuted" : false,
      "muteExpiration" : 0,
      "groupMetadata" : {
         "id" : "4239048293082@g.us",
         "creation" : 1658328976,
         "owner" : "79999999999@c.us",
         "size" : 0,
         "participants" : [
           {
             "id" : "79999999999@c.us",
             "isAdmin" : true,
             "isSuperAdmin" : false
           },
           { 
             "id" : "79991112233@c.us",
             "isAdmin" : false,
             "isSuperAdmin":false
           }
        ]
      }
    }
  ]
}

Получение истории сообщений чата

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Mar 2023 12:21:29 +0000

Получение истории сообщений чата

Данная команда получает историю сообщений из указанного чата. Может быть получено не более 100 сообщений из истории, и не старше 90 дней. Запрос осуществляется синхронно, т.е. ответ приходит на запрос а не в WebHook.

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

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

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

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

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

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

WhatsappID - идентификатор Whatsapp в системе
recipient - указывает на чат (или группу), историю сообщений которого нужно получить. Описание объекта recipient

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

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

{
  "result": "OK"
  "data": [
        {
            "id": "false_79999999999@c.us_17AC61BFA5A561B7EE42F98810EDFFC4",
            "ack": 0,
            "hasMedia": false,
            "mediaKey": "",
            "body": "Hello world!",
            "type": "chat",
            "timestamp": 1667296242,
            "from": "79999999999@c.us",
            "to": "79999999999@c.us",
            "isForwarded": false
        }
    ]
}

result - при успешном завершении имеет значение OK
data - массив объектов сообщений. Подробное описание объекта сообщения.

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

anonymous@undisclosed.example.com (Anonymous) — 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» передается объект медиа-файла

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

anonymous@undisclosed.example.com (Anonymous) — 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

anonymous@undisclosed.example.com (Anonymous) — Thu, 04 Apr 2024 17:42:43 +0000

Запросы к API

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

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

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

send - отправка сообщений
seen - делает последние сообщения в чате просмотренными для собеседника
typing - отправляет собеседнику статус «печатает» в течение 15 с
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
}

Отправка флага просмотра

anonymous@undisclosed.example.com (Anonymous) — Fri, 09 Sep 2022 10:35:52 +0000

Отправка флага просмотра

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

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

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

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

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

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

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

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

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

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

{
  "result": "OK"
}

Отправка сообщений

anonymous@undisclosed.example.com (Anonymous) — Wed, 20 Dec 2023 13:37:47 +0000

Отправка сообщений

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

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

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

В теле запроса передается объект отправки сообщения.

Способ отправки

Сообщение через API можно отправить двумя способами:

Синхронно, т.е. ответ на запрос будет отправлен только после отправки сообщения, и в ответ вернется объект отправленного сообщения с идентификатором. При этом, на вебхук не приходит сообщение "Sent"
Асинхронно, т.е. в ответе на запрос будет возвращен результат постановки в очередь, как правило это «ОК», а объект отправленного сообщения придет на вебхук, если он установлен. Тип сообщения - "Sent"

Тип сообщения "Ack" приходит на вебхук всегда, независимо от того синхронно или асинхронно было отправлено сообщение.

Тип отправки зависит от значения поля «async», если оно true, то передача происходит асинхронно, в противном случае - синхронно.

Объект отправки сообщения

В теле запроса отправки сообщения 4 основных поля:

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": { ... RECIPIENT_OBJECT ... },
  "message": { ... MESSAGE_OBJECT ... }
}

WhatsappID - идентификатор Whatsapp в сервисе
async - управление синхронностью запроса
recipient - объект получателя сообщения
message - объект сообщения

Recipient - объект получателя сообщения

Получатель сообщения в Whatsapp может задаваться несколькими способами

1. по идентификатору Whatsapp. Система идентификаторов Whatsapp несложная, если это контакт, то идентификатор равен номеру контакта, к которому прибавляется @c.us, например 79991112233@c.us, если же мы имеем дело с группой, то идентификатор состоит из внутреннего номера группы с @g.us на конце, т.е. AA11223344@g.us

В случае задания получателя по идентификатору, объект получателя будет иметь следующий вид:

//для контакта
"recipient" : {
  "id" : "79991112233@c.us"
}

//для группы
"recipient" : {
  "id" : "AA11223344@g.us"
}

2. По номеру и типу. Тип может иметь значение contact или group. Значение по умолчанию - contact.

"recipient" : {
  "type" : "contact",
  "number" : "79991112233"
}

//равнозначно

"recipient" : {
  "number" : "79991112233"
}

//или для группы

"recipient" : {
  "type" : "group",
  "number" : "AA11223344"
}

Message - объект сообщения

Объект сообщения состоит из следующих полей:

"message" : {
  "type" : "<string>",
  "body" : "<string>",
  "quote" : "<string>",
  "media" : { ... MEDIA_OBJECT ...}
}

За тип сообщения отвечает поле type объекта сообщения. Сообщения могут быть следующих типов:

В зависимости от типа изменяются обязательные поля в объекте. По умолчанию, поле type принимает значение «text». Поле quote - является необязательным и может быть указано в любом типе сообщения. В данном поле указывается длинный идентификатор сообщения, который приходит в объекте ответа на отправку в синхронном варианте или на вебхук в асинхронном варианте отправки или как входящее сообщение. При его указании, отправленное сообщение будет помечено как ответ на сообщение, идентификатор которого указан

"message" : {
  ...
  "quote" : "true_79991112233@c.us_3EB0EBC34954F8976AA6"
  ...
}

Text - текстовое сообщение

Message с типом «text» является обычным текстовым сообщением. Поле type не указано или равно «text». Поле body является обязательным.

"message" : {
  "body" : "Hello world!"
}

Изображение, стикер, документ или голосовое сообщение

При указании одного из типов медиа в сообщении, поле body становится не обязательным, а поле media - обязательным. В поле body также можно указать текст, который появится в сообщении с медиа-файлом.

Media - объект медиа-файла

Объект медиа-файла состоит из 3 полей:

"media" : {
  "mimetype" : "<mimetype_list_value>",
  "data" : "<base64_encoded_data>",
  "filename" : "<string>"
}

mimetype - значение из списка доступных Mimetype
data - тело файла, закодированное в base64
filename - имя файла, как оно будет отображаться у получателя. Используется при типе сообщения doc и image

Голосовое сообщение должно быть в формате ogg

Пример объекта отправки сообщения

Текстовое сообщение

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": {
    "number" : "79999999999"
  },
  "message": {
    "body" : "Привет, мир!"
  }
}

Медиа сообщение с изображением

{
  "WhatsappID": "YOUR_WHATSAPP_ID",
  "async": false,
  "recipient": {
    "type" : "group",
    "number" : "AA11223344"
  },
  "message": {
    "type" : "image",
    "body" : "Вам прилетела птичка!",
    "quote" : "true_79991112233@c.us_3EB0EBC34954F8976AA6",
    "media" : {
       "mimetype" : "image/png",
       "data" : "iVBORw0KG....5CYII=",
       "filename" : "bird.png"
    }
  }
}

Список доступных Mimetype

application/ogg
application/pdf
application/zip
application/gzip
application/msword
audio/mp4
audio/aac
audio/mpeg
audio/ogg
audio/webm
image/gif
image/jpeg
image/pjpeg
image/png
image/svg+xml
image/tiff
image/webp
video/mpeg
video/mp4
video/ogg
video/quicktime
video/webm
video/x-ms-wmv
video/x-flv
application/vnd.ms-excel
application/vnd.ms-powerpoint
application/msword

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

anonymous@undisclosed.example.com (Anonymous) — 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 - попытка открыть окно с идентификатором несуществующей или закрытой сессии.

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

anonymous@undisclosed.example.com (Anonymous) — Tue, 07 Feb 2023 12:48:54 +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": "Удаляется",
        "pushname": "Vasya",
        "wid": "79991234567@c.us",
    }
}

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

anonymous@undisclosed.example.com (Anonymous) — Tue, 07 Feb 2023 12:46:53 +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": "Авторизация",
        "pushname": null,
        "wid": null,
        "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": "Работает",
        "pushname": "Vasya",
        "wid": "79991234567@c.us",
        "qr_link": ""
     },
  ]
}

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

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

anonymous@undisclosed.example.com (Anonymous) — Tue, 07 Feb 2023 12:47:31 +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": "Работает",
     "pushname": "Vasya",
     "wid": "79991234567@c.us",
  }
}

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

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

anonymous@undisclosed.example.com (Anonymous) — 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"
}

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

anonymous@undisclosed.example.com (Anonymous) — 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);
?>