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

# Conversa e histórico

> Consulte o estado de uma conversa e leia o histórico de mensagens e eventos

<Info>
  **Endpoint** · `GET /conversation` (detalhe) e `GET /conversation/messages` (histórico)
</Info>

<Note>
  Endpoints de **somente consulta**: retornam informação e não modificam nada. Não são enviados dentro do array `actions` — você os chama diretamente.
</Note>

São as duas leituras que dão contexto antes de operar sobre uma conversa. `GET /conversation` responde em que estado ela está (janela de 24h, caixa de entrada, funcionário AI, etiquetas) e quem é o contato; `GET /conversation/messages` responde o que foi dito, em que ordem e por quem. Com o primeiro você decide **qual ação é válida** (por exemplo, com a janela fechada só é possível enviar um template); com o segundo você redige a resposta com o histórico à vista.

Ambos identificam a conversa com a mesma referência que o resto da API, porém passada por **query params** em vez do corpo: exatamente um de `phone`, `username`, `whatsapp_user_id` ou `uuid`, mais `channel`.

## Detalhe da conversa

```http theme={null}
GET /conversation
```

**Parâmetros**

* `phone` — telefone no formato E.164. É normalizado para dígitos antes do lookup.
* `username` — username público de WhatsApp do contato. É normalizado (remove o `@` inicial, ignora maiúsculas).
* `whatsapp_user_id` — BSUID do contato (identidade opaca da Meta). Igualdade exata, sem normalizar.
* `uuid` — UUID interno do 1TO1 AI, se você já o tiver salvo.
* `channel` — chave pública do canal (**obrigatório** em toda requisição). Liste-as com `GET /channels`. Não diferencia maiúsculas de minúsculas. Fixa o canal objetivo; nos caminhos por contato restringe a resolução a esse canal, e com `uuid` o resolver o ignora, mas o contrato continua exigindo-o.

Exatamente **um** de `phone`, `username`, `whatsapp_user_id` ou `uuid` deve vir: zero ou dois identificadores respondem `400` (`INVALID_REQUEST`).

### Resposta

```json theme={null}
{
  "conversation_info": {
    "phone": "5215512345678",
    "window_open": true,
    "window_expires_at": "2026-07-21T18:30:00Z",
    "inbox_status": "pending",
    "is_tester": false,
    "mailbox": { "name": "Ventas" },
    "ai_employee": { "name": "Aura" },
    "tags": [{ "name": "VIP" }]
  },
  "contact_info": {
    "first_name": "Juan",
    "middle_name": "Carlos",
    "last_name": "Pérez",
    "second_last_name": "López",
    "full_name": "Juan Carlos Pérez López",
    "username": "juanp",
    "phone": "5215512345678",
    "whatsapp_user_id": "5215512345678"
  }
}
```

`window_open` é o campo que decide o que você pode enviar: se for `false`, a única mensagem permitida é um template aprovado. `window_expires_at` vem como `null` quando o contato nunca escreveu (a janela nunca foi aberta), e `inbox_status` é `pending` ou `resolved`. `mailbox` e `ai_employee` são `null` quando a conversa não tem caixa de entrada ou funcionário AI atribuído. `is_tester` marca se a conversa foi criada a partir do módulo de testes.

<Note>
  Em `contact_info`, `whatsapp_user_id` retorna o BSUID real quando ele existe, com fallback para o telefone enquanto a Meta não migrar. Se o valor recebido for o telefone, reenvie-o como `phone` e não como `whatsapp_user_id` — o resolver casa BSUIDs por igualdade exata e retornaria `404`.
</Note>

**Erros**

* `400` `INVALID_REQUEST` — a referência traz zero ou dois identificadores, ou falta `channel`.
* `404` `CONVERSATION_NOT_FOUND` — a conversa não existe ou pertence a outro negócio. `CHANNEL_NOT_FOUND` — a chave de canal não existe.
* `409` `PHONE_NUMBER_AMBIGUOUS` / `USERNAME_AMBIGUOUS` — vários contatos compartilham esse telefone ou esse username. Identifique por `whatsapp_user_id` ou `uuid`.

### Exemplo

Uma leitura pura: consulta o estado e não altera nada da conversa.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation?phone=5215512345678&channel=ch_7A9K2M4Q" \
  -H "Authorization: Bearer sk_1to1_sua_api_key"
