Skip to content
Dashboard

Instagram

Run your Instagram accounts through the API: read and answer private messages, manage comment automations, schedule posts and read their numbers.

The API covers an Instagram account end to end, like the dashboard: who writes to it, what the agent and the automations do, and what you publish. Private messages work like WhatsApp’s: you read them under /conversations and answer them with POST /messages. Messenger, through the Facebook Page linked to an account, works the same way with channel: facebook.

Each step below gives a cURL call and the name of the MCP tool that does the same thing from an AI assistant.

Method Path Scope
GET /instagram/accounts instagram:read
GET /conversations conversations:read
POST /messages messages:send
GET /instagram/automations instagram:read
POST /instagram/automations instagram:write
PATCH /instagram/automations/{id} instagram:write
DELETE /instagram/automations/{id} instagram:write
POST /instagram/posts instagram:write
GET /instagram/posts instagram:read
GET /instagram/posts/{id} instagram:read
GET /instagram/stats instagram:read
GET /instagram/insights/posts instagram:read
  • Instagram must be enabled on your workspace and an account connected from the dashboard. Otherwise the Instagram routes answer 403 instagram_not_enabled.
  • The key needs instagram:read (and instagram:write to change anything). A Full access key made before these endpoints were released does not carry them: create a new one (Authentication).
  • Private messages need no Instagram scope: conversations:read to read them, messages:send to answer.

Every Instagram route takes an account_id. With a single account you can leave it out; with several, it is required.

Terminal window
curl "https://app.whatsetter.com/api/v1/instagram/accounts" \
-H "Authorization: Bearer ws_live_…"

MCP: list_instagram_accounts.

{
"data": [
{
"id": "68f1c2d3e4f5a6b7c8d9e0f1",
"username": "acme.studio",
"name": "Acme Studio",
"status": "connected",
"grants": { "messages": true, "publish": true, "insights": true },
"facebook_page": { "name": "Acme Studio", "can_publish": true },
"agent": { "campaign_id": "instagram-acme-studio-x7k2", "enabled": true, "all_dms": true },
"triage": { "enabled": true, "answer_collab": false, "answer_support": false, "answer_personal": false },
"human_pause_hours": 24
}
]
}
Field Meaning
status connected, or needs_reconnect when the connection expired: reconnect it from the dashboard.
grants What the account allows: private messages, publishing, insights. An account connected before publishing was offered must be reconnected to publish.
agent The agent that answers (campaign_id), whether it is on, and whether it answers every private message (all_dms) or only the people an automation brought.
triage When the agent answers every private message, the messages it leaves aside: a brand (answer_collab: false), a customer with a problem (answer_support: false), thanks and chat (answer_personal: false).
human_pause_hours How long a person’s reply pauses the agent on a lead. 0 = never.

The inbox covers WhatsApp, Instagram and Messenger. Ask for the Instagram conversations that need you:

Terminal window
curl "https://app.whatsetter.com/api/v1/conversations?channel=instagram&needs_reply=true" \
-H "Authorization: Bearer ws_live_…"

MCP: list_conversations, then get_conversation_messages for one thread.

Each conversation says its channel, the person’s ig_username, the account_id, whether the agent answers it now (agent_active, and agent_paused_until after a person’s reply), whether it needs a reply (needs_reply: the dashboard’s To do view) and, when the agent answers every private message, what the triage read the last message as (triage_verdict). triage=collab or triage=support lists the messages the agent left for you. Details in Conversations.

The same call as WhatsApp, on the lead’s lead_id:

Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/messages" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5b7e1c2a-9d3f-4a8b-b6c1-0e2f3a4b5c6d" \
-d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"Thanks for your message! Here is the price list."}'

MCP: send_message.

  • Only within 24 hours of the person’s last message (Meta’s rule). Past that: 409 messaging_window_closed with window_closes_at, nothing is sent.
  • 1,000 characters on Instagram, 2,000 on Messenger.
  • Like a reply typed in the inbox, it pauses the agent on this lead for human_pause_hours. To keep the thread for good, POST /leads/{id}/handoff; to give it back, POST /leads/{id}/resume.

More in Messages.

