# Messages

## Endpoints

- `POST /messaging/{session}/messages/send`: [Send message](https://docs.polymorfa.com/api/messages/send-message)
- `POST /messaging/{session}/messages/seen`: [Send seen](https://docs.polymorfa.com/api/messages/send-seen)
- `POST /messaging/{session}/messages/react`: [Send reaction](https://docs.polymorfa.com/api/messages/send-reaction)
- `POST /messaging/{session}/messages/typing`: [Set typing](https://docs.polymorfa.com/api/messages/set-typing)
- `POST /messaging/{session}/messages/star`: [Star message](https://docs.polymorfa.com/api/messages/star-message)

## The sent 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.
- `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.
- `status` (string, required). Upstream acceptance status. Delivery and read receipts arrive separately.
- `type` (string, required). Type discriminator for this object.
- `content` (object, required). Specifies content for this native sent message.
  - One of:
    - `text` (object).
      - `text` (string, required, min length 1). Text to send.
    - `image` (object).
      - `image` (object, required). Image attached to or representing this resource.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `descriptor` (object). Specifies descriptor for this image.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
        - `quality` (string). `standard` (default) sends the image once, as supplied. `hd` requests a WhatsApp HD pair: a standard-quality message followed by the original. HD pairs are not sent yet; an `hd` request is sent once, as supplied, and the response has no `hdMessageId`. Values: `standard`, `hd`.
    - `video` (object).
      - `video` (object, required). Structured video values for this one of.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `descriptor` (object). Specifies descriptor for this video.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `seconds` (integer, range 0–86400). Duration in seconds.
    - `file` (object).
      - `file` (object, required). Structured file values for this one of.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `filename` (string). Filename presented for the media attachment.
        - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `descriptor` (object). Specifies descriptor for this file.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
    - `voice` (object).
      - `voice` (object, required). Voice-message content and metadata.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
        - `descriptor` (object). Specifies descriptor for this voice.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `seconds` (integer, range 0–86400). Duration in seconds.
          - `waveform` (string, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 voice-note waveform, 64 to 192 bytes.
    - `sticker` (object).
      - `sticker` (object, required). Structured sticker values for this one of.
        - Provide exactly one of: `url`, `base64` or `descriptor`.
        - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
        - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
        - `descriptor` (object). Specifies descriptor for this sticker.
          - When `mimeType` is `image/webp`: .
          - When `mimeType` is `application/was`, When `stickerType` is `lottie`: requires `stickerType`.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `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. Values: `image/webp`, `application/was`.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
        - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this sticker.
        - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this sticker.
    - `stickerPack` (object).
      - `stickerPack` (object, required). Specifies sticker pack for this one of.
        - One of:
          - `Option 1` (object). Convert up to 100 image items. Items and an explicit tray share 64 MiB of input and 128 million source plus 512px output frame pixels. Preparation stops at the command deadline or 30 seconds, whichever comes first. Reduce dimensions, frame counts or item count if the pack exceeds these limits.
            - `id` (string, required, min length 1). Identifier for this resource.
            - `name` (string, required, min length 1). Human-readable name for this resource.
            - `publisher` (string, required, min length 1). Specifies publisher for this any of.
            - `description` (string, min length 0). Human-readable description of this resource.
            - `caption` (string, min length 0). Caption shown with the attached media.
            - `items` (array of object, required, items 1–100). Items associated with this any of.
              - Provide exactly one of: `url` or `base64`.
              - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this item.
              - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this item.
              - `fileName` (string, min length 1, pattern ^[^/\\:\x00]+$). Human-readable file name for this item.
              - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
              - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
            - `trayIcon` (object). Structured tray icon values for this any of.
              - Provide exactly one of: `url` or `base64`.
              - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
              - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
          - `descriptor` (object).
            - `id` (string, required, min length 1). Identifier for this resource.
            - `name` (string, required, min length 1). Human-readable name for this resource.
            - `publisher` (string, required, min length 1). Specifies publisher for this any of.
            - `description` (string, min length 0). Human-readable description of this resource.
            - `caption` (string, min length 0). Caption shown with the attached media.
            - `items` (array of object, required, items 1–100). Items associated with this any of.
              - `fileName` (string, required, min length 1, pattern ^[^/\\:\x00]+$). Human-readable file name for this item.
              - `stickerType` (string, required). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
              - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this item.
              - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this item.
            - `descriptor` (object, required). Structured descriptor values for this any of.
              - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
              - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
              - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
              - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
              - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
              - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
              - `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. Values: `application/zip`.
              - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `trayIconFileName` (string, min length 1, pattern ^[^/\\:\x00]+$). Human-readable tray icon file name for this any of.
            - `thumbnailDescriptor` (object). Structured thumbnail descriptor values for this any of.
              - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
              - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
              - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
              - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
              - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
              - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
              - `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. Values: `image/png`.
              - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
              - `width` (integer, range 1–65536). Width in pixels. Send with height.
              - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `forwardMedia` (object).
            - `forwardMedia` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Specifies forward media for this any of.
    - `location` (object).
      - `location` (object, required). Structured location values for this one of.
        - `lat` (number, required, range -90–90). Latitude in decimal degrees.
        - `long` (number, required, range -180–180). Longitude in decimal degrees.
        - `address` (string). Display address for the location.
    - `poll` (object).
      - `poll` (object, required). Structured poll values for this one of.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `options` (array of string, required, items 2–12, item min length 1). Selectable options carried by this object.
        - `multiSelect` (boolean). Whether multi select.
    - `contact` (object).
      - `contact` (object, required). Structured contact values for this one of.
        - `vcard` (string, required, min length 1). Specifies vcard for this contact.
    - `requestPhoneNumber` (object).
      - `requestPhoneNumber` (object, required). Structured request phone number values for this one of.
    - `product` (object).
      - `product` (object, required). Structured product values for this one of.
        - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `currencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code.
        - `priceAmount1000` (integer, required, range 0–9007199254740991). Price expressed in thousandths of the declared currency unit.
        - `salePriceAmount1000` (integer, range 0–9007199254740991). Discounted price expressed in thousandths of the declared currency unit.
        - `retailerId` (string, min length 0). Merchant-defined identifier for the catalog item.
        - `url` (string (uri), max length 2048, format uri). URL associated with this resource.
        - `imageCount` (integer, range 0–100). Number of images.
        - `image` (object). Image attached to or representing this resource.
          - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
          - `base64` (string, max length 87384). Base64-encoded content with no data-URL prefix.
          - `mimeType` (string, min length 0, 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.
        - `body` (string, min length 0). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
    - `productList` (object).
      - `productList` (object, required). Structured product list values for this one of.
        - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `sections` (array of object, required, items 1–10, Total products: At most `30` product IDs across all sections, Product IDs: Every product ID must be unique across all sections). Ordered sections displayed in the interactive message.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `productIds` (array of string, required, items 1–30, item min length 1). Identifiers of the products included in this section.
    - `order` (object).
      - `order` (object, required). Structured order values for this one of.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `thumbnailBase64` (string, max length 87384). Base64-encoded thumbnail content with no data-URL prefix.
        - `itemCount` (integer, required, range 1–100). Number of items.
        - `status` (string, required). Order status sent with this business order. Values: `inquiry`, `accepted`, `declined`.
        - `message` (string, min length 0). Outbound message content attached to this business order.
        - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
        - `sellerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `token` (string, min length 0). Opaque token required by the target operation.
        - `totalAmount1000` (integer, required, range 0–9007199254740991). Order total expressed in thousandths of the declared currency unit.
        - `totalCurrencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code used for the order total.
        - `catalogType` (string, min length 0). Category assigned to catalog.
    - `list` (object).
      - `list` (object, required). On an official WhatsApp Business number, `title` is the header (at most 60 characters) and `description` the body (at most 1,024 characters); without `description`, `title` is the body. There, each section title allows at most 24 characters and is required when the list has more than one section, lists allow at most 10 rows in total, row titles at most 24 characters, row IDs at most 200, row descriptions at most 72, `buttonText` at most 20 and `footer` at most 60. Every number also limits `buttonText` to 64 UTF-8 bytes, row `id` to 256 bytes and `title` and `description` to 256 and 4,096 bytes, so multibyte text reaches those byte limits before the character limits. Content outside any limit returns `400`.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `sections` (array of object, required, items 1–10, Total rows: At most `30` rows across all sections, Row IDs: Every row ID must be unique across all sections). Ordered sections displayed in the interactive message.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `rows` (array of object, required, items 1–30). Rows associated with this section.
    - `carousel` (object).
      - `carousel` (object, required). Linked Devices only: one message with 2–10 image/video cards and native buttons per card. Each card accepts up to ten replies or three CTAs without mixing; reply IDs are unique across cards. Combined media is bounded to 50 MiB. Official approved carousel templates use content.template instead.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `cards` (array of object, required, items 2–10). Cards associated with this carousel.
          - One of:
            - `image` (object).
              - `body` (string, required, min length 1). Primary text content shown to the recipient.
              - `buttons` (array of one of, required, items 1–10). Interactive buttons displayed with the message.
              - `image` (object, required). Image attached to or representing this resource.
            - `video` (object).
              - `body` (string, required, min length 1). Primary text content shown to the recipient.
              - `buttons` (array of one of, required, items 1–10). Interactive buttons displayed with the message.
              - `video` (object, required). Structured video values for this any of.
    - `buttons` (object).
      - `buttons` (object, required). Linked Devices support up to 10 total buttons and at most 3 CTAs. Replies may be mixed with URL and call buttons using a hydrated template; copy/catalog buttons cannot be mixed with replies. An optional image, video or document header requires exactly one URL or base64 source and cannot be combined with a title. On an official WhatsApp Business number, media headers require an approved template, and at most 3 `reply` buttons are sent; other button types return `501`. There, `body` allows at most 1,024 characters, `title` and `footer` at most 60, and each button needs a unique `id` and a unique `text` of at most 20 characters. Every number also limits each button `id` to 256 UTF-8 bytes. Content outside any limit returns `400`.
        - `media` (object). Reference to the media attached to this message.
          - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
          - `base64` (string, length 1–70000000). Base64-encoded content with no data-URL prefix.
          - `mimeType` (string, min length 0, 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.
          - `type` (string, required). Type discriminator for this object. Values: `image`, `video`, `document`.
          - `filename` (string, min length 0). Filename presented for the media attachment.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `buttons` (array of object, required, items 1–10). Interactive buttons displayed with the message.
          - One of:
            - `url` (object).
              - `type` (string, required). Type discriminator for this object. Values: `url`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
            - `call` (object).
              - `type` (string, required). Type discriminator for this object. Values: `call`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `phoneNumber` (string, required, pattern ^\+?\d{6,20}$). Phone number in international format.
            - `reply` (object).
              - `type` (string, required). Type discriminator for this object. Values: `reply`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `id` (string, required, min length 1). Identifier for this resource.
            - `copy` (object).
              - `type` (string, required). Type discriminator for this object. Values: `copy`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `copyCode` (string, required, min length 1). Text copied when the recipient activates the copy-code button.
            - `catalog` (object).
              - `type` (string, required). Type discriminator for this object. Values: `catalog`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `businessPhoneNumber` (string, required, pattern ^\+?\d{6,20}$). WhatsApp business phone number whose catalog is opened by this button.
              - `catalogProductId` (string, min length 0). Identifier for the catalog product.
    - `addressMessage` (object).
      - `addressMessage` (object, required). Structured address message values for this one of.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `buttonText` (string, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `country` (string, pattern ^[A-Z]{2}$). ISO 3166-1 alpha-2 country code.
    - `flow` (object).
      - `flow` (object, required). Structured flow values for this one of.
        - When `action` is `navigate`: requires `screen`.
        - When `action` is `data_exchange`: `screen` and `dataJson` not accepted.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `token` (string, required, min length 1). Opaque token required by the target operation.
        - `action` (string, required). Action performed when the recipient activates this control. Values: `navigate`, `data_exchange`.
        - `screen` (string, min length 0). Flow screen opened when the recipient activates the message.
        - `dataJson` (string, min length 0, Serialized value: A non-null JSON object; arrays, scalar values, and invalid JSON are not accepted, UTF-8 size: At most `16` KiB (`16,384` bytes)). JSON object encoded as a string and supplied to the Flow interaction.
    - `callPermissionRequest` (object).
      - `callPermissionRequest` (object, required). Ask the person for permission to call them. Cloud API numbers only; WhatsApp limits how often you can ask.
        - `body` (string, required, length 1–1024). Why you want to call, shown above WhatsApp's allow and decline buttons. 1 to 1,024 Unicode characters.
    - `template` (object).
      - `template` (object, required). Structured template values for this one of.
        - `name` (string, required, min length 1). Human-readable name for this resource.
        - `language` (string, required, min length 2). Language or locale code used for this content.
        - `components` (array of any, max items 1000). Structured components that make up this message or template.
- `mediaId` (string). Identifier for the media.
- `hdMessageId` (string, pattern ^[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.
```json
{
  "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 https://api.polymorfa.com/messaging/{session}/messages/send` (Messaging API)

Required permission: `messages:write`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `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

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

### 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

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - Provide one of: `id`, `phoneNumber` or `bsuid`.
  - `id` (string, 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}$). International phone number to look up, including + and the country code. WhatsApp determines the recipient account.
  - `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). Known username. This field alone does not select a conversation.
- `isForwarded` (boolean). Mark this message as forwarded.
- `mentions` (array of string, max items 256, item pattern ^[1-9][0-9]{0,18}$). User IDs to mention in this message.
- `quotedMessage` (object). Specifies quoted message for this native send message request.
  - `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
  - `type` (string). Type discriminator for this object.
  - `text` (string). Text content carried by this object.
- `content` (object, required). Specifies content for this native send message request.
  - One of:
    - `text` (object).
      - `text` (string, required, min length 1). Text to send.
    - `image` (object).
      - `image` (object, required). Image attached to or representing this resource.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `descriptor` (object). Specifies descriptor for this image.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
        - `quality` (string). `standard` (default) sends the image once, as supplied. `hd` requests a WhatsApp HD pair: a standard-quality message followed by the original. HD pairs are not sent yet; an `hd` request is sent once, as supplied, and the response has no `hdMessageId`. Values: `standard`, `hd`.
    - `video` (object).
      - `video` (object, required). Structured video values for this one of.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `descriptor` (object). Specifies descriptor for this video.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `seconds` (integer, range 0–86400). Duration in seconds.
    - `file` (object).
      - `file` (object, required). Structured file values for this one of.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `filename` (string). Filename presented for the media attachment.
        - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `descriptor` (object). Specifies descriptor for this file.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
    - `voice` (object).
      - `voice` (object, required). Voice-message content and metadata.
        - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
        - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
        - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
        - `caption` (string). Caption sent with the media.
        - `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
        - `descriptor` (object). Specifies descriptor for this voice.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the plaintext file.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `seconds` (integer, range 0–86400). Duration in seconds.
          - `waveform` (string, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 voice-note waveform, 64 to 192 bytes.
    - `sticker` (object).
      - `sticker` (object, required). Structured sticker values for this one of.
        - Provide exactly one of: `url`, `base64` or `descriptor`.
        - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
        - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
        - `descriptor` (object). Specifies descriptor for this sticker.
          - When `mimeType` is `image/webp`: .
          - When `mimeType` is `application/was`, When `stickerType` is `lottie`: requires `stickerType`.
          - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
          - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
          - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
          - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
          - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
          - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
          - `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. Values: `image/webp`, `application/was`.
          - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
          - `width` (integer, range 1–65536). Width in pixels. Send with height.
          - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
        - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this sticker.
        - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this sticker.
    - `stickerPack` (object).
      - `stickerPack` (object, required). Specifies sticker pack for this one of.
        - One of:
          - `Option 1` (object). Convert up to 100 image items. Items and an explicit tray share 64 MiB of input and 128 million source plus 512px output frame pixels. Preparation stops at the command deadline or 30 seconds, whichever comes first. Reduce dimensions, frame counts or item count if the pack exceeds these limits.
            - `id` (string, required, min length 1). Identifier for this resource.
            - `name` (string, required, min length 1). Human-readable name for this resource.
            - `publisher` (string, required, min length 1). Specifies publisher for this any of.
            - `description` (string, min length 0). Human-readable description of this resource.
            - `caption` (string, min length 0). Caption shown with the attached media.
            - `items` (array of object, required, items 1–100). Items associated with this any of.
              - Provide exactly one of: `url` or `base64`.
              - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this item.
              - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this item.
              - `fileName` (string, min length 1, pattern ^[^/\\:\x00]+$). Human-readable file name for this item.
              - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
              - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
            - `trayIcon` (object). Structured tray icon values for this any of.
              - Provide exactly one of: `url` or `base64`.
              - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
              - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
          - `descriptor` (object).
            - `id` (string, required, min length 1). Identifier for this resource.
            - `name` (string, required, min length 1). Human-readable name for this resource.
            - `publisher` (string, required, min length 1). Specifies publisher for this any of.
            - `description` (string, min length 0). Human-readable description of this resource.
            - `caption` (string, min length 0). Caption shown with the attached media.
            - `items` (array of object, required, items 1–100). Items associated with this any of.
              - `fileName` (string, required, min length 1, pattern ^[^/\\:\x00]+$). Human-readable file name for this item.
              - `stickerType` (string, required). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
              - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this item.
              - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this item.
            - `descriptor` (object, required). Structured descriptor values for this any of.
              - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
              - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
              - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
              - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
              - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
              - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
              - `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. Values: `application/zip`.
              - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `trayIconFileName` (string, min length 1, pattern ^[^/\\:\x00]+$). Human-readable tray icon file name for this any of.
            - `thumbnailDescriptor` (object). Structured thumbnail descriptor values for this any of.
              - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
              - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
              - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
              - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
              - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
              - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
              - `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. Values: `image/png`.
              - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
              - `width` (integer, range 1–65536). Width in pixels. Send with height.
              - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `forwardMedia` (object).
            - `forwardMedia` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Specifies forward media for this any of.
    - `location` (object).
      - `location` (object, required). Structured location values for this one of.
        - `lat` (number, required, range -90–90). Latitude in decimal degrees.
        - `long` (number, required, range -180–180). Longitude in decimal degrees.
        - `address` (string). Display address for the location.
    - `poll` (object).
      - `poll` (object, required). Structured poll values for this one of.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `options` (array of string, required, items 2–12, item min length 1). Selectable options carried by this object.
        - `multiSelect` (boolean). Whether multi select.
    - `contact` (object).
      - `contact` (object, required). Structured contact values for this one of.
        - `vcard` (string, required, min length 1). Specifies vcard for this contact.
    - `requestPhoneNumber` (object).
      - `requestPhoneNumber` (object, required). Structured request phone number values for this one of.
    - `product` (object).
      - `product` (object, required). Structured product values for this one of.
        - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `currencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code.
        - `priceAmount1000` (integer, required, range 0–9007199254740991). Price expressed in thousandths of the declared currency unit.
        - `salePriceAmount1000` (integer, range 0–9007199254740991). Discounted price expressed in thousandths of the declared currency unit.
        - `retailerId` (string, min length 0). Merchant-defined identifier for the catalog item.
        - `url` (string (uri), max length 2048, format uri). URL associated with this resource.
        - `imageCount` (integer, range 0–100). Number of images.
        - `image` (object). Image attached to or representing this resource.
          - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
          - `base64` (string, max length 87384). Base64-encoded content with no data-URL prefix.
          - `mimeType` (string, min length 0, 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.
        - `body` (string, min length 0). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
    - `productList` (object).
      - `productList` (object, required). Structured product list values for this one of.
        - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `sections` (array of object, required, items 1–10, Total products: At most `30` product IDs across all sections, Product IDs: Every product ID must be unique across all sections). Ordered sections displayed in the interactive message.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `productIds` (array of string, required, items 1–30, item min length 1). Identifiers of the products included in this section.
    - `order` (object).
      - `order` (object, required). Structured order values for this one of.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `thumbnailBase64` (string, max length 87384). Base64-encoded thumbnail content with no data-URL prefix.
        - `itemCount` (integer, required, range 1–100). Number of items.
        - `status` (string, required). Order status sent with this business order. Values: `inquiry`, `accepted`, `declined`.
        - `message` (string, min length 0). Outbound message content attached to this business order.
        - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
        - `sellerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
        - `token` (string, min length 0). Opaque token required by the target operation.
        - `totalAmount1000` (integer, required, range 0–9007199254740991). Order total expressed in thousandths of the declared currency unit.
        - `totalCurrencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code used for the order total.
        - `catalogType` (string, min length 0). Category assigned to catalog.
    - `list` (object).
      - `list` (object, required). On an official WhatsApp Business number, `title` is the header (at most 60 characters) and `description` the body (at most 1,024 characters); without `description`, `title` is the body. There, each section title allows at most 24 characters and is required when the list has more than one section, lists allow at most 10 rows in total, row titles at most 24 characters, row IDs at most 200, row descriptions at most 72, `buttonText` at most 20 and `footer` at most 60. Every number also limits `buttonText` to 64 UTF-8 bytes, row `id` to 256 bytes and `title` and `description` to 256 and 4,096 bytes, so multibyte text reaches those byte limits before the character limits. Content outside any limit returns `400`.
        - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
        - `description` (string, min length 0). Human-readable description of this resource.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `sections` (array of object, required, items 1–10, Total rows: At most `30` rows across all sections, Row IDs: Every row ID must be unique across all sections). Ordered sections displayed in the interactive message.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `rows` (array of object, required, items 1–30). Rows associated with this section.
    - `carousel` (object).
      - `carousel` (object, required). Linked Devices only: one message with 2–10 image/video cards and native buttons per card. Each card accepts up to ten replies or three CTAs without mixing; reply IDs are unique across cards. Combined media is bounded to 50 MiB. Official approved carousel templates use content.template instead.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `cards` (array of object, required, items 2–10). Cards associated with this carousel.
          - One of:
            - `image` (object).
              - `body` (string, required, min length 1). Primary text content shown to the recipient.
              - `buttons` (array of one of, required, items 1–10). Interactive buttons displayed with the message.
              - `image` (object, required). Image attached to or representing this resource.
            - `video` (object).
              - `body` (string, required, min length 1). Primary text content shown to the recipient.
              - `buttons` (array of one of, required, items 1–10). Interactive buttons displayed with the message.
              - `video` (object, required). Structured video values for this any of.
    - `buttons` (object).
      - `buttons` (object, required). Linked Devices support up to 10 total buttons and at most 3 CTAs. Replies may be mixed with URL and call buttons using a hydrated template; copy/catalog buttons cannot be mixed with replies. An optional image, video or document header requires exactly one URL or base64 source and cannot be combined with a title. On an official WhatsApp Business number, media headers require an approved template, and at most 3 `reply` buttons are sent; other button types return `501`. There, `body` allows at most 1,024 characters, `title` and `footer` at most 60, and each button needs a unique `id` and a unique `text` of at most 20 characters. Every number also limits each button `id` to 256 UTF-8 bytes. Content outside any limit returns `400`.
        - `media` (object). Reference to the media attached to this message.
          - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
          - `base64` (string, length 1–70000000). Base64-encoded content with no data-URL prefix.
          - `mimeType` (string, min length 0, 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.
          - `type` (string, required). Type discriminator for this object. Values: `image`, `video`, `document`.
          - `filename` (string, min length 0). Filename presented for the media attachment.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
        - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `buttons` (array of object, required, items 1–10). Interactive buttons displayed with the message.
          - One of:
            - `url` (object).
              - `type` (string, required). Type discriminator for this object. Values: `url`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `url` (string (uri), required, max length 2048, format uri). URL associated with this resource.
            - `call` (object).
              - `type` (string, required). Type discriminator for this object. Values: `call`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `phoneNumber` (string, required, pattern ^\+?\d{6,20}$). Phone number in international format.
            - `reply` (object).
              - `type` (string, required). Type discriminator for this object. Values: `reply`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `id` (string, required, min length 1). Identifier for this resource.
            - `copy` (object).
              - `type` (string, required). Type discriminator for this object. Values: `copy`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `copyCode` (string, required, min length 1). Text copied when the recipient activates the copy-code button.
            - `catalog` (object).
              - `type` (string, required). Type discriminator for this object. Values: `catalog`.
              - `text` (string, required, min length 1). Text content carried by this object.
              - `businessPhoneNumber` (string, required, pattern ^\+?\d{6,20}$). WhatsApp business phone number whose catalog is opened by this button.
              - `catalogProductId` (string, min length 0). Identifier for the catalog product.
    - `addressMessage` (object).
      - `addressMessage` (object, required). Structured address message values for this one of.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `buttonText` (string, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `country` (string, pattern ^[A-Z]{2}$). ISO 3166-1 alpha-2 country code.
    - `flow` (object).
      - `flow` (object, required). Structured flow values for this one of.
        - When `action` is `navigate`: requires `screen`.
        - When `action` is `data_exchange`: `screen` and `dataJson` not accepted.
        - `body` (string, required, min length 1). Primary text content shown to the recipient.
        - `buttonText` (string, required, min length 1). Text displayed on the action button.
        - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
        - `id` (string, required, min length 1). Identifier for this resource.
        - `token` (string, required, min length 1). Opaque token required by the target operation.
        - `action` (string, required). Action performed when the recipient activates this control. Values: `navigate`, `data_exchange`.
        - `screen` (string, min length 0). Flow screen opened when the recipient activates the message.
        - `dataJson` (string, min length 0, Serialized value: A non-null JSON object; arrays, scalar values, and invalid JSON are not accepted, UTF-8 size: At most `16` KiB (`16,384` bytes)). JSON object encoded as a string and supplied to the Flow interaction.
    - `callPermissionRequest` (object).
      - `callPermissionRequest` (object, required). Ask the person for permission to call them. Cloud API numbers only; WhatsApp limits how often you can ask.
        - `body` (string, required, length 1–1024). Why you want to call, shown above WhatsApp's allow and decline buttons. 1 to 1,024 Unicode characters.
    - `template` (object).
      - `template` (object, required). Structured template values for this one of.
        - `name` (string, required, min length 1). Human-readable name for this resource.
        - `language` (string, required, min length 2). Language or locale code used for this content.
        - `components` (array of any, max items 1000). Structured components that make up this message or template.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/send" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "conversation": {
    "phoneNumber": "+15550001111"
  },
  "content": {
    "text": "Hello"
  }
}'
```

### Responses

#### 200

Message sent successfully
- `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.
  - `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.
  - `status` (string, required). Upstream acceptance status. Delivery and read receipts arrive separately.
  - `type` (string, required). Type discriminator for this object.
  - `content` (object, required). Specifies content for this native sent message.
    - One of:
      - `text` (object).
        - `text` (string, required, min length 1). Text to send.
      - `image` (object).
        - `image` (object, required). Image attached to or representing this resource.
          - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
          - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
          - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
          - `caption` (string). Caption sent with the media.
          - `descriptor` (object). Specifies descriptor for this image.
            - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
            - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
            - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
            - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
            - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
            - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
            - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `image/jpeg`, `image/png`, or `image/webp`). MIME type of the plaintext file.
            - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
            - `width` (integer, range 1–65536). Width in pixels. Send with height.
            - `height` (integer, range 1–65536). Height in pixels. Send with width.
          - `quality` (string). `standard` (default) sends the image once, as supplied. `hd` requests a WhatsApp HD pair: a standard-quality message followed by the original. HD pairs are not sent yet; an `hd` request is sent once, as supplied, and the response has no `hdMessageId`. Values: `standard`, `hd`.
      - `video` (object).
        - `video` (object, required). Structured video values for this one of.
          - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
          - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
          - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
          - `caption` (string). Caption sent with the media.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `descriptor` (object). Specifies descriptor for this video.
            - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
            - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
            - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
            - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
            - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
            - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
            - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `video/mp4` or `video/3gpp`). MIME type of the plaintext file.
            - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
            - `width` (integer, range 1–65536). Width in pixels. Send with height.
            - `height` (integer, range 1–65536). Height in pixels. Send with width.
            - `seconds` (integer, range 0–86400). Duration in seconds.
      - `file` (object).
        - `file` (object, required). Structured file values for this one of.
          - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
          - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
          - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
          - `caption` (string). Caption sent with the media.
          - `filename` (string). Filename presented for the media attachment.
          - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `descriptor` (object). Specifies descriptor for this file.
            - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
            - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
            - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
            - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
            - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
            - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
            - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `application/pdf`, `text/plain`, or `application/vnd.openxmlformats-officedocument.wordprocessingml.document`). MIME type of the plaintext file.
            - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
      - `voice` (object).
        - `voice` (object, required). Voice-message content and metadata.
          - `url` (string (uri), format uri). URL of the media to send. Specify exactly one of url, base64 or descriptor.
          - `base64` (string, min length 1). Base64-encoded media bytes. Specify exactly one of url, base64 or descriptor.
          - `mimeType` (string, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the media. With descriptor, set descriptor.mimeType instead.
          - `caption` (string). Caption sent with the media.
          - `ptt` (boolean). Whether the audio is presented as a push-to-talk voice message.
          - `descriptor` (object). Specifies descriptor for this voice.
            - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
            - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
            - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
            - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
            - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
            - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
            - `mimeType` (string, required, length 1–255, pattern ^[ -~]+$, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). MIME type of the plaintext file.
            - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `seconds` (integer, range 0–86400). Duration in seconds.
            - `waveform` (string, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 voice-note waveform, 64 to 192 bytes.
      - `sticker` (object).
        - `sticker` (object, required). Structured sticker values for this one of.
          - Provide exactly one of: `url`, `base64` or `descriptor`.
          - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
          - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
          - `descriptor` (object). Specifies descriptor for this sticker.
            - When `mimeType` is `image/webp`: .
            - When `mimeType` is `application/was`, When `stickerType` is `lottie`: requires `stickerType`.
            - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
            - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
            - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
            - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
            - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
            - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
            - `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. Values: `image/webp`, `application/was`.
            - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
            - `width` (integer, range 1–65536). Width in pixels. Send with height.
            - `height` (integer, range 1–65536). Height in pixels. Send with width.
            - `stickerType` (string). Category assigned to sticker. Values: `static`, `animated`, `lottie`.
          - `emojis` (array of string, max items 10, item min length 1). Emojis associated with this sticker.
          - `accessibilityLabel` (string, min length 0). Specifies accessibility label for this sticker.
      - `stickerPack` (object).
        - `stickerPack` (object, required). Specifies sticker pack for this one of.
          - One of:
            - `Option 1` (object). Convert up to 100 image items. Items and an explicit tray share 64 MiB of input and 128 million source plus 512px output frame pixels. Preparation stops at the command deadline or 30 seconds, whichever comes first. Reduce dimensions, frame counts or item count if the pack exceeds these limits.
              - `id` (string, required, min length 1). Identifier for this resource.
              - `name` (string, required, min length 1). Human-readable name for this resource.
              - `publisher` (string, required, min length 1). Specifies publisher for this any of.
              - `description` (string, min length 0). Human-readable description of this resource.
              - `caption` (string, min length 0). Caption shown with the attached media.
              - `items` (array of object, required, items 1–100). Items associated with this any of.
              - `trayIcon` (object). Structured tray icon values for this any of.
                - Provide exactly one of: `url` or `base64`.
                - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
                - `base64` (string, length 1–28000000). Base64-encoded content with no data-URL prefix.
            - `descriptor` (object).
              - `id` (string, required, min length 1). Identifier for this resource.
              - `name` (string, required, min length 1). Human-readable name for this resource.
              - `publisher` (string, required, min length 1). Specifies publisher for this any of.
              - `description` (string, min length 0). Human-readable description of this resource.
              - `caption` (string, min length 0). Caption shown with the attached media.
              - `items` (array of object, required, items 1–100). Items associated with this any of.
              - `descriptor` (object, required). Structured descriptor values for this any of.
                - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
                - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
                - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
                - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
                - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
                - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
                - `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. Values: `application/zip`.
                - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
              - `trayIconFileName` (string, min length 1, pattern ^[^/\\:\x00]+$). Human-readable tray icon file name for this any of.
              - `thumbnailDescriptor` (object). Structured thumbnail descriptor values for this any of.
                - `url` (string, required, max length 2048, pattern ^https:\/\/[!-~]+$). Media URL returned by the upload.
                - `directPath` (string, required, max length 2048, pattern ^\/(?!\/)[!-~]+$). Direct path returned by the upload.
                - `mediaKey` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 32-byte media key you encrypted the file with.
                - `fileSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the plaintext file.
                - `fileEncSha256` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Base64 SHA-256 of the uploaded ciphertext and MAC.
                - `fileLength` (integer, required, range 1–2147483648). Plaintext file size in bytes.
                - `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. Values: `image/png`.
                - `mediaKeyTimestamp` (integer, range 1–1099511627776). Unix time in seconds when the media key was created.
                - `width` (integer, range 1–65536). Width in pixels. Send with height.
                - `height` (integer, range 1–65536). Height in pixels. Send with width.
            - `forwardMedia` (object).
              - `forwardMedia` (string, required, pattern ^[A-Za-z0-9+/]+={0,2}$). Specifies forward media for this any of.
      - `location` (object).
        - `location` (object, required). Structured location values for this one of.
          - `lat` (number, required, range -90–90). Latitude in decimal degrees.
          - `long` (number, required, range -180–180). Longitude in decimal degrees.
          - `address` (string). Display address for the location.
      - `poll` (object).
        - `poll` (object, required). Structured poll values for this one of.
          - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
          - `options` (array of string, required, items 2–12, item min length 1). Selectable options carried by this object.
          - `multiSelect` (boolean). Whether multi select.
      - `contact` (object).
        - `contact` (object, required). Structured contact values for this one of.
          - `vcard` (string, required, min length 1). Specifies vcard for this contact.
      - `requestPhoneNumber` (object).
        - `requestPhoneNumber` (object, required). Structured request phone number values for this one of.
      - `product` (object).
        - `product` (object, required). Structured product values for this one of.
          - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
          - `id` (string, required, min length 1). Identifier for this resource.
          - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
          - `description` (string, min length 0). Human-readable description of this resource.
          - `currencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code.
          - `priceAmount1000` (integer, required, range 0–9007199254740991). Price expressed in thousandths of the declared currency unit.
          - `salePriceAmount1000` (integer, range 0–9007199254740991). Discounted price expressed in thousandths of the declared currency unit.
          - `retailerId` (string, min length 0). Merchant-defined identifier for the catalog item.
          - `url` (string (uri), max length 2048, format uri). URL associated with this resource.
          - `imageCount` (integer, range 0–100). Number of images.
          - `image` (object). Image attached to or representing this resource.
            - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
            - `base64` (string, max length 87384). Base64-encoded content with no data-URL prefix.
            - `mimeType` (string, min length 0, 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.
          - `body` (string, min length 0). Primary text content shown to the recipient.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
      - `productList` (object).
        - `productList` (object, required). Structured product list values for this one of.
          - `businessOwnerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
          - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
          - `description` (string, min length 0). Human-readable description of this resource.
          - `buttonText` (string, required, min length 1). Text displayed on the action button.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `sections` (array of object, required, items 1–10, Total products: At most `30` product IDs across all sections, Product IDs: Every product ID must be unique across all sections). Ordered sections displayed in the interactive message.
            - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
            - `productIds` (array of string, required, items 1–30, item min length 1). Identifiers of the products included in this section.
      - `order` (object).
        - `order` (object, required). Structured order values for this one of.
          - `id` (string, required, min length 1). Identifier for this resource.
          - `thumbnailBase64` (string, max length 87384). Base64-encoded thumbnail content with no data-URL prefix.
          - `itemCount` (integer, required, range 1–100). Number of items.
          - `status` (string, required). Order status sent with this business order. Values: `inquiry`, `accepted`, `declined`.
          - `message` (string, min length 0). Outbound message content attached to this business order.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `sellerId` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
          - `token` (string, min length 0). Opaque token required by the target operation.
          - `totalAmount1000` (integer, required, range 0–9007199254740991). Order total expressed in thousandths of the declared currency unit.
          - `totalCurrencyCode` (string, required, pattern ^[A-Z]{3}$). ISO 4217 currency code used for the order total.
          - `catalogType` (string, min length 0). Category assigned to catalog.
      - `list` (object).
        - `list` (object, required). On an official WhatsApp Business number, `title` is the header (at most 60 characters) and `description` the body (at most 1,024 characters); without `description`, `title` is the body. There, each section title allows at most 24 characters and is required when the list has more than one section, lists allow at most 10 rows in total, row titles at most 24 characters, row IDs at most 200, row descriptions at most 72, `buttonText` at most 20 and `footer` at most 60. Every number also limits `buttonText` to 64 UTF-8 bytes, row `id` to 256 bytes and `title` and `description` to 256 and 4,096 bytes, so multibyte text reaches those byte limits before the character limits. Content outside any limit returns `400`.
          - `title` (string, required, min length 1). Human-readable title shown to the recipient or operator.
          - `description` (string, min length 0). Human-readable description of this resource.
          - `buttonText` (string, required, min length 1). Text displayed on the action button.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `sections` (array of object, required, items 1–10, Total rows: At most `30` rows across all sections, Row IDs: Every row ID must be unique across all sections). Ordered sections displayed in the interactive message.
            - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
            - `rows` (array of object, required, items 1–30). Rows associated with this section.
      - `carousel` (object).
        - `carousel` (object, required). Linked Devices only: one message with 2–10 image/video cards and native buttons per card. Each card accepts up to ten replies or three CTAs without mixing; reply IDs are unique across cards. Combined media is bounded to 50 MiB. Official approved carousel templates use content.template instead.
          - `body` (string, required, min length 1). Primary text content shown to the recipient.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `cards` (array of object, required, items 2–10). Cards associated with this carousel.
            - One of:
              - `image` (object).
              - `video` (object).
      - `buttons` (object).
        - `buttons` (object, required). Linked Devices support up to 10 total buttons and at most 3 CTAs. Replies may be mixed with URL and call buttons using a hydrated template; copy/catalog buttons cannot be mixed with replies. An optional image, video or document header requires exactly one URL or base64 source and cannot be combined with a title. On an official WhatsApp Business number, media headers require an approved template, and at most 3 `reply` buttons are sent; other button types return `501`. There, `body` allows at most 1,024 characters, `title` and `footer` at most 60, and each button needs a unique `id` and a unique `text` of at most 20 characters. Every number also limits each button `id` to 256 UTF-8 bytes. Content outside any limit returns `400`.
          - `media` (object). Reference to the media attached to this message.
            - `url` (string (uri), max length 4096, format uri). URL associated with this resource.
            - `base64` (string, length 1–70000000). Base64-encoded content with no data-URL prefix.
            - `mimeType` (string, min length 0, 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.
            - `type` (string, required). Type discriminator for this object. Values: `image`, `video`, `document`.
            - `filename` (string, min length 0). Filename presented for the media attachment.
            - `thumbnail` (string, length 4–21848). Base64-encoded JPEG preview shown before the media downloads, at most 16 KiB. Linked Devices numbers only.
          - `title` (string, min length 0). Human-readable title shown to the recipient or operator.
          - `body` (string, required, min length 1). Primary text content shown to the recipient.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `buttons` (array of object, required, items 1–10). Interactive buttons displayed with the message.
            - One of:
              - `url` (object).
              - `call` (object).
              - `reply` (object).
              - `copy` (object).
              - `catalog` (object).
      - `addressMessage` (object).
        - `addressMessage` (object, required). Structured address message values for this one of.
          - `body` (string, required, min length 1). Primary text content shown to the recipient.
          - `buttonText` (string, min length 1). Text displayed on the action button.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `country` (string, pattern ^[A-Z]{2}$). ISO 3166-1 alpha-2 country code.
      - `flow` (object).
        - `flow` (object, required). Structured flow values for this one of.
          - When `action` is `navigate`: requires `screen`.
          - When `action` is `data_exchange`: `screen` and `dataJson` not accepted.
          - `body` (string, required, min length 1). Primary text content shown to the recipient.
          - `buttonText` (string, required, min length 1). Text displayed on the action button.
          - `footer` (string, min length 0). Supplementary footer text shown below the primary content.
          - `id` (string, required, min length 1). Identifier for this resource.
          - `token` (string, required, min length 1). Opaque token required by the target operation.
          - `action` (string, required). Action performed when the recipient activates this control. Values: `navigate`, `data_exchange`.
          - `screen` (string, min length 0). Flow screen opened when the recipient activates the message.
          - `dataJson` (string, min length 0, Serialized value: A non-null JSON object; arrays, scalar values, and invalid JSON are not accepted, UTF-8 size: At most `16` KiB (`16,384` bytes)). JSON object encoded as a string and supplied to the Flow interaction.
      - `callPermissionRequest` (object).
        - `callPermissionRequest` (object, required). Ask the person for permission to call them. Cloud API numbers only; WhatsApp limits how often you can ask.
          - `body` (string, required, length 1–1024). Why you want to call, shown above WhatsApp's allow and decline buttons. 1 to 1,024 Unicode characters.
      - `template` (object).
        - `template` (object, required). Structured template values for this one of.
          - `name` (string, required, min length 1). Human-readable name for this resource.
          - `language` (string, required, min length 2). Language or locale code used for this content.
          - `components` (array of any, max items 1000). Structured components that make up this message or template.
  - `mediaId` (string). Identifier for the media.
  - `hdMessageId` (string, pattern ^[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.

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,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string"
    },
    "conversation": {
      "id": "739182640518203"
    },
    "timestamp": "2026-09-22T12:00:00Z",
    "status": "string",
    "type": "string",
    "content": {
      "text": "string"
    }
  }
}
```

#### 202

Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `requestId` (string (uuid), required, format uuid). Identifier used to correlate this request across systems.

Headers:

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

```json
{
  "success": true,
  "data": {
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

Invalid request
- `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

Invalid credential
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"
}
```

#### 402

`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

Missing scope or resource access
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

`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`)
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": "unsupported_for_connection",
    "message": "The session's connection does not support this call operation.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#unsupported-for-connection"
}
```

#### 413

The JSON request exceeds 72 MiB, or decoded media exceeds its size limit
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "media_too_large",
    "message": "The message or media exceeds the size limit.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#media-too-large"
}
```

#### 422

The supplied media URL could not be fetched. 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": "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"
}
```

#### 429

`call_permission_request_limited`: WhatsApp limits how often this person can be asked for call permission.
Same fields as 400.

Headers:

- `Retry-After` (integer, min 1). Seconds until the limiting window resets, when WhatsApp reports a reset time.
- `Polymorfa-RateLimit-Reason` (string). The limit that blocked the request. Values: `call_permission_request`.
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "call_permission_request_limited",
    "message": "WhatsApp limits how often this number can ask this person for call permission. Follow Retry-After when supplied.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#call-permission-request-limited"
}
```

#### 500

Unexpected service failure
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"
}
```

#### 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
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "operation_not_supported",
    "message": "This operation is not supported.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#operation-not-supported"
}
```

#### 502

Messaging provider failure
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}
```

#### 503

Session 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
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": "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"
}
```

#### 504

Result unknown after timeout
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}
```

## Send seen

`POST https://api.polymorfa.com/messaging/{session}/messages/seen` (Messaging API)

Required permission: `messages:write`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

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

### Body

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - Provide one of: `id`, `phoneNumber` or `bsuid`.
  - `id` (string, 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}$). International phone number to look up, including + and the country code. WhatsApp determines the recipient account.
  - `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). Known username. This field alone does not select a conversation.
- `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/seen" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Seen marker confirmed by the messaging backend
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation.

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,
  "data": {
    "status": "string"
  }
}
```

#### 202

Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `requestId` (string (uuid), required, format uuid). Identifier used to correlate this request across systems.

Headers:

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

```json
{
  "success": true,
  "data": {
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

Invalid request
- `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

Invalid credential
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"
}
```

#### 402

`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

Missing scope or resource access
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

Unexpected service failure
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"
}
```

#### 502

Messaging provider failure
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}
```

#### 503

Session or service 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"
}
```

#### 504

Result unknown after timeout
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}
```

## Send reaction

`POST https://api.polymorfa.com/messaging/{session}/messages/react` (Messaging API)

