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

Переименовать чат

PATCH /v1/chats/:chatId

Меняет название группового чата. Вызывающий должен быть участником чата с правами на его переименование.

Параметры

Параметр Тип Обяз. Описание
chatId (path) number да Числовой ID чата. Получить: POST /v1/chats или поле chatId строки GET /v1/chats/recent
format (query) string нет v2 включает режим v2 — см. «Режим v2» ниже. Любое другое значение игнорируется, ответ прежний

Режим v2. format=v2 меняет групповой чат целиком одним вызовом: название, описание, аватар, владельца, тип, права, участников и менеджеров. Поле title становится необязательным, но нужно хотя бы одно поле. Каждое поле проверяется до обращения к Битрикс24: неизвестное поле, неверный тип или значение вне списка отклоняются с 400 INVALID_PARAMS с именем поля. Режим v2 требует права на изменение чата — по умолчанию оно у владельца, — а не права на переименование, которого достаточно без параметра. Личный диалог отклоняется с 422 BITRIX_ERROR и error.b24Code WRONG_MESSAGE_TYPE. В ответе data — объект { result: true }. Чтобы только переименовать чат по праву переименования, вызывайте эндпоинт без format.

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

Поле Тип Обяз. Описание
title string да Новое название чата. Не может быть пустым. В режиме v2 необязательно
description string нет Только режим v2. Новое описание
avatar string | number нет Только режим v2. Картинка строкой base64 или ID файла на Диске, доступного вызывающему
ownerId number нет Только режим v2. Передать чат этому пользователю — ID из списка пользователей
type string нет Только режим v2. Сменить тип чата. Недопустимая смена отклоняется с 422 BITRIX_ERROR, причина — в error.b24Code
searchable string нет Только режим v2. Y — открытый чат: его может найти и вступить в него любой сотрудник
manageUi string нет Только режим v2. Кто может менять название, описание и аватар: MEMBER, MANAGER, OWNER
manageUsersAdd string нет Только режим v2. Кто может добавлять участников: MEMBER, MANAGER, OWNER
manageUsersDelete string нет Только режим v2. Кто может удалять участников: MEMBER, MANAGER, OWNER
manageMessages string нет Только режим v2. Кто может писать: NONE (никто, кроме владельца), MEMBER, MANAGER, OWNER
manageMessagesAutoDelete string нет Только режим v2. Кто может включать автоудаление сообщений: NONE, MEMBER, MANAGER, OWNER
manageGuestInvites string нет Только режим v2. Кто может приглашать гостей: NONE, MEMBER, MANAGER, OWNER
addedMemberEntities array нет Только режим v2. Добавить участников — пары [тип, id]: ["user", 5], ["department", "12:F"] (подразделение с дочерними), ["project", 3]
deletedMemberEntities array нет Только режим v2. Удалить участников — пары [тип, id] в той же форме
hideHistory string нет Только режим v2. Y — добавленные участники не видят прежнюю историю
addedManagers array нет Только режим v2. ID пользователей, которых сделать менеджерами, — положительные целые
deletedManagers array нет Только режим v2. ID менеджеров, с которых снять роль менеджера, — положительные целые

Примеры

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/chats/3663 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проект Бета"
  }'

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

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/chats/3663 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Проект Бета"
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/3663', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Проект Бета',
  }),
})

const { success, data } = await res.json()
console.log('Переименован:', data) // true

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/3663', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Проект Бета',
  }),
})

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

curl — режим v2

Terminal 
curl -X PATCH "https://vibecode.bitrix24.tech/v1/chats/3663?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Обсуждение релиза",
    "addedManagers": [27],
    "manageMessages": "MANAGER"
  }'

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data boolean true при успешном переименовании
data.result boolean Режим v2: true — изменения применены

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

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

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

400 — передан пустой заголовок:

JSON 
{
  "success": false,
  "error": {
    "code": "TITLE_EMPTY",
    "message": "title is required and cannot be blank."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_CHAT_ID chatId не является положительным целым числом
400 TITLE_EMPTY Поле title отсутствует или пустое. Только без format
400 INVALID_PARAMS Только режим v2: нет ни одного поля для изменения, тело не JSON-объект, неизвестное поле или параметр строки запроса вне format, неверный тип или значение вне списка — поле названо в сообщении. Проверяется до обращения к Битрикс24
404 CHAT_NOT_FOUND_OR_NO_ACCESS Чат не существует или у вызывающего нет прав на переименование. Только без format
404 ENTITY_NOT_FOUND Режим v2: Битрикс24 вернул «не найдено». Код портала — в error.b24Code
422 BITRIX_ERROR Режим v2: Битрикс24 вернул ошибку. Код портала — в error.b24Code. Несуществующий чат приходит здесь с CHAT_NOT_FOUND, личный диалог — с WRONG_MESSAGE_TYPE
403 BITRIX_ACCESS_DENIED Режим v2: у вызывающего нет права на изменение чата — Битрикс24 отказал с кодом ACCESS_DENIED
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — вызов изменяет чат
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Аватар в теле запроса. Тело запроса ограничено 1 МиБ, а base64 увеличивает размер картинки на треть: в поле avatar помещается изображение примерно до 750 КиБ. Картинку больше загрузите на Диск и передайте ID файла.

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