Токены бота

Токен бота — ключ, которым ваш код обращается к API от имени бота: отправляет сообщения, читает чаты, открывает формы. Токены выпускаются на вкладке API в карточке бота. Там же указан user_id бота: это его id в методах API.

Вкладка API доступна создателю бота и администраторам пространства, если на вкладке Основное им открыт доступ к редактированию. Руководителю чата с ботом токены не видны, даже когда остальные настройки бота ему открыты — подробнее в разделе Настройки бота.

Authorization: Bearer <токен бота>

Выпуск токена

Вкладка «API» в карточке бота

Создайте токен

На вкладке API нажмите Создать токен и задайте название — по нему токен узнаётся в списке, например по имени сервиса, который им пользуется.

Выберите права

Права задаются на каждый токен отдельно. Выдавайте минимально необходимые: токен для уведомлений не должен уметь удалять сообщения. Нужное право можно найти поиском по названию.

Окно «Создание токена бота»

Скопируйте значение

Значение токена показывается один раз, сразу после создания, в окне Скопируйте ваш API токен. Скопируйте его кнопкой Скопировать и закрыть — повторно значение не покажут ни в интерфейсе, ни через API.

Токены бота не имеют срока жизни: токен работает, пока его не перевыпустят, не удалят или пока не удалят самого бота.

Несколько токенов

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

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

• Список разрешений — посмотреть, что токену разрешено.
• Редактировать — изменить название и права. Новые права действуют сразу, выпускать токен заново не нужно.
• Перевыпустить — старое значение перестаёт работать сразу, новое показывается один раз, а название и права сохраняются.
• Удалить — токен перестаёт работать, восстановить его нельзя. Если токеном пользовались в последние 7 дней, диалог удаления предупредит об этом.

Права токена

Права определяют, какие методы API можно вызывать этим токеном. Круг данных они не расширяют: бот видит открытые каналы и чаты, куда его добавили, какие бы права ни были у токена. Подробнее — в разделе Доступы к чатам и сообщениям.

Часть прав есть только у ботов:

• bot_self:webhook:write — бот сам меняет адрес своего исходящего вебхука методом PUTСаморегистрация вебхука бота, подробнее в разделе Через API.
• bot_self:write — бот сам перевыпускает свой токен методом POSTРотация собственного токена бота.

Права для черновиков, управления ботами и другие права, которые выдаются только персональным токенам, боту недоступны. Полная таблица прав по ролям — в разделе Доступные скоупы. Проверить права текущего токена можно методом GETИнформация о токене.

Токены через API

Токенами бота управляют те же методы, что стоят за вкладкой API:

• GETСписок токенов бота — действующие токены с замаскированным значением.
• POSTНовый токен бота — токен с именем и правами. Значение приходит в ответе один раз, а без поля scopes токен выпускается без прав.
• PUTИзменение токена бота — новое имя или права, они действуют сразу.
• POSTПеревыпуск токена бота — новое значение вместо прежнего, имя и права остаются.
• DELETEУдаление токена бота — токен перестаёт работать сразу.

Права выбирают из каталога: GETКаталог прав бота перечисляет права, которые можно выдать этому боту, с описаниями и категориями, как на вкладке. Методы вызывают персональным токеном со скоупами bots:read и bots:write.

Бот, созданный методом POSTНовый бот, сразу получает основной токен: он приходит в поле access_token один раз, а его права задаются полем webhook.scopes. Без этого поля токен получает набор по умолчанию. В нём нет прав самоуправления (bot_self:webhook:write и bot_self:write) и чтения статусов сотрудников (user_status:read): их выдают явно. С empty: true бот создаётся без токена, как в интерфейсе.

Основной токен — тот, что в списке без имени, а если такого нет, самый старый. К нему относятся поле webhook.scopes метода PUTРедактирование бота и два метода ротации: POSTРотация токена бота перевыпускает его персональным токеном, а POSTРотация собственного токена бота — сам бот, с правом bot_self:write. Ротация выпускает основной токен заново: прежнее значение перестаёт работать сразу, у нового другой id и нет имени, а значение приходит в ответе один раз.

Если у бота нет ни одного токена, webhook.scopes создаёт основной токен, но его значение не возвращает. Чтобы получить значение, перевыпустите токен.

Если токен утёк

Перевыпустите токен кнопкой Перевыпустить или методом POSTПеревыпуск токена бота: старое значение перестанет работать в ту же секунду. Затем обновите токен в сервисах, которые им пользуются. Если токен больше не нужен, удалите его.

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