n8n

O 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). Com eles você envia mensagens, gerencia modelos e reage a mensagens recebidas sem escrever código.

Em breve. A versão 1.0.0 do node, descrita aqui, ainda não está publicada no npm. Quando a 1.0.0 sair, ela chega pela instalação de nodes da comunidade do n8n. Até lá, o mesmo resultado se obtém com o node HTTP Request do n8n chamando a API (Enviar mensagens) e um Webhook recebendo os eventos (Webhooks).

Instalar e conectar#

No n8n, abra Settings → Community nodes → Install e informe @synergyconnectapp/n8n-nodes-synergy-connect.
Crie a chave no app: Configurações → API e webhooks → Nova chave, com os escopos messages e management (o trigger cria o webhook, e isso exige management). Para Template com escrita também vale management. Veja Autenticação.
No n8n, crie a credencial Synergy Connect API:

Campo	Valor
API Key	A chave `syn_…`
Base URL	`https://api.synergyconnect.com.br` (o padrão)
Phone Number ID	Opcional: o número padrão dos nodes

O teste da credencial chama GET /v1/me e nunca envia mensagem. A URL precisa ser https.

O node de ações#

Recurso	Operações
Message	Send Text, Send Image, Send Video, Send Audio (opção Voice), Send Document, Send Sticker, Send Location, Send Contacts, Send Template, Send Buttons, Send List, Send Reaction, Send Raw (JSON), Mark as Read
Media	Upload, Get, Download (o arquivo vem em `binary`), Delete
Template	Get Many, Get, Create, Update, Delete, Upload Example Media
Conversation	Hand Off to Agent
Flow	Send Flow (emite o token e envia numa ação só)

Em Phone Number, escolha "From list" (o node lista seus números por GET /v1/numbers) ou "By ID".

Exemplo: avisar a cliente que o pedido saiu#

Um workflow com um gatilho da sua loja (por exemplo "Webhook" ou "Shopify Trigger") ligado a um node Synergy Connect:

Resource: Message; Operation: Send Template
Phone Number: seu número
To: {{ $json.cliente.telefone }} (apenas dígitos, com DDI: 5511999999999)
Template: pedido_enviado (o node lista os modelos aprovados), idioma pt_BR
Body Variables: {{ $json.cliente.nome }} e {{ $json.pedido.numero }}

O node faz a chamada que você faria à mão:

E a saída do node é a resposta da API:

Opções de mensagem#

Reply To Message ID: responde citando uma mensagem.
Idempotency Key: por padrão {{$execution.id}}-{{$itemIndex}}. Se o n8n repetir a execução, a mensagem não duplica.
Replies Go To: para onde vão as respostas do cliente (fila de atendimento ou automação).
Graph API Version: padrão v25.0.

Mensagem fora da janela de 24 h só vai como modelo (Janela de atendimento de 24 horas). O node explica os erros mais comuns: 401 e 403 (escopo, plano), 429 (com o Retry-After). Hand Off to Agent exige um plano com caixa de entrada (inbox).

Exemplo

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":"template","template":{"name":"pedido_enviado","language":{"code":"pt_BR"},"components":[{"type":"body","parameters":[{"type":"text","text":"Maria"},{"type":"text","text":"#42"}]}]}}'

JSON

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
  "messages": [{ "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABEYEjI0QUY0QTk3QjI4QjE4MDBGNQA=" }]
}

O trigger#

Synergy Connect Trigger cria e mantém um webhook na Synergy (Webhooks) apontando para a URL do workflow. Ao ativar o workflow, ele cadastra o webhook; ao desativar, apaga.

Opção	Para quê
Events	Message Received (padrão), Message Status Update, Message Echo, Conversation Status Changed, Template Status/Quality/Category, Phone Number Quality/Name, Account Update/Alerts, Group Lifecycle/Participants/Settings e Onboarding Result (exige uma chave com o escopo `onboarding`; veja Cadastro hospedado de números). Em "Advanced": calls, history, app state sync e business capability
Phone Numbers	Opcional: limita a alguns números. Vazio = todos os da chave
Output Mode	`single` (um item por envelope), `perEventType` ou `perMessageSubtype` (separa, por exemplo, a resposta de um Flow)

O trigger confere a assinatura de toda entrega antes de rodar o workflow, com X-Synergy-Signature (tolerância de 300 s) quando presente, ou X-Hub-Signature-256 (Assinatura dos webhooks). Entrega sem assinatura válida recebe 401 e não dispara nada. O synergy_ping do cadastro é respondido sem disparar o workflow.

Cada item de saída leva, além do conteúdo do evento, os campos _deliveryId, _timestamped, _eventType, _instanceId e _wabaId. Use _deliveryId para descartar eventos repetidos: a entrega é ao menos uma vez.

Exemplo de item para uma mensagem recebida:

O webhook criado se chama n8n · <workflow> · prod (ou test, na execução de teste), para você reconhecê-lo em Configurações → API e webhooks. A URL do workflow precisa ser pública e https: o trigger recusa localhost, IP privado e http:.

JSON

{
  "_deliveryId": "ev-3f9a1c0b7d2e:0b9c4d1e",
  "_timestamped": true,
  "_eventType": "messages",
  "_instanceId": "3f9a1c0b7d2e4a6f8b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "_wabaId": "102290129340398",
  "messages": [{ "from": "5511999999999", "id": "wamid.TEST.6f1c2a0e", "timestamp": "1767225600", "type": "text", "text": { "body": "Oi, meu pedido chegou?" } }]
}

Não confunda com o pacote antigo#

Existe no npm um pacote chamado n8n-nodes-synergy-connect (sem @synergyconnectapp/). Ele é da Synergy antiga, outra plataforma, e não funciona com a Synergy Connect. Este pacote é novo e separado, e não há migração entre os dois: instale o que tem @synergyconnectapp/ no nome e crie a credencial com uma chave syn_…. O node recusa credenciais que apontam para a plataforma antiga, com uma mensagem dizendo o que trocar.

Limites do node#

Só WhatsApp. Conta do Instagram não aparece nos nodes.
Sem leitura de conversas: para isso use o SDK, a API (Ler conversas) ou o MCP.
A gestão dos webhooks é só do trigger; o node de ações não tem o recurso Webhook.

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