Page About Story

This document explains how to use The Page About Story API to read, create, update, and delete Page About Story data.

Before You Start

For people who own or manage the Page being queried, you will need:

  • the manage_pages permission
  • a Page access token requested by a User who can perform the MANAGE task on the Page that is being queried

For people who do not own or manage the Page being queried, you will need:

Create a Story

Additional Requirements

Only people who own or manage the Page can create a Page About Story.

Send a POST request to the /{page-id}/page_about_story endpoint with parameters to set the title, the story text, and to publish the story:

curl -i -X POST "https://graph.facebook.com/{page-id}/page_about_story
     ?title=My Title 
     &composed_text=[{text:My Story text., type:UNSTYLED, depth:0}]
     &is_published=true
     &access_token={page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}/page_about_story",
  new JSONObject("{\"title\":\"My Story Title\",\"composed_text\":\"[{\"text\":\"My Story text.\", \"type\":\"UNSTYLED\", \"depth\":0}]\",\"is_published\":\"true\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/page_about_story"
           parameters:@{ @"title": @"My Story Title",@"composed_text": @"[{"text":"My Story text.", "type":"UNSTYLED", "depth":0}]",@"is_published": @"true",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}/page_about_story',
  'POST',
  {"title":"My Story Title","composed_text":"[{\"text\":\"My Story text.\", \"type\":\"UNSTYLED\", \"depth\":0}]","is_published":"true"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}/page_about_story',
    array (
      'title' => 'My Story Title',
      'composed_text' => '[{"text":"My Story text.", "type":"UNSTYLED", "depth":0}]',
      'is_published' => 'true'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app receives the following response:

{
  "page_about_story_id": "{page-story-id}"
}

Create a Story with Inline Style Elements

Send a POST request to the /{page-id}/page_about_story endpoint with parameters to set the title, the story text with style elements, and to publish the story.

curl -i -X POST "https://graph.facebook.com/{page-id}/page_about_story
   ?title=My Story Title
   &composed_text=[        
     {
       "text":"My Facebook Story text.", 
       "type":"UNSTYLED", "depth": 0, 
       "inline_style_ranges": [
         {
           "offset": 12, 
            "length": 5, 
            "style": "ITALIC"
         }
       ]
     }
   ]
   &is_published=true
   &access_token={page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}/page_about_story",
  new JSONObject("{\"title\":\"My Story Title\",\"composed_text\":\"[{\"text\":\"My Facebook Story text.\", \"type\":\"UNSTYLED\", \"depth\": 0, \"inline_style_ranges\": [{\"offset\": 12, \"length\": 5, \"style\": \"ITALIC\"}]}]\",\"is_published\":\"true\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/page_about_story"
           parameters:@{ @"title": @"My Story Title",@"composed_text": @"[{"text":"My Facebook Story text.", "type":"UNSTYLED", "depth": 0, "inline_style_ranges": [{"offset": 12, "length": 5, "style": "ITALIC"}]}]",@"is_published": @"true",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}/page_about_story',
  'POST',
  {"title":"My Story Title","composed_text":"[{\"text\":\"My Facebook Story text.\", \"type\":\"UNSTYLED\", \"depth\": 0, \"inline_style_ranges\": [{\"offset\": 12, \"length\": 5, \"style\": \"ITALIC\"}]}]","is_published":"true"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}/page_about_story',
    array (
      'title' => 'My Story Title',
      'composed_text' => '[{"text":"My Facebook Story text.", "type":"UNSTYLED", "depth": 0, "inline_style_ranges": [{"offset": 12, "length": 5, "style": "ITALIC"}]}]',
      'is_published' => 'true'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app receives the following response:

{
  "page_about_story_id": "{page-story-id}"
}

Get a Story

Send a GET request to the /{page-id} endpoint with the page_about_story field:

curl -i -X GET "https://graph.facebook.com/{page-id}
     ?fields=page_about_story
     &access_token={access-token}"
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{page-id}",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "page_about_story");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}"
           parameters:@{ @"fields": @"page_about_story",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}',
  'GET',
  {"fields":"page_about_story"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{page-id}',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app receives the following response:

{
  "page_about_story": {
    "id": "{page-about-story-id}",
    "page_id": "{page-id}",
    "is_published": true,
    "title": "My Story Title",
    "composed_text": [
      {
        "text": "My Story text.",
        "type": "UNSTYLED",
        "depth": 0
      }
    ]
  },
  "id": "{page-id}"
}

Update a Story

Additional Requirements

Only people who own or manage the Page can update a Page About Story.

Send a POST request to the /{page-story-id} endpoint with the parameters you would like to update:

curl -i -X POST "https://graph.facebook.com/{page-story-id}
     ?composed_text=[{"text": "My longer story text."}]
     &access_token={page-access-token}"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-story-id}",
  new JSONObject("{\"composed_text\":\"[{\\\"text\\\": \\\"My longer story text.\\\"}]\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-story-id}"
           parameters:@{ @"composed_text": @"[{"text": "My longer story text."}]",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-story-id}',
  'POST',
  {"composed_text":"[{\"text\": \"My longer story text.\"}]"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-story-id}',
    array (
      'composed_text' => '[{"text": "My longer story text."}]'
    ),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app receives the following response:

{
  "id": "{page-story-id}"
}

Delete a Story

Additional Requirements

Only people who own or manage the Page can delete a Page About Story.

Send a DELETE request to the /{page-story-id} endpoint where {page-story-id} is the ID of the Page Story you want to delete:

curl -i -X DELETE "https://graph.facebook.com/{page-story-id}
     ?access_token={page-access-token}"
Bundle parameters = new Bundle();

GraphRequest request = new GraphRequest(
  accessToken,
  "/{page-story-id}",
  parameters,
  HttpMethod.DELETE,
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-story-id}"
           parameters:nil
           HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-story-id}',
  'DELETE',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->delete(
    '/{page-story-id}',
    array (),
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app receives the following response:

{
  "success": true
}

Reference

Nodes

NodeDescription
Page

Represents a Facebook Page.

Page About Story

Represents a Facebook Page About Story.

Endpoints

EndpointsDescription
/{page-id}/page_about_story

Creates a Facebook Page About Story.

Parameters

page_about_story ParametersDescription
composed_text
JSON array,Required

The text, image, etc. of your story, including styling.

depth
int, optional

The indent value of text. Only takes effect when type is UNORDERED_LIST_ITEM or ORDERED_LIST_ITEM

entity_ranges
array, optional
  • offset: The index of the entity from the left side border where index starts at 0. non-negative int
    • For IMAGE, this should be 0, since image itself always take up a block
    • For LINK, for example, your text is “Welcome to Facebook” and you want “Facebook” to be a link. Set offset to 10, since “F” is the 10th character, and length to 8.
  • length: The number of characters of the entity. non-negative int
    • For IMAGE, this should be 1
    • offset plus length cannot be greater than the length of the text content.
  • key: Used to find the entity in entity_map. int
inline_style_ranges
array, optional

Should be the same value as

composed_text[entity_ranges]
text
int, optional

Should be the same value as

composed_text[entity_ranges]
type
int, optional

Should be the same value as

composed_text[entity_ranges]
cover_photo
dictionary, optional

The cover photo of your Page About Story.

  • photo_id: ID of the photo that has already been uploaded to Facebook. Learn more about the Photo node and Page photos.int, required
  • x_offset: horizontal offset int, optional
  • y_offset: horizontal offset int, optional horizontal offset
entity_map

Description of an entity map.

array, optional
caption

Description under the image.

string, optional for IMAGE
key

Should be the same value as

composed_text[entity_ranges]int, required
photo_id

Photo ID

int, required for IMAGE
position

LEFT, RIGHT, CENTER, default is CENTER

enum, optional for IMAGE
size

COLUMN, LARGE, MAXIMUM, default is NONE. Only takes effect when when position is CENTER.

enum, optional for IMAGE
type

IMAGE or LINK

enum, required
url

A link within your text.

string, required for LINK
is_published

Returns if the Page About Story is published or not.

boolean, optional
title

The title of your Page About Story.

string, optional