Skip to main content
SocialAPI reads and sends the Messenger direct messages (DMs) of a connected Facebook Page. A conversation is one person talking to one Page. The Page can message a person only within 24 hours of the person’s last message, and SocialAPI offers no way to reach the person after that. A DM request costs 1 interaction credit, and reads, reactions, typing indicators, and seen receipts cost none. For the rules shared by every platform, see Direct messages.

Endpoints

{conversation_id} is the conversation id from GET /v1/inbox/conversations. {message_id} is a message’s platform_id. A conversation starts when the person messages the Page, or when the person answers a private reply. SocialAPI has no endpoint to start a conversation with someone who never messaged the Page.

Your first message

List the Facebook conversations of one account:
Response (HTTP 200):
Reply into that conversation with two quick replies:
Response (HTTP 200):
message_ids lists the SocialAPI ID of every message the request sent, in send order. When the person taps a quick reply, SocialAPI sends a dm.postback event with its payload.

Conversations on Facebook

Facebook conversations have the fields described in Conversations, with these Facebook values: SocialAPI has no participant profile endpoint for Facebook, and a Facebook conversation never reports whether the person follows the Page.

Accounts with more than one Page

A connected Facebook account can hold more than 1 Page, and each conversation belongs to one of them. Pass page_id (the sapi_page_ ID from GET /v1/accounts/{account_id}/pages) to GET /v1/inbox/conversations to list the conversations of one Page. Sends, reactions, and sender actions take no Page parameter: SocialAPI acts as the Page that owns the conversation. See Pages of an account.

Read messages

GET /v1/inbox/conversations/{conversation_id}/messages lists the messages of a conversation, newest first, in the shape described in Read messages.
  • Messages sent outside SocialAPI. A message typed in Facebook’s own apps, such as Meta Business Suite, appears as an outgoing message.
  • Attachments. attachment_type and attachment_url hold the first attachment of a message. The dm.received event carries every attachment.
  • Replies. A message that replies to an earlier one carries reply_to with the earlier message’s platform_id.
  • Status. An outgoing message moves from pending to sent, delivered, and read as Facebook reports it.
When a conversation or a message is missing from a list, force a refresh with POST /v1/inbox/sync.

Send a message

POST /v1/inbox/conversations/{conversation_id}/messages sends a message as the Page. The fields are in Send a message. On Facebook: SocialAPI sends the text first, then each attachment in order, as separate messages, and the request costs 1 interaction credit. If a send fails part way, the earlier messages stay delivered, and the error carries error.meta.sent_count and error.meta.failed_index. A failed request returns its credit only when the error is a validation.* error and no message was delivered. A request that delivered at least 1 message keeps its credit, and so does a Facebook refusal such as platform.facebook.window_closed. A request refused before any send costs nothing: a missing scope, a 404, a missing permission, messaging.tag_not_supported, messaging.velocity_limit, messaging.recipient_limit, platform.facebook.throttled, and a platform.facebook.window_closed with error.meta.blocked_locally: true. See When a credit comes back. An attachment Facebook cannot fetch or accept returns 422 platform.facebook.attachment_failed.

Interactive messages

A Facebook DM can carry tappable content. Set at most 1 of quick_replies, buttons, or cards: more than 1 returns 400 validation.interactive_conflict. A tap on a quick reply or a postback button sends a dm.postback event with your payload, and the tapped title appears in the conversation as the person’s message. Field rules and every error code are in Interactive messages.

The messaging window

The Page can message a person only within 24 hours of the person’s last message. Outside the window, a send returns 400 platform.facebook.window_closed and sends nothing. The person reopens the window by messaging the Page again.
  • Later sends return the same error. After Facebook refuses a send for a closed window, later sends to that conversation return 400 platform.facebook.window_closed with error.meta.blocked_locally: true, until the person messages the Page again or 24 hours after the refusal, whichever comes first. These later refusals cost no credit. Facebook’s own refusal costs the request’s 1 credit.
  • No message tags. SocialAPI sends no message tag on Facebook, including HUMAN_AGENT, so nothing extends the window. A send with message_tag returns 422 messaging.tag_not_supported.
  • Private replies. A private reply does not open the window and does not end these refusals. The person’s next message does both.

