# Pulsanti di azione

Una notifica push può contenere fino a tre pulsanti. Invece di leggere un avviso e poi aprire il laptop per fare qualcosa, agisci direttamente dalla schermata di blocco: apri la run, avvia il riavvio, copia il codice.

## I tre tipi

| Tipo | Cosa fa il pulsante | `value` contiene |
|------|----------------------|---------------|
| `view` | Apre un URL | L'URL, ad esempio `https://status.example.com` |
| `http` | Invia una richiesta HTTP in background | Una stringa JSON: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | Copia un testo negli appunti | Il testo esatto da copiare |

Per `http` è richiesto solo `url` — `method` vale `GET` di default. Quando `body` è presente e non è impostato alcun content type, viene aggiunto automaticamente `Content-Type: application/json`.

`http` e `copy` vengono eseguiti senza aprire l'app, anche quando è chiusa. `view` porta in primo piano l'app o il browser.

## Dove compaiono i pulsanti

I pulsanti vengono mostrati nella notifica di sistema su iOS e Android, che l'app sia aperta, in background o chiusa, e sono presenti anche dentro il messaggio stesso. Questo secondo aspetto è importante: se fai scorrere via il banner, i pulsanti restano disponibili quando apri il messaggio più tardi.

- **Etichette** vengono mostrate esattamente come le invii, su entrambe le piattaforme. Se iOS non riesce a preparare in tempo i pulsanti personalizzati, usa un'etichetta generica per ogni tipo — **Apri**, **Esegui**, **Copia** — e i pulsanti continuano a funzionare.
- **Schermata di blocco.** `http` e `copy` vengono eseguiti dalla schermata di blocco senza sbloccare il telefono. `view` apre l'app o il browser, quindi il telefono chiede prima di sbloccarsi. Su Android i pulsanti sono visibili nella schermata di blocco solo se questa è impostata per mostrare il contenuto delle notifiche.
- **Richieste fallite.** Se una richiesta `http` fallisce (uno stato diverso da 2xx/3xx o un errore di rete), compare una notifica con un pulsante **Riprova**. Una richiesta che potrebbe essere arrivata al tuo server non viene mai ritentata da sola.
- **Versione dell'app.** I pulsanti nelle notifiche di sistema richiedono l'app Pocket Alert 2.0.1 o successiva. Le versioni precedenti mostrano i pulsanti solo dentro il messaggio.

## Flussi di approvazione

Due pulsanti `http` — **Approva** e **Rifiuta** — trasformano una notifica in un pannello di controllo a un tocco. Lo schema funziona per qualsiasi cosa resti in attesa di una persona:

- Una pipeline di deploy che si blocca in attesa di approvazione manuale
- Un agente LLM che ha bisogno di un via libera prima di spendere denaro o toccare la produzione
- Un rimborso sopra una certa soglia
- Una porta, un cancello, una luce, un garage

La richiesta va direttamente dal telefono al tuo endpoint. Pocket Alert non fa da proxy e non vede il corpo della risposta.

> **Warning: La gestione dei duplicati è a tuo carico**
>
> Toccare due volte lo stesso pulsante `http` invia la richiesta due volte — non blocchiamo le ripetizioni. Se l'invio doppio è costoso, rendi l'endpoint idempotente.

## Pulsanti dai webhook

I webhook possono includere un template di azione con segnaposto `%path%`, riempiti con i dati del payload in arrivo. Un avviso Sentry può arrivare con un pulsante **Apri issue** funzionante che punta a quello specifico issue; un evento Stripe con un pulsante **Visualizza pagamento** per quel addebito.

I valori sostituiti vengono codificati in JSON prima che il template venga interpretato, quindi un campo del payload che contiene virgolette non può uscire dal proprio contesto e riscrivere l'URL. Se un pulsante produce un valore non valido, ad esempio un pulsante **Runbook** quando l'avviso non ha un URL di runbook, viene eliminato solo quel pulsante; gli altri pulsanti e il messaggio vengono comunque consegnati. Un pulsante malformato non ti fa mai perdere l'avviso.

Puoi impostare il template nella console quando crei o modifichi un webhook, oppure tramite le [API dei webhook](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

## Limiti e validazione

- Massimo **3** pulsanti per messaggio; vengono mostrati nell'ordine in cui li invii.
- L'array `actions` può occupare al massimo **2048 byte** una volta codificato in JSON. Viaggia all'interno della push, che è limitata a 4 KB, quindi un `message` lungo viene accorciato per fare spazio.
- `view` e `http` richiedono un URL `http(s)` valido. Qualsiasi altra cosa restituisce `400` dall'API; in un template di webhook il pulsante non valido viene eliminato.
- I valori `type` sconosciuti restituiscono `400`.

> **Warning: Funzionalità a pagamento**
>
> I pulsanti di azione vengono rimossi dai messaggi nei piani gratuiti, lato server. Il messaggio in sé viene consegnato normalmente.

## Correlati

- [Crea messaggio](https://info.pocketalert.app/api/messages/create.md) — l'array `actions` e il riferimento completo della richiesta
- [Livelli di priorità](https://info.pocketalert.app/features/priority-levels.md) — quanto forte suona l'avviso
- [Impostazioni dei webhook](https://info.pocketalert.app/api/webhooks/settings.md) — template di azione sui webhook in arrivo
