Вебхуки

Вебхук — это мостик между Chato и вашей программой: сайтом, складом, 1С, CRM. Он работает в обе стороны, и стороны независимы: можно включить только одну.

• Исходящий — Chato сам стучится к вам, когда что-то произошло, и спрашивает вас во время разговора с клиентом.
• Входящий — ваша программа стучится в Chato: пишет клиенту, зовёт менеджера, правит карточку, читает переписку.

Настраивается в кабинете: ИИ-ассистент → Подключения → Вебхук.

Исходящий: события на ваш адрес

Впишите адрес (только https), при желании секрет для подписи и свои заголовки — обычно это ключ доступа к вашей программе. Затем отметьте, о чём вам сообщать:

Chato отправляет POST с телом такого вида:

{
  "workspaceId": "cmr4sk0ya0001o701hl7ghbqk",
  "event": "message.received",
  "sentAt": "2026-09-08T10:00:00.000Z",
  "data": {
    "conversationId": "cmt9x1a2b0003o701abcd1234",
    "channelId": "cmt9x0zzz0001o701wxyz9876",
    "messageId": "cmt9x2c3d0005o701efgh5678",
    "direction": "INBOUND",
    "type": "TEXT",
    "text": "Здравствуйте, заказ готов?",
    "sentAt": "2026-09-08T10:00:00.000Z",
    "isFirstMessage": false
  }
}

Отвечайте кодом 200 — тело ответа Chato не разбирает. Если ваш сервер молчит или отвечает ошибкой, разговор с клиентом это не задерживает: событие просто не доставлено, запись об этом остаётся в наших логах.

Подпись запроса

Если задан секрет, Chato кладёт в заголовок x-chato-signature HMAC-SHA256 от тела запроса, шестнадцатеричной строкой. Проверьте её у себя — так вы отличите наш запрос от чужого:

const crypto = require('node:crypto');
const expected = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = expected === req.headers['x-chato-signature'];

Считайте подпись по сырому телу запроса, до разбора JSON: пересобранный объект даёт другую строку байтов, и подпись не сойдётся.

Вызов вашей программы из разговора

Тот же адрес используется, когда ассистент на шаге «Вызвать функцию» спрашивает вашу программу — «есть ли красный в 42-м размере». Тело: workspaceId, conversationId, sentAt и data с тем, что собрал ассистент. Что вы ответите — то он и скажет клиенту своими словами, поэтому отвечайте коротким понятным JSON.

Входящая ссылка: ваша программа действует в диалоге

Нажмите Создать ссылку и передайте её программисту. Она выглядит так:

POST https://chato.kz/api/v1/ai-assistant/inbound/ВАШ_КЛЮЧ
Content-Type: application/json

Диалог указывается либо своим conversationId, либо телефоном клиента: номер принимается в любом виде — +7 771 525 89 15, 87715258915.

Написать клиенту

curl -X POST https://chato.kz/api/v1/ai-assistant/inbound/ВАШ_КЛЮЧ \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+7 771 525 89 15","text":"Заказ собран, ждём вас до 19:00"}'

Ответ: {"status":"sent","conversationId":"..."}.

Приложить файл

{
  "phone": "77715258915",
  "text": "Ваш счёт",
  "fileUrl": "https://ваш-сервис.kz/schet-2026-09.pdf",
  "fileName": "Счёт за сентябрь.pdf"
}

Файл берётся по ссылке (только https, до 20 МБ) и уходит клиенту вложением. text при этом необязателен.

Написать первым

Если диалога с этим человеком ещё нет, добавьте channelId — из какого канала писать:

{ "phone": "77715258915", "channelId": "cmt9x0zzz0001o701wxyz9876", "text": "Здравствуйте!" }

Без channelId незнакомому номеру ничего не уходит — иначе утёкшая ссылка превратилась бы в рассылку.

Остальные действия

Все они отправляются на тот же адрес, отличается только поле action.

Пояснения к полям: text — текст (для note это пометка, для handoff — причина, необязательна); contact — объект { name, phone }, меняется только присланное; limit — от 1 до 100, по умолчанию 20; status — OPEN, WAITING, IN_PROGRESS или CLOSED. После reopen ассистент снова отвечает в диалоге.

Пример — передать диалог человеку:

{ "action": "handoff", "conversationId": "cmt9x1a2b0003o701abcd1234", "text": "клиент просит менеджера" }

Пример — узнать, кто это и что с диалогом:

{ "action": "contact.get", "phone": "77715258915" }

{
  "status": "ok",
  "conversationId": "cmt9x1a2b0003o701abcd1234",
  "contact": { "id": "...", "name": "Асем", "phone": "77715258915", "username": null },
  "conversation": { "id": "...", "status": "OPEN", "channelId": "...", "unreadCount": 2 }
}

conversations.list — единственное действие, которому диалог не нужен: им как раз находят нужный, когда идентификатора нет.

Что вернётся при ошибке

Ключ всегда работает только в пределах вашей компании: чужой conversationId в теле запроса ничего не даст.

Сделки и вебхуки CRM

Для своей CRM есть отдельные адреса вебхуков: с выбором событий сделок (deal.created, deal.won, task.completed и другие), подписью HMAC-SHA256 с меткой времени, повторами при ошибках, журналом доставок и кнопкой «Отправить ещё раз». Там же — ключи открытого API с правами. Всё это описано в статье Открытый API сделок и вебхуки CRM; адрес ассистента, описанный выше, продолжает работать как раньше.