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

Change a chat description

PUT /v1/chats/:dialogId/description

Replaces the chat description with the text from the request. An empty string clears the description.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog ID: chatXXX for a group chat, a numeric user ID for private messages, me — the current user's personal dialog. A CRM entity chat is found via Find a CRM entity chat

The endpoint takes no query parameters: any parameter in the query string is refused with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
description string yes The new description. Bitrix24 trims leading and trailing spaces. An empty string "" clears the description

Other body fields are refused with 400 INVALID_PARAMS, and the message names the extra field.

Examples

curl — personal key

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/description \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Warehouse equipment purchase"}'

curl — OAuth application

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/description \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Warehouse equipment purchase"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2741/description', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ description: 'Warehouse equipment purchase' }),
})

const { success } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2741/description', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ description: 'Warehouse equipment purchase' }),
})

const { success } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data boolean true — the description is saved

Response example

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

Error response example

400 — the body has no description field:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `description` must be a string — the new description; an empty string clears it."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS The body has no description or it is not a string, the body has another field, the body is not a JSON object, or the query string has a parameter. Checked before the Bitrix24 call
403 BITRIX_ACCESS_DENIED Bitrix24 refused: the user is not a chat member, or the ui permission does not let them change the description
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. If the chat does not exist, the code is CHAT_NOT_FOUND
403 SCOPE_DENIED The API key lacks the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — changing the description counts as a write
401 TOKEN_MISSING The API key has no configured Bitrix24 tokens
502 ME_ALIAS_RESOLUTION_FAILED dialogId=me — the current user's ID could not be resolved
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

Current description. The saved text comes in the description field of the Dialog details response. Changing the description does not post a system message to the chat.

Who can change the description. A chat's description, color and avatar can be changed by the users the ui permission allows. PUT /v1/chats/:dialogId/permissions/ui sets who holds it, and the permissions.manageUi field of the Dialog details response shows the current value.

See also