GET /v1/referrals — atribuição de Click-to-WhatsApp

Quando alguém toca num anúncio Click-to-WhatsApp (CTWA) ou num post orgânico e escreve para o seu número da API oficial, a Meta anexa a origem daquele clique à primeira mensagem recebida. A Pilot Status guarda isso, e estes dois endpoints leem de volta: um mensagem por mensagem, outro agregado por anúncio.

Endpoints

GET https://pilotstatus.com.br/v1/referrals GET https://pilotstatus.com.br/v1/referrals/summary

Os dois exigem uma API key escopada a número (ps_*) no header x-api-key. Keys de tenant recebem 403.

Na prática só números da API oficial (Meta) têm origem de anúncio — o bloco de origem é um campo do webhook da Cloud API do WhatsApp, então número conectado por QR code nunca tem.

Nome de campanha, e quando ele vem nulo

A resposta traz os nomes legíveis do anúncio — adName, adsetName, campaignName e os ids correspondentes — ao lado do sourceId cru.

Os cinco campos de nome voltam null enquanto o anunciante não compartilhar a conta de anúncios com a gente, e null é estado suportado, não erro.Ler o nome de um anúncio exige a permissão ads_read na conta de anúncios do próprio anunciante. A forma de conceder isso é o compartilhamento de parceiro da Meta: o anunciante adiciona o portfólio empresarial da Pilot Status como parceiro na conta de anúncios, com “ver desempenho”. Até que ele faça isso, a conversa continua contada e o sourceId continua vindo — só os nomes é que são nulos.Nada que você envie na requisição muda isso. Consultar nunca dispara chamada à Marketing API: a resolução roda de forma assíncrona, fora do caminho da requisição, então um null que você vê agora pode ser um nome segundos depois, sem você fazer nada — veja O primeiro clique em um anúncio novo chega antes dos nomes.

O namesResolvedAt é o que torna os três estados distinguíveis, e cada um pede uma resposta diferente:

`namesResolvedAt`	Nomes	O que significa
`null`	nulos	Ainda não resolvido. Em criativo que ninguém clicou antes, é o estado normal nos primeiros segundos depois do clique — veja a seção abaixo. Se ficar assim, a conta de anúncios não foi compartilhada.
data preenchida	preenchidos	Resolvido. Os nomes são os que a Meta devolveu naquele momento.
data preenchida	nulos	Perguntamos e a Meta não devolveu — anúncio apagado, ou compartilhamento ainda ausente.

O sourceId continua sendo a identidade mesmo com os nomes presentes. Uma campanha pode ser renomeada na Meta a qualquer momento, então quem usa campaignName como chave perde o próprio histórico na primeira vez que o anunciante editar.

O primeiro clique em um anúncio novo chega antes dos nomes

A linha do referral é gravada antes de o seu webhook disparar, então sourceId, sourceUrl, headline e body já podem ser lidos no instante em que o evento chega até você. Os nomes não: eles são resolvidos por um worker separado, que chama a Marketing API da Meta uma vez por anúncio, e essa chamada termina depois que o webhook já saiu. Medido em produção em 53 anúncios: os nomes ficam prontos 0,7s depois da linha da mensagem na mediana, 3,0s no p95 e 5,5s no pior caso. A variação é a latência da própria Meta. Ou seja, uma integração que chama o GET /v1/referrals no instante em que o webhook chega está correndo contra esse worker — e no primeiro clique de um criativo novo ela costuma ganhar a corrida, recebendo o referral com os cinco campos de nome null e namesResolvedAt: null. Isso acontece uma vez por anúncio, só. Todo clique seguinte no mesmo anúncio lê os nomes já em cache e volta preenchido na hora. É exatamente por isso que a mesma integração vê os nomes “às vezes”: as falhas são criativos novos, os acertos são anúncios que já tinham sido clicados.

Receita. Trate namesResolvedAt: null como pergunte de novo, nunca como não existem nomes: repita a mesma consulta ~5s depois e mais uma vez ~60s depois. Assim que namesResolvedAt tiver uma data, a resposta é definitiva — nomes preenchidos são os nomes, nomes nulos significam que falta o compartilhamento de parceiro, e repetir não vai mudar.

Só a primeira mensagem carrega a origem

A Meta envia a origem na primeira mensagem da conversa e nunca repete. Então uma linha em GET /v1/referrals equivale a uma conversa que nasceu daquele anúncio, e conversations no resumo é o número que o seu anúncio realmente produziu.

