Instagram

Instagram is covered by Managed Keys: your subscription includes Outstand's own Meta app, so you can connect Instagram Business or Creator accounts and publish photos, videos and Reels through Outstand's unified API without registering anything yourself. The Bring Your Own Key (BYOK) steps below are optional - follow them only if you want your own Meta app credentials on the connection screen.

Managed Keys are included with your subscription. We handle the OAuth app setup for you, so you can skip the approval process entirely. Follow the steps below only if you want full white-labelling with your own Meta app credentials (BYOK). Contact support@outstand.so if you have questions about your Managed Keys setup.

Quick Information

Our application works with the following OAuth scopes:

• instagram_business_basic - Basic Instagram access (allows reading profile)
• instagram_business_content_publish - Permission to publish posts and Reels
• instagram_business_manage_comments - Permission to interact with comments
• instagram_business_manage_insights - Permission to read engagement metrics
• instagram_business_manage_messages - Permission to read and send direct messages (Managed Keys only, not requested by default, see Direct Messages)

Whether you use Managed Keys or BYOK, the first four are the OAuth scopes requested by default and required for the integration to work. instagram_business_manage_messages is only used by Direct Messages and must be requested explicitly, see Enable Direct Messages.

Prerequisites

This is a process which takes a considerable amount of time to complete. It's recommended to start the process well in advance of needing to use the integration. In our experience it takes at least 2 weeks to get the integration approved and fully working.

Before you begin, ensure you have:

• A Meta (Facebook) Developer account
• An Instagram Business or Creator account (personal accounts cannot be used for posting via API)
• A Facebook Page linked to your Instagram account (required by Meta for the Graph API; link via Instagram → Settings → Account → Linked accounts)
• Basic understanding of Meta's Instagram Graph API

Note: Instagram Business accounts can be managed by multiple users and are designed for social media management tools. Creator accounts are primarily for influencers. Convert your personal account to a Business or Creator account before proceeding. Linking to a Facebook Page is mandatory for Instagram Business/Creator API access.

Step 1: Create a Meta Developer Account

If you don't already have one:

1. Go to developers.facebook.com
2. Click Get Started or My Apps in the top right
3. Sign in with your Facebook account
4. Complete your developer profile by verifying your identity

Step 2: Create a New App

1. Navigate to developers.facebook.com/apps
2. Click Create App
3. Select your app type:
   • Choose Business if you're managing social media for a business
   • Instagram integration is most commonly used with Business apps
4. Fill in the required details:
   • App Display Name: Your application name (e.g., "My Instagram Manager")
   • App Contact Email: Your email address
   • Business Account: Select or create a Business Account (required for Instagram API)

Step 3: Add Instagram Product to Your App

1. After creating your app, you'll see the Add Products to Your App page
2. Find Instagram in the list of available products
3. Click Set Up next to Instagram
4. Accept the required permissions and terms

If you don't see Instagram:

• Ensure you have a Meta Business Account
• Verify your app type supports Instagram integration
• Some regions may have limited Instagram API access

Step 4: Configure Basic Settings

1. Navigate to Settings → Basic in your app dashboard
2. Fill in the required fields:
   • App Name: Confirm or update your app name
   • App Domain: Your website domain
   • Privacy Policy URL: Link to your privacy policy (required)
   • Terms of Service URL: Link to your terms of service
   • App Icon: Upload a 1024x1024px app icon
   • Category: Select "Business" or "Utility"
3. Click Save Changes

Step 5: Connect Your Instagram Business Account

Before you can use Instagram posting features, you need to connect your Instagram account:

1. Go to Settings → Basic in your app dashboard
2. Scroll down to the Instagram section
3. Click Add or Remove Instagram Accounts
4. Follow the prompts to connect your Instagram Business or Creator account
5. You may be asked to connect a Facebook Page - this is required for Instagram Business accounts

Note: Your Instagram account must be a Business or Creator account. You cannot use a personal Instagram account with the API. Convert your account if necessary through Instagram settings.

Step 6: Configure OAuth Settings

1. Scroll to Basic Settings → Add Platform

