Guides par ressource
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.
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 qui fait la même chose depuis un assistant IA.
Endpoints
Section intitulée « Endpoints »| Méthode | Chemin | 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 |
Avant de commencer
Section intitulée « 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 deinstagram:writepour 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). - Les messages privés ne demandent aucun scope Instagram :
conversations:readpour les lire,messages:sendpour y répondre.
1. Trouver tes comptes
Section intitulée « 1. Trouver tes comptes »Chaque route Instagram prend un account_id. Avec un seul compte, tu peux l’omettre ; avec plusieurs, il est obligatoire.
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 } ]}| 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
Section intitulée « 2. Lire les messages privés »La boîte de réception couvre WhatsApp, Instagram et Messenger. Demande les conversations Instagram qui t’attendent :
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.
3. Répondre
Section intitulée « 3. Répondre »Le même appel que pour WhatsApp, sur le lead_id du lead :
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_closedavecwindow_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; pour le rendre,POST /leads/{id}/resume.
Plus de détails dans Messages.
4. Gérer les automatisations
Section intitulée « 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.
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: truese 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 dansconflict: 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
Section intitulée « 5. Programmer une publication »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,permalinkune fois en ligne, et sa copie sur la Page Facebook avecfacebook: 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/postsse parcourt aveccursor, comme les autres listes.
6. Lire les chiffres
Section intitulée « 6. Lire les chiffres »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
Section intitulée « 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. |