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

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

Этот подход, часто называемый «обратным API» или «push-API», кардинально отличается от традиционного опроса (polling), когда ваш сервер постоянно обращается к API сервера с вопросами: «Есть новые сообщения? А сейчас? А теперь?». Вебхуки экономят вычислительные ресурсы, трафик и обеспечивают мгновенную реакцию.

Настройка Webhook URL

Для получения сообщений через Webhook необходимо указать URL вашего сервера в разделе Настройки > Выбрать канал связи > Вкладка "Данные и API" > Webhook URL. На этот URL будут отправляться POST-запросы с данными о входящих и исходящих сообщениях в формате JSON.

Ваш URL обработчика Webhook должен быть доступен в Интернет и отвечать HTTP 200 на POST-запросы. Длительность обработки запроса на вашей стороне не должна превышать 10 секунд. Сообщения по Webhook отправляются последовательно, соблюдая порядок событий. Если ваш сервер не отвечает или возвращает код ошибки, WAMM.chat будет повторять запросы еще 5 раз, увеличивая интервал между запросами.

Формат данных сообщения

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

Описание полей сообщения

Формат данных статуса сообщения

{
    "tip": "msg_state",
    "msg_data": {
        "msg_id": "1234567",
        "date_upd": "2023-05-24 22:46:03",
        "state": "delivered"
    }
}

Описание полей статуса сообщения

Пример обработки webhook на PHP

// Получаем данные из POST запроса
$input = file_get_contents('php://input');
$data = json_decode($input, true);

// Проверяем, что данные успешно декодированы
if ($data === null) {
    http_response_code(400); // Bad Request
    exit('Invalid JSON data');
}
// Всегда возвращаем статус 200, чтобы WAMM.chat знал, что запрос успешно обработан
header("HTTP/1.0 200 OK");
echo 'OK';

// Отправляем серверу WAMM.chat ответ и уже далее обрабатываем запрос сколько угодно продолжительно
fastcgi_finish_request();

// Лог для отладки (опционально)
file_put_contents('webhook_log.txt', date('Y-m-d H:i:s') . " - " . $input . PHP_EOL, FILE_APPEND);

// Обрабатываем сообщение
if (isset($data['tip'])) {
    switch ($data['tip']) {
        case 'msg':
            // Обработка нового сообщения
            processChatMessage($data['msg_data']);
            break;
        case 'msg_state':
            // Обработка статуса сообщения
            processMessageStatus($data['msg_data']);
            break;
        default:
            // Неизвестный тип события
            logUnknownEvent($data);
            break;
    }
}

// Функция обработки нового сообщения
function processChatMessage($message) {
    // Проверяем, входящее или исходящее сообщение
    if ($message['from_me'] == 0) {
        // Входящее сообщение (от клиента)
        $phone = $message['phone'];
        $text = $message['msg_text'];
        $msgId = $message['msg_id'];
        
        // Пример: сохранение в базу данных
        // saveMessageToDatabase($phone, $text, $msgId, 'incoming');
        
        // Пример: автоматический ответ на определенные сообщения
        if (strtolower($text) === 'привет') {
            // Отправка автоматического ответа через API WAMM.chat
            // sendReply($phone, 'Здравствуйте! Чем могу помочь?');
        }
    } else {
        // Исходящее сообщение (от оператора)
        // saveMessageToDatabase($message['phone'], $message['msg_text'], $message['msg_id'], 'outgoing');
    }
}

// Функция обработки статуса сообщения
function processMessageStatus($status) {
    $msgId = $status['msg_id'];
    $state = $status['state'];
    $dateUpd = $status['date_upd'];
    
    // Пример: обновление статуса сообщения в базе данных
    // updateMessageStatus($msgId, $state, $dateUpd);
    
    // Логирование изменения статуса
    $logMessage = "Сообщение ID: $msgId, новый статус: $state, дата обновления: $dateUpd";
    // logStatus($logMessage);
}

// Функция для логирования неизвестных событий
function logUnknownEvent($data) {
    // Записываем неизвестное событие в журнал для анализа
    // logToFile('unknown_events.log', json_encode($data));
}

Советы по реализации

Примечания