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

Change a chat color

PUT /v1/chats/:dialogId/color

Sets the chat color to one of the seventeen Bitrix24 palette codes. An RGB color value is not accepted.

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
color string yes A color code from the table below, in any case: mint and MINT are equivalent

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

The table lists the palette codes and the color a chat with each code returns in the color field of the Dialog details response. A #rrggbb value in the request is refused.

Code Color in the chat response
RED #df532d
GREEN #64a513
MINT #4ba984
LIGHT_BLUE #4ba5c3
DARK_BLUE #3e99ce
PURPLE #8474c8
AQUA #1eb4aa
PINK #f76187
LIME #58cc47
BROWN #ab7761
AZURE #29619b
KHAKI #728f7a
SAND #ba9c7b
MARENGO #556574
GRAY #909090
GRAPHITE #5e5f5e
COPILOT #8d51eb

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success } = await res.json()

JavaScript — OAuth application

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

const { success } = await res.json()

Response fields

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

Response example

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

Error response example

400 — a #rrggbb color was sent instead of a code:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `color` must be a palette code: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE, COPILOT (any case). A hex value is not accepted — the portal stores codes, and replaces any other value with a colour of its own choice."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS The body has no color or it is not a palette code, 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 color
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 color 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

A value outside the palette is refused before the write. The code ORANGE, a #rrggbb value and a mistyped code never reach Bitrix24: Bitrix24 would store a color of its own choice instead and report success. So the endpoint returns 400 INVALID_PARAMS, and the chat color stays unchanged.

No system message. Changing the color does not post a system message to the chat, unlike changing the avatar.

See also