dialogbrain-com Onboarding API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Onboarding API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Onboarding
paths:
  /api/onboarding/status:
    get:
      tags:
      - Onboarding
      summary: Get Onboarding Status
      description: 'Get current onboarding state for the user.


        Returns status, current product, step, and any saved data.

        Used by frontend to determine where to resume.'
      operationId: get_onboarding_status_api_onboarding_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStatusResponse'
  /api/onboarding/ru-superagent/owner:
    get:
      tags:
      - Onboarding
      summary: Get Superagent Owner
      description: Return the current owner contacts from the Router's sender_filter trigger.
      operationId: get_superagent_owner_api_onboarding_ru_superagent_owner_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/onboarding/ru-superagent/set-owner:
    post:
      tags:
      - Onboarding
      summary: Set Superagent Owner
      description: 'Set or update the superagent owner contact for a channel.

        Persists the owner into the Router fork''s sender_filter trigger (raw contact

        as a placeholder external_id) and returns fast; the background greeting

        resolves the real channel id and re-writes the trigger, then greets the owner.'
      operationId: set_superagent_owner_api_onboarding_ru_superagent_set_owner_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuSuperagentSetOwnerRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/ru-superagent/create-bot:
    post:
      tags:
      - Onboarding
      summary: Create Superagent Bot
      description: 'Auto-create a Telegram bot the Router controls (RU step 2, option B).


        Forks + runs the `telegram-bot-creator` system agent, which drives @BotFather

        from the workspace''s connected MTProto Telegram account and connects the new

        bot as a telegram_bot channel. The first person to /start the bot is claimed

        as owner (auto-claim in the inbound path). Returns fast; the UI polls

        /ru-superagent/bot-status.'
      operationId: create_superagent_bot_api_onboarding_ru_superagent_create_bot_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuCreateBotRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/ru-superagent/bot-status:
    get:
      tags:
      - Onboarding
      summary: Get Superagent Bot Status
      description: Poll the Telegram-bot auto-creation outcome for the onboarding UI.
      operationId: get_superagent_bot_status_api_onboarding_ru_superagent_bot_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuBotStatusResponse'
  /api/onboarding/ru-first-run/complete:
    post:
      tags:
      - Onboarding
      summary: Complete Ru First Run
      description: Complete RU-only first-run popup after messenger connect+sync.
      operationId: complete_ru_first_run_api_onboarding_ru_first_run_complete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuFirstRunCompleteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuFirstRunCompleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/ru-first-run/greeting-status:
    get:
      tags:
      - Onboarding
      summary: Get Ru First Run Greeting Status
      description: 'Poll the outcome of the first-run greeting so the onboarding UI can show

        the right next step (deep-link to the owner thread, or "write first" hint).'
      operationId: get_ru_first_run_greeting_status_api_onboarding_ru_first_run_greeting_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuGreetingStatusResponse'
  /api/onboarding/update:
    post:
      tags:
      - Onboarding
      summary: Update Onboarding
      description: 'Save onboarding progress.


        Can update product, step, goal, and/or data.

        Merges data with existing data (doesn''t replace).'
      operationId: update_onboarding_api_onboarding_update_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingUpdateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/skip:
    post:
      tags:
      - Onboarding
      summary: Skip Onboarding
      description: 'Skip onboarding for now.


        User can finish setup anytime from Settings.

        Positive, reassuring response - never make user feel bad.'
      operationId: skip_onboarding_api_onboarding_skip_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingSkipResponse'
  /api/onboarding/complete:
    post:
      tags:
      - Onboarding
      summary: Complete Onboarding
      description: 'Mark onboarding as completed.


        Called after user finishes the wizard (with or without trial activation).

        For LiveChat: Creates prompt and widget before completing.'
      operationId: complete_onboarding_api_onboarding_complete_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingCompleteResponse'
  /api/onboarding/scrape-website:
    post:
      tags:
      - Onboarding
      summary: Scrape Website Background
      description: 'Fire-and-forget website scraping.


        - Returns immediately (doesn''t wait for scrape)

        - Rate limited: max once per 30s per user

        - Skips if same URL was recently scraped'
      operationId: scrape_website_background_api_onboarding_scrape_website_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrapeWebsiteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/generate-livechat-prompt:
    post:
      tags:
      - Onboarding
      summary: Generate Livechat Prompt
      description: 'Generate AI prompt from scraped website info.


        Called from WidgetSetupStep to show user the generated prompt.

        Uses data already stored in onboarding_data.'
      operationId: generate_livechat_prompt_api_onboarding_generate_livechat_prompt_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/onboarding/generate-prompt:
    post:
      tags:
      - Onboarding
      summary: Generate Prompt
      description: 'Generate AI communication prompt using streaming.


        Creates a personalized prompt based on business description.

        Returns Server-Sent Events stream for real-time effect.'
      operationId: generate_prompt_api_onboarding_generate_prompt_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeneratePromptRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/activate-trial:
    post:
      tags:
      - Onboarding
      summary: Activate Trial
      description: 'Activate free trial for a product.


        Creates trial record without requiring Stripe payment method.

        For full Stripe integration, payment method can be added later.


        "Soft billing" - user sees "Activate free month" not "Select plan".'
      operationId: activate_trial_api_onboarding_activate_trial_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivateTrialRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateTrialResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/trials:
    get:
      tags:
      - Onboarding
      summary: Get User Trials
      description: 'Get all trials for the current user.


        Used by frontend to show trial status across products.'
      operationId: get_user_trials_api_onboarding_trials_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/onboarding/entitlements:
    get:
      tags:
      - Onboarding
      summary: Get Entitlements Endpoint
      description: 'Get user''s entitlements for all products.


        Returns trial status, subscription status, and feature access for each product.

        Frontend should call this on app load and cache the result.'
      operationId: get_entitlements_endpoint_api_onboarding_entitlements_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/onboarding/entitlements/{product}:
    get:
      tags:
      - Onboarding
      summary: Check Product Entitlement
      description: 'Check if user can access a specific product.


        Returns 200 if allowed, 403 with error details if denied.

        Use this before performing premium actions.'
      operationId: check_product_entitlement_api_onboarding_entitlements__product__get
      parameters:
      - name: product
        in: path
        required: true
        schema:
          type: string
          title: Product
      - name: action
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Action
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/onboarding/social-boost/boost:
    post:
      tags:
      - Onboarding
      summary: Onboarding Boost Post
      description: 'Boost a post during onboarding.


        Auto-joins the user to Social Boost community if not already a member,

        then adds the post to the boost pool with default engagement settings.'
      operationId: onboarding_boost_post_api_onboarding_social_boost_boost_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingBoostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OnboardingBoostRequest:
      properties:
        channel_account_id:
          type: integer
          title: Channel Account Id
        post_url:
          type: string
          title: Post Url
        post_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Post Id
      type: object
      required:
      - channel_account_id
      - post_url
      title: OnboardingBoostRequest
      description: Request to boost a post during onboarding.
    ActivateTrialRequest:
      properties:
        product:
          type: string
          enum:
          - livechat
          - social-boost
          - ai-communication
          title: Product
        plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id
      type: object
      required:
      - product
      title: ActivateTrialRequest
      description: Request to activate trial.
    RuSuperagentSetOwnerRequest:
      properties:
        channel:
          type: string
          enum:
          - telegram
          - maxru
          - whatsapp
          title: Channel
        account_id:
          type: integer
          title: Account Id
        owner_contact:
          type: string
          title: Owner Contact
      type: object
      required:
      - channel
      - account_id
      - owner_contact
      title: RuSuperagentSetOwnerRequest
      description: Set or update the superagent owner contact for a channel.
    OnboardingStatusResponse:
      properties:
        status:
          type: string
          enum:
          - pending
          - in_progress
          - skipped
          - completed
          title: Status
        product:
          anyOf:
          - type: string
            enum:
            - livechat
            - social-boost
            - ai-communication
          - type: 'null'
          title: Product
        step:
          type: integer
          title: Step
          default: 0
        goal:
          anyOf:
          - type: string
            enum:
            - get_leads
            - respond_faster
            - automate
            - boost_engagement
            - manage_inbox
            - reach_people
            - capture_leads
            - nurture
          - type: 'null'
          title: Goal
        data:
          additionalProperties: true
          type: object
          title: Data
          default: {}
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        can_skip:
          type: boolean
          title: Can Skip
          default: true
        resume_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Resume Message
        show_superagent_welcome:
          type: boolean
          title: Show Superagent Welcome
          default: false
        superagent_welcome_completed:
          type: boolean
          title: Superagent Welcome Completed
          default: false
      type: object
      required:
      - status
      title: OnboardingStatusResponse
      description: Current onboarding state.
    OnboardingUpdateRequest:
      properties:
        product:
          anyOf:
          - type: string
            enum:
            - livechat
            - social-boost
            - ai-communication
          - type: 'null'
          title: Product
        step:
          anyOf:
          - type: integer
          - type: 'null'
          title: Step
        goal:
          anyOf:
          - type: string
            enum:
            - get_leads
            - respond_faster
            - automate
            - boost_engagement
            - manage_inbox
            - reach_people
            - capture_leads
            - nurture
          - type: 'null'
          title: Goal
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
      type: object
      title: OnboardingUpdateRequest
      description: Update onboarding progress.
    GeneratePromptRequest:
      properties:
        business_description:
          type: string
          title: Business Description
        channel:
          type: string
          title: Channel
        goal:
          anyOf:
          - type: string
            enum:
            - get_leads
            - respond_faster
            - automate
            - boost_engagement
            - manage_inbox
            - reach_people
            - capture_leads
            - nurture
          - type: 'null'
          title: Goal
        tone:
          anyOf:
          - type: string
          - type: 'null'
          title: Tone
          default: professional
      type: object
      required:
      - business_description
      - channel
      title: GeneratePromptRequest
      description: Request for AI prompt generation.
    OnboardingUpdateResponse:
      properties:
        success:
          type: boolean
          title: Success
        status:
          type: string
          enum:
          - pending
          - in_progress
          - skipped
          - completed
          title: Status
        product:
          anyOf:
          - type: string
            enum:
            - livechat
            - social-boost
            - ai-communication
          - type: 'null'
          title: Product
        step:
          type: integer
          title: Step
          default: 0
      type: object
      required:
      - success
      - status
      title: OnboardingUpdateResponse
      description: Response after updating onboarding.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ScrapeWebsiteRequest:
      properties:
        website:
          type: string
          title: Website
      type: object
      required:
      - website
      title: ScrapeWebsiteRequest
      description: Request to scrape website in background.
    RuBotStatusResponse:
      properties:
        status:
          type: string
          enum:
          - creating
          - connected
          - failed
          - none
          title: Status
        bot_username:
          anyOf:
          - type: string
          - type: 'null'
          title: Bot Username
        account_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Account Id
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
        step:
          anyOf:
          - type: integer
          - type: 'null'
          title: Step
      type: object
      required:
      - status
      title: RuBotStatusResponse
    ActivateTrialResponse:
      properties:
        success:
          type: boolean
          title: Success
        trial_ends_at:
          type: string
          title: Trial Ends At
        plan_name:
          type: string
          title: Plan Name
        message:
          type: string
          title: Message
      type: object
      required:
      - success
      - trial_ends_at
      - plan_name
      - message
      title: ActivateTrialResponse
      description: Response after activating trial.
    OnboardingSkipResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
          default: No problem! You can finish setup anytime from Settings.
      type: object
      required:
      - success
      title: OnboardingSkipResponse
      description: Response after skipping onboarding.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    RuFirstRunCompleteResponse:
      properties:
        success:
          type: boolean
          title: Success
        first_greeting_status:
          type: string
          enum:
          - sent
          - failed
          - dispatched
          title: First Greeting Status
      type: object
      required:
      - success
      - first_greeting_status
      title: RuFirstRunCompleteResponse
    RuGreetingStatusResponse:
      properties:
        status:
          type: string
          enum:
          - sending
          - delivered
          - deferred
          - failed
          - none
          title: Status
        channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Channel
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        via:
          anyOf:
          - type: string
            enum:
            - sync
            - discovery
          - type: 'null'
          title: Via
      type: object
      required:
      - status
      title: RuGreetingStatusResponse
    OnboardingCompleteResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        next_url:
          type: string
          title: Next Url
        widget_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Widget Key
        embed_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Code
        prompt_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Prompt Id
      type: object
      required:
      - success
      - message
      - next_url
      title: OnboardingCompleteResponse
      description: Response after completing onboarding.
    RuFirstRunCompleteRequest:
      properties:
        channel:
          type: string
          enum:
          - telegram
          - maxru
          - whatsapp
          title: Channel
        account_id:
          type: integer
          title: Account Id
        owner_contact:
          type: string
          title: Owner Contact
          default: ''
      type: object
      required:
      - channel
      - account_id
      title: RuFirstRunCompleteRequest
      description: Complete RU first-run welcome popup flow.
    RuCreateBotRequest:
      properties:
        account_id:
          type: integer
          title: Account Id
      type: object
      required:
      - account_id
      title: RuCreateBotRequest
      description: 'Auto-create a Telegram bot that the Router controls (RU step 2, option B).


        The bot is created by the `telegram-bot-creator` agent from the workspace''s

        connected MTProto Telegram account; account_id is the channel connected in

        step 1 (context only).'