Parcours marketing

Les journeys (ou flows) sont des automatisations en plusieurs étapes : un déclencheur enrôle un contact, puis le contact avance d'étape en étape au fil du temps. Ils se gèrent avec le router tRPC journeys de l'API Plateforme, appelé à /api/trpc/journeys.<procedure> selon les conventions tRPC. Les procédures (hors tick) agissent sur le site courant de votre session.

Attention

Aujourd'hui, seules les étapes EMAIL produisent un effet. L'étape SMS est ignorée, et les autres étapes d'action se contentent de faire avancer le contact. Une étape WEBHOOK n'émet pas de requête sortante. Consultez le tableau des types d'étapes ci-dessous avant de concevoir un journey.

Procédures

Procédure Rôle Permission
list Lister les journeys du site, avec le nombre d'étapes et d'enrôlements. automation:read
get Récupérer un journey et ses étapes. automation:read
create Créer un journey (inactif, sans étapes). automation:write
update Mettre à jour les métadonnées d'un journey (nom, description, priorité). automation:write
updateSteps Remplacer la liste ordonnée des étapes (50 au plus). Journey inactif uniquement. automation:write
activate Activer un journey (il commence à se déclencher). automation:write
pause Mettre un journey en pause. automation:write
setActive Définir explicitement l'état actif. automation:write
listTemplates Lister les modèles prêts à l'emploi. automation:read
createFromTemplate Créer un journey à partir d'un modèle. automation:write
listEnrollments Lister les enrôlements. automation:read
enroll Enrôler un contact manuellement. automation:write
getStats Statistiques du site : nombre de journeys, journeys actifs, enrôlements par statut. automation:read
tick Faire avancer les enrôlements arrivés à échéance. La plateforme l'appelle déjà à intervalle régulier. automation:write

Paramètres d'entrée

Procédure Entrée
list activeOnly? (booléen).
get, activate, pause id (UUID du journey).
create name (1 à 100 caractères), description? (500 au plus), trigger? (par défaut MANUAL), priority? (1 à 1000, par défaut 100), maxDurationDays? (1 à 365), templateKey?.
update id, puis name?, description?, priority?.
updateSteps id, steps : tableau d'étapes (voir « Étapes et délais » ci-dessous).
setActive id, isActive (booléen).
createFromTemplate templateKey (clé du modèle), name?. Si le nom existe déjà sur le site, un suffixe (2), (3)… est ajouté.
listEnrollments journeyId?, status? (ACTIVE, PAUSED, COMPLETED, EXITED, ERROR), limit? (1 à 500, par défaut 100). Tri du plus récent au plus ancien.
enroll journeyId, puis un contact : clientId, leadId ou email (avec firstName?, lastName?).

Erreurs courantes :

Code Cas
NOT_FOUND Le journey n'existe pas sur le site courant.
BAD_REQUEST updateSteps sur un journey actif (mettez-le en pause d'abord), clé de modèle inconnue, ou enroll sans clientId, leadId ni email.

Déclencheurs

Un journey démarre quand son déclencheur se produit pour un contact :

Déclencheur Se produit sur
NEWSLETTER_SIGNUP Une inscription à la newsletter, un formulaire d'inscription public, ou un opt-in consenti sur un jeu-concours ou un portail Wi-Fi.
CART_ABANDONED Un panier détecté comme abandonné.
ORDER_MINTED Le paiement d'une commande.
DATE_WINBACK Un client devenu inactif.
MANUAL Un appel explicite à journeys.enroll.

Étapes et délais

Chaque étape a un name (1 à 120 caractères), un stepType, une valeur delayMinutes (entier de 0 à 525 600, soit un an) et, selon le type, un objet actionData. Le délai se compte à partir de l'exécution de l'étape précédente : une étape avec delayMinutes: 4320 s'exécute trois jours après celle qui la précède. Le délai de la première étape se compte à partir de l'enrôlement.

La colonne statut décrit le comportement actuel de chaque type d'étape :

Type d'étape Statut
EMAIL Actif : c'est la seule étape qui envoie.
WAIT Contrôle de flux : ne fait rien par lui-même ; son délai sert à espacer l'étape suivante.
CONDITION Contrôle de flux : simple marqueur, aucun branchement n'est évalué.
GOAL Contrôle de flux : marqueur d'objectif.
SMS Sans effet : ignorée, aucun SMS n'est envoyé.
WEBHOOK Sans effet : n'émet aucune requête sortante.
UPDATE_FIELD Sans effet.
ADD_TO_SEGMENT Sans effet.
REMOVE_FROM_SEGMENT Sans effet.
CREATE_TASK Sans effet.
SEND_NOTIFICATION Sans effet.

Une étape « sans effet » est bien traversée (l'enrôlement passe à l'étape suivante), mais elle ne modifie rien et n'envoie rien. Ne comptez pas sur elle pour une action métier. Une fois la dernière étape exécutée, l'enrôlement est terminé.

Étape EMAIL

L'actionData d'une étape EMAIL accepte :

Clé Rôle
emailType Type d'e-mail. Si un modèle d'e-mail est configuré pour ce type sur le site, il est utilisé en priorité.
fallbackSubject Objet utilisé sans modèle configuré (par défaut « Notification »).
fallbackHtml HTML utilisé sans modèle configuré. Sans modèle ni fallbackHtml, l'envoi échoue.
variables Variables supplémentaires pour le modèle d'e-mail configuré. {{firstName}} et {{lastName}} sont fournies d'office. Le fallbackHtml est envoyé tel quel, sans substitution de variables.

L'e-mail part à l'adresse du contact ; les destinataires désabonnés sont écartés. Si l'envoi échoue (contact sans adresse, aucun contenu), l'échec est enregistré et l'enrôlement passe quand même à l'étape suivante.

updateSteps remplace toute la liste : l'ordre du tableau devient l'ordre des étapes. Une étape transmise avec son id existant est mise à jour sur place (les enrôlements en cours la conservent) ; une étape sans id est créée ; une étape absente du tableau est supprimée, et les enrôlements qui s'y trouvaient sont terminés.

curl -X POST "https://manage.inklura.fr/api/trpc/journeys.updateSteps" \
  -H "Authorization: Bearer $INKLURA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"id":"<journey-id>","steps":[
        {"name":"Bienvenue","stepType":"EMAIL","delayMinutes":0,
         "actionData":{"emailType":"journey.welcome.intro",
                       "fallbackSubject":"Bienvenue",
                       "fallbackHtml":"<p>Bonjour,</p>"}},
        {"name":"Relance","stepType":"EMAIL","delayMinutes":4320,
         "actionData":{"fallbackSubject":"Pour bien démarrer",
                       "fallbackHtml":"<p>Quelques ressources pour commencer.</p>"}}
      ]}}'

