Создание бота
Бота можно создать двумя способами:
- Через интерфейс — в разделе Интеграции > Боты. Подходит для ручной настройки: у каждой возможности бота своя вкладка в его карточке.
- Через API (POSTНовый бот) — программно, без интерфейса. Подходит для автоматизации: завести бота из своего сервиса или скрипта и сразу получить
access_token.
Создавать ботов могут администраторы и сотрудники, а владелец или администратор пространства может оставить это только администраторам. Подробнее — в разделе Кто может создавать токены.
Создание бота через интерфейс
Создание и настройка ботов через интерфейс доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна.
Откройте Интеграции > Боты и нажмите Создать бота. В диалоге два поля:
- Название — имя бота в чатах и в его профиле.
- Ник для @упоминаний — латиница, цифры и
_, в конце_bot. Можно оставить пустым, тогда ник соберётся из названия. Ник уникален в пространстве.
Создание бота
После создания откроется карточка бота. Бот создаётся без токенов и вебхуков, а каждая возможность включается на своей вкладке, когда понадобится. Чаще всего сразу нужны четыре шага:
Выпустите токен
На вкладке API нажмите Создать токен, задайте название и права. Значение токена показывается один раз: скопируйте его до закрытия окна. Подробнее — в разделе Токены бота.
Настройте доступ
На вкладке Основное решите, кто может добавлять бота в чаты и кто может его редактировать, и нужен ли публичный бот. Там же меняются имя, аватар и ник. Подробнее — в разделе Настройки бота.
Включите исходящий вебхук
Чтобы бот узнавал о сообщениях и нажатиях кнопок, на вкладке Исходящий вебхук нажмите Включить, укажите URL своего сервера и отметьте события. Для новых сообщений выберите режим: новый бот слушает только команды, а их список пуст. Подробнее — в разделах Настройка и типы событий и Общение с ботом.
Добавьте бота в чаты
Новый бот не состоит ни в одном чате. Добавьте его в беседы и каналы, где он будет работать, или позовите по нику в треде, а в личные сообщения ему пишут сами. Подробнее — в разделе Доступы к чатам и сообщениям.
Созданный бот появится на вкладке Управление — подробнее в разделе Где бот находится в интерфейсе.
Создание бота через API
Бота можно создать программно методом POSTНовый бот — без интерфейса. Это удобно, когда нужно завести бота из своего сервиса или скрипта.
Отправьте запрос на создание
Передайте параметры бота в объекте webhook: имя, никнейм, Webhook URL, список событий и команды. Обязательное поле одно — имя. Никнейм должен заканчиваться на _bot.
По умолчанию trigger_on равен commands, а список команд пуст, поэтому о новых сообщениях бот не узнает. Если бот должен отвечать на сообщения, передайте trigger_on: "all_messages" или перечислите команды в commands.
В том же запросе можно включить авторизацию от имени сотрудника объектом oauth_client — подробнее в разделе Настройка авторизации.
Сохраните access_token
В ответе вы получите access_token бота — сразу сохраните его. Повторно значение не показывается ни в интерфейсе, ни через API: потерянный токен перевыпускают. Вместе с токеном придёт id бота (его user_id).
Бот, созданный через API, сразу принимает запросы на входящий вебхук — подробнее в разделе Входящие вебхуки.
Чтобы создать бота как в интерфейсе, без токена и входящего вебхука, передайте empty: true. Токены такому боту выпускают методом POSTНовый токен бота, а входящий вебхук включают полем kind.
Жизненный цикл через API
Получить параметры существующего бота можно методом GETИнформация о боте, а изменить — методом PUTРедактирование бота. Какие поля за какую вкладку отвечают — в разделах Настройки бота, Входящие вебхуки, Исходящие вебхуки и Настройка авторизации. Адрес исходящего вебхука бот может прописать и сам — методом PUTСаморегистрация вебхука бота.
- GETСписок ботов — боты, доступные вам для редактирования, с поиском по имени в параметре
query. Полный перечень ботов пространства доступен Владельцу отдельным методом, см. Права и роли. - GETСписок токенов бота, POSTНовый токен бота и соседние методы — токены бота со своими именами и правами. Подробнее — в разделе Токены бота.
- POSTРотация токена бота и POSTРотация собственного токена бота — перевыпуск основного токена.
- POSTРотация секрета клиента — новый
client_secretдля авторизации от имени сотрудника. - DELETEУдаление бота — удаление без возможности отмены, подробнее в разделе Удаление бота.
Изменения бота попадают в журнал аудита: выпуск, изменение и перевыпуск токенов, смена адреса исходящего вебхука, настроек истории событий и своих сообщений, списков доступа к боту, смена настроек авторизации, обновление секрета, выключение авторизации и удаление бота.