Messages
The sent 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 4 child fields
timestampstring (date-time)requiredISO 8601 timestamp associated with this event.
statusstringrequiredUpstream acceptance status. Delivery and read receipts arrive separately.
typestringrequiredType discriminator for this object.
contentobjectrequiredSpecifies content for this native sent message.
One oftextstringrequiredmin length1Text to send.
mediaIdstringIdentifier for the media.
hdMessageIdstringpattern^[1-9][0-9]{0,18}$ID of the HD half of an image pair, present when
quality: "hd"sent one.idis the standard-quality message.
{
"id": "739182640518203",
"whatsapp_ids": {
"linked_devices": "string",
"official_api": "string"
},
"whatsapp_id": "string",
"conversation": {
"id": "739182640518203",
"phoneNumber": "string",
"bsuid": "string",
"username": "string"
},
"timestamp": "2026-09-22T12:00:00Z",
"status": "string",
"type": "string",
"content": {
"text": "string"
},
"mediaId": "string",
"hdMessageId": "739182640518203"
}Send message
- Base URL
https://api.polymorfa.com- Required permission
messages:write
Send a message to a conversation. Put exactly one message kind inside content. The complete JSON request body is limited to 72 MiB before parsing; decoded media remains limited to 50 MiB. Testing sessions send only to active testing numbers in the same project; supply the recipient phoneNumber.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
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
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Provide one of:
id,phoneNumberorbsuidShow 4 child fields
isForwardedbooleanMark this message as forwarded.
mentionsarray of stringmax items256item pattern^[1-9][0-9]{0,18}$User IDs to mention in this message.
quotedMessageobjectSpecifies quoted message for this native send message request.
Show 3 child fields
contentobjectrequiredSpecifies content for this native send message request.
One oftextstringrequiredmin length1Text to send.
Responses
200Message sent successfully
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 10 child fields
Show 4 headers
202Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
400Invalid request
401Invalid credential
402`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
403Missing scope or resource access
404Resource not found
409`unsupported_for_connection`: call permission requests need a Cloud API number; `call_permission_granted`: the person already granted permanent permission. 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`)
413The JSON request exceeds 72 MiB, or decoded media exceeds its size limit
422The supplied media URL could not be fetched. The Idempotency-Key was already used for a different request (`idempotency_conflict`)
429`call_permission_request_limited`: WhatsApp limits how often this person can be asked for call permission.
500Unexpected service failure
501`operation_not_supported`: the number's connection cannot send this content, such as a poll, or a URL, call or copy-code button on an official WhatsApp Business number
502Messaging provider failure
503Session or service unavailable. 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
504Result unknown after timeout
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": {
"phoneNumber": "+15550001111"
},
"content": {
"text": "Hello"
}
}'{
"success": true,
"data": {
"id": "739182640518203",
"whatsapp_ids": {
"linked_devices": "string"
},
"conversation": {
"id": "739182640518203"
},
"timestamp": "2026-09-22T12:00:00Z",
"status": "string",
"type": "string",
"content": {
"text": "string"
}
}
}Send seen
- Base URL
https://api.polymorfa.com- Required permission
messages:write
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Body
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Provide one of:
id,phoneNumberorbsuidShow 4 child fields
idstringrequiredpattern^[1-9][0-9]{0,18}$Opaque Polymorfa resource ID. Keep this value as a string.
Responses
200Seen marker confirmed by the messaging backend
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 1 child field
Show 3 headers
202Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
400Invalid request
401Invalid credential
402`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
403Missing scope or resource access
404Resource not found
500Unexpected service failure
502Messaging provider failure
503Session or service unavailable
504Result unknown after timeout
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/seen" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": {
"id": "739182640518203",
"phoneNumber": "string",
"bsuid": "string",
"username": "string"
},
"id": "739182640518203"
}'{
"success": true,
"data": {
"status": "string"
}
}Send reaction
- Base URL
https://api.polymorfa.com- Required permission
messages:write
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
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
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Provide one of:
id,phoneNumberorbsuidShow 4 child fields
idstringrequiredpattern^[1-9][0-9]{0,18}$Opaque Polymorfa resource ID. Keep this value as a string.
reactionstringrequiredReaction applied to the referenced message.
Responses
200Reaction sent
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 6 child fields
Show 4 headers
202Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
400Invalid request
401Invalid credential
402`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
403Missing scope or resource access
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`)
500Unexpected service failure
502Messaging provider failure
503Session or service unavailable. 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
504Result unknown after timeout
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/react" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": {
"id": "739182640518203",
"phoneNumber": "string",
"bsuid": "string",
"username": "string"
},
"id": "739182640518203",
"reaction": "string"
}'{
"success": true,
"data": {
"id": "739182640518203",
"whatsapp_ids": {
"linked_devices": "string"
},
"conversation": {
"id": "739182640518203"
},
"timestamp": "2026-09-22T12:00:00Z",
"status": "string"
}
}Set typing
- Base URL
https://api.polymorfa.com- Required permission
messages:write
On a Linked Devices number, state sets typing, recording or paused. On an official WhatsApp Business number, send state: "typing" with the id of a message you received; this marks that message read and shows a typing indicator until you reply or 25 seconds pass. On a Number with both connections, this method uses the Linked Devices connection; use the Graph API status request for official typing. Other states return 501, and a missing id returns 400.
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Body
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Provide one of:
id,phoneNumberorbsuidShow 4 child fields
statestringrequiredTyping state to publish for the target conversation.
Allowed valuestypingrecordingpausedidstringpattern^[1-9][0-9]{0,18}$Opaque Polymorfa resource ID. Keep this value as a string.
Responses
200Typing state confirmed by the messaging backend
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 1 child field
Show 3 headers
202Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
400Invalid request
401Invalid credential
402`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
403Missing scope or resource access
404Resource not found
409Routing or operation conflict
500Unexpected service failure
501`operation_not_supported`: official WhatsApp Business numbers support only the `typing` state
502Messaging provider failure
503Session or service unavailable
504Result unknown after timeout
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/typing" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": {
"id": "739182640518203",
"phoneNumber": "string",
"bsuid": "string",
"username": "string"
},
"state": "typing"
}'{
"success": true,
"data": {
"status": "string"
}
}Star message
- Base URL
https://api.polymorfa.com- Required permission
messages:write
Path parameters
sessionstringrequiredIdentifier of the connected Polymorfa session.
Body
conversationobjectrequiredPublic conversation identifier or E.164 phone number.
Provide one of:
id,phoneNumberorbsuidShow 4 child fields
idstringrequiredpattern^[1-9][0-9]{0,18}$Opaque Polymorfa resource ID. Keep this value as a string.
starbooleanrequiredWhether star.
Responses
200Star status updated
successbooleanrequiredWhether the request succeeded.
Allowed valuestruedataobjectrequiredStructured data carried by this object.
Show 1 child field
Show 3 headers
202Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
400Invalid request
401Invalid credential
402`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
403Missing scope or resource access
404Resource not found
409Routing or operation conflict
500Unexpected service failure
502Messaging provider failure
503Session or service unavailable
504Result unknown after timeout
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/star" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Polymorfa-Version: 2026-09-22" \
-H "Content-Type: application/json" \
-d '{
"conversation": {
"id": "739182640518203",
"phoneNumber": "string",
"bsuid": "string",
"username": "string"
},
"id": "739182640518203",
"star": true
}'{
"success": true,
"data": {
"status": "string"
}
}