Autenticação

Toda chamada usa uma chave de API no header Authorization: Bearer <chave>, o mesmo header dos SDKs da Meta. Não há outro lugar aceito: nem query string, nem outro header.

Formato da chave#

A chave tem a forma syn_<orgId>_<40 caracteres>_<10 caracteres>. Uma chave malformada ou forjada é recusada antes de chegar ao número. A Synergy guarda só o hash: a chave completa é mostrada uma única vez, ao ser criada.

Exemplo

curl

curl 'https://api.synergyconnect.com.br/v1/webhooks' \
  -H "Authorization: Bearer $SYNERGY_API_KEY"

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v1/webhooks', {
  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/webhooks",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
)
print(res.status_code, res.json())

Escopos#

Escopo	Libera	Rótulo no app
`messages`	Mensagens, mídia, pedido de atendimento humano e token de Flow	Enviar mensagens
`management`	Cadastrar, editar, testar e consultar webhooks	Gerenciar webhooks

Uma chave sem o escopo recebe 403 (código 200 nas rotas no formato da Graph API; This key lacks the management scope na gestão).

Modo e números#

Cada chave tem um modo, que decide para onde vai a resposta do cliente:

Notificações (notify): a resposta vai para a fila dos atendentes.
Bot de atendimento (bot): a resposta continua com a integração. Se uma pessoa assumir a conversa, a chave bot para de enviar (409, código 1390001) até a conversa voltar para a automação.

A chave pode valer para todos os números ou só para alguns. Usada em outro número, recebe 401 (código 190), a mesma resposta de uma chave revogada.

Criar, rotacionar e revogar#

Tudo é feito no app, em Configurações → API e webhooks → Chaves de API, por um administrador. Não há rota da API para gerenciar chaves.

Criar: Nova chave. A chave aparece uma vez só.
Editar: nome, modo, escopos e números podem mudar; vale na hora, em todos os números. A chave em si não muda.
Rotacionar: não existe "trocar" uma chave. Crie uma segunda chave, ponha-a no sistema, confira que o tráfego passou a usá-la e então revogue a antiga. Cada sistema deve ter a sua chave, assim revogar uma não derruba as outras.
Revogar: no menu da chave. O sistema que a usa para de enviar na hora, em todos os números; as mensagens já enviadas continuam nas conversas. Não dá para desfazer.

Uma chave revogada recebe 401. Na gestão de webhooks, uma chave recusada (revogada, ou sem o escopo management) continua recebendo 401 Invalid or revoked key por 60 s, mesmo que a primeira recusa tenha sido um 403.

Boas práticas#

Guarde a chave em variável de ambiente ou cofre de segredos; nunca no código nem no navegador.
Uma chave por sistema, com só os escopos e os números de que ele precisa.
Revogue a chave suspeita de vazamento e crie outra.
Não registre a chave em logs.
Para webhooks, o segredo de assinatura é outro: veja Webhooks.

Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.