How to Build a Claude-Powered Onboarding Assistant

Building a Claude-powered customer onboarding assistant means wiring Claude's API into your app's onboarding flow so it can answer setup questions, walk users through configuration steps, and flag when someone is stuck — all without a human support agent in the loop for every message. The core pieces are a system prompt that encodes your product's onboarding logic, tool calls that let Claude check account state or trigger actions, and a chat UI embedded directly in your onboarding screens.

This guide covers the architecture, the prompt design, and the tool definitions you need to ship this in a weekend, plus where it tends to break in production and how to avoid those failures.

Why onboarding is a good fit for Claude

Onboarding support tickets are repetitive by nature: "where do I find my API key," "how do I invite teammates," "why isn't my webhook firing." These questions have deterministic answers that live in your docs, your account schema, or your product's current state. That's exactly the kind of task an LLM with tool access handles well — it can read context, decide which lookup to run, and phrase the answer in plain language instead of linking to a help article and hoping the user reads it.

The alternative — a rules-based chatbot tree — breaks the moment a user phrases their question slightly differently than you anticipated. Claude handles that variance natively.

Step 1: Define the onboarding states you need to support

Before writing any code, map out the discrete states a user can be in during onboarding. For a typical B2B SaaS:

• Account created, email unverified
• Email verified, no workspace created
• Workspace created, no team invited
• Team invited, no integration connected
• Integration connected, first action not taken

Each state has a different "next best step," and your assistant should know which state the current user is in before it responds. This is the single biggest factor in whether the assistant feels helpful or generic.

Step 2: Build a tool that exposes account state

Claude can't know your user's onboarding state unless you tell it. Define a tool that looks up the current state from your database and pass it as part of the tool use flow.

{
  "name": "get_onboarding_status",
  "description": "Returns the current onboarding step, completed steps, and the user's workspace configuration.",
  "input_schema": {
    "type": "object",
    "properties": {
      "user_id": { "type": "string" }
    },
    "required": ["user_id"]
  }
}

When Claude calls this tool, your backend returns something like:

{
  "current_step": "team_invited",
  "completed_steps": ["email_verified", "workspace_created", "team_invited"],
  "remaining_steps": ["integration_connected", "first_action"],
  "workspace_name": "Acme Corp"
}

Claude then uses that structured state to give a grounded, specific answer instead of a generic one. For a full walkthrough of defining and handling tools, see /docs/tools.

Step 3: Write a system prompt that constrains scope

Onboarding assistants fail when they try to answer everything. Scope the system prompt tightly:

You are the onboarding assistant for [Product]. Your only job is to help
new users complete setup. You can:
- Explain what each onboarding step requires
- Call get_onboarding_status to check progress
- Call send_invite_reminder if a user asks to re-send a teammate invite
- Point to docs for anything outside onboarding

If a user asks about billing, security, or anything unrelated to setup,
say so plainly and direct them to support@[product].com. Do not guess
about account-specific data you haven't fetched via a tool.

That last line matters more than it looks — without it, Claude will sometimes answer plausibly instead of calling the tool, which produces confidently wrong answers about account-specific details.

Step 4: Wire it up with streaming

Onboarding assistants live inside the product UI, so responses need to feel instant. Streaming tokens as they're generated instead of waiting for the full response is the difference between "this feels like a helper" and "this feels like a form submission." If you're using SubToAPI as your Claude access layer, streaming is supported out of the box — see /docs/streaming for the implementation details.

A minimal request looks like this:

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4",
    max_tokens: 1024,
    stream: true,
    system: ONBOARDING_SYSTEM_PROMPT,
    tools: [getOnboardingStatusTool, sendInviteReminderTool],
    messages: [{ role: "user", content: userMessage }]
  })
});

This is identical in shape to calling Claude's API directly — SubToAPI exposes the same messages format behind an application key (sub_live_...), which means you can assign a dedicated key per app or environment and see usage broken down per key in the dashboard. That's useful once you have an onboarding assistant, a support assistant, and an internal tool all calling Claude from the same team account. See /docs/messages for the full request/response reference, or /docs/quickstart if you're starting from zero.

Step 5: Add escalation, not just answers

The assistant's job isn't to answer every question — it's to know when it can't. Build an explicit escalation path: after two unresolved exchanges on the same topic, surface a "talk to a human" button that pre-fills a support ticket with the conversation transcript. This single feature does more for user trust than any amount of prompt tuning, because users stop treating the bot as a wall between them and real help.

Step 6: Instrument and iterate

Log every tool call Claude makes and every message where the user abandoned the conversation. The patterns here tell you which onboarding step is genuinely confusing versus which step the assistant explains poorly — those are different problems with different fixes.

Getting started

If you already have Claude access through your organization, you can be live with a working assistant today: create an application key at /signup, drop the system prompt and tool definitions above into your onboarding UI, and point requests at the SubToAPI endpoint instead of managing provider credentials directly. Plans start at €9/month for solo projects, with team seats at /pricing for larger builds.

questions

Does the onboarding assistant need its own Claude account? No — you can use a dedicated application API key scoped to that feature while sharing billing and usage reporting with the rest of your team's Claude usage.

How do I stop the assistant from making up account details? Force tool use for anything account-specific in the system prompt, and avoid giving Claude raw database access — only expose narrow, purpose-built tools like get_onboarding_status.

Should the assistant replace onboarding emails and docs? No, it should sit alongside them. Use the assistant for real-time, in-context questions and keep static docs as the reference source it points to when a topic is outside its scope.