dialogbrain-com Widgets API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Widgets API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: Widgets
paths:
  /api/v1/widgets:
    post:
      tags:
      - Widgets
      summary: Create Widget
      description: 'Create a widget and return it, embed key included.


        Requires Idempotency-Key: a retried request with the same key returns the widget created the first time instead of a second one. A widget is its own channel, so it has its own conversations and, with allow_voice, its own voice pickup.'
      operationId: create_widget_api_v1_widgets_post
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__v1___tool_schema__WidgetCreateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Widgets
      summary: List Widgets
      description: List the widgets in the workspace. Pass active_only=true to skip the disabled ones.
      operationId: list_widgets_api_v1_widgets_get
      parameters:
      - name: active_only
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Active Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/widgets/{widget_id}:
    get:
      tags:
      - Widgets
      summary: Get Widget
      description: Fetch one widget, with its theme, channel and voice settings.
      operationId: get_widget_api_v1_widgets__widget_id__get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: integer
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: No widget with this id in the workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Widgets
      summary: Update Widget
      description: Update a widget. Fields you leave out keep their current value.
      operationId: update_widget_api_v1_widgets__widget_id__patch
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: integer
          title: Widget Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__v1___tool_schema__WidgetUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: No widget with this id in the workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Widgets
      summary: Delete Widget
      description: 'Delete a widget. This also deletes every conversation it produced and their messages, and cannot be undone.


        A widget is its own channel, so removing it removes the channel the conversations hang from. Export anything you need first; the embed code stops working immediately.'
      operationId: delete_widget_api_v1_widgets__widget_id__delete
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: integer
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: No widget with this id in the workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/widgets/{widget_id}/embed-code:
    get:
      tags:
      - Widgets
      summary: Get Widget Embed Code
      description: Return the script tag to paste on the site the widget belongs to.
      operationId: get_widget_embed_code_api_v1_widgets__widget_id__embed_code_get
      parameters:
      - name: widget_id
        in: path
        required: true
        schema:
          type: integer
          title: Widget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '404':
          description: No widget with this id in the workspace.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    anyOf:
                    - type: string
                    - type: array
                      items: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    src__api__v1___tool_schema__WidgetUpdateRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: New name for the widget
        auto_reply_mode:
          anyOf:
          - type: string
            enum:
            - auto
            - draft
          - type: 'null'
          title: Auto Reply Mode
          description: 'Auto-reply mode: ''draft'' or ''auto''. OMIT to leave the auto-reply mode unchanged.'
        primary_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Color
          description: Primary color for widget theme (hex, e.g., '#2563eb'). Paints the header, the visitor's message bubbles and the send button — and the launcher bubble too unless launcher_color overrides it.
        launcher_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Launcher Color
          description: Hex color for the closed launcher bubble (e.g., '#ffffff'). Override this to use a different color than primary_color. Clear it to revert to primary_color.
        position:
          anyOf:
          - type: string
            enum:
            - bottom-right
            - bottom-left
          - type: 'null'
          title: Position
          description: Widget position on screen. OMIT to leave the position unchanged.
        header_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Header Title
          description: Title shown in chat header
        header_subtitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Header Subtitle
          description: Subtitle shown in chat header
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
          description: Enable or disable the widget. OMIT to leave the active flag unchanged.
        allowed_domains:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Allowed Domains
          description: List of allowed domains for the widget
        calendly_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Calendly Url
          description: Booking URL for calendar action (e.g., 'https://calendly.com/yourname')
        contact_form_fields:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Contact Form Fields
          description: Fields to collect in contact form (e.g., ['name', 'email', 'phone'])
        require_identification:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Require Identification
          description: Require visitor to identify before chatting. OMIT to leave the identification policy unchanged.
        identification_fields:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Identification Fields
          description: Fields to require for visitor identification (e.g., ['name', 'email'])
        website_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Website Url
          description: Website URL for product/site search integration
        enable_search_action:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Search Action
          description: Enable or disable the search action button. OMIT to leave this flag unchanged.
        enable_form_action:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Form Action
          description: Enable or disable the contact form action button. OMIT to leave this flag unchanged.
        enable_calendar_action:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Calendar Action
          description: Enable or disable the calendar booking action button. OMIT to leave this flag unchanged.
        greeting_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Greeting Text
          description: Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?')
        returning_greeting_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Returning Greeting Text
          description: Greeting for returning visitors who already have chat history (e.g., 'Welcome back! How can I help you today?'). Falls back to greeting_text if not set.
        greeting_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Greeting Enabled
          description: Enable or disable the proactive greeting. OMIT to leave this flag unchanged.
        greeting_delay_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Greeting Delay Seconds
          description: 'Delay in seconds before the proactive greeting appears (0–300). 0 = send immediately on page load. Default: 30.'
        greeting_behavior:
          anyOf:
          - type: string
            enum:
            - notification
            - auto_open
            - on_open
          - type: 'null'
          title: Greeting Behavior
          description: notification = show badge after delay; auto_open = open widget automatically after delay; on_open = greet only when visitor manually opens. OMIT to leave the greeting behavior unchanged.
        color_scheme:
          anyOf:
          - type: string
            enum:
            - light
            - dark
            - auto
          - type: 'null'
          title: Color Scheme
          description: Widget color scheme. 'auto' follows the visitor's OS dark/light mode preference. OMIT to leave the color scheme unchanged.
        show_visitor_history:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Show Visitor History
          description: Show full chat history to returning visitors. OMIT to leave this flag unchanged.
        allow_voice:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Voice
          description: 'Master switch for voice on this widget — set true to show the mic and let visitors talk to the agent. Everything else voice-related (greeting, button label, STT/TTS from the agent''s own config) is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave the setting unchanged.'
        max_voice_duration_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Voice Duration Seconds
          description: Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged.
        voice_greeting:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Greeting
          description: Spoken opening line when a visitor starts a voice call through this widget. Played via TTS before the AI model runs. Empty string disables the greeting. Requires allow_voice=true to be audible.
        display_mode:
          anyOf:
          - type: string
            enum:
            - chat
            - voice_only
            - headless
          - type: 'null'
          title: Display Mode
          description: 'How the widget renders: ''chat'' (default) for the full panel with a microphone, ''voice_only'' for a mic-only bubble that starts a call, ''headless'' for no interface at all, driven through window.DialogBrain.'
        voice_button_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Button Label
          description: Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if not set.
      type: object
      title: WidgetUpdateRequest
    src__api__v1___tool_schema__WidgetCreateRequest:
      properties:
        name:
          type: string
          title: Name
          description: Name for the widget (e.g., 'Website Chat', 'Support Widget')
        auto_reply_mode:
          anyOf:
          - type: string
            enum:
            - auto
            - draft
          - type: 'null'
          title: Auto Reply Mode
          description: 'Auto-reply mode: ''draft'' (review before sending) or ''auto'' (send immediately)'
          default: draft
        primary_color:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Color
          description: Primary color for widget theme (hex, e.g., '#2563eb')
          default: '#2563eb'
        position:
          anyOf:
          - type: string
            enum:
            - bottom-right
            - bottom-left
          - type: 'null'
          title: Position
          description: Widget position on screen
          default: bottom-right
        header_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Header Title
          description: Title shown in chat header
          default: Chat with us
        display_mode:
          anyOf:
          - type: string
            enum:
            - chat
            - voice_only
            - headless
          - type: 'null'
          title: Display Mode
          description: 'How the widget renders: ''chat'' (default) for the full panel with a microphone, ''voice_only'' for a mic-only bubble that starts a call, ''headless'' for no interface at all, driven through window.DialogBrain.'
          default: chat
        allow_voice:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Voice
          description: 'Master switch for voice — set true to show the mic so visitors can talk to the agent. Everything else voice-related is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave voice off (the default).'
        voice_button_label:
          anyOf:
          - type: string
          - type: 'null'
          title: Voice Button Label
          description: Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if omitted.
      type: object
      required:
      - name
      title: WidgetCreateRequest