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.
O estado paused suspende novas tentativas da campanha. Uma requisição já em andamento pode terminar, e os webhooks de envios anteriores continuam atualizando os resultados. Pausar não cancela uma mensagem que a Meta já aceitou.
cancelled encerra a fila por ação do usuário e não permite retomada dessa campanha. Os destinatários ainda sem tentativa passam a not_sent nos resultados; uma tentativa em andamento sem confirmação permanece uncertain. Mensagens já aceitas continuam recebendo atualizações de entrega e leitura.
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",
"delivery_api": "cloud",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.delivery_api | API selecionada para esta campanha: cloud ou marketing. A segunda opção exige template MARKETING e ativação Meta; não há fallback automático entre as rotas. |
| campaign.accepted | Envios aceitos pela API da Meta. Uma mensagem aceita ainda pode falhar depois. |
| campaign.dispatch_failed | Contador histórico de ocorrências durante o disparo. Pode incluir exclusões e tentativas sem confirmação; não é o total de falhas definitivas. Use counts e o status de cada destinatário para decidir o tratamento. |
| campaign.paused_at / pause_reason | Horário UTC e motivo da pausa local. manual_pause: ação no painel; worker_interrupted: processamento interrompido; template_paused, template_not_found ou template_not_approved: disponibilidade do modelo; template_params_mismatch, template_param_format ou invalid_template: parâmetros ou formato recusados; template_catalog_unavailable ou template_category_unavailable: não foi possível conferir o catálogo ou a categoria, e a fila foi preservada; meta_template_paused/disabled/rejected: evento da Meta. null quando não informado ou não reconhecido. |
| 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. |
| counts.uncertain | Tentativas sem confirmação de aceite nem de recusa. Não entram em counts.failed e não devem ser reenviadas automaticamente. |
| counts.not_sent | Destinatários para os quais não há tentativa registrada após o encerramento ou a interrupção do disparo. Revise o motivo e a elegibilidade antes de preparar outra campanha. |
| records / untracked | records conta destinatários rastreados, inclusive excluídos. Pode superar campaign.total quando a trilha mantém exclusões da importação ou da revisão do público agendado. 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; isso não comprova que a Meta recusou o envio. |
| 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. |
| delivery_api | API selecionada para a mensagem: cloud ou marketing; null em registros sem essa informação. A escolha da campanha não preenche retroativamente a evidência de cada mensagem. |
| delivery_api_confirmed | Rota comprovada pela classificação do webhook Meta: marketing_lite confirma marketing; marketing confirma cloud. null não comprova falha nem permite inferir a rota utilizada. |
| 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.
API de entrega da campanha (link para esta seção)
Na criação da campanha pelo painel, a escolha vale para o disparo: cloud é o padrão e marketing usa a Marketing Messages API da Meta somente com template MARKETING. A consulta pública informa a escolha em campaign.delivery_api. A API pública de campanhas continua sendo de leitura; para enviar uma mensagem pela integração, use POST /messages com delivery_api.
Os cuidados de consentimento, bloqueios, qualidade e disponibilidade do modelo são os mesmos. A rota de marketing usa política STRICT; uma recusa não faz a campanha mudar silenciosamente para Cloud API. Alterar a API de entrega não é uma forma de contornar quem pediu para sair ou uma limitação da Meta.
Separe a seleção campaign.delivery_api da evidência items[].delivery_api_confirmed. A confirmação depende da classificação recebida no webhook, pode chegar depois e pode permanecer nula no histórico. O estado de entrega continua sendo informado em status.
Comparar resultados das duas opções (link para esta seção)
Separe públicos equivalentes e sem sobreposição; não envie a mesma promoção duas vezes para a mesma pessoa só para comparar rotas. Use o mesmo conteúdo, critérios de seleção, período e tempo de observação após o envio. Registre a opção escolhida e mantenha aceites, entregas, falhas, incertezas e saídas separados.
| Medida | Como comparar |
|---|---|
| Entrega | Use delivered_including_read. No mundo real, mensagens lidas também foram entregues; counts.delivered e counts.read são separados apenas na resposta da API. |
| Leitura | Compare counts.read com o mesmo denominador em ambos os grupos. Não some leituras novamente ao total que já inclui read. |
| Tempo | Use o mesmo intervalo desde a tentativa. Resultados recém-enviados não são comparáveis a uma campanha que acumulou entregas durante horas. |
| Custo | Compare cobrança efetivamente informada pela Meta, na mesma moeda e categoria. Estimativa ou valor ausente não comprova economia. |
Ritmo e previsão de término (link para esta seção)
O painel mostra o ritmo observado das tentativas e uma estimativa para terminar de processar a fila. O tempo depende da resposta da Meta, das pausas e da gravação do resultado; não há uma quantidade fixa garantida por segundo. Entrega e leitura acontecem depois e podem continuar mudando mesmo com o disparo encerrado.
Pausa e retomada no painel (link para esta seção)
Administradores e supervisores com acesso à gestão de campanhas podem pausar e retomar o processamento pelo painel. Um webhook de template PAUSED, DISABLED ou REJECTED pausa as campanhas em processamento ou agendadas que usam o mesmo modelo, idioma e conta da Meta. Qualidade RED gera aviso; não equivale, por si só, a template pausado.
A aprovação posterior do template não retoma campanhas automaticamente. A retomada exige ação no painel, template aprovado e elegibilidade atual dos contatos. Ela continua apenas destinatários ainda sem tentativa registrada; pessoas com aceite, falha de tentativa ou resultado incerto ficam fora dessa retomada. Não há prazo fixo de liberação: confira o estado atual informado pela Meta.
Se a consulta do catálogo ou da categoria estiver indisponível, a campanha pausa e preserva os destinatários sem tentativa. Essa pausa não comprova rejeição do template nem falha de entrega. Tente retomar pelo painel quando a consulta voltar a funcionar.
Os motivos marketing_api_not_ready e cloud_marketing_disabled pedem revisão da configuração da API escolhida; delivery_api_template_mismatch indica incompatibilidade com a categoria. A fila pausa, preserva quem ainda não teve tentativa e não muda de API automaticamente. A retomada mantém a escolha original. Veja os códigos e como agir.
Cancelar pelo painel é definitivo para a fila dessa campanha. A confirmação não apaga o histórico nem recolhe mensagens no WhatsApp. A pausa aplicada pela Meta nunca cancela automaticamente a campanha.
Exportar e preparar uma nova tentativa (link para esta seção)
Exporte os resultados para investigar o motivo por destinatário. A exportação registra uma fotografia; não autoriza reenviar a lista inteira. Consulte novamente os resultados e o consentimento antes de confirmar uma nova campanha.
| Situação | Tratamento |
|---|---|
| pending / sending | Aguarde a tentativa atual. Não abra uma campanha concorrente para essas pessoas. |
| sent / delivered / read | Não reenviar: há aceite ou entrega registrada. sent ainda aguarda confirmação posterior. |
| uncertain / send_uncertain | Separar para conciliação. Uma resposta inválida, conexão interrompida ou falta de WAMID não comprova recusa. Não criar outro envio para contornar a incerteza. |
| not_sent | Conferir o encerramento da fila e a elegibilidade atual. Pode compor uma nova campanha após revisão. |
| failed | Ler error_code e corrigir a causa antes de decidir. Limitação de marketing, experimento da Meta e telefone inacessível não são convites para repetir automaticamente. |
| opted_out / skipped | Respeitar a saída ou o motivo da exclusão. Não incluir contatos que recusaram promoções nem remover bloqueios para repetir o disparo. |
Reentregar um webhook repete a notificação para o servidor da integração; não envia uma nova mensagem no WhatsApp. Não transforme uma falha de entrega do webhook em uma nova campanha.
O evento message.status relata um status recebido da Meta e inclui campaign_id quando há vínculo com a campanha. Uma tentativa local sem WAMID não gera uma confirmação de falha da Meta. A ausência desse evento também não comprova que nada foi enviado; consulte os resultados e mantenha os casos incertos separados.
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.