# Send messages

> Send text, media, interactive and template messages from a connected Number.

One request sends one message: name the conversation, put exactly one message
kind in `content`, and Polymorfa sends it from the Number in the path. The
response returns the message's ID, and delivery receipts arrive later as
events.

## Before you begin

- A connected [Number](https://docs.polymorfa.com/numbers) and its Number ID.
- A server credential with `messages:write`. Keep it on your server; browsers
  use [client tokens](https://docs.polymorfa.com/development/client-tokens).
- A webhook or event stream for delivery events. See
  [Receive messages](https://docs.polymorfa.com/messaging/receive).

A test number sends only to other active test numbers in the same project.
Address them by `phoneNumber`.

## Send a text message

**API:**

Call [Send message](https://docs.polymorfa.com/api/messages/send-message):

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/$SESSION/messages/send" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c2b8e-4f7a-4f5e-9d1b-1c2d3e4f5a6b" \
  -d '{
    "conversation": { "phoneNumber": "+15550001111" },
    "content": { "text": "Your order has shipped." }
  }'
```

```typescript TypeScript
const sent = await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: { text: "Your order has shipped." },
});

console.log(sent.data.data.id, sent.data.data.status);
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "text",
    "text": { "body": "Your order has shipped." }
  }'
```

*TypeScript:*

`send` creates an idempotency key for each call, so its automatic retries
never send twice. Pass your own `idempotencyKey` to stay safe across process
restarts.

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Supported.

[Send a message](https://docs.polymorfa.com/api/graph/messages/send-a-message) sends text,
media, location, contact and reaction messages with Meta's request and
response shapes. `$PHONE_NUMBER_ID` is the Number's phone number ID; see
[Address a Number](https://docs.polymorfa.com/api/graph#address-a-number).

The response's `data` holds the sent message: its Polymorfa `id`,
`whatsapp_ids`, `conversation`, `timestamp`, `type`, `content` and `status`.
`status` reports that WhatsApp accepted the message; delivery and read
receipts arrive separately. Keep `id` to reply, react, edit or match later
events. See [Conversation identity and message IDs](https://docs.polymorfa.com/messaging/ids).

## Choose who receives it

`conversation` takes `id`, `phoneNumber` or `bsuid`. Send at least one. If you
send several, they must already identify the same conversation.

- `phoneNumber`: E.164, including `+`.
- `id`: the conversation ID from an earlier message or event. Use it to reply
  to someone whose phone number is hidden.
- `bsuid`: a business-scoped user ID.

In the Graph API, `to` takes a phone number. `recipient` takes a
business-scoped user ID on Meta Cloud API Numbers only; when both are present,
`to` is used. Parent business-scoped user IDs are not accepted.

A username alone is not a destination. See
[Conversation identity and message IDs](https://docs.polymorfa.com/messaging/ids#conversation-identity)
for how each selector routes.

## Choose the content

`content` holds exactly one message kind. Do not send `type` or put message
fields at the request root; requests with no content, several kinds or
misplaced fields fail validation.

| Kind | Field |
| --- | --- |
| Text | `content.text` |
| Image, video, file, voice note | `content.image`, `content.video`, `content.file`, `content.voice` |
| Location | `content.location` |
| Contact card | `content.contact` |
| Poll | `content.poll` |
| Reply buttons and lists | `content.buttons`, `content.list` |
| Products, product lists and orders | `content.product`, `content.productList`, `content.order` |
| Address request | `content.addressMessage` |
| WhatsApp Flow | `content.flow` |
| Phone-number request | `content.requestPhoneNumber` |
| Call permission request | `content.callPermissionRequest` |
| Template | `content.template` |

For example, a location:

```json
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "location": { "lat": 33.89, "long": 35.50, "address": "Beirut" }
  }
}
```

[Send message](https://docs.polymorfa.com/api/messages/send-message#send-message-body) lists every field
of every kind.

### Media

Put the media's URL or base64 bytes, and an optional caption, inside
`content.image`, `content.video`, `content.file` or `content.voice`. Supply
exactly one source. Set `voice.ptt` to `true` for a voice note. Images get their
size and a preview automatically; see
[Media previews and HD images](https://docs.polymorfa.com/messaging/media) for video and document
previews and the `quality` option.

**API:**

```json JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "file": { "url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }
  }
}
```

```typescript TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: {
    file: { url: "https://example.com/invoice.pdf", filename: "invoice.pdf" },
  },
});
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "document",
    "document": { "link": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }
  }'
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Supported.

