WhatsApp via Z-API

A Z-API é um provedor brasileiro que expõe o WhatsApp Web como uma API REST. Você mantém a instância no painel da Z-API (onde escaneia o QR code) e o SquadOS apenas envia e recebe mensagens via webhook. Use quando já tem (ou prefere usar) Z-API como gateway — paga direto para eles, sem precisar passar pela Cloud API da Meta.

API não-oficial

Z-API usa o protocolo do WhatsApp Web, que não é oficial. Não há SLA, o número pode ser banido se for usado para spam, e a sessão pode cair se o celular ficar offline. Para volume alto ou atendimento crítico, prefira o WhatsApp Oficial (Cloud API).

Quando usar

Use Z-API quando	Não use quando
Você já tem instâncias contratadas na Z-API	Vai abrir conta nova só para isso — a Cloud API costuma sair mais barata em volume
Precisa de envio rápido sem fila ou aprovação de templates	Precisa de SLA, métricas oficiais ou templates HSM aprovados pela Meta
Quer rodar testes ou MVP sem mexer com Business Manager	Atendimento crítico em que cair a sessão é inaceitável

Pré-requisitos

Antes de conectar:

• Conta ativa na Z-API com uma instância criada e conectada (QR code escaneado, status “Conectado” no painel da Z-API).
• As três credenciais da instância à mão:
  • Instance ID — identificador da instância (visível no painel).
  • Instance Token — token da instância.
  • Account Security Token — token de segurança da conta (também chamado de Client Token).

Você encontra os três valores no painel da Z-API, na tela da sua instância. O QR code é escaneado lá, não no SquadOS — o SquadOS só usa as credenciais para enviar e receber mensagens.

Passo a passo

1. Abra Admin → Agentes → [seu agente] → Gatilhos.

2. No card Z-API (dentro da seção WhatsApp QR Code), clique em Conectar.

3. Cole as três credenciais nos campos correspondentes:

   

4. Clique em Validar e continuar. O SquadOS chama o endpoint /status da Z-API para confirmar que as credenciais funcionam — se algum token estiver errado, o modal mostra o erro e nada é salvo.

5. O passo seguinte mostra uma URL de webhook gerada pelo SquadOS, exclusiva para esse agente. Copie a URL e, no painel da Z-API:

   • Vá em Webhooks → Ao receber mensagem.
   • Cole a URL no campo correspondente.
   • Salve.

6. De volta ao SquadOS, clique em Já configurei o webhook.

7. O SquadOS verifica a conexão consultando novamente /status na Z-API. Se a sua instância estiver conectada (QR já escaneado no painel deles), o card fica Conectado e o número aparece.

Se a verificação falhar com “A instância ainda não está conectada”, abra o painel da Z-API, confirme que sua instância mostra status Conectado (escaneie o QR lá se preciso) e clique em Verificar novamente no SquadOS.

Como funciona

• O SquadOS não hospeda sua sessão WhatsApp — ela vive inteiramente na Z-API.
• Mensagens recebidas pela Z-API são entregues no webhook do SquadOS, viram conversas, e o agente responde via POST /send-text na Z-API.
• O SquadOS não enxerga o QR code: quem mantém a sessão viva é a Z-API. Se o WhatsApp do celular cair, é no painel deles que você reconecta.

Editando credenciais depois

Se você precisar atualizar tokens (por exemplo, gerou um novo Account Security Token na Z-API), abra o card Z-API conectado, clique no botão de informações e edite os campos. O SquadOS revalida com a Z-API antes de salvar; se o conjunto novo não autenticar, mantém o anterior.

A URL de webhook não muda quando você atualiza credenciais — ela é fixa por agente.

Desconectando

No card Z-API conectado, clique em Desconectar. O SquadOS chama /disconnect na Z-API e marca o gatilho como inativo. A instância Z-API em si continua existindo — se quiser encerrar de fato a sessão WhatsApp, faça isso no painel deles.

Problemas comuns

• “Credenciais inválidas” no passo 1. Confira o Instance ID, Instance Token e Account Security Token — caracteres extras (espaços, quebras de linha coladas do clipboard) costumam ser o motivo. O SquadOS chama /status para validar; se a Z-API responder 401/403, esse erro aparece.
• Webhook configurado mas mensagens não chegam. No painel da Z-API, confira que o webhook está marcado em Ao receber mensagem (não em outro evento). Confira também se o status da instância é Conectado — sessão derrubada não entrega mensagens.
• Agente responde, mas o cliente não recebe. Pode ser que o número do cliente esteja bloqueado na Z-API ou que a Z-API tenha derrubado a sessão por uso anormal. Veja o histórico de envios no painel deles.
• Sessão cai sozinha. WhatsApp Web invalida sessões com frequência (celular sem internet, mudança de SIM, uso indevido detectado). Reconecte pelo painel da Z-API. Se acontece muito, considere migrar para o WhatsApp Oficial.