Боты

Раздел «Боты» — владельческое управление ботами: создание, настройка, перевыпуск токена, добавление в группу. Все запросы этого раздела выполняются от лица владельца и требуют заголовок Authorization: Bearer <accessToken>, как и любой другой пользовательский раздел API.

Для действий, которые бот выполняет от своего собственного лица (отправка сообщений, подключение к голосовым каналам, управление группой и т.д.), используется отдельный self-service раздел — «Self-service», доступный самому боту по токену бота (Authorization: Bot <botToken>), а не владельцу.

Объект BotResponse

Поле	Тип	Описание
id	string	Идентификатор бота.
ownerId	string	Идентификатор владельца.
username	string	Имя пользователя бота.
displayName	string	Отображаемое имя.
description	string	Описание бота.
avatarId	string	Id аватара бота (или пусто).
avatarUrl	string	URL аватара бота (или пусто).
userStatus	UserStatus	Текущий статус присутствия бота.
type	BotType	Тип бота.
isEnabled	boolean	Включён ли бот — отключённый бот не может аутентифицироваться токеном.
createdAt / updatedAt	string	Когда бот создан/обновлён (ISO8601).
intents	integer (int64)	Битовая маска выданных Gateway Intents.

BotType

Значение	Описание
BOT	Обычный бот, управляемый своим кодом через self-service API.
AGENT	Бот на основе LLM-провайдера (см. «Агенты» ниже).

Объект ошибки

При любой ошибке вместо 200 OK возвращается default-ответ:

Поле	Тип	Описание
code	integer	Числовой код ошибки (google.rpc.Code).
message	string	Человекочитаемое описание ошибки.
details	array	Дополнительные структурированные детали ошибки (google.protobuf.Any); в большинстве случаев пуст.

---

Управление ботами

Мои боты

GET/v1/bots

Возвращает список ботов текущего пользователя.

Ответ 200 OK: bots — массив объектов BotResponse.

Получить бота

GET/v1/bots/{botId}

Параметры пути: botId.

Ответ 200 OK: bot — объект BotResponse; credential — заполнен только для ботов типа AGENT (провайдер, модель, без самого ключа — см. AgentCredential).

Создать бота

POST/v1/bots

Тело запроса: username, displayName?, description?, avatarId?, type (BotType), intents — битовая маска Gateway Intents, выданных боту сразу при создании (по умолчанию 0 — бот сможет только аутентифицироваться, но не сможет вызывать методы self-service API).

Ответ 200 OK: bot — созданный объект BotResponse; token — токен бота.

Токен показывается только один раз

token возвращается только в ответе на CreateBot (и на «Перевыпустить токен») — сохраните его сразу, повторно получить существующий токен нельзя, только перевыпустить новый.

Изменить бота

POST/v1/bots/{botId}

Параметры пути: botId. Тело запроса: displayName?, description?, avatarId?, isEnabled?, updateIntents? (boolean — нужно, чтобы отличить «не трогать intents» от «заменить на 0»), intents? (учитывается только если updateIntents: true).

Ответ 200 OK: обновлённый объект BotResponse.

Изменение intents вступает в силу с задержкой

Как и у токена, набор intents бота кэшируется на стороне self-service API и Gateway примерно на 60 секунд — см. «Аутентификация ботов».

Удалить бота

POST/v1/bots/{botId}:delete

Параметры пути: botId.

Ответ 200 OK: пустой объект {}.

Перевыпустить токен

POST/v1/bots/{botId}:regenerate-token

Старый токен становится недействительным немедленно.

Параметры пути: botId.

Ответ 200 OK: token — новый токен бота.

Добавить бота в группу

POST/v1/bots/{botId}/groups/{groupId}

Добавляет бота (которым владеет текущий пользователь) в группу, участником которой текущий пользователь уже является — без инвайт-кода. Бот сразу становится обычным участником группы.

Параметры пути: botId, groupId. Тело запроса: permissions — битовая маска Permissions, по которой создаётся управляемая роль бота в группе.

Нельзя выдать больше прав, чем есть у себя

Владелец бота не может выдать боту больше прав в группе, чем есть у него самого — как и при создании обычной роли.

Ответ 200 OK: groupId, botId, success.

---

Аватар бота

Ту же двухшаговую схему через предподписанный URL, что и у аватара пользователя и у аватара группы, меняет только владелец бота.

Запросить загрузку аватара

POST/v1/bots/{botId}/avatar/upload

Параметры пути: botId. Тело запроса: contentType, sizeBytes.

Ответ 200 OK: mediaId, uploadUrl, expiresAt.

Подтвердить загрузку аватара

POST/v1/bots/{botId}/avatar/confirm

Параметры пути: botId. Тело запроса: avatarId (значение mediaId из предыдущего ответа).

Ответ 200 OK: обновлённый объект BotResponse с новым avatarUrl.

Удалить аватар

DELETE/v1/bots/{botId}/avatar

Параметры пути: botId.

Ответ 200 OK: обновлённый объект BotResponse с пустым avatarUrl.

---

Intents

Каталог доступных intents

GET/v1/bots/available-intents

Статический список всех существующих Gateway Intents — не привязан к конкретному боту. Используется, чтобы построить форму выбора intents при создании/изменении бота, не хардкодя битовые значения на клиенте.

Ответ 200 OK: intents — массив объектов { name, value }, где value — битовое значение конкретного intent'а.

---

Агенты

Боты типа AGENT — это боты, чьи ответы генерирует LLM-провайдер (OpenAI, Anthropic, Google, DeepSeek, Mistral, Kimi), а не собственный код владельца: бот подписывается на упоминания в чатах группы и отвечает через тот же self-service SendMessage, что и обычный бот, но текст ответа формирует выбранный провайдер. Учётные данные провайдера (AgentCredential) хранятся отдельно от бота в зашифрованном виде и возвращаются вместе с BotResponse только в виде метаданных, без самого ключа:

Поле	Тип	Описание
provider	string	Один из: OPENAI, ANTHROPIC, GOOGLE, DEEPSEEK, MISTRAL, KIMI.
modelName	string	Имя модели у провайдера.
organizationId	string	Id организации у провайдера (если применимо).
createdAt / updatedAt / lastUsedAt	string	Служебные метки времени (ISO8601).

Отдельного REST-эндпоинта для создания/изменения AgentCredential в текущей версии API нет — этот раздел документирует только то, что уже видно в BotResponse.credential.