Graph media objects (`image`, `video`, `audio`, `document`, `sticker`) take a
`link` or the `id` of a file you uploaded with
[Upload media](https://docs.polymorfa.com/api/graph/media/upload-media), which needs
`media:manage`.

### Interactive messages

Reply buttons, for example:

**API:**

```json JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "buttons": {
      "body": "Confirm your appointment?",
      "buttons": [
        { "type": "reply", "text": "Confirm", "id": "confirm" },
        { "type": "reply", "text": "Reschedule", "id": "reschedule" }
      ]
    }
  }
}
```

```typescript TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: {
    buttons: {
      body: "Confirm your appointment?",
      buttons: [
        { type: "reply", text: "Confirm", id: "confirm" },
        { type: "reply", text: "Reschedule", id: "reschedule" },
      ],
    },
  },
});
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "body": { "text": "Confirm your appointment?" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "confirm", "title": "Confirm" } },
          { "type": "reply", "reply": { "id": "reschedule", "title": "Reschedule" } }
        ]
      }
    }
  }'
```

*TypeScript:*

Your editor lists each kind's fields from the `SendMessageRequest` type.

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Partly supported.

On Linked Devices Numbers, [Send a message](https://docs.polymorfa.com/api/graph/messages/send-a-message)
translates reply buttons, lists and HTTPS call-to-action URLs to native
messages. Interactive forms with no native equivalent, and catalog product
sends, return capability error `131026`.

| Input | Rule |
| --- | --- |
| Product-list sections | At most 30 product IDs across all sections; every product ID is unique. |
| List sections | At most 30 rows across all sections; every row ID is unique. |
| Linked Device buttons | Up to 10 total controls and up to 3 CTAs (`url`, `call`, `copy`, `catalog`). Replies may mix with URL/call controls; copy/catalog controls cannot mix with replies. |
| Linked Device carousel | 2–10 image/video cards. Each card accepts 1–10 reply buttons or 1–3 CTAs, without mixing replies and CTAs. Reply IDs must be unique across all cards. |
| Meta Cloud API buttons | Direct `content.buttons` sends accept 1–3 `reply` buttons; other controls and media headers return `501`. For those controls, send an approved `content.template` whose components define them. `content.buttons` is not merged into a template message. |
| `content.flow.dataJson` | A JSON object encoded as a string, at most 16 KiB (16,384 UTF-8 bytes). Arrays, scalar values and invalid JSON are rejected. |
| `content.addressMessage` on Meta Cloud API | `body` and a two-letter uppercase `country` code. |
| `content.addressMessage` on Linked Devices | `body` and a nonblank `buttonText`. |

Button messages accept an optional `media` header (`type: "image"`, `"video"`
or `"document"`) with exactly one `url` or `base64` source. A media header and
`title` cannot be combined. Keep reply IDs stable so incoming button responses
can be matched to the original choice. Media buttons and each complete carousel
use one message send; they are not split into additional messages. Meta Cloud API
media controls and carousels require an approved template through the template
route. Client rendering can differ between Web and phones.

`content.carousel` holds a `body`, an optional `footer` and 2–10 `cards`. Each
card holds a `body`, its `buttons` and exactly one `image` or `video`. Supply
exactly one `url` or `base64` source for each card's media. Combined source media
across all cards must not exceed 50 MiB. Invalid card, button or media combinations
fail validation. Cards have no `footer` of their own.

Products and product lists use `businessOwnerId`; orders use `sellerId`. Both
are public identity IDs for a business with a known phone number. Catalog
responses expose the owner's ID in `belongsTo`. Product and collection IDs stay
their original commerce identifiers. See [Catalogs and commerce](https://docs.polymorfa.com/numbers/catalog).

`requestPhoneNumber` requires the contact's `conversation.id`. See
[Hidden phone numbers](https://docs.polymorfa.com/messaging/user-identities#hidden-phone-numbers).

### Templates

`content.template` takes the template's `name`, `language` and `components`.
The template must be approved in that language, or the send fails with
`template_not_approved`. On a Meta Cloud API Number, a free-form message sent
more than 24 hours after the customer last wrote fails with
`conversation_window_closed`; send a template instead. See
[Message templates](https://docs.polymorfa.com/messaging/templates).

**API:**

```json JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "template": {
      "name": "order_ready",
      "language": "en_US",
      "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "Ada" }] }]
    }
  }
}
```

```typescript TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: {
    template: {
      name: "order_ready",
      language: "en_US",
      components: [{ type: "body", parameters: [{ type: "text", text: "Ada" }] }],
    },
  },
});
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "template",
    "template": {
      "name": "order_ready",
      "language": { "code": "en_US" },
      "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "Ada" }] }]
    }
  }'
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Not supported.

[Send a message](https://docs.polymorfa.com/api/graph/messages/send-a-message) sends a template
Meta approved for the Number's WhatsApp Business Account. Linked Devices
Numbers return capability error `131026`.

## Reply, mention and forward

`quotedMessage`, `mentions` and `isForwarded` sit beside `conversation` and
`content`.

**API:**

```json JSON
{
  "conversation": { "id": "739182640518203" },
  "content": { "text": "Thanks, we got it." },
  "quotedMessage": { "id": "739182640518977" }
}
```

```typescript TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { id: "<conversation-id>" },
  content: { text: "Thanks, we got it." },
  quotedMessage: { id: "<message-id>" },
});
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "text",
    "context": { "message_id": "'"$MESSAGE_ID"'" },
    "text": { "body": "Thanks, we got it." }
  }'
```

**Graph API:** Meta Cloud API Numbers: Partly supported. Linked Devices Numbers: Partly supported.

`context.message_id` quotes the message. Mentions and the forwarded flag are
not offered through the Graph API.

Set `isForwarded: true` to mark a message as forwarded.

## Act on a message

Message actions use `id` for the message and `conversation` for its chat:

**API:**

```json JSON
{
  "conversation": { "id": "739182640518203" },
  "id": "739182640518204"
}
```

```typescript TypeScript
const conversation = { id: "<conversation-id>" };

await messaging.messages.react("<number-id>", { conversation, id: "<message-id>", reaction: "👍" });
await messaging.messages.markSeen("<number-id>", { conversation, id: "<message-id>" });
await messaging.messages.setTyping("<number-id>", { conversation, state: "typing", id: "<message-id>" });

await messaging.chats.editMessage("<number-id>", "<conversation-id>", "<message-id>", {
  text: "Your order ships tomorrow.",
});
await messaging.chats.deleteMessage("<number-id>", "<conversation-id>", "<message-id>");
```

```bash Graph API
# React to a message
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15550001111",
    "type": "reaction",
    "reaction": { "message_id": "'"$MESSAGE_ID"'", "emoji": "👍" }
  }'

# Mark it read (Meta Cloud API Numbers)
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messaging_product": "whatsapp", "status": "read", "message_id": "'"$MESSAGE_ID"'" }'
```

**Graph API:** Meta Cloud API Numbers: Partly supported. Linked Devices Numbers: Partly supported.

[Send a message](https://docs.polymorfa.com/api/graph/messages/send-a-message) reacts on both
connection types. Marking read works on Meta Cloud API Numbers; a
`typing_indicator` request is accepted there but shows no typing indicator.
Linked Devices Numbers return capability error `131026` for read and typing;
use the methods below. Starring, editing and deleting are not offered through
the Graph API.

| Action | Method | Scope |
| --- | --- | --- |
| Mark seen | [Send seen](https://docs.polymorfa.com/api/messages/send-seen) | `messages:write` |
| React | [Send reaction](https://docs.polymorfa.com/api/messages/send-reaction) | `messages:write` |
| Show typing | [Set typing](https://docs.polymorfa.com/api/messages/set-typing) | `messages:write` |
| Star | [Star message](https://docs.polymorfa.com/api/messages/star-message) | `messages:write` |
| Edit a sent message | [Edit message](https://docs.polymorfa.com/api/chats/edit-message) | `chats:manage` |
| Delete a sent message | [Delete message](https://docs.polymorfa.com/api/chats/delete-message) | `chats:manage` |

Meta Cloud API Numbers need the `id` of an inbound message to show typing. They
mark it read and show typing for up to 25 seconds or until you reply, and
support only the `typing` state. Linked Devices Numbers also accept
`recording` and `paused`.

## Get the result asynchronously

Linked Devices requests that accept `Prefer: respond-async` return `202` with
`Preference-Applied: respond-async`. The result then arrives in a
`command.result` event, with the request's `requestId`, the `command` and
`success`. Do not assume the preference applied without that header.

Meta Cloud API requests always return their result synchronously, including
when you send `Prefer: respond-async`.

## Handle failures

When a send fails, the error's `docs` URL points to the matching failure on
the method's reference page. Two server errors need care:

- `result_unknown`: the command's result was not received. It does not prove
  the send failed. Check the message events before retrying.
- `command_dispatch_failed` (`503`): the command could not be dispatched.

A send that a Number cannot perform after it was accepted arrives as
`message.failed`, including sends refused by safety checks. See
[Errors](https://docs.polymorfa.com/api/errors).

## Retry sends safely

Send an `Idempotency-Key` header, such as a UUID, with each message and reuse
it when you retry. For one hour, a retained receipt prevents the same request
from sending a second copy. Keep the first response. When exact replay data is
unavailable, a repeat returns `503 idempotency_replay_unavailable` without
sending again. Read message events before deciding whether another write is safe. [Retry writes safely](https://docs.polymorfa.com/development/idempotency) covers every outcome.

## Verify delivery

Subscribe to these events for the messages you send:

| Event | Meaning |
| --- | --- |
| `message.sent` | The outgoing message was sent. |
| `message.ack` | A receipt arrived. `type` is `delivered`, `read`, `played` or `error`; `messages` lists the message IDs. |
| `message.failed` | The send failed. `error` is `invalid_recipient`, `session_not_connected`, `ack_timeout`, `send_failed` or `blocked_by_safety`. |

## See also

- [Receive messages](https://docs.polymorfa.com/messaging/receive)
- [Conversation identity and message IDs](https://docs.polymorfa.com/messaging/ids)
- [Retry writes safely](https://docs.polymorfa.com/development/idempotency)
- [Send message reference](https://docs.polymorfa.com/api/messages/send-message)

[Stickers and sticker packs](https://docs.polymorfa.com/messaging/stickers) covers the candidate operations, conversion limits and availability.
