--- title: "Send message" method: POST path: "/v1/inbox/conversations/{conversationId}/messages" tags: ["Messages"] --- # Send message `POST /v1/inbox/conversations/{conversationId}/messages` Send a message in a conversation. Supports text, attachments, quick replies, buttons, templates, and message tags. Attachment and interactive message support varies by platform. WhatsApp template messages: to send an approved template into this conversation (required when the 24-hour customer-service window is closed), use the `template` field with a single element carrying the template reference: `{ "elements": [{ "name": ..., "language": ..., "components": [...] }] }`. See the `template` field below for the exact shape. To send a template to a phone number you have no conversation with yet, use the create-conversation endpoint (POST /v1/inbox/conversations) instead. WhatsApp rich interactive messages (list, CTA URL, Flow, location request) are available via the `interactive` field. Tap events are delivered through the `message.received` webhook with WhatsApp-specific `metadata` fields (`interactiveType`, `interactiveId`, `flowResponseJson`, `flowResponseData`). **Idempotency:** send an `Idempotency-Key` header to make retries safe (e.g. after a client-side timeout where delivery is unknown): same key + same body replays the original response (with `Idempotent-Replayed: true`) instead of sending the message a second time; same key + different body returns 422; a key still in flight returns 409. Works for JSON and multipart (file upload) requests alike. Keys are retained for 24 hours. ## Path parameters - `conversationId` string, required ## Headers - `Idempotency-Key` string ## Request body - object - `accountId` string, required — Social account ID - `message` string — Message text - `attachmentUrl` string — URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead. - `category` 'utility' — WhatsApp only (Meta Direct Send). Sends this message as a business-initiated UTILITY message without an approved template, for example outside the 24-hour customer service window; Meta matches or auto-creates a template asynchronously. The WhatsApp Business Account must be eligible for Direct Send, otherwise the send fails with an error telling you to use an approved message template instead. Supported only for text messages (link preview ok) and interactive messages (reply buttons, CTA URL buttons, voice-call button, header of text/image/video/document). Cannot be combined with template, attachments, location, or contacts. Utility messages only; marketing content is not allowed under this category. Accepted on the JSON body only, not on multipart requests. - `attachmentType` 'image' | 'video' | 'audio' | 'file' — Type of attachment. Defaults to file if not specified. - `attachmentName` string — WhatsApp only. Display name for a document sent via attachmentUrl with attachmentType: file (e.g. "Report.pdf"). Maps to the recipient's file name; without it WhatsApp derives the name from the URL and shows "Untitled". Ignored for image/video/audio and for binary uploads (which use the uploaded file's name). - `voiceNote` boolean — WhatsApp only. When `true` on an audio attachment, the message is sent as a voice message (PTT) — the recipient sees the waveform + voice-note UI instead of a basic audio attachment. The audio file MUST be `.ogg` encoded with the OPUS codec (mono) per Meta's voice-message contract; other formats are rejected by WhatsApp. Ignored for non-audio attachments. - `quickReplies` object[] — Quick reply buttons. Mutually exclusive with buttons. Max 13 items. - `title` string, required — Button label (max 20 chars) - `payload` string, required — Payload sent back on tap - `imageUrl` string — Optional icon URL (Meta only) - `buttons` object[] — Action buttons. Mutually exclusive with quickReplies. Max 3 items. Instagram / Facebook: also mutually exclusive with `template`. A Meta message carries one body shape, so sending both is a 400 rather than a silent drop of the buttons. WhatsApp: buttons always render as interactive reply buttons. Only `title` and `payload` are used — `type`, `url`, and `phone` are ignored (WhatsApp has no URL/phone button in this field; use the `interactive` field with `type: cta_url` for a link button). `payload` becomes the button reply ID delivered on the `message.received` webhook when the user taps. To send a simple reply-button message, provide `title` + `payload` and set `type: postback`, e.g. `{ "type": "postback", "title": "Yes", "payload": "yes" }`. - `type` 'url' | 'postback' | 'phone', required — Button type. phone is Facebook only. Ignored on WhatsApp (buttons always render as reply buttons). - `title` string, required — Button label (max 20 chars) - `url` string — URL for url-type buttons (Facebook/Instagram only) - `payload` string — Payload for postback-type buttons. On WhatsApp, this is the reply ID returned on the message.received webhook when the button is tapped. - `phone` string — Phone number for phone-type buttons (Facebook only) - `template` object — Platform-dependent template payload. Ignored on Telegram. Instagram / Facebook: a generic template (carousel). Set `type: generic` and provide up to 10 `elements`, each with a `title` (required) and optional `subtitle`, `imageUrl`, and `buttons`. Mutually exclusive with the top-level `buttons` field (sending both is a 400); put the card's buttons on its `elements` instead. WhatsApp: sends an approved WhatsApp template message, the only message type WhatsApp accepts when the 24-hour customer-service window is closed. Provide exactly one element carrying the template reference: `{ "elements": [{ "name": "order_update", "language": "en_US", "components": [...] }] }` (`type` is ignored on WhatsApp). `components` is optional and is forwarded unchanged as the `template.components` array of Meta's Cloud API send payload; use it to fill body/header variables and button parameters, e.g. `[{ "type": "body", "parameters": [{ "type": "text", "text": "John" }] }]`. Templates with media headers (image, video, document) must include the header component with its media link here at send time. To send a template to a phone number with no existing conversation, or to have media headers filled in automatically from the template definition, use the create-conversation endpoint (POST /v1/inbox/conversations) instead. - `type` 'generic' — Template type. Required for Instagram/Facebook generic templates; ignored on WhatsApp. - `elements` object[] - `title` string — Element title (max 80 chars). Required for Instagram/Facebook generic templates. - `subtitle` string — Element subtitle (Instagram/Facebook only) - `imageUrl` string — Element image URL (Instagram/Facebook only) - `buttons` object[] — Element buttons (Instagram/Facebook only) - `type` 'url' | 'postback' - `title` string - `url` string - `payload` string - `name` string — WhatsApp only. Name of the approved template to send. - `language` string — WhatsApp only. Template language code (e.g. en_US). - `components` object[] — WhatsApp only. Meta Cloud API send-shape components array, forwarded to Meta verbatim. - `interactive` object — WhatsApp-only. Rich interactive payload for list messages, CTA URL buttons, Flow prompts, location requests, voice-call buttons, and commerce messages (single product, product list, catalog, and carousel). When set, takes priority over `buttons` and `quickReplies`. The shape mirrors Meta's Cloud API `interactive` object verbatim, so any payload that works against Meta directly will also work here. Use `buttons` / `quickReplies` for simple button replies (WhatsApp's `interactive.type: "button"`): the abstraction caps at 3 buttons and handles the auto-conversion for you. Use this field only for the types listed in the enum below. All interactive messages are session messages: they can only be sent inside the 24-hour customer service window opened by the user's last inbound message. Commerce types (`product`, `product_list`, `catalog_message`, and product carousels) require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. Media carousels (image/video cards) do not need a catalog. For `product`, `body` is optional (WhatsApp renders the product card itself) and `header` is not allowed (the product image is the header). For `product_list`, a `header` with `type: "text"` is required. For `carousel`, top-level `header`/`footer` are not supported; media goes on each card instead. For `voice_call`, the message renders WhatsApp's native call button; tapping it starts a voice call to your business number. Requires WhatsApp Business Calling to be enabled on the sending number. The optional `parameters.payload` string is echoed back on the `calls` webhook (as `cta_payload`) for attribution. For `location_request_message`, `action` may be omitted (we default it to `{ "name": "send_location" }`). WhatsApp renders a localized "Send location" button; the user's reply arrives as a regular location message in the conversation. For `request_contact_info`, `action` may be omitted (we default it to `{ "name": "request_contact_info" }`). WhatsApp renders a localized share button that cannot be relabelled, so put the reason for asking in `body.text`: this is a consent prompt, and a bare request converts badly. The reply arrives as an inbound `contacts` message with `metadata.contactsOrigin` set to `contact_request`, and we fold the shared number back into the contact automatically. A `contacts` message with origin `other` is a card the user picked from their address book and is NOT proof of their own number. For `catalog_message`, `action` may also be omitted (we default it to `{ "name": "catalog_message" }`). Tap events come back via the `message.received` webhook with `metadata.interactiveType` set to `list_reply` or `nfm_reply`. Carts submitted from commerce messages arrive as `metadata.order`; product inquiries arrive as `metadata.referredProduct`. - `type` 'list' | 'cta_url' | 'flow' | 'location_request_message' | 'request_contact_info' | 'voice_call' | 'product' | 'product_list' | 'catalog_message' | 'carousel', required — Which interactive layout to render. - `header` object — Optional header shown above the body. Required with `type: "text"` for `product_list`; not allowed for `product` or `carousel`. - `type` 'text' | 'image' | 'video' | 'document' - `text` string — Required when header type is text. - `image` object - `link` string - `video` object - `link` string - `document` object - `link` string - `body` object — Required for every type except `product`, where it is optional. - `text` string, required — Main body text. - `footer` object — Optional footer shown below the action. - `text` string - `action` union - object — List action. `type` on the parent must be `list`. - `button` string, required — CTA label that opens the list (max ~20 chars). - `sections` object[], required — 1-10 sections. Total rows across all sections cannot exceed 10. - `title` string — Optional section header (max 24 chars). - `rows` object[], required - `id` string, required — Identifier returned in the webhook as metadata.interactiveId (max 200 chars). - `title` string, required — Row label (max 24 chars). - `description` string — Optional description below the title (max 72 chars). - object — CTA URL action. `type` on the parent must be `cta_url`. - `name` 'cta_url', required - `parameters` object, required - `display_text` string, required — Button label (max 20 chars). - `url` string, uri, required — Target URL opened when the user taps the button. - object — Voice-call action. `type` on the parent must be `voice_call`. Renders WhatsApp's native call button (requires Calling enabled on the sending number). - `name` 'voice_call', required - `parameters` object — All optional. - `display_text` string — Button label. Defaults to "Call Now". - `ttl_minutes` integer — How long the button stays tappable. Defaults to 10080 (7 days). - `payload` string — Arbitrary string echoed back as `cta_payload` on the `calls` webhook (connect/terminate) for attribution. - object — Flow action. `type` on the parent must be `flow`. - `name` 'flow', required - `parameters` object, required - `flow_message_version` '3' — Defaults to "3" when omitted. - `flow_token` string, required — Opaque token you choose to correlate Flow responses with your own state (max 200 chars). - `flow_id` string, required — Published Flow ID from Meta Business Manager. - `flow_cta` string, required — Button label that opens the Flow (max 20 chars). - `flow_action` 'navigate' | 'data_exchange', required — `navigate` sends the user to `flow_action_payload.screen`; `data_exchange` posts data to your Flow endpoint. - `flow_action_payload` object — Required when flow_action is `navigate`. - `screen` string — First screen to show. - `data` object — Optional pre-filled data passed to the screen. - `mode` 'draft' — Set to `draft` to test an unpublished Flow. - object — Location request action. `type` on the parent must be `location_request_message`. May be omitted entirely; it is defaulted. - `name` 'send_location', required - object — Contact-info request action. `type` on the parent must be `request_contact_info`. May be omitted entirely; it is defaulted. - `name` 'request_contact_info', required - object — Single-product action. `type` on the parent must be `product`. Requires a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. - `catalog_id` string, required — Meta catalog ID connected to the WhatsApp Business Account. - `product_retailer_id` string, required — Retailer ID (SKU) of the product inside the catalog. - object — Multi-product action. `type` on the parent must be `product_list`. Requires a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. - `catalog_id` string, required — Meta catalog ID connected to the WhatsApp Business Account. - `sections` object[], required — 1-10 sections. Total products across all sections cannot exceed 30. - `title` string — Optional section header. - `product_items` object[], required - `product_retailer_id` string, required — Retailer ID (SKU) of the product inside the catalog. - object — Catalog-message action. `type` on the parent must be `catalog_message`. May be omitted entirely; it is defaulted to `{ "name": "catalog_message" }`. Requires a Meta catalog connected to the WhatsApp Business Account in Commerce Manager. - `name` 'catalog_message', required - `parameters` object - `thumbnail_product_retailer_id` string — Optional product whose image is used as the message thumbnail. Falls back to the first catalog item when omitted. - object — Carousel action. `type` on the parent must be `carousel`. Carries 2-10 cards, either all product cards (`type: "product"`, all referencing the same `catalog_id`) or media cards (any other `type`, e.g. `cta_url`, with a required image/video `header` on each card). `card_index` (0-9, non-repeating) is auto-filled sequentially when omitted. Product carousels require a Meta catalog connected to the WhatsApp Business Account in Commerce Manager; media carousels do not. - `cards` object[], required - `card_index` integer — Card position. Auto-filled sequentially when omitted. - `type` string — `product` for a product card; media cards use `cta_url` or a quick-reply type. - `header` object — Media cards only, required. Carries the card's image or video. - `body` object — Optional card body text. - `action` object — Product cards: `{ catalog_id, product_retailer_id }` (required). Media cards: the card's button action (e.g. `cta_url` with `parameters.display_text` and `parameters.url`). - `replyMarkup` object — Telegram-native keyboard markup. Ignored on other platforms. - `type` 'inline_keyboard' | 'reply_keyboard' — Keyboard type - `keyboard` array[] — Array of rows, each row is an array of buttons - object[] - `text` string — Button text - `callbackData` string — Callback data (inline_keyboard only, max 64 bytes) - `url` string — URL to open (inline_keyboard only) - `oneTime` boolean — Hide keyboard after use (reply_keyboard only) - `messagingType` 'RESPONSE' | 'UPDATE' | 'MESSAGE_TAG' — Facebook messaging type. Required when using messageTag. - `messageTag` 'CONFIRMED_EVENT_UPDATE' | 'POST_PURCHASE_UPDATE' | 'ACCOUNT_UPDATE' | 'HUMAN_AGENT' — Facebook message tag for messaging outside 24h window. Requires messagingType MESSAGE_TAG. Instagram only supports HUMAN_AGENT. - `replyTo` string — Platform message ID to quote-reply to. For WhatsApp, pass the wamid; for Telegram, the Telegram message ID (both available in message.platformMessageId from webhooks or the list-messages endpoint). On Slack it threads the reply (thread_ts) instead of quoting. Silently ignored on platforms without send-side reply support, including Instagram and Facebook Messenger (Meta's Send API rejects reply_to on Instagram and does not expose it on Messenger). - `location` object — WhatsApp-only. Send a location pin. - `latitude` number, required — Latitude in decimal degrees. - `longitude` number, required — Longitude in decimal degrees. - `name` string — Optional location name. - `address` string — Optional street address. - `contacts` object[] — WhatsApp-only. Send one or more contact cards. - `name` object, required - `formatted_name` string, required — Full display name. - `first_name` string - `last_name` string - `phones` object[] - `phone` string - `type` string — e.g. CELL, WORK, HOME. - `emails` object[] - `email` string - `type` string ## Response `200` Message sent - object - `success` boolean - `data` object - `messageId` string — ID of the sent message (not returned for Reddit) - `conversationId` string, nullable — Twitter conversation ID - `sentAt` string, date-time, nullable — Bluesky sent timestamp - `message` string, nullable — Success message (Reddit only) ## Other responses - `400` — Bad request (e.g., attachment not supported for platform, validation error, category combined with a template or attachment, category used on a non-WhatsApp account, or the WhatsApp Business Account is not eligible for Direct Send) - `401` — Unauthorized - `403` — Inbox addon required - `409` — Same Idempotency-Key still processing; retry after a short backoff - `422` — Idempotency-Key reused with a different body --- [API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)