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

`POST /v1/chats/dialog-id`

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

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

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `externalId` | string | да | Внешний идентификатор — одна из форм ниже. Пробелы по краям отбрасываются |

| Форма `externalId` | Что делает эндпоинт |
|--------------------|---------------------|
| `chatN`, например `chat42` | Возвращает то же значение, не проверяя, что чат существует |
| ID пользователя из [списка пользователей](/docs/entities/users/list), например `5` | Возвращает личный диалог с этим пользователем. Если диалога ещё не было, создаёт его |
| `crm\|<TYPE>\|<ID>`, например `crm\|DEAL\|15` | Возвращает чат CRM-сущности. Если его нет, создаёт и делает вызывающего участником |
| `sgN`, например `sg3` | Возвращает чат рабочей группы. Если его нет, создаёт |

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

## Примеры

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

```bash
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-приложение

```bash
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` | Ключ только для чтения: вызов может создать чат — см. [права доступа](/docs/access-rights) |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**CRM-чат создаётся и для несуществующей сущности.** На тестовом портале запрос с `crm|DEAL|<ID>` сделки, которой нет, создал чат и сделал вызывающего его участником. Удалить такой чат [удалением чата](/docs/chats/management/delete) нельзя — ответ `403 BITRIX_ACCESS_DENIED`. Проверяйте, что сущность существует, до вызова.

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

**Найти чат CRM-сущности без создания.** Если чат нужен, только когда он уже есть, используйте [поиск чата CRM-сущности](/docs/chats/discovery/find): для сущности без чата он отвечает `data: null` и ничего не создаёт.

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

- [Поиск чатов](/docs/chats/discovery)
- [Найти чат CRM-сущности](/docs/chats/discovery/find)
- [Информация о диалоге](/docs/chats/discovery/get)