Skip to content
Shortcut: /, ⌘K or Ctrl+K

Chats

View as Markdown

The chat object

Attributes

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Show 4 child fields
  • kindstringrequired

    Kind discriminator for this object.

    Allowed valuesdirectgroupchannelbroadcast
  • lastActivityAtstring (date-time)required

    Timestamp for last activity at.

  • lastMessageobjectrequired

    Specifies last message for this native history chat.

    Show 6 child fields
The chat object
{
  "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

  • idstringrequiredpattern^[1-9][0-9]{0,18}$

    Opaque Polymorfa resource ID. Keep this value as a string.

  • whatsapp_idsobjectrequired

    Exact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.

    One of
    • linked_devicesstringrequiredlength1–512

      Specifies linked devices for this any of.

    • official_apistringlength1–512

      Specifies official api for this any of.

  • whatsapp_idstringdeprecatedlength1–512

    Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Show 5 child fields
  • directionstringrequired

    Specifies direction for this native history message.

    Allowed valuesinboundoutbound
  • fromMebooleanrequired

    True when the Number sent the message, including from another linked device.

  • typestringrequired

    Message type as delivered in message.received, for example text or image.

  • timestampstring (date-time)required

    When WhatsApp reported the message.

  • pushNamestring

    WhatsApp display name reported by the sender's client.

  • textstring

    Text content carried by this object.

  • captionstring

    Caption shown with the attached media.

  • mimeTypestring

    IANA media type that matches the media payload.

    • Media type: IANA type/subtype value matching the payload, such as image/jpeg, video/mp4, audio/ogg, or application/pdf

  • filenamestring

    Filename presented for the media attachment.

  • pttboolean

    Whether the audio is presented as a push-to-talk voice message.

  • stickerTypestring

    Category assigned to sticker.

    Allowed valuesstaticanimatedlottie
  • originstring

    Specifies origin for this native history message.

    Allowed valuesavatarai
  • emojisarray of string

    Emojis associated with this native history message.

  • accessibilityLabelstring

    Specifies accessibility label for this native history message.

  • stickerPackobject

    Specifies sticker pack for this native history message.

    Show 6 child fields
  • latitudenumber

    Latitude in decimal degrees.

  • longitudenumber

    Longitude in decimal degrees.

  • displayNamestring

    Human-readable display name.

  • titlestring

    Human-readable title shown to the recipient or operator.

  • reactionstring

    Reaction applied to the referenced message.

  • reactionTostringpattern^[1-9][0-9]{0,18}$

    Opaque Polymorfa resource ID. Keep this value as a string.

  • editedboolean

    Whether the event represents an edited message.

  • unavailableboolean

    Whether the content is unavailable.

  • unavailableReasonstring

    Reason the content is unavailable.

  • pollOptionsarray of object

    Options recipients can choose in the poll.

    Show 2 child fields
  • orderobject

    Specifies order for this native history message.

    Show 3 child fields
  • mediaarray of object

    Downloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available.

    Show 4 child fields
  • mediaRetrievalobject

    Specifies media retrieval for this native history message.

    Show 2 child fields
The message object
{
  "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/messaging/{session}/chatsMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:read

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

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

Query parameters

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 50
  • cursorstringlength1–1024pattern^[A-Za-z0-9_-]+$

    Specifies cursor for this query parameter.

  • kindstring

    Kind discriminator for this object.

    Allowed valuesdirectgroupchannelbroadcast
  • activeSincestring (date-time)

    Specifies active since for this query parameter.

  • activeBeforestring (date-time)

    Specifies active before for this query parameter.

Responses

  • 200One page of conversations
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 4 child fields
    • hasMorebooleanrequired

      True when nextCursor returns more items.

    • nextCursorstringrequirednullable

      Specifies next cursor for this native list chats response.

    • previousCursorstringrequirednullable

      Always null for conversations. Use nextCursor to continue listing.

    Show 4 headers
  • 400A filter or cursor is invalid.
  • 401The credential is missing or invalid.
  • 403The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
  • 404The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
  • 503The history service for the Number's data region is unavailable.
GET /messaging/{session}/chatscURL
curl "https://api.polymorfa.com/messaging/<session>/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
}

List chat messages

GET/messaging/{session}/chats/{conversation}/messagesMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
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

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Query parameters

  • limitintegerrange1–100

    Specifies limit for this query parameter.

    Default 50
  • cursorstringlength1–1024pattern^[A-Za-z0-9_-]+$

    Specifies cursor for this query parameter.

  • orderstring

    Specifies order for this query parameter.

    Allowed valuesdescasc
    Default "desc"
  • sincestring (date-time)

    Specifies since for this query parameter.

  • untilstring (date-time)

    Specifies until for this query parameter.

  • directionstring

    Specifies direction for this query parameter.

    Allowed valuesinboundoutbound
  • typesstringpattern^[a-z][a-z_]{0,31}(?:,[a-z][a-z_]{0,31}){0,15}$

    Specifies types for this query parameter.

Responses

  • 200One page of messages
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataarray of objectrequired

      Structured data carried by this object.

      Show 32 child fields
    • hasMorebooleanrequired

      True when nextCursor returns more items.

    • nextCursorstringrequirednullable

      Specifies next cursor for this native list chat messages response.

    • previousCursorstringrequirednullable

      Cursor for the preceding page of messages. Null when no preceding page exists.

    Show 4 headers
  • 400A filter or cursor is invalid.
  • 401The credential is missing or invalid.
  • 403The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
  • 404The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
  • 503The history service for the Number's data region is unavailable.
GET /messaging/{session}/chats/{conversation}/messagescURL
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
}

