Skip to content

Facebook Messenger API

The Facebook Messenger API lets a developer list conversations for a connected Facebook Page, read message history for a thread, and send replies programmatically through a unified messages endpoint.

List Facebook Messenger conversations request
curl "{{API_BASE_URL}}/v1/messages?platform=facebook&accountId=acc_fb_page_456&limit=20" \
  -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/messages?platform=facebook&accountId=acc_fb_page_456&limit=20" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

It is scoped to Facebook Page conversations rather than personal profiles, and replies are subject to Meta's 24-Hour Window rule. The worked example in this guide preserves the exact supplied request and response shape for listing conversations, including the accountId query parameter, the x-access-key header, and the nextCursor field used for pagination.

Facebook Messenger API overview and Facebook Page scope

A Facebook Messenger API is most useful when the goal is to operate a Facebook Page inbox from your own product instead of rebuilding the underlying Meta Graph API workflow for every customer. The core operations are List Conversations, Read Message History, and Send Replies. Listing returns each conversation with participant names and profile pictures, the most recent message, and an updated time. Reading history loads the messages in a thread so you can rebuild the full conversation on your side. Sending a reply gives you a sent message identifier that you can store alongside your own records for later reconciliation.

The scope is a connected Facebook Page, not a personal Facebook profile. That distinction matters for product design: your integration should ask the user to connect the Page whose inbox they want to manage, then use that Page's account identifier for conversation calls. If a user tries to connect a personal profile, the expected failure is that no Page inbox is available for that account.

Integration follows three practical steps. First, obtain an API key for the unified service. Second, connect the Facebook Page account once and integrate the messages calls alongside posting, scheduling, analytics, and comment management if your product needs those capabilities. Third, decide whether a unified endpoint fits your roadmap. A unified /v1/messages surface is attractive when you want the same request and response shape across messaging platforms, while building directly against the Meta Graph API may fit better when you need Meta-specific controls, custom permission handling, or a native Meta integration that you are prepared to maintain through App Review and platform changes.

List Conversations: exact request and field map

Listing conversations is the entry point for building an inbox. The supplied example requests the messages collection with platform=facebook, accountId set to the connected Page account, and a limit of 20, authenticated with the x-access-key header. The response includes success, selfId, and selfUsername for the connected account, followed by a conversations array. Each conversation includes an id, a participants array with id, name, username, and profilePictureUrl for each participant, a lastMessage object with id, text, from, and timestamp, and an updatedTime value. The top-level nextCursor value is the pagination handle for fetching the next page of conversations.

Treat nextCursor as opaque. Store it exactly as returned, pass it back on the next list request according to the implemented pagination contract, and stop when no cursor is returned. Do not try to decode, sort, or synthesize a cursor. For inbox rendering, use updatedTime to order conversations, participants to identify the customer and the Page, and lastMessage to show a preview and the time of the most recent activity. Keep the sent message ID from a reply together with the conversation id so your own delivery records can be reconciled later.

Read Message History and Send Replies

Read Message History loads the messages in a Messenger thread, paginated, with the sender and a timestamp for each message. Use it after listing conversations to reconstruct the full thread in your own inbox, CRM, or help desk. Send Replies sends a reply to a customer in one call, and the response returns the sent message ID for tracking. The supplied source material describes these capabilities and their expected data, but it does not supply a complete request and response contract for history or reply operations beyond the list-conversations example. Implementations should therefore confirm the exact method, path, parameters, and response fields for history and reply calls from the authoritative contract before treating them as stable.

24-Hour Window failure matrix

Meta permits an ordinary response only during the day that follows the customer's most recent message. This 24-Hour Window comes from the platform itself, not from the API layer wrapping it. Your product should check the timing of the last customer message before attempting a standard reply, and when a send is attempted outside the window, surface the failure clearly instead of silently queuing or retrying it as if it were a transient error. A useful failure matrix distinguishes an outside-window reply, which should be rejected and shown to the agent, from a personal-profile account, which is out of scope, from a pagination problem, where the cursor should be preserved and retried, and from an unavailable platform status, where the feature should be disabled or gated until availability is confirmed for the connected account.

Build your own inbox and CRM integration criteria

The same data used by a dashboard inbox can power a branded support inbox or be wired into a CRM and help desk. List Conversations gives you the inbox queue, Read Message History gives you the thread view, and Send Replies gives you the agent action. Because the Facebook surface uses the same /v1/messages request and response shape as other messaging endpoints, a team can add Facebook Page messaging to an existing multi-platform inbox without learning a separate integration pattern for each network. Related messaging surfaces include Instagram conversations, Twitter / X conversations, LinkedIn conversations, and TikTok conversations, and the same connected accounts can also support posting, scheduling, analytics, comments, and comment-to-DM workflows where those capabilities are needed.

