# Botões de ação

Uma notificação pode ter até três botões. Em vez de ler um alerta e depois abrir o notebook para resolver, você age direto na tela de bloqueio: abre a execução, dispara o reinício, copia o código.

## Os três tipos

| Tipo | O que o botão faz | `value` contém |
|------|----------------------|---------------|
| `view` | Abre uma URL | A URL, por exemplo `https://status.example.com` |
| `http` | Envia uma requisição HTTP em segundo plano | Uma string JSON: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | Copia texto para a área de transferência | O texto literal a ser copiado |

Para `http`, só `url` é obrigatório — `method` usa `GET` por padrão. Quando `body` está presente e nenhum tipo de conteúdo é definido, `Content-Type: application/json` é adicionado automaticamente.

`http` e `copy` funcionam sem abrir o app, mesmo quando ele está fechado. `view` traz o app ou o navegador para o primeiro plano.

## Onde os botões aparecem

Os botões são exibidos na notificação do sistema no iOS e no Android, com o app aberto, em segundo plano ou fechado, e também ficam dentro da própria mensagem. Essa segunda parte é importante: se você arrastar o banner para fora, os botões continuam lá quando abrir a mensagem depois.

- **Rótulos** são exibidos exatamente como você envia, em ambas as plataformas. Se o iOS não conseguir preparar os botões personalizados a tempo, ele usa um rótulo genérico por tipo — **Abrir**, **Executar**, **Copiar** — e os botões continuam funcionando.
- **Tela de bloqueio.** `http` e `copy` funcionam direto da tela de bloqueio, sem desbloquear. `view` abre o app ou o navegador, então o celular pede para desbloquear primeiro. No Android, os botões só aparecem na tela de bloqueio se ela estiver configurada para mostrar o conteúdo das notificações.
- **Requisições com falha.** Se uma requisição `http` falhar (status diferente de 2xx/3xx ou erro de rede), aparece uma notificação com um botão **Tentar novamente**. Uma requisição que pode ter chegado ao seu servidor nunca é repetida automaticamente.
- **Versão do app.** Os botões na notificação do sistema exigem o app Pocket Alert 2.0.1 ou superior. Versões anteriores mostram os botões apenas dentro da mensagem.

## Fluxos de aprovação

Dois botões `http` — **Aprovar** e **Recusar** — transformam uma notificação em um painel de controle com um toque. O padrão funciona para qualquer coisa que fique pausada esperando uma pessoa:

- Um pipeline de deploy que trava esperando aprovação manual
- Um agente de LLM que precisa de aval antes de gastar dinheiro ou mexer em produção
- Um reembolso acima de um limite
- Uma porta, um portão, uma luz, uma garagem

A requisição vai direto do celular para o seu endpoint. O Pocket Alert não faz proxy dela e não vê o corpo da resposta.

> **Warning: A idempotência é sua responsabilidade**
>
> Tocar duas vezes no mesmo botão `http` envia a requisição duas vezes — não bloqueamos repetições. Se disparar em duplicidade for caro, torne o endpoint idempotente.

## Botões vindos de webhooks

Webhooks podem carregar um modelo de ação com placeholders `%path%`, preenchidos a partir do payload recebido. Um alerta do Sentry pode chegar com um botão **Abrir issue** funcionando, apontando para aquela issue específica; um evento do Stripe, com um botão **Ver pagamento** para aquela cobrança.

Os valores substituídos recebem escape JSON antes de o modelo ser interpretado, então um campo do payload com aspas não consegue sair do lugar e reescrever a URL. Se um botão resolver para algo inválido, por exemplo um botão **Runbook** quando o alerta não tem URL de runbook, só esse botão é descartado; os demais botões e a mensagem continuam sendo entregues. Um botão malformado nunca faz você perder o alerta.

Você pode definir o modelo no console ao criar ou editar um webhook, ou pela [API de webhooks](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

## Limites e validação

- No máximo **3** botões por mensagem; eles aparecem na ordem em que você os envia.
- O array `actions` pode ter no máximo **2048 bytes** depois de codificado em JSON. Ele viaja dentro do push, que tem limite de 4 KB, então um `message` longo é encurtado para dar espaço.
- `view` e `http` exigem uma URL `http(s)` válida. Qualquer outra coisa retorna `400` na API; em um modelo de webhook, o botão inválido é descartado.
- Valores de `type` desconhecidos retornam `400`.

> **Warning: Recurso pago**
>
> Botões de ação são removidos das mensagens em planos gratuitos, no servidor. A mensagem em si é entregue normalmente.

## Relacionado

- [Criar mensagem](https://info.pocketalert.app/api/messages/create.md) — o array `actions` e a referência completa da requisição
- [Níveis de prioridade](https://info.pocketalert.app/features/priority-levels.md) — o quanto alto o alerta toca
- [Configurações de webhook](https://info.pocketalert.app/api/webhooks/settings.md) — modelos de ação em webhooks de entrada