Durée maximale

maxDurationDays (sur create, ou fixé par le modèle) borne la vie d'un enrôlement : passé ce nombre de jours depuis l'enrôlement, il est terminé sans exécuter les étapes restantes.

Modèles prêts à l'emploi

listTemplates expose des journeys tout faits ; createFromTemplate en crée un :

Modèle Déclencheur Déroulé Durée maximale
welcome NEWSLETTER_SIGNUP E-mails à J+0, J+3 et J+10, puis un GOAL. 30 jours
abandoned-cart CART_ABANDONED E-mails 1 h après l'enrôlement, puis 24 h après l'enrôlement. 7 jours
post-purchase ORDER_MINTED Remerciement à J+0, demande d'avis à J+7. 30 jours
win-back DATE_WINBACK J+0, puis J+3. 21 jours

Les e-mails des modèles portent un emailType et un contenu de repli en français ; configurez un modèle d'e-mail pour ce type, ou remplacez les étapes avec updateSteps, pour adapter le texte.

Note

create et createFromTemplate créent un journey inactif. Rien ne se déclenche tant qu'un administrateur ne l'a pas activé avec activate.

Comment se fait l'enrôlement

L'enrôlement automatique ne vise qu'un journey actif dont le déclencheur correspond (si plusieurs correspondent, celui dont la valeur priority est la plus basse). Un contact n'est enrôlé qu'une seule fois par journey.

Déclencheur Enrôlement Par défaut
NEWSLETTER_SIGNUP Au moment de l'inscription publique. Le contact est retrouvé ou créé comme prospect à partir de son e-mail. Actif.
CART_ABANDONED Une recherche régulière des paniers non vides d'un client identifié, inactifs depuis plus d'une heure (et moins de 14 jours), traitée par lots. Actif.
DATE_WINBACK Une recherche régulière des clients dont toutes les commandes ont plus de 90 jours, traitée par lots. Actif.
ORDER_MINTED Au paiement de la commande. Désactivé : ce déclencheur n'enrôle pas encore automatiquement.
MANUAL En appelant journeys.enroll avec un journeyId et un contact (clientId, leadId ou email). s.o.

Avec enroll, clientId est prioritaire, puis leadId ; avec seulement email, le prospect correspondant est retrouvé ou créé. enroll ne vérifie pas que le journey est actif. La réponse (sous result.data.json) indique le résultat :

{ "enrolled": true, "enrollmentId": "<enrollment-id>", "journeyId": "<journey-id>" }

Quand rien n'est fait, enrolled vaut false et reason explique pourquoi : already-enrolled (contact déjà enrôlé dans ce journey) ou journey-has-no-steps.

Une fois le contact enrôlé, la plateforme fait avancer les enrôlements arrivés à échéance grâce à une tâche planifiée qui appelle journeys.tick. Vous n'avez pas à l'appeler vous-même.

Note

pause arrête les nouveaux enrôlements automatiques, mais les enrôlements déjà en cours continuent d'avancer et d'envoyer leurs e-mails.

Définir et activer un journey

journeys.createFromTemplate         (ou : journeys.create + journeys.updateSteps)
        │
        ▼
journeys.activate

Pour modifier les étapes d'un journey actif : pause, puis updateSteps, puis activate.

Après activate :

  • l'enrôlement se fait automatiquement selon le déclencheur (voir le tableau ci-dessus) ;
  • ou vous enrôlez des contacts manuellement avec journeys.enroll (déclencheur MANUAL).

Voir aussi