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
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. To find a CRM entity chat, use 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
Fieldcolor Typestring Requiredyes DescriptionA 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
CodeRED Color in the chat response#df532d
CodeGREEN Color in the chat response#64a513
CodeMINT Color in the chat response#4ba984
CodeLIGHT_BLUE Color in the chat response#4ba5c3
CodeDARK_BLUE Color in the chat response#3e99ce
CodePURPLE Color in the chat response#8474c8
CodeAQUA Color in the chat response#1eb4aa
CodePINK Color in the chat response#f76187
CodeLIME Color in the chat response#58cc47
CodeBROWN Color in the chat response#ab7761
CodeAZURE Color in the chat response#29619b
CodeKHAKI Color in the chat response#728f7a
CodeSAND Color in the chat response#ba9c7b
CodeMARENGO Color in the chat response#556574
CodeGRAY Color in the chat response#909090
CodeGRAPHITE Color in the chat response#5e5f5e
CodeCOPILOT Color in the chat response#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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean Descriptiontrue — 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
HTTP400 CodeINVALID_PARAMS DescriptionThe 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
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused: the user is not a chat member, or the ui permission does not let them change the color
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 color 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

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