Read message history

The message history API is a beta. A team owner or admin must enroll the team on the Numbers page. Until the team is enrolled and the beta is offered to it, every history request returns 403 permission_denied.

The message history API returns conversations and messages that Polymorfa stored for a Number with hosted message storage enabled. Use it to backfill an inbox, render a conversation after a page reload, or reconcile your own store with what Polymorfa retained.

Before you start

Hosted message storage is on for the Number. History contains only messages received or sent after storage was enabled. For any other Number, history requests return 404 hms_not_enabled. Test numbers never have stored history.
Your team is enrolled in the beta. Enrollment is on the Numbers page of the Console. Withdrawing blocks new history reads and does not delete stored messages.
You call from your server with an organization key or project token. Client tokens are rejected with 403 permission_denied.

Method	Scope
List conversations `GET /messaging/{session}/chats`	`chats:read`
Get a conversation `GET /messaging/{session}/chats/{conversation}`	`chats:read`
List messages `GET /messaging/{session}/chats/{conversation}/messages`	`messages:read`
Get a message `GET /messaging/{session}/chats/{conversation}/messages/{messageId}`	`messages:read`

messages:read is a new scope. Credentials created before it existed, including full-access credentials, do not include it. Create a credential that lists messages:read explicitly.

List conversations

Conversations are ordered by most recent activity, newest first. Each entry carries the conversation identity, its kind, and a summary of the latest stored message. The summary has no message body; read messages for content.

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

{
  "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
}

Query parameter	Meaning
`limit`	Page size, 1 to 100. Default 50.
`cursor`	`nextCursor` from the previous page.
`kind`	`direct`, `group`, `channel`, or `broadcast`.
`activeSince`	Conversations with activity at or after this ISO 8601 time.
`activeBefore`	Conversations whose latest activity is before this ISO 8601 time.

A conversation appears only while at least one of its messages is retained. A conversation that receives a new message while you page moves to the top of the list; it is not repeated on later pages.

List messages in a conversation

Select the conversation by its id or by an E.164 phone number (URL-encode the + as %2B). Messages are newest first by default.

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

{
  "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
}

Query parameter	Meaning
`limit`	Page size, 1 to 100. Default 50.
`cursor`	`nextCursor` or `previousCursor` from an earlier page.
`order`	`desc` (newest first, default) or `asc` (oldest first).
`since`	Messages sent at or after this ISO 8601 time.
`until`	Messages sent before this ISO 8601 time. `since` must be earlier.
`direction`	`inbound` (from contacts) or `outbound` (sent by the Number, including from its other linked devices).
`types`	Comma-separated message types, up to 16, for example `text,image`.

whatsapp_ids object holds the provider references that Polymorfa observed for the message. It contains linked_devices, official_api, or both. Use the Polymorfa id to fetch a message or send a reply. The older whatsapp_id field remains temporarily for integrations that still read one reference. In a group, an inbound message includes conversation.sender, the author. The message fields match message.received: text, caption, mimeType, filename, ptt, latitude, longitude, displayName, title, reaction, reactionTo, edited, unavailable, unavailableReason, and pollOptions appear when the stored message has them. Messages sent through the API are stored with their type and identifiers; their body is not part of the stored record.

Paginate

Cursors are opaque. Pass them back unchanged, with the same path and filters. A cursor used with different filters or a different conversation returns 400 invalid_parameter with param: "cursor"; start again without a cursor.

nextCursor continues in the current order. It is null on the last page, and hasMore is false.
previousCursor returns the page before the current one. It is null on the first page. Conversation lists do not have a previous cursor.

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);

Media

History never returns WhatsApp media keys, download paths, or storage URLs. An image, video, audio, document, or sticker message has a media array. Each entry names a file you can download with Download media using a credential with media:read. The array is empty when Polymorfa has no downloadable copy of that file.

Retention and data region

History returns only messages inside the Number’s hosted storage retention period, or under legal hold. Expired messages are not returned, and a message can disappear between two pages when its retention period ends. Every successful response has a Polymorfa-Data-Region header naming the region that stored and served the history. History is read only in the Number’s region.

Errors

Status	Code	When
`400`	`invalid_parameter`	A filter is invalid, or a cursor does not match the request.
`403`	`missing_scope`	The credential lacks `chats:read` or `messages:read`.
`403`	`permission_denied`	The request used a client token, or the team is not enrolled in the beta.
`404`	`hms_not_enabled`	Hosted message storage is off for the Number.
`404`	`resource_not_found`	The Number, conversation, or message is not available to the credential.
`503`	`service_unavailable`	History for the Number’s region is temporarily unavailable. Retry later.

See Errors for the full error format.

Get started

Tools and clients

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

Read message history

Before you start

List conversations

List messages in a conversation

Paginate

Media

Retention and data region

Errors

​Before you start

​List conversations

​List messages in a conversation

​Paginate

​Media

​Retention and data region

​Errors

Before you start

List conversations

List messages in a conversation

Paginate

Media

Retention and data region

Errors