Chats
The chat object
Attributes
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 4 child fields
kindstringrequiredKind discriminator for this object.
Allowed valuesdirectgroupchannelbroadcastlastActivityAtstring (date-time)requiredTimestamp for last activity at.
lastMessageobjectrequiredSpecifies last message for this native history chat.
Show 6 child fields
{
"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_idsobjectrequiredExact observed provider references under linked_devices, official_api, or both. Use the Polymorfa id for message actions.
One oflinked_devicesstringrequiredlength1–512Specifies linked devices for this any of.
official_apistringlength1–512Specifies official api for this any of.
whatsapp_idstringdeprecatedlength1–512Temporary singular provider reference for older consumers. Use whatsapp_ids for transport-specific references.
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Show 5 child fields
directionstringrequiredSpecifies direction for this native history message.
Allowed valuesinboundoutboundfromMebooleanrequiredTrue when the Number sent the message, including from another linked device.
typestringrequiredMessage type as delivered in
message.received, for exampletextorimage.timestampstring (date-time)requiredWhen WhatsApp reported the message.
pushNamestringWhatsApp display name reported by the sender's client.
textstringText content carried by this object.
captionstringCaption shown with the attached media.
mimeTypestringIANA media type that matches the media payload.
Media type: IANA
type/subtypevalue matching the payload, such asimage/jpeg,video/mp4,audio/ogg, orapplication/pdf
filenamestringFilename presented for the media attachment.
pttbooleanWhether the audio is presented as a push-to-talk voice message.
stickerTypestringCategory assigned to sticker.
Allowed valuesstaticanimatedlottieoriginstringSpecifies origin for this native history message.
Allowed valuesavataraiemojisarray of stringEmojis associated with this native history message.
accessibilityLabelstringSpecifies accessibility label for this native history message.
stickerPackobjectSpecifies sticker pack for this native history message.
Show 6 child fields
latitudenumberLatitude in decimal degrees.
longitudenumberLongitude in decimal degrees.
displayNamestringHuman-readable display name.
titlestringHuman-readable title shown to the recipient or operator.
reactionstringReaction applied to the referenced message.
reactionTostringpattern^[1-9][0-9]{0,18}$Opaque Polymorfa resource ID. Keep this value as a string.
editedbooleanWhether the event represents an edited message.
unavailablebooleanWhether the content is unavailable.
unavailableReasonstringReason the content is unavailable.
pollOptionsarray of objectOptions recipients can choose in the poll.
Show 2 child fields
orderobjectSpecifies order for this native history message.
Show 3 child fields
mediaarray of objectDownloadable media for image, video, audio, document, and sticker messages. Empty when no copy is available.
Show 4 child fields
mediaRetrievalobjectSpecifies media retrieval for this native history message.
Show 2 child fields
{
"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
- 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 length1Identifier of the connected Polymorfa session.
Query parameters
limitintegerrange1–100Specifies limit for this query parameter.
Default50cursorstringlength1–1024pattern^[A-Za-z0-9_-]+$Specifies cursor for this query parameter.
kindstringKind discriminator for this object.
Allowed valuesdirectgroupchannelbroadcastactiveSincestring (date-time)Specifies active since for this query parameter.
activeBeforestring (date-time)Specifies active before for this query parameter.
Responses
200One page of conversations
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray of objectrequiredStructured data carried by this object.
Show 4 child fields
hasMorebooleanrequiredTrue when
nextCursorreturns more items.nextCursorstringrequirednullableSpecifies next cursor for this native list chats response.
previousCursorstringrequirednullableAlways 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.
curl "https://api.polymorfa.com/messaging/<session>/chats" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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 length1Identifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Query parameters
limitintegerrange1–100Specifies limit for this query parameter.
Default50cursorstringlength1–1024pattern^[A-Za-z0-9_-]+$Specifies cursor for this query parameter.
orderstringSpecifies order for this query parameter.
Allowed valuesdescascDefault"desc"sincestring (date-time)Specifies since for this query parameter.
untilstring (date-time)Specifies until for this query parameter.
directionstringSpecifies direction for this query parameter.
Allowed valuesinboundoutboundtypesstringpattern^[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
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataarray of objectrequiredStructured data carried by this object.
Show 32 child fields
hasMorebooleanrequiredTrue when
nextCursorreturns more items.nextCursorstringrequirednullableSpecifies next cursor for this native list chat messages response.
previousCursorstringrequirednullableCursor 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.
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
messages:read
Returns one stored message. Beta: requires team enrollment.
Path parameters
sessionstringrequiredmin length1Identifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
messageIdstringrequiredpattern^[1-9][0-9]{0,18}$Polymorfa message ID. Use the Polymorfa message's
idfor actions and replies.
Responses
200The message
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- Base URL
https://api.polymorfa.com- Required permission
chats:read
Returns one conversation with stored messages. Beta: requires team enrollment.
Path parameters
sessionstringrequiredmin length1Identifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Responses
200The conversation
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured 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.
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"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
- 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 length1Identifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
messageIdstringrequiredpattern^[1-9][0-9]{0,18}$Polymorfa message ID. Use the Polymorfa message's
idfor 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.
curl "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/messages/<messageId>/media" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"Content type */*
No example for this content type
Archive chat
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Responses
200Chat archived
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/archive" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true
}Unarchive chat
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Responses
200Chat unarchived
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
curl -X POST "https://api.polymorfa.com/messaging/<session>/chats/<conversation>/unarchive" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22"{
"success": true
}Set chat disappearing timer
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
Body
durationSecondsnumberrequiredDuration in seconds.
Accepts one ofnumber,
0number,
86400number,
604800number,
7776000
Responses
200Disappearing-message timer updated
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
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
}'{
"success": true
}Edit message
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
messageIdstringrequiredpattern^[1-9][0-9]{0,18}$Polymorfa message ID. Use the Polymorfa message's
idfor actions and replies.
Headers
Idempotency-Keystringlength1–255Unique 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 carriesIdempotent-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 returns422 idempotency_conflict. A retry while the original is still running returns409 idempotency_in_progress, and a retry after an unrecorded outcome returns409 idempotency_outcome_unknown. If the recorded response cannot be read, the retry returns503 idempotency_replay_unavailablewithRetry-Afterand the write still does not run again.
Body
textstringrequiredmin length1Text content carried by this object.
Responses
200Message edited
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
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"
}'{
"success": true
}Delete message
- Base URL
https://api.polymorfa.com- Required permission
chats:manage
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
conversationstringrequiredPublic conversation identifier or E.164 phone number.
messageIdstringrequiredpattern^[1-9][0-9]{0,18}$Polymorfa message ID. Use the Polymorfa message's
idfor actions and replies.
Headers
Idempotency-Keystringlength1–255Unique 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 carriesIdempotent-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 returns422 idempotency_conflict. A retry while the original is still running returns409 idempotency_in_progress, and a retry after an unrecorded outcome returns409 idempotency_outcome_unknown. If the recorded response cannot be read, the retry returns503 idempotency_replay_unavailablewithRetry-Afterand the write still does not run again.
Responses
200Message deleted
successbooleanrequiredWhether the request succeeded.
messagestringHuman-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
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"{
"success": true
}