# Chats

## Endpoints

- `GET /messaging/{session}/chats`: [List chats](https://docs.polymorfa.com/api/chats/list-chats)
- `GET /messaging/{session}/chats/{conversation}/messages`: [List chat messages](https://docs.polymorfa.com/api/chats/list-chat-messages)
- `GET /messaging/{session}/chats/{conversation}/messages/{messageId}`: [Get chat message](https://docs.polymorfa.com/api/chats/get-chat-message)
- `GET /messaging/{session}/chats/{conversation}`: [Get chat](https://docs.polymorfa.com/api/chats/get-chat)
- `GET /messaging/{session}/chats/{conversation}/messages/{messageId}/media`: [Get chat message media](https://docs.polymorfa.com/api/chats/get-chat-message-media)
- `POST /messaging/{session}/chats/{conversation}/archive`: [Archive chat](https://docs.polymorfa.com/api/chats/archive-chat)
- `POST /messaging/{session}/chats/{conversation}/unarchive`: [Unarchive chat](https://docs.polymorfa.com/api/chats/unarchive-chat)
- `PUT /messaging/{session}/chats/{conversation}/disappearing`: [Set chat disappearing timer](https://docs.polymorfa.com/api/chats/set-chat-disappearing-timer)
- `PUT /messaging/{session}/chats/{conversation}/messages/{messageId}`: [Edit message](https://docs.polymorfa.com/api/chats/edit-message)
- `DELETE /messaging/{session}/chats/{conversation}/messages/{messageId}`: [Delete message](https://docs.polymorfa.com/api/chats/delete-message)

## The chat object

### Attributes

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
  - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
  - `username` (string, length 1–256). WhatsApp username when one is available.
- `kind` (string, required). Kind discriminator for this object. Values: `direct`, `group`, `channel`, `broadcast`.
- `lastActivityAt` (string (date-time), required, format date-time). Timestamp for last activity at.
- `lastMessage` (object, required). Specifies last message for this native history chat.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
    - One of:
      - `linked_devices` (object).
        - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, length 1–512). Specifies official api for this any of.
      - `official_api` (object).
        - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, required, length 1–512). Specifies official api for this any of.
  - `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
  - `direction` (string, required). Specifies direction for this native history message summary. Values: `inbound`, `outbound`.
  - `type` (string, required). Type discriminator for this object.
  - `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.
```json
{
  "conversation": {
    "id": "739182640518203",
    "phoneNumber": "string",
    "bsuid": "string",
    "username": "string"
  },
  "kind": "direct",
  "lastActivityAt": "2026-09-22T12:00:00Z",
  "lastMessage": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string",
      "official_api": "string"
    },
    "whatsapp_id": "string",
    "direction": "inbound",
    "type": "string",
    "timestamp": "2026-09-22T12:00:00Z"
  }
}
```

## The message object

### Attributes

- `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
- `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
  - One of:
    - `linked_devices` (object).
      - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
      - `official_api` (string, length 1–512). Specifies official api for this any of.
    - `official_api` (object).
      - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
      - `official_api` (string, required, length 1–512). Specifies official api for this any of.
- `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
  - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
  - `username` (string, length 1–256). WhatsApp username when one is available.
  - `sender` (object). Stable identifier for the user who sent the message or event.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
    - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
    - `username` (string, length 1–256). WhatsApp username when one is available.
- `direction` (string, required). Specifies direction for this native history message. Values: `inbound`, `outbound`.
- `fromMe` (boolean, required). True when the Number sent the message, including from another linked device.
- `type` (string, required). Message type as delivered in `message.received`, for example `text` or `image`.
- `timestamp` (string (date-time), required, format date-time). When WhatsApp reported the message.
- `pushName` (string). WhatsApp display name reported by the sender's client.
- `text` (string). Text content carried by this object.
- `caption` (string). Caption shown with the attached media.
- `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
- `filename` (string). Filename presented for the media attachment.
- `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
- `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
- `origin` (string). Specifies origin for this native history message. Values: `avatar`, `ai`.
- `emojis` (array of string). Emojis associated with this native history message.
- `accessibilityLabel` (string). Specifies accessibility label for this native history message.
- `stickerPack` (object). Specifies sticker pack for this native history message.
  - `id` (string, required). Identifier for this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `publisher` (string, required). Specifies publisher for this native sticker pack metadata.
  - `description` (string). Human-readable description of this resource.
  - `trayIconFileName` (string). Human-readable tray icon file name for this native sticker pack metadata.
  - `items` (array of object, required). Items associated with this native sticker pack metadata.
    - `fileName` (string, required). Human-readable file name for this native sticker pack item.
    - `stickerType` (string, required). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
    - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). IANA media type that matches the media payload.
    - `emojis` (array of string). Emojis associated with this native sticker pack item.
    - `accessibilityLabel` (string). Specifies accessibility label for this native sticker pack item.
    - `premium` (integer). Specifies premium for this native sticker pack item.
- `latitude` (number). Latitude in decimal degrees.
- `longitude` (number). Longitude in decimal degrees.
- `displayName` (string). Human-readable display name.
- `title` (string). Human-readable title shown to the recipient or operator.
- `reaction` (string). Reaction applied to the referenced message.
- `reactionTo` (string, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
- `edited` (boolean). Whether the event represents an edited message.
- `unavailable` (boolean). Whether the content is unavailable.
- `unavailableReason` (string). Reason the content is unavailable.
- `pollOptions` (array of object). Options recipients can choose in the poll.
  - `name` (string, required). Human-readable name for this resource.
  - `hash` (string, required). Specifies hash for this poll option.
- `order` (object). Specifies order for this native history message.
  - `catalogId` (string, required, pattern ^[0-9]{1,32}$). Meta catalog ID the cart was built from.
  - `text` (string, length 1–4096). Text the contact sent with the order.
  - `items` (array of object, required, items 1–1000). Items associated with this native cloud order.
    - `productRetailerId` (string, required, length 1–256). Your retailer ID (SKU), at most 256 UTF-8 bytes with no control characters.
    - `quantity` (integer, required, greater than 0). Units ordered.
    - `itemPrice` (number, required, min 0). Unit price as Meta reported it. Polymorfa does not convert or recompute it.
    - `currency` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code Meta reported for the item.
- `media` (array of object). Downloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available.
  - `id` (string, required). Media ID. Download the bytes from `url` with a credential that has `media:read`.
  - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
  - `fileLength` (integer, required, min 0). Size of the media file in bytes.
  - `url` (string, required). Path of the media download method.
- `mediaRetrieval` (object). Specifies media retrieval for this native history message.
  - `state` (string, required). `pending`: the copy is not stored yet. `stored`: `media` lists the copy. Every other state is final and no copy will be stored. Values: `pending`, `stored`, `unavailable`, `expired`, `too_large`, `unsupported_type`, `failed`, `cancelled`.
  - `reason` (string). Why a final state other than `stored` was reached, for example `provider_media_not_found` or `media_too_large`.
```json
{
  "id": "739182640518203",
  "whatsapp_ids": {
    "linked_devices": "string",
    "official_api": "string"
  },
  "whatsapp_id": "string",
  "conversation": {
    "id": "739182640518203",
    "phoneNumber": "string",
    "bsuid": "string",
    "username": "string",
    "sender": {
      "id": "739182640518203",
      "phoneNumber": "string",
      "bsuid": "string",
      "username": "string"
    }
  },
  "direction": "inbound",
  "fromMe": true,
  "type": "string",
  "timestamp": "2026-09-22T12:00:00Z",
  "pushName": "string",
  "text": "string",
  "caption": "string",
  "mimeType": "string",
  "filename": "string",
  "ptt": true,
  "stickerType": "static",
  "origin": "avatar",
  "emojis": [
    "string"
  ],
  "accessibilityLabel": "string",
  "stickerPack": {
    "id": "string",
    "name": "string",
    "publisher": "string",
    "description": "string",
    "trayIconFileName": "string",
    "items": [
      {
        "fileName": "string",
        "stickerType": "static",
        "mimeType": "string",
        "emojis": [
          "string"
        ],
        "accessibilityLabel": "string",
        "premium": 0
      }
    ]
  },
  "latitude": 0,
  "longitude": 0,
  "displayName": "string",
  "title": "string",
  "reaction": "string",
  "reactionTo": "739182640518203",
  "edited": true,
  "unavailable": true,
  "unavailableReason": "string",
  "pollOptions": [
    {
      "name": "string",
      "hash": "string"
    }
  ],
  "order": {
    "catalogId": "string",
    "text": "string",
    "items": [
      {
        "productRetailerId": "string",
        "quantity": 0,
        "itemPrice": 0,
        "currency": "string"
      }
    ]
  },
  "media": [
    {
      "id": "string",
      "mimeType": "string",
      "fileLength": 0,
      "url": "/messaging/media/0e6f1c3a-5a55-4f3c-9d4f-0b1f8f2a9c11"
    }
  ],
  "mediaRetrieval": {
    "state": "pending",
    "reason": "provider_media_expired"
  }
}
```

## List chats

`GET https://api.polymorfa.com/messaging/{session}/chats` (Messaging API)

Required permission: `chats:read`

**Protocols:** Linked Device API

**Required scope:** `chats:read`

Lists conversations with stored messages for a Number with hosted message storage, most recent activity first. Beta: requires team enrollment.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.

### Query parameters

- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `50`.
- `cursor` (string, length 1–1024, pattern ^[A-Za-z0-9_-]+$). Specifies cursor for this query parameter.
- `kind` (string). Kind discriminator for this object. Values: `direct`, `group`, `channel`, `broadcast`.
- `activeSince` (string (date-time), format date-time). Specifies active since for this query parameter.
- `activeBefore` (string (date-time), format date-time). Specifies active before for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/chats" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

One page of conversations
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `conversation` (object, required). Public conversation identifier or E.164 phone number.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
    - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
    - `username` (string, length 1–256). WhatsApp username when one is available.
  - `kind` (string, required). Kind discriminator for this object. Values: `direct`, `group`, `channel`, `broadcast`.
  - `lastActivityAt` (string (date-time), required, format date-time). Timestamp for last activity at.
  - `lastMessage` (object, required). Specifies last message for this native history chat.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
      - One of:
        - `linked_devices` (object).
          - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
          - `official_api` (string, length 1–512). Specifies official api for this any of.
        - `official_api` (object).
          - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
          - `official_api` (string, required, length 1–512). Specifies official api for this any of.
    - `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
    - `direction` (string, required). Specifies direction for this native history message summary. Values: `inbound`, `outbound`.
    - `type` (string, required). Type discriminator for this object.
    - `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.
- `hasMore` (boolean, required). True when `nextCursor` returns more items.
- `nextCursor` (string, required, nullable). Specifies next cursor for this native list chats response.
- `previousCursor` (string, required, nullable). Always null for conversations. Use nextCursor to continue listing.

Headers:

- `Polymorfa-Data-Region` (string). Data region that served the stored history.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "conversation": {
        "id": "739182640518203"
      },
      "kind": "direct",
      "lastActivityAt": "2026-09-22T12:00:00Z",
      "lastMessage": {
        "id": "739182640518203",
        "whatsapp_ids": {
          "linked_devices": "string"
        },
        "direction": "inbound",
        "type": "string",
        "timestamp": "2026-09-22T12:00:00Z"
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "string",
  "previousCursor": "string"
}
```

#### 400

A filter or cursor is invalid.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

The credential is missing or invalid.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The history service for the Number's data region is unavailable.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## List chat messages

`GET https://api.polymorfa.com/messaging/{session}/chats/{conversation}/messages` (Messaging API)

Required permission: `messages:read`

**Protocols:** Linked Device API

**Required scope:** `messages:read`

Lists stored messages in one conversation, newest first by default. Page in either direction with `nextCursor` and `previousCursor`. Beta: requires team enrollment.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.

### Query parameters

- `limit` (integer, range 1–100). Specifies limit for this query parameter. Default: `50`.
- `cursor` (string, length 1–1024, pattern ^[A-Za-z0-9_-]+$). Specifies cursor for this query parameter.
- `order` (string). Specifies order for this query parameter. Values: `desc`, `asc`. Default: `"desc"`.
- `since` (string (date-time), format date-time). Specifies since for this query parameter.
- `until` (string (date-time), format date-time). Specifies until for this query parameter.
- `direction` (string). Specifies direction for this query parameter. Values: `inbound`, `outbound`.
- `types` (string, pattern ^[a-z][a-z_]{0,31}(?:,[a-z][a-z_]{0,31}){0,15}$). Specifies types for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

One page of messages
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
    - One of:
      - `linked_devices` (object).
        - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, length 1–512). Specifies official api for this any of.
      - `official_api` (object).
        - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, required, length 1–512). Specifies official api for this any of.
  - `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
  - `conversation` (object, required). Public conversation identifier or E.164 phone number.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
    - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
    - `username` (string, length 1–256). WhatsApp username when one is available.
    - `sender` (object). Stable identifier for the user who sent the message or event.
      - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
      - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
      - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
      - `username` (string, length 1–256). WhatsApp username when one is available.
  - `direction` (string, required). Specifies direction for this native history message. Values: `inbound`, `outbound`.
  - `fromMe` (boolean, required). True when the Number sent the message, including from another linked device.
  - `type` (string, required). Message type as delivered in `message.received`, for example `text` or `image`.
  - `timestamp` (string (date-time), required, format date-time). When WhatsApp reported the message.
  - `pushName` (string). WhatsApp display name reported by the sender's client.
  - `text` (string). Text content carried by this object.
  - `caption` (string). Caption shown with the attached media.
  - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
  - `filename` (string). Filename presented for the media attachment.
  - `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
  - `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
  - `origin` (string). Specifies origin for this native history message. Values: `avatar`, `ai`.
  - `emojis` (array of string). Emojis associated with this native history message.
  - `accessibilityLabel` (string). Specifies accessibility label for this native history message.
  - `stickerPack` (object). Specifies sticker pack for this native history message.
    - `id` (string, required). Identifier for this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `publisher` (string, required). Specifies publisher for this native sticker pack metadata.
    - `description` (string). Human-readable description of this resource.
    - `trayIconFileName` (string). Human-readable tray icon file name for this native sticker pack metadata.
    - `items` (array of object, required). Items associated with this native sticker pack metadata.
      - `fileName` (string, required). Human-readable file name for this native sticker pack item.
      - `stickerType` (string, required). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
      - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). IANA media type that matches the media payload.
      - `emojis` (array of string). Emojis associated with this native sticker pack item.
      - `accessibilityLabel` (string). Specifies accessibility label for this native sticker pack item.
      - `premium` (integer). Specifies premium for this native sticker pack item.
  - `latitude` (number). Latitude in decimal degrees.
  - `longitude` (number). Longitude in decimal degrees.
  - `displayName` (string). Human-readable display name.
  - `title` (string). Human-readable title shown to the recipient or operator.
  - `reaction` (string). Reaction applied to the referenced message.
  - `reactionTo` (string, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `edited` (boolean). Whether the event represents an edited message.
  - `unavailable` (boolean). Whether the content is unavailable.
  - `unavailableReason` (string). Reason the content is unavailable.
  - `pollOptions` (array of object). Options recipients can choose in the poll.
    - `name` (string, required). Human-readable name for this resource.
    - `hash` (string, required). Specifies hash for this poll option.
  - `order` (object). Specifies order for this native history message.
    - `catalogId` (string, required, pattern ^[0-9]{1,32}$). Meta catalog ID the cart was built from.
    - `text` (string, length 1–4096). Text the contact sent with the order.
    - `items` (array of object, required, items 1–1000). Items associated with this native cloud order.
      - `productRetailerId` (string, required, length 1–256). Your retailer ID (SKU), at most 256 UTF-8 bytes with no control characters.
      - `quantity` (integer, required, greater than 0). Units ordered.
      - `itemPrice` (number, required, min 0). Unit price as Meta reported it. Polymorfa does not convert or recompute it.
      - `currency` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code Meta reported for the item.
  - `media` (array of object). Downloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available.
    - `id` (string, required). Media ID. Download the bytes from `url` with a credential that has `media:read`.
    - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
    - `fileLength` (integer, required, min 0). Size of the media file in bytes.
    - `url` (string, required). Path of the media download method.
  - `mediaRetrieval` (object). Specifies media retrieval for this native history message.
    - `state` (string, required). `pending`: the copy is not stored yet. `stored`: `media` lists the copy. Every other state is final and no copy will be stored. Values: `pending`, `stored`, `unavailable`, `expired`, `too_large`, `unsupported_type`, `failed`, `cancelled`.
    - `reason` (string). Why a final state other than `stored` was reached, for example `provider_media_not_found` or `media_too_large`.
- `hasMore` (boolean, required). True when `nextCursor` returns more items.
- `nextCursor` (string, required, nullable). Specifies next cursor for this native list chat messages response.
- `previousCursor` (string, required, nullable). Cursor for the preceding page of messages. Null when no preceding page exists.

Headers:

- `Polymorfa-Data-Region` (string). Data region that served the stored history.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "conversation": {
        "id": "739182640518203"
      },
      "direction": "inbound",
      "fromMe": true,
      "type": "string",
      "timestamp": "2026-09-22T12:00:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "string",
  "previousCursor": "string"
}
```

#### 400

A filter or cursor is invalid.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

The credential is missing or invalid.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The history service for the Number's data region is unavailable.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Get chat message

`GET https://api.polymorfa.com/messaging/{session}/chats/{conversation}/messages/{messageId}` (Messaging API)

Required permission: `messages:read`

**Protocols:** Linked Device API

**Required scope:** `messages:read`

Returns one stored message. Beta: requires team enrollment.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.
- `messageId` (string, required, pattern ^[1-9][0-9]{0,18}$). Polymorfa message ID. Use the Polymorfa message's `id` for actions and replies.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The message
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
    - One of:
      - `linked_devices` (object).
        - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, length 1–512). Specifies official api for this any of.
      - `official_api` (object).
        - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
        - `official_api` (string, required, length 1–512). Specifies official api for this any of.
  - `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
  - `conversation` (object, required). Public conversation identifier or E.164 phone number.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
    - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
    - `username` (string, length 1–256). WhatsApp username when one is available.
    - `sender` (object). Stable identifier for the user who sent the message or event.
      - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
      - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
      - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
      - `username` (string, length 1–256). WhatsApp username when one is available.
  - `direction` (string, required). Specifies direction for this native history message. Values: `inbound`, `outbound`.
  - `fromMe` (boolean, required). True when the Number sent the message, including from another linked device.
  - `type` (string, required). Message type as delivered in `message.received`, for example `text` or `image`.
  - `timestamp` (string (date-time), required, format date-time). When WhatsApp reported the message.
  - `pushName` (string). WhatsApp display name reported by the sender's client.
  - `text` (string). Text content carried by this object.
  - `caption` (string). Caption shown with the attached media.
  - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
  - `filename` (string). Filename presented for the media attachment.
  - `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
  - `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
  - `origin` (string). Specifies origin for this native history message. Values: `avatar`, `ai`.
  - `emojis` (array of string). Emojis associated with this native history message.
  - `accessibilityLabel` (string). Specifies accessibility label for this native history message.
  - `stickerPack` (object). Specifies sticker pack for this native history message.
    - `id` (string, required). Identifier for this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `publisher` (string, required). Specifies publisher for this native sticker pack metadata.
    - `description` (string). Human-readable description of this resource.
    - `trayIconFileName` (string). Human-readable tray icon file name for this native sticker pack metadata.
    - `items` (array of object, required). Items associated with this native sticker pack metadata.
      - `fileName` (string, required). Human-readable file name for this native sticker pack item.
      - `stickerType` (string, required). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
      - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). IANA media type that matches the media payload.
      - `emojis` (array of string). Emojis associated with this native sticker pack item.
      - `accessibilityLabel` (string). Specifies accessibility label for this native sticker pack item.
      - `premium` (integer). Specifies premium for this native sticker pack item.
  - `latitude` (number). Latitude in decimal degrees.
  - `longitude` (number). Longitude in decimal degrees.
  - `displayName` (string). Human-readable display name.
  - `title` (string). Human-readable title shown to the recipient or operator.
  - `reaction` (string). Reaction applied to the referenced message.
  - `reactionTo` (string, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `edited` (boolean). Whether the event represents an edited message.
  - `unavailable` (boolean). Whether the content is unavailable.
  - `unavailableReason` (string). Reason the content is unavailable.
  - `pollOptions` (array of object). Options recipients can choose in the poll.
    - `name` (string, required). Human-readable name for this resource.
    - `hash` (string, required). Specifies hash for this poll option.
  - `order` (object). Specifies order for this native history message.
    - `catalogId` (string, required, pattern ^[0-9]{1,32}$). Meta catalog ID the cart was built from.
    - `text` (string, length 1–4096). Text the contact sent with the order.
    - `items` (array of object, required, items 1–1000). Items associated with this native cloud order.
      - `productRetailerId` (string, required, length 1–256). Your retailer ID (SKU), at most 256 UTF-8 bytes with no control characters.
      - `quantity` (integer, required, greater than 0). Units ordered.
      - `itemPrice` (number, required, min 0). Unit price as Meta reported it. Polymorfa does not convert or recompute it.
      - `currency` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code Meta reported for the item.
  - `media` (array of object). Downloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available.
    - `id` (string, required). Media ID. Download the bytes from `url` with a credential that has `media:read`.
    - `mimeType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `video/mp4`, `audio/ogg`, or `application/pdf`). IANA media type that matches the media payload.
    - `fileLength` (integer, required, min 0). Size of the media file in bytes.
    - `url` (string, required). Path of the media download method.
  - `mediaRetrieval` (object). Specifies media retrieval for this native history message.
    - `state` (string, required). `pending`: the copy is not stored yet. `stored`: `media` lists the copy. Every other state is final and no copy will be stored. Values: `pending`, `stored`, `unavailable`, `expired`, `too_large`, `unsupported_type`, `failed`, `cancelled`.
    - `reason` (string). Why a final state other than `stored` was reached, for example `provider_media_not_found` or `media_too_large`.

Headers:

- `Polymorfa-Data-Region` (string). Data region that served the stored history.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string"
    },
    "conversation": {
      "id": "739182640518203"
    },
    "direction": "inbound",
    "fromMe": true,
    "type": "string",
    "timestamp": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

A filter or cursor is invalid.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

The credential is missing or invalid.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The history service for the Number's data region is unavailable.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Get chat

`GET https://api.polymorfa.com/messaging/{session}/chats/{conversation}` (Messaging API)

Required permission: `chats:read`

**Protocols:** Linked Device API

**Required scope:** `chats:read`

Returns one conversation with stored messages. Beta: requires team enrollment.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The conversation
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `conversation` (object, required). Public conversation identifier or E.164 phone number.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `phoneNumber` (string, pattern ^\+[1-9]\d{1,14}$). Phone number reported by WhatsApp, when available. It can differ from the number supplied for lookup. Use id for later actions and replies.
    - `bsuid` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). Business-scoped user identifier (BSUID), scoped to the owning business portfolio.
    - `username` (string, length 1–256). WhatsApp username when one is available.
  - `kind` (string, required). Kind discriminator for this object. Values: `direct`, `group`, `channel`, `broadcast`.
  - `lastActivityAt` (string (date-time), required, format date-time). Timestamp for last activity at.
  - `lastMessage` (object, required). Specifies last message for this native history chat.
    - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
    - `whatsapp_ids` (object, required). Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
      - One of:
        - `linked_devices` (object).
          - `linked_devices` (string, required, length 1–512). Specifies linked devices for this any of.
          - `official_api` (string, length 1–512). Specifies official api for this any of.
        - `official_api` (object).
          - `linked_devices` (string, length 1–512). Specifies linked devices for this any of.
          - `official_api` (string, required, length 1–512). Specifies official api for this any of.
    - `whatsapp_id` (string, deprecated, length 1–512). Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
    - `direction` (string, required). Specifies direction for this native history message summary. Values: `inbound`, `outbound`.
    - `type` (string, required). Type discriminator for this object.
    - `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.

Headers:

- `Polymorfa-Data-Region` (string). Data region that served the stored history.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "conversation": {
      "id": "739182640518203"
    },
    "kind": "direct",
    "lastActivityAt": "2026-09-22T12:00:00Z",
    "lastMessage": {
      "id": "739182640518203",
      "whatsapp_ids": {
        "linked_devices": "string"
      },
      "direction": "inbound",
      "type": "string",
      "timestamp": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

A filter or cursor is invalid.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

The credential is missing or invalid.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The history service for the Number's data region is unavailable.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Get chat message media

`GET https://api.polymorfa.com/messaging/{session}/chats/{conversation}/messages/{messageId}/media` (Messaging API)

**Protocols:** Meta Cloud API

**Required scopes (all):** `messages:read` · `media:read`

Returns the stored copy of an Official API message's media when `mediaRetrieval.state` is `stored`. Requires `messages:read` and `media:read`, or a client token with the `conversations_read` action. Beta: requires team enrollment.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.
- `messageId` (string, required, pattern ^[1-9][0-9]{0,18}$). Polymorfa message ID. Use the Polymorfa message's `id` for actions and replies.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>/media" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The media bytes, with the stored content type

Content type: `*/*`

Headers:

- `Polymorfa-Data-Region` (string). Data region that served the stored history.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

#### 400

A filter or cursor is invalid.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

The credential is missing or invalid.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The Number, conversation or message is unavailable, no stored copy exists, or hosted message storage is not enabled (`hms_not_enabled`).
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The history service for the Number's data region is unavailable.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Archive chat

`POST https://api.polymorfa.com/messaging/{session}/chats/{conversation}/archive` (Messaging API)

Required permission: `chats:manage`

**Protocols:** Linked Device API

**Required scope:** `chats:manage`

### Path parameters

- `session` (string, required). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/archive" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Chat archived
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Unarchive chat

`POST https://api.polymorfa.com/messaging/{session}/chats/{conversation}/unarchive` (Messaging API)

Required permission: `chats:manage`

**Protocols:** Linked Device API

**Required scope:** `chats:manage`

### Path parameters

- `session` (string, required). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/unarchive" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Chat unarchived
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Set chat disappearing timer

`PUT https://api.polymorfa.com/messaging/{session}/chats/{conversation}/disappearing` (Messaging API)

Required permission: `chats:manage`

**Protocols:** Linked Device API

**Required scope:** `chats:manage`

### Path parameters

- `session` (string, required). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.

### Body

- `durationSeconds` (number, required). Duration in seconds.
  - Accepts one of:
    - number, `0`
    - number, `86400`
    - number, `604800`
    - number, `7776000`

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/disappearing" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "durationSeconds": 0
}'
```

### Responses

#### 200

Disappearing-message timer updated
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Edit message

`PUT https://api.polymorfa.com/messaging/{session}/chats/{conversation}/messages/{messageId}` (Messaging API)

Required permission: `chats:manage`

**Protocols:** Linked Device API

**Required scope:** `chats:manage`

### Path parameters

- `session` (string, required). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.
- `messageId` (string, required, pattern ^[1-9][0-9]{0,18}$). Polymorfa message ID. Use the Polymorfa message's `id` for actions and replies.

### Header parameters

- `Idempotency-Key` (string, length 1–255). Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 1 hour. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again while its receipt is retained. Keep the first response. Exact response replay requires authorized replay data; opaque message or campaign bodies are not retained by default. An available exact replay carries `Idempotent-Replayed: true`. Authorization, rate-limit and state refusals (401, 403, 408, 409, 423, 425, 429) are not recorded, so the same key can retry them. Reusing the key for a different request returns `422 idempotency_conflict`. A retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`. If the recorded response cannot be read, the retry returns `503 idempotency_replay_unavailable` with `Retry-After` and the write still does not run again.

### Body

- `text` (string, required, min length 1). Text content carried by this object.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string"
}'
```

### Responses

#### 200

Message edited
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `Idempotent-Replayed` (string). `true` when this response is the recorded response of an earlier request with the same Idempotency-Key. Values: `true`.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The Idempotency-Key belongs to a request that is still running (`idempotency_in_progress`, with Retry-After) or whose outcome was not recorded (`idempotency_outcome_unknown`)
Same fields as 400.

Headers:

- `Retry-After` (integer, min 0). Seconds to wait before checking again with the same key. Waiting does not release the execution fence or guarantee that replay data becomes available. Same-key retries are protected only within the one-hour receipt window.
- `Link` (string). Link to the documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this Idempotency-Key is still in progress. Check again after Retry-After with the same key within the documented receipt window. Exact response data may be unavailable.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-in-progress"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`)
Same fields as 400.

Headers:

- `Link`: described under 409.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

For `idempotency_replay_unavailable` only: the exact response for this Idempotency-Key is unavailable (with Retry-After). Opaque responses are not retained by default. The write did not run again. Keep the first response and reconcile events or the resource; waiting does not guarantee that replay data becomes available. Do not switch keys to resend
Same fields as 400.

Headers:

- `Retry-After`: described under 409.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "idempotency_replay_unavailable",
    "message": "The exact response for this Idempotency-Key is unavailable. The request was not repeated. Keep the first response and reconcile events or the resource. Waiting does not guarantee replay data becomes available; do not switch keys to resend.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-replay-unavailable"
}
```

## Delete message

`DELETE https://api.polymorfa.com/messaging/{session}/chats/{conversation}/messages/{messageId}` (Messaging API)

