Resumo de anúncios (CTWA)
Agrupa o tráfego de Click-to-WhatsApp do número vinculado por anúncio/post, ordenado por número de conversas desc. conversations conta conversas DISTINTAS e messages conta mensagens — duas mensagens da mesma conversa são 1 conversa e 2 mensagens.
lastSourceUrl e lastHeadline vêm da mensagem mais recente daquele anúncio: a copy pode ser editada, e a útil é a última que a Meta enviou.
A lista tem teto de 200 anúncios; quando estoura, truncated vem true e um notice explica — estreite a janela com startDate/endDate.
referral.sourceId é o id do anúncio (ou do post) da Meta, exposto como chave opaca de agrupamento. Não há nome de campanha nem de conjunto aqui, e isso não é omissão: ler o objeto do anúncio (GET /{ad_id}?fields=id,name,adset{id,name},campaign{id,name}) exige a permissão ads_read na conta de anúncios do anunciante, e o token de usuário de sistema por trás de um número conectado carrega apenas whatsapp_business_management e whatsapp_business_messaging. Para resolver os nomes, chame a Marketing API da Meta com um token autorizado naquela conta, usando este sourceId.
Privacidade (PII): os CONTADORES seguem corretos num número RELAY_ONLY (saem da identidade do anúncio, que não é dado pessoal); só lastSourceUrl e lastHeadline voltam nulos, com piiNotice: "PII_RELAY_ONLY".
Requer key escopada a número.
O objeto referral também traz os nomes RESOLVIDOS do anúncio — adName, adsetId, adsetName, campaignId, campaignName — e mais namesResolvedAt.
⚠️ Esses seis voltam null enquanto o anunciante não tiver compartilhado aquela conta de anúncios com o portfólio empresarial da Pilot Status como parceiro. Nome nulo é estado SUPORTADO, não erro: a conversa continua contada e o sourceId continua vindo.
Nenhum endpoint resolve nome sob demanda — a resolução é assíncrona, fora do caminho da requisição, então consultar nunca dispara chamada à Marketing API e um null pode virar nome minutos depois sem você fazer nada. O namesResolvedAt é o que torna isso observável: null significa “ainda não resolvido”, enquanto data preenchida com nomes nulos significa “perguntamos e a Meta não devolveu” (anúncio apagado, ou compartilhamento ausente).