WhatsApp via Z-API
A integração WhatsApp (Z-API) conecta ao SquadOS uma instância que você já mantém na Z-API. A sessão, o QR code e a conta do provedor ficam no painel da Z-API; o SquadOS valida as credenciais, recebe mensagens pelo webhook e envia respostas pela API do provedor.
Antes de começar
Section titled “Antes de começar”Você precisa de:
- permissão para criar ou editar caixas de entrada no SquadOS;
- uma conta Z-API com uma instância criada;
- o QR code dessa instância já escaneado no painel da Z-API;
- Instance ID;
- Instance Token;
- Account Security Token, também chamado de Client Token.
Os três nomes acima são os mesmos exibidos pelo formulário do SquadOS. Copie cada valor da mesma instância. O QR code não é escaneado no SquadOS.
Conectar a caixa
Section titled “Conectar a caixa”- No painel administrativo, abra Caixas de entrada.
- Selecione Conectar caixa de entrada.
- Na seção WhatsApp, escolha WhatsApp (Z-API). A descrição da opção é Use a sua conta na Z-API.
- No formulário Conectar Z-API, preencha Instance ID, Instance Token e Account Security Token.
- Selecione Validar e continuar. O SquadOS consulta o status da instância com as três credenciais. Se o provedor estiver indisponível ou recusar os dados, nenhuma caixa é criada; confira os valores e tente novamente.
- O SquadOS exibe uma URL exclusiva de webhook. Copie-a.
- No painel da Z-API, abra a configuração da instância e vá a Webhooks → Ao receber mensagem. Cole a URL no campo de webhook e salve.
- Volte ao SquadOS e selecione Já configurei o webhook. O sistema consulta a Z-API novamente.
- Se aparecer A instância ainda não está conectada, conecte o número pelo QR code no painel da Z-API e use Verificar novamente no SquadOS.
- Quando aparecer Conectado! Pronto pra usar., aguarde o diálogo retornar ao passo da caixa e selecione Continuar.
- Em Quem atende esta caixa?, escolha um agente ativo para respostas automáticas ou Atendimento humano para deixar as mensagens na fila dos operadores.
- Revise o Nome da caixa e selecione Concluir.
A caixa só é criada quando a verificação confirma a conexão. Fechar o assistente antes disso não deve deixar uma caixa incompleta na lista.
O que acontece com as mensagens
Section titled “O que acontece com as mensagens”- Mensagens individuais recebidas no webhook criam ou continuam uma conversa identificada pelo telefone do contato.
- Mensagens enviadas pelo próprio número e mensagens de grupo são ignoradas.
- Uma caixa com agente ativo entrega a entrada ao agente e envia a resposta pela Z-API.
- Uma caixa em Atendimento humano recebe a conversa sem chamar um agente; um operador responde pela tela de conversas.
- Texto é enviado pelo endpoint de texto da Z-API. Imagens geradas pelo agente podem usar o endpoint de imagem; se esse envio falhar, o produto tenta enviar um aviso textual.
- Este canal não usa a janela de 24 horas nem os modelos da API oficial da Meta. Automação e envio proativo ainda dependem de uma conversa e de um contato já associados à caixa.
Conferir e editar a conexão
Section titled “Conferir e editar a conexão”Na lista de caixas de entrada, abra a edição da caixa Z-API e entre na configuração do canal. O painel de informações mostra, quando disponíveis:
- o número conectado;
- a data da conexão;
- a URL atual do webhook, com ação para copiar;
- Instance ID, Instance Token e Account Security Token.
Ao salvar credenciais alteradas, o SquadOS primeiro combina os campos novos com a configuração existente e valida o conjunto na Z-API. Se a validação falhar, a configuração anterior continua gravada. A URL do webhook mantém o mesmo segredo da caixa; atualizar tokens não exige trocar essa URL no provedor.
Desconectar
Section titled “Desconectar”Use Desconectar na configuração da caixa. O SquadOS solicita a desconexão à Z-API e remove a caixa da lista. Se já houver conversas, elas continuam no histórico com a origem do canal, mas a credencial da caixa é removida.
Depois da ação, confira o status da instância no painel da Z-API. Hoje uma falha do endpoint remoto pode ser apenas registrada em log enquanto o SquadOS remove a caixa e informa sucesso. Se a instância ainda estiver conectada, encerre a sessão diretamente na Z-API antes de reutilizar ou abandonar o número.
Diagnóstico
Section titled “Diagnóstico”As credenciais não passam na validação
Section titled “As credenciais não passam na validação”Confirme que os três valores pertencem à mesma instância e que Account Security Token é o token de segurança da conta. Remova espaços ou quebras de linha copiados junto com os tokens. Se o erro disser que o provedor não está acessível, tente novamente antes de trocar credenciais que já funcionavam.
A conexão não é confirmada
Section titled “A conexão não é confirmada”Abra a instância no painel da Z-API e confirme que tanto a instância quanto o smartphone aparecem conectados. O SquadOS exige os dois estados. Depois use Verificar novamente.
Uma indisponibilidade HTTP da consulta também pode ser interpretada como desconexão e, em uma caixa ativa, desativá-la com o motivo de sessão perdida. Confirme o estado real na Z-API antes de criar outra conexão.
O webhook foi salvo, mas não chega mensagem
Section titled “O webhook foi salvo, mas não chega mensagem”Confirme que:
- a URL está em Webhooks → Ao receber mensagem da instância correta;
- a URL foi copiada por inteiro;
- a instância e o smartphone continuam conectados;
- o teste foi feito em conversa individual, por outra pessoa, com uma mensagem de texto;
- a caixa tem o destino esperado: agente ativo ou atendimento humano.
O estado Conectado comprova a consulta ao provedor, não a entrega do webhook. Faça um teste real e confirme a criação da conversa no SquadOS.
A conversa aparece, mas não há resposta automática
Section titled “A conversa aparece, mas não há resposta automática”Confira se a caixa está destinada a um agente ativo. Em Atendimento humano, nenhuma IA responde automaticamente. Se o agente respondeu no histórico mas o contato não recebeu, confira o estado da sessão e os envios no painel da Z-API.
A mídia do cliente não aparece
Section titled “A mídia do cliente não aparece”Esse é o limite atual do adaptador: o arquivo não é transportado para a conversa. Peça uma descrição em texto ou use outro canal que aceite o tipo de anexo necessário.