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

справочник API · v1

Заявки

Заявки, которые собрали AI-сотрудники во всех каналах, и создание заявок из ваших систем.

Ресурс Lead

ПолеОписание
idstringId заявки.
agentIdstring | nullAI-сотрудник, который собрал заявку.
namestring | nullИмя клиента.
phonestring | nullТелефон клиента.
emailstring | nullEmail клиента.
messagestring | nullЧто просил клиент.
statusstringОбработка: новая, связались, закрыта. · одно из: NEW, CONTACTED, CLOSED
stagestringСтадия воронки: новая, квалифицирована, в CRM, сделка, отказ. · одно из: NEW, QUALIFIED, IN_CRM, WON, LOST
sourcestringОткуда пришла, например chat (диалог AI-сотрудника) или api.
typestring | nullТип заявки (консультация, заказ, запись…), если сотрудник его определил.
topicstring | nullТема обращения.
scoreinteger | nullОценка горячести 0–100. · 0–100
createdAtstring (date-time)Когда создана.

Список заявок

get/api/v1/leads

Заявки компании, новые первыми. Заявки, скрытые до оплаты тарифа, не отдаются.

Право ключа: Заявки — чтение · leads:read

curl "https://app.chatneuron.ru/api/v1/leads?limit=50&since=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer cn_live_…"

Параметры запроса

ПараметрОписание
limitintegerСколько записей на странице. · 1–100 · по умолчанию 50
sincestring (date-time)Брать записи с этой даты (ISO 8601).
cursorstringnextCursor из прошлого ответа.

Ответ 200

Страница заявок.

JSON
{
  "data": [
    {
      "id": "cmv8k2x1q0001abcd",
      "agentId": "cmu3f9z7k0002efgh",
      "name": "Анна",
      "phone": "+79991234567",
      "email": null,
      "message": "Нужна консультация по доставке",
      "status": "NEW",
      "stage": "QUALIFIED",
      "source": "chat",
      "type": null,
      "topic": "Доставка",
      "score": 72,
      "createdAt": "2026-10-27T09:15:02.114Z"
    }
  ],
  "nextCursor": "cmv8k2x1q0001abcd"
}

Ошибки

СтатусcodeКогда
400invalid_requestНекорректные параметры или тело запроса.
401unauthorizedНет ключа, ключ неверный или отозван.
429rate_limitedБольше 120 запросов в минуту. Повторите через Retry-After секунд.

Создать заявку

post/api/v1/leads

Новая заявка из вашей системы. Доставляется как любая другая: в CRM, Telegram, на почту и в исходящие вебхуки (lead.created). Нужен ключ с правом записи. Обязателен телефон или email.

Право ключа: Заявки — создание и изменение · leads:write

curl -X POST https://app.chatneuron.ru/api/v1/leads \
  -H "Authorization: Bearer cn_live_…" \
  -H "Idempotency-Key: 6f1c2b9e-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"name":"Анна","phone":"+79991234567","message":"Заявка с сайта","topic":"Доставка"}'

Параметры запроса

ПараметрОписание
Idempotency-KeystringЛюбая ваша строка до 255 символов (например, UUID). Повтор с тем же ключом в течение 24 ч вернёт прежний ответ с заголовком Idempotent-Replayed: true и ничего не создаст заново. · до 255 символов

Тело запроса

ПолеОписание
namestringИмя клиента. · до 200 символов
phonestringТелефон. · до 40 символов
emailstring (email)Email. · до 200 символов
messagestringТекст заявки. · до 5000 символов
topicstringТема. · до 500 символов
agentIdstringAI-сотрудник, к которому отнести заявку. · до 40 символов

Ответ 201

Заявка создана. Схема — LeadCreated.

JSON
{
  "data": {
    "id": "cmv8k2x1q0001abcd",
    "locked": false
  }
}

Ошибки

СтатусcodeКогда
400invalid_requestНекорректные параметры или тело запроса.
401unauthorizedНет ключа, ключ неверный или отозван.
403forbiddenУ ключа нет нужного права — оно указано в тексте ошибки.
409idempotency_in_progressЗапрос с этим Idempotency-Key ещё выполняется.
422idempotency_mismatchIdempotency-Key уже использован с другим запросом.
429rate_limitedБольше 120 запросов в минуту. Повторите через Retry-After секунд.

Заявка

get/api/v1/leads/{id}

Одна заявка по id. Скрытая до оплаты тарифа отвечает 404, как несуществующая.

Право ключа: Заявки — чтение · leads:read

curl https://app.chatneuron.ru/api/v1/leads/cmv8k2x1q0001abcd \
  -H "Authorization: Bearer cn_live_…"

Параметры запроса

ПараметрОписание
idstring · обязателенId заявки.

Ответ 200

Заявка.

JSON
{
  "data": {
    "id": "cmv8k2x1q0001abcd",
    "agentId": "cmu3f9z7k0002efgh",
    "name": "Анна",
    "phone": "+79991234567",
    "email": null,
    "message": "Нужна консультация по доставке",
    "status": "NEW",
    "stage": "QUALIFIED",
    "source": "chat",
    "type": null,
    "topic": "Доставка",
    "score": 72,
    "createdAt": "2026-10-27T09:15:02.114Z"
  }
}

Ошибки

СтатусcodeКогда
401unauthorizedНет ключа, ключ неверный или отозван.
404not_foundНет такой записи в компании ключа.
429rate_limitedБольше 120 запросов в минуту. Повторите через Retry-After секунд.

Изменить заявку

patch/api/v1/leads/{id}

Обработка (status) и стадия воронки (stage) — например, когда сделку закрыли в вашей CRM. Нужен ключ с правом записи. Изменение уходит в исходящие вебхуки (lead.updated); без изменений событие не отправляется.

Право ключа: Заявки — создание и изменение · leads:write

curl -X PATCH https://app.chatneuron.ru/api/v1/leads/cmv8k2x1q0001abcd \
  -H "Authorization: Bearer cn_live_…" \
  -H "Idempotency-Key: 6f1c2b9e-order-1042" \
  -H "Content-Type: application/json" \
  -d '{"stage":"WON"}'

Параметры запроса

ПараметрОписание
idstring · обязателенId заявки.
Idempotency-KeystringЛюбая ваша строка до 255 символов (например, UUID). Повтор с тем же ключом в течение 24 ч вернёт прежний ответ с заголовком Idempotent-Replayed: true и ничего не создаст заново. · до 255 символов

Тело запроса

ПолеОписание
statusstringОбработка: новая, связались, закрыта. · одно из: NEW, CONTACTED, CLOSED
stagestringСтадия воронки. · одно из: NEW, QUALIFIED, IN_CRM, WON, LOST

Ответ 200

Заявка после изменения.

JSON
{
  "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"
  }
}

Ошибки

СтатусcodeКогда
400invalid_requestНекорректные параметры или тело запроса.
401unauthorizedНет ключа, ключ неверный или отозван.
403forbiddenУ ключа нет нужного права — оно указано в тексте ошибки.
404not_foundНет такой записи в компании ключа.
409idempotency_in_progressЗапрос с этим Idempotency-Key ещё выполняется.
422idempotency_mismatchIdempotency-Key уже использован с другим запросом.
429rate_limitedБольше 120 запросов в минуту. Повторите через Retry-After секунд.

Дальше

Общие правила — ключи, лимиты, ошибки, страницы — в обзоре API. Узнавать о событиях сразу, без опроса, — через исходящие вебхуки.