# polymorfa message

> Send messages and perform message actions.

## Commands

- [polymorfa message delete](https://docs.polymorfa.com/cli/message/delete): Delete a message you sent for everyone in the conversation.
- [polymorfa message edit](https://docs.polymorfa.com/cli/message/edit): Replace the text of a message you sent.
- [polymorfa message mark-seen](https://docs.polymorfa.com/cli/message/mark-seen): Mark a message as seen.
- [polymorfa message operation-status](https://docs.polymorfa.com/cli/message/operation-status): Read the outcome of a message operation without sending again.
- [polymorfa message react](https://docs.polymorfa.com/cli/message/react): React to a message.
- [polymorfa message send audio](https://docs.polymorfa.com/cli/message/send-audio): Send audio or a voice note from a local file or URL.
- [polymorfa message send buttons](https://docs.polymorfa.com/cli/message/send-buttons): Send an interactive message with reply, URL, call, or copy-code buttons.
- [polymorfa message send contact](https://docs.polymorfa.com/cli/message/send-contact): Send a contact card built from flags or read from a vCard file.
- [polymorfa message send document](https://docs.polymorfa.com/cli/message/send-document): Send a document from a local file or URL.
- [polymorfa message send image](https://docs.polymorfa.com/cli/message/send-image): Send an image from a local file or URL.
- [polymorfa message send list](https://docs.polymorfa.com/cli/message/send-list): Send an interactive list message with selectable rows.
- [polymorfa message send location](https://docs.polymorfa.com/cli/message/send-location): Send a location pin.
- [polymorfa message send order](https://docs.polymorfa.com/cli/message/send-order): Send a Brazil order with Pix, payment link or boleto instructions (beta; Official API Numbers only). Polymorfa relays the order and does not process the payment. Makes one attempt.
- [polymorfa message send order-status](https://docs.polymorfa.com/cli/message/send-order-status): Update a Brazil order sent with "message send order" (beta). Send a payment status only after your payment provider confirms it; captured shows the order as paid. Makes one attempt.
- [polymorfa message send poll](https://docs.polymorfa.com/cli/message/send-poll): Send a poll.
- [polymorfa message send template](https://docs.polymorfa.com/cli/message/send-template): Send an approved message template by name and language.
- [polymorfa message send text](https://docs.polymorfa.com/cli/message/send-text): Send a text message.
- [polymorfa message send video](https://docs.polymorfa.com/cli/message/send-video): Send a video from a local file or URL.
- [polymorfa message star](https://docs.polymorfa.com/cli/message/star): Star or unstar a message.
- [polymorfa message typing](https://docs.polymorfa.com/cli/message/typing): Set typing for a chat. Official Numbers require --id and --state typing; the inbound message is marked read.

## polymorfa message delete

Delete a message you sent for everyone in the conversation.

### Usage

```bash
polymorfa message delete MESSAGE [flags]
```

### Arguments

- `MESSAGE` (required). Message ID.

### Flags

- `--chat <value>` (value, required). Conversation that contains the message.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--session <value>` (value, required). Messaging session ID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--yes` (boolean). Confirm deletion without an interactive prompt.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message delete 740000000001 --session session_123 --chat 730000000001 --yes
```

## polymorfa message edit

Replace the text of a message you sent.

### Usage

```bash
polymorfa message edit MESSAGE [flags]
```

### Arguments

- `MESSAGE` (required). Message ID.

### Flags

- `--body <value>` (value, required). Replacement text.
- `--chat <value>` (value, required). Conversation that contains the message.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--session <value>` (value, required). Messaging session ID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message edit 740000000001 --session session_123 --chat 730000000001 --body "Corrected text"
```

## polymorfa message mark-seen

Mark a message as seen.

### Usage

```bash
polymorfa message mark-seen MESSAGE [flags]
```

### Arguments

- `MESSAGE` (required). Message ID.

### Flags

- `--chat <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--idempotency-key <value>` (value). Safely identify retries of this seen receipt.
- `--session <value>` (value, required). Messaging session ID.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa message operation-status

Read the outcome of a message operation without sending again.

### Usage

```bash
polymorfa message operation-status OPERATION [flags]
```

### Arguments

- `OPERATION` (required). Operation ID from the send response.

### Flags

- `--session <value>` (value, required). Number session name.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa message react

React to a message.

### Usage

```bash
polymorfa message react MESSAGE [flags]
```

### Arguments

- `MESSAGE` (required). Message ID.

### Flags

- `--chat <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--emoji <value>` (value, required). Reaction emoji.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--session <value>` (value, required). Messaging session ID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa message send audio

Send audio or a voice note from a local file or URL.

### Usage

```bash
polymorfa message send audio [flags]
```

### Flags

- `--file <value>` (value). Local file to upload with the message.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--max-bytes <value>` (value). Reject local files larger than this many bytes. Default: `104857600`.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--mime-type <value>` (value). MIME type. Inferred from the file extension when omitted.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--url <value>` (value). Public http or https URL the API fetches the media from.
- `--voice` (boolean). Send as a push-to-talk voice note instead of an audio file.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send audio --session session_123 --to +15551234567 --file ./note.ogg
```

```bash
polymorfa message send audio --session session_123 --to +15551234567 --url https://example.com/note.ogg
```

## polymorfa message send buttons

Send an interactive message with reply, URL, call, or copy-code buttons.

### Usage

```bash
polymorfa message send buttons [flags]
```

### Flags

- `--body <value>` (value, required). Message body.
- `--button <value>` (value, required, repeatable). Button as reply:<id>=<text>, url:<text>=<url>, call:<text>=<+E.164>, or copy:<text>=<code>. Repeat for several buttons.
- `--footer <value>` (value). Footer text.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--title <value>` (value). Header title.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send buttons --session session_123 --to +15551234567 --body "Confirm your order?" --button reply:yes=Yes --button reply:no=No
```

```bash
polymorfa message send buttons --session session_123 --to +15551234567 --body "Track it" --button "url:Open tracking=https://example.com/t/123"
```

## polymorfa message send contact

Send a contact card built from flags or read from a vCard file.

### Usage

```bash
polymorfa message send contact [flags]
```

### Flags

- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--name <value>` (value). Contact display name.
- `--organization <value>` (value). Contact organization.
- `--phone <value>` (value, repeatable). Contact E.164 phone number. Repeat for several numbers.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--vcard <value>` (value). Read one vCard from a file.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send contact --session session_123 --to +15551234567 --name "Ada Lovelace" --phone +15557654321
```

```bash
polymorfa message send contact --session session_123 --to +15551234567 --vcard ./ada.vcf
```

## polymorfa message send document

Send a document from a local file or URL.

### Usage

```bash
polymorfa message send document [flags]
```

### Flags

- `--caption <value>` (value). Caption sent with the document.
- `--file <value>` (value). Local file to upload with the message.
- `--filename <value>` (value). File name shown to the recipient. Defaults to the local file name.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--max-bytes <value>` (value). Reject local files larger than this many bytes. Default: `104857600`.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--mime-type <value>` (value). MIME type. Inferred from the file extension when omitted.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--url <value>` (value). Public http or https URL the API fetches the media from.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send document --session session_123 --to +15551234567 --file ./invoice.pdf
```

```bash
polymorfa message send document --session session_123 --to +15551234567 --url https://example.com/invoice.pdf
```

## polymorfa message send image

Send an image from a local file or URL.

### Usage

```bash
polymorfa message send image [flags]
```

### Flags

- `--caption <value>` (value). Caption sent with the image.
- `--file <value>` (value). Local file to upload with the message.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--max-bytes <value>` (value). Reject local files larger than this many bytes. Default: `104857600`.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--mime-type <value>` (value). MIME type. Inferred from the file extension when omitted.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--url <value>` (value). Public http or https URL the API fetches the media from.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send image --session session_123 --to +15551234567 --file ./photo.jpg
```

```bash
polymorfa message send image --session session_123 --to +15551234567 --url https://example.com/photo.jpg
```

## polymorfa message send list

Send an interactive list message with selectable rows.

### Usage

```bash
polymorfa message send list [flags]
```

### Flags

- `--button-text <value>` (value, required). Label of the button that opens the list.
- `--description <value>` (value). Body text above the button.
- `--footer <value>` (value). Footer text.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--row <value>` (value, required, repeatable). Row as [<section>/]<id>=<title>[|<description>]. Repeat for several rows; rows with the same section are grouped.
- `--session <value>` (value, required). Messaging session ID.
- `--title <value>` (value, required). List title.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send list --session session_123 --to +15551234567 --title "Pick a slot" --button-text Choose --row "Morning/am9=9:00" --row "Afternoon/pm2=14:00|Near the office"
```

## polymorfa message send location

Send a location pin.

### Usage

```bash
polymorfa message send location [flags]
```

### Flags

- `--address <value>` (value). Address shown with the pin.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--lat <value>` (value, required). Latitude in degrees.
- `--long <value>` (value, required). Longitude in degrees. Use --long=-0.12 for negative values.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send location --session session_123 --to +15551234567 --lat 51.5007 --long=-0.1246 --address "Westminster, London"
```

## polymorfa message send order

Send a Brazil order with Pix, payment link or boleto instructions (beta; Official API Numbers only). Polymorfa relays the order and does not process the payment. Makes one attempt.

### Usage

```bash
polymorfa message send order [flags]
```

### Flags

- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key to check a previous attempt (24-hour retention).
- `--order <value>` (value, required). Read the orderDetails JSON object (referenceId, type, body, currency, totalAmount, paymentSettings, optional order) from a file or stdin (-).
- `--session <value>` (value, required). Messaging session ID of an Official API Number.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID of the buyer.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send order --session session_123 --to +5511987654321 --order order.json
```

```bash
cat order.json | polymorfa message send order --session session_123 --to +5511987654321 --order - --idempotency-key order-1522
```

## polymorfa message send order-status

Update a Brazil order sent with "message send order" (beta). Send a payment status only after your payment provider confirms it; captured shows the order as paid. Makes one attempt.

### Usage

```bash
polymorfa message send order-status [flags]
```

### Flags

- `--body <value>` (value, required). Message text.
- `--footer <value>` (value). Footer text.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key to check a previous attempt (24-hour retention).
- `--order-description <value>` (value). Order status detail, such as a cancellation reason.
- `--order-status <value>` (value). New order status. Values: `pending`, `processing`, `partially_shipped`, `shipped`, `completed`, `canceled`.
- `--payment-status <value>` (value). Payment status confirmed by your payment provider. Values: `pending`, `captured`, `failed`.
- `--payment-timestamp <value>` (value). Payment time in Unix seconds.
- `--reference-id <value>` (value, required). The referenceId of the order.
- `--session <value>` (value, required). Messaging session ID of an Official API Number.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID of the buyer.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send order-status --session session_123 --to +5511987654321 --reference-id order-1522 --body "Payment received" --order-status processing --payment-status captured
```

## polymorfa message send poll

Send a poll.

### Usage

```bash
polymorfa message send poll [flags]
```

### Flags

- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--multi-select` (boolean). Allow voters to choose more than one option.
- `--option <value>` (value, required, repeatable). Poll option. Repeat for 2 to 12 options.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--title <value>` (value, required). Poll question.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send poll --session session_123 --to 730000000001 --title "Lunch?" --option Pizza --option Sushi
```

## polymorfa message send template

Send an approved message template by name and language.

### Usage

```bash
polymorfa message send template [flags]
```

### Flags

- `--components <value>` (value). Read the template components JSON array from a file or stdin (-).
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--language <value>` (value, required). Template language code, such as en_US.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--name <value>` (value, required). Template name.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send template --session session_123 --to +15551234567 --name order_update --language en_US
```

```bash
polymorfa message send template --session session_123 --to +15551234567 --name order_update --language en_US --components components.json
```

## polymorfa message send text

Send a text message.

### Usage

```bash
polymorfa message send text [flags]
```

### Flags

- `--body <value>` (value, required). Text to send.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa message send video

Send a video from a local file or URL.

### Usage

```bash
polymorfa message send video [flags]
```

### Flags

- `--caption <value>` (value). Caption sent with the video.
- `--file <value>` (value). Local file to upload with the message.
- `--forwarded` (boolean). Mark the message as forwarded.
- `--idempotency-key <value>` (value). Idempotency-Key header. Generated per invocation when omitted; reuse an explicit key across process retries (24-hour retention).
- `--max-bytes <value>` (value). Reject local files larger than this many bytes. Default: `104857600`.
- `--mention <value>` (value, repeatable). Mention a Polymorfa user ID. Repeat for multiple recipients.
- `--mime-type <value>` (value). MIME type. Inferred from the file extension when omitted.
- `--reply-to <value>` (value). Polymorfa message ID to quote in the reply.
- `--session <value>` (value, required). Messaging session ID.
- `--to <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--transport <value>` (value). Send using routing rules (auto), Linked Devices, or Official API. Explicit choices never fall back. Values: `auto`, `linked_devices`, `official_api`.
- `--url <value>` (value). Public http or https URL the API fetches the media from.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa message send video --session session_123 --to +15551234567 --file ./clip.mp4
```

```bash
polymorfa message send video --session session_123 --to +15551234567 --url https://example.com/clip.mp4
```

## polymorfa message star

Star or unstar a message.

### Usage

```bash
polymorfa message star MESSAGE [flags]
```

### Arguments

- `MESSAGE` (required). Message ID.

### Flags

- `--chat <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--idempotency-key <value>` (value). Safely identify retries of this star update.
- `--remove` (boolean). Remove the existing star.
- `--session <value>` (value, required). Messaging session ID.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

## polymorfa message typing

Set typing for a chat. Official Numbers require --id and --state typing; the inbound message is marked read.

### Usage

```bash
polymorfa message typing [flags]
```

### Flags

- `--chat <value>` (value, required). Conversation ID, E.164 phone number, or BSUID.
- `--id <value>` (value). Inbound message ID. Required on Official Numbers; marks the message read and shows typing for up to 25 seconds.
- `--idempotency-key <value>` (value). Request identifier. The API does not deduplicate typing updates by this header.
- `--session <value>` (value, required). Messaging session ID.
- `--state <value>` (value, required). Typing state. Values: `typing`, `recording`, `paused`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).
