Skip to content

Instantly share code, notes, and snippets.

@amponce

amponce/ai_onboarding.md

Last active December 12, 2025 19:49
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save amponce/f4b677dd7ec77ee245826902449c2535 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save amponce/f4b677dd7ec77ee245826902449c2535 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ai_onboarding.md

AI-Driven Onboarding Flow Plan

Overview

A conversational, step-by-step onboarding experience where an AI assistant (Athena) guides new users through setup, learns their intentions, and configures their workspace accordingly.

Phase 1: Account Foundation

Step What Happens AI Involvement
1. Welcome & Identity User enters name, email, creates password AI introduces itself: "Hi, I'm Athena. Let's get you set up in about 3 minutes."
2. Organization Setup Company name, industry, size AI asks conversationally: "What's your company called? What industry are you in?" Uses responses to pre-configure defaults.
3. Role Discovery AI determines user's primary function Conversational Q&A: "What brings you to Digital Bar? Are you focused on sales outreach, customer support, or managing operations?"

Phase 2: View Persona Assignment

Based on Phase 1 responses, Athena recommends one of three personas:

Persona Trigger Signals Default View Configuration
Sales & Marketing "lead generation", "outreach", "prospecting", "sales" Prioritizes: Prospecting, Campaigns, Contacts, Research
Customer Support "tickets", "support", "customer service", "help desk" Prioritizes: Tickets, Calls, Contacts, Knowledge Base
Operations & Management "manage team", "analytics", "overview", "admin" Full access, dashboard-first with all sections visible

AI presents the recommendation: "Based on what you've shared, I think you'll get the most value from our Sales & Marketing view. This puts prospecting and campaigns front and center. Sound good, or would you like to explore other options?"

Phase 3: Integration & Data Import

flowchart TD A[AI: How do you want to bring in contacts?] --> B{User Choice} B -->|CSV Upload| C[File Upload UI] B -->|Database Sync| D[Database Connection Setup] B -->|CRM Integration| E[Salesforce/HubSpot OAuth] B -->|Start Fresh| F[Skip - Create manually later]

C --> G[AI: Field Mapping Assistant]
D --> G
E --> G

G --> H[Preview & Confirm Import]
H --> I[Phase 4: Agent Configuration]
image

AI-Guided Import:

  • Athena asks: "Do you have existing contacts you'd like to bring in? I can help you import from a CSV, connect to a database, or link your CRM."
  • For CSV: AI auto-detects columns, suggests field mappings
  • For Database: Guided connection string setup with validation

Phase 4: Agent Configuration

Option Description AI Guidance
Use Platform Agents Pre-built voice agents for common use cases "Our platform agents are ready to go—no API keys needed. Perfect for getting started quickly."
Bring Your Own Connect Retell or Vapi with custom agents "If you have your own agents configured in Retell or Vapi, I can help you connect them. You'll need your API key."
Skip for Now Configure later "No problem—you can always set up agents later in Settings."

API Key Collection (if needed):

  • AI explains what's needed: "To connect your Retell agents, I'll need your API key. You can find this in your Retell dashboard under Settings > API Keys."
  • Secure input modal (using existing secrets tool pattern)

Phase 5: Team Invitations (Optional)

AI: "Would you like to invite any team members now? 
     I can send them an invitation email."

[Add Team Member Input]
- Email address
- Role selector (Viewer/Editor/Admin)

[Skip] "I'll do this later"

Phase 6: Guided First Actions

Based on persona, Athena suggests immediate next steps:

Persona First Action Suggestions
Sales & Marketing "Let's find your first prospects. What industry and location should we search?" → Launches Research
Customer Support "Let's make sure incoming calls are routed correctly. Which agent should handle support calls?" → Phone config
Operations "Here's your command center. Let me show you how to monitor team activity." → Dashboard tour

Technical Architecture

/onboarding (dedicated route)
├── OnboardingLayout.tsx (progress indicator, Athena sidebar)
├── steps/
│   ├── WelcomeStep.tsx
│   ├── OrganizationStep.tsx
│   ├── RoleDiscoveryStep.tsx (AI conversational)
│   ├── ViewPersonaStep.tsx (AI recommendation)
│   ├── DataImportStep.tsx
│   ├── AgentConfigStep.tsx
│   ├── TeamInviteStep.tsx
│   └── FirstActionsStep.tsx
├── hooks/
│   ├── useOnboardingState.ts (persists progress)
│   └── useOnboardingAI.ts (Athena responses)
└── components/
    ├── OnboardingProgress.tsx
    ├── AthenaChat.tsx (conversational UI)
    └── OnboardingCard.tsx

Database Requirements:

  • onboarding_progress table to track step completion
  • Update user_view_preferences with selected persona
  • Store onboarding responses for personalization

Key UX Principles

  1. Conversational, not form-heavy — Athena asks questions naturally, not as traditional form fields
  2. Smart defaults — AI pre-fills based on industry/role signals
  3. Escapable — Users can skip steps and return later
  4. Progress persistence — If user leaves, they resume where they stopped
  5. Immediate value — End with an action, not just "setup complete"

Questions to Resolve

Before implementation, we should decide:

  1. Voice vs. Text Athena — Should onboarding Athena be voice-enabled (like the homepage), or text-only chat?
  2. Branching depth — How detailed should role discovery questions get? (e.g., "What's your sales team size?" for Sales persona)
  3. Mandatory vs. Optional steps — Which steps must be completed before accessing the app?
  4. Re-onboarding — Can users re-trigger onboarding to reconfigure their persona?

Want me to dive deeper into any phase, or shall we start designing the UI for one of these steps?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment