Vue d'ensemble de l'API Automations

Bêta. L’API Automations est en version bêta et nous recueillons activement les retours. Les points de terminaison, les charges utiles et les limites peuvent évoluer au fil de nos itérations. Merci d’envoyer vos retours et rapports de bugs au support afin que nous puissions prioriser les bonnes améliorations.

Les points de terminaison Automations vous permettent de définir des règles qui réagissent automatiquement à l’engagement Instagram entrant. Chaque automatisation associe un ou plusieurs déclencheurs (l’événement qui active la règle) à une ou plusieurs actions (ce qui se produit lorsqu’elle est activée). Une seule règle peut écouter plusieurs déclencheurs et lancer plusieurs actions — déclencher un webhook vers votre pipeline d’analytics ET envoyer un DM à partir du même engagement. Le moteur ne réagit qu’à un engagement qu’un utilisateur vous adresse (un commentaire, une réponse à une story, un DM ou une réaction) — il n’envoie jamais de DM déclenchés par un suivi, de premiers DM à des inconnus, ni d’envois sortants en masse — et il hérite des limites de débit par compte d’Ayrshare, de la déduplication par destinataire et de l’ingestion idempotente des webhooks.

sent signifie que Meta a accepté le message, pas que le destinataire l’a reçu. La livraison est en fin de compte dictée par le paramètre Instagram Message requests du destinataire : s’il n’autorise pas les demandes de message de tout le monde, Meta renvoie une réponse de succès et supprime silencieusement le message, ce qui est invisible à chaque couche d’API. Même un DM déclenché par un commentaire et effectivement livré arrive sous forme de demande de message que le destinataire doit accepter (sauf si une conversation existe déjà entre les deux comptes). Voir Automation DM Sent but Not Delivered pour l’explication complète.

Fonctionnement

Créer une automatisation

POST /automations avec les déclencheurs et les actions souhaités. L’automatisation est activée immédiatement.

Un utilisateur final s'engage

Quelqu’un commente votre publication, répond à votre story, envoie un DM ou réagit à un DM. Meta transmet le webhook à Ayrshare.

Ayrshare fait la correspondance et lance

Le moteur recherche chaque règle correspondant à l’événement, vérifie la déduplication par action et votre plafond quotidien de DM, puis exécute chaque action. Une gigue de 20 à 60 secondes est appliquée aux envois de DM pour rester dans les heuristiques anti-spam d’Instagram.

Vérifier ce qui a été déclenché

GET /automations/:id/activity retourne le journal d’audit — chaque tentative d’envoi, les résultats par action et toute erreur.

Déclencheurs

Vous pouvez attacher jusqu’à 50 déclencheurs à une automatisation. Chaque déclencheur est une union discriminée sur le champ type ; les champs spécifiques au type se trouvent au même niveau. Tous les déclencheurs sont uniquement Instagram en v1.

Type	Se déclenche lorsque	Configuration
`comment_keyword`	Un commentaire correspondant à un mot-clé arrive sur une publication spécifique	`postId` (requis) ; `keywords` (requis, ≥1 entrée)
`story_reply`	Un utilisateur répond à une story via DM	`storyId` (optionnel)
`dm_reaction`	Un utilisateur réagit à l’un de vos DM avec un emoji	`emoji` (optionnel — omettez pour déclencher sur n’importe quel emoji)
`dm_keyword`	Un utilisateur envoie un DM dont le texte correspond à un mot-clé	`keywords` (requis, ≥1 entrée)

La correspondance de mot-clé est insensible à la casse et par mot entier. Un événement satisfait un déclencheur filtré par mot-clé s’il contient l’un des mots-clés configurés. Omettez storyId sur un déclencheur de story pour qu’il se déclenche sur chaque story du compte connecté.

Actions

Vous pouvez attacher jusqu’à 50 actions à une automatisation. Elles s’exécutent séquentiellement ; chaque résultat est enregistré sur la ligne d’activité.

Type	Effet	Configuration
`send_dm`	Envoie un DM Instagram à l’utilisateur qui a déclenché la règle, en utilisant un message basé sur un modèle.	`message` (requis, modèle)
`fire_webhook`	POSTe le contexte de l’automatisation sur votre URL de webhook au niveau du compte (configurée via `POST /hook/webhook`).	(aucune — la forme de la charge utile est fixe ; voir ci-dessous)
`send_email`	Met en file d’attente un e-mail via le pipeline de messagerie de la plateforme.	`to` (requis, e-mail) ; `subject` (optionnel, modèle) ; `message` (requis, modèle)

