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.
O que dá para fazer#
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… | Chamada | Escopo da chave |
|---|---|---|
| Enviar uma mensagem | POST /{version}/{phone_number_id}/messages | messages |
| Enviar, consultar, baixar e apagar mídia | /{version}/{phone_number_id}/media, /{version}/{media_id} | messages |
| Passar a conversa para um atendente | POST /v1/numbers/{phone_number_id}/handoff | messages |
| Emitir o token de um WhatsApp Flow | POST /v1/numbers/{phone_number_id}/flows/{flow_id}/token | messages |
| 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).
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.
Mensagens#
Guias#
Ficou com dúvida? Escreva para suporte@synergyconnect.com.br.