Для AI-агентов: markdown этой страницы — /docs-content/openlines/crm/lead.md индекс документации — /llms.txt

Создать лид из обращения

POST /v1/openlines/dialogs/:chatId/lead

Создаёт лид в CRM по диалогу открытой линии и возвращает карточку CRM, к которой диалог привязан после вызова. Если к диалогу уже привязана карточка CRM, новый лид не создаётся и приходит существующая привязка.

Параметры

Параметр Тип Обяз. Описание
ПараметрchatId (path) Типnumber Обяз.да ОписаниеИдентификатор чата открытой линии — положительное целое без префикса chat. Список: поле chatId в ответе POST /v1/openlines/sessions/search

Тело запроса пустое.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/dialogs/123/lead \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.tech/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
if (data.leadId === null) {
  console.log(`Диалог уже привязан: ${data.crmEntityType} ${data.crmEntityId}`)
} else {
  console.log('Лид:', data.leadId)
}

JavaScript — OAuth-приложение

javascript 
const chatId = 123
const res = await fetch(`https://vibecode.bitrix24.tech/v1/openlines/dialogs/${chatId}/lead`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue, когда привязка диалога прочитана после вызова
Полеdata.chatId Типnumber ОписаниеИдентификатор чата из запроса
Полеdata.crmEntityType Типstring ОписаниеТип карточки CRM, к которой привязан диалог: lead, deal, company или contact
Полеdata.crmEntityId Типnumber ОписаниеID карточки CRM, к которой привязан диалог
Полеdata.leadId Типnumber | null ОписаниеID лида, когда диалог привязан к лиду. null, когда диалог привязан к сделке, компании или контакту

Пример ответа

Диалог привязан к лиду:

JSON 
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "lead",
    "crmEntityId": 42,
    "leadId": 42
  }
}

К диалогу уже была привязана сделка:

JSON 
{
  "success": true,
  "data": {
    "chatId": 123,
    "crmEntityType": "deal",
    "crmEntityId": 42,
    "leadId": null
  }
}

Пример ответа при ошибке

400 — chatId в пути не положительное целое:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_CHAT_ID",
    "message": "chatId must be a positive safe integer"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_JSON_BODY ОписаниеПередано тело запроса, которое не разбирается как JSON. Проверка идёт до разбора chatId в пути
HTTP400 КодINVALID_CHAT_ID ОписаниеchatId в пути не положительное целое, в том числе форма chat123, или число больше 9007199254740991. Битрикс24 не вызывается
HTTP404 КодENTITY_NOT_FOUND ОписаниеБитрикс24 не нашёл чат с таким chatId
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ сотрудника, от имени которого идёт вызов, нет прав на диалог, лид не создан
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеСообщение Bitrix24 refused the dialog: it is absent or inaccessible: Битрикс24 принял вызов, но отказал в чтении привязки диалога. Лид при этом мог быть создан
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал в создании лида, его код приходит в error.b24Code
HTTP502 КодOPENLINE_OPERATOR_FAILED ОписаниеБитрикс24 не подтвердил создание лида либо после вызова не удалось прочитать привязку диалога к CRM. Лид при этом мог быть создан
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа imopenlines
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает только на чтение
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ личного ключа нет доступа к порталу Битрикс24, у ключа приложения не передан токен сессии в Authorization
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит 120 запросов в минуту на портал. Лимит делится между репликами платформы, поэтому код может прийти раньше 120-го запроса. Действующее значение для ключа — в заголовке x-ratelimit-limit, остаток — в x-ratelimit-remaining
HTTP429 КодRATE_LIMITED ОписаниеБитрикс24 отклонил вызов по лимиту частоты запросов к порталу. В ответе приходит заголовок Retry-After
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или соединение с ним оборвалось до полного ответа
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 принял вызов, но не ответил за отведённое время. Лид при этом мог быть создан

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Повтор после сбоя безопасен. После 502 OPENLINE_OPERATOR_FAILED, 503 BITRIX_TIMEOUT и 403 BITRIX_ACCESS_DENIED вызов можно повторить: если первый вызов успел создать лид, повторный второго лида не создаст и вернёт уже существующую привязку.

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