For AI agents: markdown of this page — /docs-content-en/chats/discovery/dialog-id.md documentation index — /llms.txt

Dialog ID by external identifier

POST /v1/chats/dialog-id

Returns 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.

Request fields (body)

Field Type Required Description
FieldexternalId Typestring Requiredyes DescriptionThe external identifier — one of the forms below. Surrounding spaces are trimmed
externalId form What the endpoint does
externalId formchatN, for example chat42 What the endpoint doesReturns the same value without checking that the chat exists
externalId formA user ID from the user list, for example 5 What the endpoint doesReturns the personal dialog with this user. Creates it if there was none
externalId formcrm|<TYPE>|<ID>, for example crm|DEAL|15 What the endpoint doesReturns the CRM entity chat. If there is none, creates it and makes the caller a member
externalId formsgN, for example sg3 What the endpoint doesReturns the workgroup chat. Creates it if there is none

Any 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.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Dialog:', data.dialogId) // chat264

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.dialogId Typestring DescriptionThe dialog ID as chatN

Response example

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

Error response example

400 — externalId was not passed:

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."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionThe externalId field is missing. A request without a body lands here too
HTTP400 CodeINVALID_PARAMS DescriptionexternalId is not a string or is empty, or another body field or a query parameter was sent
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only: the call may create a chat — see access rights
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

A CRM chat is created even for a missing entity. On a test Bitrix24 account a request with crm|DEAL|<ID> 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 — the response is 403 BITRIX_ACCESS_DENIED. Check that the entity exists before the call.

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.

Find a CRM entity chat without creating one. If you need the chat only when it already exists, use finding a CRM entity chat: for an entity without a chat it returns data: null and creates nothing.

See also