Conectar o WhatsApp pela Z-API
Passo a passo pra criar a conta na Z-API, parear o seu número e conectar na OctoSolve.
A Z-API é uma alternativa não oficial pra conectar o WhatsApp. A conta é sua: você contrata, cria a instância e pareia o número no painel deles. A OctoSolve só aponta pra essa instância, a gente nunca guarda a sua sessão.
Antes de seguir, entenda o risco: provedores não oficiais podem levar ao banimento do seu número pelo WhatsApp. A recomendação da casa continua sendo a API oficial (Meta), que é estável e sem esse risco. Se for usar mesmo assim, prefira um número novo, dedicado, e faça um aquecimento manual antes (use como pessoa normal por alguns dias) antes de ligar o agente.
Antes de começar
- A Z-API é paga, na faixa de R$100 por mês por número. Ela costuma oferecer alguns dias de teste grátis.
- Você vai precisar do celular com o número em mãos pra ler o QR Code.
- 1 instância = 1 número de WhatsApp.
Parte 1: na Z-API
1. Crie a conta e a instância
Acesse z-api.io, crie sua conta e entre em Instâncias Web. Clique em + Adicionar pra criar a instância do seu número.
2. Abra a instância criada
Clique no nome da instância na lista. Você cai na tela Dados da instância web, que tem tudo o que a gente precisa.
3. Guarde o ID e o Token da instância
Nessa tela ficam as duas credenciais que você vai colar na OctoSolve:
- ID da instância
- Token da instância
Trate essas credenciais como senha: quem tiver elas consegue enviar mensagem pelo seu número. Não compartilhe em grupo, print ou e-mail.
4. Ative o Token de segurança da conta
Esse passo é obrigatório. Sem ele, a Z-API até recebe as mensagens, mas recusa todo envio, e o seu cliente não recebe nada.
No painel da Z-API, abra o menu Segurança. No item Token de segurança da conta, clique em Configurar agora pra ativar. A Z-API gera o token: copie e guarde junto com o ID e o Token da instância.
Esse token é o que a Z-API chama de Client-Token. Ele vale pra conta inteira, não por instância: se você tem mais de um número, é o mesmo token pra todos.
5. Pareie o seu número lendo o QR Code
No celular: WhatsApp → Aparelhos conectados → Conectar aparelho, e leia o QR que aparece na tela da Z-API. O QR expira rápido, então deixe o celular na mão antes de gerar.
6. Confirme que ficou Conectado
Assim que parear, o painel mostra Conectado. É esse estado que a OctoSolve espera.
Não precisa configurar webhook na Z-API. A OctoSolve configura isso sozinha quando você conectar, no passo seguinte.
Parte 2: na OctoSolve
7. Abra o cadastro de conexão
Vá em Configurações → Canais → Conectar canal → WhatsApp e abra Outras formas de conectar. Escolha o card Z-API.
8. Cole as credenciais
Preencha (todos são obrigatórios):
- Nome da conexão: um apelido pra você reconhecer depois
- ID da instância: o do passo 3
- Token da instância: o do passo 3
- Token de segurança (Client-Token): o do passo 4
9. Leia o aviso e finalize
Marque Entendi os riscos e clique em Finalizar. Como o número já está pareado lá, a conexão entra na hora, sem pedir QR aqui.
A conexão aparece na lista de canais com o selo Z-API, e o agente já começa a atender por ela.
Se der erro
| O que aparece | O que fazer |
|---|---|
| Instância Z-API não encontrada | O ID da instância está errado. Confira no painel da Z-API. |
| Token recusado | O Token da instância está errado. Confira no painel. |
| Menção a "null not allowed" | O Token de segurança está errado ou não foi ativado. Refaça o passo 4. |
| Conectou mas o agente não responde | Confira se a instância está Conectada no painel da Z-API. Se caiu, pareie o número de novo por lá. |
| O agente responde no painel, mas nada chega no WhatsApp do cliente | Falta o Token de segurança, ou ele está errado. É o caso de baixo. |
O agente responde no painel, mas o cliente não recebe (Token de segurança)
Esse é o caso mais traiçoeiro, porque parece que está tudo bem.
Sem o Token de segurança correto, a Z-API se comporta assim:
- a entrada continua funcionando: a mensagem do cliente chega e você vê a resposta do agente no painel da OctoSolve
- todo envio falha: a Z-API recusa com
your client-token is not configurede nenhuma mensagem chega no WhatsApp do cliente
Ou seja: a conexão continua marcada como conectada e o agente parece trabalhar, mas ninguém do outro lado recebe.
Hoje o campo é obrigatório pra conectar, então isso só acontece em dois casos: conexões antigas, criadas quando o campo ainda era opcional, ou um token que mudou no painel da Z-API.
Como resolver
- No painel da Z-API, abra o menu Segurança e copie o Token de segurança da conta. Se ele ainda não estiver ativado, clique em Configurar agora (passo 4 acima).
- Na OctoSolve, vá em Configurações → Canais, ache a conexão Z-API e clique em Credenciais
- Cole o Token de segurança e clique em Salvar credenciais
Pronto, o envio volta na hora. Não precisa excluir nem recriar a conexão.
Detalhes dessa tela:
- Campo em branco continua como está: você preenche só o que mudou. Pra trocar só o Token de segurança, não precisa redigitar o Token da instância.
- A gente testa antes de salvar: se a Z-API recusar a credencial nova, o erro aparece e a credencial antiga continua valendo. Você não fica pior do que estava.
- Não dá pra deixar a conexão sem Token de segurança: como a Z-API recusa o envio sem ele, salvar sem token nenhum só devolveria o agente pro estado mudo descrito aqui.
A mesma tela serve pra trocar o Token da instância quando você gera um novo no painel.
Desconectar
Pra parar de atender por esse número, use Desconectar no card da conexão em Canais. A gente invalida na hora o recebimento e o agente para de responder. A sua instância na Z-API continua intacta, a gente nunca mexe nela.