Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstflow.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Core concepts

TermDefinition
AgentA workspace that groups your experiences, audience, and settings. One agent per AI product or environment.
ExperienceA single flow — a tour, survey, or announcement — with its content, triggers, and audience settings.
FlowThe node graph that defines an experience: the sequence of messages, decisions, and actions.
NodeA single step in a flow. Types: message, decision, announcement.
EdgeA directed connection between two nodes. Decision nodes have multiple outgoing edges, one per branch.
TriggerThe condition that causes an experience to appear: chat_opens, after_user_message, after_idle, or custom_event.
AudienceWho sees an experience: everyone, a named segment, or users matching trait rules.
SegmentA server-computed group of users (e.g., “Pro plan users”). Membership is calculated by the backend and returned in the SDK config.

​
Architecture

┌─────────────────────────────────────────────────────────┐
│  Dashboard (Next.js)                                    │
│  Create experiences, set triggers, manage audience      │
└─────────────────────┬───────────────────────────────────┘
                      │ REST API
┌─────────────────────▼───────────────────────────────────┐
│  API (NestJS + PostgreSQL)                              │
│  Stores experiences (flow graph + settings)             │
│  Computes audience segment memberships                  │
│  Webhooks via Svix                                      │
└─────────────────────┬───────────────────────────────────┘
                      │ GET /agents/:id/config
┌─────────────────────▼───────────────────────────────────┐
│  SDK (@firstflow/react / nextjs / react-native)         │
│  Fetches config → evaluates eligibility                 │
│  FirstflowWidget renders the active experience          │
└─────────────────────────────────────────────────────────┘
The API stores two representations of each experience:
  • flow — the full editor graph (used by the Dashboard builder)
  • flowRuntime — a stripped version with editor-only nodes removed (used by the SDK)

​
Experience lifecycle

​
1. Design-time (Dashboard)

You build an experience using the visual flow editor:
  1. Add message or decision nodes
  2. Connect them with edges
  3. Configure triggers (when it shows) and audience (who sees it)
  4. Set frequency, device, and schedule
  5. Publish (status → active)

​
2. Fetch

The SDK fetches GET /agents/:id/config on mount. The response includes all active experiences for the agent, including flow graphs, settings, and the current user’s segment memberships. Config is cached in memory for 5 minutes. Subsequent mounts with the same agentId + apiKey reuse the cache.

​
3. Eligibility evaluation

For each experience, the SDK runs this check client-side: 
status === "active"
AND device matches (desktop / mobile / all)
AND schedule window is open (start ≤ now < expiry)
AND frequency limit not reached (checked against localStorage)
AND audience matches (all, or segment membership, or trait rules)
AND trigger condition is satisfied
The highest-priority passing experience is shown first.

​
4. Rendering

FirstflowWidget renders the active experience. Placement is either:
  • overlay — centered modal over the chat
  • inlineStack — inline, above the chat input

​
5. Node execution

The SDK walks the flow graph:
  1. Start at the first non-editor node
  2. Render the node (message, announcement, decision)
  3. On user action (CTA click, survey answer, dismiss), follow the outgoing edge
  4. For decision nodes, evaluate branch conditions to pick the next node
  5. Continue until there are no more outgoing edges

​
6. Analytics

The SDK fires events throughout the flow. Events are batched and sent to the analytics pipeline:
EventWhen
experience.startedFirst node rendered
experience.completedNo more nodes remain
experience.dismissedUser dismisses
survey.answerUser answers a question
survey.submittedSurvey flow completes
announcement.clickedCTA activated

​
Decision nodes

A decision node splits the flow into up to 3 branches. Each branch has conditions (AND within a branch, OR across branches). The first branch whose conditions match determines the next node. 
Decision node
├── Branch "If"   (conditions: plan equals "pro")  → Node A
├── Branch "Else if" (conditions: plan equals "free") → Node B
└── Branch "Else" (no conditions → always matches) → Node C
Branch conditions can evaluate:
  • User traits: traits.plan, traits.role, etc.
  • Survey answers: answers.<questionId>

​
Frequency tracking

The SDK tracks how many times each experience has been shown, stored in localStorage (or sessionStorage for session-scoped limits).
Frequency typeBehavior
onceShow one time, ever
limitedShow up to N times per session, day, week, or lifetime
alwaysNo limit
Storage keys use the prefix ff_exp_ — clear them to reset frequency for testing.