Vai al contenuto

Crea messaggio POST ​

Invia una notifica push ai tuoi dispositivi.

Endpoint ​

POST https://api.pocketalert.app/v1/messages

Autenticazione ​

Obbligatorio

Includi una di queste intestazioni nella tua richiesta:

  • Token: <your-api-key> — Ottienila da Chiavi API
  • Authorization: Bearer <jwt-token> — Da Accedi

Richiesta ​

Intestazioni ​

IntestazioneObbligatoriaDescrizione
Content-Type✅application/json
Token✅La tua chiave API
Authorization✅Bearer <jwt-token>

* È richiesta una delle intestazioni Token o Authorization

Parametri del corpo ​

ParametroTipoObbligatorioDescrizione
titlestring✅Titolo della notifica
messagestring✅Testo del corpo della notifica
application_idstring❌TID dell'applicazione per classificare il messaggio
device_idstring❌TID di un dispositivo specifico; ometti per tutti i dispositivi
levelstring | 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.
actionsarray❌Fino a 3 pulsanti di azione mostrati nella notifica. Vedi Pulsanti di azione.
send_atstring | int❌Consegna a un orario specifico invece che immediatamente. RFC3339, timestamp Unix o YYYY-MM-DD HH:MM. Vedi Invio programmato.
delaystring❌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):

CampoTipoObbligatorioDescrizione
typestring✅view (apre un URL), http (esegue una richiesta HTTP) oppure copy (copia il testo negli appunti)
labelstring✅Testo del pulsante, mostrato così com'è su Android e iOS
valuestring✅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 solo url; method predefinito è 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à ​

LivelloAliasComportamento
silentmin, -2Consegnata solo nel centro notifiche: nessun suono o vibrazione
low-1Silenziosa, senza interruzioni
defaultnormal, 0 (o omesso)Banner e suono standard
high1Urgente per il tempo — supera Full immersion / riepilogo programmato
criticalmax, urgent, 2Sveglia 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.

ParametroAccettaEsempi
send_atRFC3339, timestamp Unix o YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayDurata in stile Go oppure secondi30m, 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 ​

bash
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" }
    ]
  }'
javascript
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);
python
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())
php
$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

CampoTipoDescrizione
tidstringIdentificatore univoco del messaggio
titlestringTitolo del messaggio
messagestringCorpo del messaggio
applicationstringNome dell'applicazione (se specificato)
devicestringNome del dispositivo di destinazione
actionsarrayPulsanti di azione restituiti (solo se forniti)
created_atstringData e ora di creazione
json
{
  "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):

IntestazioneDescrizione
X-PA-Daily-LimitMessaggi consentiti al giorno con il tuo piano
X-PA-Daily-RemainingMessaggi rimasti oggi, dopo questo
X-PA-Daily-ResetTimestamp Unix (in secondi) del prossimo azzeramento, alle 00:00 UTC

Risposte di errore ​

StatoDescrizione
400Richiesta non valida — title o message mancanti, level non valido o, nei piani a pagamento, actions non valido
401Non autorizzato — token non valido o mancante
403Vietato — send_at o delay su un piano gratuito
404Non trovato — application_id o device_id non esistono
429Limite 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.
json
{
  "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
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
json
{
  "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.

Documentazione di Pocket Alert