2. Select Website from the platform options

3. Enter your Site URL (required for OAuth redirects)

4. Add Valid OAuth Redirect URIs:

   • For production: https://www.outstand.so/app/api/socials/instagram/callback

5. In Instagram → API setup with Instagram login → Set up Instagram business login → Business login settings, set the callback URLs, replacing {YOUR_APP_ID} with your Instagram App ID:

   • Deauthorize callback URL: https://webhooks.outstand.so/instagram/{YOUR_APP_ID}/deauthorize
   • Data deletion request URL: https://webhooks.outstand.so/instagram/{YOUR_APP_ID}/data-deletion

   When either callback arrives, Outstand deletes the account that person connected through your app, together with its tokens, imported posts and message history.

Step 7: Add Required OAuth Scopes

1. You'll need to request the following permissions:

   • instagram_business_basic - Basic Instagram access (allows reading profile)
   • instagram_business_content_publish - Permission to publish posts and Reels
   • instagram_business_manage_comments - Permission to interact with comments
   • instagram_business_manage_insights - Permission to read engagement metrics

As you can see, the permissions are focused on Business Accounts only.

Direct Messages are not available with BYOK yet. You can skip instagram_business_manage_messages in App Review. See Direct Messages for details.

2. Click on each permission to configure:
   • Read the permission description
   • Accept the required use cases
   • Provide detailed explanations for how you'll use the permission
   • Record a screencast showing your app's functionality

Important: Instagram Content Publishing requires detailed explanations and app review. Be specific about your use case for social media management and scheduling.

Step 8: Submit for App Review

Instagram publishing permissions require Meta App Review:

1. Go to App Review → Permissions and Features
2. Click Request next to permissions marked with warnings:
   • instagram_content_publish
   • pages_read_engagement
3. For each permission, provide:
   • How will you use this permission? Describe your social media management use case
   • Why do you need this permission? Explain the business need for posting to Instagram
   • Instructions: Provide clear, step-by-step instructions for reviewers to test your app
4. Submit a screencast showing your app's functionality (required)
5. Configure Test Users (add yourself or colleagues who can test the app)

Processing Time: App review typically takes 1-7 business days. Instagram publishing review can take longer. Meta may request additional information or clarifications.

Step 9: Obtain Your Credentials

1. Navigate to Settings → Basic in your app dashboard

2. You'll find two important values:

   • App ID: This is your OAuth Client ID (referred to as "client_key" in the API)
   • App Secret: This is your OAuth Client Secret (referred to as "client_secret" in the API)

3. Click Show next to App Secret to reveal it

4. Copy both values immediately and store them securely

Security Warning: Your App Secret is sensitive and should never be exposed. Copy it only once and store it securely. You may need to reveal it multiple times, but it's better to save it securely the first time.

Step 10: Add Credentials to Outstand

Once you have your App ID and App Secret, you can add them to Outstand:

Method 1: Using the Dashboard

1. Log in to Outstand Dashboard
2. Navigate to Settings → Social Networks
3. Select Instagram from the dropdown
4. Enter your App ID in the "Client ID / API Key" field
5. Enter your App Secret in the "Client Secret / API Secret" field
6. Click Add Social Network

Method 2: Using the API

curl -X POST https://api.outstand.so/v1/social-networks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "instagram",
    "client_key": "YOUR_APP_ID_HERE",
    "client_secret": "YOUR_APP_SECRET_HERE"
  }'

Step 11: Connect Your Instagram Account

After adding your credentials:

1. Ensure your Instagram account is a Business or Creator account
2. Verify your Instagram account is linked to a Facebook Page
3. Navigate to Accounts in your Outstand dashboard
4. Click Connect Account
5. Select Instagram
6. Complete the Meta authorization flow
7. Grant the required permissions (publish content, read engagement, etc.)
8. Select the Instagram Business account you want to connect
9. Your Instagram account will appear in your connected accounts list

Note: Since Instagram publishing uses the Instagram Graph API, the connection process goes through Meta's OAuth system, but you'll be managing your Instagram Business account.

Troubleshooting

"Invalid client credentials"

