# Histórico

> Conversas, contatos e mensagens gravados pelo Messajo: filtros, paginação por cursor e como a retenção limita o intervalo.

O Messajo guarda o que passa pelas conexões e deixa consultar pela API com a permissão `read`. Tudo respeita as conexões da chave: chave presa a algumas conexões só vê o que é delas.

## Rotas

| Rota | Filtros | Ordem |
|---|---|---|
| `GET /v1/conversations` | `connection_id`, `contact_id`, `window=open\|closed`, `since`, `until` (sobre `last_message_at`) | `last_message_at` mais recente primeiro |
| `GET /v1/conversations/{id}/messages` | `direction`, `type`, `since`, `until`, `order=desc\|asc` | `created_at` |
| `GET /v1/messages` | `connection_id`, `contact_id`, `conversation_id`, `direction`, `status`, `type`, `source`, `campaign_id`, `since`, `until`, `order` | `created_at` |
| `GET /v1/contacts` | `connection_id`, `channel`, `identity`, `q`, `since` | `last_seen_at` mais recente primeiro |

Cada uma tem a versão por id (`GET /v1/conversations/{id}`, `GET /v1/messages/{id}`, `GET /v1/contacts/{id}`). Datas em ISO 8601.

- `identity` busca exata por telefone (só dígitos), BSUID, @usuário do Instagram, IGSID ou PSID.
- `q` busca pelo começo do nome do contato (até 64 caracteres).
- `source` diz de onde veio a mensagem: `customer` (o contato), `api`, `campaign`, `business_app` (o app no celular, na coexistência) ou `history` (histórico importado); `campaign_id` traz só as mensagens de uma campanha.
- A mídia aparece como parte da mensagem, com `id`. O arquivo sai em `GET /v1/media/{id}/content`.

## Paginação por cursor

Toda lista devolve `{ data, next_cursor }`. Passe `limit` (até 100) e, para a próxima página, o `next_cursor` recebido em `cursor`. Acabou quando `next_cursor` vier `null`.

```bash
curl "https://api.messajo.com/v1/messages?conversation_id=cnv_...&limit=100" \
  -H "Authorization: Bearer $MESSAJO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "msg_...",
      "conversation_id": "cnv_...",
      "contact_id": "ctc_...",
      "direction": "inbound",
      "type": "text",
      "text": { "body": "Oi! Ainda tem o cupom?" },
      "source": "customer",
      "status": "received",
      "campaign": null,
      "created_at": "2026-11-10T14:03:11.000Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjpbIjIwMjYtMTEtMTBUMTQ6MDM6MTEuMDAwWiIsIm1zZ18uLi4iXX0"
}
```

- O cursor é opaco: não monte nem altere. Cursor quebrado → `400` [`invalid_cursor`](/errors#invalid_cursor).
- O cursor guarda a posição, não um retrato da lista: o que chegar depois não duplica nem pula itens já lidos.
- Use os mesmos filtros em todas as páginas.

Com o [SDK](/sdk/typescript/), o `paginate` segue o cursor sozinho:

```ts
for await (const message of messajo.paginate(messajo.messages.list, {
  conversation_id: "cnv_...",
})) {
  console.log(message.id);
}
```

## Intervalo e retenção

Mensagens são guardadas por mês. Toda consulta de mensagens tem um intervalo `since`/`until`:

- sem `since`, vale o início da [retenção](/operate/data-privacy/#retenção) da organização (90 dias por padrão); sem `until`, agora;
- um `since` mais antigo que a retenção é cortado no limite, sem erro: o que passou do prazo já foi apagado;
- intervalos curtos respondem mais rápido.

A retenção conta da **gravação** no Messajo. O histórico de 6 meses importado na coexistência é gravado no dia da importação e sai junto com o resto quando o prazo vence.
