Criar mensagem POST
Envie uma notificação push para seus dispositivos.
Endpoint
POST https://api.pocketalert.app/v1/messagesAutenticação
Obrigatório
Inclua um destes cabeçalhos na sua requisição:
Token: <your-api-key>— Obtenha em Chaves de APIAuthorization: Bearer <jwt-token>— Em Login
Requisição
Cabeçalhos
| Cabeçalho | Obrigatório | Descrição |
|---|---|---|
Content-Type | ✅ | application/json |
Token | ✅ | Sua chave de API |
Authorization | ✅ | Bearer <jwt-token> |
* É obrigatório informar Token ou Authorization
Parâmetros do corpo
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | ✅ | Título da notificação |
message | string | ✅ | Texto do corpo da notificação |
application_id | string | ❌ | TID do aplicativo para categorizar a mensagem |
device_id | string | ❌ | TID de um dispositivo específico; omita para enviar a todos os dispositivos |
level | string | int | ❌ | Nível de prioridade que controla como a push é entregue. Aceita um nome ou um inteiro (-2..2). priority também é aceito como sinônimo. O padrão é o nível padrão do aplicativo e, em seguida, default. |
actions | array | ❌ | Até 3 botões de ação exibidos na notificação. Veja Botões de ação. |
send_at | string | int | ❌ | Entrega em um horário específico, em vez de imediatamente. RFC3339, timestamp Unix ou YYYY-MM-DD HH:MM. Veja Envio agendado. |
delay | string | ❌ | Entrega após um atraso relativo: 30m, 2h ou apenas segundos. Não pode ser usado junto com send_at. |
Botões de ação
Cada notificação pode ter até 3 botões de ação. Eles funcionam com o aplicativo aberto, em segundo plano ou fechado. actions é um array de objetos, com no máximo 2048 bytes depois de codificado em JSON (ele viaja dentro da push, que é limitada a 4 KB; um message longo é encurtado para caber):
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
type | string | ✅ | view (abre uma URL), http (dispara uma requisição HTTP) ou copy (copia um texto para a área de transferência) |
label | string | ✅ | Texto do botão, exibido como está no Android e no iOS |
value | string | ✅ | Depende de type; veja abaixo |
value por tipo:
view— a URL a ser aberta, por exemplo"https://pocketalert.app".http— uma string JSON descrevendo a requisição:{"url":"https://…","method":"POST","headers":{…},"body":"…"}. Sóurlé obrigatório;methodassumeGETpor padrão. É disparado pelo dispositivo em segundo plano, sem abrir o aplicativo, então pode acessar hosts da rede local do celular. Se a requisição falhar (status diferente de 2xx/3xx ou erro de rede), é exibida uma notificação com um botão Tentar novamente; ela nunca é reenviada automaticamente depois que pode ter chegado ao servidor.copy— o texto literal colocado na área de transferência.
Humano no controle
Dois ações http (por exemplo Aprovar / Recusar) formam um painel de controle de um toque, ideal para aprovar ações de agentes LLM direto pela notificação.
Recurso pago
Os botões de ação são removidos nos planos gratuitos: a mensagem é entregue sem eles, e actions não é validado.
Veja Botões de ação para limites, validação e modelos de webhook.
Níveis de prioridade
| Nível | Aliases | Comportamento |
|---|---|---|
silent | min, -2 | Entregue apenas na bandeja, sem som ou vibração |
low | -1 | Discreto, sem interromper |
default | normal, 0 (ou omitido) | Banner e som padrão |
high | 1 | Sensível ao tempo: fura o Foco / o resumo agendado |
critical | max, urgent, 2 | Acorda o dispositivo mesmo com a chave silenciosa e o Não perturbe ativados. Veja Níveis de prioridade |
WARNING
critical é um recurso dos planos pagos. Nos planos gratuitos, ele é rebaixado automaticamente para high. Valores inválidos (nome desconhecido ou inteiro fora do intervalo) retornam 400.
Veja Níveis de prioridade para saber como cada nível se comporta no iOS e no Android.
Envio agendado
Adicione send_at ou delay, nunca os dois, e a mensagem fica armazenada criptografada até o horário de entrega, em vez de ser enviada imediatamente.
| Parâmetro | Aceita | Exemplos |
|---|---|---|
send_at | RFC3339, timestamp Unix ou YYYY-MM-DD HH:MM | 2026-08-15T09:00:00Z, 1786867200 |
delay | Duração no estilo Go ou apenas segundos | 30m, 2h, 3600 |
Um horário sem deslocamento de fuso é lido no fuso horário da sua conta. O limite é de 30 dias, e um send_at no passado retorna 400 (com 60 segundos de tolerância para diferenças no relógio).
Requisições agendadas retornam 201 com "scheduled": true, status, deliver_at e deliver_at_utc, em vez de uma mensagem entregue. Liste-as com GET /v1/messages/scheduled e cancele com DELETE /v1/messages/scheduled/{tid}. Veja Envio agendado.
WARNING
O envio agendado é um recurso dos planos pagos. Requisições dos planos gratuitos que usem send_at ou delay retornam 403.
Exemplo de requisição
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();Resposta
Resposta de sucesso
201 Created
Mensagem criada com sucesso
| Campo | Tipo | Descrição |
|---|---|---|
tid | string | Identificador único da mensagem |
title | string | Título da mensagem |
message | string | Corpo da mensagem |
application | string | Nome do aplicativo (se informado) |
device | string | Nome do dispositivo de destino |
actions | array | Botões de ação devolvidos (somente quando enviados) |
created_at | string | Data e hora de criação |
{
"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"
}Cabeçalhos de cota
As respostas trazem o uso de hoje do limite diário (omitido nos planos ilimitados):
| Cabeçalho | Descrição |
|---|---|
X-PA-Daily-Limit | Mensagens permitidas por dia no seu plano |
X-PA-Daily-Remaining | Mensagens restantes hoje, após esta |
X-PA-Daily-Reset | Timestamp Unix (segundos) da próxima renovação, 00:00 UTC |
Respostas de erro
| Status | Descrição |
|---|---|
400 | Requisição inválida: title ou message ausente, level inválido ou, nos planos pagos, actions inválido |
401 | Não autorizado: token inválido ou ausente |
403 | Proibido: send_at ou delay em um plano gratuito |
404 | Não encontrado: application_id ou device_id não existe |
429 | Limite diário atingido: a mensagem não foi armazenada nem enviada. Aguarde o número de segundos de Retry-After ou faça upgrade. Veja Limites diários de mensagens. |
{
"error": "Validation failed",
"details": {
"title": ["The title field is required"]
}
}Limite diário atingido
Quando a cota de hoje se esgota, a mensagem é rejeitada, não colocada na fila, até às 00:00 UTC. Retry-After indica os segundos que faltam até a renovação.
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"
}Excluir mensagens não libera cota. Consulte o uso de hoje com GET /v1/messages/usage.