Listar os cliques em anúncio
Os cliques em anúncio que chegaram ao número, do mais novo para o mais antigo, paginados por cursor. Cada item traz o anúncio, o conjunto e a campanha (do cache da Synergy: null enquanto o anúncio não foi buscado) e attributable, que diz se o clique trouxe o identificador de clique da Meta. O identificador em si nunca sai pela API.
since e until são segundos desde 1970 e filtram por quando a mensagem do clique chegou (until inclusive). Com ad_id só saem os cliques daquele anúncio.
Requer#
- Escopo da chave
- read
readComo os escopos funcionam - Recurso do plano
- API e webhooks
apie Inbox (fila da equipe)inboxVer os planos que incluem - Formato
- Rota do Synergy. Erros no formato da Meta.
Parâmetros#
No caminho#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| phone_number_id | string | obrigatório | O phone_number_id do número na Meta (o mesmo da Cloud API). Precisa ser um número ativo da organização da chave. |
Na query#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| limit | integer | opcional | Itens por página: 1 a 50, padrão 20. |
| after | string | opcional | O paging.after da página anterior (opaco). |
| since | integer | opcional | Só cliques recebidos a partir deste instante (segundos desde 1970). |
| until | integer | opcional | Só cliques recebidos até este instante, inclusive (segundos desde 1970). |
| ad_id | string | opcional | Só os cliques deste anúncio. |
Cabeçalhos#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| Authorization | string | obrigatório | Sua chave de API, no formato Bearer <chave>. Veja Autenticação. |
Respostas#
| Status | Código | Quando acontece |
|---|---|---|
| 200 | — | Um clique |
| 400 | 100 | Cursor que não veio desta API (não é base64url de uma lista de inteiros, ou tem o tamanho errado) |
| 400 | 100 | Parâmetro fora da faixa (por exemplo limit acima de 50) |
| 401 | 190 | Sem Authorization: Bearer, chave malformada ou forjada, chave revogada, ou chave sem acesso a este número |
| 403 | 200 | A chave não tem o escopo read |
| 403 | 1390004 | O plano da organização não inclui a API |
| 403 | 1390011 | O plano da organização não inclui o Inbox (a leitura exige api e inbox) |
| 403 | 1390014 | O número foi congelado pela plataforma |
| 404 | 100 | O phone_number_id não é um número ativo desta organização (ou não tem de 5 a 20 dígitos) |
| 429 | 130429 | Mais de 2000 requisições em 10 s com esta chave neste número (Retry-After: 10) |
| 429 | 130429 | O número acabou de recusar por vazão, ou está sobrecarregado: o 429 se repete por 200 ms (Retry-After: 1) |
| 429 | 130429 | Mais de 30 leituras em 60 s com esta chave neste número (Retry-After: 60) |
| 429 | 1390015 | O teto diário de páginas de leitura desta chave neste número acabou (Retry-After = segundos até 00:00 UTC) |
| 503 | 2 | Serviço temporariamente indisponível |
Os erros no formato da Meta trazem o código em error.code. Ver todos os erros.
Corpo da resposta 200#
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| data | object[] | obrigatório | |
| data[].id | string | obrigatório | O id do clique neste número (inteiro, como texto). |
| data[].conversation_id | string | null | obrigatório | |
| data[].wa_id | string | null | obrigatório | |
| data[].received_at | string | obrigatório | Quando a mensagem do clique chegou: segundos desde 1970, como texto. |
| data[].ad_id | string | null | obrigatório | |
| data[].source_type | string | null | obrigatório | ad ou post, como a Meta manda. |
| data[].source_url | string | null | obrigatório | |
| data[].headline | string | null | obrigatório | |
| data[].body | string | null | obrigatório | |
| data[].media_url | string | null | obrigatório | |
| data[].attributable | boolean | obrigatório | true = o clique trouxe o identificador de clique da Meta. Só vale dentro da janela de retenção do identificador (90 dias): depois da purga ele deixa de existir e este campo vira false. Para a conversa, use attribution.attributable, que sobrevive à purga. |
| data[].ad_name | string | null | obrigatório | Do cache do anúncio: null enquanto não foi buscado. |
| data[].adset_id | string | null | obrigatório | |
| data[].adset_name | string | null | obrigatório | |
| data[].campaign_id | string | null | obrigatório | |
| data[].campaign_name | string | null | obrigatório | |
| data[].objective | string | null | obrigatório | |
| paging | object | obrigatório | |
| paging.after | string | null | obrigatório | Cursor opaco da próxima página; null = acabou. |
Limites de taxa#
- Borda: 2000 requisições a cada 10 s por chave × número (API_EDGE_LIMIT).
- Leitura: 30 páginas a cada 60 s por chave × número (API_READ_LIMIT), além do limite de borda.
- Teto diário: 1000 páginas por chave × número por dia UTC (um administrador da organização pode mudar entre 100 e 20.000 por chave em Configurações → Desenvolvedor). Passou: 429, código 1390015, até 00:00 UTC.
Notas#
- Número:
{phone_number_id}precisa ser um número de WhatsApp ativo que a chave alcança; qualquer outro (inclusive o id de uma conta do Instagram) responde 404 (código 100), sem acordar o número. - Plano: exige
apieinbox, conferidos também pelo número a cada chamada: um downgrade recusa na chamada seguinte (403, código 1390011). - Tetos: cada chamada examina no máximo 500 conversas ou contatos (200 mensagens) e para; uma página curta com cursor não nulo quer dizer "continue". Cursores são opacos: um cursor inválido responde 400 (código 100), nunca 5xx.
- Conteúdo de terceiro: nomes e textos que o contato controla saem como chegaram. Uma integração que passa isso a uma IA deve tratar como dado, não como instrução.
curl
curl 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/referrals?since=1767139200&limit=20' \
-H "Authorization: Bearer $SYNERGY_API_KEY"JavaScript
const res = await fetch('https://api.synergyconnect.com.br/v1/numbers/106540352242922/referrals?since=1767139200&limit=20', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
},
});
console.log(res.status, await res.json());Python
import os
import requests
res = requests.get(
"https://api.synergyconnect.com.br/v1/numbers/106540352242922/referrals?since=1767139200&limit=20",
headers={
"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
},
)
print(res.status_code, res.json())200
{
"data": [
{
"id": "77",
"conversation_id": "4182",
"wa_id": "5511999999999",
"received_at": "1767225500",
"ad_id": "120210000000000123",
"source_type": "ad",
"source_url": "https://fb.me/exemplo",
"headline": "Frete grátis hoje",
"body": "Peça pelo WhatsApp",
"media_url": "https://scontent.xx.fbcdn.net/exemplo.jpg",
"attributable": true,
"ad_name": "Frete grátis - vídeo 1",
"adset_id": "120210000000000456",
"adset_name": "Público amplo SP",
"campaign_id": "120210000000000789",
"campaign_name": "Vendas - outubro",
"objective": "OUTCOME_SALES"
}
],
"paging": {
"after": "Wzc3XQ"
}
}400
{
"error": {
"message": "(#100) Invalid parameter.",
"type": "OAuthException",
"code": 100,
"error_data": {
"messaging_product": "whatsapp",
"details": "Invalid cursor."
},
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 2 casos com este status; veja a tabela de respostas.
401
{
"error": {
"message": "(#190) Invalid OAuth access token.",
"type": "OAuthException",
"code": 190,
"fbtrace_id": "syn-3f9a1c0b"
}
}403
{
"error": {
"message": "(#200) Permissions error: this key does not have access to this resource.",
"type": "OAuthException",
"code": 200,
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 4 casos com este status; veja a tabela de respostas.
404
{
"error": {
"message": "(#100) Unsupported request: object does not exist or this key cannot reach it.",
"type": "OAuthException",
"code": 100,
"fbtrace_id": "syn-3f9a1c0b"
}
}429
{
"error": {
"message": "(#130429) Rate limit hit: the number's message throughput has been reached.",
"type": "OAuthException",
"code": 130429,
"fbtrace_id": "syn-3f9a1c0b"
}
}Há 4 casos com este status; veja a tabela de respostas.
503
{
"error": {
"message": "(#2) Service temporarily unavailable.",
"type": "OAuthException",
"code": 2,
"fbtrace_id": "syn-3f9a1c0b"
}
}Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.