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.

​
Onboarding tour for new users

Show a multi-step walkthrough the first time a user opens chat. Dashboard:
  1. Create an experience → Tour
  2. Add message nodes for each step
  3. Set trigger: chat_opens
  4. Set frequency: once
  5. Set audience: all (or a segment like “new users”)
Code — no changes needed beyond the base integration: 
<FirstflowWidget experiencePlacement="inlineStack">
  <MessageList />
  <Composer />
</FirstflowWidget>
The tour renders automatically on the first chat open.

​
NPS survey after engagement

Collect Net Promoter Score after the user has sent a few messages. Dashboard:
  1. Create an experience → Survey
  2. Add an NPS question (0–10 scale)
  3. Set trigger: after_user_message
  4. Set frequency: once per week
  5. Set audience: all
Code: 
<FirstflowWidget>
  <MessageList />
  <Composer />
</FirstflowWidget>

​
Feature announcement for a specific plan

Announce a new feature only to Pro users. Dashboard:
  1. Create an experience → Announcement
  2. Add title, description, and a CTA button
  3. Set audience: segment “pro users” (or rule: plan equals pro)
  4. Set schedule: start when ready
Code — pass user traits to enable targeting: 
<FirstflowProvider
  agentId="your-agent-id"
  apiKey="your-api-key"
  user={{
    id: user.id,
    traits: { plan: user.plan },
  }}
>
  <FirstflowWidget>
    <MessageList />
    <Composer />
  </FirstflowWidget>
</FirstflowProvider>

​
Custom event trigger

Fire an experience after a specific action in your app (e.g., completing checkout). Dashboard:
  1. Set trigger: custom_event
  2. Set event name: checkout_completed
Code: 
const firstflow = useFirstflow();

async function handleCheckout() {
  await submitOrder();
  firstflow.analytics.track("checkout_completed");
  // If an experience is configured for this event, it shows next time chat opens
}

​
Decision branch based on survey answer

Route users through different flows based on their NPS score. Dashboard — flow editor:
  1. Add a survey node with an NPS question
  2. Add a decision node connected to the survey
  3. Branch 1: condition answers.nps_score >= 9 → “Thank you, would you leave a review?”
  4. Branch 2: condition answers.nps_score <= 6 → “We’re sorry, what can we improve?”
  5. Branch 3 (else): → “Thanks for your feedback”
This is configured entirely in the flow editor. No code changes.

​
Segment targeting

Target users based on computed segments. Dashboard:
  1. Create a segment: Audience → Segments → New Segment
  2. Add rules, e.g., “plan equals enterprise AND sessions > 5”
  3. Set experience audience to that segment
Code: 
<FirstflowProvider
  user={{
    id: user.id,
    traits: {
      plan: user.plan,
      sessions: user.sessionCount,
    },
  }}
>
Segment membership is computed server-side. The SDK receives the membership map in the config response and evaluates it when rendering.

​
Server-side rendering (Next.js)

Eliminate the loading flash when the SDK fetches config on the client. 
// app/layout.tsx
import { getFirstflowConfig } from "@firstflow/nextjs/server";
import { FirstflowProvider } from "@firstflow/nextjs";

export default async function RootLayout({ children }) {
  const config = await getFirstflowConfig();

  return (
    <html>
      <body>
        <FirstflowProvider
          agentId={process.env.FIRSTFLOW_AGENT_ID!}
          initialSdkPayload={config}
        >
          {children}
        </FirstflowProvider>
      </body>
    </html>
  );
}

​
Standalone survey in a modal

Render a specific survey outside FirstflowWidget, for example in a dedicated feedback modal. 
import { Survey } from "@firstflow/react";

function FeedbackModal({ open, onClose }: { open: boolean; onClose: () => void }) {
  return open ? (
    <div className="modal-overlay">
      <div className="modal">
        <Survey
          experienceId="your-survey-id"
          layout="paginated"
          onSubmitted={onClose}
          onDismissed={onClose}
        />
      </div>
    </div>
  ) : null;
}

​
Inline placement with overlay for announcements

Show tours inline but announcements as overlays — per-experience placement in the Dashboard overrides the widget default. 
<FirstflowWidget experiencePlacement="inlineStack">
  {/* Tours and surveys appear inline */}
  {/* Announcements can override to overlay in Dashboard settings */}
  <MessageList />
  <Composer />
</FirstflowWidget>

​
Wiring experience prompts to your chat input

When a flow node has a button CTA with a configured ctaPrompt, Firstflow calls onExperienceUserPrompt. Wire it to send the message through your chat: 
<FirstflowProvider
  agentId="your-agent-id"
  apiKey="your-api-key"
  onExperienceUserPrompt={(event) => {
    // event.prompt is the text configured in the flow editor
    chatEngine.sendMessage(event.prompt);
  }}
>
This enables guided prompting: a tour step can say “Click to ask the agent about billing” and automatically send the message on click.