# Botones de acción

Una notificación puede incluir hasta tres botones. En lugar de leer una alerta y luego abrir un portátil para actuar, actúas desde la pantalla de bloqueo: abres la ejecución, lanzas el reinicio o copias el código.

## Los tres tipos

| Tipo | Qué hace el botón | `value` contiene |
|------|----------------------|---------------|
| `view` | Abre una URL | La URL, p. ej. `https://status.example.com` |
| `http` | Envía una petición HTTP en segundo plano | Una cadena JSON: `{"url":"…","method":"POST","headers":{…},"body":"…"}` |
| `copy` | Copia texto al portapapeles | El texto literal que se va a copiar |

Para `http`, solo `url` es obligatorio; `method` toma `GET` por defecto. Cuando `body` está presente y no se define un tipo de contenido, se añade `Content-Type: application/json` automáticamente.

`http` y `copy` se ejecutan sin abrir la aplicación, incluso cuando está cerrada. `view` lleva la aplicación o el navegador al primer plano.

## Dónde aparecen los botones

Los botones se muestran en la notificación del sistema tanto en iOS como en Android, con la aplicación abierta, en segundo plano o cerrada, y también están dentro del propio mensaje. Esa segunda parte es importante: si descartas el banner, los botones siguen ahí cuando abras el mensaje más tarde.

- **Las etiquetas** se muestran exactamente como las envías en ambas plataformas. Si iOS no puede preparar los botones personalizados a tiempo, usa una etiqueta genérica por tipo (**Abrir**, **Ejecutar**, **Copiar**) y los botones siguen funcionando.
- **Pantalla de bloqueo.** `http` y `copy` se ejecutan desde la pantalla de bloqueo sin desbloquear el teléfono. `view` abre la aplicación o el navegador, así que el teléfono pide desbloqueo primero. En Android, los botones solo se muestran en la pantalla de bloqueo si está configurada para mostrar el contenido de las notificaciones.
- **Peticiones fallidas.** Si una petición `http` falla (un estado distinto de 2xx/3xx o un error de red), aparece una notificación con un botón **Reintentar**. Una petición que podría haber llegado a tu servidor nunca se reintenta por sí sola.
- **Versión de la aplicación.** Los botones de notificación del sistema requieren la aplicación Pocket Alert 2.0.1 o posterior. Las versiones anteriores solo muestran los botones dentro del mensaje.

## Flujos de aprobación

Dos botones `http`, **Aprobar** y **Rechazar**, convierten una notificación en un panel de control de un solo toque. El patrón sirve para cualquier cosa que se detenga esperando a una persona:

- Un pipeline de despliegue que se bloquea hasta una aprobación manual
- Un agente LLM que necesita confirmación antes de gastar dinero o tocar producción
- Un reembolso por encima de un umbral
- Una puerta, una cancela, una luz, un garaje

La petición va directamente del teléfono a tu endpoint. Pocket Alert no la intermedia ni ve el cuerpo de la respuesta.

> **Warning: La idempotencia es responsabilidad tuya**
>
> Pulsar dos veces el mismo botón `http` envía la petición dos veces; no bloqueamos las repeticiones. Si un envío duplicado resulta costoso, haz que el endpoint sea idempotente.

## Botones desde webhooks

Los webhooks pueden incluir una plantilla de acciones con marcadores `%path%`, rellenados a partir del payload entrante. Una alerta de Sentry puede llegar con un botón **Abrir incidencia** que apunte a esa incidencia concreta; un evento de Stripe, con un botón **Ver pago** para ese cargo.

Los valores sustituidos se escapan como JSON antes de analizar la plantilla, de modo que un campo del payload con comillas no puede salirse del contexto y reescribir la URL. Si un botón resuelve algo no válido, por ejemplo un botón **Runbook** cuando la alerta no tiene URL de runbook, solo se descarta ese botón; el resto de botones y el mensaje se entregan igualmente. Un botón mal formado nunca te hará perder la alerta.

Puedes definir la plantilla en el panel al crear o editar un webhook, o a través de la [API de webhooks](https://info.pocketalert.app/api/webhooks/create.md#action-buttons-template).

## Límites y validación

- Máximo **3** botones por mensaje; se muestran en el orden en que los envías.
- El array `actions` puede ocupar como máximo **2048 bytes** una vez codificado en JSON. Viaja dentro del push, que está limitado a 4 KB, así que un `message` largo se acorta para dejar espacio.
- `view` y `http` requieren una URL `http(s)` válida. Cualquier otra cosa devuelve `400` en la API; en una plantilla de webhook, el botón no válido se descarta.
- Los valores `type` desconocidos devuelven `400`.

> **Warning: Función de pago**
>
> Los botones de acción se eliminan de los mensajes en los planes gratuitos, en el servidor. El mensaje en sí se entrega con normalidad.

## Relacionado

- [Crear mensaje](https://info.pocketalert.app/api/messages/create.md): el array `actions` y la referencia completa de la petición
- [Niveles de prioridad](https://info.pocketalert.app/features/priority-levels.md): con qué intensidad suena la alerta
- [Configuración de webhooks](https://info.pocketalert.app/api/webhooks/settings.md): plantillas de acciones en webhooks entrantes
