WhatsApp via Evolution API

A Evolution API é um gateway WhatsApp open-source que você roda no seu próprio servidor (ou em hospedagem dedicada). É o caminho preferido quando você quer controle total sobre a infraestrutura — quem hospeda é você, e o SquadOS só conversa com a sua instância via REST.

API não-oficial

Evolution API também usa o protocolo do WhatsApp Web — sem SLA da Meta, sujeito a banimento se usado para spam, e a sessão pode cair. Para escala em produção com SLA, prefira o WhatsApp Oficial (Cloud API).

Quando usar

Use Evolution quando	Não use quando
Você quer hospedar tudo — banco, fila, sessão — no seu próprio servidor	Não tem time para subir e manter um servidor 24/7
Precisa customizar comportamento que provedores gerenciados não permitem	Quer começar rápido sem operar infraestrutura — Z-API/Uazapi/Cloud API saem na frente
Já tem Evolution rodando para outras integrações	Está avaliando WhatsApp pela primeira vez

Pré-requisitos

Antes de conectar:

• Evolution API rodando num servidor acessível pela internet (HTTPS). O SquadOS precisa alcançar a URL pública para chamar a API.
• Instância criada dentro do Evolution Manager, com um instance_name definido.
• API Key da instância (também chamada de apikey nos headers da Evolution).

O QR code do WhatsApp é escaneado no Evolution Manager, não no SquadOS. O SquadOS apenas consulta o estado da instância e envia/recebe mensagens via API.

Passo a passo

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

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

3. Preencha:

   

   • URL da sua instância Evolution — base da Evolution (ex.: https://evolution.suaempresa.com).
   • Nome da instância — o instance_name que você criou no Evolution Manager.
   • API Key da instância — a apikey daquela instância específica.

4. Clique em Validar e continuar. O SquadOS chama GET /instance/connectionState/<instance_name> na sua Evolution. Possíveis erros nesse passo:

   • 401/403 → API Key errada → “credenciais inválidas”.
   • 404 → instância não existe naquela URL → “instance not found”.
   • Outros HTTPs → erro de rede / Evolution offline.

5. O passo seguinte mostra a URL de webhook gerada pelo SquadOS e o passo a passo de configuração no Evolution Manager. Copie a URL e, no Evolution Manager:

   1. Abra a instância que você acabou de cadastrar.
   2. Vá em Configurações → Webhook (ou Events) da instância.
   3. Cole a URL no campo Webhook URL e mantenha o método como POST.
   4. Em eventos, marque apenas messages.upsert.
   5. Salve a configuração de webhook.
   6. Conecte o WhatsApp escaneando o QR code dentro do próprio Evolution Manager (não aqui).

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

7. O SquadOS chama /instance/connectionState/<instance_name> para verificar. Quando o Evolution retornar state: open, o card vira Conectado e o número aparece (obtido via /instance/fetchInstances).

Se a verificação falhar, abra o Evolution Manager, confirme que a instância está com estado open (escaneie o QR lá) e clique em Verificar novamente.

Por que apenas messages.upsert?

O webhook da Evolution suporta vários eventos (connection.update, presence.update, qrcode.updated, etc.), mas o SquadOS só processa messages.upsert. Qualquer outro evento é descartado com OK - other event — então marcar mais eventos só gera tráfego e processamento inútil. Mantenha só messages.upsert selecionado.

Como funciona

• O SquadOS não hospeda a sessão WhatsApp — ela vive na sua Evolution.
• Mensagens chegam pelo webhook (evento messages.upsert), viram conversas no SquadOS, e o agente responde via POST /message/sendText/<instance_name> na Evolution.
• Mídia é enviada via POST /message/sendMedia/<instance_name>.
• Grupos (@g.us) e mensagens com fromMe: true são filtrados no SquadOS — mas vale também filtrá-los no Evolution para reduzir tráfego.

Editando credenciais depois

Se a API Key foi rotacionada ou você mudou a URL base (migrou servidor, trocou domínio), abra o card Evolution conectado, clique em informações e edite. O SquadOS revalida com a Evolution antes de salvar; se falhar, mantém o anterior.

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

Desconectando

No card Evolution conectado, clique em Desconectar. O SquadOS chama DELETE /instance/logout/<instance_name> na Evolution e marca o gatilho como inativo. A instância em si continua no Evolution Manager — para apagar definitivamente, use o Manager.

Problemas comuns

• “Credenciais inválidas” no passo 1. API Key errada ou faltando o header apikey. Confira no Evolution Manager qual é a apikey daquela instância (ela é por-instância, não global).
• “Instance not found”. O instance_name digitado não existe naquela URL base. Confira ortografia (case-sensitive) e que a URL aponta para o Evolution certo.
• Webhook configurado mas mensagens não chegam. No Evolution Manager, confirme que messages.upsert está marcado e que o webhook está habilitado. Confirme também que a URL pública do Evolution está acessível pelo SquadOS (sem firewall bloqueando IP do Supabase).
• Status fica em “close” eternamente. Você precisa escanear o QR code no Evolution Manager — o SquadOS não exibe QR para esse provedor.
• Mensagens duplicadas / agente respondendo a si mesmo. Verifique se o Evolution está enviando mensagens com fromMe: true no webhook. O SquadOS já filtra essas, mas se acontece em loop pode haver problema na configuração de eventos do webhook.