API: Conversations¶

Visão Geral¶

Gerenciamento de conversas entre contatos WhatsApp e a plataforma. Suporta modo IA (automático) e modo Manual (operador humano).

Endpoints¶

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

Lista conversas de uma instância.

Query Parameters: - status (opcional): Active, Resolved, Escalated - page (opcional): Página (default: 1) - pageSize (opcional): Itens por página (default: 20)

Response (200 OK):

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contactPhone": "+5511999998888",
      "contactName": "João Silva",
      "contactProfilePictureUrl": "https://cdn.exemplo.com/profile.jpg",
      "status": "Active",
      "mode": "AI",
      "startedAt": "2024-01-20T10:00:00Z",
      "lastMessageAt": "2024-01-20T10:30:00Z",
      "lastMessage": "Qual o horário de funcionamento?",
      "unreadCount": 2
    }
  ],
  "totalCount": 50,
  "page": 1,
  "pageSize": 20
}

GET /api/conversations/{id}¶

Retorna detalhes de uma conversa.

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "instanceId": "660e8400-e29b-41d4-a716-446655440001",
  "instanceName": "Suporte Principal",
  "agentId": "770e8400-e29b-41d4-a716-446655440002",
  "agentName": "Suporte TI",
  "contactPhone": "+5511999998888",
  "contactName": "João Silva",
  "contactProfilePictureUrl": "https://cdn.exemplo.com/profile.jpg",
  "status": "Active",
  "mode": "AI",
  "modeChangedAt": null,
  "startedAt": "2024-01-20T10:00:00Z",
  "lastMessageAt": "2024-01-20T10:30:00Z",
  "resolvedAt": null,
  "summary": null,
  "totalInputTokens": 1500,
  "totalOutputTokens": 800
}

GET /api/conversations/{id}/messages¶

Lista mensagens de uma conversa com paginação.

Query Parameters: - before (opcional): Cursor para paginação (ID da mensagem) - limit (opcional): Quantidade (default: 50)

Response (200 OK):

href="#__codelineno-2-1">{ "items": [ { "id": "880e8400-e29b-41d4-a716-446655440000", "role": "User", "type": "Text", "content": "Qual o horário de funcionamento?", "mediaUrl": null, "mediaMimeType": null, "mediaFileName": null, "status": "Read", "createdAt": "2024-01-20T10:30:00Z", "inputTokens": null, "outputTokens": null, "reactions": [ { "emoji": "👍", "senderPhone": "+5511999998888", "fromMe": false } ] }, { "id": "990e8400-e29b-41d4-a716-446655440001", "role": "Assistant", "type": "Text", "content": "Nosso horário é das 8h às 18h.", "mediaUrl": null, "mediaMimeType": null, "mediaFileName": null, "status": "Delivered", "createdAt": "2024-01-20T10:30:05Z", "inputTokens": 50, "outputTokens": 20, "reactions": [] } ], "hasMore": true, "oldestMessageId": "770e8400-e29b-41d4-a716-446655440000" }

POST /api/conversations/start¶

Inicia uma nova conversa a partir do portal.

Request:

{
  "instanceId": "660e8400-e29b-41d4-a716-446655440001",
  "contactPhone": "+5511999998888",
  "message": "Olá, como posso ajudar?"
}

Response (201 Created):

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "messageId": "880e8400-e29b-41d4-a716-446655440000"
}

POST /api/conversations/{id}/messages¶

Envia uma mensagem na conversa.

Request:

{
  "content": "Segue o documento solicitado.",
  "attachments": [
    {
      "fileName": "manual.pdf",
      "mimeType": "application/pdf",
      "base64": "JVBERi0xLjQK..."
    }
  ],
  "isVoiceMessage": false
}

Response (200 OK):

{
  "messageId": "880e8400-e29b-41d4-a716-446655440000",
  "whatsappMessageId": "wamid.xxx",
  "status": "Sent"
}

POST /api/conversations/{id}/transfer¶

Transfere o modo da conversa (AI ↔ Manual).

Request:

{
  "targetMode": "Manual"
}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mode": "Manual",
  "modeChangedAt": "2024-01-20T11:00:00Z"
}

POST /api/conversations/{id}/resolve¶

Resolve uma conversa.

Request:

{
  "summary": "Cliente tinha dúvida sobre horário. Esclarecido."
}

Response (200 OK):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Resolved",
  "resolvedAt": "2024-01-20T11:30:00Z"
}

PUT /api/conversations/{id}/read¶

Marca a conversa como lida pelo operador.

Response: 204 No Content

POST /api/conversations/{conversationId}/messages/{messageId}/react¶

Adiciona ou remove uma reação a uma mensagem.

Request:

{
  "emoji": "👍"
}

Response (200 OK):

{
  "messageId": "880e8400-e29b-41d4-a716-446655440000",
  "emoji": "👍",
  "added": true
}

Tipos de Mensagem¶

Type	Descrição
Text	Mensagem de texto
Image	Imagem (jpg, png, gif, webp)
Audio	Áudio/Voice message
Video	Vídeo
Document	Documento (pdf, doc, etc)
Sticker	Sticker do WhatsApp

Status de Mensagem¶

Status	Descrição
Pending	Aguardando envio
Sent	Enviada (✓)
Delivered	Entregue (✓✓)
Read	Lida (✓✓ azul)
Failed	Falhou

Modos de Conversa¶

Mode	Descrição
AI	IA processa as mensagens automaticamente
Manual	Operador humano responde via portal

SignalR - Eventos Real-time¶

O hub ConversationHub emite eventos para atualizações em tempo real:

Evento	Descrição
NewMessage	Nova mensagem na conversa
MessageStatusUpdated	Status de entrega atualizado
ConversationUpdated	Conversa atualizada (status, modo)
NewConversation	Nova conversa iniciada

Exemplo de Uso (Blazor)¶

_hubConnection.On<MessageItemResponse>("NewMessage", message =>
{
    _messages.Add(message);
    StateHasChanged();
});

Erros Comuns¶

Status	Código	Descrição
404	CONVERSATION_NOT_FOUND	Conversa não encontrada
400	INSTANCE_DISCONNECTED	Instância WhatsApp desconectada
400	CONVERSATION_RESOLVED	Conversa já resolvida