PartyFlow

Public API Changelog — Integrations#

Публичные изменения API внешних интеграций. Breaking changes помечаются BREAKING.

Формат записи: YYYY-MM-DD — раздел — что изменилось + ссылки на затронутые публичные доки.

2026-05-25 — Bot REST reference discoverability#

Reference-документация Bot REST API обновлена для developer portal: добавлена карта endpoint'ов, явный flow загрузки файлов через Bot Files API и ссылки на attachments, Agent Runs, Execution Tasks и runtime_capability.token.

API contract не менялся.

Затронутые доки:

2026-05-24 — Bot REST execution tasks#

Bot REST API получил v1 endpoints для execution task widgets и связь с Agent Runs.

  • Новый POST /api/v1/bot/execution_tasks.
  • Новый GET /api/v1/bot/execution_tasks/{widget_id}.
  • Новый PATCH /api/v1/bot/execution_tasks/{widget_id}.
  • Новый POST /api/v1/bot/execution_tasks/{widget_id}/cancel.
  • POST /api/v1/bot/agent_runs принимает optional widget_id.
  • Terminal PATCH /api/v1/bot/agent_runs/{run_id} для linked widget_id обновляет task и передаёт только проверенные финальные файлы.
  • runtime_capability.token scoped к space_id, widget_id, optional agent_run_id, allowed actions и expiry; token показывается один раз.

Затронутые доки:

2026-05-23 — Bot REST file attachments#

Bot REST API получил загрузку файлов через short-lived upload URL и прикрепление файлов к bot messages / final Agent Run messages.

  • Новый POST /api/v1/bot/files/upload_sessions.
  • Новый POST /api/v1/bot/files/{file_id}/confirm.
  • Новый GET /api/v1/bot/files/{file_id}/download_url.
  • POST /api/v1/bot/messages принимает attachments: [{"file_id": "..."}]; теперь нужен content или хотя бы один attachment.
  • PATCH /api/v1/bot/agent_runs/{run_id} принимает final attachments только при status="completed" и возвращает attachments + attachment_status.
  • Upload использует приватное хранилище PartyFlow; постоянные идентификаторы хранилища не возвращаются через публичный API.

Затронутые доки:

2026-05-20 — Bot Agent Runs / responsive status#

Bot REST API получил Agent Runs для долгих AI-ответов: бот создаёт placeholder-сообщение, затем обновляет безопасный статус через тот же message flow. Пользователи видят обычные message.new / message.edited; отдельного agent.run.* stream в MVP нет.

  • Новый POST /api/v1/bot/agent_runs.
  • Новый PATCH /api/v1/bot/agent_runs/{run_id} с монотонным sequence.
  • Новый GET /api/v1/bot/agent_runs/{run_id}.
  • Новый POST /api/v1/bot/agent_runs/{run_id}/cancel.
  • POST /api/v1/bot/agent_runs требует Idempotency-Key header или body-поле idempotency_key; повтор с тем же ключом возвращает существующий run без второго placeholder, а reuse ключа для другого conversation/trigger возвращает 409.
  • Agent Run writes требуют, чтобы бот был участником conversation, и ограничены rate limit'ом с 429 Retry-After.
  • bot_metadata_json.kind="agent_run" содержит server-generated status_text, sequence, is_terminal, updated_at, completed_at и безопасный error_code.

Затронутые доки:

2026-05-14 — BREAKING Interactive callback payload canonical fields#

Interactive callbacks и interactive poll payload теперь используют canonical flat-поля без отдельной v2 версии: event_type, space_id, actor_user_id, occurred_at.

  • space_id обязателен во всех button.click, select.submit, modal.submit payload и берётся из server-authoritative контекста PartyFlow.
  • Старые поля type, user_id, timestamp удалены из interactive callback body и payload_json.
  • button.click и select.submit содержат data; select.submit дополнительно содержит selected_value; modal.submit содержит values и не содержит data.

Затронутые доки:

2026-05-13 — Unified bot message context#

В bot-facing события сообщений добавлен единый объект conversation_context.

  • Для MESSAGE_CREATED, MESSAGE_UPDATED, MESSAGE_DELETED в Bot Event Polling, Bot Webhook и outgoing webhook data теперь можно отличить DM, public/private беседу, обычный thread и Call Thread без эвристик по ID.
  • Bot DM SSE (GET /api/v1/bot/stream) использует те же message-поля и тот же conversation_context, плюс SSE-поле event: "message.new".
  • conversation_context.type — raw conversation type, scope — dm / public / private, subtype="call_thread" ставится только для треда гостевого voice-чата.
  • Старые flat-поля conversation_id, thread_id, parent_message_id сохранены для обратной совместимости.

Затронутые доки:

2026-05-12 — Developer docs cleanup#

