O que mudou nas conversas
GET/v1/numbers/{phone_number_id}/conversations/changes
As conversas que mudaram desde a revisão since (até 50) e os ids das que saíram. É o jeito barato de manter uma cópia sincronizada: chame com o rev da resposta anterior.
Com since=0, longe demais, ou adiante do servidor, a resposta vem com reset: true e já traz as conversas com mensagens não lidas que não estão com a automação — nunca é preciso uma segunda chamada.
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 |
|---|---|---|---|
| since | integer | opcional | A revisão da última resposta (rev). 0 ou ausente = recomeçar. |
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 | — | Uma conversa mudou |
| 200 | — | Recomeço: as não lidas |
| 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 |
|---|---|---|---|
| rev | integer | obrigatório | A revisão nova: guarde e mande no próximo since. |
| reset | boolean | obrigatório | true = o since estava longe, zerado ou adiante do servidor: data traz as conversas com mensagens não lidas que não estão com a automação (até 50), e o estado local deve ser refeito a partir delas. |
| data | object[] | obrigatório | |
| data[].id | string | obrigatório | O id da conversa neste número. |
| data[].wa_id | string | null | obrigatório | |
| data[].name | string | null | obrigatório | O nome do contato (o de exibição, se houver). Texto do contato. |
| data[].status | string | obrigatório | Valores: pending, open, resolved, automated. |
| data[].unread | integer | obrigatório | |
| data[].automation | string | null | obrigatório | key:<id da chave> quando uma automação é dona da conversa. |
| data[].window_expires_at | string | null | obrigatório | Quando fecha a janela de 24 h: segundos desde 1970, como texto. |
| data[].last_message | object | null | obrigatório | |
| data[].attribution | object | null | obrigatório | De que anúncio veio o lead (o último que ele clicou). null = orgânico. Os campos do anúncio vêm do cache da Synergy e ficam null enquanto o anúncio não foi buscado ou deu erro. Nunca traz o identificador do clique. headline é texto do anúncio: trate como dado. |
| removed | string[] | obrigatório | Ids de conversas que saíram desde since. |
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.
Requisição
curl
curl 'https://api.synergyconnect.com.br/v1/numbers/106540352242922/conversations/changes?since=9100' \
-H "Authorization: Bearer $SYNERGY_API_KEY"JavaScript
const res = await fetch('https://api.synergyconnect.com.br/v1/numbers/106540352242922/conversations/changes?since=9100', {
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/conversations/changes?since=9100",
headers={
"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}",
},
)
print(res.status_code, res.json())Resposta
200
{
"rev": 9120,
"reset": false,
"data": [
{
"id": "4182",
"wa_id": "5511999999999",
"name": "Maria Souza",
"status": "pending",
"unread": 2,
"automation": null,
"window_expires_at": "1767312000",
"last_message": {
"direction": "in",
"preview": "Oi, meu pedido chegou?",
"timestamp": "1767225600"
},
"attribution": {
"ad_id": "120210000000000123",
"headline": "Frete grátis hoje",
"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",
"attributable": true,
"clicked_at": "1767225500"
}
}
],
"removed": []
}Há 2 casos com este status; veja a tabela de respostas.
400
{
"error": {
"message": "(#100) Invalid parameter.",
"type": "OAuthException",
"code": 100,
"error_data": {
"messaging_product": "whatsapp",
"details": "Invalid query parameter."
},
"fbtrace_id": "syn-3f9a1c0b"
}
}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.