Conversations

Ad referrals (CTWA)

Lists the linked number’s inbound messages that arrived from a Click-to-WhatsApp ad or post, newest first. In practice only official API (Meta) numbers carry an ad origin: the referral block is a Cloud API webhook field.

Meta sends the origin on the first message of the conversation only and never repeats it, so each item here amounts to one conversation that started from that ad.

referral.sourceId is Meta’s ad (or post) id, exposed as an opaque grouping key. There is no campaign or adset name here and that is not an omission: reading the ad object (GET /{ad_id}?fields=id,name,adset{id,name},campaign{id,name}) requires the ads_read permission on the advertiser’s ad account, and the WhatsApp system-user token behind a connected number carries only whatsapp_business_management and whatsapp_business_messaging. To resolve names, call the Meta Marketing API yourself with a token authorised on that ad account, using this sourceId.

Privacy (PII): on a redacted row the ad identity survives (sourceId, sourceType) while ctwaClid, headline and body come back null and redacted: true is set — an ad id identifies a creative, never a person, so attribution keeps working on a RELAY_ONLY number instead of returning nothing.

Requires a number-scoped key.

The referral object also carries the RESOLVED names of the ad — adName, adsetId, adsetName, campaignId, campaignName — plus namesResolvedAt.

⚠️ Those six come back null unless the advertiser has shared that ad account with the Pilot Status business portfolio as a partner. A null name is a SUPPORTED state, not an error: the conversation is still counted and sourceId is still returned.

No endpoint resolves a name on demand — resolution happens asynchronously, off the request path, so querying never triggers a Marketing API call and a null can become a name minutes later with nothing done on your side. namesResolvedAt is what makes that observable: null means “not resolved yet”, while a timestamp with null names means “we asked and Meta returned nothing” (deleted ad, or sharing not granted).

GET

referrals

List ad referrals (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"
}

Authorizations

x-api-key

string

header

required

Your ps_ API key

Query Parameters

sourceId

string

Filter to a single ad/post id. (string)

sourceType

string

Filter by origin type: "ad" or "post". (string ("ad" | "post"))

startDate

string

Start of the date range (over providerTimestamp). Must be ≤ endDate. (string (ISO 8601))

endDate

string

End of the date range (over providerTimestamp). (string (ISO 8601))

page

string

Page (default 1). (integer (≥1))

pageSize

string

Items per page (default 30, max 100). (integer (1–100))

Response

List ad referrals

List ad referrals (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

Ad referrals (CTWA)

Authorizations

Query Parameters

Response