No API changes. Из внешней документации убраны сведения, предназначенные для реализации UI-клиента PartyFlow. Разделы Integrations теперь описывают только bot-side и webhook-сценарии для внешних разработчиков.

2026-04-28 — Built-in slash commands: scope-drift cleanup#

Закрыли расхождения между описанием и реализацией встроенных команд /poll и /remind:

  • /poll авто-реакции. В ответ message.send.response для успешного /poll добавлено поле auto_reactions: string[] со списком emoji (1️⃣ … 🔟) в порядке вариантов. Клиент-отправитель должен пройтись message.toggleReaction по этому списку, чтобы пользователи могли голосовать кликом по реакции. Поле отсутствует/пусто для ephemeral-ответов и команд без авто-реакций.
  • /remind @user. Теперь поддерживается напоминание другому участнику канала: /remind @alice "review" in 2h. @user должен быть в mention_details обычной системы упоминаний (как в чате). При срабатывании bot-сообщение содержит mention_user_ids: [target], поэтому целевой пользователь получает push.
  • /remind #channel — поддерживается: бот публикует напоминание в указанный канал. Имя резолвится по индексу, поэтому работает быстро даже на крупных space-ах. Авторизация — та же, что и у обычного сообщения: только каналы, где вы участник; private-каналы и не-найденные имена возвращают одинаковое "Канал #<name> не найден или у вас нет к нему доступа." (защита от enumeration). Тред исходного канала не наследуется в напоминание для #channel (тред принадлежит исходному каналу).
  • /remind at HH:MM теперь в локальной таймзоне отправителя. До этого время трактовалось как UTC — at 14:00 могло прозвонить за полдня раньше/позже от ожидаемого. Таймзона берётся из профиля пользователя (timezone); при отсутствии — fallback в UTC. Confirmation-сообщение содержит таймзону для прозрачности ("… на 14:00 Europe/Moscow").

Затронутые доки:

Совместимость: запросы фронта не ломаются — auto_reactions опциональное, отсутствие @user в mention_details даёт ephemeral-ошибку (раньше поведение было то же — все таргеты молча превращались в me). Старые клиенты, не реагирующие на auto_reactions, продолжат показывать /poll как plain bot-сообщение без интерактивных голосов.

2026-04-19 — Управление outgoing webhooks и interactive config в Admin UI#

Admin UI теперь поддерживает полный цикл управления outgoing webhook'ами и настройками интерактивных ботов: создание, просмотр, обновление, удаление, тестовую отправку, ротацию секретов и просмотр истории доставок.

Для interactive components админ может настроить или очистить callback URL и перевыпустить buttons_signing_secret. Plaintext-секрет возвращается только один раз: при первом включении или при ротации. В списках, уведомлениях и повторных ответах секрет не показывается.

Затронутые доки:

Всё ещё Planned:

  • Локализация error-сообщений для новых interactive config flows.

Post-publish fix (2026-04-19): уведомление об auto-disable подписки теперь отображается в Admin UI после 100 подряд неуспешных доставок.

2026-04-19 — Bot Read API, Custom Slash Commands, Interactive Components (GA)#

Phase 2 дополняет outgoing webhooks тремя отдельно полезными возможностями — чтением истории канала ботом, кастомными slash-командами и интерактивными элементами (кнопки, select menus, модалки).

Bot Read API. Новый endpoint GET /api/v1/channels/{conversation_id}/messages позволяет боту получать историю канала под Bearer auth. Поддерживаются курсоры before_msg_index / after_msg_index / around_msg_index (один за раз), фильтр thread_id, delta-sync updated_since. Privacy-филтр — whitelist полей: read_receipts, edit_history, delivery_status, parent_preview и mention_details ботам не возвращаются. System-события (is_system: true, joins/renames) выдаются — они нужны AI summarizer'ам. Rate limit — 10 запросов/мин на канал × 100 запросов/мин на бота. Полный справочник — reference/bot-rest-api.md.

Custom slash commands. Бот регистрирует свои команды через POST /api/v1/bots/{bot_id}/commands и получает signing_secret (один раз). Когда пользователь вводит /deploy prod, PartyFlow шлёт HMAC-подписанный POST на callback_url с payload {command, command_id, args, text, user_id, conversation_id, trigger_id, ...}. Бот отвечает response_type: "in_channel" / "ephemeral" в течение 3 секунд ИЛИ пустым телом и дошлёт результат через POST /api/v1/bot/messages + заголовок X-PartyFlow-Trigger-Id (TTL 5 мин, single-use). Ограничения: имя ^[a-z][a-z0-9_-]{0,31}$, rate limit 30/мин на пользователя × команду + 300/мин на команду глобально, cap 25 команд на бота / 100 на space. Полный справочник — reference/slash-commands.md.

