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`
Download stored message media `GET /messaging/{session}/chats/{conversation}/messages/{messageId}/media`	`messages:read` and `media: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. Download Linked Devices media entries with Download linked media using a credential with media:read. Download a stored Official API message’s media with Download stored message media using both messages:read and media:read. A stored-media ID is not a linked-media ID. The array is empty when Polymorfa has no downloadable copy of that file.

Official API media

WhatsApp keeps media from an Official API message for a limited time. When hosted message storage retains such a message, Polymorfa copies its media into the Number’s data region. The message then has a mediaRetrieval object. This applies to Numbers connected through the Official API only; on a Number that uses Hybrid Link, Official API media is not copied.

{
  "type": "image",
  "media": [
    {
      "id": "5f0c2a1e-9d3b-5c47-a1f2-6b8e4d7c9a10",
      "mimeType": "image/jpeg",
      "fileLength": 48213,
      "url": "/messaging/support-line/chats/739182640518203/messages/739182640518977/media"
    }
  ],
  "mediaRetrieval": { "state": "stored" }
}

`mediaRetrieval.state`	Meaning
`pending`	The copy is not stored yet. Polymorfa retries failed downloads with increasing delays.
`stored`	`media` lists the copy. Download it from its `url`.
`unavailable`	WhatsApp has no file for this message.
`expired`	The file was no longer downloadable, or the message’s retention ended first.
`too_large`	The file exceeds the size limit below.
`unsupported_type`	The file’s type does not match the message type.
`failed`	Every download attempt failed.
`cancelled`	Hosted message storage was turned off, its data region changed, or the Number’s Official API connection was removed before the copy was stored.

Every state except pending is final. A final state other than stored has a reason, for example provider_media_not_found or media_too_large; media is then empty. Polymorfa stores files up to 32 MiB, and never more than WhatsApp’s own limit for the media type: 5 MB for images, 500 KB for stickers, and 16 MB for audio and video. WhatsApp makes a file available for 7 days after it delivers the message, so a copy that is not stored within that time ends as expired. Download the copy with Download stored message media using a credential with both messages:read and media:read. The response body is the file itself, served as an attachment with its stored content type. The copy is deleted with the message when its retention period ends.

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`, or `media:read` for a media download.
`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, or no stored media copy exists.
`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

TypeScript SDK

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

Official API media

Retention and data region

Errors

​Before you start

​List conversations

​List messages in a conversation

​Paginate

​Media

​Official API media

​Retention and data region

​Errors

Before you start

List conversations

List messages in a conversation

Paginate

Media

Official API media

Retention and data region

Errors