Conversations & Messages API Routes

GET /api/conversations

Descrição: Lista conversas da conta com suporte a filtros de status, atribuicao, escopo (mine/team/all) e paginação cursor-based. Enriquece cada conversa com última mensagem e contagem de não-lidas. Auth: Required

Request:

• Query params:
  • status (string, optional) - Filtrar por status (“open”, “closed”, “waiting”, “bot”)
  • assigned_to (uuid, optional) - Filtrar por usuário atribuido
  • scope (“all” | “mine” | “team”, default: “all”) - Escopo de visualização
  • cursor (string, optional) - Valor de last_message_at para paginação
  • limit (number, default: 50)

Response (sem cursor):

• 200: Array de conversas com contact, last_message_content, last_message_direction, unread_count

Response (com cursor):

• 200: { data: Conversation[], nextCursor: string | null, hasMore: boolean }

Notas:

• Escopo mine: conversas atribuidas ao usuário ou sem atribuicao, excluindo fechadas.
• Escopo team: conversas atribuidas a qualquer membro, excluindo fechadas.
• Enriquecimento: 2 queries paralelas para última mensagem e contagem de não-lidas.

---

POST /api/conversations

Descrição: Cria uma nova conversa vinculada a um contato e perfil WhatsApp. Auth: Required

Request:

• Body: { "contact_id": "uuid", "whatsapp_profile_id": "uuid" }

Response:

• 201: Conversa criada com contact expandido

---

GET /api/conversations/[id]/messages

Descrição: Lista mensagens de uma conversa específica, ordenadas cronologicamente (ascendente). Auth: Required

Request:

• Query params: limit (number, default: 50), before (string, optional) - para paginação histórico

Response:

• 200: Message[] (array de mensagens)

---

POST /api/conversations/[id]/messages

Descrição: Envia uma mensagem em uma conversa. Tenta enviar via WhatsApp se perfil conectado; caso contrario, salva como “pending”. Auth: Required

Request:

• Body: { "content": { "type": "text", "body": "Ola!" }, "text": "fallback" }

Response:

• 201: Message (mensagem criada)
• 404: Conversa não encontrada

Notas: Se conversa estava “closed”, reabre como “open”. Falha no envio WhatsApp não lança erro.

---

PUT /api/conversations/[id]/assign

Descrição: Atribui uma conversa a um usuário da equipe. Aceita null para desatribuir. Auth: Required Audit: update / conversation

Request:

• Body: { "assigned_to": "uuid | null" }

Response:

• 200: Conversation (com contact expandido)
• 400: “Usuário não pertence a esta conta”
• 404: Conversa não encontrada

Notas: Se conversa esta em “waiting” e recebe atribuicao, muda status para “open”. Dispara trigger conversation_assigned.

---

PATCH /api/conversations/[id]/status

Descrição: Atualiza o status de uma conversa (open, closed, waiting, bot). Auth: Required

Request:

• Body: { "status": "open | closed | waiting | bot" }

Response:

• 200: Conversation (atualizada)

Notas: Emite evento METRIC_CONVERSATION_CLOSED ou METRIC_CONVERSATION_OPENED conforme o status.

---

POST /api/conversations/[id]/transfer

Descrição: Transfere uma conversa para outro usuário da equipe. Cria nota interna automatica documentando a transferencia. Auth: Required Audit: update / conversation

Request:

• Body: { "to_user_id": "uuid", "reason": "string (opcional)" }

Response:

• 200: Conversation (com contact expandido)
• 400: “to_user_id e obrigatório” | “Usuário destino não pertence a esta conta”

---

GET /api/conversations/[id]/notes

Descrição: Lista todas as notas internas de uma conversa, enriquecidas com nome e email do autor. Auth: Required

Response:

• 200: Array de notas com user_name e user_email
• 404: Conversa não encontrada

---

POST /api/conversations/[id]/notes

Descrição: Cria uma nova nota interna em uma conversa. Auth: Required

Request:

• Body: { "content": "string (1-2000 chars)" }

Response:

• 201: InternalNote (criada)

---

DELETE /api/conversations/[id]/notes/[noteId]

Descrição: Exclui uma nota interna. Apenas o autor ou administradores podem excluir. Auth: Required

Response:

• 204: No content
• 403: “Apenas o autor ou administrador pode excluir esta nota”

---

POST /api/messages/send

Descrição: Envia uma mensagem em uma conversa via WhatsApp. Suporta texto, imagem, video, documento e template. Auth: Required Rate Limit: send preset (60 req/window) - chave: msg-send:{accountId} Audit: create / message

Request:

• Body (sendMessageSchema):

  {
    "conversation_id": "uuid",
    "content": {
      "type": "text | image | video | document | template | interactive",
      "body": "string (max 4096)",
      "media_url": "url",
      "template_name": "string",
      "template_params": {}
    }
  }

Response:

• 200: Message
• 502: “Falha ao enviar mensagem via WhatsApp”

Notas: Verifica plano ativo e limite mensal de mensagens. Se conversa esta “closed” ou “bot”, reabre como “open”.

---

GET /api/chat/unread-count

Descrição: Retorna contagem de conversas não-lidas (abertas ou aguardando com atividade nas últimas 24h). Auth: Required

Response:

• 200: { count: number }

---

GET /api/chatbot/logs

Descrição: Lista logs do chatbot com paginação cursor-based. Auth: Required

Request:

• Query params: limit (number, default: 50), cursor (string, optional)

Response:

• 200: { items: ChatbotLog[], next_cursor: string | null, has_more: boolean }