Interactive components. Бот прикрепляет кнопки, select menus и модалки к сообщениям через bot_metadata_json (schema {version: 1, blocks: [{type: "actions", elements: [...]}]}). При клике PartyFlow шлёт HMAC-подписанный POST на отдельный buttons_callback_url (конфигурируется через PATCH /api/v1/bot/interactive_config с отдельным buttons_signing_secret). Бот отвечает одним из: update_message (редактируется текущее сообщение), send_message (отправляется новое), ephemeral_text (показывается только кликавшему), open_modal (открывается форма, submit проходит отдельным запросом с single-use token TTL 15 мин), noop. Visibility: поле visibility_user_ids на элементе ограничивает, кто может видеть/кликать. Rate limit: 30 кликов/мин на пользователя × сообщение + 600 кликов/мин на бота глобально. Signed tokens v1.exp.sig автоматически проставляются PartyFlow при send/edit сообщения — боту их считать не нужно. Полный справочник: reference/interactive-components.md.

Затронутые доки:

Всё ещё Planned:

  • События MEMBER_JOINED / MEMBER_LEFT в outgoing webhooks.
  • OAuth 2.0 provider и публичный App Directory.
  • Performance / sustained-load гарантии (публичные SLO по p95 и throughput).

2026-04-18 — Outgoing webhooks (GA)#

Outgoing webhooks переведены в General Availability. Теперь внешние сервисы могут получать события из каналов PartyFlow по HTTPS POST с HMAC-подписью.

Что доступно:

  • Подписка на 7 event types: MESSAGE_CREATED, MESSAGE_UPDATED, MESSAGE_DELETED, REACTION_ADDED, REACTION_REMOVED, CONVERSATION_CREATED, CONVERSATION_ARCHIVED.
  • Фильтры доставки: по channel_ids (пусто = все каналы), по trigger (all / mention конкретного бота / keywords с whole-token matching).
  • HMAC-SHA256 подпись (X-PartyFlow-Signature: sha256=<hex>), signing string v1:{timestamp}:{body}. Все подписи фиксируются перед первой отправкой — retry всегда с той же подписью.
  • Заголовки: X-PartyFlow-Signature, X-PartyFlow-Timestamp, X-PartyFlow-Delivery-Id (UUIDv7, для idempotency), X-PartyFlow-Event, X-PartyFlow-Webhook-Version: 1.
  • Retry schedule: exponential backoff с конфигурируемыми Initial / Max / MaxAttempts и ±20% jitter. Production-дефолты — Initial = 5s, Max = 1h, MaxAttempts = 8, что даёт последовательность 5s → 10s → 20s → 40s → 80s → 160s → 320s перед dead-letter; полное retry-window — ~10 минут 35 секунд. Honor'им Retry-After при 429/503 (RFC 7231 header + JSON body + plaintext fallback, clamp 1s..1h).
  • Auto-disable подписки после 100 подряд dead-letter'ов.
  • Опциональный context enrichment: до 50 последних сообщений канала в payload.context.messages[] — для AI/LLM получателей.
  • SSRF-защита: URL проверяется на каждом create/update и перед каждой dispatch (DNS resolve, CIDR blocklist).
  • HTTPS обязателен в production.

Затронутые доки:

Всё ещё Planned:

  • События MEMBER_JOINED / MEMBER_LEFT (API уже есть, publisher пока не эмитит).
  • Кастомные slash-команды — пользователь регистрирует свой HTTP endpoint под /команду.
  • Кнопки в сообщениях ботов.
  • Расширенное управление outgoing подписками через Admin UI.
  • Performance / sustained-load гарантии (публичные SLO по p95 и throughput).

2026-04-17 — Инициализация документации#

  • Создана папка docs/public/integrations/. Готов базовый набор: overview, quickstart, security, changelog, два reference'а (HTTP webhook endpoint, Bot REST API).
  • Добавлены внутренние правила ведения публичной документации.

2026-04-16 — Push policy для webhook-сообщений#

  • Добавлены поля silent, severity, mentions[] в payload incoming webhook'а.
  • Push теперь шлётся только при @mention (Slack-style policy).
  • severity: critical пробивает quiet hours / DND получателя (но уважает явно заглушённые каналы).
  • Затронутые доки: reference/http-webhook-endpoint.md, quickstart.md.

2026-04-16 — HMAC обязателен по умолчанию#

  • require_signature: true теперь default при создании webhook'а.
  • Для CI/CD и simple scripts admin может явно выбрать require_signature: false (token-only режим).
  • Webhook в token-only режиме всё равно генерирует и хранит signing secret — это позволяет включить подпись позже без пересоздания.
  • Затронутые доки: concepts/security.md, reference/http-webhook-endpoint.md, quickstart.md.

2026-04-16 — Ротация signing secret без смены URL#

  • Теперь доступна отдельная ротация signing secret: URL webhook'а не меняется, меняется только secret.
  • Rotate token (старое поведение) по-прежнему меняет и URL, и signing secret одновременно.
  • Затронутые доки: concepts/security.md.

