API: Instances¶

Visão Geral¶

Gerenciamento de instâncias WhatsApp conectadas via Evolution API. Cada instância representa um número de telefone conectado.

Endpoints¶

GET /api/instances¶

Lista todas as instâncias do tenant.

Response (200 OK):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Suporte Principal",
    "phoneNumber": "+5511999998888",
    "status": "Connected",
    "agentId": "660e8400-e29b-41d4-a716-446655440001",
    "agentName": "Suporte TI",
    "startsWithAI": true,
    "createdAt": "2024-01-15T10:00:00Z",
    "todayConversations": 25,
    "isArchived": false
  }
]

GET /api/instances/{id}¶

Retorna detalhes de uma instância.

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal",
  "phoneNumber": "+5511999998888",
  "status": "Connected",
  "agentId": "660e8400-e29b-41d4-a716-446655440001",
  "agentName": "Suporte TI",
  "startsWithAI": true,
  "aiAvailabilityHours": [
    { "dayOfWeek": 1, "startTime": "08:00", "endTime": "18:00" }
  ],
  "signatureText": "Atendente Virtual",
  "signaturePosition": "Disabled",
  "showTyping": true,
  "delaySeconds": 0,
  "reopenWindowMinutes": 10,
  "markAsReadOnAiReply": true,
  "maxAiResponsesPerConversation": null,
  "allowImageAnalysis": true,
  "allowAudioAnalysis": true,
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-20T14:00:00Z",
  "totalConversations": 500,
  "todayConversations": 25
}

POST /api/instances¶

Cria uma nova instância.

Request:

{
  "name": "Suporte Principal",
  "agentId": "660e8400-e29b-41d4-a716-446655440001"
}

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal",
  "status": "Disconnected"
}

PUT /api/instances/{id}¶

Atualiza uma instância.

Request:

{
  "name": "Suporte Principal v2",
  "agentId": "660e8400-e29b-41d4-a716-446655440001",
  "startsWithAI": true,
  "aiAvailabilityHours": [
    { "dayOfWeek": 1, "startTime": "08:00", "endTime": "18:00" }
  ],
  "signatureText": "Atendente Virtual",
  "signaturePosition": "Disabled",
  "showTyping": true,
  "delaySeconds": 0,
  "reopenWindowMinutes": 10,
  "markAsReadOnAiReply": true,
  "maxAiResponsesPerConversation": null,
  "allowImageAnalysis": true,
  "allowAudioAnalysis": false
}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Suporte Principal v2",
  "agentId": "660e8400-e29b-41d4-a716-446655440001",
  "startsWithAI": true,
  "aiAvailabilityHours": [
    { "dayOfWeek": 1, "startTime": "08:00", "endTime": "18:00" }
  ],
  "signatureText": "Atendente Virtual",
  "signaturePosition": "Disabled",
  "showTyping": true,
  "delaySeconds": 0,
  "reopenWindowMinutes": 10,
  "markAsReadOnAiReply": true,
  "maxAiResponsesPerConversation": null,
  "allowImageAnalysis": true,
  "allowAudioAnalysis": false,
  "updatedAt": "2024-01-20T14:00:00Z"
}

DELETE /api/instances/{id}¶

Arquiva uma instância (soft delete). A instância é desconectada e não processa mensagens, mas pode ser restaurada.

Response: 204 No Content

POST /api/instances/{id}/restore¶

Restaura uma instância arquivada.

Autorização: Admin

Response: 204 No Content

Comportamento: - Remove flag de arquivamento (IsArchived = false, ArchivedAt = null) - Instância volta desconectada — o admin deve reconectá-la manualmente

DELETE /api/instances/{id}/permanent?name={confirmationName}¶

Exclui permanentemente uma instância arquivada e todos os dados associados. Requer confirmação por nome.

Autorização: Admin

Query Parameters:

Parâmetro	Tipo	Descrição
name	string	Nome da instância (deve coincidir para confirmar)

