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

Rename a chat

PATCH /v1/chats/:chatId

Changes the name of a group chat. The caller must be a member of the chat with permission to rename it.

Parameters

Parameter Type Required Description
ParameterchatId (path) Typenumber Requiredyes DescriptionNumeric chat ID. Get it from: POST /v1/chats or the chatId field of a GET /v1/chats/recent row
Parameterformat (query) Typestring Requiredno Descriptionv2 turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged

The v2 mode. format=v2 changes a group chat as a whole in one call: the name, description, avatar, owner, type, permissions, members and managers. The title field becomes optional, but at least one field is required. Every field is checked before any call to Bitrix24: an unknown field, a wrong type or a value outside the list is rejected with 400 INVALID_PARAMS naming the field. The v2 mode requires the permission to change the chat — the owner has it by default — rather than the rename permission, which is enough without the parameter. A personal dialog is rejected with 422 BITRIX_ERROR and error.b24Code WRONG_MESSAGE_TYPE. In the response, data is the object { result: true }. To only rename a chat under the rename permission, call the endpoint without format.

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredyes DescriptionNew chat name. Cannot be empty. Optional in the v2 mode
Fielddescription Typestring Requiredno DescriptionThe v2 mode only. New description
Fieldavatar Typestring | number Requiredno DescriptionThe v2 mode only. An image as a base64 string, or the ID of a Drive file the caller can read
FieldownerId Typenumber Requiredno DescriptionThe v2 mode only. Hand the chat over to this user — an ID from the user list
Fieldtype Typestring Requiredno DescriptionThe v2 mode only. Change the chat type. A change that is not allowed is rejected with 422 BITRIX_ERROR, with the reason in error.b24Code
Fieldsearchable Typestring Requiredno DescriptionThe v2 mode only. Y — an open chat: any employee can find it and join
FieldmanageUi Typestring Requiredno DescriptionThe v2 mode only. Who can change the name, description and avatar: MEMBER, MANAGER, OWNER
FieldmanageUsersAdd Typestring Requiredno DescriptionThe v2 mode only. Who can add members: MEMBER, MANAGER, OWNER
FieldmanageUsersDelete Typestring Requiredno DescriptionThe v2 mode only. Who can remove members: MEMBER, MANAGER, OWNER
FieldmanageMessages Typestring Requiredno DescriptionThe v2 mode only. Who can post: NONE (nobody but the owner), MEMBER, MANAGER, OWNER
FieldmanageMessagesAutoDelete Typestring Requiredno DescriptionThe v2 mode only. Who can turn on message auto-deletion: NONE, MEMBER, MANAGER, OWNER
FieldmanageGuestInvites Typestring Requiredno DescriptionThe v2 mode only. Who can invite guests: NONE, MEMBER, MANAGER, OWNER
FieldaddedMemberEntities Typearray Requiredno DescriptionThe v2 mode only. Members to add — [type, id] pairs: ["user", 5], ["department", "12:F"] (a department with its sub-departments), ["project", 3]
FielddeletedMemberEntities Typearray Requiredno DescriptionThe v2 mode only. Members to remove — [type, id] pairs of the same form
FieldhideHistory Typestring Requiredno DescriptionThe v2 mode only. Y — the added members do not see the earlier history
FieldaddedManagers Typearray Requiredno DescriptionThe v2 mode only. IDs of users to make managers — positive integers
FielddeletedManagers Typearray Requiredno DescriptionThe v2 mode only. IDs of managers to remove the manager role from — positive integers

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/chats/3663 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Beta"
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/chats/3663 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Beta"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/3663', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Project Beta',
  }),
})

const { success, data } = await res.json()
console.log('Renamed:', data) // true

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/3663', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Project Beta',
  }),
})

const { success, data } = await res.json()

curl — the v2 mode

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/3663?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Release discussion",
    "addedManagers": [27],
    "manageMessages": "MANAGER"
  }'

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean Descriptiontrue when the rename succeeded
Fielddata.result Typeboolean DescriptionThe v2 mode: true — the changes are applied

Response example

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

Error response example

400 — an empty title was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "TITLE_EMPTY",
    "message": "title is required and cannot be blank."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_CHAT_ID DescriptionchatId is not a positive integer
HTTP400 CodeTITLE_EMPTY DescriptionThe title field is missing or empty. Without format only
HTTP400 CodeINVALID_PARAMS DescriptionThe v2 mode only: no field to change, the body is not a JSON object, an unknown field or a query string parameter other than format, a wrong type or a value outside the list — the message names the field. Checked before any call to Bitrix24
HTTP404 CodeCHAT_NOT_FOUND_OR_NO_ACCESS DescriptionThe chat does not exist or the caller has no permission to rename it. Without format only
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe v2 mode: Bitrix24 returned "not found". The Bitrix24 code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The Bitrix24 code is in error.b24Code. The v2 mode: a missing chat lands here with CHAT_NOT_FOUND, a personal dialog with WRONG_MESSAGE_TYPE. Without format: a collab chat lands here with ACCESS_ERROR and the text This chat cannot be renamed
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe v2 mode: the caller has no permission to change the chat — Bitrix24 refused with the ACCESS_DENIED code. The same error is returned for a collab chat, even to its owner
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — the call changes the chat
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

An avatar in the request body. The request body is limited to 1 MiB, and base64 inflates an image by a third: the avatar field fits an image of up to about 750 KiB. Upload a larger image to Drive and pass the file ID.

See also