Graph API
Graph API Version

Graph API Reference /{conversation-id}/messages

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 after June 30 2020

The messages in a conversation between a person and a page.

Reading

Graph API Explorer
GET /v7.0/{conversation-id}/messages 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}/messages',
    '{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}/messages",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{conversation-id}/messages",
    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}/messages"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A page access token with pages_messaging permission is required to view any messages in a conversation that Page is involved in.

Fields

Returns an array of Message objects with additional fields:

Name Description Type

Vector

Vector

Publishing

Deprecated in v6.0 - Use Send API instead

On February 4th, 2020, we announced the deprecation of this POST endpoint on v6.0 of Graph API. On June 30th, 2020, it will be removed from all versions of the API. Please use Send API instead.

This endpoint only allows plain text messages, while the Send API allows apps to send Templates and Quick Replies among other rich messaging features. If you use the Conversation API to send a message outside of the 24 hour window, you may only send messages that fall within the approved use cases of the message tags described here

POST /v7.0/{conversation-id}/messages HTTP/1.1
Host: graph.facebook.com

message=This+is+a+test+message
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{conversation-id}/messages',
    array (
      'message' => 'This is a test message',
    ),
    '{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}/messages",
    "POST",
    {
        "message": "This is a test message"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("message", "This is a test message");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{conversation-id}/messages",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"message": @"This is a test message",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{conversation-id}/messages"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Pages can only reply to a message. They cannot initiate a conversation.

Fields

Parameter Description Type

message

The text of reply. This field is required.

string

Response

Name Description Type

id

The ID of the newly created message.

string

A page admin can privately reply to a user who has commented on a post on the page however a system message will be returned by the Graph API.

GET /v7.0/{conversation-id}/messages?message=You+are+responding+to+Sam+Smith%27s+post%3A+%22Hello+Post%22&id=%7Bconversation-id%7D 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}/messages?message=You+are+responding+to+Sam+Smith%27s+post%3A+%22Hello+Post%22&id=%7Bconversation-id%7D',
    '{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}/messages",
    {
        "message": "You are responding to Sam Smith's post: \"Hello Post\"",
        "id": "{conversation-id}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("message", "You are responding to Sam Smith's post: \"Hello Post\"");
params.putString("id", "{conversation-id}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{conversation-id}/messages",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"message": @"You are responding to Sam Smith's post: \"Hello Post\"",
  @"id": @"{conversation-id}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{conversation-id}/messages"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Deleting

You can't delete using this edge.

Updating

You can't update using this edge.