• Verify you copied the App ID and App Secret correctly
• Ensure there are no extra spaces or newlines in your credentials
• Check that your app hasn't been deleted or disabled

"App not approved for this operation"

• Instagram publishing requires App Review approval from Meta
• Verify that instagram_content_publish permission has been approved
• Check your app's review status in Meta Business Suite
• You can test in Test Mode before completing App Review

"Redirect URI mismatch"

• Verify the redirect URIs in your Meta app settings match exactly with Outstand's callback URL
• Redirect URIs are case-sensitive

"Instagram account not a Business account"

• Personal Instagram accounts cannot be used with the Graph API
• Convert your account to Business or Creator in Instagram app settings
• Go to Instagram → Settings → Account → Switch to Professional Account

"Instagram not linked to a Facebook Page"

• Instagram Business accounts must be linked to a Facebook Page
• Go to Instagram → Settings → Account → Linked Accounts
• Link your Facebook Page
• You'll need admin access to the Facebook Page

"To use 'Human Agent', your use of this endpoint must be reviewed and approved by Facebook"

• The Meta app that owns the connection has not been approved for Human Agent
• Remove instagram.tag from the request and reply within 24 hours of the contact's last message
• See 24-Hour Messaging Window

Direct messages are not arriving

• Direct Messages only work on Managed Keys. They are not available with your own Meta app (BYOK) yet
• Reconnect the account if it was connected before Direct Messages launched, and approve every requested permission
• The account must be a professional account (Business or Creator). Personal accounts cannot use direct messages
• In the Instagram app, go to Settings → Messages and story replies → Message controls → Connected tools and turn on Allow access to messages
• See Direct Messages for the full requirements

Important Notes

• Business Account Required: Only Instagram Business and Creator accounts can use the API. Personal accounts cannot be integrated.

• App Review: Instagram publishing requires App Review and approval from Meta. This process can take days to weeks. You can test most features in Test Mode before approval.

• Content Types: Instagram Graph API supports:

  • Photo posts (single image)
  • Carousel posts (multiple images/videos, 2-10 items)
  • Video posts / Reels (through Instagram's publishing API)
  • Stories (single image or video, set publishAsStory: true in Instagram config)

• AI Content Disclosure: Self-disclose AI-generated media by setting isAiGenerated: true in the Instagram configuration. See AI Content Disclosure below.

• Credential Security: Never share your App Secret or commit it to version control. Use secure credential management for production apps.

Media Requirements

Instagram validates media through the Graph API Content Publishing endpoints. The limits below come from Meta's official IG User media reference.

Text

• Caption: up to 2,200 characters, with a maximum of 30 hashtags and 20 @ mentions.

Images

Feed Video

Reels

Carousel

• Between 2 and 10 items (images, videos, or a mix). Each image must meet the image requirements above.

Stories

See Publishing Stories below for the full Stories media specification (single media only, JPEG image up to 8 MB, MP4/MOV video 3-60 seconds up to 100 MB).

Publishing Rate Limits

Instagram enforces a Content Publishing rate limit per Instagram account:

• 100 API-published posts within a rolling 24-hour period. A carousel counts as a single post.
• The limit applies to POST /{ig-user-id}/media_publish. You can check current usage via the GET /{ig-user-id}/content_publishing_limit endpoint.
• Stories published via the API count toward this same 100-post limit.

See Meta's Content Publishing documentation for details.

Available Metrics

When using the Account Metrics API with an Instagram account, the following engagement data is available:

Requirements:

• Business or Creator account (personal accounts cannot access insights)
• instagram_business_manage_insights permission must be approved
• Accounts with fewer than 100 followers may have limited insights availability
• Supports date range filtering via since and until parameters (Unix timestamps)

Publishing Stories

Instagram Stories can be published through Outstand by setting publishAsStory: true in the Instagram configuration override when creating a post.

Example

curl -X POST https://api.outstand.so/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "",
    "accounts": ["YOUR_INSTAGRAM_ACCOUNT_ID"],
    "containers": [
      {
        "content": "",
        "media": [{ "url": "https://example.com/story.jpg", "filename": "story.jpg" }]
      }
    ],
    "instagram": {
      "publishAsStory": true
    }
  }'

