POST /v1/actions/trigger-sequence

Inscrit un contact dans une séquence publiée. Les séquences sont des campagnes multi-étapes étalées dans le temps — typiquement une série de bienvenue ou de drip avec des délais entre les étapes.

Si le contact a déjà une session running pour cette séquence, l'endpoint renvoie 200 avec status: "already_running" et n'en démarre pas une seconde. L'appel est ainsi sûr à réessayer.

POST /api/v1/actions/trigger-sequence

Corps de la requête

Champ	Type	Requis	Notes
sequence_id	UUID	oui	Doit être une séquence publiée (published_at non null)
contact_id	UUID	l'un des deux	Recherche d'un contact existant
phone	string	l'un des deux	Recherche ou création du contact (upsert automatique avec opted_in_at: now)
context	object	non	Sac libre clé/valeur passé à chaque nœud de la séquence

curl -X POST https://www.qyvo.io/api/v1/actions/trigger-sequence \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "sequence_id": "01J3S...",
    "phone": "+14155550123",
    "context": { "order_id": "ORD-1042", "first_name": "Romain" }
  }'

const session = await fetch('https://www.qyvo.io/api/v1/actions/trigger-sequence', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.QYVO_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sequence_id: '01J3S...',
    phone: '+14155550123',
    context: { order_id: 'ORD-1042', first_name: 'Romain' },
  }),
}).then((r) => r.json());

$session = Http::withToken(env('QYVO_TOKEN'))
    ->post('https://www.qyvo.io/api/v1/actions/trigger-sequence', [
        'sequence_id' => '01J3S...',
        'phone' => '+14155550123',
        'context' => ['order_id' => 'ORD-1042', 'first_name' => 'Romain'],
    ])
    ->json();

import os, httpx
session = httpx.post(
    'https://www.qyvo.io/api/v1/actions/trigger-sequence',
    headers={'Authorization': f"Bearer {os.environ['QYVO_TOKEN']}"},
    json={
        'sequence_id': '01J3S...',
        'phone': '+14155550123',
        'context': {'order_id': 'ORD-1042', 'first_name': 'Romain'},
    },
).json()

Réponse — 201 Created

{
  "id": "01J5B...",
  "status": "started",
  "sequence_id": "01J3S...",
  "sequence_name": "Welcome 7-day",
  "contact_id": "01J1Y..."
}

Si le contact est déjà dans la séquence :

{
  "id": "01J5B...",
  "status": "already_running",
  "message": "Contact is already in this sequence"
}

Erreurs

Statut	Cause
404	Sequence not found or not published — publiez-la d'abord dans le tableau de bord
404	Contact not found (uniquement lors d'une recherche par contact_id)
422	Sequence has no entry node — le graphe de la séquence est vide ; éditez-le dans le tableau de bord
422	Ni contact_id ni phone fourni

Utilisation du context

Tout ce que vous passez dans context est disponible pour les nœuds de message template dans la séquence sous la forme {{context.first_name}}, {{context.order_id}}, etc. Utile pour personnaliser la campagne avec des données de commande ou de produit.