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

ID диалога по внешнему идентификатору

POST /v1/chats/dialog-id

Возвращает ID диалога в виде chatN для внешнего идентификатора: ID пользователя, CRM-сущности, рабочей группы или самого чата. Метод получает или создаёт: если чата для идентификатора ещё нет, эндпоинт его создаёт, поэтому он — POST и считается изменяющим. Метод служебный.

Поля запроса (body)

Поле Тип Обяз. Описание
externalId string да Внешний идентификатор — одна из форм ниже. Пробелы по краям отбрасываются
Форма externalId Что делает эндпоинт
chatN, например chat42 Возвращает то же значение, не проверяя, что чат существует
ID пользователя из списка пользователей, например 5 Возвращает личный диалог с этим пользователем. Если диалога ещё не было, создаёт его
crm|<TYPE>|<ID>, например crm|DEAL|15 Возвращает чат CRM-сущности. Если его нет, создаёт и делает вызывающего участником
sgN, например sg3 Возвращает чат рабочей группы. Если его нет, создаёт

Другая форма — 422 BITRIX_ERROR с error.b24Code CHAT_NOT_FOUND. Другие поля тела и параметры строки запроса отклоняются с 400 INVALID_PARAMS до обращения к Битрикс24.

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/chats/dialog-id \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "crm|DEAL|15" }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/chats/dialog-id \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "crm|DEAL|15" }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/dialog-id', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ externalId: 'crm|DEAL|15' }),
})

const { data } = await res.json()
console.log('Диалог:', data.dialogId) // chat264

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/dialog-id', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ externalId: 'crm|DEAL|15' }),
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.dialogId string ID диалога в виде chatN

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

JSON 
{
  "success": true,
  "data": {
    "dialogId": "chat42"
  }
}

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

400 — не передан externalId:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Body field `externalId` (chat<N>, a user id, crm|<TYPE>|<ID> or sg<N>) is required. Nothing was sent to Bitrix24."
  }
}

Ошибки

HTTP Код Описание
400 MISSING_PARAMS Нет поля externalId. Сюда же приходит запрос без тела
400 INVALID_PARAMS externalId не строка или пустой, передано другое поле тела или параметр строки запроса
404 ENTITY_NOT_FOUND Битрикс24 вернул «не найдено». Код портала — в error.b24Code
422 BITRIX_ERROR Битрикс24 вернул ошибку. Код портала — в error.b24Code. CHAT_NOT_FOUND — форма externalId не распознана или чат получить не удалось
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения: вызов может создать чат — см. права доступа
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24

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

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

CRM-чат создаётся и для несуществующей сущности. На тестовом портале запрос с crm|DEAL|<ID> сделки, которой нет, создал чат и сделал вызывающего его участником. Удалить такой чат удалением чата нельзя — ответ 403 BITRIX_ACCESS_DENIED. Проверяйте, что сущность существует, до вызова.

Личный диалог приходит как chatN. Для ID пользователя ответ — chatN личного диалога, а не ID собеседника, которым личный диалог адресуют остальные эндпоинты.

Найти чат CRM-сущности без создания. Если чат нужен, только когда он уже есть, используйте поиск чата CRM-сущности: для сущности без чата он отвечает data: null и ничего не создаёт.

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