`GET /v1/referrals`

Parâmetros de query

string

Restringe a um único id de anúncio/post.

string

ad ou post. Qualquer outro valor devolve 400 INVALID_SOURCE_TYPE.

string

Data-hora ISO 8601. Mensagens a partir de (inclusive) este instante.

string

Data-hora ISO 8601. Mensagens até (inclusive) este instante.

integer

padrão:"1"

Página (≥ 1).

integer

padrão:"30"

Itens por página (1–100).

O objeto `referral`

Campo	Significado
`sourceId`	Id do anúncio (ou post) na Meta. Chave opaca — veja o aviso acima.
`sourceType`	`ad` ou `post`.
`sourceUrl`	Permalink do anúncio/post clicado.
`headline`	Título do anúncio.
`body`	Texto do anúncio.
`mediaType`	`image` ou `video`.
`imageUrl`	Imagem do criativo, quando o anúncio é de imagem.
`videoUrl`	Vídeo do criativo, quando o anúncio é de vídeo.
`thumbnailUrl`	Miniatura do criativo.
`ctwaClid`	Id daquele clique específico na Meta. Tratado como dado pessoal — veja abaixo.
`adName`	Nome do anúncio no Gerenciador de Anúncios. `null` sem compartilhamento de parceiro.
`adsetId` · `adsetName`	Conjunto a que ele pertence. `null` sem compartilhamento de parceiro.
`campaignId` · `campaignName`	Campanha a que ele pertence. `null` sem compartilhamento de parceiro.
`namesResolvedAt`	ISO 8601 da última tentativa de resolução, ou `null` se nunca houve. Veja a tabela acima.

Exemplo

curl "https://pilotstatus.com.br/v1/referrals?sourceType=ad&startDate=2026-08-01T00:00:00Z" \
  -H "x-api-key: ps_sua_key_aqui"