Required permission: `messages:write`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

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

### 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

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - Provide one of: `id`, `phoneNumber` or `bsuid`.
  - `id` (string, 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}$). International phone number to look up, including + and the country code. WhatsApp determines the recipient account.
  - `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). Known username. This field alone does not select a conversation.
- `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
- `reaction` (string, required). Reaction applied to the referenced message.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/react" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Reaction sent
- `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.
  - `timestamp` (string (date-time), required, format date-time). ISO 8601 timestamp associated with this event.
  - `status` (string, required). Upstream acceptance status. Delivery and read receipts arrive separately.

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,
  "data": {
    "id": "739182640518203",
    "whatsapp_ids": {
      "linked_devices": "string"
    },
    "conversation": {
      "id": "739182640518203"
    },
    "timestamp": "2026-09-22T12:00:00Z",
    "status": "string"
  }
}
```

#### 202

Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `requestId` (string (uuid), required, format uuid). Identifier used to correlate this request across systems.

Headers:

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

```json
{
  "success": true,
  "data": {
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

Invalid request
- `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

Invalid credential
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"
}
```

#### 402

`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

Missing scope or resource access
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

Unexpected service failure
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"
}
```

#### 502

Messaging provider failure
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}
```

#### 503

Session 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
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": "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"
}
```

#### 504

Result unknown after timeout
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}
```

