Sharing to Stories

With Sharing to Stories, you can allow your app's Users to share your content as an Instagram story.

Overview

By using Android Implicit Intents and iOS Custom URL Schemes, your app can pass photos, videos, and stickers to the Instagram app. The Instagram app will receive this content and load it in the story composer so the User can publish it to their Instagram Stories.

The Instagram app's story composer is comprised of a background layer, a sticker layer, and an attribution link.

Background Layer

The background layer fills the screen and you can customize it with a photo, video, solid color, or color gradient.

Sticker Layer

The sticker layer can contain an image, and the layer can be further customized by the User within the story composer.

Attribution Link — Approved Apps Only

The attribution link appears as text displaying your app's icon and name, and can deep link to content within your app.

This feature is currently in closed beta and only available to developers who have been approved for access. To request approval, complete this form.

Android Developers

Android implementations use implicit intents to launch the Instagram app and pass it content. In general, your sharing flow should:

  1. Instantiate an implicit intent with the content you want to pass to the Instagram app.
  2. Start an activity and check that it can resolve the implicit intent.
  3. Resolve the activity if it is able to.

Shareable Content

You can pass the following content to the Instagram app:

ContentTypeDescription

Background asset *

Uri

Uri to an image asset (JPG, PNG) or video asset (H.264, H.265, WebM). Recommended image dimensions: 640x480. Videos can be 1080p and up to 20 seconds in duration.

Sticker asset *

Uri

Uri to an image asset (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background.

Background layer top color

String

A hex string color value used in conjunction with the background layer bottom color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead. Note that if you are passing a background asset, the asset will be used and these values will be ignored.

Background layer bottom color

String

A hex string color value used in conjunction with the background layer top color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead. Note that if you are passing a background asset, the asset will be used and these values will be ignored.

Attribution Link

String

A deep link URL to content in your app. If missing, the story will not include an attribution link. This feature is currently in closed beta and only available to developers who have been approved for access.

* You must pass the Instagram app a background asset, a sticker asset, or both.

Sharing a Background Asset

This sample code shows how to pass the Instagram app a background layer image asset and an attribution deep link.

// Define image asset URI and attribution link URL
Uri backgroundAssetUri = "your-image-asset-uri-goes-here;"
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";

// Instantiate implicit intent with ADD_TO_STORY action,
// background asset, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG);
intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
intent.putExtra("content_url", attributionLinkUrl);

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

Sharing a Sticker Asset

This sample code shows how to pass the Instagram app a sticker layer image asset, an attribution deep link, and a set of background layer colors. Note that if you do not supply background layer colors, we will set the background layer color to #222222.

// Define image asset URI and attribution link URL
Uri stickerAssetUri = "your-image-asset-uri-goes-here;"
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";

// Instantiate implicit intent with ADD_TO_STORY action,
// sticker asset, background colors, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.setType(MEDIA_TYPE_JPEG);
intent.putExtra("interactive_asset_uri", stickerAssetUri);
intent.putExtra("content_url", attributionLinkUrl);
intent.putExtra("top_background_color", "#33FF33");
intent.putExtra("bottom_background_color", "#FF00FF");

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
activity.grantUriPermission(
    "com.instagram.android", stickerAssetUri, Intent.FLAG_GRANT_READ_URI_PERMISSION);
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

Sharing a Background Asset and a Sticker Asset

This sample code shows how to pass the Instagram app a background layer image asset, a sticker layer image asset, and an attribution deep link URL.

// Define background and sticker asset URIs and attribution link URL
Uri backgroundAssetUri = "your-background-image-asset-uri-goes-here;"
Uri stickerAssetUri = "your-sticker-image-asset-uri-goes-here;"
String attributionLinkUrl = "https://www.my-aweseome-app.com/p/BhzbIOUBval/";

// Instantiate implicit intent with ADD_TO_STORY action,
// background asset, sticker asset, and attribution link
Intent intent = new Intent("com.instagram.share.ADD_TO_STORY");
intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION);
intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG);
intent.putExtra("interactive_asset_uri", stickerAssetUri);
intent.putExtra("content_url", attributionLinkUrl);

// Instantiate activity and verify it will resolve implicit intent
Activity activity = getActivity();
activity.grantUriPermission(
    "com.instagram.android", stickerAssetUri, Intent.FLAG_GRANT_READ_URI_PERMISSION);
if (activity.getPackageManager().resolveActivity(intent, 0) != null) {
  activity.startActivityForResult(intent, 0);
}

iOS Developers

iOS implementations use a custom URL scheme to launch the Instagram app and pass it content. In general, your sharing flow should:

  1. Check that your app can resolve Instagram's custom URL scheme.
  2. Assign the content that you want to share to the pasteboard.
  3. Resolve the custom URL scheme if your app is able to.

Shareable Content

You can pass the following content to the Instagram app:

