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

Change a chat avatar

PUT /v1/chats/:dialogId/avatar

Sets the chat avatar: an image from the request body or a file that is already on Drive. A body field selects the mode.

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
Fieldavatar Typestring Requiredno DescriptionA PNG, JPEG, GIF or WebP image in base64, with sides of at most 5000 pixels. The string must not contain spaces or line breaks. A data:image/<type>;base64, prefix is allowed and is stripped. The whole request body is limited to 1 MiB, which is about 750 KiB of the source file
FieldavatarId Typenumber Requiredno DescriptionThe fileId of a file on Drive — the data.fileId field of the Get file response, not data.id

Send exactly one of the two fields. A body with neither, with both, or with other fields is refused with 400 INVALID_PARAMS.

Examples

The examples set the avatar from the local file logo.png.

curl — personal key

Terminal 
{ printf '{"avatar":"'; base64 < logo.png | tr -d '\r\n'; printf '"}'; } | \
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/avatar \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

curl — OAuth application

Terminal 
{ printf '{"avatar":"'; base64 < logo.png | tr -d '\r\n'; printf '"}'; } | \
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2741/avatar \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @-

JavaScript — personal key

javascript 
import { readFileSync } from 'node:fs'

const avatar = readFileSync('logo.png').toString('base64')

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

const { data } = await res.json()
console.log('Image ID:', data.avatarId)

JavaScript — OAuth application

javascript 
import { readFileSync } from 'node:fs'

const avatar = readFileSync('logo.png').toString('base64')

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

const { data } = await res.json()
console.log('Image ID:', data.avatarId)

For a file on Drive, the request body is {"avatarId": 830}, with the same headers.

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.avatarId Typenumber DescriptionOnly in the avatar mode: the ID of the image Bitrix24 saved as the avatar
Fielddata.result Typeboolean DescriptionOnly in the avatarId mode: true — the avatar is set

Response example

An image from the request body, the avatar field:

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

A file on Drive, the avatarId field:

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

Error response example

422 — avatarId carries the Drive file's id instead of its fileId:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Wrong file type",
    "b24Code": "WRONG_PARAMETER"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionNeither avatar nor avatarId is sent, or both are
HTTP400 CodeINVALID_PARAMS Descriptionavatar is not a string
HTTP400 CodeINVALID_PARAMS Descriptionavatar is not base64: an empty string, a length that is not a multiple of 4, characters outside the base64 alphabet, spaces or line breaks
HTTP400 CodeINVALID_PARAMS Descriptionavatar does not decode to a PNG, JPEG, GIF or WebP image
HTTP400 CodeINVALID_PARAMS DescriptionAn image side exceeds 5000 pixels
HTTP400 CodeINVALID_PARAMS DescriptionavatarId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe body has a field other than avatar and avatarId
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionThe query string has a parameter
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body exceeds 1 MiB
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 refused: the user is not a chat member, or the ui permission does not let them change the avatar. The same error is returned for a collab chat, even to its owner
HTTP422 CodeBITRIX_ERROR Descriptionerror.b24Code is WRONG_PARAMETER with the text Wrong file type: avatarId is not the fileId of a Drive file — the file's data.id was sent, or no file has that fileId
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned another 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 avatar 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

All 400 refusals happen before the Bitrix24 call.

Full list of common API errors — Errors.

Known specifics

The image is checked before the write. Bitrix24 would accept a string that does not read as an image and report success, but it would remove the chat avatar. So the format and size are checked before the Bitrix24 call: a failed check returns 400 INVALID_PARAMS, and the previous avatar stays.

A system message about the avatar change. Changing the avatar in either mode posts a system message to the chat saying that the user changed the chat icon.

Current avatar. The current avatar comes in the avatar field of the Dialog details response. An empty string means the chat has no avatar.

See also