Synergy Connect

Documentação

EntrarCriar conta

Changelog

2026-10-06: Instagram e Jornadas#

Mudanças aditivas na v1: nada que existia mudou de comportamento, e as integrações atuais continuam funcionando. O envio e os webhooks do WhatsApp seguem iguais.

Instagram (Instagram)

  • POST /{version}/{ig-user-id}/messages: envia uma mensagem direta (texto, respostas rápidas, mídia, botões e ações de digitação) por uma conta do Instagram conectada, com a mesma chave, o mesmo Idempotency-Key e o mesmo formato de erro. O corpo é o do Instagram, e a resposta é { recipient_id, message_id }. Exige os recursos api e instagram no plano.
  • recipient.comment_id envia a resposta privada a um comentário: entra na fila das Jornadas e responde 202 { queued: true, comment_id }.
  • A rota decide pelo id se é um número do WhatsApp ou uma conta do Instagram. Um id novo que a chave não pode mais tentar naquele minuto (30 por minuto) recebe 429 com Retry-After: 1, nunca um 404 falso.
  • A janela de 24 horas é conferida pela Synergy (erro 10, subcódigo 2534022), e a API nunca usa a etiqueta Human Agent. Chaves de assistente (MCP) não enviam pelo Instagram: 403, código 200.

Jornadas (Jornadas)

  • GET /{version}/{id}/journeys: as Jornadas ativas da conta (id, name, trigger), com escopo messages ou read.
  • POST /{version}/{id}/journeys/{journey_id}/runs: inicia uma Jornada de gatilho "API" para uma pessoa (recipient.id no Instagram, recipient.wa_id no WhatsApp), com Idempotency-Key obrigatório. Responde 202 { run_id }. Exige api, journeys e journeysPro.

Webhooks (Webhooks)

  • Novos campos para assinar: messaging_postbacks, message_reactions, messaging_seen, messaging_referral, message_edit, messaging_optins, comments, live_comments e mentions (os nomes da Meta para o Instagram), e os da Synergy synergy_comment_actions e synergy_journeys. messages vale para os dois canais.
  • Os eventos de uma conta do Instagram saem com object: "instagram" e entry[].id igual ao ig-user-id. Só são enviados se o plano tem o recurso instagram quando o evento chega.
  • Os comentários de uma mesma entrega da Meta saem em um envelope por endpoint, e uma conta do Instagram entrega no máximo 60 envelopes por minuto a cada endpoint (o excedente é descartado e contado).

2026-10-06: leitura, modelos, cadastro hospedado, assinatura com carimbo e ferramentas#

Mudanças aditivas na v1: nada que existia mudou de comportamento, e as integrações atuais continuam funcionando.

Novas rotas

  • GET /v1/me e GET /v1/numbers: quem é a chave (escopos, plano) e quais números ela alcança. Qualquer escopo serve.
  • Leitura de conversas, com o novo escopo read (Ler conversas): GET …/conversations, POST …/conversations/search, GET …/conversations/changes, GET …/conversations/{conversation_id}/messages e POST …/contacts/search, todas em /v1/numbers/{phone_number_id}/. Exigem api e inbox no plano, e têm limite de taxa e teto diário próprios (erro 1390015, e 1390011 quando o plano não tem inbox).
  • Modelos pela API (Modelos de mensagem (templates)): listar e consultar (escopo messages); criar, editar, apagar e subir a mídia de exemplo (escopo management), por número.
  • Cadastro hospedado de números, com o novo escopo onboarding (Cadastro hospedado de números): POST /v1/onboarding-sessions, GET /v1/onboarding-sessions/{session_id} e POST …/cancel; e o evento de webhook synergy_onboarding.

Webhooks

  • Nova assinatura X-Synergy-Signature (t=<segundos>,v1=<HMAC de t.id.corpo>), com carimbo de tempo e tolerância de 300 s, além do X-Hub-Signature-256, que segue igual (Assinatura dos webhooks).
  • O X-Synergy-Delivery-Id agora só tem A-Za-z0-9_- (até 200 caracteres), porque entra na conta da assinatura entre dois pontos. O id do evento é normalizado de forma legível e sem colisões: _ vira __, : vira _c, . vira _d e qualquer outro caractere vira _x mais o hexadecimal do byte, então ev-abc:1a2b3c4d chega como ev-abc_c1a2b3c4d. O mesmo evento segue com o mesmo id em toda retentativa, e o t da X-Synergy-Signature tem de 1 a 12 dígitos. A regra completa está em Assinatura dos webhooks.
  • Os webhooks ganham um name opcional. Uma chave restrita a alguns números agora pode criar webhooks sem instanceIds: o webhook nasce restrito aos mesmos números.

Chaves

  • Os escopos agora são messages, management, read e onboarding. Chaves e corpos desconhecidos nas rotas de gestão são recusados com 400 (nenhum campo extra é aceito).
  • Chaves de assistente (para o MCP) têm limites próprios de envio, por hora e por dia, e opção "só responder" (erros 1390012 e 1390013).

Ferramentas e guias

v1: 2026-10-05#

Versão atual da API pública. v1 é o prefixo das rotas próprias (/v1/…); nas rotas no formato da Graph API, {version} é a versão da Graph API da Meta escolhida pela integração (o exemplo dos guias usa v25.0), não uma versão desta API.

Esta é a primeira publicação da documentação. O que a versão inclui:

  • Envio de mensagens e mídia no contrato da Cloud API da Meta.
  • POST /v1/numbers/{phone_number_id}/handoff: passar uma conversa para um atendente.
  • POST /v1/numbers/{phone_number_id}/flows/{flow_id}/token: token para enviar WhatsApp Flows.
  • Gestão de webhooks em /v1/webhooks…: criar, listar, alterar, apagar, trocar o segredo, tentar de novo, reenviar, testar, saúde e métricas.
  • Webhooks assinados com X-Hub-Signature-256, com X-Synergy-Delivery-Id para idempotência.
  • O documento OpenAPI 3.1 da API é a referência completa de caminhos, corpos e respostas.

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