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:

Dê um nome (ex.: “Recepção” — vai aparecer no inbox e nos relatórios).
Escolha o setor (se já tiver setores configurados).
Um QR Code aparece na tela.
No celular, abra o WhatsApp Business (recomendado — ver nota abaixo) → Aparelhos conectados → Conectar um aparelho → aponte a câmera.
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.

Conectar com número de telefone (sem câmera)

No modal Conectar WhatsApp, escolha Conectar com número de telefone. Informe o número com DDI e DDD (ex.: +55 11 99999-9999) e clique em Gerar código. No celular desse número, abra Aparelhos conectados → Conectar um aparelho → Conectar com número de telefone e digite os oito caracteres exibidos no North.

Aguarde a confirmação de conexão antes de fechar. Gerar o código, por si só, ainda não conecta o canal. O contador indica o tempo de verificação da conexão, não a validade do código. Use-o imediatamente; se o WhatsApp indicar expiração, clique em Gerar novo código. Se a verificação terminar antes de você concluir, clique em Verificar conexão novamente.

Essa alternativa também funciona no modal de reconexão. Você pode voltar a Conectar com QR Code sem fechar o modal. Se o celular pedir uma chave de acesso adicional, siga as instruções nele; se não concluir, procure o suporte.

Conectar a API Oficial manualmente

Se você pergunta “onde vejo esses códigos?” ou “o que precisa além do token?”, são três dados: Phone Number ID, WABA ID e Access Token Permanente. O número precisa estar configurado na Cloud API da Meta. Se estiver começando, a aba Conectar com Facebook, quando disponível, preenche as credenciais e configura os webhooks automaticamente.

Onde encontrar os IDs do número

Entre com uma conta que tenha acesso ao portfólio empresarial e à conta WhatsApp Business da clínica. Os nomes dos menus da Meta podem variar conforme o idioma e a versão do painel.

No Meta for Developers, abra o aplicativo ligado ao WhatsApp da clínica.
Entre em WhatsApp → Configuração da API (API Setup), também apresentada como Primeiros passos (Getting Started).
Selecione o número correto no seletor de remetente. Copie o Phone Number ID e o WhatsApp Business Account ID exibidos para essa conta. Confira se selecionou o número real da clínica, e não o número de teste da Meta.
Para conferir o WABA, abra o Meta Business Suite → Configurações → Contas → Contas do WhatsApp. Selecione a conta da clínica e confira seu ID. O WhatsApp Manager permite conferir os números vinculados a ela.

O Phone Number ID identifica o número dentro da Meta; não é o telefone com DDD. O WABA ID identifica a conta WhatsApp Business; não é o ID do portfólio empresarial, do aplicativo, da conta de anúncios ou do pixel. Uma WABA pode ter vários números. Veja também a documentação oficial da Meta sobre a Cloud API.

Como gerar o token permanente

O token temporário do painel de testes não serve para manter a integração. Para uso contínuo, o administrador do portfólio deve gerar um token de usuário do sistema:

No Business Suite, abra Configurações → Usuários → Usuários do sistema.
Crie ou selecione o usuário do sistema responsável pela integração.
Em Adicionar ativos, atribua o aplicativo usado na integração e o acesso necessário à conta WhatsApp Business. Se a WABA não aparecer ali, confira a atribuição em Contas → Contas do WhatsApp → Acesso à conta.
Em Gerar token, selecione o aplicativo e as permissões whatsapp_business_messaging e whatsapp_business_management.
Escolha a validade Nunca, quando disponível, para obter o token sem expiração programada. Se essa opção ou as permissões não aparecerem, peça ao administrador que revise o acesso do aplicativo e dos ativos.
Guarde o token em local seguro e cole-o somente no campo de credencial do North. Mesmo um token permanente pode ser revogado ou perder acesso.

Consulte a referência da Meta sobre tokens de acesso. Não envie tokens em prints, artigos ou mensagens de atendimento.

Onde colar no North

Em Conversas → Cadastros → Conexões → Nova Conexão, escolha API Oficial e abra Configuração Manual, na seção Credenciais da API Oficial (Meta).

Dado da Meta	Campo no North
ID do número	Phone Number ID
ID da conta WhatsApp Business (WABA)	WhatsApp Business Account ID
Token do usuário do sistema	Access Token Permanente

Preencha também nome de exibição, setor, nome do negócio, funil e etapa padrão exigidos no formulário, confira a clínica selecionada e clique em Salvar. Os campos dos IDs aceitam apenas dígitos, sem espaços ou trechos de URL. A tela de Templates usa a conexão cadastrada; os três dados são informados em Conexões.

Preparar o recebimento das mensagens

Na configuração manual, siga também as instruções de recebimento exibidas no formulário: compartilhar a WABA com o parceiro North CRM e configurar, no aplicativo Meta, o webhook e a assinatura do campo messages. Use a URL de callback indicada na tela e solicite ao suporte o token de verificação. Esse token é diferente do Access Token Permanente.

Depois de salvar, valide o recebimento de uma mensagem de teste e uma resposta pelo North. Salvar as credenciais não comprova que o recebimento está funcionando.

“Phone Number ID ou WABA ID não existe” / “Sem permissão ou ID inválido”

Esses avisos podem significar ID incorreto ou falta de acesso do token. Confira, nesta ordem:

Os IDs foram copiados dos campos certos e o número pertence à WABA?
O aplicativo e o usuário do sistema têm acesso à WABA da clínica?
O token tem as permissões acima, está válido e foi copiado por inteiro?
Foi usado o número real, sem misturar dados de outra clínica ou de teste?

Se persistir, informe ao suporte a clínica, o horário e a mensagem do erro, com um print que oculte o token. Não exclua o número nem recrie a WABA para tentar resolver um erro de permissão.

Custos e pagamento da API Oficial (Meta)

A API Oficial do WhatsApp é tarifada pela Meta por conversa. A cobrança é feita diretamente pela Meta e não está inclusa na mensalidade do North. Os valores variam conforme a categoria e as regras de tarifação vigentes na conta WhatsApp Business.

Antes de conectar ou criar uma conta WhatsApp Business (WABA), cadastre uma forma de pagamento válida no Meta Business Manager. Sem uma forma de pagamento válida, a Meta pode restringir a cobrança e bloquear o envio de mensagens, mesmo que a conexão apareça como ativa no North.

Para cadastrar ou atualizar o pagamento:

Abra o Meta Business Manager.
Acesse Cobrança e pagamentos.
Selecione a conta WhatsApp Business usada pela clínica.
Adicione uma forma de pagamento válida e confira se não há faturas ou restrições pendentes.

A tarifação e a cobrança são definidas e processadas pela Meta. Consulte o painel da própria conta antes de iniciar campanhas ou automações para confirmar os valores vigentes.

O número da API oficial parou de enviar

Se as mensagens ficam vermelhas, mostram Tentar novamente ou o número oficial deixa de enviar, comece pela cobrança da Meta — mesmo que a conexão ainda apareça ativa no North:

confira o cartão e eventuais faturas em Cobrança e pagamentos;
se a conta usa crédito administrado por uma agência, confirme que ainda existe saldo disponível;
regularize a pendência e faça um novo teste de envio.

Com o pagamento regular, prossiga verificando o status da conexão, a aprovação do template e a janela de 24 horas. Não desconecte o número nem recrie a WABA antes de eliminar essas causas.

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”).
Leia o novo QR no celular ou escolha Conectar com número de telefone no modal para usar um código de pareamento.

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).

Ao pausar uma conexão que ainda envia mensagens automáticas, o North mostra as regras afetadas e avisa que elas também serão desativadas. Você pode cancelar ou confirmar Desativar canal e mensagens.

Ao excluir uma conexão, também é possível migrar as regras para outro canal ativo antes de continuar.

Isso evita que uma automação pare silenciosamente por continuar ligada a um canal indisponível. A operação não reenvia mensagens antigas.

Essa migração cobre as mensagens automáticas vinculadas ao canal. Regras de Distribuição de Leads filtradas por canal precisam ser revisadas separadamente em Leads → Cadastros → Distribuição e apontadas para o canal novo.

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:

Conecte o canal novo (vai aparecer como segunda conexão na lista).
Abra o card do canal antigo (o que você quer desativar).
Use Migrar para outro canal.
Escolha o canal de destino.
O sistema checa dependências (mensagens configuradas, automações, templates) e mostra um resumo.
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. Para devolver agendamentos e compras à Meta, veja API de Conversões e requisitos de ativação.
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

Ao escanear o QR aparece “número já conectado em outro canal”. O número já está ativo em outro canal da clínica — as conversas dele já chegam no inbox para todos os usuários, não precisa conectar de novo. Veja Número já conectado em outro canal.

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ê.