Integração com WhatsApp
Conecte o WhatsApp ao Synchro Hub para disparar mensagens de recuperação de carrinho. Tutorial passo a passo dos provedores Meta Cloud, Evolution e Z-API.
Conecte o WhatsApp ao Synchro Hub para disparar mensagens de recuperação de carrinho diretamente para o cliente, com taxa de abertura muito superior à do e-mail.
Visão geral
O Synchro Hub suporta três provedores de WhatsApp. Você escolhe o que combina com seu momento e cadastra a credencial em Configurações → Integrações → Comunicação.
| Provedor | Quando usar |
|---|---|
| Meta Cloud (API oficial) | Quer profissionalismo, métricas completas (entrega, leitura, falha) e zero risco de banimento. |
| Evolution (auto-hospedada) | Tem time técnico, quer custo baixo e flexibilidade total. Sem rastreamento de leitura. |
| Z-API (SaaS brasileira) | Está começando e quer simplicidade. Setup rápido, sem precisar hospedar nada. Sem rastreamento de leitura. |
Importante: Evolution e Z-API usam o WhatsApp de forma não oficial — há risco de banimento do número. A Meta Cloud é o canal homologado pela Meta e não tem esse risco, mas tem janela de 24h para mensagens livres (depois disso, só templates pré-aprovados).
Tempo estimado: 5 a 15 minutos (varia por provedor). O que você vai precisar:
- Workspace já criado no Synchro Hub.
- Credenciais do provedor escolhido (token, URL, número de origem).
Passo 1 — Acessar a tela de integrações
- No menu lateral, acesse Configurações.
- Vá em Integrações → Comunicação.
- Clique em Adicionar credencial.
Se você já tem uma credencial cadastrada, ela aparece em forma de card. Clique no ícone de lápis para editar ou no ícone de lixeira para remover.
Passo 2 — Escolher o provedor e preencher os campos
No modal que abrir, selecione o provedor. Os campos exigidos mudam conforme a escolha:
Meta Cloud (API oficial)
Pré-requisitos:
- Um App criado em developers.facebook.com/apps com o produto WhatsApp habilitado.
- Um número de telefone já vinculado ao WhatsApp Business Account (WABA).
- O System User Access Token (permanente) do Meta Business — não use token temporário de 24h, pois o Synchro Hub precisa armazená-lo para disparar mensagens.
- O Phone Number ID (visível em WhatsApp → Setup no painel da Meta).
Campos a preencher no Synchro Hub:
- Nome — identificação interna da credencial (ex.: “Conta principal”).
- Phone Number ID — identificador do número no painel do WhatsApp Business (Meta).
- Token de API — o System User Access Token permanente.
- Número de origem — número do WhatsApp que vai aparecer para o cliente, no formato internacional (ex.:
5511999999999).
Ao salvar, o Synchro Hub provisiona automaticamente um webhook exclusivo para essa credencial. Você precisa configurar esse webhook no painel da Meta (passos 3 e 4) para receber eventos de leitura, falha e qualidade do número.
Evolution (auto-hospedada)
- Base URL — endereço da sua instância Evolution (ex.:
https://evo.minhaempresa.com). - Instance Name — nome da instância configurada no Evolution.
- Token de API — token gerado pela sua instância.
- Número de origem — número do WhatsApp conectado à instância.
Z-API (SaaS brasileira)
- Instance ID — identificador da instância no painel da Z-API.
- Token de API — token gerado no painel da Z-API.
- Base URL — opcional; só preencha se a Z-API instruir um endpoint específico.
- Número de origem — número conectado na Z-API.
Marque a opção Ativa para que o Synchro Hub possa usar essa credencial nos fluxos de automação de recuperação.
Passo 3 — Salvar a credencial
- Clique em Salvar.
- O Synchro Hub guarda o token de forma criptografada — depois de salvo, ele não fica visível no painel, nem para você. Se precisar trocar, é só clicar em Substituir token na próxima edição.
- O card da credencial aparece na lista, marcado como Ativa.
Passo 4 — Configurar o webhook da Meta Cloud
Este passo só se aplica a credenciais Meta Cloud. Se você está usando Evolution ou Z-API, pode pular para o Passo 5.
Sem essa configuração, o Synchro Hub não recebe sinais de leitura, falha de entrega nem qualidade do número — você fica sem taxa de abertura e sem pausa automática quando a Meta degrada seu número.
4.1 Copiar URL e Verify Token
- Reabra a credencial que acabou de criar (ícone de lápis).
- Role até o card “Webhook da Meta Cloud”. Você vai ver dois campos:
- Callback URL — algo como
https://api.seu-synchro.com/v1/webhooks/whatsapp/meta/<integrationId>. - Verify token — uma string única gerada pelo Synchro Hub.
- Callback URL — algo como
- Use os botões Copiar ao lado de cada campo. Mantenha esta aba aberta.
4.2 Colar no painel Meta Developer
- Abra seu app em developers.facebook.com/apps.
- No menu lateral, acesse WhatsApp → Configuration.
- Na seção Webhook, clique em Edit:
- Callback URL — cole o valor copiado do Synchro Hub.
- Verify token — cole o valor copiado do Synchro Hub.
- Clique em Verify and save. A Meta envia um
GETpara a URL e, se o token bater, o status passa a Verified.
4.3 Assinar os campos certos
Ainda em WhatsApp → Configuration → Webhook, clique em Manage e ative:
| Campo | Para quê |
|---|---|
messages | Confirma leituras (read) e falhas (failed) dos disparos |
message_template_status_update | Avisa quando um template é aprovado ou rejeitado pela Meta |
phone_number_quality_update | Sinaliza degradação do número (GREEN → YELLOW → RED) |
account_update | Avisa restrição ou banimento da conta business |
Sem messages, o funil não terá taxa de abertura. Sem phone_number_quality_update, o Synchro Hub não pausa envios automaticamente quando o número degrada.
Passo 5 — Acompanhar a saúde de entrega (Meta Cloud)
No modal da credencial Meta Cloud, role até o card “Saúde de entrega”:
- Sem dados — ainda não chegou nenhum evento de qualidade. Normal para número recém-cadastrado.
- GREEN — número saudável.
- YELLOW — atenção. A Meta reduziu seu limite. Recomendamos pausar disparos em massa e revisar o conteúdo dos templates.
- RED — o Synchro Hub pausa envios automaticamente por 6 horas. Enquanto a pausa estiver ativa, um banner vermelho mostra até quando os disparos ficam bloqueados.
Passo 6 — Testar o disparo
A forma mais rápida de validar a conexão é enviar um teste a partir de um template de WhatsApp:
- Vá em Recuperação → Templates.
- Selecione um template de WhatsApp (ou crie um novo).
- Use o botão Enviar teste e indique o número que vai receber a mensagem.
- Em segundos, a mensagem deve chegar no WhatsApp do destinatário.
Se a mensagem não chegar, confira a seção de solução de problemas abaixo.
Comparativo de rastreamento
A capacidade de medir abertura e falha varia muito entre provedores. Considere isso na hora de escolher:
| Métrica | Meta Cloud | Evolution | Z-API |
|---|---|---|---|
| Mensagem enviada | ✓ | ✓ | ✓ |
| Mensagem lida | ✓ | — | — |
| Falha de envio | ✓ | — | — |
| Cliques no link | ✓ | ✓ | ✓ |
Solução de problemas
| Sintoma | O que fazer |
|---|---|
| Erro ao salvar a credencial | Confira se o token foi colado sem espaços e se o número de origem está em formato internacional. |
| Webhook da Meta não verifica | Reabra a credencial no Synchro Hub, copie novamente Callback URL e Verify token e cole no painel Meta. Tokens antigos podem ter sido rotacionados. |
| Sem eventos de leitura ou falha | Confirme que o campo messages está assinado em WhatsApp → Configuration → Webhook → Manage no Meta Developer. |
| Banner vermelho de pausa ativa | Qualidade do número foi para RED. Aguarde as 6h de pausa, revise os templates e o ritmo de disparo antes de retomar. |
| Mensagem de teste não chega (Meta Cloud) | Verifique se o destinatário está dentro da janela de 24h ou se você está usando um template pré-aprovado pela Meta. |
| Mensagem de teste não chega (Evolution) | Confirme que sua instância está conectada (QR Code lido) e respondendo no Base URL informado. |
| Mensagem de teste não chega (Z-API) | Acesse o painel da Z-API e veja se a instância está com status Conectado. |
| Número foi banido | Acontece principalmente com Evolution e Z-API por uso não oficial. Cadastre um número novo e considere migrar para Meta Cloud em operações maiores. |
Perguntas frequentes
Posso ter mais de um provedor cadastrado? Para Meta Cloud, sim — você pode cadastrar várias credenciais no mesmo workspace, uma por Phone Number ID. Para Evolution e Z-API, vale uma credencial ativa por workspace; para trocar de provedor, edite a credencial existente.
Posso usar o mesmo número da Meta Cloud em outras ferramentas? Não. A Meta exige número dedicado por aplicação. Use um número exclusivo para o WhatsApp Business / Meta Cloud.
Mensagens de WhatsApp contam na quota do plano? Sim. Cada plano define um limite mensal de mensagens de WhatsApp. O uso aparece em Recuperação → Configurações no banner de quota.
Como desconecto o WhatsApp? No card da credencial, clique em Remover. Os fluxos de automação que dependem do WhatsApp param de disparar mensagens nesse canal até você cadastrar uma nova credencial.