Conexões do WhatsApp: como conectar, gerenciar e migrar canais

A tela de Conexões é onde você gerencia os números de WhatsApp da clínica. Cada número conectado é uma “conexão” (também chamada de “canal” ou “instância”). É por aqui que você conecta um novo número, vê se está tudo certo, reconecta quando cai, e migra para um chip novo sem perder histórico.

Como abrir

Conversas → Cadastros → Conexões (rota /app/instancias-whatsapp).

A tela lista todas as conexões da clínica (ativas, desconectadas, em migração). Cada uma é um card.

O que cada conexão mostra

Cada card de conexão tem:

• Nome de exibição — como você identifica a conexão internamente (ex.: “Recepção”, “Comercial”, “Pós-venda”).
• Número — telefone conectado.
• Status ao vivo — atualizado a cada 30s:
  • Conectado (verde) — sessão ativa, mensagens chegando.
  • Desconectado (vermelho) — sessão perdida, precisa reconectar.
  • Em reconexão (amarelo) — tentando reconectar automaticamente.
  • Erro (vermelho escuro) — falha de comunicação com o WhatsApp. Requer ação manual.
• Setor — agrupa conexões por departamento (ex.: “Atendimento”, “Vendas”). Definido em CANAL_SETORES.
• Conexão padrão? — badge se for a conexão usada por padrão nos envios.
• Ações — QR Code (reconectar), definir padrão, histórico/auditoria, excluir, migrar.

O status ao vivo é o que importa. Mesmo que sua conexão pareça “ativa” pelo histórico, ela pode ter caído sem você perceber. O check de 30s detecta.

Conectar uma nova conexão

+ Nova Conexão:

1. Dê um nome (ex.: “Recepção” — vai aparecer no inbox e nos relatórios).
2. Escolha o setor (se já tiver setores configurados).
3. Um QR Code aparece na tela.
4. No celular, abra o WhatsApp Business (recomendado — ver nota abaixo) → Aparelhos conectados → Conectar um aparelho → aponte a câmera.
5. Em segundos, a conexão fica Ativa e o card aparece na lista com status verde.

Por que WhatsApp Business e não WhatsApp comum? O Business permite uso comercial, mensagens automáticas com template e categorização de conversa. O WhatsApp pessoal também conecta, mas pode ser bloqueado pelo Meta se você usar pra disparo comercial.

Quando a conexão cai

A queda é rara mas acontece (internet do celular cai, WhatsApp é desinstalado, número é desativado pelo cliente, etc.). Quando o sistema detecta:

• O card mostra Desconectado com timestamp.
• Mensagens que tentam sair via essa conexão ficam na fila (vão sair quando reconectar).
• Mensagens que chegam não aparecem no inbox até reconectar.
• O sistema tenta reconectar automaticamente por alguns minutos antes de marcar como erro.

Para forçar reconexão manualmente:

• Abra o card da conexão.
• Clique em QR Code (ou “Reconectar”).
• Novo QR aparece — passe pelo celular de novo.

Definir uma conexão como padrão

Se a clínica tem mais de uma conexão (ex.: “Recepção” e “Pós-venda”), o sistema precisa saber qual usar por padrão para:

• Disparos em massa sem conexão definida.
• Confirmação de agendamento (quando o lead não tem canal atribuído).
• Mensagens automáticas da agenda.

Na lista, use Definir como padrão no card da conexão. A anterior perde o badge. Apenas uma conexão pode ser padrão por vez.

Se você tem vários atendentes em conexões diferentes, configure setores para que cada mensagem saia pelo canal certo. Conexão padrão é só o “fallback”.

Excluir uma conexão

A exclusão é soft delete — a conexão some da lista ativa mas o histórico fica preservado (mensagens, métricas, vínculos com leads). Use para:

• Número antigo que a clínica não usa mais.
• Conexão de teste que não vai pra produção.
• Canal duplicado por engano.

Atenção: se você exclui a única conexão da clínica, o sistema fica sem canal pra enviar. Mensagens param de sair. Antes de excluir, defina outra como padrão (ou conecte uma nova antes).