Stories Limitations

• Single media only - Stories do not support carousel (multiple images/videos). Exactly one image or video is required.
• No caption - Instagram Stories published via API do not support captions or text overlays.
• No interactive stickers - Link, poll, question, countdown, and location stickers are not available via the API.
• No user tags, alt text, or collaborators - These feed post features are not supported for Stories.
• 24-hour expiry - Stories automatically expire 24 hours after publishing (standard Instagram behavior).
• Image specs - JPEG format, max 8 MB, recommended 9:16 aspect ratio (1080x1920).
• Video specs - MP4 or MOV, 3-60 seconds duration, max 100 MB, recommended 9:16 aspect ratio, H264/HEVC codec.
• Rate limit - Stories count toward the shared limit of 100 API-published posts per rolling 24 hours.

Reel Cover Images

When you publish a video, Instagram picks the cover shown in the Reels tab from a frame of the video itself. You can control that in two ways through the Instagram configuration override:

• reelCoverUrl - a public URL to your own cover image (for example, a designed thumbnail).
• reelThumbOffset - an offset in milliseconds, selecting a frame from the video.

If you set both, reelCoverUrl wins and the offset is ignored - this mirrors Instagram's own behavior.

Example

curl -X POST https://api.outstand.so/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Our new product in 30 seconds",
    "accounts": ["YOUR_INSTAGRAM_ACCOUNT_ID"],
    "containers": [
      {
        "content": "Our new product in 30 seconds",
        "media": [{ "url": "https://example.com/reel.mp4", "filename": "reel.mp4" }]
      }
    ],
    "instagram": {
      "reelCoverUrl": "https://example.com/reel-cover.jpg"
    }
  }'

Cover Image Requirements

• Reels only - a cover image can only be set on a single-video post. Setting it on an image post, a carousel, or a Story returns an error.
• Publicly reachable URL - Instagram fetches the image from your server, so it cannot be behind auth. Expiring signed URLs must still be valid when the post publishes (which matters for scheduled posts).
• Format - JPEG, sRGB color space.
• File size - max 8 MB.
• Aspect ratio - 9:16 recommended (1080x1920). If your image is not 9:16, Instagram crops to the middle 9:16 rectangle for the Reels tab, and to the middle 1:1 square if the reel is also shared to the feed.

AI Content Disclosure

Instagram supports self-disclosure of AI-generated content at publish time. Setting isAiGenerated: true in the Instagram configuration override sets Meta's is_ai_generated parameter on the media container, which Instagram surfaces as an "AI info" label on the post.

Example

curl -X POST https://api.outstand.so/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Generated with our new AI creative tool",
    "accounts": ["YOUR_INSTAGRAM_ACCOUNT_ID"],
    "containers": [
      {
        "content": "Generated with our new AI creative tool",
        "media": [{ "url": "https://example.com/ai-image.jpg", "filename": "ai-image.jpg" }]
      }
    ],
    "instagram": {
      "isAiGenerated": true
    }
  }'

Notes

• Applies to all media types - feed posts, Reels, carousels, and Stories.
• Carousels - the flag is applied to the carousel as a whole. Meta rejects is_ai_generated on individual carousel items, so Outstand always sets it on the carousel container, not the child items.
• No extra permissions - no additional OAuth scopes or minimum API version are required.
• Independent of embedded metadata - this is separate from C2PA/IPTC provenance metadata that may already be embedded in your media file. Instagram may apply an AI label from detected metadata even without this flag. See Meta's approach to labeling AI-generated content for how the two signals interact.

Comment Webhooks

Subscribe a webhook endpoint to comment.received to be notified when someone comments on a connected account's post, or replies to a comment on it. It covers every post the account owns, including posts published outside Outstand, and carries the comment text and its author. See the comment.received payload.