Response: 204 No Content

Comportamento: - Somente instâncias arquivadas podem ser excluídas permanentemente - Remove em cascata: conversas, mensagens, whitelist, blacklist - Remove arquivos R2 (mídia de conversas) em paralelo (Parallel.ForEachAsync, MaxDegreeOfParallelism=10) - Ação irreversível — não pode ser desfeita

Erros:

Status	Código	Descrição
404	INSTANCE_NOT_FOUND	Instância não encontrada
400	VALIDATION_ERROR	Nome de confirmação não confere ou instância não está arquivada

POST /api/instances/{id}/connect¶

Conecta a instância ao WhatsApp. Retorna QR code se necessário.

Response (200 OK):

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

POST /api/instances/{id}/disconnect¶

Desconecta a instância do WhatsApp.

Response (200 OK):

{
  "status": "Disconnected"
}

GET /api/instances/{id}/status¶

Retorna o status atual da conexão.

Response (200 OK):

{
  "status": "Connected",
  "phoneNumber": "+5511999998888",
  "profileName": "Empresa XYZ",
  "profilePictureUrl": "https://pps.whatsapp.net/..."
}

Sub-recursos¶

Whitelist¶

Lista de contatos autorizados. Se vazia, aceita todos.

GET /api/instances/{instanceId}/whitelist¶

[
  {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+5511999887766",
    "contactName": "João - Loja 5",
    "notes": "Gerente da loja",
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00Z"
  }
]

GET /api/instances/{instanceId}/whitelist/{id}¶

Retorna uma entrada específica da whitelist.

POST /api/instances/{instanceId}/whitelist¶

{
  "phoneNumber": "+5511999887766",
  "contactName": "João - Loja 5",
  "notes": "Gerente da loja",
  "isActive": true
}

PUT /api/instances/{instanceId}/whitelist/{id}¶

Atualiza uma entrada da whitelist.

DELETE /api/instances/{instanceId}/whitelist/{id}¶

Blacklist¶

Lista de contatos bloqueados. Mensagens são ignoradas.

GET /api/instances/{instanceId}/blacklist¶

[
  {
    "id": "990e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "+5511999776655",
    "reason": "Spam",
    "blockedAt": "2024-01-18T14:00:00Z",
    "blockedByName": "Admin"
  }
]

GET /api/instances/{instanceId}/blacklist/{id}¶

Retorna uma entrada específica da blacklist.

POST /api/instances/{instanceId}/blacklist¶

{
  "phoneNumber": "+5511999776655",
  "reason": "Spam"
}

PUT /api/instances/{instanceId}/blacklist/{id}¶

Atualiza uma entrada da blacklist.

DELETE /api/instances/{instanceId}/blacklist/{id}¶

Status de Conexão¶

Status	Descrição
Disconnected	Desconectado
Connecting	Conectando (aguardando QR)
Connected	Conectado e operacional
Open	Conexão aberta
Close	Conexão fechada

Lógica de Whitelist/Blacklist¶

Blacklist é verificada primeiro - se número está na blacklist, mensagem é ignorada
Whitelist vazia - aceita qualquer número
Whitelist com entradas - só aceita números listados e ativos

Evolution API¶

A instância corresponde a uma sessão no Evolution API. O nome da instância é usado para identificar a sessão.

Criação de Sessão¶

Quando uma instância é criada, a API: 1. Cria a sessão no Evolution via POST /instance/create 2. Salva a instância no banco 3. Sessão fica em status Disconnected

Conexão¶

Quando /connect é chamado: 1. API chama Evolution GET /instance/connect/{instanceName} 2. Evolution retorna QR code 3. Usuário escaneia com WhatsApp 4. Webhook connection.update atualiza status para Connected

Erros Comuns¶

Status	Código	Descrição
404	INSTANCE_NOT_FOUND	Instância não encontrada
400	EVOLUTION_ERROR	Erro na Evolution API