WhatsApp via Evolution API

A integração WhatsApp (Evolution) usa uma instância da Evolution API que a sua organização já administra. A sessão e o QR code ficam na Evolution; o SquadOS valida as credenciais, recebe mensagens pelo webhook e envia respostas pela API.

O que este conector exige

O conector atual do SquadOS é compatível com a Evolution API que oferece estes contratos:

GET /instance/connectionState/{instanceName} para consultar a conexão;
GET /instance/fetchInstances?instanceName={instanceName} para identificar o número;
evento de webhook messages.upsert;
endpoints /message/sendText/{instanceName}, /message/sendMedia/{instanceName} e /chat/sendPresence/{instanceName}.

Não confunda esse produto com Evolution Go: ele usa outros endpoints e outros nomes de evento. Consulte a instalação da Evolution API e a configuração oficial de webhooks da mesma família compatível.

Antes de começar

Você precisa de:

permissão para criar caixas de entrada no SquadOS;
uma instância Evolution API criada;
o Nome da instância;
uma chave aceita no header apikey pela sua instalação — global ou específica da instância, conforme a configuração da Evolution;
a URL base absoluta da instância, por exemplo https://evolution.suaempresa.com;
acesso ao Evolution Manager para configurar o webhook e parear o WhatsApp.

Uma barra / no fim da URL base é aceita e removida pelo SquadOS. Use somente um endereço confiável administrado pela sua organização. Não informe localhost, endereços de rede privada ou painéis internos: a validação faz uma requisição a partir do servidor do SquadOS.

Conectar a caixa

No Admin, abra Caixas de entrada.
Clique em Conectar caixa.
No grupo WhatsApp, escolha WhatsApp (Evolution). A descrição exibida é Use a sua instância da Evolution API.
Preencha exatamente os três campos:
- URL da sua instância Evolution;
- Nome da instância;
- API Key da instância.
Clique em Validar e continuar.

Nesse ponto, o SquadOS chama GET /instance/connectionState/{instanceName} com o header apikey. Uma resposta HTTP 2xx comprova que a URL, a instância e a chave foram aceitas; ela ainda não comprova que o WhatsApp está pareado nem que o webhook entrega mensagens. A caixa ainda não é criada.

Configurar o webhook e o WhatsApp

Depois da validação, o SquadOS mostra uma URL de webhook exclusiva para a conexão pendente. Copie a URL completa e siga o texto exibido no produto:

Abra o Evolution Manager e selecione a instância informada.
Vá a Configurações > Webhook ou Events da instância.
Cole a URL em Webhook URL e mantenha o método POST.
Selecione somente o evento de mensagem. A interface do SquadOS o chama de messages.upsert; algumas versões da Evolution mostram a opção de configuração como MESSAGES_UPSERT. O payload recebido pelo SquadOS precisa ter event: "messages.upsert".
Salve o webhook.
No próprio Evolution Manager, conecte o WhatsApp e escaneie o QR code. O SquadOS não mostra esse QR code.
Volte ao SquadOS e clique em Já configurei o webhook.
Se a instância ainda não estiver conectada, conclua o pareamento na Evolution e use Verificar novamente.

Somente quando connectionState retorna instance.state: "open" o SquadOS ativa a conexão. Ele tenta obter o número por fetchInstances; a identidade não deve estar ativa em outra caixa.

Escolher quem atende

Após a conexão, o wizard abre Quem atende esta caixa?:

escolha um agente ativo para ele responder automaticamente; ou
mantenha Atendimento humano para a mensagem entrar na fila e ser respondida em Conversas.

Dê um Nome da caixa e clique em Concluir. A credencial pertence à caixa, não ao agente. Por isso, configuração e desconexão ficam em Caixas de entrada; o editor do agente apenas mostra as caixas encaminhadas para ele.

Mensagens aceitas

Na entrada, o adapter atual:

aceita somente requests JSON com event: "messages.upsert";
ignora grupos cujo remoteJid termina em @g.us;
ignora mensagens com fromMe: true;
lê texto simples, texto estendido e a legenda de uma imagem;
usa o telefone extraído de remoteJid para manter a conversa na mesma caixa.

Arquivos recebidos não são transportados para o SquadOS nessa integração. Imagem sem legenda, áudio, vídeo, sticker e documento podem chegar ao pipeline sem conteúdo útil. Enquanto esse limite existir, peça ao cliente para enviar a informação em texto ou use outro canal para jornadas que dependem de anexos.

Na saída, agente, operador e Automação podem reutilizar a conversa e a caixa. O adapter envia texto, imagem gerada por URL e presença de digitação. Uma imagem enviada pelo SquadOS não significa que imagens recebidas pela Evolution sejam preservadas.

Estado, credenciais e desconexão

Abra a caixa e use Editar para consultar a conexão ou substituir URL, nome e chave. O SquadOS valida o conjunto novo antes de salvá-lo; se a validação falhar, mantém as credenciais anteriores.

O status exibido é uma consulta à Evolution, não uma prova contínua de entrega. Uma falha HTTP ou de rede nessa consulta hoje pode ser tratada como connected: false e desativar uma caixa que ainda esteja pareada. Antes de refazer a conexão, confira o estado no Evolution Manager e tente novamente.

Ao desconectar, o SquadOS chama DELETE /instance/logout/{instanceName} e remove a caixa local. As conversas já criadas permanecem no histórico, mas a conexão deixa de recebê-las e de respondê-las. Como uma falha remota pode ser ocultada, confirme também no Evolution Manager que a sessão realmente encerrou. Desconectar não apaga a instância; exclua-a separadamente no provedor somente se esse for o objetivo.

Diagnóstico

Credenciais inválidas: a validação recebeu um HTTP não 2xx diferente de 404 e 5xx. Confira URL, nome e chave. Não presuma que toda ocorrência seja apenas uma chave incorreta.
Instância não encontrada: a Evolution respondeu 404. Confirme o instanceName, inclusive maiúsculas e minúsculas, e a URL base.
Provedor indisponível: houve erro de rede ou HTTP 5xx. Confirme a saúde da Evolution e repita; não recrie a caixa de imediato.
A instância ainda não está conectada: o estado ainda não é open. Faça o pareamento no Evolution Manager e clique em Verificar novamente.
Webhook não recebe mensagens: confira URL completa, método POST, evento de mensagem e se a configuração por eventos não acrescentou um sufixo à URL. O SquadOS espera o endpoint exatamente como foi copiado.
A caixa conecta, mas a primeira mensagem não aparece: envie texto simples de um contato individual. Não use grupo, mensagem enviada pelo próprio número ou mídia sem legenda como primeiro teste.
Número ou resposta incorretos: confira se a caixa está ligada ao destino esperado e se o mesmo número não está ativo em outra caixa.

Para fechar o teste, envie uma mensagem textual de outro número, confirme a entrada em Conversas e responda pelo destino escolhido. Estado Conectado sozinho não valida o caminho completo.