Chatterfly

Introduction

Chatterfly lets you build AI-powered, human-in-the-loop workflows and put them in front of users anywhere — your website, a hosted link, or your own backend. This page explains the core concepts you'll see everywhere else in the docs.

What is Chatterfly?

Chatterfly is a workflow platform that combines three things:

  • AI agents — LLM-backed steps that can converse, reason, and call tools.
  • Human-in-the-loop (HITL) steps — points where a workflow pauses and asks a real person for input: a chat reply, a form, a rating, a file, a voice answer.
  • Automation — tool calls, code execution, branching, loops, schedules, and webhooks that glue everything together.

You design workflows visually in the dashboard editor (or as JSON), deploy them, and then anyone — customers, teammates, other systems — can participate in them.

Core concepts

Five terms appear throughout the docs. Here is what each one means and how they relate:

ConceptWhat it is
WorkflowThe design — a tree of nodes (Agent, Input, Message, Tool, Conditional…) describing what should happen. You edit workflows in the dashboard; they are versioned as you save.
DeploymentA published, pinned version of a workflow. Deploying freezes the definition and gives you an API key and a deployment ID (e.g. dep_abc123). Runs are always started against a deployment, so editing the workflow later never breaks live traffic.
RunA single execution of a deployment. Each run has its own state, timeline of events, and participants. Runs are started from the API, a trigger, the hosted survey page, or the dashboard.
ParticipantA person (or agent, or application) taking part in a run, identified by a role (e.g. customer, reviewer). External participants authenticate with short-lived participant tokens — they never need a Chatterfly account.
TenantYour organisation's workspace. Workflows, deployments, runs, API keys, connections, and knowledge bases all belong to a tenant. Users can be members of multiple tenants.
Tip: The mental model in one sentence: a workflow is the recipe, a deployment is the published edition of the recipe, and a run is one meal cooked from it — with participants sitting at the table.

Lifecycle of a run

A typical embedded workflow goes through these stages:

  1. Build — create a workflow in the dashboard editor.
  2. Deploy — publish it. You get an API key and deployment ID.
  3. Start a run — via POST /api/v1/runs, a trigger (cron or webhook), the serverless embed, or a hosted survey link.
  4. Execute — the engine walks the node tree: agents respond, tools are called, messages are sent.
  5. Pause for humans — when the run reaches an Input or Agent node that needs a person, it opens a HITL session. The widget (or inbox, or messaging channel) renders it and collects the answer.
  6. Resume & complete — submitted answers flow back into run state and execution continues until the workflow finishes.

Every step is recorded on the run's timeline, which you can inspect in the dashboard or stream live over WebSocket.

Ways to integrate

There are three integration paths, in increasing order of control:

1. Hosted page

Zero code. Share a link like /survey/<tenant>/<slug> and Chatterfly hosts the whole experience.

2. Serverless embed

One React component with a deploymentId prop. No backend code — Chatterfly creates runs and tokens automatically.

3. Full widget

Your server starts runs and mints participant tokens with the REST API. Maximum control over identity, roles, and lifecycle.

All three render the same participant experience — the @chatterfly/widget chat UI with rich input types, voice, and theming.

Next steps