2026-04-09 — Phase 1 GA#

Phase 1 Integration Hub готова к production:

  • Incoming webhooks (Slack + Pachca формат, auto-detect).
  • Bot accounts + REST API.
  • Встроенные slash-команды /poll и /remind.
  • HMAC signing в двух схемах (Slack v0 + PartyFlow-native).
  • Auto-disable после 100 подряд ошибок.
  • Rate limiting по тарифам.

2026-04-19 — Outgoing retry schedule: теперь конфигурируемый exponential#

Расписание retry'ев для outgoing webhooks переведено с фиксированной таблицы 10s → 1m → 10m → 1h (4 попытки) на exponential backoff с конфигурируемыми Initial, Max и MaxAttempts. Формула: delay = min(Initial · 2^(attempt-1), Max) ± Jitter.

Production-дефолты: Initial = 5s, Max = 1h, MaxAttempts = 8, Jitter = ±20%. Это даёт последовательность 5s → 10s → 20s → 40s → 80s → 160s → 320s перед dead-letter — всего 8 попыток, полное retry-window ~10 минут 35 секунд (против ~71 минуты в предыдущей версии схемы).

Что это значит для получателей: если ваши алерты завязаны на "доставка не приходит — значит endpoint down ≥ 1 час", переключитесь на ориентир ~10-13 минут. Новое расписание срабатывает быстрее при восстановлении flappy-получателя, но и переходит в dead-letter раньше — следите за consecutive_failures внимательнее.

Изменение внесено in-place: первая версия публичных доков ещё не публиковалась на developer portal, поэтому deprecation-процедура не применяется.

Затронутые доки: overview.md, concepts/webhooks.md, concepts/rate-limits.md, reference/outgoing-webhooks.md, запись 2026-04-18 — Outgoing webhooks (GA) в этом changelog'е.

2026-04-19 — Concept docs closeout (P0)#

Закрыли три заготовки-placeholder'а, которые мешали публикации на developer portal:

  • concepts/bots.md — полная концепт-страница: что такое bot account vs webhook, lifecycle (create → token → invite → send/read → regenerate/disable), authentication model (Bearer + SHA-256), membership, read-scope (privacy-фильтр), best practices.
  • reference/message-format.md — публичный справочник bot_metadata_json: Slack attachments, Slack Block Kit, Pachca buttons/files, severity badge, сводная таблица "кто что шлёт" (Grafana, GitLab CI, Sentry, Jenkins, PagerDuty, GitHub Actions, Prometheus Alertmanager, Pachca-боты).
  • reference/error-codes.md — сводная таблица всех HTTP статусов публичных endpoints + диагностика (уже была заполнена, в этом закрытии снят status: planned).

Параллельно обновили карту документации.

2026-04-19 — Bot messages metadata_json via REST (fix)#

POST /api/v1/bot/messages теперь прокидывает поле metadata_json в chat-слой. Раньше поле молча игнорировалось handler'ом, поэтому interactive-сообщения можно было отправить только через click-response. Теперь работает прямая отправка сообщения с кнопками, select menus и модалками.

Затронутые доки: reference/interactive-components.md, reference/bot-rest-api.md.

2026-05-02 — Bot Direct Messages (DM) + SSE Stream#

Боты теперь могут участвовать в личных переписках (DM) и получать сообщения в реальном времени через SSE (Server-Sent Events).

Bot DM creation.

  • Пользователь может создать DM с ботом через обычный conversation.create с is_direct: true и member_ids: [bot_id] — бекенд автоматически определяет, что peer — бот, и создаёт direct-чат.
  • Бот может инициировать DM самостоятельно: POST /api/v1/bot/dm с user_id целевого пользователя. Пользователь должен быть участником того же space'а. Возвращает conversation_id (создаётся или возвращается существующий).

SSE Stream для ботов.

  • Новый endpoint GET /api/v1/bot/stream — EventSource-поток для доставки сообщений из DM в реальном времени.
  • Auth: тот же Bearer token, что и для остальных bot endpoints.
  • Формат: text/event-stream. Каждое сообщение — data: <json>\n\n.
  • Keep-alive: :ping\n\n каждые 30 секунд.
  • Offline persistence: если бот не подключён, сообщения сохраняются в inbox (до 50 сообщений, TTL 24ч). При следующем подключении backlog доставляется первым, затем поток переключается на live-режим.
  • Событие message.new содержит: message_id, conversation_id, author_id, text, sent_at.

Ограничения:

  • SSE работает только для DM. Боты в групповых каналах продолжают получать события через outgoing webhooks (как раньше).
  • Rate limit на POST /api/v1/bot/dm — 1 запрос/сек на бота.

Затронутые доки: