Como ativar uma nova caixa WhatsApp no MágicaChat usando Evolution API

Visão geral

Este guia ajuda clientes que usam Mágica Chat, Chatwoot, Kanban Conexão Azul ou uma operação self-hosted/SaaS com Evolution API a ativar novas caixas de entrada WhatsApp com mais segurança.

O objetivo é evitar um problema comum: o WhatsApp aparece como conectado, mas a caixa não recebe ou não envia corretamente pelo MágicaChat.

Na prática, conectar o WhatsApp é apenas uma parte do processo. Depois disso, a integração da instância com o Chatwoot/MágicaChat também precisa estar ativa.

Mapa visual do fluxo

Use este mapa para explicar ao time o que precisa funcionar antes de liberar uma nova caixa:

Fluxo esperado:

Operador -> MágicaChat -> Evolution API -> WhatsApp
WhatsApp -> Evolution API -> MágicaChat -> Inbox correta

Matriz visual de aceite

Considere a caixa pronta apenas quando todos os blocos abaixo estiverem confirmados:

ROI operacional do checklist

Benefício para a operação

Seguir este checklist reduz retrabalho, evita paradas no atendimento e aumenta a previsibilidade da operação.

Com a caixa validada corretamente, sua equipe ganha:

• menos mensagens perdidas;

• menos tempo de diagnóstico;

• mais segurança ao criar novos canais;

• melhor rastreabilidade das conversas;

• mais confiança para escalar atendimento, suporte, comercial, qualidade ou pós-venda;

• maior ROI sobre a infraestrutura já contratada.

Quando usar este guia

Use este procedimento sempre que sua empresa for:

• criar uma nova caixa de entrada WhatsApp;

• conectar um novo número via WhatsApp Web API/Evolution;

• trocar o nome de uma inbox;

• migrar uma caixa para outro fluxo;

• validar uma instância que aparece como conectada, mas não funciona no MágicaChat;

• revisar uma operação self-hosted ou SaaS com múltiplos números.

Checklist rápido

Antes de liberar a caixa para uso real, confirme:

• a caixa existe no MágicaChat/Chatwoot;

• o WhatsApp foi conectado na Evolution;

• a instância está com estado open;

• a integração Chatwoot da instância está ativa;

• o nome da inbox está correto;

• o envio de mensagem funciona;

• o recebimento de resposta funciona;

• a conversa aparece na inbox correta;

• automações ou agentes de IA, se existirem, responderam no fluxo certo.

Passo 1: criar a caixa de entrada

No MágicaChat/Chatwoot:

1. Acesse as configurações da conta.

2. Crie uma nova caixa de entrada.

3. Use um nome claro, por exemplo:

   • Comercial

   • Suporte

   • Qualidade

   • Admissão

   • Financeiro

4. Confirme quais usuários ou times terão acesso à caixa.

Recomendação: use o mesmo nome da caixa no Chatwoot e na Evolution. Isso reduz erro operacional.

Passo 2: conectar o WhatsApp na Evolution

No gerenciador da Evolution:

1. Crie ou selecione a instância do WhatsApp.

2. Escaneie o QR Code com o celular responsável pelo número.

3. Aguarde o status da instância ficar open.

Importante: o status open significa que o WhatsApp está conectado. Ele não garante sozinho que o Chatwoot/MágicaChat está recebendo as mensagens.

Passo 3: ativar a integração com o Chatwoot/MágicaChat

Depois que o WhatsApp estiver conectado, confirme se a integração Chatwoot da instância está ativa.

O ponto mais importante é:

Chatwoot integration: enabled=true

Se essa integração estiver desativada, a instância pode parecer conectada no WhatsApp, mas a caixa não funcionará corretamente no MágicaChat.

Campos que normalmente precisam estar corretos:

• conta correta;

• URL correta do MágicaChat/Chatwoot;

• nome correto da inbox;

• token/API interna configurada pelo suporte;

• importação de contatos, quando aplicável;

• importação de mensagens, quando aplicável;

• regra de reabertura de conversa, quando aplicável.

Por segurança, tokens, chaves de API e senhas nunca devem ser enviados por chat, print ou e-mail.

Passo 4: validar envio e recebimento

Faça um teste simples antes de liberar a caixa:

1. Envie uma mensagem do MágicaChat para um número de teste autorizado.

2. Confirme que a mensagem chegou no WhatsApp.

3. Responda pelo WhatsApp com uma mensagem curta, por exemplo: ok.

4. Confirme que a resposta entrou na inbox correta.

5. Verifique se a conversa ficou aberta, pendente ou atribuída conforme a regra da operação.

6. Se houver automação ou IA, confirme se ela respondeu no fluxo correto.

Esse teste valida o caminho completo:

MágicaChat -> Evolution -> WhatsApp -> Evolution -> MágicaChat

Sinais de problema

A instância aparece como open, mas a caixa não recebe mensagem

Provável causa:

• a integração Chatwoot da instância não está ativa;

• a inbox configurada não corresponde à caixa correta;

• o token interno está incorreto ou expirado;

• a URL do Chatwoot/MágicaChat está incorreta;

• a instância foi criada, mas não foi vinculada à caixa.

A mensagem sai pela Evolution, mas não aparece no Chatwoot

Provável causa:

• a conexão WhatsApp está funcionando;

• a ponte com o MágicaChat não está ativa;

• a caixa foi criada, mas a integração não foi finalizada.

Uma chave de API mostra apenas algumas instâncias

Provável causa:

• a chave usada tem escopo limitado;

• a chave não é a global correta;

• a consulta está usando credencial de instância.

Nesse caso, acione o suporte. Não compartilhe a chave em canais abertos.

Padrão de aceite para uma nova caixa

Considere a caixa entregue apenas quando todos os itens abaixo estiverem confirmados:

• WhatsApp conectado.

• Instância com estado open.

• Integração Chatwoot/MágicaChat ativa.

• Inbox correta localizada.

• Mensagem enviada com sucesso.

• Resposta recebida na inbox correta.

• Automação ou IA validada, se existir.

• Operador confirmou o teste.

Boas práticas

• Dê nomes claros às caixas.

• Evite criar caixas duplicadas para o mesmo número.

• Teste sempre com número autorizado.

• Não use número de cliente final para teste técnico sem permissão.

• Não compartilhe tokens, API keys ou senhas.

• Documente qual número pertence a qual caixa.

• Faça um teste de envio e recebimento sempre que criar ou alterar uma instância.

• Em operações críticas, peça ao suporte para validar antes de liberar ao time.

Quando chamar o suporte

Acione o suporte da Conexão Azul se:

• a instância está open, mas a inbox não recebe;

• mensagens chegam no WhatsApp, mas não aparecem no MágicaChat;

• o envio funciona em uma caixa, mas não em outra;

• uma nova caixa precisa ser vinculada à Evolution;

• existem múltiplas instâncias e você não sabe qual chave/API usar;

• a operação usa automações, IA, filas ou Kanban e precisa de validação ponta a ponta.

Resumo

Para uma nova caixa WhatsApp funcionar corretamente no MágicaChat, não basta conectar o número na Evolution.

Você precisa validar três camadas:

1. WhatsApp conectado.

2. Integração Chatwoot/MágicaChat ativa.

3. Envio e recebimento testados na inbox correta.

Esse processo simples evita falhas de atendimento, reduz retrabalho e ajuda sua operação a crescer com mais segurança.