# Ler o histórico de mensagens

> Liste as conversas armazenadas e percorra as mensagens delas em números com armazenamento hospedado de mensagens.

> **Note**
>
> A API de histórico de mensagens está em beta. Em [Recursos opcionais](https://docs.polymorfa.com/teams/opt-in-features), um
> proprietário ou administrador da equipe seleciona o histórico de mensagens,
> depois **Participar**, revisa os termos e seleciona **Aceitar e
> participar**. Até a equipe participar e o beta ser oferecido a ela, toda
> solicitação de histórico retorna `403 permission_denied`.

A API de histórico de mensagens retorna as conversas e mensagens que a
Polymorfa armazenou para um número com armazenamento hospedado de mensagens
ativado. Use-a para preencher uma caixa de entrada com mensagens anteriores,
exibir uma conversa depois que a página recarrega ou conciliar o seu próprio
armazenamento com o que a Polymorfa reteve.

## Antes de começar

- **O armazenamento hospedado de mensagens está ativado para o número.** O
  histórico contém apenas mensagens recebidas ou enviadas depois que o
  armazenamento foi ativado. Para qualquer outro número, as solicitações de
  histórico retornam `404 hms_not_enabled`. Números de teste nunca têm
  histórico armazenado.
- **Sua equipe participa do beta.** Participe em [Recursos opcionais](https://docs.polymorfa.com/teams/opt-in-features)
  no Console. Sair do beta bloqueia novas leituras do histórico e
  não exclui as mensagens armazenadas.
- **Você faz as chamadas do seu servidor com uma chave da equipe ou um
  token de projeto.** Tokens de cliente são rejeitados com
  `403 permission_denied`.

| Método | Escopo |
| --- | --- |
| [List conversations](https://docs.polymorfa.com/api/chats/list-chats) `GET /messaging/{session}/chats` | `chats:read` |
| [Get a conversation](https://docs.polymorfa.com/api/chats/get-chat) `GET /messaging/{session}/chats/{conversation}` | `chats:read` |
| [List messages](https://docs.polymorfa.com/api/chats/list-chat-messages) `GET /messaging/{session}/chats/{conversation}/messages` | `messages:read` |
| [Get a message](https://docs.polymorfa.com/api/chats/get-chat-message) `GET /messaging/{session}/chats/{conversation}/messages/{messageId}` | `messages:read` |
| [Download stored message media](https://docs.polymorfa.com/api/chats/get-chat-message-media) `GET /messaging/{session}/chats/{conversation}/messages/{messageId}/media` | `messages:read` e `media:read` |

`messages:read` é um escopo novo. As credenciais criadas antes de ele existir,
incluindo as credenciais com acesso total, não o incluem. Crie uma credencial
que liste `messages:read` explicitamente.

## Listar conversas

As conversas são ordenadas pela atividade mais recente, da mais nova para a
mais antiga. Cada item traz a identidade da conversa, o tipo dela e um resumo
da última mensagem armazenada. O resumo não tem o corpo da mensagem; leia as
mensagens para obter o conteúdo.

```bash
curl "https://api.polymorfa.com/messaging/support-line/chats?limit=20&kind=direct" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"
```

```json
{
  "success": true,
  "data": [
    {
      "conversation": { "id": "739182640518203", "phoneNumber": "+15550001111" },
      "kind": "direct",
      "lastActivityAt": "2026-09-18T10:05:00.000Z",
      "lastMessage": {
        "id": "739182640518977",
        "whatsapp_ids": { "linked_devices": "3EB0C767D8A1A2B5" },
        "whatsapp_id": "3EB0C767D8A1A2B5",
        "direction": "inbound",
        "type": "text",
        "timestamp": "2026-09-18T10:05:00.000Z"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJz...",
  "previousCursor": null
}
```

| Parâmetro de consulta | Significado |
| --- | --- |
| `limit` | Tamanho da página, de 1 a 100. Padrão 50. |
| `cursor` | `nextCursor` da página anterior. |
| `kind` | `direct`, `group`, `channel` ou `broadcast`. |
| `activeSince` | Conversas com atividade nesse horário ISO 8601 ou depois dele. |
| `activeBefore` | Conversas cuja atividade mais recente é anterior a esse horário ISO 8601. |

Uma conversa só aparece enquanto pelo menos uma das mensagens dela estiver
retida. Uma conversa que recebe uma mensagem nova enquanto você percorre as
páginas vai para o topo da lista; ela não se repete nas páginas seguintes.

## Listar as mensagens de uma conversa

Selecione a conversa pelo `id` ou por um número de telefone E.164 (codifique o
`+` na URL como `%2B`). Por padrão, as mensagens vêm da mais nova para a mais
antiga.

```bash cURL
curl "https://api.polymorfa.com/messaging/support-line/chats/739182640518203/messages?limit=50&direction=inbound&types=text,image" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"
```

```typescript TypeScript
const page = await messaging.chats.listMessages("<number-id>", "+15550001111", {
  limit: 50,
  order: "desc",
});
for (const message of page.data.data) console.log(message.id, message.text);

if (page.data.hasMore && page.data.nextCursor) {
  const older = await messaging.chats.listMessages("<number-id>", "+15550001111", {
    cursor: page.data.nextCursor,
    order: "desc",
  });
  console.log(older.data.data.length);
}
```

*TypeScript:*

`chats.list` lista as conversas armazenadas, e `chats.downloadMessageMediaStream`
baixa a cópia armazenada da mídia de uma mensagem.

A resposta:

```json
{
  "success": true,
  "data": [
    {
      "id": "739182640518977",
      "whatsapp_ids": { "linked_devices": "3EB0C767D8A1A2B5" },
      "whatsapp_id": "3EB0C767D8A1A2B5",
      "conversation": { "id": "739182640518203", "phoneNumber": "+15550001111" },
      "direction": "inbound",
      "fromMe": false,
      "type": "image",
      "timestamp": "2026-09-18T10:05:00.000Z",
      "pushName": "Ana",
      "caption": "Receipt",
      "mimeType": "image/jpeg",
      "media": [
        {
          "id": "0e6f1c3a-5a55-4f3c-9d4f-0b1f8f2a9c11",
          "mimeType": "image/jpeg",
          "fileLength": 48213,
          "url": "/messaging/media/0e6f1c3a-5a55-4f3c-9d4f-0b1f8f2a9c11"
        }
      ]
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJz...",
  "previousCursor": null
}
```

| Parâmetro de consulta | Significado |
| --- | --- |
| `limit` | Tamanho da página, de 1 a 100. Padrão 50. |
| `cursor` | `nextCursor` ou `previousCursor` de uma página anterior. |
| `order` | `desc` (mais novas primeiro, padrão) ou `asc` (mais antigas primeiro). |
| `since` | Mensagens enviadas nesse horário ISO 8601 ou depois dele. |
| `until` | Mensagens enviadas antes desse horário ISO 8601. `since` precisa ser anterior. |
| `direction` | `inbound` (dos contatos) ou `outbound` (enviadas pelo número, inclusive pelos outros dispositivos vinculados dele). |
| `types` | Tipos de mensagem separados por vírgula, até 16, por exemplo `text,image`. |

O objeto `whatsapp_ids` guarda as referências do provedor que a Polymorfa
observou para a mensagem. Ele contém `linked_devices`, `official_api` ou os
dois. Use o `id` da Polymorfa para buscar uma mensagem ou enviar uma resposta.
O campo antigo `whatsapp_id` continua disponível temporariamente para as
integrações que ainda leem uma única referência.

Em um grupo, uma mensagem recebida inclui `conversation.sender`, o autor. Os
campos da mensagem são os mesmos de `message.received`: `text`, `caption`,
`mimeType`, `filename`, `ptt`, `latitude`, `longitude`, `displayName`,
`title`, `reaction`, `reactionTo`, `edited`, `unavailable`,
`unavailableReason` e `pollOptions` aparecem quando a mensagem armazenada os
tem. As mensagens enviadas pela API são armazenadas com o tipo e os
identificadores; o corpo delas não faz parte do registro armazenado.

## Paginação

Os cursores são opacos. Devolva-os sem alterações, com o mesmo caminho e os
mesmos filtros. Um cursor usado com outros filtros ou em outra conversa
retorna `400 invalid_parameter` com `param: "cursor"`; comece de novo sem
cursor.

- `nextCursor` continua na `order` atual. Ele é `null` na última página, e
  `hasMore` é `false`.
- `previousCursor` retorna a página anterior à atual. Ele é `null` na primeira
  página. Listas de conversas não têm cursor anterior.

```ts
let cursor: string | undefined;
do {
  const url = new URL("https://api.polymorfa.com/messaging/support-line/chats/739182640518203/messages");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  if (!response.ok) throw new Error(`history request failed: ${response.status}`);
  const page = await response.json();
  for (const message of page.data) store(message);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

## Mídia

O histórico nunca retorna chaves de mídia do WhatsApp, caminhos de download ou
URLs de armazenamento. Uma mensagem de imagem, vídeo, áudio, documento ou
figurinha tem um array `media`. Baixe os itens de mídia de Dispositivos
vinculados com [Download linked media](https://docs.polymorfa.com/api/media/download-linked-media)
usando uma credencial com `media:read`. O array fica vazio quando a Polymorfa
não tem uma referência desse arquivo que possa ser baixada.

O armazenamento hospedado de mensagens não guarda arquivos de anexo. Ele guarda
o tipo, a legenda e o tipo MIME de uma mensagem de mídia. Uma mensagem da API
oficial não tem cópia armazenada, então [Download stored message media](https://docs.polymorfa.com/api/chats/get-chat-message-media)
retorna `404 resource_not_found` para ela. Baixe cada arquivo quando o seu
webhook receber a mensagem, enquanto o WhatsApp ainda o disponibiliza, e mantenha
a cópia no seu próprio armazenamento.

## Retenção e região de dados

O histórico retorna apenas mensagens dentro do período de retenção do
armazenamento hospedado do número, ou sob preservação legal (legal hold).
Mensagens expiradas não são retornadas, e uma mensagem pode sumir entre duas
páginas quando o período de retenção dela termina.

Toda resposta bem-sucedida tem um cabeçalho `Polymorfa-Data-Region` com o nome
da região que armazenou e serviu o histórico. O histórico é lido apenas na
região do número.

## Erros

| Status | Código | Quando |
| --- | --- | --- |
| `400` | `invalid_parameter` | Um filtro é inválido, ou um cursor não corresponde à solicitação. |
| `403` | `missing_scope` | A credencial não tem `chats:read` ou `messages:read`, ou `media:read` para baixar mídia. |
| `403` | `permission_denied` | A solicitação usou um token de cliente, ou a equipe não está inscrita no beta. |
| `404` | `hms_not_enabled` | O armazenamento hospedado de mensagens está desativado para o número. |
| `404` | `resource_not_found` | O número, a conversa ou a mensagem não está disponível para a credencial, ou não existe uma cópia de mídia armazenada. |
| `503` | `service_unavailable` | O histórico da região do número está temporariamente indisponível. Tente novamente mais tarde. |

Consulte [Erros](https://docs.polymorfa.com/api/errors) para ver o formato completo dos erros.
