How to Publish Stories with the Facebook Stories API

Facebook Stories are one of the most popular ways to publish videos, or photos on Facebook, second in popularity only to Facebook Reels. Facebook has been adding a lot of new features to their API and we’re excited that they just released the ability to post Stories using the Meta Graph API. We were waiting for this announcement since the Instagram Stories API already exists.

Let’s explore and learn how to publish using the new Facebook Stories API.

What Are Facebook Stories?

Facebook Stories have emerged as a compelling way to share moments and messages with friends, family, and followers. But what exactly is a Facebook Story, and why should you consider publishing them?

Facebook Stories are short, ephemeral posts that disappear after 24 hours, remind you of anyone, ahem Snapchat. Located at the top of the Facebook timeline, these snippets offer a quick and casual way to share updates, experiences, or thoughts. Unlike regular Facebook posts, Stories are designed for more spontaneous and less polished content, making them a unique tool for real-time engagement.

You can publish a Story as either a photo or as a video. Here is an example of a Facebook Story photo:

Using the Facebook Stories API

If you’re already familiar with the Facebook API, adding Stories API is simple. If you haven’t yet integrated with the Facebook API, we recommend this guide.

Facebook Permissions

You’ll need to be granted the following Facebook permissions. This will require a Meta review and approval, which can take several iterations with the Meta team. Expect a few weeks to several months.

• pages_manage_posts
• pages_read_engagement
• pages_show_list
• business_management

The business_management permission is a difficult permission to obtain, but you’ll need it if any of your users utilize Meta Business Suite.

Publish a Video to Stories

After you have been granted the permissions, your users have authorized their accounts, and you have the access token, you can start the process of uploading a Story video.

Step 1: Initialize session

The first steps is initializing the upload session. Here is the Javascript (Node.js) example:

const initData = await fetch(`https://graph.facebook.com/${page_id}/video_stories?upload_phase=start&access_token=${access_token}`, { method: "POST" }).then(res => res.json());

With the following JSON response:

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v18.0/video_id",
}

Step 2: Upload the video file with a remote URL

Assume you have your video hosted remotely, you can use the upload_url field with your remote URL to upload the file.

First set the header with your remote URL in the file_url:

{
    method: "POST",
    headers: {
      Authorization: `OAuth ${access_token}`,
      file_url: url
    }
};

Next, POST to the upload_url from the JSON response:

const uploadBinaryResponse = await fetch(upload_url, header)
    .then((res) => res.json());

The JSON response of a successful video upload:

{
  "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 
    }
  }
}

Step 3: Publish the Video to Stories

Finally you can publish the video to Facebook Stories by setting the upload_phase to finsh. Again in JavasScript/Node.js:

fetch(`https://graph.facebook.com/${page_id}/video_stories?upload_phase=finish&video_id=${video_id}&access_token=${access_token}`, { method: "POST }).then(res => res.json);

If everything worked, you’ll get the following JSON response:

{
  "success": true,
  "post_id": 1234
}

You can then use the post_id to manage the post, get analytics, retrieve the URL of the post, etc.

Also, you’ll want to do error checking, since we only explained the happy-path and not all of the error scenarios, which Facebook unfortunately doesn’t document.

Publish a Photo to Stories

Publish a photo to Stories is similar to publishing a video.

Step 1: Upload a Photo

You will need to use the Facebook Page Photo API endpoint to upload the photo. Pass in your remote media URL to the photos endpoint:

fetch(`https://graph.facebook.com/${page_id}/photos?access_token=${access_token}&published=false&url=${encodeURIComponent(url)}`, { method: "POST" }).then(res => res.json());

The response will contain a photo_id, which can then be sent to the publish endpoint:

fetch(`https://graph.facebook.com/${page_id}/photo_stories?photo_id=${photo_id}&access_token=${access_token}`, { method: "POST }).then(res => res.json());

If successful, the following JSON will be returned:

{
  "success": true,
  "post_id": 1234
}

An Easier Way to Facebook Stories with an API

An simpler and easier way to use the Facebook Stories API is to use the Ayrshare Social Media API. You can use our Stories API to publish video or photos by just adding one field: stories: true

For example here is how you would send a FB story:

{
    "post": "The description of the video",
    "platforms": ["facebook"],
    "mediaUrls": ["https://img.ayrshare.com/012/stories.mp4"],
    "faceBookOptions": {
        "stories": true
    }
}

Simple as that! You can also post Instagram Stories with the API.

If you want more information, check out our Business Plan.