This document shows you how to use the Facebook Stories API to publish Stories on Facebook Pages.
To publish a story, you will perform the following steps:
This guide assumes you have read the Pages API Overview and implemented the needed components, and successfully completed the Get Started guide.
You will need to implement Facebook Login or Facebook Login for Business to ask your app users for permissions needed to access their Facebook Pages and to receive Page access tokens.
Your app users will need to be able to perform the CREATE_CONTENT
task on the Page represented in the Page access token and give your app the following permissions:
pages_manage_posts
pages_read_engagement
pages_show_list
If you are using a business system user in your API requests, the business_management
permission is also required.
You must provide a photo or video that fit the following specifications.
屬性 | 規格 |
---|---|
檔案類型 | .jpeg、.bmp、.png、.gif、.tiff |
檔案大小 | 檔案不能超過 4MB。對於 .png 檔案,建議不要超過 1MB,否則圖像可能會出現像素化。 |
屬性 | 規格 | ||
---|---|---|---|
檔案類型 | .mp4(建議) | ||
長寬比 | 9 x 16 | ||
解析度 | 1080 x 1920 像素(建議)。最低為 540 x 960 像素 | ||
影格速率 | 每秒 24 至 60 影格 | ||
時間長度 | 3 至 90 秒。 以限時動態發佈在 Facebook 粉絲專頁上的連續短片不能超過 60 秒。 | ||
影片設定 |
| ||
音訊設定 |
|
GET
requests to see a list of your stories, you must
turn your Facebook story archive on
When testing an API call, you can include the access_token
parameter set to your access token. However, when making secure calls from your app, use the access token class.
Code examples within this document are formatted for readability. Replace bold, italics values, such as page_id, with your values.
To publish a video story on a Facebook Page, you will initialize a video upload session with Meta servers, upload the video to Meta servers, then publish the video story.
To initialize an upload session, send a POST
request to the /page_id/video_stories
endpoint, where page_id
is the ID for your Facebook Page, with the upload_phase
parameter set to start
.
curl -X POST "https://graph.facebook.com/v21.0
/page_id/video_stories" \
-d '{
"upload_phase":"start",
}'
On success, your app receives a JSON response with the ID for the video and the Facebook URL where you will be uploading the video.
{
"video_id": "video_id",
"upload_url": "https://rupload.facebook.com/video-upload/v21.0
/video_id",
}
Now that you have initialized an upload session and received the upload URL, you can upload your video. You can upload either:
To upload a hosted file, send a POST
request to the upload_url
endpoint you received in the initialization step with the following parameters:
file_url
set to the URL for your video file
curl -X POST "https://rupload.facebook.com/video-upload/v21.0
/video_id" \
-H "file_url: https://some.cdn.url/video.mp4"
To upload a local file, send a POST
request to the upload_url
endpoint you received in the initialization step with the following parameters:
offset
set to 0
file_size
set to the total size in bytes of the video being uploaded
curl -X POST "https://rupload.facebook.com/video-upload/v21.0
/video_id" \
-H "offset: 0" \
-H "file_size: file_size_in_bytes" \
--data-binary "@/path/to/file/my_video_file.mp4"
On upload success, your app receives a JSON response with success
set to true
.
{ "success": true }
If the video upload is interrupted, you can either restart the upload or resume it.
POST
request and set offset
to 0
. POST
request with offset
set to the bytes_transfered
value from a status check.To check a status of your video, during upload or publishing, send a GET
request to the /video_id
endpoint with the following parameter:
fields
set to status
curl -X GET "https://graph.facebook.com/v21.0
/video_id" \
-d "fields=status"
On success, your app receives a JSON response that contains:
status
object that contains:
video_status
with a value of ready
, processing
, expired
, or error
uploading_phase
object with the following key-value pairs:
status
set to in_progress
, not_started
, complete
, or error
bytes_transfered
set to the bytes that have been uploaded. can be used as the value for offset
if the upload is interrupted.processing_phase
object with the following key-value pairs:
status
set to in_progress
, not_started
, complete
, or error
processing_phase
object with the following key-value pairs:
status
set to in_progress
, not_started
, complete
, or error
publish_status
set to published
or not_published
publish_time
set to a UNIX timestamp of the actual or published time
The following response shows a file that has been successfully uploaded.
{ "status": { "video_status": "processing", "uploading_phase": { "status": "in_progress", "bytes_transfered": 50002 }, "processing_phase": { "status": "not_started" } "publishing_phase": { "status": "not_started", "publish_status": "published", "publish_time": 234523452 } } } |
The following response shows an error has occurred in the processing phase.
{ "status": { "video_status": "processing", "uploading_phase": { "status": "complete" }, "processing_phase": { "status": "not_started", "error": { "message": "Resolution too low. Video must have a minimum resolution of 540p." } } "publishing_phase": { "status": "not_started" } } } |
To publish your video story to your Page, you will send a POST
to the /page_id
/video_stories
endpoint with the following parameters:
video_id
set to the ID for your uploaded videoupload_phase
set to finish
curl -X POST "https://graph.facebook.com/v21.0
/page_id/video_stories" \
-d '{
"video_id": "video_id",
"upload_phase": "finish"
}'
On success, your app receives a JSON response that contains the following key-value pairs:
success
set to true
post_id
set to the ID for your story post{ "success": true, "post_id": 1234 }
Visit the
Page Posts Reference
to learn how to upload a photo to Meta servers using the /page_id/photos
endpoint. Be sure to include the published
parameter and set it to false
.
To publish your photo story to your Page, you will send a POST
to the /page_id
/photo_stories
endpoint with the following parameters:
photo_id
set to the ID for your uploaded photo
curl -X POST "https://graph.facebook.com/v21.0
/page_id/photo_stories" \
-d '{
"photo_id": "photo_id"
}'
On success, your app receives a JSON response that contains the following key-value pairs:
success
set to true
post_id
set to the ID for your story post{ "success": true, "post_id": 1234 }
To get a list of all stories for a Page and data about each story, send a GET
request to the /
page_id
/stories
endpoint where page_id
is the ID for the Page you want to view.
curl -i -X GET "https://graph.facebook.com/v21.0
/page_id/stories"
On success, your app receives a JSON response with an array of objects where each object contains information about a story published on the Page. Each object contains the following key-value pairs:
post_id
set to the ID for the published story poststatus
set to PUBLISHED
, ARCHIVED
creation_time
set to UNIX timestamp when the story was publishedmedia_type
set to either video
or photo
media_id
set to the ID for the video or photo in the story posturl
set to the Facebook URL for the story post, such as https://facebook.com/stories/8283482737484972
{ "data": [ { "post_id": "post_id", "status": "PUBLISHED", "creation_time": "123456", "media_type": "video", "media_id": "video_id", "url": "https://facebook.com/stories…" }, { "post_id": "post_id", "status": "PUBLISHED", "creation_time": "123456", "media_type": "photo", "media_id": "photo_id", "url": "https://facebook.com/stories…" }, { "post_id": "post_id", "status": "ARCHIVED", "creation_time": "123456", "media_type": "photo", "media_id": "photo_id", "url": "https://facebook.com/stories…" }, ... ], }
You can filter stories by status, published or archived, and date, using the since
and until
parameters.
Learn more about the endpoints and concepts discussed in this guide.