لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/chats/settings.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

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
ParameteruserId Typenumber Requiredno DescriptionID 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe settings: each key is a setting name, each value is a string or a boolean
Fielddata.status Typestring DescriptionUser status: online, dnd or away. Changed through PUT /v1/chats/settings/status
Fielddata.enableSound Typeboolean DescriptionMessenger sounds
Fielddata.enableBigSmile Typeboolean DescriptionLarge emoji in a message that consists of emoji only
Fielddata.enableDarkTheme Typestring DescriptionTheme: auto, light or dark
Fielddata.sendByEnter Typeboolean Descriptiontrue — a message is sent with Enter
Fielddata.chatAlignment Typestring DescriptionMessage alignment in a chat
Fielddata.pinnedChatSort Typestring DescriptionOrder of pinned chats
Fielddata.notifyScheme Typestring DescriptionNotification scheme: simple or expert
Fielddata.privacySearch Typestring DescriptionWho 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
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter other than userId was passed
HTTP400 CodeINVALID_PARAMS DescriptionuserId was passed more than once or with brackets, for example userId[]=5
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. The request is rejected before any call to Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The portal code is in error.b24Code. SETTINGS_ACCESS_DENIED — a non-administrator requested another user's settings
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionuserId was not passed, and the key owner could not be resolved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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