Conversations & sessions

// Shape the server SDK forwards per observed turn (IngestMessageDto)
{
  conversationId: "ses_42",            // = browser conversationId
  userId: "u_8c1f",                     // stable end-user id
  role: "assistant",                    // "user" | "assistant" | "system"
  content: "Here's how to connect Slack…",
  recentMessages: [                     // bounded sliding window, not the full thread
    { role: "user", content: "How do I wire up Slack?" }
  ],
  model: "gpt-4o", provider: "openai",  // LLM metadata, auto-captured
  inputTokens: 312, outputTokens: 88, totalCostUsd: 0.0021
}

let conversationId = localStorage.getItem("ff_conversation");
if (!conversationId) {
  conversationId = crypto.randomUUID();
  localStorage.setItem("ff_conversation", conversationId);
}
// Pass `conversationId` to FirstflowProvider AND as `sessionId` on every server LLM call.

import { FirstflowProvider } from "@firstflow/react";

<FirstflowProvider
  agentId="agt_9f2c"
  publishableKey="pk_live_…"
  user={{ id: "u_8c1f", email: "ada@acme.com", traits: { plan: "pro" } }}
  conversationId={conversationId}     // lazy; omit until the first message
>
  {children}
</FirstflowProvider>

import { OpenAI } from "@firstflow/sdk/openai";

const openai = new OpenAI(); // reads FIRSTFLOW_API_KEY + OPENAI_API_KEY from env

const completion = await openai.chat.completions.create({
  firstflowAgentId: "agt_9f2c",
  sessionId: "ses_42",        // MUST equal the browser conversationId
  userId: "u_8c1f",           // MUST equal the provider user.id
  model: "gpt-4o",
  messages: [{ role: "user", content: "How do I wire up Slack?" }],
});

import { outcome } from "@firstflow/sdk";

outcome({
  firstflowAgentId: "agt_9f2c",
  sessionId: "ses_42",                 // same conversation id
  userId: "u_8c1f",
  outcome: "completed",                 // "completed" | "abandoned" | "escalated" | custom
  intent: "billing-question",           // free-form, grouped in analytics
});