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: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. Passpage_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
outgoingmessage. - Attachments.
attachment_typeandattachment_urlhold the first attachment of a message. Thedm.receivedevent carries every attachment. - Replies. A message that replies to an earlier one carries
reply_towith the earlier message’splatform_id. - Status. An outgoing message moves from
pendingtosent,delivered, andreadas Facebook reports it.
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 ofquick_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 returns400 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_closedwitherror.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 withmessage_tagreturns422 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.
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:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacksdms:sendordms:read.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 thanaccount_id, or the account needs reconnecting.403 account.permission_missing. The account lacks the permission the call needs:messages.writeto send, react, or send a sender action, andmessages.readto start or read an inbox sync.error.meta.permissionnames it.400 validation.*,422 messaging.tag_not_supported. The body is wrong, or it carries amessage_tag. For avalidation.*error,error.meta.fieldnames the field.400 platform.facebook.window_closed. The messaging window is closed: see The messaging window.422 platform.facebook.thread_unavailable. Facebook refused to deliver to this conversation, which can be restricted or unavailable. Retrying does not help.422 platform.facebook.attachment_failed. Facebook could not fetch or accept the file. Fix the URL or the file and send again.403 platform.facebook.permission_denied. The Facebook scopes granted at connect do not cover the action. Reconnect the account and approve every scope.429 validation.interaction_limit_exhausted. The plan allowance is used up until the next billing period: see Plans.429 platform.facebook.rate_limit. Wait for theRetry-Afterheader when present.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.scopeisaccountorpage. Nothing was sent. Wait for theRetry-Afterheader, then retry.429 messaging.velocity_limit. The Page is sending messages faster than SocialAPI allows. Wait for theRetry-Afterheader. Nothing was sent and no credit was used.429 messaging.recipient_limit. Too many different people were messaged this calendar day (UTC). Wait for theRetry-Afterheader. Nothing was sent and no credit was used.403,404, or503 platform.facebook.<code>,503 platform.facebook.api_error, or501 resource.not_supported. Facebook returned an error that has no row above, where<code>is Meta’s error code: see Platform 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 withpage_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.
Related
- Facebook API: capabilities, Pages, scopes, and webhook events for Facebook
- Facebook comments: private replies that start a Messenger conversation from a comment
- Direct messages: the DM endpoints and fields shared by every platform
- Automations: send DMs and answer button taps without your own handler
- Webhook events: the DM event payloads