Pular para o conteúdo
Atalho: /, ⌘K ou Ctrl+K

Ler o histórico de mensagens

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

Ver em Markdown

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 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.

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.

Shell
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 consultaSignificado
limitTamanho da página, de 1 a 100. Padrão 50.
cursornextCursor da página anterior.
kinddirect, group, channel ou broadcast.
activeSinceConversas com atividade nesse horário ISO 8601 ou depois dele.
activeBeforeConversas 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.

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
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 consultaSignificado
limitTamanho da página, de 1 a 100. Padrão 50.
cursornextCursor ou previousCursor de uma página anterior.
orderdesc (mais novas primeiro, padrão) ou asc (mais antigas primeiro).
sinceMensagens enviadas nesse horário ISO 8601 ou depois dele.
untilMensagens enviadas antes desse horário ISO 8601. since precisa ser anterior.
directioninbound (dos contatos) ou outbound (enviadas pelo número, inclusive pelos outros dispositivos vinculados dele).
typesTipos 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.
TypeScript
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 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 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#

StatusCódigoQuando
400invalid_parameterUm filtro é inválido, ou um cursor não corresponde à solicitação.
403missing_scopeA credencial não tem chats:read ou messages:read, ou media:read para baixar mídia.
403permission_deniedA solicitação usou um token de cliente, ou a equipe não está inscrita no beta.
404hms_not_enabledO armazenamento hospedado de mensagens está desativado para o número.
404resource_not_foundO 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.
503service_unavailableO histórico da região do número está temporariamente indisponível. Tente novamente mais tarde.

Consulte Erros para ver o formato completo dos erros.