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

Messages

View as Markdown

The sent 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 4 child fields
  • timestampstring (date-time)required

    ISO 8601 timestamp associated with this event.

  • statusstringrequired

    Upstream acceptance status. Delivery and read receipts arrive separately.

  • typestringrequired

    Type discriminator for this object.

  • contentobjectrequired

    Specifies content for this native sent message.

    One of
    • textstringrequiredmin length1

      Text to send.

  • mediaIdstring

    Identifier 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. id is the standard-quality message.

The sent message object
{
  "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

POST/messaging/{session}/messages/sendMessaging APILinked Device APIMeta Cloud API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

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

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Provide one of: id, phoneNumber or bsuid

    Show 4 child fields
  • isForwardedboolean

    Mark this message as forwarded.

  • mentionsarray of stringmax items256item pattern^[1-9][0-9]{0,18}$

    User IDs to mention in this message.

  • quotedMessageobject

    Specifies quoted message for this native send message request.

    Show 3 child fields
  • contentobjectrequired

    Specifies content for this native send message request.

    One of
    • textstringrequiredmin length1

      Text to send.

Responses

  • 200Message sent successfully
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/{session}/messages/sendcURL
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"
  }
}'
Response
{
  "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

POST/messaging/{session}/messages/seenMessaging APILinked Device APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
messages:write

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Body

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Provide one of: id, phoneNumber or bsuid

    Show 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
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/{session}/messages/seencURL
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"
}'
Response
{
  "success": true,
  "data": {
    "status": "string"
  }
}

Send reaction

POST/messaging/{session}/messages/reactMessaging APILinked Device APIMeta Cloud API
Base URL
https://api.polymorfa.com
Required permission
messages:write

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

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

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Provide one of: id, phoneNumber or bsuid

    Show 4 child fields
  • idstringrequiredpattern^[1-9][0-9]{0,18}$

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

  • reactionstringrequired

    Reaction applied to the referenced message.

Responses

  • 200Reaction sent
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/{session}/messages/reactcURL
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"
}'
Response
{
  "success": true,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string"
    },
    "conversation": {
      "id": "739182640518203"
    },
    "timestamp": "2026-09-22T12:00:00Z",
    "status": "string"
  }
}

Set typing

POST/messaging/{session}/messages/typingMessaging APILinked Device APIMeta Cloud API
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

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Body

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Provide one of: id, phoneNumber or bsuid

    Show 4 child fields
  • statestringrequired

    Typing state to publish for the target conversation.

    Allowed valuestypingrecordingpaused
  • idstringpattern^[1-9][0-9]{0,18}$

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

Responses

  • 200Typing state confirmed by the messaging backend
    • successbooleanrequired

      Whether the request succeeded.

      Allowed valuestrue
    • dataobjectrequired

      Structured 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
POST /messaging/{session}/messages/typingcURL
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"
}'
Response
{
  "success": true,
  "data": {
    "status": "string"
  }
}

Star message

POST/messaging/{session}/messages/starMessaging APILinked Device API
Base URL
https://api.polymorfa.com
Required permission
messages:write

Path parameters

  • sessionstringrequired

    Identifier of the connected Polymorfa session.

Body

  • conversationobjectrequired

    Public conversation identifier or E.164 phone number.

    Provide one of: id, phoneNumber or bsuid

    Show 4 child fields
  • idstringrequiredpattern^[1-9][0-9]{0,18}$

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

  • starbooleanrequired

    Whether star.

Responses

POST /messaging/{session}/messages/starcURL
Not available with the Test key. Use a team key or project token.
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
}'
Response
{
  "success": true,
  "data": {
    "status": "string"
  }
}