<!-- Fonte: https://developers.conectaai.io/referencia/conversas · conecta/ai Desenvolvedores -->
> Atendimentos e as mensagens trocadas neles, em todos os canais. Referência gerada do contrato da API.

# Conversas

{/* Gerado por scripts/gerar-referencia.mjs a partir de openapi/openapi.json. Não edite: rode `pnpm referencia`. */}

# Conversas

Atendimentos e as mensagens trocadas neles, em todos os canais.

| Operação | Endpoint |
|---|---|
| [Listar conversas](#listar-conversas) | `GET /conversations` |
| [Ler uma conversa](#ler-uma-conversa) | `GET /conversations/{id}` |
| [Listar mensagens de uma conversa](#listar-mensagens-de-uma-conversa) | `GET /conversations/{id}/messages` |

## Listar conversas

Lista as conversas da organização, da mais recente para a mais antiga (pela data de início). Use `updated_after` para sincronizar só o que mudou desde a última leitura.

Permissão exigida na chave: `conversas:read`.

### Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | inteiro | não | Quantos itens por página, de 1 a 100. Padrão 50. |
| `cursor` | texto | não | Valor de `next_cursor` da página anterior. Omita para a primeira página. |
| `status` | `open`, `pending`, `snoozed`, `resolved`, `closed` | não | Só conversas nesta situação. |
| `channel` | `whatsapp`, `voice`, `instagram`, `messenger`, `telegram`, `email`, `sms`, `webchat`, `app` | não | Só conversas deste canal. |
| `contact_id` | texto | não | Só conversas deste contato. |
| `created_after` | texto | não | Só conversas iniciadas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z. |
| `created_before` | texto | não | Só conversas iniciadas antes deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z. |
| `updated_after` | texto | não | Só conversas alteradas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z. |

### Resposta 200

Uma página de objetos [Conversation](#objeto-conversation) em `data`, e `next_cursor` para a próxima. Veja [Paginação](/paginacao).

### Erros

| Status | Quando |
|---|---|
| `400` | `invalid_parameter`: Parâmetro inválido. |
| `401` | `unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida. |
| `403` | `insufficient_scope`: Escopo insuficiente. |
| `429` | `rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After. |
| `500` | `internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id. |

O corpo segue o formato de [Erros](/erros).

### Exemplo

```bash
curl "https://app.conectaai.io/api/v1/conversations" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"
```

Resposta `200`:

```json
{
  "data": [
    {
      "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "contact_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "channel": "whatsapp",
      "channel_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "status": "open",
      "protocol": "20261109-0042",
      "origin": "inbound",
      "handled_by": "ai",
      "assigned_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "department_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "active_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "priority": 0,
      "tags": [
        "sem-conexao"
      ],
      "summary": "Cliente sem conexão desde a manhã. A IA verificou o contrato e abriu chamado técnico.",
      "created_at": "2026-11-09T14:32:05.120Z",
      "updated_at": "2026-11-09T14:32:05.120Z",
      "last_message_at": "2026-11-09T14:32:05.120Z",
      "first_response_at": "2026-11-09T14:32:05.120Z",
      "escalated_at": "2026-11-09T14:32:05.120Z",
      "resolved_at": "2026-11-09T14:32:05.120Z"
    }
  ],
  "next_cursor": null
}
```

## Ler uma conversa

Devolve uma conversa da organização pelo identificador.

Permissão exigida na chave: `conversas:read`.

### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | texto | sim | Identificador do recurso. |

### Resposta 200

Um objeto [Conversation](#objeto-conversation).

### Erros

| Status | Quando |
|---|---|
| `401` | `unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida. |
| `403` | `insufficient_scope`: Escopo insuficiente. |
| `404` | `not_found`: Recurso não encontrado. |
| `429` | `rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After. |
| `500` | `internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id. |

O corpo segue o formato de [Erros](/erros).

### Exemplo

```bash
curl "https://app.conectaai.io/api/v1/conversations/" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"
```

Resposta `200`:

```json
{
  "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "contact_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "channel": "whatsapp",
  "channel_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "status": "open",
  "protocol": "20261109-0042",
  "origin": "inbound",
  "handled_by": "ai",
  "assigned_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "department_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "active_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "priority": 0,
  "tags": [
    "sem-conexao"
  ],
  "summary": "Cliente sem conexão desde a manhã. A IA verificou o contrato e abriu chamado técnico.",
  "created_at": "2026-11-09T14:32:05.120Z",
  "updated_at": "2026-11-09T14:32:05.120Z",
  "last_message_at": "2026-11-09T14:32:05.120Z",
  "first_response_at": "2026-11-09T14:32:05.120Z",
  "escalated_at": "2026-11-09T14:32:05.120Z",
  "resolved_at": "2026-11-09T14:32:05.120Z"
}
```

## Listar mensagens de uma conversa

Lista as mensagens de uma conversa em ordem cronológica, da primeira para a última. Notas internas da equipe não aparecem.

Permissão exigida na chave: `conversas:read`.

### Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `id` | texto | sim | Identificador do recurso. |

### Parâmetros de consulta

| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `limit` | inteiro | não | Quantos itens por página, de 1 a 100. Padrão 50. |
| `cursor` | texto | não | Valor de `next_cursor` da página anterior. Omita para a primeira página. |

### Resposta 200

Uma página de objetos [Message](#objeto-message) em `data`, e `next_cursor` para a próxima. Veja [Paginação](/paginacao).

### Erros

| Status | Quando |
|---|---|
| `400` | `invalid_parameter`: Parâmetro inválido. |
| `401` | `unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida. |
| `403` | `insufficient_scope`: Escopo insuficiente. |
| `404` | `not_found`: Recurso não encontrado. |
| `429` | `rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After. |
| `500` | `internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id. |

O corpo segue o formato de [Erros](/erros).

### Exemplo

```bash
curl "https://app.conectaai.io/api/v1/conversations//messages" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"
```

Resposta `200`:

```json
{
  "data": [
    {
      "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "conversation_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "author_type": "customer",
      "author_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "author_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "text": null,
      "caption": null,
      "media": {
        "kind": "texto",
        "mime_type": "image/jpeg",
        "file_name": null,
        "duration_sec": 0
      },
      "status": "sending",
      "reply_to_message_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "deleted": false,
      "created_at": "2026-11-09T14:32:05.120Z"
    }
  ],
  "next_cursor": null
}
```

## Objeto Conversation

Um atendimento, do primeiro contato à resolução.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto | Identificador da conversa. |
| `contact_id` | texto | Contato com quem a conversa acontece. Leia em GET /contacts/{id}. |
| `channel` | `whatsapp`, `voice`, `instagram`, `messenger`, `telegram`, `email`, `sms`, `webchat`, `app` | Canal do atendimento: whatsapp, voice (telefone), instagram, messenger, telegram, email, sms, webchat (chat do site) ou app (app do assinante). |
| `channel_id` | texto ou `null` | Canal configurado em que a conversa entrou. |
| `status` | `open`, `pending`, `snoozed`, `resolved`, `closed` | open: em andamento. pending: aguardando o cliente. snoozed: adiada pela equipe. resolved: resolvida. closed: encerrada. |
| `protocol` | texto ou `null` | Número de protocolo mostrado ao cliente. |
| `origin` | `inbound`, `template`, `campaign` | inbound: o cliente iniciou. template: a equipe iniciou por modelo aprovado. campaign: veio de uma campanha. |
| `handled_by` | `ai`, `human`, `hybrid` | Quem conduz a conversa agora: ai (agente de IA), human (atendente) ou hybrid. |
| `assigned_user_id` | texto ou `null` | Atendente responsável, quando há. |
| `department_id` | texto ou `null` | Setor da conversa, quando há. |
| `active_agent_id` | texto ou `null` | Agente de IA que conduz a conversa, quando há. |
| `priority` | inteiro | Prioridade definida pela equipe. 0 é a padrão. |
| `tags` | lista de texto | Etiquetas aplicadas, pelo slug. A lista completa está em GET /tags. |
| `summary` | texto ou `null` | Resumo da conversa gerado pela IA, quando já existe. |
| `created_at` | texto | Quando a conversa começou. Data e hora em ISO 8601, UTC. |
| `updated_at` | texto | Última alteração da conversa. Data e hora em ISO 8601, UTC. |
| `last_message_at` | texto | Última mensagem trocada. Data e hora em ISO 8601, UTC. |
| `first_response_at` | texto ou `null` | Primeira resposta ao cliente, da IA ou de gente. Data e hora em ISO 8601, UTC. |
| `escalated_at` | texto ou `null` | Quando a conversa foi passada para atendimento humano. Data e hora em ISO 8601, UTC. |
| `resolved_at` | texto ou `null` | Quando a conversa foi resolvida. Data e hora em ISO 8601, UTC. |

## Objeto Message

Uma mensagem de uma conversa. Notas internas da equipe não aparecem.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto | Identificador da mensagem. |
| `conversation_id` | texto | Conversa da mensagem. |
| `author_type` | `customer`, `ai`, `human_agent`, `system`, `event` | customer: o cliente. ai: o agente de IA. human_agent: um atendente. system: aviso automático do sistema. event: registro de acontecimento (por exemplo, início de ligação). |
| `author_user_id` | texto ou `null` | Atendente que escreveu, quando author_type é human_agent. |
| `author_agent_id` | texto ou `null` | Agente de IA que escreveu, quando author_type é ai. |
| `text` | texto ou `null` | Texto da mensagem. Em áudio, a transcrição; em imagem ou documento, a descrição que o sistema registrou. null em mensagem apagada. |
| `caption` | texto ou `null` | Legenda que o cliente escreveu junto do anexo, quando há. |
| `media` | objeto ou `null` | Anexo da mensagem, sem link para o arquivo. null quando é só texto. |
| `media.kind` | texto | Tipo do anexo: image, video, audio, audio_voicenote, document, sticker, location, contact e outros. |
| `media.mime_type` | texto ou `null` | Tipo MIME do arquivo. |
| `media.file_name` | texto ou `null` | Nome do arquivo, quando informado. |
| `media.duration_sec` | inteiro ou `null` | Duração em segundos, para áudio e vídeo. |
| `status` | `sending`, `sent`, `delivered`, `read`, `failed` ou `null` | Situação de entrega das mensagens enviadas ao cliente. |
| `reply_to_message_id` | texto ou `null` | Mensagem respondida, quando é uma resposta. |
| `deleted` | booleano | A mensagem foi apagada. O texto não é devolvido. |
| `created_at` | texto | Quando a mensagem foi registrada. Data e hora em ISO 8601, UTC. |