## Set typing

`POST https://api.polymorfa.com/messaging/{session}/messages/typing` (Messaging API)

Required permission: `messages:write`

**Protocols:** Linked Device API · Meta Cloud API

**Required scope:** `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

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

### Body

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - Provide one of: `id`, `phoneNumber` or `bsuid`.
  - `id` (string, 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}$). International phone number to look up, including + and the country code. WhatsApp determines the recipient account.
  - `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). Known username. This field alone does not select a conversation.
- `state` (string, required). Typing state to publish for the target conversation. Values: `typing`, `recording`, `paused`.
- `id` (string, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/typing" \
  -H "Authorization: Bearer <POLYMORFA_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"
}'
```

### Responses

#### 200

Typing state confirmed by the messaging backend
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation.

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,
  "data": {
    "status": "string"
  }
}
```

#### 202

Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `requestId` (string (uuid), required, format uuid). Identifier used to correlate this request across systems.

Headers:

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

```json
{
  "success": true,
  "data": {
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

Invalid request
- `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

Invalid credential
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"
}
```

#### 402

`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

Missing scope or resource access
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

Routing or operation conflict
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Unexpected service failure
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"
}
```

#### 501

`operation_not_supported`: official WhatsApp Business numbers support only the `typing` state
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "operation_not_supported",
    "message": "This operation is not supported.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#operation-not-supported"
}
```

