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".
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.
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
403anderror_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
400witherror_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
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Body Parameters (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
| platform | String | Yes | "facebook". |
| user | String | Yes | Profile username (as configured in Upload-Post) with Facebook connected. |
| recipient_id | String | Yes | The person's Page-scoped id (PSID). Get it from Get Conversations or the dm_received webhook. |
| message | String | Yes, unless attachments or sender_action is sent | Text, up to 2000 characters. |
| attachments / attachment | Object or array | No | Items {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. |
| buttons | Array | No | Up 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_replies | Array | No | Up 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_to | String | No | Message id (mid) to reply to. Applies to the text. |
| tag | String | No | "HUMAN_AGENT" to reply up to 7 days after the person's last message (see above). |
| sender_action | String | No | typing_on, typing_off or mark_seen. Sent alone, not as a message: it does not count towards the daily DM limit. |
| page_id | String | No | Numeric 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
}
| Status | error_code | Meaning |
|---|---|---|
| 400 | dm_window_blocked | More 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. |
| 400 | messenger_not_connected | The profile has no Facebook account connected. |
| 403 | messenger_not_enabled | Messenger is not enabled for this account yet (limited rollout). Contact support to request access. |
| 400 | messenger_permission_missing | The Facebook connection lacks the messaging permissions. Reconnect Facebook from the dashboard. |
| 400 | messenger_invalid_request | page_id is not a numeric Page id. |
| 400, 403 | messenger_page_unresolved | No Page could be resolved for the profile, or the page_id is not a Page of its Facebook account. |
| 400 | messenger_api_error | Any 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). |
| 401 | messenger_reauth_required | The Facebook connection is no longer valid. Reconnect Facebook. |
| 429 | dm_rate_limited, dm_send_in_progress | Too 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. |
| 502 | messenger_unreachable | Facebook 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.
| Field | Required | Description |
|---|---|---|
platform | Yes | "facebook". |
user | Yes | Profile username with Facebook connected. |
file | Yes | The file, up to 25 MB. |
type | No | image, video, audio or file. Detected from the file when omitted. |
page_id | No | Numeric 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
| Name | Value | Description |
|---|---|---|
| Authorization | Apikey your-api-key-here | Your API key for authentication |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| platform | String | Yes | "facebook". |
| user | String | Yes | Profile username (as configured in Upload-Post). |
| page_id | String | No | Numeric id of the Page to read, when the profile has no Page selected or you want another Page of the same Facebook account. |
| limit | Integer | No | Conversations per page, 1 to 50. Default 20. |
| cursor | String | No | pagination.next_cursor from the previous page. |
| since | String | No | Only conversations with activity after this moment. Unix seconds, Unix milliseconds or an ISO 8601 date. |
| participant_id | String | No | PSID of a person, to fetch only your conversation with them. |
| messages_limit | Integer | No | Latest 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" }
}
| Field | Description |
|---|---|
participants | The person (id = their PSID, the recipient_id you send to) and your Page (is_me: true). |
messages[].direction | in (from the person) or out (from your Page). |
messages[].message | The text. Empty when the message is only an attachment. |
messages[].attachments | List 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[].status | Outgoing only: sent, delivered or read, updated from Messenger's delivery and read receipts. |
messages[].reactions | Reactions on this message: [{emoji, direction}], where direction is in (the person reacted) or out (your Page reacted). Reactions are not separate messages. |
page | The Page that was read. |
pagination | Pass 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
- Daily DM limits: Messenger messages count towards the same daily DM limit of your Upload-Post account as Instagram and WhatsApp messages.
sender_actiondoes not (typing_on,typing_off,mark_seen). When the limit is reached, the API returns429. - Messenger policies: Meta does not allow promotional messages outside the 24-hour window, and
HUMAN_AGENTis for replies written by people. Breaking these rules can get the Page's messaging restricted by Meta.