Webhook онлайн-чата: события диалогов — в вашу CRM и сценарии

Какие события приходят

• conversation.created — клиент начал новый диалог в любом подключённом канале (или пришла заявка через REST API /forms/lead).

• message.created — пришло новое входящее сообщение клиента с текстом, в том числе первое сообщение нового диалога.

• conversation.closed — диалог отметили решённым или закрыли в инбоксе либо через REST API.

Каждый вебхук получает все три события. Если вам нужно только одно, отфильтруйте по полю event на своей стороне.

Формат запроса

• Метод POST, тело — JSON в UTF-8, заголовок Content-Type: application/json, User-Agent: Monochat-Webhooks/1.0.

• Тело: event (тип события), workspace_id (id проекта), ts (Unix-время в секундах) и data с данными диалога.

• Подпись: заголовок X-Monochat-Signature вида sha256=<hex>. Это HMAC-SHA256 от «сырого» тела запроса, ключ — секрет вебхука.

• Таймаут ответа — 8 секунд. Ответьте любым кодом 2xx. При ошибке (код 4xx/5xx или таймаут) Моночат повторит доставку: всего до 5 попыток — через 30 секунд, 2 минуты, 10 минут и 1 час. Тело и подпись при повторе те же, поэтому обрабатывайте события идемпотентно.

Пошагово

1. 1
   Зарегистрируйтесь и подключите каналы

   Создайте проект в Моночате (тариф Старт — 0 ₽) и подключите нужные каналы: виджет на сайт, Telegram-бота, MAX, ВКонтакте или почту.

2. 2
   Подготовьте адрес-приёмник

   Это может быть ваш сервер, функция в облаке, Apps Script или входящий вебхук в Albato, Make или n8n. Нужен публичный URL, лучше HTTPS.

3. 3
   Добавьте вебхук в Моночате

   Панель → «Интеграции» → «Исходящий webhook» → «Подключить». Вставьте URL, сохраните. Моночат сгенерирует секрет подписи и один раз покажет его с кнопкой «Копировать» — сохраните его у себя. Свой секрет можно задать в разделе «Дополнительно», а потерянный — заменить кнопкой «Новый секрет». Настраивать могут владелец и администраторы проекта.

4. 4
   Отправьте тестовое событие

   Нажмите «Тест» рядом с адресом. Придёт conversation.created с conversation_id = 0 и именем «Тест Моночат» — так можно проверить приёмник без реального клиента.

5. 5
   Проверьте подпись и обработайте событие

   Сверьте X-Monochat-Signature с HMAC вашего секрета (примеры ниже), затем создайте лид, строку в таблице или уведомление. Ссылка на диалог для сотрудников: monochat.ru/dashboard/inbox/{conversation_id}.

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

Поля data для conversation.created и message.created: conversation_id, channel_type (widget, telegram_bot, vk, max, email, avito), status, visitor_id, visitor_name, visitor_email, visitor_phone, message_text, is_new. Email и телефон приходят, только если они известны: телефон сейчас обычно есть у заявок с форм, а у сообщений из мессенджеров это поле, как правило, null.

{
  "event": "conversation.created",
  "workspace_id": 123,
  "ts": 1792141200,
  "data": {
    "conversation_id": 4567,
    "channel_type": "telegram_bot",
    "status": "open",
    "visitor_id": 8910,
    "visitor_name": "Анна",
    "visitor_email": null,
    "visitor_phone": null,
    "message_text": "Здравствуйте! Доставляете в Казань?",
    "is_new": true
  }
}

{
  "event": "conversation.closed",
  "workspace_id": 123,
  "ts": 1792144800,
  "data": {"conversation_id": 4567, "status": "resolved", "channel_type": null}
}

Значения в примере условные. В conversation.closed приходят conversation_id и status, channel_type может быть null.

Как проверить подпись

Считайте HMAC-SHA256 от тела запроса ровно в том виде, в каком оно пришло, до разбора JSON, и сравнивайте строки функцией с постоянным временем сравнения.

import hashlib
import hmac

SECRET = b"ваш-секрет"  # то, что вы указали в поле «Секрет подписи»


def is_from_monochat(raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")


# Flask:
# if not is_from_monochat(request.get_data(), request.headers.get("X-Monochat-Signature")):
#     abort(401)
# event = request.get_json()

const crypto = require("crypto");
const express = require("express");
const app = express();

// Подпись считается по «сырому» телу — не парсите JSON до проверки
app.post("/monochat-hook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.MONOCHAT_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  const got = req.get("X-Monochat-Signature") || "";
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const ev = JSON.parse(req.body.toString("utf8"));
  console.log(ev.event, ev.data.conversation_id);
  res.sendStatus(200);
});

app.listen(3000);

