Аутентификация ботов

У ботов в Voice отдельная схема аутентификации, независимая от логина обычного пользователя. Это важно понимать сразу: два разных API используют два разных способа подтвердить личность вызывающего.

API	Кто вызывает	Способ аутентификации
Владельческое управление ботами (CreateBot, AddBotToGroup и т.д.)	Человек-владелец	Обычный пользовательский вход в Voice
BotsApi (действия от лица бота)	Сам бот	Токен бота
Gateway (realtime-события)	Сам бот	Токен бота
InteractionsApi — регистрация команд	Владелец или сам бот	Оба варианта поддерживаются одновременно
InteractionsApi — выполнение команд	Любой участник группы	Обычный пользовательский вход (это действие человека, не бота)

Библиотека для ботов, которую вы пишете, должна поддерживать именно токен бота — им подписываются вызовы BotsApi и подключение к Gateway.

Формат токена

Токен бота выглядит так:

ibot_{botId}_{secret}

• ibot_ — фиксированный префикс;
• {botId} — GUID бота без дефисов (32 шестнадцатеричных символа, формат N), закодирован прямо в токене — это сделано намеренно, чтобы сервер мог проверить токен одним прямым обращением к записи бота по его id, не выполняя поиск по всей таблице;
• {secret} — случайный секрет (256 бит энтропии, в Base64Url-кодировке).

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

Как передавать токен

gRPC-вызовы (BotsApi, InteractionsApi)

Токен передаётся в метаданных вызова как стандартный HTTP-заголовок Authorization:

Authorization: Bearer ibot_...

Этот заголовок должен присутствовать в каждом gRPC-вызове BotsApi, кроме случаев, когда вы сами реализуете какой-то дополнительный, не аутентифицированный служебный вызов (таких в BotsApi нет — аутентифицированы все методы, см. «BotsApi»).

Подключение к Gateway (SignalR)

Здесь токен передаётся не заголовком, а специальным способом, принятым в протоколе SignalR — параметром строки запроса при установке WebSocket-соединения:

wss://<gateway-host>/hubs/bots?access_token=ibot_...

Если вы используете готовую библиотеку клиента SignalR для своего языка, в ней обычно есть отдельная настройка «access token provider» — воспользуйтесь ей, а не добавляйте параметр в URL вручную (значение должно быть корректно закодировано для URL).

Что происходит при неверном токене

• Любой gRPC-вызов с отсутствующим, синтаксически неверным или отозванным токеном завершается с ошибкой уровня Unauthenticated.
• Попытка подключиться к Gateway с неверным токеном заканчивается отказом на этапе WebSocket-рукопожатия — соединение не устанавливается вовсе.
• Если бот отключён владельцем (is_enabled = false) или удалён, токен перестаёт быть валидным немедленно с точки зрения контракта API, но фактически изменение может быть видно клиенту не мгновенно — токен и связанные с ним данные (владелец, набор intents) кэшируются на сервере примерно на 60 секунд. Это стоит учитывать: отключение бота или изменение его intents может вступить в силу с задержкой до минуты.

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

Владелец может перевыпустить токен бота в любой момент. Старый токен становится недействительным сразу — если ваша библиотека держит долгоживущее соединение к Gateway, будьте готовы к тому, что оно может быть разорвано сервером в любой момент из-за отзыва токена, и обрабатывайте это как обычную ошибку аутентификации, а не как сетевой сбой (то есть не пытайтесь бесконечно переподключаться с тем же токеном — сообщите об ошибке вызывающему коду).