ChatNeuron
Начать бесплатно
Разделы

справочник вебхуков

События

Что приходит POST-запросом на ваш адрес. Тело всегда одной формы: id, event, createdAt и data — у каждого события своя. Подпись и доставка — в обзоре вебхуков.

СобытиеКогда
lead.createdНовая заявка
lead.updatedЗаявка изменилась
dialog.startedНовый диалог с клиентом
dialog.handed_offДиалог передан человеку
dialog.closedДиалог закрыт
message.createdНовое сообщение в диалоге
testПроверка

lead.created

Новая заявка

Заявка появилась в компании: её собрал AI-сотрудник в любом канале или её создали через API.

Поле data

ПолеОписание
idstringId заявки — тот же, что в GET /leads.
agentIdstring | nullAI-сотрудник.
namestring | nullИмя клиента.
phonestring | nullТелефон.
emailstring | nullEmail.
messagestring | nullТекст заявки.
typestring | nullТип заявки.
topicstring | nullТема.
sourcestringОткуда пришла.
scoreinteger | nullОценка горячести 0–100.
createdAtstring (date-time)Когда создана.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "lead.created",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "cmv8k2x1q0001abcd",
    "agentId": "cmu3f9z7k0002efgh",
    "name": "Анна",
    "phone": "+79991234567",
    "email": null,
    "message": "Нужна консультация по доставке",
    "type": null,
    "topic": "Доставка",
    "source": "chat",
    "score": 72,
    "createdAt": "2026-10-27T09:15:02.114Z"
  }
}

lead.updated

Заявка изменилась

У заявки сменилась стадия или статус, поправили контакты — в кабинете, из CRM (сделка выиграна или проиграна) или после оплаты заказа в чате. В data — заявка целиком, как в GET /leads, и changes: что было и что стало.

Поле data

ПолеОписание
idstringId заявки.
agentIdstring | nullAI-сотрудник.
namestring | nullИмя клиента.
phonestring | nullТелефон.
emailstring | nullEmail.
messagestring | nullТекст заявки.
statusstringОбработка — уже новое значение. · одно из: NEW, CONTACTED, CLOSED
stagestringСтадия — уже новое значение. · одно из: NEW, QUALIFIED, IN_CRM, WON, LOST
sourcestringОткуда пришла.
typestring | nullТип заявки.
topicstring | nullТема.
scoreinteger | nullОценка горячести 0–100.
createdAtstring (date-time)Когда создана.
changesobjectЧто поменялось: имя поля → { from, to }. Например { "stage": { "from": "QUALIFIED", "to": "WON" } }.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "lead.updated",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "cmv8k2x1q0001abcd",
    "agentId": "cmu3f9z7k0002efgh",
    "name": "Анна",
    "phone": "+79991234567",
    "email": null,
    "message": "Нужна консультация по доставке",
    "status": "NEW",
    "stage": "WON",
    "source": "chat",
    "type": null,
    "topic": "Доставка",
    "score": 72,
    "createdAt": "2026-10-27T09:15:02.114Z",
    "changes": {
      "stage": {
        "from": "QUALIFIED",
        "to": "WON"
      }
    }
  }
}

dialog.started

Новый диалог с клиентом

Клиент начал новый диалог с AI-сотрудником. Тестовые диалоги из кабинета событие не вызывают.

Поле data

ПолеОписание
idstringId диалога — тот же, что в GET /dialogs.
agentIdstring | nullAI-сотрудник.
channelstringКанал.
topicstring | nullТема, если уже известна.
startedAtstring (date-time)Первое сообщение.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "dialog.started",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "cmv8m4c2r0003ijkl",
    "agentId": "cmu3f9z7k0002efgh",
    "channel": "telegram",
    "topic": null,
    "startedAt": "2026-10-27T09:10:41.000Z"
  }
}

dialog.handed_off

Диалог передан человеку

Клиент попросил живого человека, или AI-сотрудник позвал сотрудника. В summary — краткая выжимка разговора для того, кто подключится.

Поле data

ПолеОписание
idstringId диалога.
agentIdstring | nullAI-сотрудник.
channelstringКанал.
topicstring | nullТема.
summarystring | nullВыжимка разговора для сотрудника.
requestedAtstring (date-time)Когда позвали человека.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "dialog.handed_off",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "cmv8m4c2r0003ijkl",
    "agentId": "cmu3f9z7k0002efgh",
    "channel": "telegram",
    "topic": "Доставка",
    "summary": "Клиент уточняет сроки доставки в Казань, просит менеджера.",
    "requestedAt": "2026-10-27T09:12:30.000Z"
  }
}

dialog.closed

Диалог закрыт

Диалог завершился: 24 часа тишины (silence) или клиент начал новый разговор после передачи человеку. Решён ли вопрос, станет известно позже — поле resolved в GET /dialogs.

Поле data

ПолеОписание
idstringId диалога.
agentIdstring | nullAI-сотрудник.
channelstringКанал.
topicstring | nullТема.
handedOffbooleanПередавался ли человеку.
closeReasonstring | nullПочему закрыт: silence — 24 ч тишины, handoff_ended — новый разговор после передачи человеку. · одно из: silence, handoff_ended, closed, null
startedAtstring (date-time)Первое сообщение.
closedAtstring | null (date-time)Когда закрыт.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "dialog.closed",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "cmv8m4c2r0003ijkl",
    "agentId": "cmu3f9z7k0002efgh",
    "channel": "telegram",
    "topic": "Доставка",
    "handedOff": false,
    "closeReason": "silence",
    "startedAt": "2026-10-27T09:10:41.000Z",
    "closedAt": "2026-10-27T09:46:12.000Z"
  }
}

message.created

Новое сообщение в диалоге

Новая реплика клиента, AI-сотрудника или сотрудника компании. Событий много — подписывайтесь, только если нужна переписка в реальном времени.

Поле data

ПолеОписание
idstringId реплики — тот же, что в GET /dialogs/{id}/messages.
dialogIdstringId диалога.
rolestringКто написал. · одно из: client, ai, operator
textstringТекст.
authorNamestring | nullИмя сотрудника компании — только у operator.
createdAtstring (date-time)Когда отправлена.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "message.created",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "id": "4f7a2c1e-turn-0001",
    "role": "client",
    "text": "Здравствуйте! Сколько доставка в Казань?",
    "authorName": null,
    "createdAt": "2026-10-27T09:10:41.000Z",
    "dialogId": "cmv8m4c2r0003ijkl"
  }
}

test

Проверка

Приходит по кнопке «Проверить» в настройках вебхука. Подписываться на него не нужно.

Поле data

ПолеОписание
messagestringТекст проверки.
Тело запроса
{
  "id": "9b2f6c1e-4a7d-4f0e-9c3b-1d2e3f4a5b6c",
  "event": "test",
  "createdAt": "2026-10-27T09:15:02.114Z",
  "data": {
    "message": "Проверка вебхука ChatNeuron"
  }
}