Crea messaggio POST
Invia una notifica push ai tuoi dispositivi.
Endpoint
POST https://api.pocketalert.app/v1/messagesAutenticazione
Obbligatorio
Includi una di queste intestazioni nella tua richiesta:
Token: <your-api-key>— Ottienila da Chiavi APIAuthorization: Bearer <jwt-token>— Da Accedi
Richiesta
Intestazioni
| Intestazione | Obbligatoria | Descrizione |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | La tua chiave API |
Authorization | ✅ | Bearer <jwt-token> |
* È richiesta una delle intestazioni Token o Authorization
Parametri del corpo
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
title | string | ✅ | Titolo della notifica |
message | string | ✅ | Testo del corpo della notifica |
application_id | string | ❌ | TID dell'applicazione per classificare il messaggio |
device_id | string | ❌ | TID di un dispositivo specifico; ometti per tutti i dispositivi |
level | string | int | ❌ | Livello di priorità che controlla come viene consegnata la push. Accetta un nome o un intero (-2..2). priority è accettato come sinonimo. Il valore predefinito è il livello predefinito dell'applicazione, poi default. |
actions | array | ❌ | Fino a 3 pulsanti di azione mostrati nella notifica. Vedi Pulsanti di azione. |
send_at | string | int | ❌ | Consegna a un orario specifico invece che immediatamente. RFC3339, timestamp Unix o YYYY-MM-DD HH:MM. Vedi Invio programmato. |
delay | string | ❌ | Consegna dopo un ritardo relativo: 30m, 2h o semplicemente secondi. Si esclude a vicenda con send_at. |
Pulsanti di azione
Ogni notifica può contenere fino a 3 pulsanti di azione. Funzionano sia con l'app aperta, sia in background, sia chiusa. actions è un array di oggetti, di al massimo 2048 byte una volta codificato in JSON (viaggia all'interno della push, che è limitata a 4 KB; un message lungo viene accorciato per fare spazio):
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
type | string | ✅ | view (apre un URL), http (esegue una richiesta HTTP) oppure copy (copia il testo negli appunti) |
label | string | ✅ | Testo del pulsante, mostrato così com'è su Android e iOS |
value | string | ✅ | Dipende da type — vedi sotto |
value per tipo:
view— l'URL da aprire, ad esempio"https://pocketalert.app".http— una stringa JSON che descrive la richiesta:{"url":"https://…","method":"POST","headers":{…},"body":"…"}. È obbligatorio solourl;methodpredefinito èGET. Viene eseguita dal dispositivo in background senza aprire l'app, quindi può raggiungere host nella rete locale del telefono. Se la richiesta fallisce (stato diverso da 2xx/3xx o errore di rete), viene mostrata una notifica con un pulsante Riprova; non viene mai ritentata automaticamente una volta che potrebbe essere arrivata al server.copy— il testo letterale copiato negli appunti.
Human-in-the-loop
Due azioni http (ad esempio Approva / Rifiuta) creano un pannello di controllo con un solo tocco, ideale per approvare azioni di agenti LLM direttamente dalla notifica.
Funzionalità a pagamento
I pulsanti di azione vengono rimossi nei piani gratuiti: il messaggio viene consegnato senza di essi e actions non viene validato.
Vedi Pulsanti di azione per limiti, validazione e template webhook.
Livelli di priorità
| Livello | Alias | Comportamento |
|---|---|---|
silent | min, -2 | Consegnata solo nel centro notifiche: nessun suono o vibrazione |
low | -1 | Silenziosa, senza interruzioni |
default | normal, 0 (o omesso) | Banner e suono standard |
high | 1 | Urgente per il tempo — supera Full immersion / riepilogo programmato |
critical | max, urgent, 2 | Sveglia il dispositivo anche con interruttore silenzioso e Non disturbare. Vedi Livelli di priorità |
WARNING
critical è una funzionalità del piano a pagamento. Nei piani gratuiti viene automaticamente declassata a high. I valori non validi (nome sconosciuto o intero fuori intervallo) restituiscono 400.
Vedi Livelli di priorità per il comportamento di ciascun livello su iOS e Android.
Invio programmato
Aggiungi send_at oppure delay — mai entrambi — e il messaggio viene memorizzato cifrato fino all'orario di consegna invece di essere inviato subito.
| Parametro | Accetta | Esempi |
|---|---|---|
send_at | RFC3339, timestamp Unix o YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Durata in stile Go oppure secondi | 30m, 2h, 3600 |
Un orario senza offset viene interpretato nel fuso orario del tuo account. L'orizzonte massimo è di 30 giorni, e un send_at nel passato restituisce 400 (con 60 secondi di tolleranza per il disallineamento dell'orologio).
Le richieste programmate restituiscono 201 con "scheduled": true, status, deliver_at e deliver_at_utc invece di un messaggio consegnato. Elencale con GET /v1/messages/scheduled e annullale con DELETE /v1/messages/scheduled/{tid} — vedi Invio programmato.
WARNING
L'invio programmato è una funzionalità del piano a pagamento. Le richieste nei piani gratuiti che usano send_at o delay restituiscono 403.
Esempio di richiesta
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();Risposta
Risposta di successo
201 Created
Messaggio creato con successo
| Campo | Tipo | Descrizione |
|---|---|---|
tid | string | Identificatore univoco del messaggio |
title | string | Titolo del messaggio |
message | string | Corpo del messaggio |
application | string | Nome dell'applicazione (se specificato) |
device | string | Nome del dispositivo di destinazione |
actions | array | Pulsanti di azione restituiti (solo se forniti) |
created_at | string | Data e ora di creazione |
{
"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"
}Intestazioni della quota
Le risposte includono l'utilizzo odierno del limite giornaliero (omesse nei piani senza limiti):
| Intestazione | Descrizione |
|---|---|
X-PA-Daily-Limit | Messaggi consentiti al giorno con il tuo piano |
X-PA-Daily-Remaining | Messaggi rimasti oggi, dopo questo |
X-PA-Daily-Reset | Timestamp Unix (in secondi) del prossimo azzeramento, alle 00:00 UTC |
Risposte di errore
| Stato | Descrizione |
|---|---|
400 | Richiesta non valida — title o message mancanti, level non valido o, nei piani a pagamento, actions non valido |
401 | Non autorizzato — token non valido o mancante |
403 | Vietato — send_at o delay su un piano gratuito |
404 | Non trovato — application_id o device_id non esistono |
429 | Limite giornaliero raggiunto — il messaggio non è stato memorizzato né inviato. Attendi i secondi indicati in Retry-After oppure passa a un piano superiore. Vedi Limiti giornalieri di messaggi. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Limite giornaliero raggiunto
Quando la quota di oggi è esaurita, il messaggio viene rifiutato — non messo in coda — fino alle 00:00 UTC. Retry-After indica i secondi mancanti al ripristino.
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"
}Eliminare i messaggi non libera quota. Controlla l'utilizzo di oggi con GET /v1/messages/usage.