Skip to main content
Every session starts through one of the entry points below. Each is gated by an explicit route policy — the authentication tier of every trigger is fixed at the API layer, and at trigger time every effective provider is validated against its required secrets (missing credentials fail with HTTP 412 before any call or agent starts).

​
Inbound triggers

Started by the outside world reaching an address you routed to a flow. The widget’s public endpoints never expose organization data: an anonymous visitor can only talk to a flow that was explicitly enabled for web embedding, from an origin on that flow’s allowlist, within rate limits. See Client Surfaces for the anonymous identity model.

​
API triggers

Server-to-server and programmatic starts.

​
POST /api/flows/:flowId/trigger

The general-purpose trigger. Accepts a user JWT or an AICO API key. Modes:
  • Headless — runs the flow without any live conversation surface (data processing, notifications, side effects).
  • Outbound call — with a destination phone number, AICO dials out and connects the answered call to the flow.
  • Synchronous — waits for completion and returns the flow’s return value in the response.
  • Callback — with a webhookUrl, the result is POSTed to your endpoint when the flow completes.
AICO has no built-in scheduler by design. Recurring or scheduled runs are driven from your side — cron, n8n, Zapier, or any job runner calling the trigger endpoint with an API key.

​
POST /api/flows/:flowId/start

The authenticated conversation start used by the dashboard flow tester and the native clients (watch, wearable scanner, desktop). Requires an organization-scoped token; starts a chat or voice session attributed to the calling user.

​
Flow-internal triggers

Started by a running flow or the runtime itself:
  • Child flows — an invoke node spawns a child flow in its own room and can ring one or more people (in-app ring + phone dial-out, first answer wins) while the original caller is held with progress narration.
  • Child completion — the child’s return node wakes the parent flow, which continues from the invoke node.
  • Async tool callbacks — a tool that reports asynchronous completion parks or forks the flow; your system later calls a single-use, HMAC-signed callback URL to resume it.
  • Silence follow-up — a per-flow policy re-engages the user after configurable silence, on voice and text channels.

​
Direct calls (no flow)

Signed-in organization members can call each other directly: device-to-device rooms with ring, accept, decline, and cancel — used by the native clients for coworker calling and for inviting a person into a running flow’s conversation (consult / handoff). Direct calls are plain calls, not flow sessions: no flow runs, and nothing is attributed to a flow’s history.

​
Start-node input contract

A flow’s start node declares a typed input contract: which inputs the flow requires, and where each comes from — supplied by the caller, derived from the channel (e.g. the caller’s phone number), or auto-generated. Triggers that don’t satisfy the contract are refused up front, so a flow can never start with missing inputs.