For AI agents: markdown of this page — /docs-content-en/humanresources/node-operations/communications-set.md documentation index — /llms.txt

Configure communication tools

PATCH /v1/humanresources/nodes/:id/communications

Configures the link between a communication tool and an organizational structure node by its identifier. The tool type is set by the communicationType field.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionNode identifier. List: GET /v1/humanresources/nodes?type=DEPARTMENT

Request fields (body)

Field Type Required Description
FieldcommunicationType Typestring Requiredyes DescriptionCommunication tool type. Allowed values: CHAT, CHANNEL, COLLAB
Fieldids Typenumber[] Requiredno DescriptionIdentifiers of existing tools to link to the node
FieldremoveIds Typenumber[] Requiredno DescriptionIdentifiers of linked tools to unlink from the node
FieldcreateDefault Typeboolean Requiredno DescriptionCreate and link a new tool of the selected type. Defaults to false
FieldwithChildren Typeboolean Requiredno DescriptionApply the change to child nodes as well. Defaults to false

Examples

curl — personal key

Terminal 
curl -X PATCH -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"communicationType": "CHAT"}' \
  https://vibecode.bitrix24.com/v1/humanresources/nodes/23/communications

curl — OAuth application

Terminal 
curl -X PATCH -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"communicationType": "CHAT"}' \
  https://vibecode.bitrix24.com/v1/humanresources/nodes/23/communications

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/humanresources/nodes/23/communications',
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ communicationType: 'CHAT' }),
  }
)
const body = await res.json()
console.log(body.success)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/humanresources/nodes/23/communications',
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ communicationType: 'CHAT' }),
  }
)
const body = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true when the request is processed successfully
Fielddata.success Typeboolean DescriptionFlag indicating the setting was applied on the Bitrix24 side

Response example

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

Error response example

400 — the required communicationType field was not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Request object validation failed",
    "validation": [
      {
        "field": "MISSING_COMMUNICATIONTYPE",
        "message": "Parameter \"communicationType\" is required."
      }
    ]
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionThe communicationType field was not provided — error.validation returns MISSING_COMMUNICATIONTYPE
HTTP400 CodeINVALID_PARAMS DescriptionAn invalid communicationType value was provided — error.validation returns INVALID_COMMUNICATIONTYPE with the list of allowed values
HTTP400 CodeINVALID_PARAMS DescriptionThe node identifier in the path is not a positive integer
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the humanresources scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

Linking, unlinking, and creation are combined in one request. ids, removeIds, and createDefault can be passed together — a single call can link some tools, unlink others, and create a new one. withChildren propagates the change to child nodes.

See also