# Кнопки действий

Уведомление может содержать до трёх кнопок. Вместо того чтобы читать оповещение, а потом открывать ноутбук, чтобы что-то с ним сделать, вы действуете прямо с экрана блокировки: открываете запуск, перезапускаете сервис, копируете код.

## Три типа

| Тип | Что делает кнопка | Что хранится в `value` |
|------|----------------------|---------------|
| `view` | Открывает URL | URL, например `https://status.example.com` |
| `http` | Отправляет HTTP-запрос в фоновом режиме | JSON-строка: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | Копирует текст в буфер обмена | Текст, который нужно скопировать, как есть |

Для `http` обязателен только `url`, по умолчанию `method` равен `GET`. Если указан `body`, а тип содержимого не задан, автоматически добавляется `Content-Type: application/json`.

`http` и `copy` выполняются без открытия приложения, даже если оно закрыто. `view` выводит приложение или браузер на передний план.

## Где появляются кнопки

Кнопки отображаются в системном уведомлении на iOS и Android независимо от того, открыто приложение, работает в фоне или закрыто. Кроме того, они есть внутри самого сообщения. Это важно: если смахнуть баннер, кнопки всё равно будут доступны, когда вы откроете сообщение позже.

- **Подписи** выводятся на обеих платформах так, как вы их отправили. Если iOS не успевает подготовить пользовательские кнопки, она использует общую подпись для каждого типа: **Открыть**, **Запустить**, **Копировать**. Кнопки при этом продолжают работать.
- **Экран блокировки.** `http` и `copy` выполняются с экрана блокировки без разблокировки. `view` открывает приложение или браузер, поэтому телефон сначала попросит разблокировать его. На Android кнопки видны на экране блокировки только если там включён показ содержимого уведомлений.
- **Неудачные запросы.** Если запрос `http` завершился ошибкой (статус не 2xx/3xx или сетевая ошибка), появляется уведомление с кнопкой **Повторить**. Запрос, который мог дойти до вашего сервера, сам по себе повторно не отправляется.
- **Версия приложения.** Системные кнопки уведомлений требуют приложение Pocket Alert версии 2.0.1 или новее. В старых версиях кнопки показываются только внутри сообщения.

## Сценарии согласования

Две кнопки `http` — **Одобрить** и **Отклонить** — превращают уведомление в пульт управления в одно касание. Этот шаблон подходит для любого процесса, который ждёт решения человека:

- Пайплайн деплоя, который блокируется до ручного одобрения
- LLM-агент, которому нужно подтверждение, прежде чем он потратит деньги или изменит продакшен
- Возврат средств выше порога
- Дверь, ворота, свет, гараж

Запрос уходит напрямую с телефона на ваш эндпоинт. Pocket Alert не проксирует его и не видит тело ответа.

> **Warning: Идемпотентность — на вашей стороне**
>
> Повторное нажатие на ту же кнопку `http` отправит запрос ещё раз: мы не блокируем повторы. Если повторная отправка обходится дорого, сделайте эндпоинт идемпотентным.

## Кнопки из вебхуков

Вебхуки могут передавать шаблон действий с плейсхолдерами `%path%`, которые заполняются из входящих данных. Оповещение Sentry может прийти с рабочей кнопкой **Открыть задачу**, ведущей на конкретную задачу, а событие Stripe — с кнопкой **Посмотреть платёж** для этого платежа.

Подставляемые значения экранируются в формате JSON до разбора шаблона, поэтому поле с кавычками не сможет выйти за пределы и переписать URL. Если кнопка превращается во что-то некорректное, например кнопка **Runbook**, когда в оповещении нет ссылки на runbook, удаляется только эта кнопка; остальные кнопки и текст сообщения всё равно доставляются. Некорректная кнопка никогда не лишит вас оповещения.

Шаблон можно задать в консоли при создании или редактировании вебхука либо через [API вебхуков](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

## Ограничения и валидация

- Максимум **3** кнопки на сообщение; они отображаются в том порядке, в котором вы их отправили.
- Массив `actions` после JSON-кодирования может занимать не больше **2048 байт**. Он передаётся внутри push-уведомления, ограниченного 4 КБ, поэтому длинное `message` сокращается, чтобы освободить место.
- `view` и `http` требуют корректный URL `http(s)`. Любой другой вариант возвращает `400` в API; в шаблоне вебхука некорректная кнопка просто удаляется.
- Неизвестные значения `type` возвращают `400`.

> **Warning: Платная функция**
>
> На бесплатных тарифах кнопки действий удаляются из сообщений на стороне сервера. Само сообщение доставляется как обычно.

## Связанное

- [Создание сообщения](https://info.pocketalert.app/api/messages/create.md) — массив `actions` и полный справочник запроса
- [Уровни приоритета](https://info.pocketalert.app/features/priority-levels.md) — насколько громко придёт оповещение
- [Настройки вебхука](https://info.pocketalert.app/api/webhooks/settings.md) — шаблоны действий для входящих вебхуков
