Z-API do zero: conta, instância, QR Code e campanhas pelo WhatsApp

Para que serve no AFK

• Campanhas pelo WhatsApp. Em Campanhas, você escolhe um grupo do CRM, escreve a mensagem e aprova. O AFK manda pela Z-API, uma mensagem por vez, e cada envio aparece na ficha do contato.
• Automação do funil. Uma campanha automática manda a mensagem para quem entra no filtro, por exemplo "sem contato há 30 dias". Ela sai sozinha ou fica pronta no Hoje para você mandar, como você escolher.
• Nome do contato na mensagem. A mensagem é personalizada com os dados do CRM antes de sair.

O que o AFK não faz com a Z-API, hoje:

• Não recebe as mensagens. A resposta do cliente chega no seu celular, e você responde por lá.
• Não liga as Respostas automáticas nem o Atendente IA. Para isso, use a Evolution (WhatsApp por QR com a Evolution: servidor, QR Code e robô 24 horas), o WhatsApp direto do painel ou a API oficial (WhatsApp: API oficial da Meta ou QR Code).
• Não lê o SAIR que o cliente escreve. Quem pedir para sair, você tira à mão (veja No dia a dia).
• Não manda com o computador desligado. A campanha pela Z-API sai do painel, no seu computador, com o painel aberto. Fechou o painel, a fila espera e continua de onde parou.

A comparação entre a API oficial e o QR Code está em WhatsApp: API oficial da Meta ou QR Code. Aqui fica só o que é da Z-API.

Antes: grátis ou pago

Preço na página oficial da Z-API, conferido em 30/10/2026:

O AFK não cobra nada a mais. Confira o preço atual em z-api.io.

O risco, sem esconder:

O que o AFK faz para reduzir o risco (vem ligado, em ferramentas/campanhas/canais.py):

• No máximo 40 mensagens por dia no WhatsApp não oficial, somando todas as campanhas.
• Uma mensagem por vez, com intervalo aleatório de 35 a 95 segundos entre elas.
• Só de segunda a sábado, das 8h às 20h, pelo relógio do seu computador.
• Quem está na etapa Perdido do CRM nunca recebe.
• Nada sai sem você aprovar na tela, com o número de pessoas à vista.
• O aviso na tela: use só com quem já é seu contato. Número novo ou lista fria é risco alto de bloqueio.

Parte 1: conta e segurança

1. Abra app.z-api.io e crie a sua conta com um e-mail do negócio, por exemplo contato@minhaempresa.com.br.
2. No painel da Z-API, abra a aba Segurança e ligue a autenticação de dois fatores. Ela protege a conta que guarda a conexão com o seu WhatsApp.
3. Separe o número. Use um chip secundário, com o WhatsApp (ou WhatsApp Business) instalado num celular que fica com você.

Parte 2: criar a instância e ler o QR Code

Uma "instância" é uma conexão de um número de WhatsApp. Cada número é uma instância, e cada instância é cobrada à parte.

1. No painel da Z-API, crie uma instância. Dê um nome fácil, por exemplo Minha Empresa.
2. Abra a instância. A Z-API mostra um QR Code.
3. No celular do número secundário, abra o WhatsApp:
   • Android: toque nos três pontos → Dispositivos conectados → Conectar dispositivo.
   • iPhone: em Configurações, toque em Dispositivos conectados → Conectar dispositivo.
4. Confirme com a digital ou o PIN e aponte a câmera para o QR Code. Ele vence em cerca de 20 segundos. Se vencer, a Z-API mostra outro.
5. A instância aparece como conectada.

Mantenha o celular ativo. O WhatsApp desconecta os dispositivos conectados se você não abrir o WhatsApp no celular principal a cada 14 dias.

Parte 3: copiar os três valores

1. Na instância, copie o ID da instância e o token da instância. Os dois ficam em Instâncias, na tela da instância.
2. Abra a aba Segurança → Token de Segurança da Conta → Configurar Agora. A Z-API gera o token. Copie.
3. Não clique em Ativar Token ainda. Primeiro cole no AFK (Parte 4).

Parte 4: colar no AFK

1. No painel do AFK, abra Conexões, clique no cartão WhatsApp — Z-API, cole em ID da instância, Token da instância e Token de segurança da conta e clique em Salvar conexão. Este cartão não tem o botão Testar.
2. Volte na Z-API, aba Segurança, e clique em Ativar Token. A partir daí, a Z-API só aceita pedidos com esse token. O AFK já manda.
3. Faça um teste pequeno: em Campanhas, crie uma campanha com um contato só, o seu outro celular, e aprove. A mensagem sai no próximo horário permitido.

Onde os tokens ficam. Só no arquivo .env da pasta do AFK, no seu computador. Eles não vão para a nuvem do AFK e não aparecem na conversa. Quem tem o ID e o token da instância manda mensagem pelo seu número. Nunca cole em chat, print ou WhatsApp.

No dia a dia

Se um token vazar: na Z-API, gere um token novo da instância e um token de segurança novo, cole no AFK e confira as mensagens enviadas no celular. Se apareceu mensagem que você não mandou, desconecte o número em Dispositivos conectados.

Erros e soluções

Se nada funcionar

Veja Travou ou quero sugerir uma melhoria: o que mandar. Mande o texto do erro. Nunca mande a chave.

Fontes oficiais (conferido em 30/10/2026): z-api.io (plano Ultimate R$ 99,99 por instância; anual R$ 1.079,89; Partner R$ 89,99 a partir de 10 instâncias; teste de 2 dias sem cartão) · developer.z-api.io/security/client-token (aba Segurança → Token de Segurança da Conta → Configurar Agora → Ativar Token; cabeçalho Client-Token; erro null not allowed) · developer.z-api.io/tips/blockednumbernew (causas de banimento; shadowban; recomendação de esperar) · developer.z-api.io/quickstart/introduction (sessão do WhatsApp Web; não é para spam) · developer.z-api.io/en/instance/qrcode (o QR Code vence a cada 20 segundos; ID da instância em Instâncias) · faq.whatsapp.com/1317564962315842 (Dispositivos conectados → Conectar dispositivo; até 4 dispositivos; abrir o celular principal a cada 14 dias) · whatsapp.com/legal/terms-of-service (proíbe mensagem automática e em massa e acesso automatizado; suspensão ou desativação da conta).