With Sharing to Stories, you can allow your app's Users to share your content as an Instagram story.
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 and a sticker layer. Background LayerThe background layer fills the screen and you can customize it with a photo, video, solid color, or color gradient. Sticker LayerThe sticker layer can contain an image, and the layer can be further customized by the User within the story composer. |
Android implementations use implicit intents to launch the Instagram app and pass it content. In general, your sharing flow should:
You can pass the following content to the Instagram app:
Content | Type | Description |
---|---|---|
Background asset * | Uri | Uri to an image asset (JPG, PNG) or video asset (H.264, H.265, WebM). Minimum dimensions 720x1280. Recommended image ratios 9:16 or 9:18. Videos can be 1080p and up to 20 seconds in duration. The Uri needs to be a content Uri to a local file on the device. |
Sticker asset * | Uri | Uri to an image asset (JPG, PNG). Recommended dimensions: 640x480. This image will be placed as a sticker over the background. The Uri needs to be a content Uri to a local file on the device. |
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. |
* You must pass the Instagram app a background asset, a sticker asset, or both.
This sample code shows how to pass the Instagram app a background layer image asset.
// Define image asset URI Uri backgroundAssetUri = Uri.parse("your-image-asset-uri-goes-here"); String sourceApplication = "com.my.app"; // Instantiate implicit intent with ADD_TO_STORY action and background asset Intent intent = new Intent("com.instagram.share.ADD_TO_STORY"); intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG); intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); // Instantiate activity and verify it will resolve implicit intent Activity activity = getActivity(); if (activity.getPackageManager().resolveActivity(intent, 0) != null) { activity.startActivityForResult(intent, 0); }
This sample code shows how to pass the Instagram app a sticker layer image asset 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 Uri stickerAssetUri = Uri.parse("your-image-asset-uri-goes-here"); String sourceApplication = "com.my.app"; // Instantiate implicit intent with ADD_TO_STORY action, // sticker asset, and background colors Intent intent = new Intent("com.instagram.share.ADD_TO_STORY"); intent.putExtra("source_application", sourceApplication); intent.setType(MEDIA_TYPE_JPEG); intent.putExtra("interactive_asset_uri", stickerAssetUri); 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); }
This sample code shows how to pass the Instagram app a background layer image asset and a sticker layer image asset.
// Define background and sticker asset URIs Uri backgroundAssetUri = Uri.parse("your-background-image-asset-uri-goes-here"); Uri stickerAssetUri = Uri.parse("your-sticker-image-asset-uri-goes-here"); String sourceApplication = "com.my.app"; // Instantiate implicit intent with ADD_TO_STORY action, // background asset, and sticker asset Intent intent = new Intent("com.instagram.share.ADD_TO_STORY"); intent.putExtra("source_application", sourceApplication); intent.setFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION); intent.setDataAndType(backgroundAssetUri, MEDIA_TYPE_JPEG); intent.putExtra("interactive_asset_uri", stickerAssetUri); // 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 implementations use a custom URL scheme to launch the Instagram app and pass it content. In general, your sharing flow should:
You can pass the following content to the Instagram app:
Content | Key Name | Type | Description |
---|---|---|---|
Background image asset * |
|
| Data for an image asset in a supported format (JPG, PNG). Minimum dimensions 720x1280. Recommended image ratios 9:16 or 9:18. |
Background video asset * |
|
| 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 * |
|
| 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 |
|
| 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 |
|
| 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. |
* You must pass the Instagram app a background asset (image or video), a sticker asset, or both.
You need to allow list 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
.
This sample code shows how to pass the Instagram app a background layer image asset.
- (void)shareBackgroundImage { [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"])]; } - (void)backgroundImage:(NSData *)backgroundImage { // Verify app can open custom URL scheme, open if able NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share?source_application=com.my.app"]; if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) { // Assign background image asset to pasteboard NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage}]; 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 } }
This sample code shows how to pass the Instagram app a sticker layer image asset 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"]; } - (void)stickerImage:(NSData *)stickerImage backgroundTopColor:(NSString *)backgroundTopColor backgroundBottomColor:(NSString *)backgroundBottomColor { // Verify app can open custom URL scheme. If able, // assign assets to pasteboard, open scheme. NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share?source_application=com.my.app"]; if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) { // Assign sticker image asset to pasteboard NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.stickerImage" : stickerImage, @"com.instagram.sharedSticker.backgroundTopColor" : backgroundTopColor, @"com.instagram.sharedSticker.backgroundBottomColor" : backgroundBottomColor}]; 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 } }
This sample code shows how to pass the Instagram app a background layer image asset and a sticker layer image asset.
- (void)shareBackgroundAndStickerImage { [self backgroundImage:UIImagePNGRepresentation([UIImage imageNamed:@"backgroundImage"]) stickerImage:UIImagePNGRepresentation([UIImage imageNamed:@"stickerImage"])]; } - (void)backgroundImage:(NSData *)backgroundImage stickerImage:(NSData *)stickerImage { // Verify app can open custom URL scheme. If able, // assign assets to pasteboard, open scheme. NSURL *urlScheme = [NSURL URLWithString:@"instagram-stories://share?source_application=com.my.app"]; if ([[UIApplication sharedApplication] canOpenURL:urlScheme]) { // Assign background and sticker image assets to pasteboard NSArray *pasteboardItems = @[@{@"com.instagram.sharedSticker.backgroundImage" : backgroundImage, @"com.instagram.sharedSticker.stickerImage" : stickerImage}]; 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 } }
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.