Resultados de campanhas
Acompanhe os disparos feitos no painel e consulte a entrega de cada mensagem, sem enviar outra campanha.
A chave Bearer permite consultar somente as campanhas da sua empresa. Esta consulta lê os registros locais, atualizados pelos envios e pelos webhooks da Meta. Ela não consulta a Meta em tempo real.
Encontrar a campanha (link para esta seção)
/public/v1/campaignscurl "https://api.patrociniotech.com/public/v1/campaigns?limit=20" \
-H "Authorization: Bearer SUA_CHAVE"| Parâmetro | Regra |
|---|---|
| limit | De 1 a 100. Padrão: 20 campanhas por página, da mais recente para a mais antiga. |
| before_id | Na próxima página, use data.next_before_id da resposta anterior. Omita na primeira consulta. |
| data.items | Campanhas, com id, nome, número, template, idioma, agendamento e progresso do disparo. |
| data.has_more | true quando há outra página. next_before_id fica null quando a lista termina. |
O id é o mesmo usado na URL de detalhes do painel. status: done significa que o processamento do disparo acabou. Ainda podem chegar confirmações de entrega, leitura e falha.
Resultados e destinatários (link para esta seção)
/public/v1/campaigns/{campaign_id}/resultscurl "https://api.patrociniotech.com/public/v1/campaigns/302/results?status=failed&limit=50" \
-H "Authorization: Bearer SUA_CHAVE"| Parâmetro | Regra |
|---|---|
| campaign_id | Identificador positivo da campanha. Campanha inexistente ou de outra empresa retorna 404/not_found. |
| limit | De 1 a 200 destinatários por página. Padrão: 50. |
| status | all, pending, sending, sent, delivered, read, failed, skipped, uncertain, not_sent ou opted_out. Padrão: all. |
| after | Copie data.next_after da resposta anterior e mantenha o mesmo filtro. Omita na primeira página; não altere ou incremente o cursor. |
{
"success": true,
"data": {
"campaign": {
"id": 302,
"name": "Oferta de novembro",
"phone_number_id": "123456789012345",
"template": "oferta_novembro",
"language": "pt_BR",
"status": "done",Como ler os totais (link para esta seção)
| Campo | Interpretação |
|---|---|
| campaign.total | Destinatários selecionados para o disparo. Não significa que receberam a mensagem. |
| campaign.accepted | Envios aceitos pela API da Meta. Uma mensagem aceita ainda pode falhar depois. |
| campaign.dispatch_failed | Falhas durante o envio. As falhas posteriores de entrega estão em counts.failed. |
| counts.delivered / counts.read | Estados separados: delivered não inclui read. Para o total de entregas, use delivered_including_read. |
| counts.opted_out | Pessoas que pediram para parar promoções e cuja saída foi vinculada à campanha. Sobrepõe a entrega; não some esse valor aos demais estados. |
| counts.sent | Aceitas, ainda sem entrega, leitura ou falha posterior registrada. Não considere entregues nem falhadas. |
| records / untracked | records conta destinatários com evidência disponível; untracked é a diferença positiva para o público selecionado. Ausência de registro não confirma falha. |
| total_filtered | Total que corresponde ao filtro em toda a campanha. Não é o tamanho da página nem o número restante depois do cursor. |
complete_tracking é false. Nesse caso, não trate os registros ausentes como entregas, falhas ou custo zero.O resultado de cada pessoa (link para esta seção)
| Campo | Interpretação |
|---|---|
| to / contact_wa_id | to é o telefone solicitado no disparo. contact_wa_id é o identificador confirmado pela Meta quando disponível; ele pode vir normalizado. |
| message_id | WAMID aceito pela Meta. Pode ser usado na consulta de status da mensagem. null quando não há aceite registrado. |
| dispatch_status / status | dispatch_status registra a tentativa local; status considera a confirmação posterior de entrega. Um disparo sent pode terminar com status failed. |
| error_code / reason | Código estável e explicação da falha conhecida. Programe contra error_code; reason é texto para leitura. null indica informação não registrada. |
| attempted_at / status_at | Horário da tentativa e da última atualização disponível na trilha. status_at não garante o instante exato de entrega. |
| pricing_category / billable | Categoria e indicação de cobrança recebidas da Meta. null significa não informado. Esta rota não calcula o valor da fatura. |
| opted_out_at | Horário da saída de promoções atribuída à campanha. A pessoa ainda pode aparecer com status read ou delivered. |
marketing_recipient_limited indica limitação de marketing para aquele destinatário. marketing_experiment indica um teste de entrega da Meta. Esses motivos não confirmam banimento do remetente e não justificam reenviar automaticamente.
Paginação e atualização (link para esta seção)
Continue enquanto has_more for true, usando next_after como after. A ordem é lexical por telefone e cada resposta lê os registros disponíveis naquele momento. Novos webhooks podem mudar o status entre páginas; para exportar ou reconciliar, guarde pelo par campanha e destinatário, atualize o mesmo registro e faça uma nova leitura depois.
A integração não deve chamar esta rota antes de cada envio. Faça consultas periódicas com pausa e respeite a cota compartilhada por chave. Filtros inválidos retornam 422; autenticação inválida retorna 401; excesso de requisições retorna 429. Um 503 é indisponibilidade temporária da consulta, não evidência de que o disparo falhou: aguarde e repita somente o GET.