Perguntas frequentes
Respostas diretas às dúvidas mais comuns de quem integra a AI Web Push API. Cada resposta aponta para a página da documentação que aprofunda o assunto.
O que é a AI Web Push API?
É a API HTTP da plataforma AI Web Push para criar, agendar, listar, consultar e excluir campanhas de web push a partir do seu próprio sistema. Ela usa JSON, autentica com a chave do site e segmenta o público por tópicos e países. A base de todas as chamadas é https://api.aiwebpush.com/v2.
Quem pode usar a API?
Contas da AI Web Push cujo plano inclui acesso à API. Os relatórios de campanha via API (listar e consultar campanhas com analytics) também dependem do plano. Quando o recurso não está liberado, os métodos de campanha respondem 403 com a mensagem "This plan does not have permission to...", e GET /topics e GET /countries respondem 200 com uma lista vazia. Os planos estão em aiwebpush.com.
Onde pego a chave da API?
Em app.aiwebpush.com/settings: clique no site que quer integrar e copie o campo "Chave da API". Cada site tem a sua própria chave, e ela só alcança as campanhas, tópicos e países daquele site.
Como envio a chave? Preciso do prefixo Bearer?
Não. A chave vai no header Authorization exatamente como foi copiada, sem Bearer. Nos POST, envie também Content-Type: application/json.
De onde vêm os inscritos que recebem as campanhas?
Dos visitantes que aceitaram receber notificações no site por meio do plugin WordPress da AI Web Push. A API não cadastra inscritos; ela cria e consulta campanhas para a base que o plugin já formou.
Qual a diferença entre tópicos e países?
Tópicos são interesses dos inscritos: a IA da AI Web Push classifica o conteúdo que cada um lê e o dono do site também pode cadastrar tópicos no painel. Países agrupam os inscritos por localização e vêm com o prefixo country__ (por exemplo country__brazil). Uma campanha precisa de pelo menos um tópico ou um país; se informar os dois, eles são juntados numa lista só de destinos.
Como sei quais tópicos e países posso usar?
Chame GET /topics e GET /countries. Eles listam só os tópicos e países que têm pelo menos um inscrito no site, com a quantidade de inscritos em cada um. Os nomes vêm sempre em minúsculas e devem ser usados exatamente como vieram.
Como envio uma notificação na hora, agendo ou salvo um rascunho?
Tudo no mesmo POST /campaign/create, combinando dois campos: status draft só guarda a campanha; status published com scheduleMode now envia na hora; status published com scheduleMode scheduled envia na data informada em scheduleDate.
Em que fuso horário mando a data de agendamento?
Em UTC, no formato ISO 8601 com Z no fim, como 2025-05-02T18:30:00Z. Para o horário de Brasília (UTC-3), some 3 horas: 9h em Brasília é 12:00:00Z.
O que é TTL e qual valor usar?
TTL é por quanto tempo, em segundos, a notificação continua valendo se o dispositivo estiver offline. Vai até 2419200 (28 dias), que também é o padrão — enviar 0 resulta no padrão. Para uma oferta de um dia, 86400 evita entregar a notificação depois do prazo. Nas respostas, ttl também vem em segundos e ttlUnit é sempre "seconds".
Por que a campanha enviada aparece com status published, e não sent?
No filtro de POST /campaigns, status aceita draft, scheduled, sent e failed. Dentro de cada campanha da resposta, porém, o campo status mostra o valor original de criação: published, draft ou failed. Uma campanha já enviada continua como published.
Como vejo os resultados (cliques, impressões) de uma campanha?
Com GET /campaign/{campaignId} ou na lista de POST /campaigns. Cada campanha traz o bloco analytics com clicks, impressions, ctr (cliques sobre impressões, em %), its (impressões sobre a base alcançada, em %) e totalUsers.
Como funciona a paginação da listagem?
Por cursor. A primeira chamada vai sem cursor; se a resposta vier com hasMore true, repita a chamada com os mesmos filtros e o mesmo limit, passando o nextCursor no campo cursor. Pare quando hasMore vier false. O limit vai de 1 a 60 (padrão 10).
Dá para excluir ou cancelar uma campanha?
Sim, enquanto ela não foi enviada: DELETE /campaign/{campaignId} apaga rascunhos e cancela agendamentos. Se a campanha já foi enviada, nada é excluído e a resposta é 409.
Recebi 403 "Not authorized". O que está errado?
O header Authorization está ausente ou a chave não foi reconhecida. Confira se copiou a chave inteira, sem prefixo Bearer, e se é a chave do site certo. Se a mensagem for "This plan does not have permission...", a chave está certa, mas o plano da conta não inclui o recurso.
Recebi 404 "Campaign not found" para um ID que existe. Por quê?
A chave é vinculada a um site, e um ID de campanha de outro site responde 404. Confira se está usando a chave do mesmo site que criou a campanha.
Como testo sem disparar notificação de verdade?
Crie a campanha com status draft: ela fica salva, aparece em POST /campaigns e pode ser excluída depois, sem notificar ninguém. Para testar sem código, use a coleção do Postman ou entregue o arquivo OpenAPI a uma IA.
Onde acompanho mudanças na API?
No changelog desta documentação, que registra cada endpoint ou campo novo com a data. O contrato completo e atual fica no arquivo OpenAPI 3.1 público.
Não achou a resposta? Escreva para contato@aiwebpush.com ou use a página de contato.