> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
export const PlansAvailable = ({plans = [], maxPackRequired}) => {
let displayPlans = plans;
if (plans && plans.length === 1) {
const lowerCasePlan = plans[0].toLowerCase();
if (lowerCasePlan === "business") {
displayPlans = ["Launch", "Business", "Enterprise"];
} else if (lowerCasePlan === "premium") {
displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
}
}
return
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.
{maxPackRequired && window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
Max Pack required
}
;
};
**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
`POST /automations` avec les déclencheurs et les actions souhaités. L'automatisation est activée immédiatement.
Quelqu'un commente votre publication, répond à votre story, envoie un DM ou réagit à un DM. Meta transmet le webhook à Ayrshare.
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.
`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](#template-variables). | `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`](/apis/webhooks/register)). | *(aucune — la forme de la charge utile est fixe ; voir [ci-dessous](#fire_webhook-payload))* |
| `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).
```json Action avec un override de 24h theme={"system"}
{
"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 :
```json theme={"system"}
{
"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](/apis/profiles/overview)**, 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](mailto:support@ayrshare.com) 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
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 ».
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.
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 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.)
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`](/apis/automations/create-automation) — créer une nouvelle automatisation
* [`GET /automations`](/apis/automations/list-automations) — lister vos automatisations
* [`GET /automations/:id`](/apis/automations/get-automation) — récupérer une automatisation avec ses déclencheurs et actions
* [`PUT /automations/:id`](/apis/automations/update-automation) — mise à jour partielle ; mettre en pause via `active: false`
* [`DELETE /automations/:id`](/apis/automations/delete-automation) — suppression logique
* [`GET /automations/:id/activity`](/apis/automations/get-activity) — journal d'audit d'envoi paginé par curseur