> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Get widget

> Retrieve the widget configuration for an agent



## OpenAPI

````yaml https://api.threetone.in/openapi.json get /v1/convai/agents/{agent_id}/widget
openapi: 3.1.0
info:
  title: Threetone API Documentation
  version: 1.0.0
servers:
  - url: https://api.threetone.in
    description: Production
security: []
paths:
  /v1/convai/agents/{agent_id}/widget:
    get:
      tags:
        - Widget
      summary: Get widget
      description: Retrieve the widget configuration for an agent
      operationId: get_agent_widget_route
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            description: The id of an agent. This is returned on agent creation.
            examples:
              - agent_3701k3ttaq12ewp8b7qv5rfyszkz
            title: Agent Id
          description: The id of an agent. This is returned on agent creation.
        - name: conversation_signature
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              An expiring token that enables a conversation to start. Reserved
              for future use.
            title: Conversation Signature
          description: >-
            An expiring token that enables a conversation to start. Reserved for
            future use.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentEmbedResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    GetAgentEmbedResponseModel:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: The ID of the agent
        widget_config:
          $ref: '#/components/schemas/WidgetConfigResponseModel'
          description: The widget configuration for the agent
      type: object
      required:
        - agent_id
        - widget_config
      title: GetAgentEmbedResponseModel
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WidgetConfigResponseModel:
      properties:
        variant:
          $ref: '#/components/schemas/EmbedVariant'
          description: The variant of the widget
          default: full
        placement:
          $ref: '#/components/schemas/WidgetPlacement'
          description: The placement of the widget on the screen
          default: bottom-right
        expandable:
          $ref: '#/components/schemas/WidgetExpandable'
          description: Whether the widget is expandable
          default: never
        default_expanded:
          type: boolean
          title: Default Expanded
          description: Widget expanded by default
          default: false
        always_expanded:
          type: boolean
          title: Always Expanded
          description: Widget always expanded
          default: false
        dismissible:
          type: boolean
          title: Dismissible
          description: Whether the user can dismiss the widget
          default: false
        show_agent_status:
          type: boolean
          title: Show Agent Status
          description: Show agent working/done/error status during tool use
          default: false
        show_conversation_id:
          type: boolean
          title: Show Conversation Id
          description: Show conversation ID after disconnection
          default: true
        strip_audio_tags:
          type: boolean
          title: Strip Audio Tags
          description: Strip audio markup from assistant messages
          default: true
        syntax_highlight_theme:
          anyOf:
            - $ref: '#/components/schemas/SyntaxHighlightTheme'
            - type: 'null'
          description: Syntax highlighting theme for code blocks
        show_avatar_when_collapsed:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Show Avatar When Collapsed
          description: Show avatar when widget is collapsed
          default: false
        avatar:
          anyOf:
            - $ref: '#/components/schemas/OrbAvatar'
            - $ref: '#/components/schemas/URLAvatar'
            - $ref: '#/components/schemas/ImageAvatar'
            - type: 'null'
          title: Avatar
          description: The avatar of the widget
        custom_avatar_path:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Avatar Path
          description: Custom avatar path (set via POST /avatar)
        feedback_mode:
          $ref: '#/components/schemas/WidgetFeedbackMode'
          description: The feedback mode of the widget
          default: none
        end_feedback:
          anyOf:
            - $ref: '#/components/schemas/WidgetEndFeedbackConfig'
            - type: 'null'
          description: Configuration for feedback at end of conversation
        bg_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Bg Color
          description: Background color of the widget
        text_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Text Color
          description: Primary text color
        btn_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Btn Color
          description: Primary button color
        btn_text_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Btn Text Color
          description: Button label color
        border_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Border Color
          description: Border color
        focus_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Focus Color
          description: Focus ring / outline color
        border_radius:
          anyOf:
            - type: integer
            - type: 'null'
          title: Border Radius
          description: Widget border radius in pixels
        btn_radius:
          anyOf:
            - type: integer
            - type: 'null'
          title: Btn Radius
          description: Button border radius in pixels
        action_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Action Text
          description: Primary action label text
        start_call_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Call Text
          description: Start call label text
        end_call_text:
          anyOf:
            - type: string
            - type: 'null'
          title: End Call Text
          description: End call label text
        expand_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Expand Text
          description: Expand control label text
        listening_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Listening Text
          description: Listening state label text
        speaking_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Speaking Text
          description: Speaking state label text
        mic_muting_enabled:
          type: boolean
          title: Mic Muting Enabled
          description: Enable mic muting
          default: false
        transcript_enabled:
          type: boolean
          title: Transcript Enabled
          description: Show conversation transcript
          default: false
        text_input_enabled:
          type: boolean
          title: Text Input Enabled
          description: Enable text message input
          default: true
        conversation_mode_toggle_enabled:
          type: boolean
          title: Conversation Mode Toggle Enabled
          description: Enable conversation mode toggle
          default: false
        language_selector:
          type: boolean
          title: Language Selector
          description: Show language selector
          default: false
        supports_text_only:
          type: boolean
          title: Supports Text Only
          description: Support text-only mode
          default: true
        shareable_page_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Shareable Page Text
          description: Text for shareable page
        shareable_page_show_terms:
          type: boolean
          title: Shareable Page Show Terms
          description: Show terms on shareable page
          default: true
        terms_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Text
          description: Terms and conditions text (Markdown)
        terms_html:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Html
          description: Terms and conditions HTML (auto-generated from terms_text)
        terms_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Key
          description: LocalStorage key to remember acceptance
        markdown_link_allowed_hosts:
          items:
            $ref: '#/components/schemas/AllowlistItem'
          type: array
          title: Markdown Link Allowed Hosts
          description: Allowed hostnames for clickable markdown links
        markdown_link_include_www:
          type: boolean
          title: Markdown Link Include Www
          description: Include www. variants of allowed hosts
          default: true
        markdown_link_allow_http:
          type: boolean
          title: Markdown Link Allow Http
          description: Allow http:// URLs
          default: true
        disable_banner:
          type: boolean
          title: Disable Banner
          description: Whether to disable the banner
          default: false
        override_link:
          anyOf:
            - type: string
            - type: 'null'
          title: Override Link
          description: Override link for the widget
        text_contents:
          anyOf:
            - $ref: '#/components/schemas/WidgetTextContents'
            - type: 'null'
          description: All text contents shown in the widget
        styles:
          anyOf:
            - $ref: '#/components/schemas/WidgetStyles'
            - type: 'null'
          description: Semantic color and radius styles for the widget
        language_presets:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/WidgetLanguagePresetResponse'
              type: object
            - type: 'null'
          title: Language Presets
          description: Language presets for the widget
        language:
          type: string
          title: Language
          description: >-
            Primary ISO 639-1 language code (e.g. en, hi, kn); short codes, not
            hi-IN-style regions.
          default: en
        supported_language_overrides:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Supported Language Overrides
          description: Language codes that override the supported languages
        text_only:
          type: boolean
          title: Text Only
          description: Whether the agent uses text-only mode
          default: false
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
          description: First message the agent sends
        use_rtc:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Rtc
          description: Whether to use WebRTC for conversation connections
      type: object
      title: WidgetConfigResponseModel
      description: >-
        Response model for the widget endpoint. Extends WidgetConfigInput with

        agent-level fields pulled from conversation_config at response time.

        These fields are NOT stored in platform_settings.widget — they come from

        the agent's conversation_config and are merged when building the
        response.
    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
    EmbedVariant:
      type: string
      enum:
        - tiny
        - compact
        - full
        - expandable
      title: EmbedVariant
    WidgetPlacement:
      type: string
      enum:
        - top-left
        - top
        - top-right
        - bottom-left
        - bottom
        - bottom-right
      title: WidgetPlacement
    WidgetExpandable:
      type: string
      enum:
        - never
        - mobile
        - desktop
        - always
      title: WidgetExpandable
    SyntaxHighlightTheme:
      type: string
      enum:
        - light
        - dark
      title: SyntaxHighlightTheme
    OrbAvatar:
      properties:
        type:
          type: string
          title: Type
          description: Avatar type
          default: orb
        color_1:
          type: string
          title: Color 1
          description: Primary orb color
          default: '#2792dc'
        color_2:
          type: string
          title: Color 2
          description: Secondary orb color
          default: '#9ce6e6'
      type: object
      title: OrbAvatar
    URLAvatar:
      properties:
        type:
          type: string
          title: Type
          description: Avatar type
          default: url
        custom_url:
          type: string
          title: Custom Url
          description: The custom URL of the avatar
          default: ''
      type: object
      title: URLAvatar
    ImageAvatar:
      properties:
        type:
          type: string
          title: Type
          description: Avatar type
          default: image
        url:
          type: string
          title: Url
          description: URL to the avatar image
          default: ''
      type: object
      title: ImageAvatar
    WidgetFeedbackMode:
      type: string
      enum:
        - none
        - during
        - end
      title: WidgetFeedbackMode
    WidgetEndFeedbackConfig:
      properties:
        type:
          $ref: '#/components/schemas/WidgetEndFeedbackType'
          description: The type of feedback to collect at the end of the conversation
          default: rating
      type: object
      title: WidgetEndFeedbackConfig
    AllowlistItem:
      properties:
        hostname:
          type: string
          title: Hostname
          description: The hostname of the allowed origin
      type: object
      required:
        - hostname
      title: AllowlistItem
    WidgetTextContents:
      properties:
        main_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Label
          description: Call to action displayed inside the compact and full variants.
        start_call:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Call
          description: Text and ARIA label for the start call button.
        start_chat:
          anyOf:
            - type: string
            - type: 'null'
          title: Start Chat
          description: Text and ARIA label for the start chat button (text only)
        new_call:
          anyOf:
            - type: string
            - type: 'null'
          title: New Call
          description: >-
            Text and ARIA label for the new call button. Displayed when the
            caller already finished at least one call.
        end_call:
          anyOf:
            - type: string
            - type: 'null'
          title: End Call
          description: Text and ARIA label for the end call button.
        mute_microphone:
          anyOf:
            - type: string
            - type: 'null'
          title: Mute Microphone
          description: ARIA label for the mute microphone button.
        change_language:
          anyOf:
            - type: string
            - type: 'null'
          title: Change Language
          description: ARIA label for the change language dropdown.
        collapse:
          anyOf:
            - type: string
            - type: 'null'
          title: Collapse
          description: ARIA label for the collapse button.
        expand:
          anyOf:
            - type: string
            - type: 'null'
          title: Expand
          description: ARIA label for the expand button.
        copied:
          anyOf:
            - type: string
            - type: 'null'
          title: Copied
          description: Text displayed when the user copies a value using the copy button.
        accept_terms:
          anyOf:
            - type: string
            - type: 'null'
          title: Accept Terms
          description: Text and ARIA label for the accept terms button.
        dismiss_terms:
          anyOf:
            - type: string
            - type: 'null'
          title: Dismiss Terms
          description: Text and ARIA label for the cancel terms button.
        listening_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Listening Status
          description: Status displayed when the agent is listening.
        speaking_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Speaking Status
          description: Status displayed when the agent is speaking.
        connecting_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Connecting Status
          description: Status displayed when the agent is connecting.
        chatting_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Chatting Status
          description: Status displayed when the agent is chatting (text only)
        input_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Input Label
          description: ARIA label for the text message input.
        input_placeholder:
          anyOf:
            - type: string
            - type: 'null'
          title: Input Placeholder
          description: Placeholder text for the text message input.
        input_placeholder_text_only:
          anyOf:
            - type: string
            - type: 'null'
          title: Input Placeholder Text Only
          description: Placeholder text for the text message input (text only)
        input_placeholder_new_conversation:
          anyOf:
            - type: string
            - type: 'null'
          title: Input Placeholder New Conversation
          description: >-
            Placeholder text for the text message input when starting a new
            conversation (text only)
        user_ended_conversation:
          anyOf:
            - type: string
            - type: 'null'
          title: User Ended Conversation
          description: Information message displayed when the user ends the conversation.
        agent_ended_conversation:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Ended Conversation
          description: Information message displayed when the agent ends the conversation.
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Conversation Id
          description: Text label used next to the conversation ID.
        error_occurred:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Occurred
          description: Text label used when an error occurs.
        copy_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Copy Id
          description: Text and ARIA label used for the copy ID button.
        initiate_feedback:
          anyOf:
            - type: string
            - type: 'null'
          title: Initiate Feedback
          description: Text displayed to prompt the user for feedback.
        request_follow_up_feedback:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Follow Up Feedback
          description: Text displayed to request additional feedback details.
        thanks_for_feedback:
          anyOf:
            - type: string
            - type: 'null'
          title: Thanks For Feedback
          description: Text displayed to thank the user for providing feedback.
        thanks_for_feedback_details:
          anyOf:
            - type: string
            - type: 'null'
          title: Thanks For Feedback Details
          description: Additional text displayed explaining the value of user feedback.
        follow_up_feedback_placeholder:
          anyOf:
            - type: string
            - type: 'null'
          title: Follow Up Feedback Placeholder
          description: Placeholder text for the follow-up feedback input field.
        submit:
          anyOf:
            - type: string
            - type: 'null'
          title: Submit
          description: Text and ARIA label for the submit button.
        go_back:
          anyOf:
            - type: string
            - type: 'null'
          title: Go Back
          description: Text and ARIA label for the go back button.
        send_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Send Message
          description: Text and ARIA label for the send message button.
        text_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Text Mode
          description: Text and ARIA label for the switch to text mode button.
        voice_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Mode
          description: Text and ARIA label for the switch to voice mode button.
        switched_to_text_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Switched To Text Mode
          description: Toast notification displayed when switching to text mode.
        switched_to_voice_mode:
          anyOf:
            - type: string
            - type: 'null'
          title: Switched To Voice Mode
          description: Toast notification displayed when switching to voice mode.
        copy:
          anyOf:
            - type: string
            - type: 'null'
          title: Copy
          description: Text and ARIA label for the copy button.
        download:
          anyOf:
            - type: string
            - type: 'null'
          title: Download
          description: Text and ARIA label for the download button.
        wrap:
          anyOf:
            - type: string
            - type: 'null'
          title: Wrap
          description: Text and ARIA label for the wrap toggle button.
        agent_working:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Working
          description: Status text displayed when the agent is processing a tool call.
        agent_done:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Done
          description: >-
            Status text displayed when the agent finishes processing a tool
            call.
        agent_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Error
          description: >-
            Status text displayed when the agent encounters an error during a
            tool call.
      type: object
      title: WidgetTextContents
    WidgetStyles:
      properties:
        base:
          anyOf:
            - type: string
            - type: 'null'
          title: Base
          description: The base background color.
        base_hover:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Hover
          description: The color of the base background when hovered.
        base_active:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Active
          description: The color of the base background when active (clicked).
        base_border:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Border
          description: The color of the border against the base background.
        base_subtle:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Subtle
          description: The color of subtle text against the base background.
        base_primary:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Primary
          description: The color of primary text against the base background.
        base_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Error
          description: The color of error text against the base background.
        accent:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent
          description: The accent background color.
        accent_hover:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent Hover
          description: The color of the accent background when hovered.
        accent_active:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent Active
          description: The color of the accent background when active (clicked).
        accent_border:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent Border
          description: The color of the border against the accent background.
        accent_subtle:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent Subtle
          description: The color of subtle text against the accent background.
        accent_primary:
          anyOf:
            - type: string
            - type: 'null'
          title: Accent Primary
          description: The color of primary text against the accent background.
        overlay_padding:
          anyOf:
            - type: number
            - type: 'null'
          title: Overlay Padding
          description: The padding around the edges of the viewport.
        button_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Button Radius
          description: The radius of the buttons.
        input_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Input Radius
          description: The radius of the input fields.
        bubble_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Bubble Radius
          description: The radius of the chat bubbles.
        sheet_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Sheet Radius
          description: The default radius of sheets.
        compact_sheet_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Compact Sheet Radius
          description: The radius of the sheet in compact mode.
        dropdown_sheet_radius:
          anyOf:
            - type: number
            - type: 'null'
          title: Dropdown Sheet Radius
          description: The radius of the dropdown sheet.
      type: object
      title: WidgetStyles
    WidgetLanguagePresetResponse:
      properties:
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
          description: First message in this language
        text_contents:
          anyOf:
            - $ref: '#/components/schemas/WidgetTextContents'
            - type: 'null'
          description: The text contents for the selected language
        terms_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Text
          description: The text to display for terms and conditions in this language
        terms_html:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Html
          description: The HTML to display for terms and conditions in this language
        terms_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Terms Key
          description: The key to display for terms and conditions in this language
        terms_translation:
          anyOf:
            - $ref: '#/components/schemas/WidgetTermsTranslation'
            - type: 'null'
          description: The translation cache for the terms in this language
      type: object
      title: WidgetLanguagePresetResponse
    WidgetEndFeedbackType:
      type: string
      enum:
        - rating
      title: WidgetEndFeedbackType
    WidgetTermsTranslation:
      properties:
        source_hash:
          type: string
          title: Source Hash
          description: Hash of the source terms text
        text:
          type: string
          title: Text
          description: Translated terms text
      type: object
      required:
        - source_hash
        - text
      title: WidgetTermsTranslation

````