Integrations / Instagram

Instagram

Instagram professional accounts through the Instagram Graph API with Facebook Login: read media, insights and comments, reply, and publish photos.

10 actions OAuth 2 7 read3 write Calls graph.facebook.com

Connect

TypeScript

const conn = await setu.connections.initiate({ userId: "user_1", toolkit: "instagram" });
console.log(conn.connectUrl); // show this to your user
await conn.waitUntilActive();

Permissions requested

Scope	Why it is requested
`public_profile`	Read your name and ID so Setu can label the connection
`pages_show_list`	Find the Facebook Page linked to your Instagram professional account
`pages_read_engagement`	Required by Instagram to read content of accounts linked to your Page
`instagram_basic`	Read your Instagram profile and media
`instagram_content_publish`	Publish photos to your Instagram professional account
`instagram_manage_comments`	Read and reply to comments on your Instagram media
`instagram_manage_insights`	Read insights for your Instagram media

Actions

Create image post containerwriteinstagram.create_media_containerStep 1 of publishing a photo: create an unpublished media container from a public image URL and caption. Nothing is visible until publish_media is called with the returned id. Images only (no video).

Needs scopes: instagram_content_publish, instagram_basic, pages_read_engagement

Input	Type		Description
`ig_user_id`	string	Required	Instagram professional account id
`image_url`	string	Required	Public https URL of the image (JPEG)
`caption`	string	Optional	Caption, up to 2,200 characters
`alt_text`	string	Optional	Optional image description

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.create_media_container",
  input: {
    "ig_user_id": "<ig_user_id>",
    "image_url": "<image_url>"
  },
});

Get Instagram accountreadinstagram.get_accountRead an Instagram professional account's profile: username, name, biography, website, follower, following and media counts.

Needs scopes: instagram_basic, pages_read_engagement

Input	Type		Description
`ig_user_id`	string	Required	Instagram professional account id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.get_account",
  input: {
    "ig_user_id": "<ig_user_id>"
  },
});

Get Instagram account of a Pagereadinstagram.get_instagram_account_for_pageReturn the Instagram professional account id linked to a Facebook Page. Use that id as ig_user_id in the other actions.

Needs scopes: instagram_basic, pages_show_list

Input	Type		Description
`page_id`	string	Required	Facebook Page id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.get_instagram_account_for_page",
  input: {
    "page_id": "<page_id>"
  },
});

Get mediareadinstagram.get_mediaRead one Instagram media item: caption, type, media URL, permalink, timestamp, like and comment counts.

Needs scopes: instagram_basic, pages_read_engagement

Input	Type		Description
`media_id`	string	Required	Instagram media id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.get_media",
  input: {
    "media_id": "<media_id>"
  },
});

Get media insightsreadinstagram.get_media_insightsRead insight metrics for one Instagram media item, such as reach, likes, comments, shares, saved, views, total_interactions. Valid metrics depend on the media type (feed, reel, story).

Needs scopes: instagram_manage_insights, instagram_basic, pages_read_engagement

Input	Type		Description
`media_id`	string	Required	Instagram media id
`metric`	string	Required	Comma-separated metrics, e.g. reach,likes,comments,saved,shares,total_interactions
`period`	string	Optional	Optional: day, week, days_28, month, lifetime or total_over_range
`breakdown`	string	Optional	Optional breakdown, e.g. action_type (profile_activity only)

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.get_media_insights",
  input: {
    "media_id": "<media_id>",
    "metric": "<metric>"
  },
});

List comments on mediareadinstagram.list_commentsRead the top-level comments (id, text, time) on an Instagram media item. At most 50 per call; replies are not included.

Needs scopes: instagram_manage_comments, instagram_basic, pages_read_engagement

Input	Type		Description
`media_id`	string	Required	Instagram media id

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.list_comments",
  input: {
    "media_id": "<media_id>"
  },
});

List mediareadinstagram.list_mediaList the most recent media (photos, videos, reels, carousels) of an Instagram professional account with caption, type, link and counts. Stories are not included.

Needs scopes: instagram_basic, pages_read_engagement

Input	Type		Description
`ig_user_id`	string	Required	Instagram professional account id
`limit`	integer	Optional	Maximum items to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.list_media",
  input: {
    "ig_user_id": "<ig_user_id>"
  },
});

List my Pagesreadinstagram.list_pagesList the Facebook Pages the person manages (id and name) so you can find the one linked to an Instagram professional account.

Needs scope: pages_show_list

Input	Type		Description
`limit`	integer	Optional	Maximum Pages to return

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.list_pages",
  input: {},
});

Publish media containerwriteinstagram.publish_mediaStep 2 of publishing: make a media container public on Instagram. This posts to the live account. Limited to about 50 API posts per 24 hours.

Needs scopes: instagram_content_publish, instagram_basic

Input	Type		Description
`ig_user_id`	string	Required	Instagram professional account id
`creation_id`	string	Required	Container id from create_media_container

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.publish_media",
  input: {
    "ig_user_id": "<ig_user_id>",
    "creation_id": "<creation_id>"
  },
});

Reply to a commentwriteinstagram.reply_to_commentPost a public reply to a top-level Instagram comment. Replies to hidden comments or live-video comments are not allowed.

Needs scopes: instagram_manage_comments, instagram_basic, pages_show_list, pages_read_engagement

Input	Type		Description
`comment_id`	string	Required	Comment id to reply to
`message`	string	Required	Reply text

TypeScript

await setu.execute({
  userId: "user_1",
  action: "instagram.reply_to_comment",
  input: {
    "comment_id": "<comment_id>",
    "message": "<message>"
  },
});