An automation answers a comment (on every post, on the posts you publish from now on, or on some posts), a story reply, a story mention or a private message with one of its words: a public reply under the comment, one private message (with a link card, after an optional “follow me first”), then the agent continues.

Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/instagram/automations" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"account_id": "68f1c2d3e4f5a6b7c8d9e0f1",
"name": "Buyer'\''s guide",
"trigger": { "on": "comment", "posts": "next", "keywords": ["GUIDE"] },
"public_replies": ["Sent you a DM 👀"],
"dm_message": "Here is the guide 👇",
"link": { "url": "https://example.com/guide", "label": "Get the guide" }
}'

MCP: create_instagram_automation, list_instagram_automations, update_instagram_automation, delete_instagram_automation.

  • It is created off. Check it, then switch it on with PATCH /instagram/automations/{id} and {"active": true}. An active automation writes to real people.
  • trigger.posts: "all", "next" (every post published after the automation was created) or a list of Instagram media ids. trigger.any_word: true fires on every comment.
  • Switching on next to a live automation that watches the same posts for the same words answers 409 automation_conflict, with the automation in the way in conflict: one comment fires one automation only.
  • Each automation reads back with its numbers: stats.fired, stats.dms_sent, stats.link_clicks, stats.last_fired_at.
  • What the dashboard’s editor sets beyond these fields (rotated wordings, the e-mail ask, scripted steps, the follow-up) is kept when you change an automation here.
Terminal window
curl -X POST "https://app.whatsetter.com/api/v1/instagram/posts" \
-H "Authorization: Bearer ws_live_…" \
-H "Content-Type: application/json" \
-d '{
"kind": "image",
"caption": "New listing in Lyon. Comment GUIDE for the buyer'\''s guide.",
"media": [{ "type": "image", "url": "https://cdn.example.com/listing.jpg" }],
"publish_at": "2027-01-12T17:00:00Z",
"automation": { "keyword": "GUIDE", "message": "Here is the guide 👇" }
}'

MCP: schedule_instagram_post, then get_scheduled_instagram_post to follow it. get_instagram_best_times gives the next good moments.

  • It publishes publicly. Without publish_at it goes out within a minute. Media are public https URLs Instagram downloads when the post goes out.
  • Follow it with GET /instagram/posts/{id}: status, permalink once out, and its copy on the Facebook Page with facebook: true.
  • mode: "remind" publishes nothing: a member of your team is reminded to publish it from the Instagram app (remind_member_id, else the member who created the key), then the post is found and linked.
  • 50 posts waiting per account at most through the API: past that, 409 too_many_planned.
  • GET /instagram/posts pages with cursor, like the other lists.
Terminal window
curl "https://app.whatsetter.com/api/v1/instagram/stats?days=30&tz=Europe/Paris" \
-H "Authorization: Bearer ws_live_…"

MCP: get_instagram_stats, and list_instagram_posts for each post’s views and funnel.

/instagram/stats says what the automations did over 7, 30 or 90 days, against the period before: comments, private messages sent, people who replied, links sent and opened, e-mails captured, qualified leads. In totals, by_day, by_automation and by_post, each split instagram and facebook (the automations’ copy on the Page). /instagram/insights/posts gives each post’s views against the account’s average, down to the meetings it brought.

HTTP code When
403 insufficient_scope The key lacks instagram:read or instagram:write. An old Full access key: create a new one.
403 instagram_not_enabled Instagram is not enabled on the workspace.
404 not_found Unknown account, post or automation, or one of another workspace.
409 messaging_window_closed More than 24 hours since the person’s last message. See window_closes_at.
409 recipient_unreachable The person does not receive messages from the account right now (blocked it, or turned messages off).
409 automation_conflict A live automation already watches the same posts for the same words. See conflict.
409 instagram_reconnect_required The account must be reconnected from the dashboard.
409 too_many_planned 50 posts already waiting on the account.
409 post_already_started, post_already_published The post is on its way or out: it can no longer change.
422 validation_error A missing or wrong field; the message says which. account_id is required with several accounts.
422 no_reminder_recipient mode: "remind" and nobody of the workspace to remind: pass remind_member_id.