```

Se a resposta trouxer `"window_open": false`, a ação correspondente é enviar um template; se trouxer `true`, você pode enviar texto, mídia ou uma resposta rápida.

## Histórico de mensagens e eventos

```http theme={null}
GET /conversation/messages
```

Retorna as mensagens e os eventos do histórico. É identificado com a mesma referência, então **não é preciso conhecer nenhum uuid**.

**Parâmetros**

* `phone` / `username` / `whatsapp_user_id` / `uuid` — a referência da conversa, com a mesma regra: exatamente um.
* `channel` — chave pública do canal (**obrigatório**).
* `cursor` — cursor opaco retornado pela página anterior em `next_cursor` (até 512 caracteres). Não reutilize cursores entre endpoints distintos.
* `limit` — itens por página. Padrão 50, máximo 100.

<Note>
  O histórico é paginado **para trás no tempo**: a primeira chamada traz os itens mais recentes e `next_cursor` avança em direção aos mais antigos. `has_more` em `true` significa que ainda restam itens **mais antigos** por ler. A ordem dentro da página é cronológica e não é configurável (não existe parâmetro `order`).
</Note>

### Resposta

```json theme={null}
{
  "items": [
    {
      "type": "message",
      "direction": "contact",
      "event": "message_received",
      "content_type": "text",
      "body": "Olá, o pacote premium está disponível?",
      "author": { "type": "customer", "name": "Ana Pérez" },
      "status": "delivered",
      "sent_at": "2026-07-02T14:39:00.000Z"
    },
    {
      "type": "message",
      "direction": "business",
      "event": "message_sent",
      "content_type": "text",
      "body": "Bom dia! Sim, o pacote premium está disponível.",
      "author": { "type": "ai_employee", "name": "Vendas noturnas" },
      "status": "read",
      "sent_at": "2026-07-02T14:39:12.000Z"
    },
    {
      "type": "event",
      "direction": "business",
      "event": "context_note",
      "content_type": null,
      "body": "O cliente pediu um orçamento formal por e-mail.",
      "author": { "type": "api_token", "name": "Integração CRM" },
      "status": null,
      "sent_at": "2026-07-02T15:02:00.000Z"
    }
  ],
  "next_cursor": "MjAyNi0wNy0wMlQxNDozOTowMC4wMDBafDkxODIz",
  "has_more": true
}
```

Cada item responde quatro perguntas: quem falou (`direction` e `author`), o que aconteceu (`event`), com qual conteúdo (`content_type` e `body`) e quando (`sent_at`).

* `type` — `message` ou `event`. Discrimina a união: os SDKs auto-gerados o expõem como tagged union.
* `direction` — `contact` (enviado pela pessoa do outro lado) ou `business` (saiu do seu negócio).
* `author.type` — `customer`, `human`, `ai_employee`, `api_token`, `mass_campaign` ou `system`. `author.name` pode ser `null`.
* `event` — nos itens `message`: `message_received` ou `message_sent`. Nos itens `event`: `context_note`, `contact_name_updated`, `contact_phone_updated`, `contact_email_updated`, `scheduled_cancel` ou `conversion`.
* `content_type` — nos itens `message`: `text`, `image`, `audio`, `video`, `document`, `location`, `sticker`, `contacts`, `template`, `interactive` ou `reaction`. Sempre `null` nos itens `event`.
* `status` — nos itens `message`: `pending`, `sent`, `delivered`, `read` ou `failed`. Sempre `null` nos itens `event`.
* `sent_at` — relógio de negócio do item e chave de ordenação do histórico. Sempre presente.

**Erros**

* `400` `INVALID_REQUEST` — referência inválida. `INVALID_CURSOR` — cursor corrompido ou não emitido por este endpoint.
* `404` `CONVERSATION_NOT_FOUND` / `CHANNEL_NOT_FOUND`.
* `409` `PHONE_NUMBER_AMBIGUOUS` / `USERNAME_AMBIGUOUS`.

### Exemplo

Também é uma leitura: percorrer o histórico completo não altera a conversa nem marca nada como lido.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages?phone=5215512345678&channel=ch_7A9K2M4Q&limit=50" \
  -H "Authorization: Bearer sk_1to1_sua_api_key"
```

Próxima página (itens mais antigos), com o `next_cursor` da resposta anterior:

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/conversation/messages?phone=5215512345678&channel=ch_7A9K2M4Q&cursor=MjAyNi0wNy0wMlQxNDozOTowMC4wMDBafDkxODIz" \
  -H "Authorization: Bearer sk_1to1_sua_api_key"
```

Com o estado e o histórico em mãos, a escrita passa pelas ações: [Enviar mensagem](/pt/action-groups/send-message) para responder e [Alterar estado da conversa](/pt/action-groups/conversation-status) para marcá-la como resolvida ou pendente. O contexto completo da referência e da janela de 24h está em [Conversas](/pt/conversations).