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).
curl --request GET \
--url https://pilotstatus.com.br/v1/referrals/summary \
--header 'x-api-key: <api-key>'import requests
url = "https://pilotstatus.com.br/v1/referrals/summary"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://pilotstatus.com.br/v1/referrals/summary', 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/summary",
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/summary"
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))
}HttpResponse<String> response = Unirest.get("https://pilotstatus.com.br/v1/referrals/summary")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/referrals/summary")
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{
"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
}{
"error": "startDate must be before or equal to endDate",
"code": "INVALID_DATE_RANGE"
}{
"error": "Unauthorized"
}{
"error": "Tenant-scoped keys cannot call number endpoints",
"code": "TENANT_SCOPE_NOT_ALLOWED"
}Autorizações
Sua chave de API ps_
Parâmetros de consulta
Início do período (sobre providerTimestamp). Deve ser ≤ endDate. (string (ISO 8601))
Fim do período (sobre providerTimestamp). (string (ISO 8601))
Resposta
Resumo de anúncios
Esta página foi útil?
curl --request GET \
--url https://pilotstatus.com.br/v1/referrals/summary \
--header 'x-api-key: <api-key>'import requests
url = "https://pilotstatus.com.br/v1/referrals/summary"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://pilotstatus.com.br/v1/referrals/summary', 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/summary",
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/summary"
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))
}HttpResponse<String> response = Unirest.get("https://pilotstatus.com.br/v1/referrals/summary")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://pilotstatus.com.br/v1/referrals/summary")
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{
"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
}{
"error": "startDate must be before or equal to endDate",
"code": "INVALID_DATE_RANGE"
}{
"error": "Unauthorized"
}{
"error": "Tenant-scoped keys cannot call number endpoints",
"code": "TENANT_SCOPE_NOT_ALLOWED"
}