Aller au contenu
Dashboard

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.

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.

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
  • 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).
  • Les messages privés ne demandent aucun scope Instagram : conversations:read pour les lire, messages:send pour y répondre.

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

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

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

Terminal window
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.

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

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":"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 ; pour le rendre, POST /leads/{id}/resume.

Plus de détails dans Messages.

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.

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": "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.
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": "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.
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, 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.

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.