Fenêtre de déduplication par action

Chaque action — quel que soit son type — accepte également un champ optionnel de premier niveau dedupWindowMinutes qui remplace la fenêtre de déduplication par destinataire par défaut de 7 jours pour cette action uniquement.

Définissez-le à 0 pour désactiver entièrement la déduplication pour cette action (typique pour fire_webhook / send_email où le destinataire attend chaque événement).
Plafonné à 525600 (un an).

Action avec un override de 24h

{
  "type": "send_dm",
  "message": "Thanks {{recipient_username}}!",
  "dedupWindowMinutes": 1440
}

Charge utile `fire_webhook`

Lorsque fire_webhook s’exécute, il POSTe un corps JSON sur votre URL de webhook au niveau du compte :

{
  "automationId":      "auto_9xKp2Lm4nQ",
  "triggerId":         "trg_a1b2c3",
  "trigger":           "comment_keyword",
  "platform":          "instagram",
  "recipientId":       "17841401234567890",
  "recipientUsername": "jane_doe",
  "keyword":           "LINK",
  "timestamp":         "2026-05-12T09:14:22.000Z"
}

recipientUsername et keyword valent null lorsque le déclencheur ne les renseigne pas (p. ex. dm_keyword ne comporte pas de nom d’utilisateur dans la charge utile de Meta ; story_reply n’a pas de mot-clé).

Variables de modèle

send_dm.message, send_email.subject et send_email.message prennent en charge la substitution {{placeholder}}. Les placeholders inconnus sont rejetés au moment de la création/mise à jour (sous forme d’erreur de validation 473) afin qu’une faute de frappe ne laisse jamais fuiter en silence le littéral {{foo}} dans un message destiné au client.

Placeholder	Se résout en
`{{recipient_username}}`	Le handle Instagram de l’utilisateur engageant (lorsque le webhook le contient)
`{{recipient_id}}`	L’ID de participant Instagram (IGSID) de l’utilisateur engageant
`{{recipient_name}}`	Réservé ; se résout à vide jusqu’à ce qu’une future source d’enrichissement le renseigne
`{{sender_username}}`	Votre nom d’utilisateur Instagram lié
`{{sender_name}}`	Votre nom d’affichage Instagram lié
`{{comment_text}}`	Le texte du commentaire / DM / réponse à la story qui a déclenché le trigger
`{{comment_id}}`	L’identifiant de plateforme du commentaire / message qui s’est déclenché
`{{comment_sent_at}}`	Horodatage ISO 8601 de l’événement (lorsqu’il est disponible)
`{{matched_keyword}}`	Le mot-clé qui correspond (ou la chaîne emoji pour `dm_reaction`)
`{{platform}}`	Identifiant de plateforme (p. ex. `instagram`)
`{{trigger_type}}`	Type de déclencheur (p. ex. `comment_keyword`)

Pas de sender_email / recipient_email. Ceux-ci ne sont délibérément pas exposés — votre e-mail de facturation n’a aucune raison légitime d’apparaître dans un DM à un inconnu, et Meta ne fournit pas l’e-mail du destinataire dans les webhooks IG. Éviter ces placeholders empêche la divulgation accidentelle.

Exemple de modèle :

Hey {{recipient_username}}, thanks for the comment "{{comment_text}}" — here is the link you wanted: https://example.com

Limites de débit et plafonds

Plan	Automatisations actives (par profil)	Plafond quotidien de DM (par compte)
Business	10	1 000
Enterprise	50	5 000

Le plafond d’automatisations actives est compté par Profil utilisateur, et non par compte parent. Chaque profil sous votre compte bénéficie de son propre Business 10 / Enterprise 50, de sorte qu’un compte avec de nombreux profils peut exécuter autant d’automatisations sur chacun. Il compte les automatisations actives et est appliqué à la fois lors du POST (création) et de la réactivation PUT (active: false → true), faisant apparaître le code d’erreur 470. Besoin d’une limite par profil plus élevée ? Contactez le support pour qu’elle soit augmentée pour votre compte. Le plafond quotidien de DM s’applique par compte parent Ayrshare, partagé entre tous vos profils, avec un sous-plafond par profil pour qu’un profil très actif ne draine pas tout le quota du compte. Lorsqu’un plafond de DM est atteint, la ligne d’activité enregistre le statut rate_limited et aucun DM n’est envoyé. Plafonds structurels sur une seule automatisation : 1 à 50 déclencheurs, 1 à 50 actions. Instagram lui-même plafonne les DM à environ 200/heure par compte. Le moteur régule les envois avec une gigue de 20 à 60 secondes pour rester bien en dessous.