<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('MONOCHAT_WEBHOOK_SECRET'));
$got = $_SERVER['HTTP_X_MONOCHAT_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) {
    http_response_code(401);
    exit;
}
$ev = json_decode($raw, true);
// $ev['event'], $ev['data']['conversation_id'], $ev['data']['message_text']
http_response_code(200);

Секрет показывается один раз — сразу после создания вебхука, с кнопкой «Копировать». Если не сохранили, нажмите «Новый секрет» у вебхука: старый перестанет подходить, новый снова покажется один раз.

Рецепт: заявка из чата — в любую CRM

Ловите conversation.created и создавайте лид или сделку через API своей CRM: имя — visitor_name, текст обращения — message_text, канал — channel_type, в комментарий — ссылку на диалог. Так подключаются amoCRM, Мегаплан, 1С, самописные CRM и всё, у чего есть HTTP API.

Для Битрикс24 и RetailCRM писать код не нужно: в Моночате есть готовые коннекторы (лид или клиент со ссылкой на диалог). Они работают на тарифах Бизнес (1 990 ₽/мес или 1 390 ₽/мес при оплате за год), Про и Команда.

Рецепт: Google Таблицы, Albato, Make, n8n

У Моночата нет отдельного приложения в каталогах Albato, Make или n8n. Используется их универсальный приёмник: в Make — модуль Webhooks → Custom webhook, в n8n — нода Webhook с методом POST, в Albato — входящий вебхук. Скопируйте выданный URL в Моночат, отправьте «Тест», и сервис увидит структуру полей. Дальше это обычный сценарий: строка в таблицу, сделка в CRM, письмо, задача.

Google Таблица без посредников: создайте в таблице Apps Script, опубликуйте его как веб-приложение и вставьте URL /exec в вебхук. Apps Script не видит заголовков запроса, поэтому проверить подпись здесь не получится — не публикуйте этот URL. На тарифе Бизнес и выше есть и готовый коннектор Google Sheets: строка в таблицу при новом диалоге.

function doPost(e) {
  var ev = JSON.parse(e.postData.contents);
  if (ev.event !== "conversation.created") {
    return ContentService.createTextOutput("skip");
  }
  var d = ev.data;
  SpreadsheetApp.getActiveSpreadsheet().getSheets()[0].appendRow([
    new Date(ev.ts * 1000), d.channel_type, d.visitor_name, d.visitor_email || "",
    d.message_text || "", "https://monochat.ru/dashboard/inbox/" + d.conversation_id
  ]);
  return ContentService.createTextOutput("ok");
}

Рецепт: уведомление о новом диалоге в Telegram-группу

Если операторам достаточно личных уведомлений, вебхук не нужен: в разделе «Уведомления» каждый сотрудник подключает Telegram и получает сообщения о новых входящих. Вебхук нужен, чтобы писать в общий чат отдела: приёмник получает conversation.created и вызывает метод sendMessage Telegram Bot API от имени вашего бота. То же можно собрать без кода в n8n или Make.

import os
import requests  # pip install requests

BOT = os.environ["TG_BOT_TOKEN"]      # токен вашего бота от @BotFather
CHAT = os.environ["TG_CHAT_ID"]       # id группы, куда бот добавлен


def notify(ev: dict) -> None:
    if ev["event"] != "conversation.created":
        return
    d = ev["data"]
    text = (f"Новый диалог ({d['channel_type']}): {d.get('visitor_name') or 'Клиент'}\n"
            f"{d.get('message_text') or ''}\n"
            f"https://monochat.ru/dashboard/inbox/{d['conversation_id']}")
    requests.post(f"https://api.telegram.org/bot{BOT}/sendMessage",
                  json={"chat_id": CHAT, "text": text}, timeout=5)

Чего вебхук не делает — честно

• Не отправляет ответы операторов и ИИ, назначения, теги и вложения — только три события выше.

• Повторяет доставку не бесконечно: после 5 неудачных попыток (последняя — примерно через 1 ч 12 мин) событие помечается ошибкой. В «Интеграциях» есть журнал последних 20 доставок со статусом и HTTP-кодом и кнопка «Повторить»; для полной сверки используйте REST API.

• Не принимает команды обратно: ответить клиенту в канал через вебхук или REST API пока нельзя, ответы пишутся в инбоксе Моночата.

Вебхук, REST API или готовый коннектор

Можно сочетать: коннектор создаёт лид, вебхук шлёт уведомления, а REST API помогает сверять данные.

Полезные ссылки

• Документация: REST API и вебхуки
• REST API Моночата
• Готовый коннектор Битрикс24
• Готовый коннектор RetailCRM
• Моночат и amoCRM
• MAX + amoCRM через вебхук
• Глоссарий: что такое webhook
• Тарифы Моночата

Ещё по теме

Смотрите также

• Все каналы
• CRM-интеграции
• Документация
• Для разработчиков
• MAX для бизнеса