Como conectar o WhatsApp (Z-API) para avisar os vendedores

A integração de WhatsApp manda um aviso no WhatsApp do vendedor sempre que ele recebe um lead novo. A mensagem traz o nome, o telefone e o e-mail do lead e pede para ele abrir o CRM e iniciar o atendimento.

O envio usa a Z-API, um serviço que conecta um número de WhatsApp a sistemas. A conta da Z-API é da sua instituição: o CRM usa as credenciais que você informa.

Esta integração serve só para os avisos aos vendedores. O WhatsApp do SDR de Vendas IA é configurado em outro lugar, com outro número (veja Como conectar o WhatsApp do SDR).

Antes de começar

• Uma conta na Z-API (https://z-api.io) com uma instância criada e conectada ao número de WhatsApp que vai enviar os avisos (QR code lido no celular).
• No painel da Z-API, anote:
  • o ID da instância e o Token da instância (na página da instância);
  • o Client-Token da conta (em Segurança da conta).
• Cada vendedor precisa ter o WhatsApp preenchido no cadastro de usuário.

Quem pode fazer

Só o Administrador do CRM. A tela de Integrações não aparece para os outros perfis.

Passo a passo

1. Acesse Configurações → Integrações e abra a aba WhatsApp.
2. Preencha os campos:
   • Instance ID: o ID da instância da Z-API;
   • Instance Token: o token da instância;
   • Client Token: o token de segurança da conta;
   • URL da API: pode deixar em branco ou usar https://api.z-api.io. Não use o endereço do painel (app.z-api.io): se usar, a tela mostra um aviso;
   • Telefone remetente: o número conectado na instância, para sua referência;
   • Webhook URL: o CRM já sugere o endereço. Deixe como está.
3. Marque Ativar integração Z-API para esta empresa.
4. Clique em Salvar credenciais. A mensagem "Configuração da Z-API salva com sucesso." confirma.
5. Em Testar envio, digite um Número de destino com DDD (por exemplo, o seu celular) e, se quiser, uma Mensagem (opcional).
6. Clique em Enviar mensagem de teste.

Cada vendedor também precisa ligar o aviso

O aviso é enviado só para quem está com a Notificação por WhatsApp ativada. O vendedor acessa o próprio Perfil (clicando no avatar, no canto superior direito) e, no quadro Notificação por WhatsApp, clica em Ativar.

Como conferir se funcionou

• Depois do teste, a tela mostra "Mensagem enviada para..." e a mensagem chega ao número informado.
• A linha Última validação mostra o resultado do último teste.
• Para um teste completo, cadastre um lead de teste para um vendedor que tenha o WhatsApp no cadastro e a notificação ativada. O aviso "Novo lead recebido!" deve chegar ao WhatsApp dele.

Problemas comuns

O que aparece	Causa provável	Como resolver
Falha no envio (HTTP 404): "Instância não encontrada"	Instance ID ou Instance Token errado	Copie de novo os dois do painel da Z-API e salve
Falha no envio (HTTP 401 ou 403): "Credenciais recusadas"	Client Token errado ou desatualizado	Confira o token em Segurança da conta na Z-API
Falha no envio (HTTP 400): "A Z-API recusou o envio"	Instância desconectada do WhatsApp ou número de destino inválido	No painel da Z-API, veja se a instância está conectada. Se não estiver, leia o QR code de novo
"Salve as credenciais da Z-API antes de testar."	O teste foi feito antes de salvar	Clique em Salvar credenciais e teste de novo
O teste funciona, mas os vendedores não recebem os avisos	A caixa Ativar integração está desmarcada, o vendedor não ativou a notificação no perfil ou não tem WhatsApp no cadastro	Confira os três pontos. O teste avisa quando a integração está desativada
Aviso de que a URL é "o endereço do painel da Z-API"	O campo URL da API está com app.z-api.io	Apague o campo ou use https://api.z-api.io

Dúvidas comuns

Os leads importados por planilha também geram aviso no WhatsApp? Não. O aviso é só para leads novos que chegam pelos formulários e pelo cadastro. Leads importados não disparam a notificação.

Posso usar o mesmo número no WhatsApp das notificações e no SDR de Vendas IA? Não é recomendado. O SDR conversa com os alunos e precisa de um número dedicado, com uma instância própria na Z-API.

Preciso apagar os tokens para trocar só a URL? Não. Os campos de token ficam preenchidos (escondidos) depois de salvos. Altere só o campo que precisa mudar e clique em Salvar credenciais. Não apague os tokens: um campo vazio é salvo vazio.

O vendedor ativou a notificação, mas não recebe nada. O que confiro? Veja se o WhatsApp dele está preenchido no cadastro de usuário, se a integração está ativa e se a instância da Z-API continua conectada. Faça um Testar envio para o número dele.