Required permission: `chats:manage`

**Protocols:** Linked Device API

**Required scope:** `chats:manage`

### Path parameters

- `session` (string, required). Identifier of the connected Polymorfa session.
- `conversation` (string, required). Public conversation identifier or E.164 phone number.
- `messageId` (string, required, pattern ^[1-9][0-9]{0,18}$). Polymorfa message ID. Use the Polymorfa message's `id` for actions and replies.

### Header parameters

- `Idempotency-Key` (string, length 1–255). Unique key, 1 to 255 bytes of UTF-8, that makes this write safe to retry for 1 hour. A retry with the same key, credential, `Polymorfa-Version`, and request never runs the write again while its receipt is retained. Keep the first response. Exact response replay requires authorized replay data; opaque message or campaign bodies are not retained by default. An available exact replay carries `Idempotent-Replayed: true`. Authorization, rate-limit and state refusals (401, 403, 408, 409, 423, 425, 429) are not recorded, so the same key can retry them. Reusing the key for a different request returns `422 idempotency_conflict`. A retry while the original is still running returns `409 idempotency_in_progress`, and a retry after an unrecorded outcome returns `409 idempotency_outcome_unknown`. If the recorded response cannot be read, the retry returns `503 idempotency_replay_unavailable` with `Retry-After` and the write still does not run again.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Message deleted
- `success` (boolean, required). Whether the request succeeded.
- `message` (string). Human-readable message associated with this result.