Statuts d’activité

Une ligne dans GET /automations/:id/activity porte un status de premier niveau plus un status par action à l’intérieur d’actionResults[] :

Statut	Signification
`pending`	Vient d’être écrite ; le worker ne l’a pas encore prise en charge
`in_flight`	Le worker est en train d’envoyer
`sent`	Chaque action a été acceptée par la plateforme. Pour `send_dm`, cela signifie qu’Instagram a accepté le message — et non que le destinataire l’a reçu (voir la note ci-dessous)
`failed`	Au moins une action a été rejetée par la plateforme ou n’a pas pu s’exécuter (et aucune n’a rencontré d’erreur d’auth). La raison figure dans `actionResults[].errorDetails`
`auth_error`	Le jeton d’accès Instagram était invalide ; le DM n’a pas été retenté
`rate_limited`	Le plafond quotidien de DM (par palier ou par profil) a été atteint ; aucun DM n’a été envoyé
`deduplicated`	Cette action a déjà été déclenchée pour ce destinataire dans sa fenêtre de dédup
`skipped`	L’automatisation est devenue inactive ou a été supprimée entre le fan-out et l’envoi

pending et in_flight sont transitoires ; tout le reste est terminal.

sent est un accusé d’acceptation par la plateforme, pas un accusé de livraison. Instagram n’expose la livraison des messages à aucune API. Une action send_dm est marquée sent au moment où Instagram accepte le message ; la réception effective par le destinataire dépend de son paramètre Instagram Message requests, qu’Ayrshare ne peut ni lire ni influencer. Voir Automation DM Sent but Not Delivered.

Codes d’erreur

L’API renvoie deux formes d’erreur :

Erreurs de règle métier portent un code numéroté d’automatisation (p. ex. { "action": "automation", "code": 469, ... }).
Erreurs de validation — tout corps de requête mal formé (champs manquants ou invalides, variables de modèle inconnues, clés non reconnues) — sont retournées comme une seule réponse 473 avec un objet details qui liste les champs fautifs. details est la sortie du validateur (formErrors plus fieldErrors). Faites vos branchements sur details, et non sur un code par condition. Dans fieldErrors, les clés sont les champs de premier niveau de la requête (triggers, actions) : un problème à l’intérieur d’une entrée spécifique, comme un déclencheur auquel il manque son keywords, est signalé sous ce champ (p. ex. triggers), tandis que formErrors contient les problèmes de niveau objet tels que les clés non reconnues.

Code	HTTP	Signification
468	403	Plan Business ou Enterprise requis
469	404	Automatisation introuvable (également retournée quand l’appelant ne la possède pas)
470	429	Plafond d’automatisations actives atteint pour votre palier de plan
471	400	Aucun compte social lié sur la plateforme demandée pour ce profil
472	403	Fonctionnalité pas encore disponible sur votre compte — contactez-nous pour un accès anticipé
473	400	Échec de la validation (corps de requête mal formé) — inspectez `details`

Ce que Meta N’AUTORISE PAS

Quelques capacités fréquemment demandées ne sont pas prises en charge car Meta ne les autorise pas sur l’API publique d’Instagram :

Auto-DM aux nouveaux abonnés. Instagram ne publie pas de webhook de suivi.
Premiers DM à des inconnus. Meta exige que le destinataire ait interagi en premier (commentaire, réponse, DM, réaction) avant qu’un compte pro puisse lui envoyer un message. Chaque déclencheur pris en charge est ancré à un tel engagement — mais notez qu’être autorisé à envoyer n’est pas la même chose que le message soit livré : le paramètre Instagram Message requests du destinataire peut toujours conduire Meta à accepter puis supprimer silencieusement le message (voir Automation DM Sent but Not Delivered).
Campagnes de sortie en masse. Les plafonds horaires de DM et les heuristiques anti-abus s’appliquent au niveau de la plateforme.

