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
ParameterdialogId (path) Typestring Requiredyes DescriptionDialog 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
Fielddescription Typestring Requiredyes DescriptionThe 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean Descriptiontrue — 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
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused: the user is not a chat member, or the ui permission does not let them change the description
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code. If the chat does not exist, the code is CHAT_NOT_FOUND
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — changing the description counts as a write
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured Bitrix24 tokens
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptiondialogId=me — the current user's ID could not be resolved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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. Users allowed by the ui permission can change a chat's description, color and avatar. 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