Обзор
Обычно бот работает своими правами: видит чаты, в которые его добавили, и пишет как бот. Но многим автоматизациям нужны права конкретного сотрудника: собрать сводку по его чатам, завести задачу от его имени, присылать ему задачи из трекера и отвечать на них прямо из Пачки. Для этого сотрудник авторизует бота — выдаёт ему свои права, и дальше бот работает от его имени.
Механизм — OAuth 2.0 с кодом авторизации: бот отправляет сотрудника на экран согласия, получает код и обменивает его на токен, которым вызывает API от имени сотрудника.
Как это выглядит для сотрудника
Сотрудник пишет боту
Находит бота в витрине или в поиске и пишет ему, например /start. Кто может написать боту — в разделе Доступы к чатам и сообщениям.
Бот присылает кнопку
В ответ бот отправляет сообщение с кнопкой авторизации. Кнопка — обычная ссылка на экран согласия.
Бот отвечает на /start кнопкой авторизации
Сотрудник соглашается
На экране согласия видны имя бота, пространство и запрашиваемые права. Сотрудник нажимает Разрешить.
Бот получает токен
Браузер возвращается на адрес вашего сервера с кодом, сервер обменивает код на токен сотрудника. В витрине у бота появляется отметка Подключено.
Как собрать кнопку и обменять код — в разделе Получение токена.
Где включается
Авторизация включается на вкладке OAuth в карточке бота: там выдаются client_id и client_secret, задаются адреса возврата и набор прав, который бот попросит у сотрудника. Подробнее — в разделе Настройка авторизации.
Одной вкладки мало: авторизация проходит через диалог с ботом, поэтому боту нужны ещё исходящий вебхук и токен. Всё, что должно быть включено, собрано в Чек-листе запуска.
Ограничения
- Только своё пространство. Авторизовать бота может сотрудник того же пространства, где создан бот.
- По умолчанию — только администраторам. Авторизовать бота может тот, кому разрешено создавать персональные токены. По умолчанию это только администраторы: пока владелец или администратор не выберет Все сотрудники в настройке Кто может создавать персональные токены, сотрудники и мульти-гости авторизовать бота не могут. Подробнее — в разделе Кто может создавать токены.
- Гостям недоступно. Гость не может авторизовать бота ни при какой настройке, а мульти-гость может, как и сотрудник.
- Роль урезает права. Право из набора, недоступное роли сотрудника, работать не будет: вызов с таким токеном вернёт
403. - Набор прав один. Бот не выбирает права при каждой авторизации: запрашивается ровно то, что задано в его настройках.