• No extra permission - comments need instagram_business_manage_comments, which is one of the default scopes.
• Your own comments are skipped - comments written by the connected account, including replies sent through Outstand, do not trigger the event.
• Reply in a direct message - answer a comment privately with POST /v1/conversations, passing commentId and authorId from the event as instagram.comment_id and instagram.author_id. See Comment-to-DM. Enable Direct Messages on the account so the commenter's answer reaches you.
• Reconnect older accounts - Outstand subscribes an account to comments when it connects. If an account's comments never arrive, reconnect it once: accounts connected before comment webhooks launched were not subscribed. Reconnecting keeps the account's ID, scheduled posts and history.

Direct Messages

Outstand can read and reply to Instagram direct messages for your connected accounts. Inbound messages are delivered to Outstand by Meta in real time and grouped into conversations, one per contact. Direct Messages are opt-in per connection, see Enable Direct Messages. You work with them through the Conversations API:

To react to new messages without polling, subscribe a webhook endpoint to the conversation.started, message.received, message.sent and message.failed events.

Availability

Direct Messages are available on Managed Keys only. They are not supported with your own Meta app (BYOK) yet. Inbound messages reach Outstand through webhooks configured on the Meta app itself, and that setup is not available for customer-owned apps at the moment. If you are on BYOK and need Direct Messages, contact support@outstand.so.

Enable Direct Messages

Direct Messages need the instagram_business_manage_messages permission, which Outstand does not request by default (neither from the dashboard nor from an authentication URL without scopes). To enable them, generate the authentication URL with a scopes list. It replaces the defaults, so include the four default scopes too:

curl -X POST https://api.outstand.so/v1/social-networks/instagram/auth-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "https://your-app.example.com/social/callback",
    "scopes": "instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_insights,instagram_business_manage_messages"
  }'

1. Send the account owner to the returned auth_url
2. They must approve every requested permission on the Instagram consent screen, including access to messages
3. Outstand then subscribes the account to message webhooks automatically

Reconnect Existing Accounts

Accounts connected without instagram_business_manage_messages, including every account connected from the Outstand dashboard, must be reconnected with the request above before any messages are received or sent. Reconnecting updates the existing social account in place, keeping its ID, scheduled posts and history. Reconnecting a messaging-enabled account from the dashboard, or with a scopes list that omits the permission, removes messaging access again. See Existing accounts for how an account without the permission behaves.

Instagram Account Requirements

• Professional account - Meta's messaging API only works with Instagram professional accounts, meaning Business or Creator. Personal accounts have no messaging API access at all. To convert one, go to Instagram → Settings → Account → Switch to Professional Account.
• Allow access to messages - the account must allow connected tools to access its messages. In the Instagram app, go to Settings → Messages and story replies → Message controls → Connected tools and turn on Allow access to messages. Without it, Meta does not deliver the account's messages to Outstand.

24-Hour Messaging Window

Instagram only allows free-form replies within 24 hours of the contact's last inbound message. A send outside that window is rejected with a 422.

The HUMAN_AGENT tag is available on request. Meta offers a Human Agent feature that extends the reply window to 7 days for a human replying to a support issue. Outstand enables it per organization - contact support to request access. Until it is enabled, sending instagram.tag returns a 403.

The Meta app that owns the connection must also be reviewed and approved by Meta for Human Agent. If it is not, Instagram rejects the send with:

To use 'Human Agent', your use of this endpoint must be reviewed and approved by Facebook.

Notes

• No message history - only messages sent or received after the account is connected with the messaging permission are available. Earlier conversations are not imported.
• Conversations start with the contact - Instagram does not allow a business to message someone out of the blue. A conversation starts when the contact messages the account, or when you privately reply to one of their comments: one reply per comment, within 7 days of it. After a private reply, nothing more can be sent until the contact answers.

Next Steps

Once your Instagram credentials are configured and approved, you can:

1. Connect your Instagram Business or Creator accounts via the Outstand dashboard
2. Create Instagram posts using the Posts API
3. Upload photos and videos for your posts via the Media API
4. Schedule Instagram content for optimal timing
5. Monitor engagement through Instagram analytics
6. Get notified of new comments with the comment.received webhook
7. Read and reply to direct messages (Managed Keys only, requires explicitly requesting the messaging scope)