{
  "referrals": [
    {
      "id": "cm_abc123",
      "conversationId": "conv_abc123",
      "direction": "INBOUND",
      "providerKind": "META",
      "externalMessageId": "wamid.HBgNNTU0Mj...",
      "messageType": "text",
      "text": "Oi, vi o anúncio",
      "providerTimestamp": "2026-08-16T12:00:00.000Z",
      "referral": {
        "sourceId": "120249828053880703",
        "sourceType": "ad",
        "sourceUrl": "https://www.instagram.com/p/DcJhrlpA3Pl/",
        "headline": "SALE MM DESIGN",
        "body": "Seu ambiente pode ficar ainda mais incrível",
        "mediaType": "video",
        "imageUrl": null,
        "videoUrl": "https://video.example/v.mp4",
        "thumbnailUrl": "https://thumb.example/t.jpg",
        "ctwaClid": "ARAaZ1x...",
        "adName": "Ads 01 - Vídeo dos 70%",
        "adsetId": "120249828053990703",
        "adsetName": "[IG] [LL1% IG + VÍDEOS] - 35 a 50",
        "campaignId": "120249677595590703",
        "campaignName": "[CD-01] [WHATSAPP] - MM Design - Sale 70%",
        "namesResolvedAt": "2026-08-17T21:04:00.000Z"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 30,
  "totalPages": 1
}

`GET /v1/referrals/summary`

Agrupa os mesmos dados por anúncio, ordenado por número de conversas desc.

Parâmetros de query

string

Data-hora ISO 8601.

string

Data-hora ISO 8601.

Regra de contagem

conversations conta conversas distintas; messages conta mensagens. Duas mensagens na mesma conversa são 1 conversa e 2 mensagens — então conversations é a contagem de leads e messages é o volume. lastSourceUrl e lastHeadline vêm da mensagem mais recente daquele anúncio: a copy pode ser editada, e a última versão que a Meta mandou é a útil.

O teto é informado, não escondido

A lista para em 200 anúncios. Quando houver mais, truncated vem true e um notice avisa — estreite a janela com startDate/endDate em vez de paginar.

Exemplo

curl "https://pilotstatus.com.br/v1/referrals/summary?startDate=2026-08-01T00:00:00Z" \
  -H "x-api-key: ps_sua_key_aqui"

{
  "ads": [
    {
      "sourceId": "120249828053880703",
      "sourceType": "ad",
      "conversations": 12,
      "messages": 31,
      "firstAt": "2026-07-28T10:00:00.000Z",
      "lastAt": "2026-08-16T12:00:00.000Z",
      "lastSourceUrl": "https://www.instagram.com/p/DcJhrlpA3Pl/",
      "lastHeadline": "SALE MM DESIGN",
      "adName": "Ads 01 - Vídeo dos 70%",
      "adsetId": "120249828053990703",
      "adsetName": "[IG] [LL1% IG + VÍDEOS] - 35 a 50",
      "campaignId": "120249677595590703",
      "campaignName": "[CD-01] [WHATSAPP] - MM Design - Sale 70%",
      "namesResolvedAt": "2026-08-17T21:04:00.000Z"
    },
    {
      "sourceId": "120249828075420703",
      "sourceType": "ad",
      "conversations": 4,
      "messages": 9,
      "firstAt": "2026-08-02T09:00:00.000Z",
      "lastAt": "2026-08-15T18:30:00.000Z",
      "lastSourceUrl": "https://www.instagram.com/p/DcAbcdEfGh/",
      "lastHeadline": "MM DESIGN — Outlet",
      "adName": null,
      "adsetId": null,
      "adsetName": null,
      "campaignId": null,
      "campaignName": null,
      "namesResolvedAt": null
    }
  ],
  "total": 2,
  "limit": 200,
  "truncated": false
}

Efeito do modo de privacidade (PII)

A identidade do anúncio e a copy do anúncio são tratadas de forma diferente de propósito: um id de anúncio identifica um criativo, nunca uma pessoa, enquanto ctwaClid é um identificador por clique ligado ao indivíduo, e título/texto são conteúdo.

Modo PII	Efeito
`STORE_INDEFINITE` (padrão)	Tudo é devolvido.
`STORE_X_DAYS`	Linhas mais antigas que a janela de retenção mantêm `sourceId` e `sourceType`; `ctwaClid`, `headline` e `body` vêm nulos e `redacted: true` é marcado.
`RELAY_ONLY`	A mesma divisão em toda linha, mais `notice: "PII_RELAY_ONLY"`. No resumo os contadores seguem corretos — só `lastSourceUrl` e `lastHeadline` voltam nulos, com `piiNotice: "PII_RELAY_ONLY"`.

É essa divisão que mantém a atribuição de anúncio funcionando num número RELAY_ONLY em vez de devolver nada.

Erros

Status	Código	Causa
`400`	`INVALID_SOURCE_TYPE`	`sourceType` não era `ad` nem `post`.
`400`	`INVALID_DATE_RANGE`	Data malformada, ou `startDate` depois de `endDate`.
`400`	`INVALID_PAGINATION`	`page × pageSize` passou do limite de profundidade. Estreite o período.
`400`	`NUMBER_NOT_FOUND`	A key não está atrelada a um número de WhatsApp.
`401`	—	`x-api-key` ausente ou inválida.
`403`	`TENANT_SCOPE_NOT_ALLOWED`	Foi usada uma key de tenant.

Visão Geral

Mensagens

Modelos

Números

Linhas Telefônicas

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

GET /v1/referrals — atribuição de Click-to-WhatsApp

Endpoints

Nome de campanha, e quando ele vem nulo

O primeiro clique em um anúncio novo chega antes dos nomes

Só a primeira mensagem carrega a origem

`GET /v1/referrals`

Parâmetros de query

O objeto `referral`

Exemplo

`GET /v1/referrals/summary`

Parâmetros de query

Regra de contagem

O teto é informado, não escondido

Exemplo

Efeito do modo de privacidade (PII)

Erros

​Endpoints

​Nome de campanha, e quando ele vem nulo

​O primeiro clique em um anúncio novo chega antes dos nomes

​Só a primeira mensagem carrega a origem

​GET /v1/referrals

​Parâmetros de query

​O objeto referral

​Exemplo

​GET /v1/referrals/summary

​Parâmetros de query

​Regra de contagem

​O teto é informado, não escondido

​Exemplo

​Efeito do modo de privacidade (PII)

​Erros

Endpoints

Nome de campanha, e quando ele vem nulo

O primeiro clique em um anúncio novo chega antes dos nomes

Só a primeira mensagem carrega a origem

`GET /v1/referrals`

Parâmetros de query

O objeto `referral`

Exemplo

`GET /v1/referrals/summary`

Parâmetros de query

Regra de contagem

O teto é informado, não escondido

Exemplo

Efeito do modo de privacidade (PII)

Erros