Guides by resource
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.
Endpoints
Section titled “Endpoints”| 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 |
Before you start
Section titled “Before you start”- 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(andinstagram:writeto 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:readto read them,messages:sendto answer.
1. Find your accounts
Section titled “1. Find your accounts”Every Instagram route takes an account_id. With a single account you can leave it out; with several, it is required.
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. |
2. Read the private messages
Section titled “2. Read the private messages”The inbox covers WhatsApp, Instagram and Messenger. Ask for the Instagram conversations that need you:
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.
3. Answer
Section titled “3. Answer”The same call as WhatsApp, on the lead’s lead_id:
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_closedwithwindow_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.
4. Manage automations
Section titled “4. Manage automations”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.
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: truefires 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 inconflict: 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.
5. Schedule a post
Section titled “5. Schedule a post”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_atit 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,permalinkonce out, and its copy on the Facebook Page withfacebook: 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/postspages withcursor, like the other lists.
6. Read the numbers
Section titled “6. Read the numbers”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.
Errors you will meet
Section titled “Errors you will meet”| 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. |