Synergy Connect

Documentação

Desenvolvedores

Conecte o WhatsApp da empresa ao seu sistema

A API pública da Synergy Connect tem a forma da Cloud API do WhatsApp (Graph API da Meta): mesmos caminhos, corpos, respostas e códigos de erro para envio e mídia. Uma integração feita para a Meta troca o host e o token. Rotas /v1/… são da Synergy: pedir um atendente, emitir o token de um Flow e gerir os webhooks da organização.

O host da API é https://api.synergyconnect.com.br. Não há URL de staging da API pública.

https://api.synergyconnect.com.br
A API faz parte dos planos com “API e webhooks” e do plano Developer, só API, sem inbox. Ver planos

Para quem é#

Para quem integra um sistema da empresa (ERP, loja, CRM, bot) ao WhatsApp: enviar mensagens e mídia, passar uma conversa para uma pessoa e receber os eventos em um servidor próprio. O número continua sob a plataforma: a API não registra números, não mexe no PIN e não inscreve aplicativos. Qualquer outro caminho responde 404 (código 100).

O que a API faz#

Quero…ChamadaEscopo da chave
Enviar uma mensagemPOST /{version}/{phone_number_id}/messagesmessages
Enviar, consultar, baixar e apagar mídia/{version}/{phone_number_id}/media, /{version}/{media_id}messages
Passar a conversa para um atendentePOST /v1/numbers/{phone_number_id}/handoffmessages
Emitir o token de um WhatsApp FlowPOST /v1/numbers/{phone_number_id}/flows/{flow_id}/tokenmessages
Gerir webhooks/v1/webhooks…management

{version} é a versão da Graph API da Meta que a integração usa (por exemplo v25.0), repassada à Meta como veio. A versão desta API (v1) é só o prefixo das rotas próprias.

Início rápido#

1. Crie a conta#

Crie a conta na página de cadastro do app e conecte ao menos um número de WhatsApp. A API exige a feature api no plano.

2. Gere a chave de API#

No app, abra Configurações → API e webhooks (rota /settings/developer, grupo "Organização"). Só administradores da organização veem essa página. Em "Chaves de API", clique em Nova chave, dê um nome, escolha o modo (Notificações ou Bot de atendimento), os escopos e os números, e clique em Criar chave. A chave aparece uma única vez: copie e guarde. No mesmo cartão "Como conectar" está o phone_number_id de cada número.

3. Faça a primeira chamada#

Uma resposta 200 traz messages[0].id (o wamid). Fora da janela de 24 h do cliente a Meta exige um modelo (type: "template") e responde com o erro dela (por exemplo 131047).

Exemplo

curl

export SYNERGY_API_KEY='syn_...'

curl -X POST 'https://api.synergyconnect.com.br/v25.0/106540352242922/messages' \
  -H "Authorization: Bearer $SYNERGY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"messaging_product":"whatsapp","to":"5511999999999","type":"text","text":{"body":"Seu pedido saiu para entrega."}}'

JavaScript

const res = await fetch('https://api.synergyconnect.com.br/v25.0/106540352242922/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNERGY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    to: '5511999999999',
    type: 'text',
    text: { body: 'Seu pedido saiu para entrega.' },
  }),
});
console.log(res.status, await res.json());

Python

import os

import requests

res = requests.post(
    "https://api.synergyconnect.com.br/v25.0/106540352242922/messages",
    headers={"Authorization": f"Bearer {os.environ['SYNERGY_API_KEY']}"},
    json={
        "messaging_product": "whatsapp",
        "to": "5511999999999",
        "type": "text",
        "text": {"body": "Seu pedido saiu para entrega."},
    },
)
print(res.status_code, res.json())

Paginação#

A API não pagina. Nenhuma rota devolve cursor ou next: GET /v1/webhooks devolve todos os webhooks da organização que a chave alcança (o limite é de 20 por organização). Por isso não há guia de paginação.

Guias#

AutenticaçãoToda chamada usa uma chave de API no header Authorization: Bearer <chave>, o mesmo header dos SDKs da Meta.Abrir →ErrosHá dois formatos, conforme a rota.Abrir →Limites de taxaToda recusa por limite é um 429 com Retry-After (segundos).Abrir →WebhooksWebhooks entregam em uma URL sua os eventos do WhatsApp, no envelope da Meta (object: "whatsappbusinessaccount"), assinados como a Meta assina.Abrir →WhatsApp FlowsUm Flow é um formulário que o cliente preenche dentro do WhatsApp.Abrir →ChangelogMudanças aditivas na v1: nada que existia mudou de comportamento, e as integrações atuais continuam funcionando.Abrir →SDK para JavaScript e TypeScriptO @synergyconnectapp/sdk é a biblioteca oficial para chamar a API pública em JavaScript e TypeScript.Abrir →n8nO pacote @synergyconnectapp/n8n-nodes-synergy-connect traz para o n8n dois nodes da Synergy Connect: Synergy Connect (ações) e Synergy Connect Trigger (receber eventos).Abrir →Cadastro hospedado de númerosO cadastro hospedado deixa o seu cliente conectar o WhatsApp dele (o número e a conta do WhatsApp Business) à sua organização na Synergy, sem você montar o Embedded Signup da Meta.Abrir →Conectar uma IA (MCP)O servidor MCP da Synergy Connect deixa um assistente de IA (Claude, ChatGPT e outros clientes que falam MCP) consultar e enviar mensagens de WhatsApp da sua organização, com a sua permissão e dentro de limites que você define.Abrir →Ler conversasAlém de enviar e receber por webhook, a API deixa a sua integração consultar as conversas de um número: listar, buscar, ler as mensagens e acompanhar o que mudou.Abrir →PaginaçãoAs rotas que devolvem listas (conversas, mensagens, contatos) são paginadas por cursor.Abrir →Assinatura dos webhooksToda entrega de webhook vem assinada, para você ter certeza de que foi a Synergy quem enviou, e de que o corpo não foi alterado no caminho.Abrir →InstagramA conta do Instagram conectada à Synergy usa a mesma API, a mesma chave e o mesmo formato de erro do WhatsApp.Abrir →JornadasUma Jornada é um fluxo de conversa que você monta no app (Jornadas): mensagens, botões, perguntas, esperas, ramificações, pedidos de dado e a passagem para um atendente.Abrir →Referência da APIUma página por rota, com parâmetros, respostas e exemplos em curl, JavaScript e Python.Abrir →

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