Crear mensaje POST
Envía una notificación push a tus dispositivos.
Endpoint
POST https://api.pocketalert.app/v1/messagesAutenticación
Obligatorio
Incluye una de estas cabeceras en tu solicitud:
Token: <your-api-key>— Obtenla en Claves de APIAuthorization: Bearer <jwt-token>— Desde Iniciar sesión
Solicitud
Cabeceras
| Cabecera | Obligatoria | Descripción |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Tu clave de API |
Authorization | ✅ | Bearer <jwt-token> |
* Se requiere una de Token o Authorization
Parámetros del cuerpo
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
title | string | ✅ | Título de la notificación |
message | string | ✅ | Texto del cuerpo de la notificación |
application_id | string | ❌ | TID de la aplicación para categorizar el mensaje |
device_id | string | ❌ | TID de un dispositivo concreto; omítelo para enviar a todos los dispositivos |
level | string | int | ❌ | Prioridad que controla cómo se entrega la notificación push. Acepta un nombre o un entero (-2..2). priority se acepta como sinónimo. Por defecto usa el nivel predeterminado de la aplicación y, si no hay ninguno, default. |
actions | array | ❌ | Hasta 3 botones de acción que se muestran en la notificación. Consulta Botones de acción. |
send_at | string | int | ❌ | Entrega en un momento concreto en lugar de inmediatamente. RFC3339, marca de tiempo Unix o YYYY-MM-DD HH:MM. Consulta Envío programado. |
delay | string | ❌ | Entrega tras un retraso relativo: 30m, 2h o solo segundos. Es incompatible con send_at. |
Botones de acción
Cada notificación puede incluir hasta 3 botones de acción. Funcionan tanto si la aplicación está abierta como en segundo plano o cerrada. actions es un array de objetos, de como máximo 2048 bytes una vez codificado en JSON (viaja dentro de la notificación push, que tiene un límite de 4 KB; si message es largo, se acorta para hacer sitio):
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
type | string | ✅ | view (abre una URL), http (envía una solicitud HTTP) o copy (copia texto al portapapeles) |
label | string | ✅ | Texto del botón, que se muestra tal cual en Android y iOS |
value | string | ✅ | Depende de type; consulta abajo |
value según el tipo:
view: la URL que se abre, por ejemplo"https://pocketalert.app".http: una cadena JSON que describe la solicitud:{"url":"https://…","method":"POST","headers":{…},"body":"…"}. Solourles obligatorio;methodtomaGETpor defecto. Se envía desde el dispositivo en segundo plano, sin abrir la aplicación, así que puede llegar a hosts de la red local del teléfono. Si la solicitud falla (estado distinto de 2xx/3xx o error de red), se muestra una notificación con un botón Reintentar; nunca se reintenta por sí sola una vez que pudo haber llegado al servidor.copy: el texto literal que se copia al portapapeles.
Humano en el bucle
Dos acciones http (por ejemplo Aprobar / Rechazar) forman un panel de control de un toque, ideal para aprobar acciones de agentes LLM directamente desde la notificación.
Función de pago
Los botones de acción se eliminan en los planes gratuitos: el mensaje se entrega sin ellos y actions no se valida.
Consulta Botones de acción para ver límites, validación y plantillas de webhook.
Niveles de prioridad
| Nivel | Alias | Comportamiento |
|---|---|---|
silent | min, -2 | Solo llega a la bandeja: sin sonido ni vibración |
low | -1 | Silencioso, sin interrumpir |
default | normal, 0 (o se omite) | Banner y sonido estándar |
high | 1 | Sensible al tiempo: atraviesa Concentración / el resumen programado |
critical | max, urgent, 2 | Despierta el dispositivo aunque esté en modo silencio y en No molestar. Consulta Niveles de prioridad |
WARNING
critical es una función de los planes de pago. En los planes gratuitos se rebaja automáticamente a high. Los valores no válidos (nombre desconocido o entero fuera de rango) devuelven 400.
Consulta Niveles de prioridad para ver cómo se comporta cada nivel en iOS y Android.
Envío programado
Añade send_at o delay, nunca ambos, y el mensaje se guarda cifrado hasta su hora de entrega en lugar de enviarse de inmediato.
| Parámetro | Acepta | Ejemplos |
|---|---|---|
send_at | RFC3339, marca de tiempo Unix o YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Duración al estilo Go o solo segundos | 30m, 2h, 3600 |
Una hora sin desfase se interpreta en la zona horaria de tu cuenta. El límite máximo es de 30 días, y un send_at en el pasado devuelve 400 (con 60 segundos de tolerancia por desfase del reloj).
Las solicitudes programadas devuelven 201 con "scheduled": true, status, deliver_at y deliver_at_utc en lugar de un mensaje entregado. Para listarlas usa GET /v1/messages/scheduled y para cancelarlas DELETE /v1/messages/scheduled/{tid}. Consulta Envío programado.
WARNING
El envío programado es una función de los planes de pago. Las solicitudes de planes gratuitos que usen send_at o delay devuelven 403.
Ejemplo de solicitud
curl -X POST "https://api.pocketalert.app/v1/messages" \
-H "Token: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"title": "Server Alert",
"message": "CPU usage exceeded 90%",
"application_id": "qm47b9pzxzxg",
"level": "critical",
"actions": [
{ "type": "view", "label": "Dashboard", "value": "https://status.example.com" },
{ "type": "http", "label": "Restart", "value": "{\"url\":\"https://ops.example.com/restart\",\"method\":\"POST\"}" },
{ "type": "copy", "label": "Copy ID", "value": "incident-4821" }
]
}'const response = await fetch('https://api.pocketalert.app/v1/messages', {
method: 'POST',
headers: {
'Token': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: 'Server Alert',
message: 'CPU usage exceeded 90%',
application_id: 'qm47b9pzxzxg'
})
});
const data = await response.json();
console.log(data);import requests
response = requests.post(
'https://api.pocketalert.app/v1/messages',
headers={
'Token': 'your-api-key',
'Content-Type': 'application/json'
},
json={
'title': 'Server Alert',
'message': 'CPU usage exceeded 90%',
'application_id': 'qm47b9pzxzxg'
}
)
print(response.json())$response = Http::withHeaders([
'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/messages', [
'title' => 'Server Alert',
'message' => 'CPU usage exceeded 90%',
'application_id' => 'qm47b9pzxzxg',
]);
return $response->json();Respuesta
Respuesta de éxito
201 Created
Mensaje creado correctamente
| Campo | Tipo | Descripción |
|---|---|---|
tid | string | Identificador único del mensaje |
title | string | Título del mensaje |
message | string | Cuerpo del mensaje |
application | string | Nombre de la aplicación (si se indica) |
device | string | Nombre del dispositivo de destino |
actions | array | Botones de acción devueltos (solo si se enviaron) |
created_at | string | Marca de tiempo de creación |
{
"tid": "jb4xw9elz28g",
"title": "Server Alert",
"message": "CPU usage exceeded 90%",
"application": "Monitoring",
"device": "iPhone",
"actions": [
{ "type": "view", "label": "Dashboard", "value": "https://status.example.com" }
],
"created_at": "18.01.2026 15:35:35"
}Cabeceras de cuota
Las respuestas incluyen el uso actual del límite diario (se omiten en los planes sin límite):
| Cabecera | Descripción |
|---|---|
X-PA-Daily-Limit | Mensajes permitidos al día en tu plan |
X-PA-Daily-Remaining | Mensajes que quedan hoy, después de este |
X-PA-Daily-Reset | Marca de tiempo Unix (segundos) del próximo reinicio, a las 00:00 UTC |
Respuestas de error
| Estado | Descripción |
|---|---|
400 | Solicitud incorrecta: falta title o message, level no es válido o, en planes de pago, actions no es válido |
401 | No autorizado: token no válido o ausente |
403 | Prohibido: send_at o delay en un plan gratuito |
404 | No encontrado: application_id o device_id no existe |
429 | Límite diario alcanzado: el mensaje no se guardó ni se envió. Espera los segundos indicados en Retry-After o mejora tu plan. Consulta Límites diarios de mensajes. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Límite diario alcanzado
Cuando se agota la cuota de hoy, el mensaje se rechaza (no se pone en cola) hasta las 00:00 UTC. Retry-After indica los segundos que faltan para el reinicio.
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200{
"error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
"limit": 50,
"used": 50,
"resets_at": "2026-09-22T00:00:00Z",
"upgrade_url": "https://pocketalert.app/pricing"
}Borrar mensajes no libera cuota. Consulta el uso de hoy con GET /v1/messages/usage.