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.