# Get widget GET https://api.elevenlabs.io/v1/convai/agents//widget Retrieve the widget configuration for an agent Reference: https://elevenlabs.io/docs/api-reference/widget/get ## Servers - `https://api.elevenlabs.io` (Production, default) - `https://api.us.elevenlabs.io` (Production US) - `https://api.eu.residency.elevenlabs.io` (Production EU) - `https://api.in.residency.elevenlabs.io` (Production India) - `https://api.sg.residency.elevenlabs.io` (Production Singapore) ## Request ### Path parameters - `agent_id` (string, required) — The id of an agent. This is returned on agent creation. ### Query parameters - `conversation_signature` (string, optional, nullable) — An expiring token that enables a websocket conversation to start. These can be generated for an agent using the /v1/convai/conversation/get\_signed\_url endpoint ## Response ### 200 Successful Response - `agent_id` (string, required) - `widget_config` (WidgetConfigResponseModel, required) ## Errors ### 422 Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### WidgetConfigResponseModel - `language` (string, required) - `variant` (enum, optional, default: full) — The variant of the widget - Allowed values: `tiny`, `compact`, `full`, `expandable` - `placement` (enum, optional, default: bottom-right) — The placement of the widget on the screen - Allowed values: `top-left`, `top`, `top-right`, `bottom-left`, `bottom`, `bottom-right` - `expandable` (enum, optional, default: never) — Whether the widget is expandable - Allowed values: `never`, `mobile`, `desktop`, `always` - `avatar` (WidgetConfigResponseModelAvatar, optional) — The avatar of the widget - `feedback_mode` (enum, optional, default: none) — The feedback mode of the widget - Allowed values: `none`, `during`, `end` - `end_feedback` (WidgetEndFeedbackConfig, optional, nullable) — Configuration for feedback collected at the end of the conversation - `bg_color` (string, optional, default: #ffffff) — The background color of the widget - `text_color` (string, optional, default: #000000) — The text color of the widget - `btn_color` (string, optional, default: #000000) — The button color of the widget - `btn_text_color` (string, optional, default: #ffffff) — The button text color of the widget - `border_color` (string, optional, default: #e1e1e1) — The border color of the widget - `focus_color` (string, optional, default: #000000) — The focus color of the widget - `border_radius` (integer, optional, nullable) — The border radius of the widget - `btn_radius` (integer, optional, nullable) — The button radius of the widget - `action_text` (string, optional, nullable) — The action text of the widget - `start_call_text` (string, optional, nullable) — The start call text of the widget - `end_call_text` (string, optional, nullable) — The end call text of the widget - `expand_text` (string, optional, nullable) — The expand text of the widget - `listening_text` (string, optional, nullable) — The text to display when the agent is listening - `speaking_text` (string, optional, nullable) — The text to display when the agent is speaking - `shareable_page_text` (string, optional, nullable) — The text to display when sharing - `shareable_page_show_terms` (boolean, optional, default: true) — Whether to show terms and conditions on the shareable page - `terms_text` (string, optional, nullable) — The text to display for terms and conditions - `terms_html` (string, optional, nullable) — The HTML to display for terms and conditions - `terms_key` (string, optional, nullable) — The key to display for terms and conditions - `show_avatar_when_collapsed` (boolean, optional, nullable, default: false) — Whether to show the avatar when the widget is collapsed - `disable_banner` (boolean, optional, default: false) — Whether to disable the banner - `override_link` (string, optional, nullable) — The override link for the widget - `markdown_link_allowed_hosts` (list of AllowlistItem, optional) — List of allowed hostnames for clickable markdown links. Use { hostname: '\*' } to allow any domain. Empty means no links are allowed. - `markdown_link_include_www` (boolean, optional, default: true) — Whether to automatically include [www](http://www). variants of allowed hosts - `markdown_link_allow_http` (boolean, optional, default: true) — Whether to allow http\:// in addition to https\:// for allowed hosts - `mic_muting_enabled` (boolean, optional, default: true) — Whether to enable mic muting - `transcript_enabled` (boolean, optional, default: true) — Whether the widget should show the conversation transcript as it goes on - `text_input_enabled` (boolean, optional, default: true) — Whether the user should be able to send text messages - `conversation_mode_toggle_enabled` (boolean, optional, default: false) — Whether to enable the conversation mode toggle in the widget - `default_expanded` (boolean, optional, default: false) — Whether the widget should be expanded by default - `always_expanded` (boolean, optional, default: false) — Whether the widget should always be expanded - `dismissible` (boolean, optional, default: false) — Whether the widget can be dismissed by the user - `show_agent_status` (boolean, optional, default: false) — Whether to show agent working/done/error status during tool use - `show_conversation_id` (boolean, optional, default: true) — Whether to show the conversation ID after disconnection. - `strip_audio_tags` (boolean, optional, default: true) — Whether to strip audio markup from messages. - `syntax_highlight_theme` (enum, optional, nullable) — Theme for code block syntax highlighting. Defaults to auto-detection by the widget when not set. - Allowed values: `light`, `dark` - `text_contents` (WidgetTextContents, optional) — Text contents of the widget - `styles` (WidgetStyles, optional) — Styles for the widget - `show_resize_button` (boolean, optional, default: true) — Whether to show the resize button - `supported_language_overrides` (list of string, optional, nullable) - `language_presets` (map from string to WidgetLanguagePresetResponse, optional) — Language presets for the widget - `text_only` (boolean, optional, default: false) — Whether the agent uses text-only mode - `supports_text_only` (boolean, optional, default: false) — Whether the agent can be switched to text-only mode - `first_message` (string, optional, nullable) - `use_rtc` (boolean, optional, nullable) — Whether to use WebRTC for conversation connections - `file_input_config` (FileInputConfig, optional) — Configuration for file upload in the widget ### ValidationError - `loc` (list of ValidationErrorLocItems, required) - `msg` (string, required) - `type` (string, required) ### WidgetConfigResponseModelAvatar The avatar of the widget ### WidgetEndFeedbackConfig - `type` (enum, optional, default: rating) — The type of feedback to collect at the end of the conversation - Allowed values: `rating` ### AllowlistItem - `hostname` (string, required) — The hostname of the allowed origin ### WidgetTextContents - `main_label` (string, optional, nullable) — Call to action displayed inside the compact and full variants. - `start_call` (string, optional, nullable) — Text and ARIA label for the start call button. - `start_chat` (string, optional, nullable) — Text and ARIA label for the start chat button (text only) - `new_call` (string, optional, nullable) — Text and ARIA label for the new call button. Displayed when the caller already finished at least one call in order ot start the next one. - `end_call` (string, optional, nullable) — Text and ARIA label for the end call button. - `mute_microphone` (string, optional, nullable) — ARIA label for the mute microphone button. - `change_language` (string, optional, nullable) — ARIA label for the change language dropdown. - `collapse` (string, optional, nullable) — ARIA label for the collapse button. - `expand` (string, optional, nullable) — ARIA label for the expand button. - `copied` (string, optional, nullable) — Text displayed when the user copies a value using the copy button. - `accept_terms` (string, optional, nullable) — Text and ARIA label for the accept terms button. - `dismiss_terms` (string, optional, nullable) — Text and ARIA label for the cancel terms button. - `listening_status` (string, optional, nullable) — Status displayed when the agent is listening. - `speaking_status` (string, optional, nullable) — Status displayed when the agent is speaking. - `connecting_status` (string, optional, nullable) — Status displayed when the agent is connecting. - `chatting_status` (string, optional, nullable) — Status displayed when the agent is chatting (text only) - `input_label` (string, optional, nullable) — ARIA label for the text message input. - `input_placeholder` (string, optional, nullable) — Placeholder text for the text message input. - `input_placeholder_text_only` (string, optional, nullable) — Placeholder text for the text message input (text only) - `input_placeholder_new_conversation` (string, optional, nullable) — Placeholder text for the text message input when starting a new conversation (text only) - `user_ended_conversation` (string, optional, nullable) — Information message displayed when the user ends the conversation. - `agent_ended_conversation` (string, optional, nullable) — Information message displayed when the agent ends the conversation. - `conversation_id` (string, optional, nullable) — Text label used next to the conversation ID. - `error_occurred` (string, optional, nullable) — Text label used when an error occurs. - `copy_id` (string, optional, nullable) — Text and ARIA label used for the copy ID button. - `initiate_feedback` (string, optional, nullable) — Text displayed to prompt the user for feedback. - `request_follow_up_feedback` (string, optional, nullable) — Text displayed to request additional feedback details. - `thanks_for_feedback` (string, optional, nullable) — Text displayed to thank the user for providing feedback. - `thanks_for_feedback_details` (string, optional, nullable) — Additional text displayed explaining the value of user feedback. - `follow_up_feedback_placeholder` (string, optional, nullable) — Placeholder text for the follow-up feedback input field. - `submit` (string, optional, nullable) — Text and ARIA label for the submit button. - `go_back` (string, optional, nullable) — Text and ARIA label for the go back button. - `send_message` (string, optional, nullable) — Text and ARIA label for the send message button. - `text_mode` (string, optional, nullable) — Text and ARIA label for the switch to text mode button. - `voice_mode` (string, optional, nullable) — Text and ARIA label for the switch to voice mode button. - `switched_to_text_mode` (string, optional, nullable) — Toast notification displayed when switching to text mode. - `switched_to_voice_mode` (string, optional, nullable) — Toast notification displayed when switching to voice mode. - `copy` (string, optional, nullable) — Text and ARIA label for the copy button. - `download` (string, optional, nullable) — Text and ARIA label for the download button. - `wrap` (string, optional, nullable) — Text and ARIA label for the wrap toggle button. - `agent_working` (string, optional, nullable) — Status text displayed when the agent is processing a tool call. - `agent_done` (string, optional, nullable) — Status text displayed when the agent finishes processing a tool call. - `agent_error` (string, optional, nullable) — Status text displayed when the agent encounters an error during a tool call. - `attach_file` (string, optional, nullable) — Text and ARIA label for the attach file button. - `remove_file` (string, optional, nullable) — ARIA label for the remove file button. - `file_upload_error` (string, optional, nullable) — Error message displayed when a file fails to upload. - `file_type_unsupported` (string, optional, nullable) — Error message displayed when an unsupported file type is selected. Followed by the list of accepted types. - `file_too_large` (string, optional, nullable) — Error message displayed when a file exceeds the maximum size limit. - `file_limit_reached` (string, optional, nullable) — Error message displayed when the maximum number of files for a conversation is reached. - `typing_indicator` (string, optional, nullable) — Status text displayed while the agent is typing. ### WidgetStyles - `base` (string, optional, nullable) — The base background color. - `base_hover` (string, optional, nullable) — The color of the base background when hovered. - `base_active` (string, optional, nullable) — The color of the base background when active (clicked). - `base_border` (string, optional, nullable) — The color of the border against the base background. - `base_subtle` (string, optional, nullable) — The color of subtle text against the base background. - `base_primary` (string, optional, nullable) — The color of primary text against the base background. - `base_error` (string, optional, nullable) — The color of error text against the base background. - `accent` (string, optional, nullable) — The accent background color. - `accent_hover` (string, optional, nullable) — The color of the accent background when hovered. - `accent_active` (string, optional, nullable) — The color of the accent background when active (clicked). - `accent_border` (string, optional, nullable) — The color of the border against the accent background. - `accent_subtle` (string, optional, nullable) — The color of subtle text against the accent background. - `accent_primary` (string, optional, nullable) — The color of primary text against the accent background. - `overlay_padding` (double, optional, nullable) — The padding around the edges of the viewport. - `button_radius` (double, optional, nullable) — The radius of the buttons. - `input_radius` (double, optional, nullable) — The radius of the input fields. - `bubble_radius` (double, optional, nullable) — The radius of the chat bubbles. - `sheet_radius` (double, optional, nullable) — The default radius of sheets. - `compact_sheet_radius` (double, optional, nullable) — The radius of the sheet in compact mode. - `dropdown_sheet_radius` (double, optional, nullable) — The radius of the dropdown sheet. ### WidgetLanguagePresetResponse - `first_message` (string, optional, nullable) - `text_contents` (WidgetTextContents, optional, nullable) — The text contents for the selected language - `terms_text` (string, optional, nullable) — The text to display for terms and conditions in this language - `terms_html` (string, optional, nullable) — The HTML to display for terms and conditions in this language - `terms_key` (string, optional, nullable) — The key to display for terms and conditions in this language ### FileInputConfig - `enabled` (boolean, optional, default: true) — When enabled, users may attach images or PDFs in chat when the LLM supports multimodal input. - `max_files_in_memory` (integer, optional, default: 10) — Number of most-recent files kept in memory during a conversation. Older files are summarized and their bytes freed. - `max_files_per_conversation` (integer, optional, default: 10) — Total files a user can upload in one conversation. Uploads are billed per file. Use -1 for no limit, or a value >= max\_files\_in\_memory. ### ValidationErrorLocItems ### OrbAvatar - `type` ("orb", optional, default: orb) — The type of the avatar - `color_1` (string, optional, default: #2792dc) — The first color of the avatar - `color_2` (string, optional, default: #9ce6e6) — The second color of the avatar ### URLAvatar - `type` ("url", optional, default: url) — The type of the avatar - `custom_url` (string, optional, default: ) — The custom URL of the avatar ### ImageAvatar - `type` ("image", optional, default: image) — The type of the avatar - `url` (string, optional, default: ) — The URL of the avatar ## Examples **Response** ```json { "agent_id": "string", "widget_config": { "language": "en", "supported_language_overrides": [ "es", "fr" ], "language_presets": {}, "text_only": false, "supports_text_only": true, "first_message": "Hello! How can I help you today?", "use_rtc": false, "file_input_config": { "enabled": false, "max_files_in_memory": 10, "max_files_per_conversation": 10 } } } ``` **SDK Code** ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; async function main() { const client = new ElevenLabsClient(); await client.conversationalAi.agents.widget.get("agent_3701k3ttaq12ewp8b7qv5rfyszkz", {}); } main(); ``` ```python from elevenlabs import ElevenLabs client = ElevenLabs() client.conversational_ai.agents.widget.get( agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz", ) ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget" req, _ := http.NewRequest("GET", url, nil) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget") .asString(); ``` ```php request('GET', 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget'); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget"); var request = new RestRequest(Method.GET); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ## Related pages - [Administration](./administration-index.md) - [API reference](./api-reference-index.md) - [Changelog](./changelog-index.md) - [ElevenAgents](./elevenagents-index.md) - [ElevenAPI](./elevenapi-index.md) - [ElevenCreative](./elevencreative-index.md) - [ElevenLabs Documentation Docs](../index.md) - [General Troubleshooting FAQ](./troubleshooting-index.md) - [General Website FAQ](./website-index.md) - [Help Center](./help-center-2-index.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.