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

Find a CRM entity chat

GET /v1/chats/find

Returns the identifier of the chat bound to the specified CRM entity. When there is no chat for the entity, it returns data: null — not an error.

Parameters

Parameter Type Required Description
entityType string yes CRM object type. Example: CRM
entityId string yes Composite entity identifier. Format: <TYPE>|<ID>. Example: DEAL|123

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/find?entityType=CRM&entityId=DEAL%7C123" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/find?entityType=CRM&entityId=DEAL%7C123" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({ entityType: 'CRM', entityId: 'DEAL|123' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/chats/find?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
// data is an object { id } or null if the chat is not created
console.log('Chat ID:', data?.id ?? 'not found')

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({ entityType: 'CRM', entityId: 'DEAL|123' })
const res = await fetch(`https://vibecode.bitrix24.com/v1/chats/find?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object | null Object { id } with the chat identifier, or null if the chat is not created
data.id number Chat identifier. Used in GET /v1/chats/:dialogId

Response example

Chat found:

JSON 
{
  "success": true,
  "data": {
    "id": 456
  }
}

Chat for the entity is not created:

JSON 
{
  "success": true,
  "data": null
}

Error response example

400 — required parameters were not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required query params: entityType (e.g. \"CRM\") and entityId (e.g. \"DEAL|123\")"
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS entityType or entityId was not passed
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no configured tokens

The full list of general API errors — Errors.

Known specifics

  • The entityId parameter is passed URL-encoded: the | character is encoded as %7C. In JavaScript, URLSearchParams performs the encoding automatically.
  • Before accessing the id field, check data !== null: for an entity without a chat the response is successful, but data is empty.

See also