Skip to main content

Messenger Messages

Read and answer the Messenger inbox of your Facebook Page through the same DM endpoints used for Instagram and WhatsApp. In the API, Messenger is platform: "facebook".

Limited rollout

Messenger messaging is in a limited rollout until Meta approves the messaging permission for Upload-Post. It is enabled on request: contact support to ask for access. For accounts where it is not enabled, every Messenger call answers 403 with error_code: "messenger_not_enabled"; there is no plan, setting or reconnect that turns it on. Instagram and WhatsApp messages are available to every account.

Messenger is a messaging channel

Sending Messenger messages is separate from publishing. Posts to your Page still go through /upload with platform[]=facebook; Messenger messages only go through /api/uploadposts/dms/*.


Connect Messenger​

Messenger uses the Facebook connection of the profile. There is nothing extra to connect, but the connection must include Facebook's messaging permissions:

  • If you connected Facebook before Messenger was available, reconnect Facebook from the dashboard and accept the messaging permissions in Facebook's window.
  • Without them, calls fail with error_code: "messenger_permission_missing".
  • If Messenger is not enabled for your account yet (limited rollout), calls fail with 403 and error_code: "messenger_not_enabled".

Messages are sent from, and read from, the profile's Facebook Page: the Page selected for that profile in the dashboard, or else the Page its Facebook connection uses for publishing. If the Facebook account manages several Pages, pass page_id to choose another one.


The 24-hour messaging window​

  • When a person writes to your Page, you can reply for the next 24 hours.
  • Outside that window Messenger refuses normal messages, and the API answers 400 with error_code: "dm_window_blocked". Later sends to that person are refused up front until they write again.
  • tag: "HUMAN_AGENT" marks a message as a reply written by a person, which Messenger allows up to 7 days after the person's last message. Use it only for human replies, never for automated or promotional messages. Meta must have enabled the Human Agent feature for these sends; if not, it rejects them.

Send a Message​

Endpoint​

POST /api/uploadposts/dms/send

Headers​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

Body Parameters (JSON)​

NameTypeRequiredDescription
platformStringYes"facebook".
userStringYesProfile username (as configured in Upload-Post) with Facebook connected.
recipient_idStringYesThe person's Page-scoped id (PSID). Get it from Get Conversations or the dm_received webhook.
messageStringYes, unless attachments or sender_action is sentText, up to 2000 characters.
attachments / attachmentObject or arrayNoItems {type, url} or {type, attachment_id}. type is image, video, audio or file (document is accepted as file); url must be a public https:// URL, and attachment_id comes from Upload Media. Each attachment is sent as its own message after the text.
buttonsArrayNoUp to 3 buttons under the text: {title, url} (opens a link) or {title, payload} (sends the payload back to you). Needs message up to 640 characters.
quick_repliesArrayNoUp to 13 quick replies shown under the text. Each item is a string, or {title, payload} (the full Messenger format {content_type: "text", title, payload} also works).
reply_toStringNoMessage id (mid) to reply to. Applies to the text.
tagStringNo"HUMAN_AGENT" to reply up to 7 days after the person's last message (see above).
sender_actionStringNotyping_on, typing_off or mark_seen. Sent alone, not as a message: it does not count towards the daily DM limit.
page_idStringNoNumeric id of the Page to send from, when the profile has no Page selected or you want another Page of the same Facebook account.

Example Requests​

Text with quick replies:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "facebook",
"user": "my-profile",
"recipient_id": "6789012345678901",
"message": "Thanks for your message! What do you need help with?",
"quick_replies": [
{ "content_type": "text", "title": "Orders", "payload": "ORDERS" },
{ "content_type": "text", "title": "Returns", "payload": "RETURNS" }
]
}'

Upload an image, then send it:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/media \
-H 'Authorization: Apikey your-api-key-here' \
-F 'platform=facebook' \
-F 'user=my-profile' \
-F 'type=image' \
-F '[email protected]'
# -> {"success": true, "platform": "facebook", "type": "image", "attachment_id": "1857777774821032", ...}

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "facebook",
"user": "my-profile",
"recipient_id": "6789012345678901",
"message": "Here is the photo you asked for",
"attachments": [ { "type": "image", "attachment_id": "1857777774821032" } ]
}'

Buttons (link and postback):

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "facebook",
"user": "my-profile",
"recipient_id": "6789012345678901",
"message": "How can we help?",
"buttons": [
{ "title": "Track my order", "url": "https://example.com/track" },
{ "title": "Talk to support", "payload": "SUPPORT" }
]
}'

Human reply after the 24-hour window, from a specific Page:

curl -X POST https://api.upload-post.com/api/uploadposts/dms/send \
-H 'Authorization: Apikey your-api-key-here' \
-H 'Content-Type: application/json' \
-d '{
"platform": "facebook",
"user": "my-profile",
"page_id": "104512345678901",
"recipient_id": "6789012345678901",
"message": "Hi, this is Laura from support. Your refund was processed today.",
"tag": "HUMAN_AGENT"
}'

Responses​

  • 200 OK
{
"success": true,
"platform": "facebook",
"page_id": "104512345678901",
"recipient_id": "6789012345678901",
"message_id": "m_AbCdEf123...",
"messages": [
{ "message_id": "m_AbCdEf123...", "recipient_id": "6789012345678901" }
]
}

messages has one entry per Messenger message sent (a text plus attachments can be several). message_id is the first one.

  • Errors
{
"success": false,
"error": "(#10) This message is sent outside of allowed window.",
"error_code": "dm_window_blocked",
"meta_error_code": 10,
"error_subcode": 2018278
}
Statuserror_codeMeaning
400dm_window_blockedMore than 24 hours since the person's last message. Wait for them to write, or use tag: "HUMAN_AGENT" for a human reply within 7 days. When the block is already known, the response has a Retry-After header.
400messenger_not_connectedThe profile has no Facebook account connected.
403messenger_not_enabledMessenger is not enabled for this account yet (limited rollout). Contact support to request access.
400messenger_permission_missingThe Facebook connection lacks the messaging permissions. Reconnect Facebook from the dashboard.
400messenger_invalid_requestpage_id is not a numeric Page id.
400, 403messenger_page_unresolvedNo Page could be resolved for the profile, or the page_id is not a Page of its Facebook account.
400messenger_api_errorAny other Messenger refusal; error, meta_error_code and error_subcode carry Meta's reason.
400—Invalid body (text over 2000 characters, attachment without an https:// URL, unknown sender_action, more than 3 buttons or message over 640 characters with buttons, a button without url or payload, more than 13 quick_replies, tag other than HUMAN_AGENT).
401messenger_reauth_requiredThe Facebook connection is no longer valid. Reconnect Facebook.
429dm_rate_limited, dm_send_in_progressToo many sends per minute, or another send to the same person is still running. Wait for Retry-After.
429—Daily DM limit of your account reached.
502messenger_unreachableFacebook did not answer. Retry later.

Upload Media​

Upload a file once and send it with attachment_id, instead of hosting it at a public URL.

POST /api/uploadposts/dms/media

Send it as multipart/form-data.

FieldRequiredDescription
platformYes"facebook".
userYesProfile username with Facebook connected.
fileYesThe file, up to 25 MB.
typeNoimage, video, audio or file. Detected from the file when omitted.
page_idNoNumeric id of the Page the file is uploaded for (same rules as in Send a Message).
{
"success": true,
"platform": "facebook",
"type": "image",
"attachment_id": "1857777774821032",
"mime_type": "image/jpeg",
"filename": "photo.jpg",
"size": 482113
}

Pass the attachment_id in attachments of Send a Message. A file over 25 MB is refused with 413 and error_code: "dm_media_too_large".


Get Conversations​

Reads the Page's Messenger inbox live from Facebook, in the same shape as Instagram's conversations.

Endpoint​

GET /api/uploadposts/dms/conversations

Headers​

NameValueDescription
AuthorizationApikey your-api-key-hereYour API key for authentication

Query Parameters​

NameTypeRequiredDescription
platformStringYes"facebook".
userStringYesProfile username (as configured in Upload-Post).
page_idStringNoNumeric id of the Page to read, when the profile has no Page selected or you want another Page of the same Facebook account.
limitIntegerNoConversations per page, 1 to 50. Default 20.
cursorStringNopagination.next_cursor from the previous page.
sinceStringNoOnly conversations with activity after this moment. Unix seconds, Unix milliseconds or an ISO 8601 date.
participant_idStringNoPSID of a person, to fetch only your conversation with them.
messages_limitIntegerNoLatest messages per conversation, 1 to 25. Default 10.

Conversations come newest first. Responses are cached for up to 60 seconds; sending a message clears the cache. To be told the moment a message arrives, subscribe to the dm_received webhook.

Example Request​

curl 'https://api.upload-post.com/api/uploadposts/dms/conversations?platform=facebook&user=my-profile&limit=10' \
-H 'Authorization: Apikey your-api-key-here'

Response​

  • 200 OK
{
"success": true,
"conversations": [
{
"id": "t_10161234567890123",
"updated_time": "2026-11-03T10:31:00+0000",
"participants": {
"data": [
{ "id": "6789012345678901", "name": "Jane Doe" },
{ "id": "104512345678901", "name": "Acme Store", "is_me": true }
]
},
"messages": {
"data": [
{
"id": "m_AbCdEf123...",
"created_time": "2026-11-03T10:31:00+0000",
"from": { "id": "104512345678901", "name": "Acme Store" },
"to": { "data": [{ "id": "6789012345678901", "name": "Jane Doe" }] },
"message": "Thanks for your message! What do you need help with?",
"direction": "out",
"status": "read",
"reactions": [{ "emoji": "👍", "direction": "in" }]
},
{
"id": "m_GhIjKl456...",
"created_time": "2026-11-03T10:30:00+0000",
"from": { "id": "6789012345678901", "name": "Jane Doe" },
"to": { "data": [{ "id": "104512345678901", "name": "Acme Store" }] },
"message": "",
"direction": "in",
"attachments": [
{ "id": "1234567890", "type": "image", "mime_type": "image/jpeg", "url": "https://scontent.xx.fbcdn.net/...", "name": "image.jpg" }
]
}
]
}
}
],
"pagination": { "next_cursor": "QVFIUj...", "has_more": true },
"page": { "id": "104512345678901", "name": "Acme Store" }
}
FieldDescription
participantsThe person (id = their PSID, the recipient_id you send to) and your Page (is_me: true).
messages[].directionin (from the person) or out (from your Page).
messages[].messageThe text. Empty when the message is only an attachment.
messages[].attachmentsList of {id, type, mime_type, url, name}. type is image, video, audio or file. Incoming locations come as {type: "location", latitude, longitude, name} and stickers as {type: "sticker", url, sticker_id}.
messages[].statusOutgoing only: sent, delivered or read, updated from Messenger's delivery and read receipts.
messages[].reactionsReactions on this message: [{emoji, direction}], where direction is in (the person reacted) or out (your Page reacted). Reactions are not separate messages.
pageThe Page that was read.
paginationPass next_cursor as cursor to get the next page.

Unlike WhatsApp, Messenger conversations include the Page's history from before you connected it, as far back as Facebook returns it.


Receive messages in real time​

Subscribe to the dm_received webhook to get each incoming Messenger message with platform: "facebook" and account_id set to the Page id. Upload-Post starts receiving a Page's messages the first time you use Messenger with it (sending a message or listing its conversations, from the API or the dashboard), so call Get Conversations once after connecting.

Important Notes​

  1. Daily DM limits: Messenger messages count towards the same daily DM limit of your Upload-Post account as Instagram and WhatsApp messages. sender_action does not (typing_on, typing_off, mark_seen). When the limit is reached, the API returns 429.
  2. Messenger policies: Meta does not allow promotional messages outside the 24-hour window, and HUMAN_AGENT is for replies written by people. Breaking these rules can get the Page's messaging restricted by Meta.