Zapnoty — Согласования — подтверждения по кнопке

Согласования

Интерактивные подтверждения через Telegram/Max-бота: вопрос с кнопками, follow-up по клику, маршруты уведомлений и webhook — без своего бэкенда на обработку кнопок.

Как это устроено

Сначала создаётся шаблон (сценарий) — вопрос с {{vars}}, набор кнопок, тексты follow-up и маршруты по исходу. Затем по этому шаблону запускается конкретное согласование для подписчика — сразу или к назначенному времени. Бот присылает вопрос с кнопками, а по клику отправляет свой follow-up текст, применяет маршруты уведомлений и шлёт webhook. Своего бэкенда на обработку кнопок не нужно.

Эндпоинты

POST /v1/approval-templates — создать шаблон (сценарий)

POST /v1/approval-templates/{id}/routes — маршрут уведомления по исходу

POST /v1/approvals — запустить согласование

GET /v1/approvals/{id} — статус и исход

POST /v1/approvals/{id}/cancel — отменить (пока не отвечено)

1. Создание шаблона

Шаблон задаёт вопрос prompt (text, опционально format и media) с плейсхолдерами {{vars}}, кнопки и тексты follow-up для каждого исхода. Обязательна только кнопка approve; decline и reschedule — опциональны. default_ttl_minutes — срок жизни по умолчанию, если не переопределён при запуске.

POST /v1/approval-templates

Authorization: Bearer zn_live_...

{

"prompt": { "text": "Запись к врачу на {{time}}. Придёте?" },

"buttons": {

"approve": { "label": "Приду" },

"decline": { "label": "Не приду" },

"reschedule": { "label": "Перенести" }

"follow_up": {

"approved": "Спасибо! Ждём вас в {{time}}.",

"declined": "Запись отменена, слот освобождён.",

"reschedule": "Администратор свяжется с вами.",

"expired": "Не получили ответ — напомним позже."

"default_ttl_minutes": 1440

}

Кнопки и исходы

approve object обязательный

Кнопка подтверждения — исход approved. { label }

decline object

Кнопка отклонения — исход declined. Необязательна

reschedule object

Кнопка переноса — исход reschedule. Необязательна

expired —

Исход по истечении TTL без ответа (кнопки нет, только follow-up и маршрут)

2. Маршруты по исходу

POST /v1/approval-templates/{template_id}/routes

Authorization: Bearer zn_live_...

{

"trigger_outcome": "declined",

"recipient_type": "email",

"recipient_email": "reception@clinic.ru"

}

3. Запуск согласования

Запуск создаёт конкретное согласование по шаблону. Укажите подписчика через subscriber_id или external_id (ваш идентификатор пользователя). scheduled_at — отправить не сразу, а в назначенное время. vars подставляются в {{плейсхолдеры}} вопроса и follow-up.

POST /v1/approvals

Authorization: Bearer zn_live_...

{

"template_id": "aptpl_abc123",

"subscriber_id": "sub_2aUyqjCzEIiEcYMKj7TZtw",

"scheduled_at": "2026-07-02T09:00:00Z",

"ttl_minutes": 180,

"vars": { "time": "18:00" },

"metadata": { "booking_id": "bk_991" }

}

Параметры запуска

template_id string обязательный

ID шаблона согласования

subscriber_id string

ID подписчика (либо external_id)

external_id string

Ваш идентификатор пользователя (либо subscriber_id)

scheduled_at string

ISO-8601 — время отправки. Без него — сразу

ttl_minutes integer

Срок жизни, переопределяет default_ttl_minutes шаблона

vars object

Значения для {{плейсхолдеров}} вопроса и follow-up

metadata object

Произвольные данные — возвращаются в webhook и статусе

Ответ

{

"id": "apr_8kQ2mzT1",

"status": "scheduled",

"outcome": null

}

4. Статус и исход

Опрашивайте статус согласования по его ID. status проходит sent → answered (или expired / cancelled). outcome появляется после ответа: approved, declined или reschedule.

GET /v1/approvals/apr_8kQ2mzT1

Authorization: Bearer zn_live_...

{

"id": "apr_8kQ2mzT1",

"status": "answered",

"outcome": "approved",

"answered_at": "2026-07-02T15:03:11Z"

}

5. Webhook-события

Zapnoty шлёт webhook на каждый шаг: approval.sent (вопрос отправлен), approval.approved, approval.declined, approval.reschedule (ответ подписчика) и approval.expired (истёк TTL). Подпись — X-Zapnoty-Signature (HMAC-SHA256), как у остальных событий.

POST https://your-app.com/webhooks

X-Zapnoty-Signature: sha256=...

{

"event": "approval.approved",

"approval_id": "apr_8kQ2mzT1",

"template_id": "aptpl_abc123",

"outcome": "approved",

"external_id": "bk_991",

"answered_at": "2026-07-02T15:03:11Z"

}