Conversas

Origens de anúncio (CTWA)

Lista as mensagens recebidas pelo número vinculado que vieram de um clique em anúncio ou post do Click-to-WhatsApp, mais recentes primeiro. Na prática só números da API oficial (Meta) têm origem de anúncio: o bloco referral é um campo do webhook da Cloud API.

A Meta envia a origem apenas na primeira mensagem da conversa e nunca a repete, então cada item aqui equivale a uma conversa que nasceu daquele anúncio.

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): numa linha redigida a identidade do anúncio sobrevive (sourceId, sourceType) e ctwaClid, headline e body voltam nulos, com redacted: true — id de anúncio identifica um criativo, nunca uma pessoa, então a atribuição continua funcionando num número RELAY_ONLY em vez de devolver nada.

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).

GET

referrals

Listar origens de anúncio (CTWA)

curl --request GET \
  --url https://pilotstatus.com.br/v1/referrals \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://pilotstatus.com.br/v1/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pilotstatus.com.br/v1/referrals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://pilotstatus.com.br/v1/referrals"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://pilotstatus.com.br/v1/referrals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "referrals": [
    {
      "id": "cm_01HZX...",
      "conversationId": "conv_01HZX...",
      "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"
      }
    },
    {
      "id": "cm_def456",
      "conversationId": "conv_01HZX...",
      "direction": "INBOUND",
      "providerKind": "META",
      "externalMessageId": "wamid.HBgNNTU0Mj...2",
      "messageType": "text",
      "text": "quero saber o preço",
      "providerTimestamp": "2026-08-16T12:00:00.000Z",
      "referral": {
        "sourceId": "120249828075420703",
        "sourceType": "ad",
        "sourceUrl": "https://www.instagram.com/p/DcJhrlpA3Pl/",
        "headline": "MM DESIGN — Outlet",
        "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": null,
        "adsetId": null,
        "adsetName": null,
        "campaignId": null,
        "campaignName": null,
        "namesResolvedAt": null
      }
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 30,
  "totalPages": 1
}

{
  "error": "sourceType must be \"ad\" or \"post\"",
  "code": "INVALID_SOURCE_TYPE"
}

{
  "error": "Unauthorized"
}

{
  "error": "Tenant-scoped keys cannot call number endpoints",
  "code": "TENANT_SCOPE_NOT_ALLOWED"
}

Autorizações

x-api-key

string

header

obrigatório

Sua chave de API ps_

Parâmetros de consulta

sourceId

string

Filtra por um único id de anúncio/post. (string)

sourceType

string

Filtra por tipo de origem: "ad" ou "post". (string ("ad" | "post"))

startDate

string

Início do período (sobre providerTimestamp). Deve ser ≤ endDate. (string (ISO 8601))

endDate

string

Fim do período (sobre providerTimestamp). (string (ISO 8601))

page

string

Página (padrão 1). (integer (≥1))

pageSize

string

Itens por página (padrão 30, máx 100). (integer (1–100))

Resposta

Listar origens de anúncio

Listar origens de anúncio (CTWA)

curl --request GET \
  --url https://pilotstatus.com.br/v1/referrals \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://pilotstatus.com.br/v1/referrals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://pilotstatus.com.br/v1/referrals",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://pilotstatus.com.br/v1/referrals"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://pilotstatus.com.br/v1/referrals")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "referrals": [
    {
      "id": "cm_01HZX...",
      "conversationId": "conv_01HZX...",
      "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"
      }
    },
    {
      "id": "cm_def456",
      "conversationId": "conv_01HZX...",
      "direction": "INBOUND",
      "providerKind": "META",
      "externalMessageId": "wamid.HBgNNTU0Mj...2",
      "messageType": "text",
      "text": "quero saber o preço",
      "providerTimestamp": "2026-08-16T12:00:00.000Z",
      "referral": {
        "sourceId": "120249828075420703",
        "sourceType": "ad",
        "sourceUrl": "https://www.instagram.com/p/DcJhrlpA3Pl/",
        "headline": "MM DESIGN — Outlet",
        "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": null,
        "adsetId": null,
        "adsetName": null,
        "campaignId": null,
        "campaignName": null,
        "namesResolvedAt": null
      }
    }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 30,
  "totalPages": 1
}

{
  "error": "sourceType must be \"ad\" or \"post\"",
  "code": "INVALID_SOURCE_TYPE"
}

{
  "error": "Unauthorized"
}

{
  "error": "Tenant-scoped keys cannot call number endpoints",
  "code": "TENANT_SCOPE_NOT_ALLOWED"
}

Endpoints

Workspace

Origens de anúncio (CTWA)

Autorizações

Parâmetros de consulta

Resposta