Instagram Stories API: How to Publish a Story

November 21, 2023

We are excited to announce Ayrshare as the only API-first platform to offer direct posting to Instagram Stories via an API.

Instagram Stories offer a dynamic and powerful method to connect with your audience and strengthen your brand. A Story allow you to share images and videos that last for just 24 hours. These could include pictures of your latest product, an upcoming event photo, or short video snippets addressing common questions. Stories are a wonderful way to try out various content types and engage with your followers.

Ayrshare streamlines this process by allowing you to schedule your stories in advance via our Instagram Stories API – see end of this blog post for details.

Directly Publish the Instagram Stories API

You can directly publish video or photo Stories by making a few calls to the Instagram Stories API.

Before You Begin, Get the Permissions

Assuming you have Facebook app approval, you’ll need both Facebook to approve your app permissions and your users to authorize access to their account – how you get the access token.

The permissions needed for Instagram Stories publish are:

instagram_basic
instagram_manage_insights
pages_read_engagement
pages_show_list

If the token is from a User whose Page role was granted via the Business Manager, i.e. your user uses the Meta Business Suite, one of the following permissions is also required:

ads_management
pages_read_engagement
business_management

You’ll add this to your list of requested user permissions when making the OAuth call. See the links about for details on the process.

Video Publishing

Let’s start with video publishing. Assuming you have Facebook app approval, required permissions, and have generated an auth token for your user, you can make a single POST call with your video URL to publish a story:

POST https://graph.facebook.com/{ig-user-id}/media
  ?video_url={video-url}
  &media_type=STORIES
  &access_token={access-token}

Be sure to include the Instagram User ID you received when authorizing the user, the access token, and the video URL.

The main difference between publishing a regular video* or Reel is the media_type parameter value. For Reels use REELS and for Stories use STORIES.

*Starting November 9, 2023, the VIDEO media_type parameter is no longer supported by the Facebook Graph API. Use instead of the REELS value for both Reels and regular videos.

Image Publishing

Image story publishing is just as easy as videos:

POST https://graph.facebook.com/{ig-user-id}/media
  ?image_url={image-url}
  &media_type=STORIES
  &access_token={access-token}

You’ll need to include the Instagram User ID you received when authorizing the user, the access token, the image URL, and the STORIES media_type.

JSON Response

After successfully posting the media, you’ll receive back the following JSON response that contains the reference ID of the published media:

{
  "id": "17889455560051444"
}

If an error occurred, you’ll receive a JSON object containing the error.

Posting Instagram Stories via the Ayrshare API

If you don’t want to go through the hassle of getting approval, integrating, and supporting Facebook or Instagram APIs, you can use Ayrshare’s Social Media APIs. Start by signing up for Ayrshare, getting your API Key, and linking your Instagram Account, you can easily send your first image or video Story to Instagram.

POST https://app.ayrshare.com/api/post
{   
    "post": "The description of the video",
    "mediaUrls": ["https://img.ayrshare.com/012/vid.mp4"],    
    "instagramOptions": {
        "stories": true,
    }
}

Simply add your single image or video, send some post text – note Instagram does not currently take the text for Stories – and set the parameter stories: true. POST this JSON to https://app.ayrshare.com/api/post and your Story will be published.

Remember that Stories only last for 24 hours and then disappear.

If you want to learn more about publishing to Instagram check out our other article on publishing Instagram Reels via an API.