#### 502

Messaging provider failure
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}
```

#### 503

Session or service 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"
}
```

#### 504

Result unknown after timeout
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}
```

## Star message

`POST https://api.polymorfa.com/messaging/{session}/messages/star` (Messaging API)

Required permission: `messages:write`

**Protocols:** Linked Device API

**Required scope:** `messages:write`

### Path parameters

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

### Body

- `conversation` (object, required). Public conversation identifier or E.164 phone number.
  - Provide one of: `id`, `phoneNumber` or `bsuid`.
  - `id` (string, 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}$). International phone number to look up, including + and the country code. WhatsApp determines the recipient account.
  - `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). Known username. This field alone does not select a conversation.
- `id` (string, required, pattern ^[1-9][0-9]{0,18}$). Opaque Polymorfa resource ID. Keep this value as a string.
- `star` (boolean, required). Whether star.

### Request

```bash
curl -X POST "https://api.polymorfa.com/messaging/<session>/messages/star" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Star status updated
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `status` (string, required). Current status of this resource or operation.

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,
  "data": {
    "status": "string"
  }
}
```

#### 202

Accepted for asynchronous processing in response to `Prefer: respond-async`; the result is not included
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `requestId` (string (uuid), required, format uuid). Identifier used to correlate this request across systems.

Headers:

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

```json
{
  "success": true,
  "data": {
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}
```

#### 400

Invalid request
- `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

Invalid credential
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"
}
```

#### 402

`billing_credit_required`: credit is unavailable for this number. Add credit or review team billing.
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "billing_error",
    "code": "billing_credit_required",
    "message": "Credit is unavailable for this number. Add credit or review team billing.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#billing-credit-required"
}
```

#### 403

Missing scope or resource access
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

Routing or operation conflict
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Unexpected service failure
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"
}
```

#### 502

Messaging provider failure
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "upstream_error",
    "code": "upstream_failure",
    "message": "The messaging provider could not complete the request.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#upstream-failure"
}
```

#### 503

Session or service 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"
}
```

#### 504

Result unknown after timeout
Same fields as 400.

Headers:

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

```json
{
  "error": {
    "type": "api_error",
    "code": "result_unknown",
    "message": "The result was not obtained before the deadline. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#result-unknown"
}
```
