Ir para o conteúdo

Criar mensagem POST ​

Envie uma notificação push para seus dispositivos.

Endpoint ​

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

Autenticação ​

Obrigatório

Inclua um destes cabeçalhos na sua requisição:

  • Token: <your-api-key> — Obtenha em Chaves de API
  • Authorization: Bearer <jwt-token> — Em Login

Requisição ​

Cabeçalhos ​

CabeçalhoObrigatórioDescriçã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âmetroTipoObrigatórioDescrição
titlestring✅Título da notificação
messagestring✅Texto do corpo da notificação
application_idstring❌TID do aplicativo para categorizar a mensagem
device_idstring❌TID de um dispositivo específico; omita para enviar a todos os dispositivos
levelstring | 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.
actionsarray❌Até 3 botões de ação exibidos na notificação. Veja Botões de ação.
send_atstring | int❌Entrega em um horário específico, em vez de imediatamente. RFC3339, timestamp Unix ou YYYY-MM-DD HH:MM. Veja Envio agendado.
delaystring❌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):

CampoTipoObrigatórioDescrição
typestring✅view (abre uma URL), http (dispara uma requisição HTTP) ou copy (copia um texto para a área de transferência)
labelstring✅Texto do botão, exibido como está no Android e no iOS
valuestring✅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; method assume GET por 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ívelAliasesComportamento
silentmin, -2Entregue apenas na bandeja, sem som ou vibração
low-1Discreto, sem interromper
defaultnormal, 0 (ou omitido)Banner e som padrão
high1Sensível ao tempo: fura o Foco / o resumo agendado
criticalmax, urgent, 2Acorda 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âmetroAceitaExemplos
send_atRFC3339, timestamp Unix ou YYYY-MM-DD HH:MM2026-08-15T09:00:00Z, 1786867200
delayDuração no estilo Go ou apenas segundos30m, 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 ​

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();

Resposta ​

Resposta de sucesso ​

201 Created

Mensagem criada com sucesso

CampoTipoDescrição
tidstringIdentificador único da mensagem
titlestringTítulo da mensagem
messagestringCorpo da mensagem
applicationstringNome do aplicativo (se informado)
devicestringNome do dispositivo de destino
actionsarrayBotões de ação devolvidos (somente quando enviados)
created_atstringData e hora de criação
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"
}

Cabeçalhos de cota ​

As respostas trazem o uso de hoje do limite diário (omitido nos planos ilimitados):

CabeçalhoDescrição
X-PA-Daily-LimitMensagens permitidas por dia no seu plano
X-PA-Daily-RemainingMensagens restantes hoje, após esta
X-PA-Daily-ResetTimestamp Unix (segundos) da próxima renovação, 00:00 UTC

Respostas de erro ​

StatusDescrição
400Requisição inválida: title ou message ausente, level inválido ou, nos planos pagos, actions inválido
401Não autorizado: token inválido ou ausente
403Proibido: send_at ou delay em um plano gratuito
404Não encontrado: application_id ou device_id não existe
429Limite 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.
json
{
  "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
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"
}

Excluir mensagens não libera cota. Consulte o uso de hoje com GET /v1/messages/usage.

Documentação do Pocket Alert