Pular para o conteúdo principal

​
Introdução

Em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp Web. Quando isso ocorre, você verá um destes dois sinais: No navegador — a tela de verificação de segurança com chave de acesso:
No celular — uma notificação pedindo confirmação da nova conexão:
Esse comportamento não ocorre em todos os dispositivos — apenas naqueles em que o WhatsApp exige a validação pelo celular para autorizar uma nova conexão ao WhatsApp Web.
Se você se deparar com qualquer uma dessas telas ao tentar conectar sua instância Z-API, utilize a extensão Z-API Conector para o Google Chrome. Por meio dela, é possível autenticar a conexão de forma segura, sem precisar escanear um QR Code.

​
Como funciona

O fluxo de conexão via extensão envolve três etapas principais:
  1. Instalar a extensão Z-API Conector no Chrome
  2. Obter o token de extensão — via painel ou via API
  3. Inserir o token na extensão para autenticar a instância

​
Passo 1 — Instalar a extensão

Acesse a Chrome Web Store e instale a extensão Z-API Conector. Após instalar, o ícone da extensão aparecerá na barra de ferramentas do Chrome.

​
Passo 2 — Obter o token de extensão

O token pode ser obtido de duas formas:

​
Opção A — Via painel Z-API

Quando a instância está desconectada, o painel exibe o banner:
“Problemas com chave de acesso? Clique aqui e conecte via extensão da Z-API, sem precisar de QR Code.”
Clique em “Clique aqui” — o painel irá exibir a tela “Conectar via extensão” com o Código de Conexão gerado:
Após clicar, a tela será atualizada exibindo o código a ser inserido na extensão:
O próprio painel já orienta os próximos passos:
  1. Baixe a extensão Z-API Conector
  2. Abra o WhatsApp Web e clique na extensão
  3. Digite o código exibido na extensão

​
Opção B — Via API

Faça uma requisição ao endpoint de geração de token: 
curl --location 'https://api.z-api.io/instances/{instanceId}/token/{token}/extension-token' \
--header 'Client-Token: SEU_CLIENT_TOKEN'
A resposta será: 
{
  "token": "FA48-HS63",
  "expiresAt": 1782851138085
}
​
token
string
Código de acesso a ser inserido na extensão
​
expiresAt
number
Timestamp Unix (em milissegundos) com a data de expiração do token
O token possui validade limitada. Utilize-o antes que expire. Após a expiração, gere um novo token e repita o processo.
Documentação completa do endpoint: Gerar token para extensão

​
Passo 3 — Inserir o código na extensão

  1. Acesse web.whatsapp.com no Chrome, estando logado com o número que deseja conectar à instância Z-API
  2. Clique no ícone da extensão Z-API Conector na barra do Chrome
  3. A extensão irá detectar automaticamente o número logado e exibir os campos para o código de conexão
  4. Digite o código obtido no painel ou via API (formato: XXXX-XXXX) e clique em Continuar
A extensão irá validar o código e avançar para a tela de confirmação.

​
Passo 4 — Confirmar e conectar na Z-API

Após digitar o código, a extensão exibirá uma tela de confirmação com:
  • O nome da instância que será conectada
  • O número detectado no WhatsApp Web
  • Um contador regressivo com o tempo restante de validade do token
Clique em “Conectar na Z-API”. A sessão ativa do WhatsApp Web será encerrada e o número passará a estar conectado à instância Z-API.

​
Considerações Finais

Essa nova autenticação foi desenvolvida para se adequar à exigência de autenticação via chave de acesso imposta pelo WhatsApp. A extensão Z-API Conector garante que esse processo seja feito de forma segura e integrada à sua instância, sem expor credenciais sensíveis. O token de extensão tem validade de até 5 minutos. Após esse período, é necessário gerar um novo.