Обзор PartyFlow Integrations#

PartyFlow даёт четыре способа интеграции внешних сервисов с каналами:

1. Incoming webhooks — внешний сервис шлёт сообщения в канал (alerts, notifications, release notes).
2. Outgoing webhooks — PartyFlow шлёт события из канала (сообщения, реакции, создание каналов) на ваш HTTPS endpoint. Подходит для ботов-получателей, AI/LLM агентов, аудит-приёмников.
3. Bots — отдельные аккаунты-приложения с REST API для двусторонней работы: отправка сообщений, загрузка файлов, Agent Runs, Execution Tasks, участие в каналах.
4. Slash commands — пользователь набирает /команда в чате, встроенная команда возвращает результат.

Эта страница объясняет, какой сценарий для чего подходит. Дальше — quickstart, чтобы собрать первый работающий webhook за 5 минут.

Incoming webhooks#

Когда использовать

• У вас есть сервис (Grafana, GitHub, Sentry, CI/CD, custom), который умеет POST'ить JSON по URL и хочет присылать сообщения в канал.
• Поток — односторонний: только от внешнего сервиса → в канал. Обратно реакция по сообщению в канал не передаётся.
• Отправитель не нужно "приглашать" в канал — webhook привязан к каналу при создании.

Что получаете

• Уникальный URL вида https://api.partyflow.ru/api/v1/webhooks/incoming/<token>.
• HMAC signing secret для подписи запросов.
• Поддержку Slack-формата (text, attachments, blocks) и Pachca-формата (message.content, buttons, files). Один endpoint определяет формат по структуре payload автоматически.
• Тонкую политику push-уведомлений: silent, severity: critical/warning/info, mentions[].

Типичные сценарии

• Grafana alerts в #alerts.
• Release notes из CI/CD в #releases.
• Daily digest из аналитики в #analytics.

Технические лимиты (публичные)

• До 5/10/30 сообщений в секунду на webhook (зависит от тарифа).
• Payload до 256 KB.
• 100 подряд ошибок подряд → webhook автоматически отключается, требует ручного включения.

См. concepts/webhooks.md и reference/http-webhook-endpoint.md.

Outgoing webhooks#

Когда использовать

• Вам нужно реагировать на события в канале: новое сообщение, реакция, создание канала.
• Пишете AI/LLM-агента, которому нужен контекст последних сообщений канала.
• Строите аудит: каждое событие уезжает во внешний SIEM / Kafka / логгер.

Что получаете

• Подписка на конкретные event_types: MESSAGE_CREATED, MESSAGE_UPDATED, MESSAGE_DELETED, REACTION_ADDED, REACTION_REMOVED, CONVERSATION_CREATED, CONVERSATION_ARCHIVED.
• Фильтры: по channel_ids, по триггеру (all / mention конкретного бота / keywords).
• Опциональный context — последние N сообщений канала (1..50) для AI-промптов.
• HMAC-SHA256 подпись каждого запроса (X-PartyFlow-Signature: sha256=...), фиксированная перед первой отправкой — retry всегда с той же подписью.
• Retry с exponential backoff (конфигурируемое расписание; на текущих production-дефолтах — 8 попыток, полное окно ~10 минут 35 секунд с ±20% jitter), honoring Retry-After заголовка.
• Auto-disable подписки после 100 подряд неуспешных доставок.

Типичные сценарии

• AI-помощник: подписка на MESSAGE_CREATED + trigger: mention → бот отвечает только когда его @упомянули.
• Аудит: подписка на все MESSAGE_* + REACTION_* во всех каналах → зеркалит в SIEM.
• Keyword-based alerts: подписка на keywords: ["error", "fatal"] → в свой on-call канал внешним пушем.

Технические лимиты (публичные)

• URL — только HTTPS в production (SSRF-фильтр блокирует приватные диапазоны).
• До 50 сообщений контекста enrichment'а.
• До 20 ключевых слов на подписку в режиме keywords.
• 100 подряд dead-letter'ов → подписка автоматически отключается.

См. reference/outgoing-webhooks.md, concepts/webhooks.md#outgoing-webhooks, guides/verify-signatures.md.

Bots#

Когда использовать

• Вам нужен именованный участник в канале (с аватаром и display name), а не просто постинг сообщений "из Grafana".
• Бот должен отправлять в несколько разных каналов в пределах одного workspace (space).
• Вы хотите, чтобы пользователи могли @mention'ить бота, упоминать его в списке участников, делать через него структурированные диалоги.

Что получаете

• Bot token вида fri_bot_<token>, выдаётся один раз при создании.
• REST API /api/v1/bot/messages для отправки сообщений и top-level file attachments.
• Bot Files API для загрузки файлов через short-lived upload URL.
• Agent Runs для долгих AI-ответов и Execution Task widgets для видимых агентских задач с review/final artifacts.
• /api/v1/bot/me для самопроверки.
• Возможность вступать в каналы от имени бота (/api/v1/bot/conversations/{id}/join).

Типичные сценарии

• AI-агент: отвечает на упоминание, создаёт task widget, показывает runtime status через Agent Run и прикладывает final artifacts к задаче.
• Помощник по onboarding: приветствует новых участников space'а.
• Standup-бот: каждый день пишет "что делали вчера" и собирает ответы.
• Linkbot: разворачивает карточки JIRA/Linear/Notion по ссылкам.

См. concepts/bots.md и reference/bot-rest-api.md.

Slash commands#

Встроенные (available)

Кастомные (available) — бот регистрирует свою команду через REST API. PartyFlow доставляет invocation через Poll API, если бот в event_delivery_mode="poll", или шлёт HMAC-подписанный POST на callback URL команды. Доступно с 2026-04-19.

См. concepts/slash-commands.md и reference/slash-commands.md.

Безопасность#

• Все webhooks по умолчанию требуют HMAC-подпись запросов (Slack-схема X-Slack-Signature или PartyFlow-native X-PartyFlow-Signature).
• Для простых кейсов (CI/CD, мониторинг без подписи) admin может создать webhook в token-only режиме.
• Bot tokens — 256 бит энтропии, хранятся в БД как SHA-256 hash.
• Все secrets показываются один раз при создании/ротации. Сохраните сразу.

Подробно — concepts/security.md.

Что доступно сейчас и что планируется#

Available сегодня (актуально на 2026-05-25):

• Incoming webhooks (Slack + Pachca форматы, HMAC, push-policy)
• Outgoing webhooks (подписка на события канала с HMAC-подписью, retry, context enrichment)
• Bots + REST API (сообщения, file attachments через Bot Files, Agent Runs, Execution Tasks, чтение истории канала ботом — GET /api/v1/channels/{id}/messages)
• Встроенные slash-команды (/poll, /remind)
• Кастомные slash-команды (бот регистрирует /deploy, /report и т.п.; доставка через callback или Poll API)
• Interactive components: кнопки, select menus, модальные формы в сообщениях ботов; доставка через callback или Poll API

Planned (ориентир — Q2 2027):

• События MEMBER_JOINED / MEMBER_LEFT в outgoing webhooks
• OAuth 2.0 provider и публичный App Directory
• Расширенное управление outgoing подписками через Admin UI

Актуальный статус см. changelog.md.

Следующие шаги#

1. quickstart.md — поднять первый webhook за 5 минут.
2. concepts/security.md — разобраться с HMAC перед продом.
3. guides/send-grafana-alerts.md — закрыть типовой сценарий "alert'ы → канал".