Fluxo: Conexão WhatsApp¶

Visão Geral¶

Fluxo de conexão e reconexão de instâncias WhatsApp via Evolution API.

Estados de Conexão¶

                    ┌───────────────┐
                    │ Disconnected  │
                    └───────┬───────┘
                            │
                     /connect
                            │
                            ▼
                    ┌───────────────┐
                    │  Connecting   │◄────────────┐
                    │  (QR Code)    │             │
                    └───────┬───────┘             │
                            │                     │
                     Scan QR                   Timeout
                            │                     │
                            ▼                     │
                    ┌───────────────┐             │
                    │   Connected   │─────────────┘
                    └───────┬───────┘
                            │
                     Disconnect/
                     Session lost
                            │
                            ▼
                    ┌───────────────┐
                    │ Disconnected  │
                    └───────────────┘

Fluxo de Conexão¶

1. Criação da Instância¶

POST /api/instances
{
  "name": "Suporte Principal",
  "sessionId": "suporte-01",
  "agentId": "..."
}

A instância é criada com status Disconnected.

2. Iniciar Conexão¶

POST /api/instances/{id}/connect

API interna: 1. Chama Evolution API GET /instance/connect/{sessionId} 2. Evolution retorna QR Code em base64 3. Atualiza status para Connecting

Response:

{
  "status": "Connecting",
  "qrCode": "data:image/png;base64,iVBORw0KGgo..."
}

3. Escaneamento do QR Code¶

QR Code é exibido no portal
Usuário escaneia com WhatsApp mobile
Evolution estabelece conexão WebSocket com WhatsApp

4. Confirmação via Webhook¶

Evolution envia webhook connection.update:

{
  "event": "connection.update",
  "instance": "suporte-01",
  "data": {
    "state": "open",
    "wuid": "5511999998888@s.whatsapp.net"
  }
}

Processamento:

instance.Status = ConnectionStatus.Connected;
instance.PhoneNumber = connectionData.Wuid.Split('@')[0];

5. Desconexão¶

Via portal:

POST /api/instances/{id}/disconnect

Via webhook (perda de conexão):

{
  "event": "connection.update",
  "instance": "suporte-01",
  "data": {
    "state": "close"
  }
}

Interface do Portal¶

Dialog de QR Code¶

<QrCodeDialog Instance="@_instance"
              OnConnected="HandleConnected"
              OnClose="CloseDialog" />

Componente: 1. Chama /connect ao abrir 2. Exibe QR Code 3. Polling de status a cada 3 segundos 4. Fecha automaticamente quando conecta

Status na Lista¶

<ConnectionStatusIndicator Status="@instance.Status" />

Status	Cor	Ícone
Connected	Verde	✓
Connecting	Amarelo	⟳
Disconnected	Vermelho	✗

Reconexão¶

Automática (Evolution)¶

Evolution API tenta reconexão automática quando a sessão cai temporariamente.

Manual (Portal)¶

Se a reconexão automática falhar: 1. Usuário acessa detalhes da instância 2. Clica em "Conectar" 3. Novo QR Code é gerado 4. Processo de escaneamento reinicia

Tratamento de Erros¶

Cenário	Tratamento
Evolution indisponível	Erro 503, retry manual
QR Code expirado	Gerar novo QR Code
Sessão inválida	Criar nova sessão
WhatsApp bloqueado	Log error, notificar admin

Eventos SignalR¶

// Notificação de mudança de status
await _hub.Clients.Group($"tenant:{tenantId}")
    .SendAsync("InstanceStatusChanged", new {
        instanceId,
        status,
        phoneNumber
    });

Logs¶

_logger.LogInformation("Instance {SessionId} connected: {PhoneNumber}",
    sessionId, phoneNumber);

_logger.LogWarning("WhatsApp session disconnected: {SessionId}",
    sessionId);

Configuração Evolution API¶

No docker-compose.dev.yaml:

WEBHOOK_EVENTS_CONNECTION_UPDATE: "true"
WEBHOOK_EVENTS_QRCODE_UPDATED: "true"

Boas Práticas¶

Monitorar desconexões - Alertar se instância ficar offline por muito tempo
Backup de sessão - Evolution persiste sessão no volume
Evitar reconexões frequentes - Pode causar bloqueio pelo WhatsApp
Manter Evolution atualizado - Versões antigas podem ter problemas de compatibilidade