Guides

Déclencher un workflow depuis ton application

Faire entrer un contact dans un workflow quand quelque chose se passe chez toi, une commande payée ou un essai terminé, en cURL ou avec le SDK.

Un workflow peut démarrer quand ton application le lui demande. Quand une commande est payée, ton site envoie un événement : le contact est créé s’il n’existe pas, puis il entre dans le workflow qui attend cet événement.

Avant de commencer : une clé d’API pour ton application (voir Envoyer depuis ton logiciel), et un workflow actif dont le déclencheur est Ton application envoie un événement.

Choisis le nom de l'événement
Dans le workflow, sur la carte Déclencheur, tape un nom comme « Commande payée ». Il devient commande_payee : minuscules, sans accents, espaces remplacés par _. Tu peux aussi écrire directement le nom technique, avec des lettres minuscules, des chiffres, ., _ ou -.
Active le workflow
Un workflow qui attend un événement s’active comme les autres. À l’activation, il ne touche pas aux contacts déjà présents : seuls les événements reçus après l’activation le font entrer.
Envoie l'événement depuis ton application
Au moment voulu, ton application appelle l’API avec le nom et l’adresse du contact. Le contact est créé ou complété, puis il entre dans le workflow.

Envoyer l’événement

curl -X POST https://api.mail.hgdc.ch/events \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "commande_payee",
    "email": "client@exemple.ch",
    "first_name": "Léa",
    "properties": { "montant": 129.9 }
  }'

const response = await fetch("https://api.mail.hgdc.ch/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENTMAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "commande_payee",
    email: "client@exemple.ch",
    first_name: "Léa",
    properties: { montant: 129.9 },
  }),
})
const result = await response.json()

import { Agentmail } from "./lib/agentmail"

const mail = new Agentmail()
const result = await mail.events.send({
  name: "commande_payee",
  email: "client@exemple.ch",
  first_name: "Léa",
  properties: { montant: 129.9 },
})

La réponse dit ce qui s’est passé :

{
  "object": "event",
  "name": "commande_payee",
  "contact_id": "kn4d7b2x9q1m6v3r8c0w5h2t",
  "workflows_started": 1
}

workflows_started compte les workflows où le contact vient d’entrer. Un contact n’entre qu’une fois par workflow : envoyer deux fois le même événement ne le fait pas repartir.

Ce qui se passe ensuite

Un contact désabonné n’entre dans aucun workflow.
Si aucun workflow actif n’attend ce nom, workflows_started vaut 0. Ce n’est pas une erreur.
Les champs first_name et last_name complètent le contact s’il existe déjà.

Le détail de chaque champ est dans Introduction à l’API.

Si ça ne marche pas

Réponse	Cause	Quoi faire
`401 missing_api_key`	Pas d’en-tête `Authorization`.	Ajoute `Authorization: Bearer …`.
`403 invalid_api_key`	Clé inconnue ou révoquée.	Vérifie la variable d’environnement, ou crée une nouvelle clé.
`422`	Nom d’événement invalide.	Le nom ne garde que les lettres minuscules, les chiffres, `.`, `_` et `-`.
`429 rate_limit_exceeded`	Trop d’écritures en peu de temps.	Attends un peu, puis réessaie.
`workflows_started: 0`	Aucun workflow actif n’attend ce nom, ou le contact y est déjà passé.	Vérifie le nom exact dans le déclencheur, et que le workflow est actif.

Cette page t'a aidé ?