Aller au contenu

Automatisations

Une automatisation est un template : un arbre d’étapes dessiné dans l’application (un déclencheur, des messages avec boutons, des attentes, des conditions, des actions). Il ne porte ni mot-clé, ni publication, ni valeur. Ce qui tourne, c’est une pose de ce template sur une publication : les mots-clés de cette publication, et une valeur par {variable} du template. Ce que vit la personne en face est décrit dans Automatisations commentaire → DM.

Ces routes n’existent pas dans upstream. Elles ne concernent qu’Instagram.

GET /automation-flows les templates
POST /automation-flows en créer un
GET /automation-flows/{id}
PUT /automation-flows/{id} nom, canal, définition
PUT /automation-flows/{id}/status DRAFT, ACTIVE, PAUSED ou ARCHIVED
DELETE /automation-flows/{id}
GET /automation-flows/{id}/poses où il est posé
POST /automation-flows/{id}/poses le poser sur une publication déjà en ligne
GET /automation-flow-poses?integrationId=&mediaId=&workspace= ce qui tourne sur un canal, une publication ou un workspace
GET /automation-flow-poses/{id}
PUT /automation-flow-poses/{id} mots-clés, valeurs, pause
DELETE /automation-flow-poses/{id}
GET /automation-flow-poses/{id}/runs les personnes
POST /automation-flow-poses/{id}/poll relire les commentaires maintenant
POST /automation-flow-poses/{id}/replay lancer sur des commentaires désignés
GET /automation-flow-poses/{id}/catch-up aperçu du rattrapage des commentaires déjà là
POST /automation-flow-poses/{id}/catch-up les rattraper
POST /automation-flows/email-preview rendre l’e-mail d’une étape Transmettre l’e-mail
POST /automation-flows/email-test vous envoyer cet e-mail
GET /posts/{id}/automation le template que porte une publication pas encore publiée
PUT /posts/{id}/automation lui en poser un (ou le remplacer)
DELETE /posts/{id}/automation le retirer

GET /automation-flows les liste avec status (les ACTIVE et les ARCHIVED tournent), issues (ce qui bloque l’activation : level error, ou un warning) et _count (poses, runs). POST (201) prend name (1 à 120 caractères), integrationId (le canal Instagram d’où partent les DM, peut être nul) et definition : l’arbre, dans la forme qu’écrit l’éditeur. Le serveur en retire les mots-clés, publications ou valeurs qu’il contiendrait, car ils appartiennent à une pose. PUT /automation-flows/{id} prend les trois mêmes champs, tous facultatifs.

PUT /automation-flows/{id}/status avec { "status": "ACTIVE" } est refusé (400) tant que le template porte une erreur.

{ "status": "ARCHIVED" } met de côté un template ACTIVE : ses poses continuent de tourner comme avant, mais POST /automation-flows/{id}/poses est refusé, comme tout PUT /automation-flows/{id} qui change name, integrationId ou definition (400). Seul un template ACTIVE s’archive (400 sinon : un PAUSED se reprend d’abord, un DRAFT se supprime), et un template archivé ne revient qu’en ACTIVE, avec la même vérification qu’une activation. Un post planifié avec un template archivé depuis le garde : la pose est bien créée quand le post passe en ligne.

Une publication pas encore parue n’a pas d’ID de média Instagram : il n’y a rien sur quoi poser. Passez plutôt le template dans les réglages Instagram de la publication, à la création d’une publication : la pose est créée à l’instant où la publication part en ligne.

"settings": {
"post_type": "post",
"automationFlowId": "<template id>",
"automationKeywords": ["LIEN", "LEIN", "LIENS"],
"automationVariables": { "ressource": "le guide Malte", "bouton": "Le guide", "lien": "https://…" }
}

Une publication ou une story déjà programmée, pas encore publiée, reçoit son template après coup, sans être supprimée puis reprogrammée (son lien reste le même) : PUT /posts/{id}/automation, avec l’ID de la publication renvoyé à la création d’une publication.

{ "flowId": "<template id>", "keywords": ["LIEN", "LIENS"], "variables": { "ressource": "le guide Malte", "bouton": "Le guide", "lien": "https://…" } }

C’est vérifié comme à la programmation (un template archivé est en plus refusé), cela remplace le template que portait la publication, et ses autres réglages restent tels quels. À la publication, la pose est créée exactement comme si le template avait été dans les réglages dès le départ. Une story n’a pas besoin de mot. La réponse est l’automatisation de la publication : postId, integrationId, kind (post ou story), publishDate, flowId (null s’il n’y en a pas), keywords, variables. GET la lit, DELETE la retire. Publications Instagram seulement ; une publication déjà en ligne donne un 400 avec son ID de média : posez alors sur la publication elle-même (ci-dessous).

POST /automation-flows/{id}/poses

Champ Type Obligatoire Description
integrationId string Oui Le canal Instagram
mediaId string Oui L’ID de la publication, ou celui de la story
kind string Non post (par défaut : le déclencheur du template) ou story
keywords string[] Selon le template Les mots-clés de cette publication, 30 au plus (une réponse à une story n’en demande aucun)
variables object Selon le template Une valeur par {variable} du template

Un template se pose une fois par publication. La réponse (201) est la pose.

