Для AI-агентов: markdown этой страницы — /docs-content/entities/workgroups/create.md индекс документации — /llms.txt

Создать рабочую группу

POST /v1/workgroups

Создаёт новую рабочую группу на портале. Возвращает полный объект созданной группы. Обязательное поле одно — name; остальные параметры опциональны.

Поля запроса (body)

Поле Тип Обяз. По умолч. Описание
Полеname Типstring Обяз.★ По умолч.— ОписаниеНазвание рабочей группы
Полеdescription Типstring Обяз.нет По умолч.— ОписаниеОписание
ПолеownerId Типnumber Обяз.нет По умолч.текущий пользователь ключа ОписаниеИдентификатор владельца группы. Список: GET /v1/users
ПолеsubjectId Типnumber Обяз.нет По умолч.тема портала по умолчанию ОписаниеИдентификатор темы
Полеactive Типboolean Обяз.нет По умолч.true ОписаниеАктивна ли группа
Полеvisible Типboolean Обяз.нет По умолч.— ОписаниеВидна ли в общих списках. Фактическое значение — в ответе, см. «Группа создаётся коллабом»
Полеopened Типboolean Обяз.нет По умолч.false ОписаниеОткрыта ли для вступления без приглашения. Фактическое значение — в ответе, см. «Группа создаётся коллабом»
Полеarchived Типboolean Обяз.нет По умолч.false ОписаниеПоместить в архив сразу при создании
ПолеisProject Типboolean Обяз.нет По умолч.— ОписаниеСоздать как проект. Фактическое значение — в ответе, см. «Группа создаётся коллабом»
Полеkeywords Типstring Обяз.нет По умолч.— ОписаниеКлючевые слова для поиска. При создании не сохраняются, см. «Ключевые слова при создании не сохраняются»

isExtranet доступен только для чтения и определяется привязкой группы к сайтам в Битрикс24. Передача isExtranet, IS_EXTRANET, is_extranet или isextranet возвращает 400 READONLY_FIELD до создания группы: и для false, и для true, включая повтор текущего значения. Уберите это поле из тела записи; фактический признак остаётся в ответах чтения.

В POST /v1/workgroups/batch с action: create или action: update такое поле вызывает 400 BATCH_ITEM_VALIDATION до отправки всего пакета. В POST /v1/batch отклонённая операция получает READONLY_FIELD в data.errors.<id>; если отклонены все операции, HTTP-статус — 400, при смешанном результате — 200, а допустимые соседние операции выполняются.

Примеры

curl — личный ключ

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Маркетинг 2026",
    "description": "Координация рекламных кампаний",
    "opened": true,
    "isProject": true
  }'

curl — OAuth-приложение

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/workgroups" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Маркетинг 2026",
    "description": "Координация рекламных кампаний",
    "opened": true,
    "isProject": true
  }'

JavaScript — личный ключ

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Маркетинг 2026',
    description: 'Координация рекламных кампаний',
    opened: true,
    isProject: true,
  }),
})

const { success, data } = await res.json()
console.log('Workgroup ID:', data.id)

JavaScript — OAuth-приложение

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Маркетинг 2026',
    description: 'Координация рекламных кампаний',
    opened: true,
    isProject: true,
  }),
})

const { success, data } = await res.json()

Поля ответа

Возвращается полный объект созданной рабочей группы.

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеОбъект созданной рабочей группы. Полное описание полей — Получить рабочую группу или Поля рабочей группы

Пример ответа

JSON
{
  "success": true,
  "data": {
    "id": 201,
    "siteId": "ex",
    "name": "Маркетинг 2026",
    "description": "Координация рекламных кампаний",
    "dateCreate": "2026-10-20T06:48:43.000Z",
    "dateUpdate": "2026-10-20T06:48:43.000Z",
    "active": true,
    "visible": false,
    "opened": false,
    "archived": false,
    "subjectId": 1,
    "ownerId": 1317,
    "keywords": null,
    "membersCount": 1,
    "dateActivity": "2026-10-20T06:48:43.000Z",
    "subjectName": "Рабочие группы",
    "isProject": true,
    "isExtranet": true
  }
}

Пример ответа при ошибке

422 — не передано обязательное поле name:

JSON
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Не указано название"
  }
}

Ошибки

HTTP error.code Описание
HTTP400 error.codeREADONLY_FIELD ОписаниеПередано поле только для чтения, включая isExtranet или IS_EXTRANET
HTTP422 error.codeBITRIX_ERROR ОписаниеБитрикс24 отказал в создании группы — текст причины в error.message. Типичная причина: отсутствует обязательное поле name
HTTP401 error.codeMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 error.codeINVALID_API_KEY ОписаниеКлюч не опознан: такой строки на платформе нет
HTTP403 error.codeSCOPE_DENIED ОписаниеУ ключа нет скоупа sonet_group

Полный список общих ошибок API — Ошибки.

Известные особенности

Группа создаётся коллабом. На проверенных порталах новая группа создаётся коллабом при любом теле запроса. В ответе isProject: true, siteId: "ex", isExtranet: true, visible: false и opened: false, даже если в запросе передано isProject: false или opened: true. Признак проекта у такой группы не снимается: PATCH /v1/workgroups/:id с isProject: false отвечает 422 BITRIX_ERROR с текстом Field 'PROJECT' can not be updated from 'Y' for collab. Фактические значения полей читайте в ответе создания.

Ключевые слова при создании не сохраняются. Битрикс24 не сохраняет keywords, переданное при создании группы: в ответе создания и при последующем чтении keywords равно null. То же для action: create в POST /v1/workgroups/batch и POST /v1/batch. Чтобы задать ключевые слова, после создания отправьте PATCH /v1/workgroups/:id с полем keywords — обновление значение сохраняет.

Чат группы создаётся вместе с ней. Сразу после создания у группы есть один чат — чат коллаба. В его карточке type равен collab, entityType — SONET_GROUP, entityId — id группы. Отдельного главного чата нет. dialogId этого чата возвращает ID диалога по внешнему идентификатору с externalId вида sgN, где N — id из ответа. Создавать группе чат через POST /v1/chats не нужно: type: "COLLAB" с её entityId создаст второй чат коллаба.

В чат группы вместе с участником приходит BitrixGPT. Пока в чат никого не добавили, в нём только владелец. Когда в чат в режиме v2 добавляют участника, человека или бота, в составе появляется и системный бот BitrixGPT с bot: true. Ни одно поле запроса этого не отключает. Бота можно удалить из чата в режиме v2, передав его userId, но при следующем добавлении участника он вернётся. В обычном режиме список участников показывает BitrixGPT, а в режиме v2 бота нет ни в users, ни в relations.

Аватар и права чата группы через API не задаются. Аватар, права на сообщения и изменение в режиме v2 отвечают на чат коллаба 403 BITRIX_ACCESS_DENIED, в том числе владельцу. Поле imageUrl рабочей группы только для чтения: PATCH /v1/workgroups/:id с ним возвращает 400 READONLY_FIELD. Другого метода Вайбкод, который задаёт аватар этого чата, нет.

Смотрите также