Developer Documentation
Everything you need to build with Chatterfly — from your first embedded workflow to the full REST API. New here? Start with the Introduction to learn the core concepts, then follow the Quickstart.
Quickstart
Build visually in the dashboard editor and put a live workflow on a web page in about five minutes.
Build with code
Author workflows as JSON and validate/deploy from the CLI, or point a coding agent at Chatterfly over MCP.
Getting started
Introduction
What Chatterfly is, the core concepts — workflows, runs, deployments, participants — and how the pieces fit together.
Quickstart
Go from zero to a live workflow on a web page in about five minutes. No backend code required.
Agent Quickstart
Set up a personal access token, MCP, and the CLI, then use ready-to-paste prompts to have a coding agent build and deploy workflows for you.
Embedding
Serverless Embed
The fastest way to add Chatterfly to any page — drop in a single component with a deployment ID and Chatterfly handles the rest.
Widget Embed
Full-control integration with the @chatterfly/widget React package: server-side tokens, events, imperative control, and custom input types.
Theming & Slots
The theme prop, dark mode, --cf-* CSS variables, and chrome slots (header/footer/empty/completed/error state, bubble overrides).
Floating Launcher
Turn the widget into a docked chat-bubble launcher with an expandable panel and unread badge.
Script Tag & Web Component
Embed with no build step — a single <script> tag and the <chatterfly-widget> custom element for WordPress, Shopify, and static HTML.
Headless Hook
useChatterflyRun() drives the connection and state machine with no UI, for building a fully custom participant surface.
Connection Lifecycle
Active/dormant/hibernating connection states, wake triggers, connectionPolicy tuning, jittered reconnects, and participant-token expiry re-mint.
Platform
Workflows & DSL
How workflow definitions are structured: node types, branching, template variables, surfaces, and validation.
Parallel Execution
Durable structured fan-out and fan-in, join policies, and run-item operations.
Workflow Testing
Drive test-run interactions through MCP or CLI with synthetic answers, no public tunnel required.
Surfaces & Transports
How participants communicate: transport families (widget, phone, messaging, meeting), voice styles (push-to-talk, continuous, live), triggers vs. surfaces, and the support matrix.
Input Types & Variants
Interactive showcase of every built-in input type — Boolean yes/no, NPS & emoji ratings, currency amounts, address capture, and more.
Authentication & API Keys
The three credential types — API keys, participant tokens, and dashboard sessions — and when to use each.
REST API Reference
Every public endpoint: start runs, poll status, fetch messages, stream events over WebSocket, and mint participant tokens.
Triggers & Webhooks
Start runs automatically on a schedule (cron) or from external events (inbound webhooks), and get notified with event hooks.
Connections
Outbound credentialed links your workflows call: REST APIs, OpenAPI imports, MCP servers, AI providers, and messaging accounts. How they differ from surfaces, fulfillment modes, and tool naming.
Zoho Connection
Configure regional Zoho OAuth, selective CRM/People capabilities, personal attribution, and private embedded workflows.
Knowledge Bases
Searchable document collections agents can query at runtime via RAG retrieval — upload files, ingest from workflows, bind to agents as scoped tools or pre-retrieved context.