Graph API
This document refers to an outdated version of Graph API. Please use the latest version.
Graph API Version

Conversation /{conversation-id}

Use the Messenger Platform API

While the conversation endpoint allows your app to send plain text messages and retrieve message history, we recommend using the Send API instead. The Send API allows your app to send Templates, Quick Replies, and more.

A Facebook Messages conversation between a person and a Facebook Page.

Reading

Graph API Explorer
GET /v9.0/{conversation-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{conversation-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{conversation-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{conversation-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{conversation-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

As part of the V3.3 changes the read_page_mailboxes permission was deprecated. Use pages_messaging permission to access this endpoint. The read_page_mailboxes permission will stop working for all previous versions on June 30 2020

Fields

Name Description Type

id

The ID of a conversation, in a format similar to t_000000000000000

string

link

The url to the thread

string

snippet

The snippet of the most recent message in a conversation

string

updated_time

Last update time

datetime

message_count

An estimate of the number of messages

int

unread_count

An estimate of the number of unread messages

int

Vector

Vector

participants

People and Pages who are on this conversation

Struct { 'name' => string, 'email' => string, 'id' => string }

senders

People who have sent a message

Struct { 'name' => string, 'email' => string, 'id' => string }

can_reply

Whether the Page is able to reply

boolean

is_subscribed

Whether the Page is subscribed to the conversation

boolean

The thread_key and thread_id as well as associated Messages Webhooks are deprecated in v2.11 and higher.

Folders

Conversations can be grouped into different folders.

Folder ValueDescription

inbox

Messages in your inbox

other

page_done

Messages marked as Done that are no longer in your Page's main inbox. These messages are no longer visible in your inbox.

pending

Messages in your pending folder

spam

Messages marked as Spam. These messages are no longer visible in your inbox but have not been deleted.

Edges

The Conversations edge is not a Time-Based edge. To view conversations, use the Graph Explorer to view the page conversations, {page-id}?fields=conversations.

GET graph.facebook.com/{page_id}?fields=conversations{id}

returns:

{
  "conversations": {
    "data": [
      {
        "id": "m_5gMLzaXEBulHBwv6nU7X_hxByiF3gXqRcs5CcflNP_gDE3JPztdB55AuS5FQ0JZWOf7Vr63hDsF3y3aTJHVHlg"
      },
      {
        "id": "m_xuIvBo8jsWDGLDKkSX5nQss9537o-4YE54PYl8e6yCOkbUPgxFxb48rrkRzC-rXT0QZipYa_2Rw66I3auFH6Lg"
      }
    ],
    ...

Click on the id and search the messages field to view a specific conversation:

GET graph.facebook.com/{id}?fields=messages{message}

returns:

"messages": {
  "data": [
    {
      "message": "Hello World!",
      ...
    }

Publishing

You can't publish using this edge.

Deleting

You can't delete using this edge.

Updating

You can't update using this edge.

Edges

Name Description Used to Publish

/messages

List of all messages in the conversation

Replies (by Pages only)