# Instagram

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

Source: https://docs.whatsetter.com/developers/guides/instagram/

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](/developers/mcp/) that does the same thing from an AI assistant.

## Endpoints

| Method | Path | Scope |
|---|---|---|
| GET | [`/instagram/accounts`](/api-reference/operations/listinstagramaccounts/) | `instagram:read` |
| GET | [`/conversations`](/api-reference/operations/listconversations/) | `conversations:read` |
| POST | [`/messages`](/api-reference/operations/sendmessage/) | `messages:send` |
| GET | [`/instagram/automations`](/api-reference/operations/listinstagramautomations/) | `instagram:read` |
| POST | [`/instagram/automations`](/api-reference/operations/createinstagramautomation/) | `instagram:write` |
| PATCH | [`/instagram/automations/{id}`](/api-reference/operations/updateinstagramautomation/) | `instagram:write` |
| DELETE | [`/instagram/automations/{id}`](/api-reference/operations/deleteinstagramautomation/) | `instagram:write` |
| POST | [`/instagram/posts`](/api-reference/operations/createinstagrampost/) | `instagram:write` |
| GET | [`/instagram/posts`](/api-reference/operations/listinstagramposts/) | `instagram:read` |
| GET | [`/instagram/posts/{id}`](/api-reference/operations/getinstagrampost/) | `instagram:read` |
| GET | [`/instagram/stats`](/api-reference/operations/getinstagramstats/) | `instagram:read` |
| GET | [`/instagram/insights/posts`](/api-reference/operations/listinstagrampostinsights/) | `instagram:read` |

## 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` (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](/developers/authentication/)).
- Private messages need no Instagram scope: `conversations:read` to read them, `messages:send` to answer.

## 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.

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

MCP: `list_instagram_accounts`.

```json
{
  "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

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

```bash
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](/developers/guides/conversations/).

## 3. Answer

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

```bash
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`](/developers/guides/leads/); to give it back, `POST /leads/{id}/resume`.

More in [Messages](/developers/guides/messages/#instagram-and-messenger).

## 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.

```bash
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.

## 5. Schedule a post

```bash
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.

## 6. Read the numbers

```bash
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

| 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`. |

## Related

- [Conversations](/developers/guides/conversations/)
- [Messages](/developers/guides/messages/)
- [Leads: hand a conversation to a human](/developers/guides/leads/)
- [MCP server](/developers/mcp/)
- [Authentication and permissions](/developers/authentication/)
