# Instagram

> Pilote tes comptes Instagram par l'API : lire et répondre aux messages privés, gérer les automatisations, programmer des publications et lire leurs chiffres.

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

L'API couvre un compte Instagram de bout en bout, comme le dashboard : qui lui écrit, ce que font l'agent et les automatisations, et ce que tu publies. Les messages privés fonctionnent comme ceux de WhatsApp : tu les lis sous `/conversations` et tu y réponds avec `POST /messages`. Messenger, via la Page Facebook reliée à un compte, fonctionne de la même façon avec `channel: facebook`.

Chaque étape ci-dessous donne un appel cURL et le nom de l'[outil MCP](/fr/developers/mcp/) qui fait la même chose depuis un assistant IA.

## Endpoints

| Méthode | Chemin | 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` |

## Avant de commencer

- Instagram doit être activé sur ton espace et un compte connecté depuis le dashboard. Sinon, les routes Instagram répondent `403 instagram_not_enabled`.
- La clé a besoin de `instagram:read` (et de `instagram:write` pour changer quoi que ce soit). Une clé **Accès complet** créée avant la sortie de ces endpoints ne les porte pas : crées-en une nouvelle ([Authentification](/fr/developers/authentication/)).
- Les messages privés ne demandent aucun scope Instagram : `conversations:read` pour les lire, `messages:send` pour y répondre.

## 1. Trouver tes comptes

Chaque route Instagram prend un `account_id`. Avec un seul compte, tu peux l'omettre ; avec plusieurs, il est obligatoire.

```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
    }
  ]
}
```

| Champ | Sens |
|---|---|
| `status` | `connected`, ou `needs_reconnect` quand la connexion a expiré : reconnecte le compte depuis le dashboard. |
| `grants` | Ce que le compte permet : messages privés, publication, statistiques. Un compte connecté avant que la publication soit proposée doit être reconnecté pour publier. |
| `agent` | L'agent qui répond (`campaign_id`), s'il est allumé, et s'il répond à tous les messages privés (`all_dms`) ou seulement aux personnes amenées par une automatisation. |
| `triage` | Quand l'agent répond à tous les messages privés, ceux qu'il laisse de côté : une marque (`answer_collab: false`), un client avec un problème (`answer_support: false`), les remerciements et la discussion (`answer_personal: false`). |
| `human_pause_hours` | Combien de temps la réponse d'une personne met l'agent en pause sur un lead. `0` = jamais. |

## 2. Lire les messages privés

La boîte de réception couvre WhatsApp, Instagram et Messenger. Demande les conversations Instagram qui t'attendent :

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

MCP : `list_conversations`, puis `get_conversation_messages` pour un fil.

Chaque conversation dit son `channel`, le pseudo de la personne (`ig_username`), l'`account_id`, si l'agent y répond en ce moment (`agent_active`, et `agent_paused_until` après la réponse d'une personne), si elle attend une réponse (`needs_reply` : la vue **À traiter** du dashboard) et, quand l'agent répond à tous les messages privés, ce que **Le tri** a lu dans le dernier message (`triage_verdict`). `triage=collab` ou `triage=support` liste les messages que l'agent t'a laissés. Le détail dans [Conversations](/fr/developers/guides/conversations/).

## 3. Répondre

Le même appel que pour WhatsApp, sur le `lead_id` du lead :

```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":"Merci pour ton message ! Voici les tarifs."}'
```

MCP : `send_message`.

- Seulement dans les **24 heures** qui suivent le dernier message de la personne (la règle de Meta). Au-delà : `409 messaging_window_closed` avec `window_closes_at`, rien n'est envoyé.
- 1 000 caractères sur Instagram, 2 000 sur Messenger.
- Comme une réponse tapée dans la boîte de réception, elle met l'agent en pause sur ce lead pendant `human_pause_hours`. Pour garder le fil pour de bon, [`POST /leads/{id}/handoff`](/fr/developers/guides/leads/) ; pour le rendre, `POST /leads/{id}/resume`.

Plus de détails dans [Messages](/fr/developers/guides/messages/#instagram-et-messenger).

## 4. Gérer les automatisations

Une automatisation répond à un commentaire (sur toutes les publications, sur celles que tu publies à partir de maintenant, ou sur certaines), à une réponse à une story, à une mention en story ou à un message privé qui contient un de ses mots : une réponse publique sous le commentaire, un message privé (avec une carte de lien, après un « abonne-toi d'abord » au choix), puis l'agent prend le relais.

```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": "Guide de l'\''acheteur",
    "trigger": { "on": "comment", "posts": "next", "keywords": ["GUIDE"] },
    "public_replies": ["Je t'\''envoie ça en privé 👀"],
    "dm_message": "Voici le guide 👇",
    "link": { "url": "https://example.com/guide", "label": "Le guide" }
  }'