Supplied list-conversations response field map
FieldLocationType in supplied examplePurpose
successResponse top levelbooleanIndicates whether the list call succeeded.
selfIdResponse top levelstringIdentifier for the connected account.
selfUsernameResponse top levelstringDisplay username for the connected account.
conversationsResponse top levelarrayConversation objects for the connected Facebook Page.
conversations[].idConversation objectstringConversation identifier used to load history and send replies.
conversations[].participantsConversation objectarrayParticipants with id, name, username, and profilePictureUrl.
conversations[].lastMessageConversation objectobjectMost recent message with id, text, from, and timestamp.
conversations[].updatedTimeConversation objectstring (ISO 8601 in example)Last update time for ordering the inbox.
nextCursorResponse top levelstringOpaque pagination cursor for the next page of conversations.

Supplied example only; history and reply contracts were not supplied in full, and the HTTP method for /v1/messages was not explicit in the captured block.

Input contract: supplied fields versus missing history and reply details
OperationSupplied contract detailNot supplied in source materialImplementation check
List Conversations{{API_BASE_URL}}/v1/messages?platform=facebook&accountId=acc_fb_page_456&limit=20 with x-access-key header, as shown in the supplied curl block; JSON response shape shown in the worked example.Explicit HTTP method, full pagination parameter name for subsequent pages, and error/status contract.Preserve exact path, query parameters, header, and response fields; store nextCursor opaquely; confirm method from authoritative contract.
Read Message HistoryCapability described: paginated messages in a thread, each with sender and timestamp.Exact method, path, parameters, and response schema.Confirm from authoritative contract before implementation; do not invent parameters.
Send RepliesCapability described: one-call reply returning the sent message ID; standard replies limited to the 24-Hour Window.Exact method, path, parameters, request body, and response schema.Confirm from authoritative contract before implementation; surface outside-window failures clearly.

Do not invent alternate native Meta contract details for history or reply operations.

Failure matrix for Facebook Messenger operations
ConditionExpected behaviorUser-facing handling
Reply attempted more than 24 hours after the user's last messageStandard send is rejected by Meta.Show the failure to the agent; do not retry as a transient error.
Connected account is a personal Facebook profileNo Facebook Page inbox is available.Ask the user to connect a Facebook Page.
nextCursor is present in a list responseMore conversations may be available.Fetch the next page using the cursor; stop when no cursor is returned.
Platform availability is not confirmed for the connected accountFeature may be unavailable.Gate the feature and check status or dashboard before building a hard dependency.

Platform rule for the 24-Hour Window is documented in the source; other rows are implementation checks derived from the supplied scope.

Frequently asked questions

What can I do with Facebook Messenger through this API?

You can enumerate threads for a connected Facebook Page, open a thread to review earlier exchanges, and post a response to the customer, all through /v1/messages.

Can I message anyone at any time?

No. A standard response is permitted only during the day following the customer's most recent message. Once that period ends, Meta will refuse an ordinary send.

Does this work for personal Facebook profiles?

No. This surface covers inboxes belonging to Facebook Pages. Personal profiles are outside its scope, so connect the relevant Page to make its conversations accessible.

Do I need Meta App Review myself?

In the captured source description, the provider held the needed messaging permissions and ran the OAuth connection flow, so the connecting user linked a Page through OAuth rather than completing Meta App Review separately. Treat that as a source-scoped description pending owned evidence for any new implementation.

Is Facebook messaging available today?

Confirm availability for your connected account in the status page or dashboard before depending on it. The captured source noted Instagram DMs shipping at that time and Facebook Messenger sharing the same unified surface, while advising a status check rather than assuming availability.

How much does the Messages API cost?

In the captured source description, each Messages API call cost 1 credit, with listing, reading, and sending each counting as one call. Treat that as a source-scoped pricing description pending owned evidence for any new implementation.

List Facebook Messenger conversations response
{
  "success": true,
  "selfId": "1029384756",
  "selfUsername": "Your Brand",
  "conversations": [
    {
      "id": "t_100000000000001",
      "participants": [
        {
          "id": "2233445566",
          "name": "Jane Doe",
          "username": "jane.doe",
          "profilePictureUrl": "https://platform-lookaside.fbsbx.com/..."
        },
        {
          "id": "1029384756",
          "name": "Your Brand",
          "username": "yourbrand",
          "profilePictureUrl": "https://platform-lookaside.fbsbx.com/..."
        }
      ],
      "lastMessage": {
        "id": "m_aWdfbXNnXzEyMw",
        "text": "An example comment.",
        "from": {
          "id": "2233445566",
          "name": "Jane Doe"
        },
        "timestamp": "2026-08-05T16:40:00Z"
      },
      "updatedTime": "2026-08-05T16:40:00Z"
    }
  ],
  "nextCursor": "QVFIUl9..."
}