WhatsApp via Uazapi

A integração WhatsApp (UAZAPI) conecta uma instância Uazapi que você já administra a uma caixa de entrada do SquadOS. A sessão e o QR code permanecem no painel da Uazapi; o SquadOS valida a instância, recebe mensagens pelo webhook e envia respostas pela API do provedor.

Antes de começar

Você precisa de:

permissão para criar caixas de entrada;
uma instância Uazapi à qual você tenha acesso;
a URL base absoluta e confiável da instância, começando com https:// ou http://;
o Token da instância.

Uma barra no fim da URL é aceita e removida durante a validação. Use somente o endereço da instância que você administra: o backend do SquadOS acessa essa URL para validar, consultar o estado e enviar mensagens.

Conectar a caixa

No Admin, abra Caixas de entrada.
Clique em Conectar caixa.
No grupo WhatsApp, escolha WhatsApp (UAZAPI), descrito como Use a sua conta na UAZAPI.
No painel Conectar Uazapi, preencha:
- URL base — por exemplo, https://free.uazapi.com;
- Token da instância — o segredo da instância no provedor.
Clique em Validar e continuar. A validação consulta GET /instance/status. Um resultado válido confirma que o endereço respondeu e aceitou o token; ainda não comprova que o WhatsApp está conectado nem que o webhook entrega mensagens.
Copie a URL de webhook exibida pelo SquadOS.
No painel Uazapi da instância, abra a configuração de webhooks e aplique exatamente estas opções:
1. cole a URL no campo de URL e mantenha o método POST;
2. deixe addUrlEvents e addUrlTypesMessages desligadas;
3. em Escutar eventos, selecione somente 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 no próprio painel Uazapi.
Volte ao SquadOS e clique em Já configurei o webhook.
Use Verificar novamente até a Uazapi informar o estado connected. A caixa ainda não é criada enquanto essa verificação não for bem-sucedida.
Clique em Continuar e escolha um destino:
- um agente ativo, para atendimento por IA; ou
- Atendimento humano, para começar sem agente.
Dê um nome à caixa e conclua o wizard.

O SquadOS tenta identificar o número pelo campo owner devolvido pela Uazapi. A mesma identidade externa não pode pertencer a duas caixas ao mesmo tempo.

Por que o webhook exige essas opções

O parser recebe somente JSON e processa eventos cujo tipo representa mensagem. Outros eventos são confirmados e ignorados.
Desligar addUrlEvents e addUrlTypesMessages evita sufixos na URL. O endpoint do SquadOS exige o caminho exato fornecido no wizard; qualquer trecho adicional impede a identificação da caixa.
wasSentByApi evita enviar ao webhook as mensagens originadas pela própria API. O SquadOS também ignora mensagens marcadas como fromMe.
isGroupYes evita tráfego de grupos. Mesmo que o provedor o entregue, o SquadOS não cria conversa para mensagens identificadas como grupo.

Não altere a URL copiada nem acrescente eventos ou segmentos ao caminho. O filtro no provedor reduz tráfego desnecessário, mas não substitui as guardas aplicadas pelo SquadOS.

O que entra e sai

Mensagens recebidas

O SquadOS aceita o envelope atual da Uazapi (EventType: "messages") e um formato legado compatível. Ele obtém o destinatário de resposta pelo chatid, ignora remetente próprio e grupos e reconhece texto comum, texto estendido e legenda de imagem.

Cada contato individual é associado à caixa e sua conversa. Se o destino for um agente ativo, a mensagem entra no pipeline desse agente. Em Atendimento humano, ela fica disponível para a equipe nas Conversas, sem resposta automática de IA.

Mensagens enviadas

Texto é enviado por POST /send/text.
Uma imagem gerada pelo agente pode ser enviada por POST /send/media com o tipo image.
O adapter não envia indicador de digitação.
Áudio e documento não têm envio nativo por esta integração no contrato atual.

Mensagens do agente, do operador e de uma Automação usam a conversa e a caixa já existentes. Esta integração não aplica a janela de 24 horas nem os modelos da Cloud API; políticas e limites do provedor continuam sendo responsabilidade de quem administra a instância.

Ver estado e editar credenciais

Abra os detalhes da caixa para consultar o estado ou alterar URL base e Token da instância. Ao salvar credenciais novas, o SquadOS as valida antes de substituir as anteriores. A URL de webhook pertence à caixa, não ao agente de destino; trocar o destino não exige criar outro webhook.

Uma consulta de estado malsucedida não prova que a sessão caiu. Hoje, porém, uma resposta HTTP inválida do provedor é tratada como connected: false e pode desativar uma caixa ativa. Antes de refazer a conexão, confirme a sessão e a disponibilidade diretamente no painel Uazapi.

Desconectar

Ao desconectar pelo SquadOS, o produto solicita POST /instance/disconnect e remove a caixa local. Conversas históricas continuam registradas, mas a caixa e suas credenciais deixam de existir.

Diagnóstico

A validação não avança

Confirme que a URL é absoluta e usa http:// ou https://. A barra final não é um problema.
Confirme o token da mesma instância.
Abra o painel Uazapi e verifique se o serviço está disponível. Erros de rede ou HTTP 5xx aparecem como indisponibilidade do provedor; outras respostas não bem-sucedidas aparecem como credenciais inválidas.

A caixa não é criada

A caixa nasce somente depois de a Uazapi responder connected. Escaneie o QR no painel do provedor, volte ao SquadOS e use Verificar novamente.

A caixa aparece conectada, mas não recebe mensagens

O estado consulta a instância; não testa a entrega do webhook. Revise as seis opções do webhook, mantenha o caminho exatamente como foi copiado e envie uma mensagem de texto de um número individual. Não use mídia como primeiro teste.

Mensagens próprias ou de grupos chegam ao endpoint

Confirme wasSentByApi e isGroupYes em Excluir dos eventos escutados. O SquadOS também descarta esses eventos, mas o filtro correto evita chamadas desnecessárias.