WhatsApp (QR Code)

O WhatsApp QR Code conecta uma caixa de entrada a uma sessão do WhatsApp lida pelo celular. Ele é útil para uma demonstração curta ou para validar um agente antes de configurar a API oficial. A conexão pertence à organização e só cria a caixa depois que o pareamento termina.

Escolha entre as cinco conexões de WhatsApp

Na lista de canais, o SquadOS oferece cinco provedores:

WhatsApp, com a descrição Conecte seu WhatsApp com QR Code (somente para testes): é o fluxo deste guia;
WhatsApp Oficial: integração da Meta para produção, com janela de atendimento e templates;
WhatsApp Z-API, WhatsApp UAZAPI e WhatsApp Evolution: conexões por credenciais de uma conta existente nesses provedores.

Não confunda a opção WhatsApp da lista com WhatsApp Oficial. Ao abrir a primeira, o painel de conexão passa a se chamar WhatsApp QR Code.

Antes de conectar

Use um número reservado para testes e mantenha acesso ao celular que controla a conta. A mesma identidade de WhatsApp não pode ficar ativa em duas caixas da organização: uma nova conexão assume o número e remove a caixa anterior. Se o número estiver ativo em outra organização, o SquadOS bloqueia o pareamento e pede que ele seja desconectado lá primeiro.

Para abrir o fluxo, você precisa conseguir criar caixas de entrada e alterar agentes. A caixa pode ter um agente de IA ativo como destino ou ficar em Atendimento humano.

Conectar por QR Code

Abra Caixas de entrada no menu lateral.
Selecione Conectar caixa de entrada.
Em Escolha o canal, abra o grupo WhatsApp e selecione WhatsApp — a opção cuja descrição termina em somente para testes.
No painel WhatsApp QR Code, espere o código aparecer. O contador Expira em começa em dois minutos.
No aplicativo WhatsApp do celular, abra a área de aparelhos conectados e use a opção de vincular um aparelho para ler o código. O nome e a posição dessa opção podem variar conforme a versão do aplicativo.
Mantenha a tela do SquadOS aberta até aparecer a confirmação da conexão. Se o tempo acabar, selecione Atualizar QR e leia o novo código; Cancelar abandona aquela tentativa.
Em Quem atende esta caixa?, escolha Atendimento humano ou um agente de IA ativo.
Em Destino, revise a escolha, preencha Nome da caixa e selecione Concluir.

Pedir um QR e sair antes do pareamento não cria uma caixa vazia. Depois da leitura bem-sucedida, a caixa aparece em Caixas de entrada com o número identificado.

O que acontece com uma mensagem

O webhook do Wuzapi transforma cada mensagem privada aceita em uma conversa da caixa. O contato é identificado pelo telefone e a conversa recebe um título com o nome exibido ou o número. Mensagens enviadas pelo próprio número e mensagens de grupos são ignoradas para evitar loop e misturar participantes.

O canal recebe:

texto comum e texto estendido;
imagem, inclusive sua legenda;
áudio e mensagem de voz;
documento, inclusive sua legenda.

Vídeo, sticker e eventos que não sejam uma nova mensagem não entram no pipeline. Se o provedor entregar um identificador interno sem o telefone alternativo, o evento também é ignorado porque o SquadOS não consegue identificar o contato com segurança.

Com um agente como destino, a mensagem segue o pipeline normal do agente. Com Atendimento humano, ela entra na fila de Conversas sem resposta automática; um operador pode assumir e responder por lá. Se o agente estiver inativo, a entrada pode ser registrada sem resposta automática: escolha apenas agentes ativos.

Respostas e envio proativo

Respostas do agente, mensagens de operador e a ação Enviar mensagem de uma automação usam a própria sessão não oficial. Este canal não usa templates da Meta nem aplica a janela de 24 horas da API Oficial. Portanto, o envio proativo é tecnicamente possível, mas isso não o torna seguro para produção: volume, spam ou mudanças do WhatsApp continuam sujeitos a instabilidade e bloqueio.

O agente envia texto e pode enviar uma imagem gerada. Operadores e automações enviam texto pela mesma caixa. Confirme na conversa se a mensagem ficou marcada como entregue; falha do provedor pode deixar a tentativa registrada com erro de entrega.

Estado e desconexão

Ao abrir a configuração de uma caixa conectada, o SquadOS consulta o estado da sessão. Essa consulta não é monitoramento contínuo: o resultado fica em cache por cinco minutos e a tela não atualiza ao receber foco. Uma indisponibilidade transitória do Wuzapi também pode aparecer como Desconectada, embora a sessão real ainda exista. Antes de gerar outro QR, feche e abra novamente a configuração e confirme o estado do número no celular.

Para encerrar voluntariamente a conexão, abra a caixa, use Desconectar no cartão WhatsApp QR Code e confirme. O SquadOS tenta encerrar a sessão no Wuzapi e remove a caixa da lista: sem conversas, a remoção é definitiva; com histórico, a caixa fica arquivada internamente para preservar a origem das conversas. Para revogar a sessão fora do SquadOS, remova também o aparelho vinculado no aplicativo WhatsApp.

Se a sessão se perder sozinha, a caixa pode ser desativada em vez de removida e a organização recebe o motivo de desconexão. Reconectar exige gerar e ler um novo QR Code.

Diagnóstico rápido

O QR não aparece: aguarde a tentativa de geração. Se o painel mostrar erro, selecione Tentar Novamente; uma indisponibilidade ou versão incompatível do Wuzapi pode impedir a geração.
O QR expirou: selecione Atualizar QR e leia o código novo dentro dos dois minutos.
A caixa aparece desconectada: reabra a configuração e confira os aparelhos conectados no celular antes de substituir a sessão; uma falha transitória da consulta também produz esse estado.
A mensagem não aparece: confirme que é uma conversa privada e um formato aceito. Grupo, vídeo, sticker e eventos sem telefone identificável são ignorados.
A mensagem aparece, mas não há resposta: confirme que o destino é um agente ativo. Em destino humano, a resposta deve ser enviada por um operador em Conversas.
A resposta não chega ao WhatsApp: confira o estado de entrega na conversa, a conexão da caixa e os créditos da organização. Depois de uma falha do provedor, evite repetir em massa até confirmar se a primeira tentativa foi entregue.

Limites que não mudam

não há SLA, certificação ou suporte da Meta para esta conexão;
a sessão pode parar depois de uma alteração do protocolo;
usar texto livre fora da janela da Meta é uma capacidade do provedor não oficial, não uma garantia de conformidade;
o canal não recebe grupos, vídeos nem stickers;
para uma operação estável, migre para o WhatsApp Oficial.