ContentKey NameTypeDescription

Background image asset *

com.instagram.sharedSticker.backgroundImage

NSData *

Data for an image asset in a supported format (JPG, PNG). Recommended dimensions: 640x480.

Background video asset *

com.instagram.sharedSticker.backgroundVideo

NSData *

Data for video asset in a supported format (H.264, H.265, WebM). Videos can be 1080p and up to 20 seconds in duration. Under 50 MB recommended.

Sticker asset *

com.instagram.sharedSticker.stickerImage

NSData *

Data for an image asset in a supported format (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background.

Background layer top color

com.instagram.sharedSticker.backgroundTopColor

NSString *

A hex string color value used in conjunction with the background layer bottom color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead.

Background layer bottom color

com.instagram.sharedSticker.backgroundBottomColor

NSString *

A hex string color value used in conjunction with the background layer bottom color value. If both values are the same, the background layer will be a solid color. If they differ, they will be used to generate a gradient instead.

Attribution URL

com.instagram.sharedSticker.contentURL

NSString *

A deep link URL to content in your app. If missing, the story will not include an attribution link. This feature is currently in closed beta and only available to approved developers.

* You must pass the Instagram app a background asset (image or video), a sticker asset, or both.

Whitelisting Instagram's Custom URL Scheme

You need to whitelist Instagram's custom URL scheme in order for your app use it. To do this, add instagram-stories:// to the LSApplicationQueriesSchemes key in your app's Info.plist.

Sharing a Background Asset

This sample code shows how to pass the Instagram app a background layer image asset and an attribution deep link.

- (void)shareBackgroundImage {
      [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
             attributionURL:@"http://your-deep-link-url"];
}

- (void)backgroundImage:(NSData *)backgroundImage 
         attributionURL:(NSString *)attributionURL {

  // Verify app can open custom URL scheme, open if able
  NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {
  
        // Assign background image asset and attribution link URL to pasteboard
        NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage,
                                       @"com.instagram.sharedSticker.contentURL" : attributionURL}];
        NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
        // This call is iOS 10+, can use 'setItems' depending on what versions you support
        [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];
    
        [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}

Sharing a Sticker Asset

This sample code shows how to pass the Instagram app a sticker layer image asset, an attribution deep link, and a set of background layer colors. Note that if you do not supply background layer colors, we will set the background layer color to #222222.

- (void)shareStickerImage {
      [self stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])
      backgroundTopColor:@"#444444"
   backgroundBottomColor:@"#333333"
          attributionURL:@"http://your-deep-link-url"];
}

- (void)stickerImage:(NSData *)stickerImage 
    backgroundTopColor:(NSString *)backgroundTopColor 
 backgroundBottomColor:(NSString *)backgroundBottomColor
        attributionURL:(NSString *)attributionURL {

  // Verify app can open custom URL scheme. If able,
  // assign assets to pasteboard, open scheme.
  NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {

  // Assign sticker image asset and attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.stickerImage" : stickerImage,
                                     @"com.instagram.sharedSticker.backgroundTopColor" : backgroundTopColor,
                                     @"com.instagram.sharedSticker.backgroundBottomColor" : backgroundBottomColor,
                                     @"com.instagram.sharedSticker.contentURL" : attributionURL}];
      NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
      // This call is iOS 10+, can use 'setItems' depending on what versions you support
      [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];

      [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}

Sharing a Background Asset and Sticker Asset

This sample code shows how to pass the Instagram app a background layer image asset, a sticker layer image asset, and an attribution deep link URL.

- (void)shareBackgroundAndStickerImage {
  [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])
           stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])
         attributionURL:@"http://your-deep-link-url"];
}

- (void)backgroundImage:(NSData *)backgroundImage 
           stickerImage:(NSData *)stickerImage 
         attributionURL:(NSString *)attributionURL {

  // Verify app can open custom URL scheme. If able,
  // assign assets to pasteboard, open scheme.
  NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share"];
  if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) {

      // Assign background and sticker image assets and 
      // attribution link URL to pasteboard
      NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage,
                                     @"com.instagram.sharedSticker.stickerImage" : stickerImage,
                                     @"com.instagram.sharedSticker.contentURL" : attributionURL}];
      NSDictionary *pasteboardOptions = @{UIPasteboardOptionExpirationDate : [[NSDate date] dateByAddingTimeInterval:60 * 5]};
      // This call is iOS 10+, can use 'setItems' depending on what versions you support
      [[UIPasteboard generalPasteboard] setItems:pasteboardItems options:pasteboardOptions];

      [[UIApplication sharedApplication] openURL:urlScheme options:@{} completionHandler:nil];
  } else {
      // Handle older app versions or app not installed case
  }
}

Sharing to Facebook Stories

You can also allow your app's Users to share your content as a Facebook story. To learn how to do this, please refer to our Facebook Sharing to Stories documentation.