Inbox

Send a direct message

Sends a message into an existing thread. The recipient is the other participant on that thread, so no recipient id is needed. Exactly one of message or attachmentUrl may be sent per call — Meta's Send API carries one payload at a time, so combining them is a 400. Meta only accepts replies within 24 hours of the person's last message; outside that window the platform refuses the send and PostZen reports 400 PLATFORM_LIMITATION with Meta's own envelope attached. Sends are hard-gated on the account's messaging scope. Requires a read-write API key.

post/v1/inbox/conversations/{conversationId}/messages

Request

  • Base URL: https://api.postzen.dev
  • URL: https://api.postzen.dev/v1/inbox/conversations/{conversationId}/messages
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Replay protection. Retrying with the same key and the same body replays the stored outcome and sets Idempotent-Replayed: true; the same key with a different body is a 422, and a key whose first request is still in flight is a 409. A send whose outcome could not be confirmed (502 providerOutcomeUnknown) is stored as a terminal outcome, so retrying that key returns the same 502 rather than risking a duplicate message. Keys are retained for 24 hours.

Request body

accountIdstring required

PostZen account id that owns the conversation.

messagestring

Message text. Cannot be combined with attachmentUrl: Meta accepts one payload per call, so a request carrying both is rejected with a 400 rather than silently sending half of it.

attachmentUrlstring uri

Publicly fetchable http(s) URL. Meta downloads it itself, so it must be reachable without credentials — POST /v1/media/upload-direct returns a URL that qualifies.

attachmentType'image' | 'video' | 'audio' | 'file'

Required whenever attachmentUrl is set.

Response

Message sent. Idempotent-Replayed: true on the response means this was a replay of an earlier identical request rather than a new send.

successtrue required

Changes

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