POpostproxy
Direct Messages

Send message

Creates an outbound message and queues it for delivery. The message is created immediately with status pending and published asynchronously; each send accepts either text or a single attachment, never both.

post/api/chats/{chat_id}/messages

Request

  • Base URL
    https://api.postproxy.dev
  • URL
    https://api.postproxy.dev/api/chats/{chat_id}/messages
  • Auth
    HTTP bearer

Query parameters

profile_group_idstring

Profile group context for the request. Optional when the API key is scoped to a profile group (that group is used automatically); with a full-access key, defaults to the first profile group in the account.

Headers

Idempotency-Keystring

Optional idempotency key (up to 255 characters; a UUID is ideal). Retrying a successful write with the same key replays the original response (with an Idempotent-Replay: true header) instead of executing again. Stored responses are kept for 24 hours; only 2xx responses are stored.

Request body

bodystring

Message text. Required when media and elements are empty; not allowed with elements. Capped at 220 characters when buttons are present.

tag'HUMAN_AGENT'

Message tag for sending outside the 24-hour window. Facebook and Instagram only — ignored on Telegram. Extends the reply window to 7 days from the participant's last inbound message; for a human resolving the participant's own inquiry only, never promotional content. Rejected on WhatsApp, which has no HUMAN_AGENT tag — use a template or category "utility" instead.

reply_to_external_idstring

Telegram, WhatsApp and Instagram. Platform message ID (the message's external_id) to reply to — Telegram message_id, WhatsApp wamid, Instagram mid. On WhatsApp and Instagram the send quotes that message. On Instagram the target can be inbound or outbound; if Instagram rejects it (deleted, too old, or not in this chat) the send fails with message.failed instead of going out without the quote. Rejected with 422 on Facebook and Bluesky.

reply_markupobject

Telegram only. Inline keyboard (inline_keyboard), custom reply keyboard (keyboard, with one_time_keyboard / resize_keyboard), force_reply, or remove-keyboard payload — passed through to Telegram unchanged.

interactiveobject

WhatsApp only. Meta’s interactive object unchanged — reply buttons (type "button"), lists ("list"), call-to-action URLs ("cta_url"), catalog products ("product" / "product_list") or Flows ("flow"). Session message: needs an open messaging window and cannot be sent to a group.

contactsobject[]

WhatsApp only. Array of Meta contact objects (name, phones, emails, …).

category'utility'

WhatsApp only. "utility" sends a plain text outside the 24-hour window via Meta’s Direct Send, where the account is eligible. Valid only alongside body; with any other payload returns 422.

link_previewboolean

WhatsApp only. Render a preview for a link in body.

voice_noteboolean

WhatsApp only. Send an audio attachment as a voice note.

filenamestring

WhatsApp only. Filename shown for a document attachment.

Response

Accepted. The message is created with status pending; once published the status updates to published and external_id is populated. On failure it becomes failed_waiting_for_retry (retried with backoff) or failed.

idstring

Message hashid

chat_idstring

Chat hashid

external_idstring nullable

Platform-native message ID (null while pending)

direction'inbound' | 'outbound'
bodystring nullable

Message text

status'pending' | 'published' | 'failed_waiting_for_retry' | 'failed' | 'received'

pending/published/failed_waiting_for_retry/failed for outbound, received for inbound

external_comment_idstring nullable

Set when the message was sent as a private reply to a comment

error_messagestring nullable

Last error from the platform (when failed)

platform_dataobject nullable

Raw platform webhook payload, passed through unchanged. Shape is platform- and event-specific and may change without notice — prefer the typed fields where available.

external_posted_atstring nullable

ISO 8601 timestamp from the platform

external_delivered_atstring nullable

When the platform confirmed delivery (outbound; FB & IG only)

external_read_atstring nullable

When the recipient read the message (outbound; FB & IG only)

external_edited_atstring nullable

ISO 8601 timestamp of the most recent edit; body reflects the latest edit

reply_to_external_idstring nullable

Platform message ID this message replies to (inbound replies, outbound reply_to_external_id, or a Telegram callback query's source)

reply_markupobject nullable

Telegram only — the reply_markup attached to the message

cardobject nullable

Facebook and Instagram only — the card fields (subtitle, image_url, default_action) sent alongside buttons

external_deleted_atstring nullable

When the message was deleted/unsent on the platform (treat as redacted)

is_unsupportedboolean

true when the platform marked the message as unsupported (e.g. an unprocessable voice clip)

created_atstring

ISO 8601 timestamp of record creation

templateobject nullable

WhatsApp only. The template a message was sent with — id, external_id, name, language, variables.

interactiveobject nullable

WhatsApp only. Outbound: the interactive object sent. Inbound: the customer’s reply to one — type "button_reply" / "list_reply" / "nfm_reply" with the id and title you assigned.

locationobject nullable

WhatsApp only. latitude, longitude, name, address — sent or received.

sourcestring nullable

"synced" on an outbound WhatsApp message the team sent from the phone on a coexistence number.

Changes

No recorded changes to this operation across all 1 revision of this API.