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
ParameterentityType Typestring Requiredyes DescriptionCRM object type. Example: CRM
ParameterentityId Typestring Requiredyes DescriptionComposite 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 no chat exists
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject | null DescriptionObject { id } with the chat identifier, or null if no chat exists
Fielddata.id Typenumber DescriptionChat identifier. Used in GET /v1/chats/:dialogId

Response example

Chat found:

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

No chat exists for the entity:

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
HTTP400 CodeMISSING_PARAMS DescriptionentityType or entityId was not passed
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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