Instagram

Overview

The instagram platform publishes to Instagram professional (Business or Creator) accounts. Personal accounts cannot publish through the API. You can post:

• A single image (JPEG) to the feed
• A single video, published as a Reel
• A carousel of 2–10 images and/or videos
• A Reel (with optional cover, thumbnail frame, trial-reel mode, and "share to feed" toggle)
• A Story (exactly one image or video)
• Up to 3 collaborators on feed posts, carousels and Reels

Instagram does not support text-only posts: every post needs at least one image or video.

Connect the account

In Integrations, choose Instagram. There are two ways to connect, and both end up as the same Instagram account in Relaycast (reconnecting through either one updates the existing account):

Both options use the redirect URI https://social-publish-kappa.vercel.app/api/integrations/instagram/callback (override with INSTAGRAM_REDIRECT_URI).

Instagram Login setup (self-hosted)

1. In your Meta app, add the Instagram product and open API setup with Instagram login.
2. Use the Instagram app ID and secret shown there (not the Facebook app ID) for INSTAGRAM_APP_ID and INSTAGRAM_APP_SECRET.
3. Under Set up Instagram business login → Business login settings, add the redirect URI above.

Scopes requested: instagram_business_basic, instagram_business_content_publish, instagram_business_manage_messages, instagram_business_manage_comments, instagram_business_manage_insights. Tokens are long-lived (60 days) and refreshed automatically before they expire.

Facebook Login setup (self-hosted)

1. Use the Facebook app (FACEBOOK_APP_ID, FACEBOOK_APP_SECRET, the same one as Facebook Pages) with the Instagram use case Manage messages and content on Instagram.
2. Add https://social-publish-kappa.vercel.app/api/integrations/instagram/callback to Facebook Login → Settings → Valid OAuth Redirect URIs.

Always requested: instagram_basic, instagram_content_publish, pages_show_list, pages_read_engagement. Optional features request more permissions only when their flag is set, because Meta rejects the whole login if a requested permission isn't added to the app:

Post types & media rules

Choose the post type with options.publishAs:

Media is fetched by Instagram from its URL, so it must be publicly reachable (media library files are served as signed URLs automatically). Size, duration and aspect-ratio checks are done by Instagram while it processes the media.

Options

Examples

Reel with collaborators and a cover

curl -X POST https://social-publish-api.onrender.com/v1/posts \
  -H "x-access-key: $RELAYCAST_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "content": "Behind the scenes of our spring shoot #bts",
    "media": [{ "url": "https://cdn.example.com/bts.mp4", "type": "video" }],
    "targets": [{
      "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29",
      "options": {
        "publishAs": "reel",
        "shareToFeed": true,
        "collaborators": ["studio.north"],
        "coverUrl": "https://cdn.example.com/bts-cover.jpg"
      }
    }],
    "scheduledFor": "2026-11-03T17:30:00Z"
  }'

const res = await fetch("https://social-publish-api.onrender.com/v1/posts", {
  method: "POST",
  headers: {
    "x-access-key": process.env.RELAYCAST_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    content: "Behind the scenes of our spring shoot #bts",
    media: [{ url: "https://cdn.example.com/bts.mp4", type: "video" }],
    targets: [
      {
        accountId: "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29",
        options: {
          publishAs: "reel",
          shareToFeed: true,
          collaborators: ["studio.north"],
          coverUrl: "https://cdn.example.com/bts-cover.jpg",
        },
      },
    ],
    scheduledFor: "2026-11-03T17:30:00Z",
  }),
});
const { data } = await res.json();

import os, requests

res = requests.post(
    "https://social-publish-api.onrender.com/v1/posts",
    headers={"x-access-key": os.environ["RELAYCAST_API_KEY"]},
    json={
        "content": "Behind the scenes of our spring shoot #bts",
        "media": [{"url": "https://cdn.example.com/bts.mp4", "type": "video"}],
        "targets": [{
            "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29",
            "options": {
                "publishAs": "reel",
                "shareToFeed": True,
                "collaborators": ["studio.north"],
                "coverUrl": "https://cdn.example.com/bts-cover.jpg",
            },
        }],
        "scheduledFor": "2026-11-03T17:30:00Z",
    },
)
data = res.json()["data"]

Carousel

{
  "content": "Three looks from the new collection",
  "media": [
    { "url": "https://cdn.example.com/look-1.jpg", "type": "image" },
    { "url": "https://cdn.example.com/look-2.jpg", "type": "image" },
    { "url": "https://cdn.example.com/look-3.mp4", "type": "video" }
  ],
  "targets": [{ "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29" }],
  "publishNow": true
}

Story

{
  "content": "Story",
  "media": [{ "url": "https://cdn.example.com/story.jpg", "type": "image" }],
  "targets": [{ "accountId": "1d7e3f52-8c4a-4b9e-a0f1-7e6d5c4b3a29", "options": { "publishAs": "story" } }],
  "publishNow": true
}

The request still needs content (it is required for every post), but Stories have no caption.

Analytics & comments

• Analytics: likes and comment counts for every post, plus Instagram insights (views, reach, shares, saves and more, depending on the media type). With Facebook Login, insights need INSTAGRAM_FB_ENABLE_INSIGHTS=true.
• Inbox: Instagram DMs can be read and answered from the dashboard inbox.
• Comments: comment-to-DM automations and public comment replies. See Inbox & Comment Automation.

Accounts connected before a permission was added must reconnect to use the feature.

Limitations & common errors