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.

​
General

Firstflow is an SDK for adding onboarding tours, in-chat surveys, and feature announcements to AI agent and chat products. Experiences are designed visually in the Firstflow Dashboard and rendered by the SDK inside your chat UI.
No. Firstflow is a frontend-only integration. The SDK fetches configuration from the Firstflow API directly. Your backend is not involved.
Yes. Firstflow works with any React-based chat UI — Vercel AI SDK, LangChain, Botpress, OpenAI streaming, or any custom implementation. The SDK wraps your existing UI without replacing it.
Currently the SDKs are @firstflow/react, @firstflow/nextjs, and @firstflow/react-native. A vanilla JS version is on the roadmap.

​
Integration

Wrap your chat UI — the component that contains both your message list and your composer (input area). Experiences render above the composer or as an overlay depending on the experiencePlacement prop.
Yes. Use the Survey component directly for standalone surveys, or use useFirstflowSurvey() to build a fully custom survey UI. Analytics tracking via useFirstflow().analytics works independently.
The provider, widget, and hooks are Client Components ("use client"). The Next.js SDK’s getFirstflowConfig() can be called from Server Components to prefetch config. See the Next.js integration guide.
Edit or publish experiences in the Dashboard. The SDK re-fetches config automatically every 5 minutes. Call firstflow.refreshConfig() to force an immediate reload.

​
Targeting

Pass user traits to FirstflowProvider:
<FirstflowProvider
  agentId="agent_123"
  apiKey="sk_live_..."
  user={{ id: "user_123", traits: { plan: "pro", role: "admin" } }}
>
Then configure segment or rule-based audience in the Dashboard.
  • Segments are server-computed groups. Membership is calculated by the Firstflow backend based on stored user properties and returned in the SDK config. Use segments for complex or frequently-changing criteria.
  • Rules are evaluated client-side against user.traits. Use rules for simple trait-based targeting that doesn’t require server computation.
By default, FirstflowWidget shows one experience at a time — the highest-priority eligible one. Priority is set per-experience in the Dashboard.
Set frequency to once in the Dashboard. The SDK stores the show record in localStorage. To reset during testing, clear keys starting with ff_exp_.

​
Technical

Config is cached in memory for 5 minutes per agentId + apiKey pair. Multiple FirstflowProvider instances with the same credentials share the cache. Call refreshConfig() to bypass it.
In localStorage for most frequency types (keys prefixed ff_exp_). Session-scoped frequencies use sessionStorage. React Native uses AsyncStorage.
Yes. The @firstflow/nextjs SDK supports server-side config prefetching via getFirstflowConfig(). The result is passed as initialSdkPayload to avoid a client-side waterfall.
A decision node evaluates its branches in order. Each branch has conditions (AND within a branch). The first branch whose conditions match determines the next node. Conditions can reference user traits (traits.plan) or survey answers (answers.<questionId>). If no branch matches, the SDK follows the first available outgoing edge.
StyleDescription
messageSimple chat bubble
cardCard with optional icon, title, and CTA
carouselHorizontally scrollable cards
quick_repliesMessage with reply option pills
rich_cardCard with hero image/video, tags, and meta
Yes, for staging or self-hosted deployments:
# React / Vite
VITE_FIRSTFLOW_API_BASE_URL=https://your-api.example.com

# Next.js
NEXT_PUBLIC_FIRSTFLOW_API_BASE_URL=https://your-api.example.com
FIRSTFLOW_PUBLIC_API_BASE_URL=https://your-api.example.com

​
Data and privacy

  • Application data: PostgreSQL on AWS
  • Analytics events: Data warehouse (ClickHouse)
  • User frequency records: Client-side localStorage / AsyncStorage
No message content is sent to Firstflow.
No. User traits and identifiers are only used within your Firstflow account for targeting and analytics.
Enterprise plans support dedicated infrastructure. Contact sales at firstflow.app.

​
Dashboard

An agent is your workspace in Firstflow — it groups your experiences, audience, API keys, and settings. Create one agent per product or environment (e.g., production, staging).
TypeDescription
TourMulti-step flow using message nodes
SurveyFlow with survey question nodes, collects responses
AnnouncementSingle announcement card with optional CTA
All three are built with the same flow editor. The type affects how the experience is displayed and tracked.
Firstflow uses Svix for webhook delivery. Enable webhooks in Dashboard → Settings → Webhooks, then configure endpoint URLs to receive events like survey.submitted and experience.completed. All payloads are HMAC-SHA256 signed.