Headers:

- `Idempotent-Replayed` (string). `true` when this response is the recorded response of an earlier request with the same Idempotency-Key. Values: `true`.
- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The Idempotency-Key belongs to a request that is still running (`idempotency_in_progress`, with Retry-After) or whose outcome was not recorded (`idempotency_outcome_unknown`)
Same fields as 400.

Headers:

- `Retry-After` (integer, min 0). Seconds to wait before checking again with the same key. Waiting does not release the execution fence or guarantee that replay data becomes available. Same-key retries are protected only within the one-hour receipt window.
- `Link` (string). Link to the documentation for this Idempotency-Key error (`rel="describedby"`).
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_in_progress",
    "message": "A request with this Idempotency-Key is still in progress. Check again after Retry-After with the same key within the documented receipt window. Exact response data may be unavailable.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-in-progress"
}
```

#### 422

The Idempotency-Key was already used for a different request (`idempotency_conflict`)
Same fields as 400.

Headers:

- `Link`: described under 409.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request. Use a new key for a different request.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

For `idempotency_replay_unavailable` only: the exact response for this Idempotency-Key is unavailable (with Retry-After). Opaque responses are not retained by default. The write did not run again. Keep the first response and reconcile events or the resource; waiting does not guarantee that replay data becomes available. Do not switch keys to resend
Same fields as 400.

Headers:

- `Retry-After`: described under 409.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "idempotency_replay_unavailable",
    "message": "The exact response for this Idempotency-Key is unavailable. The request was not repeated. Keep the first response and reconcile events or the resource. Waiting does not guarantee replay data becomes available; do not switch keys to resend.",
    "param": null
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#idempotency-replay-unavailable"
}
```