React to a message

POST /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reaction adds the Page’s emoji reaction to a message, and replaces its earlier one. DELETE on the same path, with account_id as a query parameter, removes it.
Response (HTTP 200):
reaction is one emoji, sent as the character, not a name such as love. A name or plain text returns 400 validation.invalid_reaction, and a POST without reaction returns 400 validation.field_required. A reaction costs no credit. SocialAPI sends no event when the person reacts to a message.

Typing indicators and seen receipts

POST /v1/inbox/conversations/{conversation_id}/sender-action shows the person a typing indicator, or marks their messages seen, without sending a message. It costs no credit. Any other action returns 400 validation.invalid_action. If Facebook refuses a sender action because the messaging window is closed, the call returns 400 platform.facebook.window_closed. Facebook does not report when the person is typing. An example request is in Typing indicators and seen receipts.

Delivery and read status

Facebook reports what happens to each message the Page sends, and SocialAPI turns each report into an event: Each event carries page_id. The payloads are in Webhook events.

Limits

Each DM request costs 1 interaction credit. When the allowance is used up, the call returns 429 validation.interaction_limit_exhausted. Facebook’s own rate limit returns 429 platform.facebook.rate_limit.

Errors and debugging

Check these in order when a Facebook DM call fails:
  1. 401, 403 auth.insufficient_scope. The API key is invalid, or a scoped key lacks dms:send or dms:read.
  2. 404 conversation.not_found, 404 account.not_found, 403 account.reconnection_required, 401 platform.facebook.auth. The conversation is not yours or belongs to another connected account than account_id, or the account needs reconnecting.
  3. 403 account.permission_missing. The account lacks the permission the call needs: messages.write to send, react, or send a sender action, and messages.read to start or read an inbox sync. error.meta.permission names it.
  4. 400 validation.*, 422 messaging.tag_not_supported. The body is wrong, or it carries a message_tag. For a validation.* error, error.meta.field names the field.
  5. 400 platform.facebook.window_closed. The messaging window is closed: see The messaging window.
  6. 422 platform.facebook.thread_unavailable. Facebook refused to deliver to this conversation, which can be restricted or unavailable. Retrying does not help.
  7. 422 platform.facebook.attachment_failed. Facebook could not fetch or accept the file. Fix the URL or the file and send again.
  8. 403 platform.facebook.permission_denied. The Facebook scopes granted at connect do not cover the action. Reconnect the account and approve every scope.
  9. 429 validation.interaction_limit_exhausted. The plan allowance is used up until the next billing period: see Plans.
  10. 429 platform.facebook.rate_limit. Wait for the Retry-After header when present.
  11. 429 platform.facebook.throttled. Facebook refused the connected account, or one of its Pages, with its own rate limit, and SocialAPI refuses calls for that account or Page until the wait ends. error.meta.scope is account or page. Nothing was sent. Wait for the Retry-After header, then retry.
  12. 429 messaging.velocity_limit. The Page is sending messages faster than SocialAPI allows. Wait for the Retry-After header. Nothing was sent and no credit was used.
  13. 429 messaging.recipient_limit. Too many different people were messaged this calendar day (UTC). Wait for the Retry-After header. Nothing was sent and no credit was used.
  14. 403, 404, or 503 platform.facebook.<code>, 503 platform.facebook.api_error, or 501 resource.not_supported. Facebook returned an error that has no row above, where <code> is Meta’s error code: see Platform errors.
The full catalog is in Errors.

Scopes

The Facebook scope for Messenger (pages_messaging) and the account permissions it belongs to are in Facebook scopes.

Events

Facebook sends these DM events to your webhook endpoints, each with page_id: dm.deleted and dm.status.failed are not emitted for Facebook. Which events an account receives without the messages.read permission is in Events. The payloads are in Webhook events.

Use from an AI agent

There is no tool for reactions. See MCP tools.
Last modified on November 15, 2026