How the Onboarding Bot Works

1. High-Level Architecture

• Onboarding widget script served by the onboarding widget route. It renders a modal chat UI and drives the conversation.
• Onboarding chat API receives actions from the widget and routes them to the service layer.
• Onboarding service parses cURL commands, builds HTTP requests, injects authentication, and calls external APIs.
• Admin configuration and docs-to-cURL logic prepare the registration, authentication, and initial setup specs.

2. Client-Side State and Flow

The onboarding widget is a script that manages state in local storage and an in-memory object.

• Step field holding the current phase of the flow.
• Registration fields for name, email, and password.
• Authentication token or API key returned from the auth endpoint.
• Initial setup field values collected from the user.
• Additional step definitions and per-step data collected during the flow.

The UI combines a message area, action buttons, and an input bar for free-text replies during collection phases.

3. Registration Phase

When the widget launches, it starts with a registration card that collects name, email, and password through inputs or free text.

On submit, the client sends a registration action with payload to the onboarding chat API. The backend calls the registration function, which parses the registration cURL command, builds the request, and calls the external registration API.

If authentication is configured, the onboarding service also calls the authentication function to log in and extract a token or API key, which is returned to the widget for later steps.

4. Initial Setup Phase

After registration, the widget renders an initial setup flow driven by the initial field definitions from the backend.

• It pre-populates obvious values such as name and email.
• It asks for each missing field in sequence and saves the answers.

Once all fields are collected, the widget shows a summary and asks the user to confirm or edit. On confirm, the client posts an initial setup action. The onboarding service applies defaults and mappings, injects authentication, sends the request to the configured initial setup endpoint, and persists session data along with optional lead information.

5. Additional Steps

Additional steps let you chain API calls after initial setup.

• The widget stores all step definitions and tracks which step is active.
• For each step, it collects required fields, shows a confirmation summary, and then submits an additional step action.

The onboarding service parses the step-specific configuration, filters payload to allowed keys, injects authentication, calls the external API, and appends execution details to the stored onboarding session.

6. Skip Paths and Recovery

The onboarding flow is resilient to skips and reloads.

• Users can skip initial setup and the widget jumps directly to additional steps if they exist.
• If the browser reloads, local storage state is used to resume from the correct step.
• If an additional step fails, the user sees the error and can retry or edit inputs for that step.

7. Difference from the Main Chatbot

The onboarding-only bot focuses on activation rather than general conversation.

• It has no persona detection, sales prompts, or behavioral triggers.
• It does not answer knowledge base questions and uses only the configured onboarding endpoints.
• It follows a linear, guided flow designed to get a new user fully set up with minimal confusion.