Настройка и типы событий
Все настройки исходящего вебхука собраны на вкладке Исходящий вебхук в карточке бота. Пока вебхук выключен, на вкладке одна кнопка Включить: она спрашивает URL вашего сервера, а остальные настройки появляются после включения.
Вкладка «Исходящий вебхук» в карточке бота
Общие настройки
- Webhook URL — адрес, на который Пачка отправляет события. Подходит только публичный адрес
httpилиhttps: локальные и внутренние адреса не принимаются, для разработки подойдёт туннель. - Signing secret — ключ HMAC-SHA256 для проверки подписи из заголовка
Pachca-Signature. Появляется после включения вебхука. Подробнее — в разделе Безопасность и обработчик. - Сохранять историю событий — бот сохраняет все исходящие вебхуки в очередь, и их можно получить через API. Подробнее — в разделе Поллинг.
- Игнорировать свои сообщения — не получать вебхуки о сообщениях, отправленных самим ботом, и о реакциях, которые он сам поставил или снял. Реакции других участников на сообщения бота приходят всегда. Предотвращает зацикливание, когда бот реагирует на собственные сообщения. Нажатия кнопок обрабатываются всегда, вне зависимости от этой настройки.
Кнопка Удалить вебхук внизу вкладки отключает вебхук: события перестают доставляться, история событий, режим новых сообщений и «Игнорировать свои сообщения» возвращаются к начальным значениям, а Signing secret выпускается новый. Если включить вебхук снова, он, как новый, подписан на новые сообщения.
Какие события откуда приходят
События отмечают в списке на той же вкладке. Большинство приходит из чатов, где состоит бот, и из их тредов. Тред, куда бота добавили без родительского чата, — тоже такой чат.
| Событие на вкладке | Значения в events | Откуда приходит |
|---|---|---|
| Новые сообщения | message_new | Чаты, где состоит бот, и их треды |
| Редактирование и удаление сообщений | message_update, message_delete | Чаты, где состоит бот, и их треды |
| Добавление и удаление реакций | reaction_new, reaction_delete | Чаты, где состоит бот, и их треды |
| Нажатие кнопок | button_click | Нажатия кнопок в сообщениях самого бота и отправка форм, которые он открыл |
| Изменение состава участников чатов | chat_member_add, chat_member_remove | Чаты, где состоит бот, и их треды |
| Изменение участников пространства | company_member_invite, company_member_confirm, company_member_suspend, company_member_activate, company_member_delete, company_member_update | Всё пространство |
| Отправка ссылок в сообщении (unfurl) | message_link_shared | Все чаты пространства, только ссылки на домены бота |
| Начало видеозвонка, Завершение видеозвонка, Готовность записи видеозвонка | video_call_started, video_call_finished, video_call_recording_ready | Чаты, где состоит бот, и их треды |
Через API
Те же настройки задаются в объекте webhook метода PUTРедактирование бота или сразу при создании методом POSTНовый бот, а текущие значения возвращаются в объекте бота:
| Настройка | Поле |
|---|---|
| Webhook URL | outgoing_url, пустая строка отключает вебхук |
| События | events — значения из таблицы выше |
| Режим новых сообщений | trigger_on: all_messages или commands |
| Команды | commands — список команд, вместе через запятую не длиннее 255 символов |
| Сохранять историю событий | events_history_enabled |
| Игнорировать свои сообщения | ignore_self_messages |
| Домены для ссылок | unfurl_domains |
Персональному токену для этого нужен скоуп bots:write и доступ к настройкам бота. Бот может и сам прописать свой адрес собственным токеном — методом PUTСаморегистрация вебхука бота со скоупом bot_self:webhook:write, без участия администратора: так, например, n8n регистрирует свой адрес. Боту с включённым разворачиванием ссылок адрес меняет только администратор или владелец, и саморегистрация вернёт ошибку.
Signing secret через API не задаётся, а читается: он приходит в поле secret_token метода GETИнформация о боте, если у токена есть скоуп bots:write и вы можете управлять токенами бота.
Сообщения
В настройках доступны два отдельных пункта:
- Новые сообщения — создание сообщений
- Редактирование и удаление сообщений — изменение текста или файлов и удаление сообщений
Для новых сообщений доступны два режима отслеживания:
- Любые сообщения — все новые сообщения, включая треды
- Начинающиеся с команд — только сообщения, первое слово которых совпадает с одной из команд, например
/helpили/deploy. Команды перечисляются через запятую, совпадение проверяется точно, с учётом регистра. Полезно, если вы не хотите получать поток событий, а вам нужно вызвать сценарий только по требованию пользователя.
Режим действует и на редактирование: в режиме «Начинающиеся с команд» о правке приходят только сообщения, которые начинаются с команды. Удаления приходят всегда.
trigger_on. Выберите режим «Любые сообщения» или перечислите команды. Подробнее — в разделе Общение с ботом.content придёт пустой строкой. Вложения, реакции, кнопки, информацию о пересланном сообщении и другие поля получите методом GETИнформация о сообщении по полю id. Для события delete метод по-прежнему отвечает 200, но возвращает уже очищенную запись: content пустой, вложения и реакции удалены, заполнено поле deleted_at. В списке сообщений такая запись не возвращается.Реакции
Вебхук отправляется при добавлении или удалении реакции на сообщение.
message_id или автора методом GETИнформация о сотруднике по user_id.Нажатие кнопок
Вебхук отправляется при нажатии Data-кнопки в сообщении от бота. После получения вы можете изменить или удалить кнопки методом PUTРедактирование сообщения или ответить пользователю методом POSTНовое сообщение. Подробнее — в разделе Кнопки в сообщениях.
message_id.Заполнение формы
Вебхук отправляется при отправке пользователем заполненной формы (представления). Подробнее об обработке результатов — в разделе Обработка форм. Если у бота не задан адрес исходящего вебхука, ответить на это событие можно методом POSTОтвет на отправку формы по view_id и submit_id из payload.
chat_id фиксируется в момент открытия формы (нажатия кнопки), а не её отправки: если форма провисела открытой долго, поле всё равно ссылается на чат с кнопкой.data, дополнительных запросов не требуется. При необходимости получите автора методом GETИнформация о сотруднике по user_id.Изменение участников чатов
Вебхук отправляется при изменении состава участников чата.
user_id, а сам чат — методом GETИнформация о чате по chat_id.Изменение участников пространства
Вебхук отправляется, когда участника пространства приглашают, он принимает приглашение, его приостанавливают, снова активируют или удаляют, а также когда меняются его данные. Добавлять бота в чат не нужно.
user_id.Отправка ссылок
Вебхук отправляется при появлении в сообщении ссылки на один из доменов бота — из любого чата пространства, добавлять бота в чаты не нужно. Событие Отправка ссылок в сообщении (unfurl) и его домены (до 5, через запятую) включает только администратор или владелец пространства. После получения вы можете воспользоваться методом POSTUnfurl (разворачивание ссылок) и создать предпросмотр ссылки в сообщении. Подробнее — в разделе Разворачивание ссылок.
message_id.Видеозвонки
Вебхук отправляется о видеозвонках. Поле event в payload различает три события: started (звонок начался), finished (звонок завершился) и recording_ready (запись готова). Набор полей payload зависит от события.
finished payload содержит список участников с временем подключения и выхода, для recording_ready — ссылку на файл записи, её размер и длительность. Полные данные участников получите методом GETИнформация о сотруднике по каждому user_id, а чат — методом GETИнформация о чате по chat_id.