[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Fdiscovery\u002Fdialog-id":3,"docs-tabs-chats\u002Fdiscovery\u002Fdialog-id":6},{"content":4,"lastmod":5},"## Dialog ID by external identifier\n\n`POST \u002Fv1\u002Fchats\u002Fdialog-id`\n\nReturns the dialog ID as `chatN` for an external identifier: a user ID, a CRM entity, a workgroup or the chat itself. **The method gets or creates a chat:** if the identifier has no chat yet, the endpoint creates one, so it is a `POST` and counts as a write. This is a service method.\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `externalId` | string | yes | The external identifier — one of the forms below. Surrounding spaces are trimmed |\n\n| `externalId` form | What the endpoint does |\n|--------------------|---------------------|\n| `chatN`, for example `chat42` | Returns the same value without checking that the chat exists |\n| A user ID from the [user list](\u002Fdocs\u002Fentities\u002Fusers\u002Flist), for example `5` | Returns the personal dialog with this user. Creates it if there was none |\n| `crm\\|\u003CTYPE>\\|\u003CID>`, for example `crm\\|DEAL\\|15` | Returns the CRM entity chat. If there is none, creates it and makes the caller a member |\n| `sgN`, for example `sg3` | Returns the workgroup chat. Creates it if there is none |\n\nAny other form returns `422 BITRIX_ERROR` with `error.b24Code` set to `CHAT_NOT_FOUND`. Other body fields and query parameters are rejected with `400 INVALID_PARAMS` before any call to Bitrix24.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fdialog-id \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"externalId\": \"crm|DEAL|15\" }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fdialog-id \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"externalId\": \"crm|DEAL|15\" }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fdialog-id', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ externalId: 'crm|DEAL|15' }),\n})\n\nconst { data } = await res.json()\nconsole.log('Dialog:', data.dialogId) \u002F\u002F chat264\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Fdialog-id', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ externalId: 'crm|DEAL|15' }),\n})\n\nconst { data } = await res.json()\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.dialogId` | string | The dialog ID as `chatN` |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"dialogId\": \"chat42\"\n  }\n}\n```\n\n## Error response example\n\n400 — `externalId` was not passed:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_PARAMS\",\n    \"message\": \"Body field `externalId` (chat\u003CN>, a user id, crm|\u003CTYPE>|\u003CID> or sg\u003CN>) is required. Nothing was sent to Bitrix24.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `MISSING_PARAMS` | The `externalId` field is missing. A request without a body lands here too |\n| 400 | `INVALID_PARAMS` | `externalId` is not a string or is empty, or another body field or a query parameter was sent |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned \"not found\". The portal code is in `error.b24Code` |\n| 422 | `BITRIX_ERROR` | Bitrix24 returned an error. The portal code is in `error.b24Code`. `CHAT_NOT_FOUND` — the `externalId` form was not recognized or the chat could not be obtained |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only: the call may create a chat — see [access rights](\u002Fdocs\u002Faccess-rights) |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n\nThe full list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**A CRM chat is created even for a missing entity.** On a test Bitrix24 account a request with `crm|DEAL|\u003CID>` for a deal that does not exist created a chat and made the caller a member. Such a chat cannot be removed by [deleting the chat](\u002Fdocs\u002Fchats\u002Fmanagement\u002Fdelete) — the response is `403 BITRIX_ACCESS_DENIED`. Check that the entity exists before the call.\n\n**A personal dialog comes back as `chatN`.** For a user ID, the response is the personal dialog's `chatN`, not the other user's ID, which other endpoints use to address a personal dialog.\n\n**Find a CRM entity chat without creating one.** If you need the chat only when it already exists, use [finding a CRM entity chat](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Ffind): for an entity without a chat it returns `data: null` and creates nothing.\n\n## See also\n\n- [Chat discovery](\u002Fdocs\u002Fchats\u002Fdiscovery)\n- [Find a CRM entity chat](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Ffind)\n- [Dialog details](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Fget)\n","2026-10-07",{},1794739534400]