Как получать сообщения через WebHook

Webhook позволяет получать входящие и исходящие сообщения из WAMM.chat на ваш сервер в реальном времени, без периодических запросов к API. WAMM.chat отправляет на указанный вами URL HTTP POST с телом в формате JSON при появлении или отправке сообщения в подключённом канале. Это удобно для чат-ботов, CRM и любых систем, которым нужна мгновенная реакция на переписку.

Настройка выполняется отдельно для каждого канала: Настройки → выберите канал связи → вкладка «Данные и API» → Webhook URL. URL должен быть доступен из интернета по HTTPS или HTTP. Если webhook временно недоступен, сообщения можно догрузить методами Получение сообщений или Получение сообщений по номеру телефона. Статусы доставки и прочтения приходят отдельными событиями.

Поддерживаемые мессенджеры

Уведомления о сообщениях через Webhook доступны для всех каналов: WhatsApp, MAX Personal, Telegram Personal, Telegram Bot..

Настройка Webhook URL

Укажите публичный адрес обработчика на вашем сервере, например:

https://example.com/wamm/webhook.php

На этот адрес WAMM.chat будет отправлять POST-запросы. Обработка на вашей стороне не должна занимать более 10 секунд (таймаут на стороне WAMM.chat). События доставляются последовательно, в порядке поступления.

Пример запроса

WAMM.chat выполняет запрос к вашему серверу:

POST https://example.com/wamm/webhook.php
Content-Type: application/json

Тело запроса (JSON):

{
    "tip": "msg",
    "msg_data": {
        "msg_id": 1234567,
        "from_api": 0,
        "from_me": 0,
        "phone_acc": "79001112233",
        "phone": "79001234567",
        "phone_real": "",
        "chat_name": "Иван Петров",
        "tip_msg": "textMessage",
        "msg_text": "Добрый день, интересует ваше предложение",
        "msg_link": null,
        "date_ins": "2023-05-24 12:35:29",
        "state": "received",
        "qoute_msg_id": null
    }
}

Для исходящих сообщений (в том числе отправленных через API) поле from_me равно 1, для входящих — 0. Поле from_api равно 1, если сообщение отправлено через API WAMM.chat.

Параметры запроса (поля JSON)

Поле	Тип	Обязательный	Описание
tip	string	Да	Тип события. Для сообщений всегда `msg`
msg_id	integer	Да	Уникальный идентификатор сообщения в WAMM.chat
from_me	integer	Да	Направление: `0` — входящее, `1` — исходящее
from_api	integer	Да	Отправлено через API: `0` — нет, `1` — да
phone_acc	string	Да	Номер или идентификатор канала, подключённого к WAMM.chat
phone	string	Да	Номер телефона контакта или ID чата (для Telegram и MAX — часто ID чата)
phone_real	string	Нет	Телефон или никнейм контакта, если известен (для Telegram/MAX, когда `phone` — ID чата)
chat_name	string	Нет	Имя контакта или название чата
tip_msg	string	Да	Тип содержимого: `textMessage`, `documentMessage`, `imageMessage`, `audioMessage`, `videoMessage`, `location`, `file_link`, `contactMessage` и др.
msg_text	string	Нет	Текст сообщения (для файлов может быть пустым или служебным)
msg_link	string	Нет	Ссылка на файл или имя файла, если применимо
date_ins	string	Да	Дата и время сообщения (`YYYY-MM-DD HH:MM:SS`, часовой пояс — Europe/Moscow)
state	string	Да	Статус в момент события: `received`, `sent`, `sending` и др.
qoute_msg_id	string / integer	Нет	ID цитируемого сообщения в мессенджере, если сообщение — ответ (имя поля в JSON именно `qoute_msg_id`)

Ответ при успехе

Ваш обработчик должен ответить HTTP-кодом 200, 202 или 204. Тело ответа может быть любым (например, OK). Без успешного ответа WAMM.chat считает доставку неуспешной и повторит отправку.

HTTP/1.1 200 OK
Content-Type: text/plain

OK

Возможные ошибки

Ситуация	Поведение WAMM.chat
Ответ не 200 / 202 / 204	Повторная отправка того же события (до 3 попыток с увеличивающимся интервалом)
Таймаут или недоступность URL (> 10 сек, сеть, DNS)	Повторная отправка; в настройках канала может фиксироваться время последней ошибки webhook
Webhook URL не задан или канал не на связи	События не отправляются; используйте msg_get_last / msg_get
Некорректный JSON в теле ответа вашего сервера	Не влияет на приём webhook; важен только HTTP-код ответа

Примеры использования

<?php
// webhook.php — обработчик Webhook WAMM.chat (события tip = msg)

$input = file_get_contents('php://input');
$data  = json_decode($input, true);

if (!is_array($data)) {
    http_response_code(400);
    exit('Invalid JSON');
}

// Сразу подтверждаем приём (до долгой обработки)
http_response_code(200);
header('Content-Type: text/plain');
echo 'OK';

if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();
}

if (($data['tip'] ?? '') !== 'msg' || empty($data['msg_data'])) {
    exit;
}

$msg = $data['msg_data'];

// Пример: только входящие от клиента
if ((int)($msg['from_me'] ?? 0) === 0) {
    $phone   = $msg['phone'] ?? '';
    $text    = $msg['msg_text'] ?? '';
    $msgId   = $msg['msg_id'] ?? 0;
    // saveIncomingMessage($phone, $text, $msgId);
}

// Пример: ответ через API (нужен токен канала)
// if (mb_strtolower($text) === 'привет') {
//     file_get_contents('https://wamm.chat/api2/msg_to/YOUR_TOKEN/?phone=' . urlencode($phone) . '&text=' . urlencode('Здравствуйте!'));
// }

Безопасность: для дополнительной защиты можно ограничить доступ к обработчику по IP-адресам серверов WAMM.chat (см. раздел Интеграция API). Рекомендуется логировать сырые тела запросов на этапе отладки и обрабатывать повторные доставки идемпотентно по msg_id.

Получение сообщений через WebHook - API