WhatsApp via Uazapi

A Uazapi é um provedor brasileiro que também expõe o WhatsApp via API REST, com modelo self-host ou hospedagem própria deles. O SquadOS se conecta à instância Uazapi pela URL base + token, e o QR code é escaneado no painel da Uazapi (não aqui).

API não-oficial

Igual à Z-API, a Uazapi roda sobre o protocolo do WhatsApp Web — sem SLA da Meta, risco de banimento se usado para spam, e a sessão pode cair sem aviso. Para produção em escala, considere o WhatsApp Oficial (Cloud API).

Quando usar

Use Uazapi quando	Não use quando
Você já hospeda Uazapi ou usa o serviço gerenciado deles	Está começando do zero e não tem preferência — avalie Z-API ou Cloud API
Precisa de mais flexibilidade no servidor (self-host)	Não tem time para manter o servidor de pé
Tem volume médio com tolerância a quedas pontuais	Atendimento crítico onde indisponibilidade vira incidente

Pré-requisitos

Antes de conectar:

• Instância Uazapi rodando, seja no serviço deles (ex.: https://free.uazapi.com) ou self-host.
• URL base da sua instância (sem barra no final): https://free.uazapi.com, https://uazapi.seudominio.com, etc.
• Token da instância — gerado no painel Uazapi.

O QR code do WhatsApp é escaneado no painel da Uazapi, não no SquadOS. O SquadOS apenas consulta o status da instância e envia/recebe mensagens.

Passo a passo

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

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

3. Preencha:

   

   • URL base — a base da sua instância (ex.: https://free.uazapi.com).
   • Token da instância — token gerado no painel.

4. Clique em Validar e continuar. O SquadOS chama GET /instance/status na sua Uazapi — se o token estiver errado, o modal mostra o erro.

5. O passo seguinte exibe a URL de webhook gerada pelo SquadOS e a sequência exata de configuração que o painel Uazapi exige. Copie a URL e, no painel Uazapi (botão Webhooks da instância):

   1. Cole a URL no campo URL do webhook e mantenha o método como POST.
   2. Deixe as opções addUrlEvents e addUrlTypesMessages desligadas.
   3. Em Escutar eventos, adicione apenas: messages.
   4. Em Excluir dos eventos escutados, adicione: wasSentByApi e isGroupYes.
   5. Marque Habilitado e clique em Salvar.
   6. Conecte o WhatsApp escaneando o QR code dentro do próprio painel Uazapi (não no SquadOS).

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

7. O SquadOS chama /instance/status para verificar. Se a Uazapi reportar status connected, o card fica Conectado e o número aparece (extraído do campo owner que a Uazapi devolve).

Se a verificação falhar, abra o painel Uazapi, confirme que o status é connected (e que você escaneou o QR lá) e clique em Verificar novamente.

Por que esses filtros específicos no webhook?

A configuração do passo 5 não é decoração — é o que faz a integração funcionar:

• messages é o único evento que o SquadOS parseia. Outros eventos seriam respondidos com OK - other event (ignorados), mas chegariam ao webhook e gerariam ruído inútil.
• wasSentByApi filtra as mensagens que o próprio agente acabou de enviar — sem isso, a resposta do agente voltaria pelo webhook e o agente responderia à própria resposta, em loop.
• isGroupYes filtra mensagens de grupos. O SquadOS não responde em grupos hoje; deixar passar gera processamento inútil.
• addUrlEvents e addUrlTypesMessages desligadas mantêm a URL do webhook estática (sem sufixos dinâmicos), que é o que o SquadOS espera para validar o webhook_secret.

Se as mensagens não estiverem chegando, revise primeiro essa configuração antes de qualquer outra coisa.

Como funciona

• O SquadOS não hospeda a sessão WhatsApp — ela vive na sua instância Uazapi.
• Mensagens entram via webhook, viram conversas no SquadOS, e o agente responde via POST /send/text na Uazapi.
• Mídia (imagens, áudios, documentos) é enviada via POST /send/media.

Editando credenciais depois

Se o token expirou ou você mudou a URL base, abra o card Uazapi conectado, clique em informações e edite. O SquadOS revalida com a Uazapi antes de salvar; se falhar, mantém o anterior.

A URL de webhook não muda — é fixa por agente.

Desconectando

No card Uazapi conectado, clique em Desconectar. O SquadOS chama POST /instance/disconnect na Uazapi e marca o gatilho como inativo. A instância em si continua existindo no painel Uazapi.

Problemas comuns

• “Credenciais inválidas” no passo 1. Confira a URL base (sem barra no final, com https://) e o token. Se a Uazapi responder 401/403, esse erro aparece.
• Webhook configurado mas mensagens não chegam. O culpado mais comum é a configuração de eventos do webhook. Volte ao painel Uazapi e confirme item por item o passo 5 acima — principalmente que apenas messages está marcado e que wasSentByApi está nos excluídos.
• Agente responde sua própria resposta em loop. Significa que wasSentByApi não está nos eventos excluídos. Ajuste no painel Uazapi.
• Mensagens de grupo chegando. isGroupYes não está nos excluídos. O SquadOS já filtra grupos do lado dele, mas excluir no webhook reduz tráfego inútil.
• Status fica em “disconnected” eternamente. Você precisa escanear o QR code no painel Uazapi — o SquadOS não exibe QR para esse provedor (a Uazapi gerencia a sessão lá).