Get chat message

GET/messaging/{session}/chats/{conversation}/messages/{messageId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
messages:read

Returns one stored message. Beta: requires team enrollment.

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

  • messageIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Polymorfa message ID. Use the Polymorfa message's id for actions and replies.

Responses

  • 200The message
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 32 child fields
    Show 4 headers
  • 400A filter or cursor is invalid.
  • 401The credential is missing or invalid.
  • 403The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
  • 404The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
  • 503The history service for the Number's data region is unavailable.
GET /messaging/{session}/chats/{conversation}/messages/{messageId}cURL
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
  }
}

Get chat

GET/messaging/{session}/chats/{conversation}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:read

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

Path parameters

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Responses

  • 200The conversation
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 4 headers
  • 400A filter or cursor is invalid.
  • 401The credential is missing or invalid.
  • 403The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
  • 404The Number or conversation is unavailable, or hosted message storage is not enabled (`hms_not_enabled`).
  • 503The history service for the Number's data region is unavailable.
GET /messaging/{session}/chats/{conversation}cURL
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "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"
    }
  }
}

Get chat message media

GET/messaging/{session}/chats/{conversation}/messages/{messageId}/mediaMessaging APIMeta Cloud API
Base URL
https://api.polymorfa.com

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

  • sessionstringrequiredmin length1

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

  • messageIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Polymorfa message ID. Use the Polymorfa message's id for actions and replies.

Responses

  • 200The media bytes, with the stored content type

    Content type*/*

    Show 4 headers
  • 400A filter or cursor is invalid.
  • 401The credential is missing or invalid.
  • 403The credential lacks the scope, is a client token without the `conversations_read` action, or the team is not enrolled in the beta.
  • 404The Number, conversation or message is unavailable, no stored copy exists, or hosted message storage is not enabled (`hms_not_enabled`).
  • 503The history service for the Number's data region is unavailable.
GET /messaging/{session}/chats/{conversation}/messages/{messageId}/mediacURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>/media" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response

Content type */*

No example for this content type

Archive chat

POST/messaging/{session}/chats/{conversation}/archiveMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Responses

  • 200Chat archived
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /messaging/{session}/chats/{conversation}/archivecURL
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/archive" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}

Unarchive chat

POST/messaging/{session}/chats/{conversation}/unarchiveMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Responses

  • 200Chat unarchived
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
POST /messaging/{session}/chats/{conversation}/unarchivecURL
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/unarchive" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}

Set chat disappearing timer

PUT/messaging/{session}/chats/{conversation}/disappearingMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

Body

  • durationSecondsnumberrequired

    Duration in seconds.

    Accepts one of
    • number, 0

    • number, 86400

    • number, 604800

    • number, 7776000

Responses

  • 200Disappearing-message timer updated
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 3 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 500Internal server error
PUT /messaging/{session}/chats/{conversation}/disappearingcURL
curl -X PUT "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/disappearing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "durationSeconds": 0
}'
Response
{
  "success": true
}

Edit message

PUT/messaging/{session}/chats/{conversation}/messages/{messageId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

  • messageIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Polymorfa message ID. Use the Polymorfa message's id for actions and replies.

Headers

  • Idempotency-Keystringlength1–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

  • textstringrequiredmin length1

    Text content carried by this object.

Responses

  • 200Message edited
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 4 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409The 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`)
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`)
  • 500Internal server error
  • 503For `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
PUT /messaging/{session}/chats/{conversation}/messages/{messageId}cURL
curl -X PUT "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "string"
}'
Response
{
  "success": true
}

Delete message

DELETE/messaging/{session}/chats/{conversation}/messages/{messageId}Messaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
chats:manage

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

  • conversationstringrequired

    Public conversation identifier or E.164 phone number.

  • messageIdstringrequiredpattern^[1-9][0-9]{0,18}$

    Polymorfa message ID. Use the Polymorfa message's id for actions and replies.

Headers

  • Idempotency-Keystringlength1–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.

Responses

  • 200Message deleted
    • successbooleanrequired

      Whether the request succeeded.

    • messagestring

      Human-readable message associated with this result.

    Show 4 headers
  • 400Bad request — request body or params failed validation
  • 401Missing or invalid authentication token
  • 403Authenticated but not permitted (missing scope or rule violation)
  • 404Resource not found
  • 409The 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`)
  • 422The Idempotency-Key was already used for a different request (`idempotency_conflict`)
  • 500Internal server error
  • 503For `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
DELETE /messaging/{session}/chats/{conversation}/messages/{messageId}cURL
curl -X DELETE "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "success": true
}