GET /automation-flow-poses?integrationId= liste les poses d’un canal ; ajoutez mediaId= pour une seule publication. workspace= (un id renvoyé par GET /workspaces) liste celles de tous les canaux de ce workspace, à la place de integrationId ou avec lui : le canal doit alors être dans ce workspace, sinon la liste revient vide. Il faut l’un des deux. Chaque pose porte son flow (id, name, status), son mediaId et sa source (post_comment ou story_reply : ce qui la déclenche), postId (la publication UseNadia, quand elle vient du composeur), ses keywords, variables, active, et counts (runs, waiting, done, failed, emails).

counts est le funnel de la publication : runs (les personnes entrées), replied (ont réécrit après leur commentaire ou leur réponse à la story), emails, clicked (ont cliqué au moins un lien reçu, aperçus de lien exclus), et waitingAt, où attendent les waiting : firstMessage (n’ont jamais touché le premier DM), email (ont répondu sans laisser leur e-mail), other.

PUT /automation-flow-poses/{id} modifie keywords (30 au plus), variables ou active (false met en pause cette pose seule ; le statut du template est l’interrupteur de toutes). Les personnes déjà dans le parcours gardent l’arbre sur lequel elles ont démarré.

GET /automation-flow-poses/{id}/runs?status= : une ligne par personne, avec son username, le keyword qu’elle a utilisé, son email une fois donné, et un status. C’est ce qu’écrit Exporter en CSV dans l’application, pour une intégration qui récupère les e-mails sans outil d’e-mail connecté :

Statut Sens
PENDING Mot-clé reconnu, première étape pas encore envoyée
WAITING À une étape « attendre la réponse »
DELAYED Dans un délai
DONE Arrivée au bout
HANDED_OFF Passée à un humain (l’Inbox l’affiche)
FAILED error porte le message de Meta. Jamais relancée d’elle-même
SKIPPED Ignorée : une fois par personne, commentaire du compte, une réponse…

Tout autre status est refusé en 400, avec la liste de ces valeurs dans message.

POST /automation-flow-poses/{id}/poll relit maintenant les commentaires de la publication et démarre ce qu’un webhook manqué a laissé de côté ({ checked, started }).

POST /automation-flow-poses/{id}/replay lance l’automatisation sur des commentaires désignés par leur ID (commentIds, 1 à 50 ; resend relance un commentaire qui a déjà un run), quelle que soit leur date. Un résultat par commentaire : started, ou la raison du refus (not_on_post, already_has_a_run, no_keyword, once_per_user, is_a_reply, own_comment, no_author, outside_meta_7_day_window, pose_has_errors).

Une pose ignore les commentaires écrits avant elle. Le rattrapage lève ce seul garde-fou, borné à une pose : les autres restent ceux d’un commentaire neuf (premier niveau, pas les vôtres, moins de 7 jours, un des mots, une fois par personne, jamais un commentaire qui a déjà un run).

GET /automation-flow-poses/{id}/catch-up est l’aperçu, qui n’envoie rien  : checked, matching, comments (ceux qui recevraient l’automatisation, du plus ancien au plus récent, avec commentId, username, text, timestamp, keyword), skipped (les autres, comptés par raison), queued (encore en route d’un rattrapage précédent), perMinute et minutes.

POST /automation-flow-poses/{id}/catch-up les rattrape  : { matching, started, queued, perMinute }. Le premier lot part tout de suite, le reste à perMinute par minute (10), sous la limite de Meta de 750 réponses privées par heure et par compte. Le relancer n’ajoute que ce qui n’est ni servi ni en route.

Une étape Transmettre l’e-mail inscrit le contact dans votre outil d’e-mail et peut lui envoyer un modèle de cet outil. Dans la definition d’un template, elle s’écrit :

{
"type": "action",
"action": "forward_email",
"provider": "resend",
"destinationId": "…",
"destinationName": "Lecteurs du guide",
"templateId": "…",
"templateName": "Le lien demandé"
}

provider est l’identifiant de l’outil (brevo, resend), ou null tant qu’aucun n’est choisi. Les identifiants sont des chaînes, ceux de Brevo compris ("13"). Une ancienne étape "action": "brevo" avec listId est encore lue, et revient sous cette forme.

Avant que quiconque reçoive l’e-mail :

  • POST /automation-flows/email-preview le rend avec les valeurs d’un run, sans rien envoyer. La réponse (201) porte templateId, templateName, active (si l’outil enverrait le modèle : actif chez Brevo, publié chez Resend), le subject et le html rendus, le sender du modèle (nom, e-mail) et params, les valeurs utilisées pour le rendu (LINK, RESOURCE, KEYWORD, USERNAME).
  • POST /automation-flows/email-test l’envoie vraiment, à une adresse, et répond { "sent": true, "to": "…" }.
Champ Type Obligatoire Description
provider string ≤ 50 Oui L’outil, le provider de l’étape (brevo, resend)
templateId string ≤ 200 Oui Le modèle, le templateId de l’étape
brevoTemplateId number Non, déprécié Ancienne forme, encore acceptée : lue comme provider: "brevo" avec ce templateId
dmLinkUrl string ≤ 2 000 Non Le lien donné par le DM
resourceName string ≤ 200 Non Le nom de la ressource
keyword string ≤ 100 Non Le mot-clé
username string ≤ 100 Non La personne
to string ≤ 320 Oui par l’API (email-test) Où envoyer le test

Sans connexion à cet outil, pour un outil qui n’envoie pas par modèle, ou quand l’outil refuse (par exemple le test d’un modèle Resend sans From ou sans sujet), les deux routes répondent 400. Le message d’un refus de l’outil commence par son nom.