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

Send messages

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

View as Markdown

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
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
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);
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.

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.

KindField
Textcontent.text
Image, video, file, voice notecontent.image, content.video, content.file, content.voice
Locationcontent.location
Contact cardcontent.contact
Pollcontent.poll
Reply buttons and listscontent.buttons, content.list
Products, product lists and orderscontent.product, content.productList, content.order
Address requestcontent.addressMessage
WhatsApp Flowcontent.flow
Phone-number requestcontent.requestPhoneNumber
Call permission requestcontent.callPermissionRequest
Templatecontent.template

For example, a location:

JSON
{
  "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

JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "file": { "url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }
  }
}
TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { phoneNumber: "+15550001111" },
  content: {
    file: { url: "https://example.com/invoice.pdf", filename: "invoice.pdf" },
  },
});
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" }
  }'

Interactive messages#

Reply buttons, for example:

API

JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "buttons": {
      "body": "Confirm your appointment?",
      "buttons": [
        { "type": "reply", "text": "Confirm", "id": "confirm" },
        { "type": "reply", "text": "Reschedule", "id": "reschedule" }
      ]
    }
  }
}
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" },
      ],
    },
  },
});
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.

InputRule
Product-list sectionsAt most 30 product IDs across all sections; every product ID is unique.
List sectionsAt most 30 rows across all sections; every row ID is unique.
Linked Device buttonsUp 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 carousel2–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 buttonsDirect 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.dataJsonA 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 APIbody and a two-letter uppercase country code.
content.addressMessage on Linked Devicesbody 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

JSON
{
  "conversation": { "phoneNumber": "+15550001111" },
  "content": {
    "template": {
      "name": "order_ready",
      "language": "en_US",
      "components": [{ "type": "body", "parameters": [{ "type": "text", "text": "Ada" }] }]
    }
  }
}
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" }] }],
    },
  },
});
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" }] }]
    }
  }'

Reply, mention and forward#

quotedMessage, mentions and isForwarded sit beside conversation and content.

API

JSON
{
  "conversation": { "id": "739182640518203" },
  "content": { "text": "Thanks, we got it." },
  "quotedMessage": { "id": "739182640518977" }
}
TypeScript
await messaging.messages.send("<number-id>", {
  conversation: { id: "<conversation-id>" },
  content: { text: "Thanks, we got it." },
  quotedMessage: { id: "<message-id>" },
});
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." }
  }'

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
{
  "conversation": { "id": "739182640518203" },
  "id": "739182640518204"
}
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>");
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"'" }'
ActionMethodScope
Mark seenSend seenmessages:write
ReactSend reactionmessages:write
Show typingSet typingmessages:write
StarStar messagemessages:write
Edit a sent messageEdit messagechats:manage
Delete a sent messageDelete messagechats: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:

EventMeaning
message.sentThe outgoing message was sent.
message.ackA receipt arrived. type is delivered, read, played or error; messages lists the message IDs.
message.failedThe 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.