Vue d'ensemble de l'API Automations

Automatisations Instagram déclenchées par l’engagement — envoyez un DM, un webhook ou un e-mail lorsqu’un utilisateur final commente, répond à une story, réagit à un DM ou envoie un DM

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 fonctionne entièrement dans le cadre des règles de Meta (pas de DM déclenchés par un suivi, pas de premier message à des inconnus, pas d’envoi en masse) et hérite des limites de débit par compte d’Ayrshare, de la déduplication par destinataire et de l’ingestion idempotente des webhooks.

​

Fonctionnement

1. Créer une automatisation

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

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

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

4. 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	Toutes les actions ont réussi
failed	Au moins une action a échoué (et aucune n’a rencontré d’erreur d’auth)
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.

​

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 initie le contact (commentaire, réponse, DM, réaction) avant qu’un compte pro puisse lui envoyer un message — ce qui correspond exactement à chaque déclencheur pris en charge ici.
• 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 initié une conversation. Chaque déclencheur pris en charge (comment_keyword, story_reply, dm_reaction, dm_keyword) satisfait à l’exigence « l’utilisateur vous a contacté en premier ».

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