Для разработчиков

Создание и настройка

Бота можно создать двумя способами:

  • Через интерфейс — отдельные настройки (тип бота, аватар) и наглядная пошаговая форма. Подходит для разовой ручной настройки.
  • Через API (POSTНовый бот) — программно, без интерфейса. Подходит для автоматизации: завести бота из своего сервиса или скрипта и сразу получить access_token.

Создание бота через интерфейс

Создание и настройка ботов через интерфейс доступны в веб-версии и десктопном приложении Пачки. В мобильных приложениях (iOS и Android) эта возможность недоступна.

Для создания бота перейдите в Автоматизации > Интеграции > Чат-боты и Вебхуки и нажмите кнопку «+».

Новый бот

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

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

  • Для одного чата — подойдёт для отправки уведомлений из других сервисов. В одном чате можно собрать всех получателей и обсуждать уведомления в тредах.
  • Для нескольких чатов — подойдёт, если вы хотите создать личное взаимодействие бота с каждым участником вашей компании или разными группами участников.
  • Unfurl бот (только администраторам) — подойдёт для получения событий об отправке ссылок во всех чатах вашего пространства и возможности создавать их предпросмотр.

Тип бота нельзя изменить после создания. Ограничение «для одного чата» распространяется только на каналы и беседы — бот по-прежнему может участвовать в тредах и личных сообщениях. Бот любого типа может быть настроен как публичный.

Скопируйте токен

После создания бота перейдите на вкладку API и скопируйте access_token — он потребуется для работы с API от имени бота. Токен не имеет срока жизни. Там же доступен user_id бота — используется, например, для POSTдобавления бота в чат.

Измените название и аватар (опционально)

На вкладке Основное вы можете изменить имя бота и загрузить изображение — они будут отображаться в сообщениях от бота и в его профиле.

Настройте исходящий вебхук (опционально)

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

Создание бота через API

Бота можно создать программно методом POSTНовый бот — без интерфейса. Это удобно, когда нужно завести бота из своего сервиса или скрипта.

Отправьте запрос на создание

Передайте параметры бота в объекте bot.webhook: имя, никнейм, Webhook URL, список событий и команды. Никнейм должен заканчиваться на _bot.

Тип бота — в один или несколько чатов — задаётся полем single_chat и только при создании: изменить его потом нельзя, как и тип бота в интерфейсе. Ограничение «в один чат» распространяется только на беседы и каналы, треды и личные сообщения не в счёт.

Сохраните access_token

В ответе вы получите access_token бота — сразу сохраните его. Повторно получить токен вы сможете только через интерфейс (вкладка API настроек бота), там же его можно перевыпустить. Вместе с токеном придёт id бота (его user_id).

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

Профиль бота

Бот, как и любой участник пространства, имеет свой профиль. В нём отображаются имя, аватар, никнейм, статус и список общих чатов с ботом. Профиль бота можно редактировать — изменить имя, никнейм и другие поля.

Никнейм — уникальный идентификатор бота для упоминания через @. Именно по никнейму сотрудники могут упоминать бота в сообщениях и добавлять его в сквозные треды. Никнейм и другие поля профиля можно изменить через интерфейс или через API — метод PUTРедактирование сотрудника.

Настройка доступов

Эти настройки находятся на вкладке Основное.

Настройка доступов к боту

Кто может редактировать настройки бота

Управление доступов участников пространства к поиску бота в разделе Чат-боты и Вебхуки и редактированию его настроек (основных, вебхуков и токена API):

  • Создатель — этот пункт нельзя отключить, создатель бота всегда имеет доступ к настройкам бота
  • Администраторы — владелец и участники пространства с ролью «Администратор»
  • Создатели и руководители чатов, в которые добавлен бот — этот пункт позволяет управлять доступом к редактированию бота на уровне ролей в чате, куда добавлен бот

Кто может добавлять бота в чаты

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

  • Создатель
  • Создатель и Администраторы
  • Все участники (кроме гостей)
  • Публичный бот

Настройка через API

Эти доступы можно задать не только в интерфейсе, но и через API — методом PUTРедактирование бота или сразу при создании:

  • Кто может редактировать настройки бота — поле can_edit (роли admin и chat_owners). Создатель имеет доступ всегда, поэтому в поле перечисляются только дополнительные роли, а пустой массив означает «только создатель»
  • Кто может добавлять бота в чаты — поле who_can_add (creator, creator_admin, creator_admin_user, anyone)

Настройка вебхуков и API

Вкладки настройки вебхуков и API бота

Входящий Webhook

Позволяет отправлять сообщения в чат от имени бота одним HTTP-запросом — без использования API. В настройках доступны Webhook URL, выбор формата отображения (Liquid или Mustache), шаблон сообщения и поле для верификации (например, для интеграции с monday.com). Подробнее — в разделе Входящие вебхуки.

Исходящий Webhook

Позволяет получать уведомления о событиях в реальном времени на указанный вами URL. В настройках доступны Webhook URL, Signing secret для проверки подлинности запросов, выбор типов событий (новые сообщения, реакции, нажатия кнопок, изменение участников и другие) и фильтрация по командам. Подробнее — в разделе Исходящие вебхуки.

API

Вкладка с access_token и user_id бота для работы с REST API. Токен не имеет срока жизни, но при необходимости его можно перевыпустить кнопкой «Обновить Access token». Подробнее — в разделе Авторизация.