POST /v1/actions/trigger-flow

Enrolls a contact in a published flow. Flows are stateful conversational responses — short, branching, with timeouts in minutes (not days). They're the right fit for cart abandonment, in-conversation menus, and customer-service triage.

Flows have a default session TTL of 30 minutes (configurable per flow via flow.settings.session_ttl_minutes).

If the contact already has a running session for this flow, the call returns status: "already_running" instead of starting a duplicate.

POST /api/v1/actions/trigger-flow

Request body

Field	Type	Required	Notes
flow_id	UUID	yes	Must be published
contact_id	UUID	one of
phone	string	one of	Auto-upserts the contact with opted_in_at: now
context	object	no	Free-form, available inside the flow as {{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()

Response — 201 Created

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

Errors

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