> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversas

> As conversas são o núcleo do ZappWay — cada mensagem trocada com um contato por qualquer canal (WhatsApp, Email, Widget, TikTok e outros) é organizada como uma conversa.

> **O que você vai aprender:**
> Esta página explica como funcionam as conversas no ZappWay, como listá-las e gerenciá-las, como atualizar seus status em massa, como exportá-las e como usar o recurso de resumo por IA.

***

## 🔢 Sumário

1. [Visão Geral](#1-visao-geral)
2. [Referência de Endpoints](#2-referencia-de-endpoints)
3. [Listando Conversas](#3-listando-conversas)
4. [Gerenciando uma Conversa](#4-gerenciando-uma-conversa)
5. [Atualização de Status em Massa](#5-atualizacao-de-status-em-massa)
6. [Exportar Conversas](#6-exportar-conversas)
7. [Avaliando Respostas](#7-avaliando-respostas)
8. [Formato de Resposta](#8-formato-de-resposta)
9. [Boas Práticas](#9-boas-praticas)
10. [Troubleshooting](#10-troubleshooting)

***

## 1. Visão Geral

### O que é uma Conversa?

Uma **Conversa** no ZappWay é um thread completo de mensagens entre um contato e sua organização — mediado por um Funcionário IA, um agente humano, ou ambos.

**Conversas podem originar de:**

* 💬 WhatsApp (Business API)
* 📧 Caixa de Entrada de Email
* 🌐 Widget (chat do site)
* 📱 DMs do TikTok
* 🔌 Qualquer integração conectada

**Cada conversa possui:**

* Um **contato** — com quem a conversa está acontecendo
* Um **canal** — onde a conversa está ocorrendo
* Um **status** — `open`, `resolved` ou `snoozed`
* Uma atribuição de **Funcionário IA** (opcional)
* Um **thread de mensagens** completo com timestamps

### Colaboração IA e Humano

As conversas suportam um **modelo híbrido**: o Funcionário IA pode lidar com as mensagens automaticamente, e um agente humano pode assumir a qualquer momento. As mensagens da IA e as mensagens humanas aparecem no mesmo thread.

***

## 2. Referência de Endpoints

| Método   | Endpoint                                          | Descrição                                            | Auth                             |
| -------- | ------------------------------------------------- | ---------------------------------------------------- | -------------------------------- |
| `GET`    | `/api/conversations`                              | Listar conversas com filtros                         | Auth opcional (suporte a widget) |
| `HEAD`   | `/api/conversations`                              | Preflight CORS                                       | Nenhuma                          |
| `GET`    | `/api/conversations/[conversationId]`             | Obter uma conversa específica                        | Sessão org                       |
| `PATCH`  | `/api/conversations/[conversationId]`             | Atualizar conversa (atribuir agente, definir status) | Sessão org                       |
| `DELETE` | `/api/conversations/[conversationId]`             | Excluir uma conversa                                 | Sessão org                       |
| `POST`   | `/api/conversations/update-status`                | Atualizar status de conversas em massa               | Sessão org                       |
| `POST`   | `/api/conversations/bulk-unread`                  | Marcar conversas como não lidas em massa             | Sessão org                       |
| `GET`    | `/api/conversations/export`                       | Exportar conversas para arquivo                      | Sessão org                       |
| `POST`   | `/api/conversations/[conversationId]/eval-answer` | Avaliar qualidade de resposta da IA                  | Sessão org                       |

***

## 3. Listando Conversas

### Listar Conversas

```bash theme={null}
GET /api/conversations
```

Suporta **autenticação opcional** — requisições autenticadas retornam conversas da organização; requisições não autenticadas podem retornar conversas públicas do widget.

**Parâmetros de Query:**

| Parâmetro   | Tipo                                | Descrição                                             |
| ----------- | ----------------------------------- | ----------------------------------------------------- |
| `status`    | `"open" \| "resolved" \| "snoozed"` | Filtrar por status da conversa                        |
| `agentId`   | `string`                            | Filtrar por Funcionário IA atribuído                  |
| `contactId` | `string`                            | Filtrar por contato                                   |
| `channel`   | `string`                            | Filtrar por canal (ex: `whatsapp`, `email`, `widget`) |
| `page`      | `number`                            | Número da página para paginação                       |
| `limit`     | `number`                            | Número de resultados por página                       |
| `search`    | `string`                            | Busca full-text no conteúdo das conversas             |
| `dateFrom`  | `ISO 8601`                          | Filtrar conversas após esta data                      |
| `dateTo`    | `ISO 8601`                          | Filtrar conversas antes desta data                    |

**Exemplo:**

```bash theme={null}
GET /api/conversations?status=open&channel=whatsapp&page=1&limit=20
```

**TypeScript:**

```ts theme={null}
const params = new URLSearchParams({
  status: 'open',
  channel: 'whatsapp',
  page: '1',
  limit: '20',
});

const response = await fetch(`/api/conversations?${params}`);
const data = await response.json();
```

***

## 4. Gerenciando uma Conversa

### Obter uma Conversa

```bash theme={null}
GET /api/conversations/{conversationId}
```

### Atualizar uma Conversa

```bash theme={null}
PATCH /api/conversations/{conversationId}
Content-Type: application/json
```

**Corpo da Requisição:**

| Campo            | Tipo                                | Descrição                                 |
| ---------------- | ----------------------------------- | ----------------------------------------- |
| `status`         | `"open" \| "resolved" \| "snoozed"` | Atualizar status da conversa              |
| `agentId`        | `string \| null`                    | Atribuir ou desatribuir um Funcionário IA |
| `assignedUserId` | `string \| null`                    | Atribuir a um membro humano da equipe     |
| `note`           | `string`                            | Adicionar uma nota interna                |
| `snoozeUntil`    | `ISO 8601`                          | Adiar até um datetime específico          |

**Exemplo — Resolver uma conversa:**

```json theme={null}
{
  "status": "resolved"
}
```

**Exemplo — Atribuir ao Funcionário IA:**

```json theme={null}
{
  "agentId": "agent_456"
}
```

**Exemplo — Adiar:**

```json theme={null}
{
  "status": "snoozed",
  "snoozeUntil": "2025-01-20T09:00:00.000Z"
}
```

### Excluir uma Conversa

```bash theme={null}
DELETE /api/conversations/{conversationId}
```

> ⚠️ Excluir uma conversa remove permanentemente todas as mensagens associadas. Esta ação é irreversível.

***

## 5. Atualização de Status em Massa

Atualize o status de várias conversas ao mesmo tempo.

```bash theme={null}
POST /api/conversations/update-status
Content-Type: application/json
```

**Corpo da Requisição:**

| Campo             | Tipo                                | Obrigatório | Descrição                                         |
| ----------------- | ----------------------------------- | ----------- | ------------------------------------------------- |
| `conversationIds` | `string[]`                          | ✅           | Array de IDs de conversas a atualizar             |
| `status`          | `"open" \| "resolved" \| "snoozed"` | ✅           | Novo status para todas as conversas especificadas |

**Exemplo — Resolver múltiplas conversas:**

```json theme={null}
{
  "conversationIds": ["conv_abc123", "conv_def456", "conv_ghi789"],
  "status": "resolved"
}
```

### Marcar como Não Lidas em Massa

```bash theme={null}
POST /api/conversations/bulk-unread
Content-Type: application/json
```

**Corpo da Requisição:**

```json theme={null}
{
  "conversationIds": ["conv_abc123", "conv_def456"]
}
```

***

## 6. Exportar Conversas

Baixe conversas como arquivo para relatórios, conformidade ou análise.

```bash theme={null}
GET /api/conversations/export
```

**Parâmetros de Query:**

| Parâmetro  | Tipo              | Descrição                              |
| ---------- | ----------------- | -------------------------------------- |
| `status`   | `string`          | Filtrar por status antes de exportar   |
| `dateFrom` | `ISO 8601`        | Exportar conversas a partir desta data |
| `dateTo`   | `ISO 8601`        | Exportar conversas até esta data       |
| `format`   | `"csv" \| "json"` | Formato de exportação (padrão: `csv`)  |

***

## 7. Avaliando Respostas

Use o endpoint de avaliação para classificar a qualidade das respostas geradas pela IA. Este feedback é usado para melhorar o desempenho da IA ao longo do tempo.

```bash theme={null}
POST /api/conversations/{conversationId}/eval-answer
Content-Type: application/json
```

**Corpo da Requisição:**

| Campo       | Tipo                       | Obrigatório | Descrição                      |
| ----------- | -------------------------- | ----------- | ------------------------------ |
| `messageId` | `string`                   | ✅           | ID da mensagem da IA a avaliar |
| `rating`    | `"positive" \| "negative"` | ✅           | Sua classificação de qualidade |
| `feedback`  | `string`                   | ❌           | Feedback escrito opcional      |

**Exemplo:**

```json theme={null}
{
  "messageId": "msg_abc123",
  "rating": "positive",
  "feedback": "Resposta perfeita — precisa e concisa"
}
```

***

## 8. Formato de Resposta

### Status Codes

| Status | Significado                                          |
| ------ | ---------------------------------------------------- |
| `200`  | Requisição bem-sucedida                              |
| `204`  | Excluído com sucesso                                 |
| `400`  | Corpo inválido da requisição ou parâmetros inválidos |
| `401`  | Não autenticado                                      |
| `403`  | Permissões insuficientes                             |
| `404`  | Conversa não encontrada                              |
| `500`  | Erro interno do servidor                             |

***

## 9. Boas Práticas

### Gerenciamento de Status

| Status     | Use Quando                                                                             |
| ---------- | -------------------------------------------------------------------------------------- |
| `open`     | Conversa ativa e requer atenção                                                        |
| `resolved` | Problema totalmente resolvido — conversa concluída                                     |
| `snoozed`  | Conversa precisa de acompanhamento posterior — reabre automaticamente em `snoozeUntil` |

**Dicas:**

* Use a **atualização de status em massa** para gerenciamento da fila ao final do dia
* Defina `snoozeUntil` para o próximo dia útil para conversas de baixa prioridade
* Resolva conversas prontamente para manter a fila limpa

### Filtragem e Pesquisa

* Combine filtros (ex: `status=open&channel=whatsapp&agentId=agent_123`) para resultados precisos
* Use `search` para busca por palavra-chave quando lembrar do conteúdo mas não do contato
* Exporte subconjuntos filtrados para necessidades específicas de relatório

### Avaliação de Respostas da IA

* Avalie as respostas da IA regularmente para melhorar o desempenho do modelo
* Forneça `feedback` escrito para avaliações negativas — isso ajuda a identificar padrões
* Foque em avaliar respostas onde a IA cometeu um erro factual ou não capturou a intenção

***

## 10. Troubleshooting

| Problema                                          | Causa Possível                                        | Solução                                                        |
| ------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| Conversa não aparece na lista                     | Filtro errado aplicado                                | Tente remover os filtros e buscar por contato ou palavra-chave |
| Atualização de status em massa falha parcialmente | Alguns IDs não pertencem à sua organização            | Verifique se todos os IDs de conversa estão corretos           |
| Exportação retorna arquivo vazio                  | Nenhuma conversa corresponde ao filtro de data/status | Amplie o intervalo de datas ou remova o filtro de status       |
| Não é possível excluir uma conversa               | Conversa vinculada a uma sessão ativa do widget       | Aguarde a sessão terminar ou contate o suporte                 |
| Avaliação de resposta rejeitada                   | `messageId` não é uma mensagem gerada por IA          | Apenas mensagens geradas por IA podem ser avaliadas            |