POST /v1/actions/trigger-flow

Inscrit un contact dans un flow publié. Les flows sont des réponses conversationnelles à état — courtes, avec branches, dont les timeouts se mesurent en minutes (et non en jours). Ils sont adaptés à l'abandon de panier, aux menus en cours de conversation et au triage du service client.

Les flows ont un TTL de session par défaut de 30 minutes (configurable par flow via flow.settings.session_ttl_minutes).

Si le contact a déjà une session running pour ce flow, l'appel renvoie status: "already_running" au lieu d'en démarrer une en doublon.

POST /api/v1/actions/trigger-flow

Corps de la requête

Champ	Type	Requis	Notes
flow_id	UUID	oui	Doit être publié
contact_id	UUID	l'un des deux
phone	string	l'un des deux	Upsert automatique du contact avec opted_in_at: now
context	object	non	Libre, accessible dans le flow via {{context.*}}

curl -X POST https://www.qyvo.io/api/v1/actions/trigger-flow \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "01J3F...",
    "phone": "+14155550123",
    "context": { "cart_id": "987654321", "cart_total": "129.00" }
  }'

const session = await fetch('https://www.qyvo.io/api/v1/actions/trigger-flow', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.QYVO_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    flow_id: '01J3F...',
    phone: '+14155550123',
    context: { cart_id: '987654321', cart_total: '129.00' },
  }),
}).then((r) => r.json());

$session = Http::withToken(env('QYVO_TOKEN'))
    ->post('https://www.qyvo.io/api/v1/actions/trigger-flow', [
        'flow_id' => '01J3F...',
        'phone' => '+14155550123',
        'context' => ['cart_id' => '987654321', 'cart_total' => '129.00'],
    ])
    ->json();

import os, httpx
session = httpx.post(
    'https://www.qyvo.io/api/v1/actions/trigger-flow',
    headers={'Authorization': f"Bearer {os.environ['QYVO_TOKEN']}"},
    json={
        'flow_id': '01J3F...',
        'phone': '+14155550123',
        'context': {'cart_id': '987654321', 'cart_total': '129.00'},
    },
).json()

Réponse — 201 Created

{
  "id": "01J5A...",
  "status": "started",
  "flow_id": "01J3F...",
  "flow_name": "Abandoned cart 30min",
  "contact_id": "01J1Y..."
}

Erreurs

Statut	Cause
404	Flow not found or not published
422	Flow has no entry node