Utilisation multi-profil

Les points de terminaison respectent l’en-tête profileKey. Passez la clé d’un profil enfant et l’automatisation est créée/gérée sous ce profil. Les limites de débit se répartissent entre les profils via un sous-plafond par profil afin qu’un profil bavard ne draine pas le quota du compte parent.

FAQ

Puis-je déclencher sur un nouvel abonné ?

Non. Instagram ne publie pas de webhook de suivi, et Meta n’autorise pas les applications tierces à envoyer un DM à un utilisateur qui n’a pas interagi en premier. Chaque déclencheur pris en charge (comment_keyword, story_reply, dm_reaction, dm_keyword) est ancré à un tel engagement, ce qui rend l’envoi permissible.

Pourquoi une activité indique-t-elle `sent` alors que le destinataire n'a jamais reçu le DM ?

sent signifie qu’Instagram a accepté le message, pas qu’il a été livré. La livraison dépend du paramètre Instagram Message requests du destinataire — s’il n’autorise pas les demandes de message de tout le monde, Meta renvoie une réponse de succès et supprime silencieusement le message, sans erreur, webhook ou autre signal sur aucune surface d’API. Un DM déclenché par un commentaire, même livré avec succès, arrive également sous forme de demande de message que le destinataire doit accepter (sauf si une conversation existe déjà). Il s’agit d’une limitation permanente de la plateforme Instagram. Voir Automation DM Sent but Not Delivered.

Que se passe-t-il si mon jeton d'accès est invalide lorsqu'une automatisation se déclenche ?

La ligne d’activité enregistre le statut auth_error et le DM n’est pas retenté. Reconnectez le compte, puis le prochain engagement correspondant se déclenchera normalement.

Pourquoi y a-t-il un délai avant l'envoi du DM ?

Chaque envoi send_dm est planifié 20 à 60 secondes après l’engagement pour paraître organique aux systèmes anti-spam d’Instagram. Les actions fire_webhook et send_email n’ont PAS de gigue. L’horodatage created de la ligne d’activité est le moment où le déclencheur a correspondu ; completedAt est le moment où l’envoi s’est terminé.

Les lignes d'activité sont-elles conservées indéfiniment ?

Les lignes d’activité sont conservées indéfiniment à des fins de traçage et d’analyse. Le point de terminaison GET /automations/:id/activity renvoie les lignes des 30 derniers jours pour des raisons de performance. (La protection contre la dédup utilise sa propre fenêtre par action — par défaut 7 jours — qui est indépendante de la période de consultation des activités.)

La suppression d'une automatisation supprime-t-elle son historique d'activité ?

Non. La suppression est une suppression logique : la ligne maître est marquée deleted, aucun nouvel envoi ne se produit, mais les lignes d’activité historiques restent consultables via le point de terminaison d’activité.

Points de terminaison

POST /automations — créer une nouvelle automatisation
GET /automations — lister vos automatisations
GET /automations/:id — récupérer une automatisation avec ses déclencheurs et actions
PUT /automations/:id — mise à jour partielle ; mettre en pause via active: false
DELETE /automations/:id — suppression logique
GET /automations/:id/activity — journal d’audit d’envoi paginé par curseur

Get Started

API Endpoints

Multiple Users

Dashboard

Additional

Fonctionnement

Déclencheurs

Actions

Fenêtre de déduplication par action

Charge utile `fire_webhook`

Variables de modèle

Limites de débit et plafonds

Statuts d’activité

Codes d’erreur

Ce que Meta N’AUTORISE PAS

Utilisation multi-profil

FAQ

Points de terminaison

​Fonctionnement

​Déclencheurs

​Actions

​Fenêtre de déduplication par action

​Charge utile fire_webhook

​Variables de modèle

​Limites de débit et plafonds

​Statuts d’activité

​Codes d’erreur

​Ce que Meta N’AUTORISE PAS

​Utilisation multi-profil

​FAQ

​Points de terminaison

Fonctionnement

Déclencheurs

Actions

Fenêtre de déduplication par action

Charge utile `fire_webhook`

Variables de modèle

Limites de débit et plafonds

Statuts d’activité

Codes d’erreur

Ce que Meta N’AUTORISE PAS

Utilisation multi-profil

FAQ

Points de terminaison