Untuk agen AI: markdown halaman ini — /docs-content-en/chats/settings.md indeks dokumentasi — /llms.txt

Artikel dokumentasi saat ini tersedia dalam bahasa Inggris.

Messenger settings

Reading and changing the user's general messenger settings and status — the same ones the user sees in the Bitrix24 messenger settings window.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Read settings

GET /v1/chats/settings

Returns the user's general messenger settings — sound, theme, sending with Enter, privacy, the notification scheme and more.

Parameters

Parameter Type Required Description
userId number no ID of the user whose settings to read, a positive integer. Defaults to the key owner. Only a Bitrix24 administrator can read another user's settings. User list: GET /v1/users

Any other query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/settings" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data: settings } = await res.json()
console.log('Theme:', settings.enableDarkTheme, 'Enter sends:', settings.sendByEnter)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data: settings } = await res.json()
console.log('Status:', settings.status)

Response fields

data is the settings object. Each key is a setting name, and each value is a string or a boolean. Bitrix24 defines the setting names, and the set depends on the messenger version. Changing a setting accepts the same names. The table describes the main settings. The response example shows the full set.

Field Type Description
success boolean Always true on success
data object The settings: each key is a setting name, each value is a string or a boolean
data.status string User status: online, dnd or away. Changed through PUT /v1/chats/settings/status
data.enableSound boolean Messenger sounds
data.enableBigSmile boolean Large emoji in a message that consists of emoji only
data.enableDarkTheme string Theme: auto, light or dark
data.sendByEnter boolean true — a message is sent with Enter
data.chatAlignment string Message alignment in a chat
data.pinnedChatSort string Order of pinned chats
data.notifyScheme string Notification scheme: simple or expert
data.privacySearch string Who can find the user in search

Response example

JSON 
{
  "success": true,
  "data": {
    "status": "online",
    "backgroundImage": false,
    "bxdNotify": false,
    "sshNotify": true,
    "generalNotify": false,
    "trackStatus": "",
    "nativeNotify": true,
    "openDesktopFromPanel": false,
    "viewOffline": true,
    "viewGroup": true,
    "viewLastMessage": true,
    "viewBirthday": true,
    "viewCommonUsers": true,
    "enableSound": true,
    "enableBigSmile": true,
    "defaultReaction": "like",
    "enableDarkTheme": "dark",
    "isCurrentThemeDark": false,
    "enableRichLink": true,
    "linesTabEnable": true,
    "linesNewGroupEnable": false,
    "sendByEnter": true,
    "correctText": false,
    "panelPositionHorizontal": "right",
    "panelPositionVertical": "bottom",
    "loadLastMessage": true,
    "loadLastNotify": true,
    "notifyAutoRead": false,
    "notifyScheme": "expert",
    "notifySchemeLevel": "important",
    "notifySchemeSendSite": false,
    "notifySchemeSendEmail": false,
    "notifySchemeSendXmpp": true,
    "notifySchemeSendPush": false,
    "privacyMessage": "all",
    "privacyChat": "all",
    "privacyCall": "all",
    "privacySearch": "all",
    "privacyProfile": "all",
    "callAcceptIncomingVideo": "AllowAll",
    "backgroundImageId": "azure",
    "chatAlignment": "left",
    "pinnedChatSort": "byCost"
  }
}

Error response example

400 — userId is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "The query parameter `userId` must be a positive integer."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS userId is not a positive integer
400 INVALID_PARAMS A query parameter other than userId was passed
400 INVALID_PARAMS userId was passed more than once or with brackets, for example userId[]=5
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only. The request is rejected before any call to Bitrix24
422 BITRIX_ERROR Bitrix24 returned an error. The portal code is in error.b24Code. SETTINGS_ACCESS_DENIED — a non-administrator requested another user's settings
502 ME_ALIAS_RESOLUTION_FAILED userId was not passed, and the key owner could not be resolved
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • Reading the settings of a user who is not yet bound to a settings preset may create that binding without changing the values.
  • For a userId that does not exist in the Bitrix24 account, the response contains the default settings, without an error. To check that the user exists, use GET /v1/users/:id.

See also