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 and its Number ID.
- A server credential with
messages:write. Keep it on your server; browsers use client tokens. - A webhook or event stream for delivery events. See Receive messages.
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:
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." }
}'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);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.
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.
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 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:
{
"conversation": { "phoneNumber": "+15550001111" },
"content": {
"location": { "lat": 33.89, "long": 35.50, "address": "Beirut" }
}
}Send message 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 for video and document previews and the quality option.
API
{
"conversation": { "phoneNumber": "+15550001111" },
"content": {
"file": { "url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }
}
}await messaging.messages.send("<number-id>", {
conversation: { phoneNumber: "+15550001111" },
content: {
file: { url: "https://example.com/invoice.pdf", filename: "invoice.pdf" },
},
});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" }
}'Interactive messages#
Reply buttons, for example:
API
{
"conversation": { "phoneNumber": "+15550001111" },
"content": {
"buttons": {
"body": "Confirm your appointment?",
"buttons": [
{ "type": "reply", "text": "Confirm", "id": "confirm" },
{ "type": "reply", "text": "Reschedule", "id": "reschedule" }
]
}
}
}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" },
],
},
},
});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.
| 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.
requestPhoneNumber requires the contact's conversation.id. See 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.
API
{
"conversation": { "phoneNumber": "+15550001111" },
"content": {
"template": {
"name": "order_ready",
"language": "en_US",
"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "Ada" }] }]
}
}
}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" }] }],
},
},
});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" }] }]
}
}'Reply, mention and forward#
quotedMessage, mentions and isForwarded sit beside conversation and content.
API
{
"conversation": { "id": "739182640518203" },
"content": { "text": "Thanks, we got it." },
"quotedMessage": { "id": "739182640518977" }
}await messaging.messages.send("<number-id>", {
conversation: { id: "<conversation-id>" },
content: { text: "Thanks, we got it." },
quotedMessage: { id: "<message-id>" },
});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." }
}'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
{
"conversation": { "id": "739182640518203" },
"id": "739182640518204"
}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>");# 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"'" }'| Action | Method | Scope |
|---|---|---|
| Mark seen | Send seen | messages:write |
| React | Send reaction | messages:write |
| Show typing | Set typing | messages:write |
| Star | Star message | messages:write |
| Edit a sent message | Edit message | chats:manage |
| Delete a sent message | 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.
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 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#
Stickers and sticker packs covers the candidate operations, conversion limits and availability.