```

MCP : `create_instagram_automation`, `list_instagram_automations`, `update_instagram_automation`, `delete_instagram_automation`.

- Elle est créée **éteinte**. Vérifie-la, puis allume-la avec `PATCH /instagram/automations/{id}` et `{"active": true}`. Une automatisation allumée écrit à de vraies personnes.
- `trigger.posts` : `"all"`, `"next"` (chaque publication publiée après la création de l'automatisation) ou une liste d'identifiants de médias Instagram. `trigger.any_word: true` se déclenche sur chaque commentaire.
- L'allumer à côté d'une automatisation en marche qui surveille les mêmes publications pour les mêmes mots répond `409 automation_conflict`, avec celle qui gêne dans `conflict` : un commentaire ne déclenche qu'une seule automatisation.
- Chaque automatisation se relit avec ses chiffres : `stats.fired`, `stats.dms_sent`, `stats.link_clicks`, `stats.last_fired_at`.
- Ce que l'éditeur du dashboard règle en plus de ces champs (formulations en rotation, demande d'e-mail, étapes écrites, relance) est gardé quand tu modifies une automatisation ici.

## 5. Programmer une publication

```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": "Nouveau bien à Lyon. Commente GUIDE pour le guide de l'\''acheteur.",
    "media": [{ "type": "image", "url": "https://cdn.example.com/listing.jpg" }],
    "publish_at": "2027-01-12T17:00:00Z",
    "automation": { "keyword": "GUIDE", "message": "Voici le guide 👇" }
  }'
```

MCP : `schedule_instagram_post`, puis `get_scheduled_instagram_post` pour la suivre. `get_instagram_best_times` donne les prochains bons moments.

- Elle publie **publiquement**. Sans `publish_at`, elle part dans la minute. Les médias sont des URL https publiques qu'Instagram télécharge au moment de publier.
- Suis-la avec `GET /instagram/posts/{id}` : `status`, `permalink` une fois en ligne, et sa copie sur la Page Facebook avec `facebook: true`.
- `mode: "remind"` ne publie rien : un membre de ton équipe reçoit un rappel pour la publier depuis l'app Instagram (`remind_member_id`, sinon le membre qui a créé la clé), puis la publication est retrouvée et reliée.
- 50 publications en attente par compte au plus par l'API : au-delà, `409 too_many_planned`.
- `GET /instagram/posts` se parcourt avec `cursor`, comme les autres listes.

## 6. Lire les chiffres

```bash
curl "https://app.whatsetter.com/api/v1/instagram/stats?days=30&tz=Europe/Paris" \
  -H "Authorization: Bearer ws_live_…"
```

MCP : `get_instagram_stats`, et `list_instagram_posts` pour les vues et l'entonnoir de chaque publication.

`/instagram/stats` dit ce qu'ont fait les automatisations sur 7, 30 ou 90 jours, face à la période d'avant : commentaires, messages privés envoyés, personnes qui ont répondu, liens envoyés et ouverts, e-mails récupérés, leads qualifiés. Dans `totals`, `by_day`, `by_automation` et `by_post`, chaque fois séparés entre `instagram` et `facebook` (la copie des automatisations sur la Page). `/instagram/insights/posts` donne les vues de chaque publication face à la moyenne du compte, jusqu'aux rendez-vous qu'elle a amenés.

## Les erreurs que tu rencontreras

| HTTP | `code` | Quand |
|---|---|---|
| 403 | `insufficient_scope` | La clé n'a pas `instagram:read` ou `instagram:write`. Une ancienne clé **Accès complet** : crées-en une nouvelle. |
| 403 | `instagram_not_enabled` | Instagram n'est pas activé sur l'espace. |
| 404 | `not_found` | Compte, publication ou automatisation inconnus, ou d'un autre espace. |
| 409 | `messaging_window_closed` | Plus de 24 heures depuis le dernier message de la personne. Voir `window_closes_at`. |
| 409 | `recipient_unreachable` | La personne ne reçoit pas de messages du compte en ce moment (elle l'a bloqué, ou a coupé ses messages). |
| 409 | `automation_conflict` | Une automatisation en marche surveille déjà les mêmes publications pour les mêmes mots. Voir `conflict`. |
| 409 | `instagram_reconnect_required` | Le compte doit être reconnecté depuis le dashboard. |
| 409 | `too_many_planned` | 50 publications attendent déjà sur le compte. |
| 409 | `post_already_started`, `post_already_published` | La publication est partie ou en ligne : elle ne peut plus changer. |
| 422 | `validation_error` | Un champ manquant ou faux ; le message dit lequel. `account_id` est obligatoire avec plusieurs comptes. |
| 422 | `no_reminder_recipient` | `mode: "remind"` et personne de l'espace à prévenir : passe `remind_member_id`. |

## Voir aussi

- [Conversations](/fr/developers/guides/conversations/)
- [Messages](/fr/developers/guides/messages/)
- [Leads : passer une conversation à un humain](/fr/developers/guides/leads/)
- [Serveur MCP](/fr/developers/mcp/)
- [Authentification et permissions](/fr/developers/authentication/)