Migrar de canal (preservar histórico)

A migração é a feature mais valiosa da tela: quando você troca o número de WhatsApp (chip novo, novo aparelho, reforma), a migração leva o histórico junto — conversas, mensagens, vínculos com leads.

Cenário típico: a clínica troca de chip. Você conecta o número novo, e migra as conversas do número antigo para o novo. Os leads passam a ser contactados pelo número novo, sem perder o histórico.

Como migrar:

1. Conecte o canal novo (vai aparecer como segunda conexão na lista).
2. Abra o card do canal antigo (o que você quer desativar).
3. Use Migrar para outro canal.
4. Escolha o canal de destino.
5. O sistema checa dependências (mensagens configuradas, automações, templates) e mostra um resumo.
6. Confirme. A migração é assíncrona (pode levar minutos para clínicas com muito histórico).

A migração não pode ser revertida automaticamente — planeje fazer em horário de baixo movimento (ex.: domingo de manhã).

Auditoria de conexões

Cada ação numa conexão (criar, excluir, migrar, mudar setor, mudar padrão) fica registrada. Use Histórico no card da conexão para ver:

• Quem fez a ação.
• Quando.
• O que mudou (campo a campo, se foi edição).

A auditoria é por conexão, não por clínica. Conexões diferentes têm históricos independentes.

Conexões extras (Meta Ads e Google Ads)

A mesma tela tem uma seção para conexões com Meta (Meta Ads / Facebook Ads) e Google Ads. São conexões de marketing, não de atendimento:

• Meta Ads — vincular a conta de anúncios do Meta para puxar leads de campanhas de Lead Ads e medir conversão. Um guia específico dessa integração será publicado na Central de Ajuda.
• Google Ads — vincular para puxar conversões offline e medir ROI.

Essas conexões são independentes do WhatsApp. Você pode conectar Meta/Google mesmo sem nenhum WhatsApp conectado.

Permissões

• Ver conexões: permissão cadastros.canais (ou legado whatsapp.visualizar).
• Conectar nova / excluir / migrar: geralmente restrita a gerentes / admin.
• Definir padrão: admin.
• Ver auditoria: admin.

Boas práticas

• Use nomes descritivos. “Recepção”, “Comercial”, “Pós-venda” — em vez de “Conexão 1”, “Conexão 2”.
• Defina uma conexão padrão sempre. Mensagens sem canal definido caem na padrão, e sem padrão o sistema não sabe pra onde mandar.
• Monitore o status. Mesmo que a conexão pareça ativa, vale checar a lista de conexões uma vez por semana — o status é ao vivo, então você detecta antes de uma paciente reclamar.
• Documente o “chip da clínica”. O número físico está num celular — mantenha um registro (interno) de quem é o responsável por esse celular e o que acontece se o celular quebrar.
• Migração é rara, mas planeje. Se a clínica troca de chip todo ano (ex.: chip pré-pago), use a migração em vez de simplesmente excluir e criar — preserva o histórico de anos.

Perguntas rápidas

Conectei mas a conexão cai em poucas horas. Pode ser: (a) o celular está sem internet, (b) o WhatsApp foi desinstalado, (c) o número foi desativado pela operadora. Verifique o celular e reconecte.

Tenho duas conexões, qual é a padrão? Olhe o badge “Padrão” no card. Se nenhuma tem, clique em Definir como padrão na que você quer usar.

Quero desconectar temporariamente (ex.: manutenção). Não há “desconectar temporário”. Você tem duas opções: excluir (perde o status, mantém histórico) ou deixar conectada (status pode cair, mas é fácil reconectar).

Como faço pra mudar o nome de uma conexão? Abra o card, clique no ícone de editar ao lado do nome. Salva na hora.

Migrar e excluir é a mesma coisa? Não. Migrar leva o histórico para outra conexão. Excluir apenas remove da lista (histórico fica em outro lugar do sistema, mas a conexão não tem mais status).

Dúvidas sobre conexões múltiplas, migração ou Meta/ Google? Chame o suporte pelo WhatsApp — a gente configura junto com você.