> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 获取智能体小组件配置

GET https://api.elevenlabs.io/v1/convai/agents/{agent_id}/widget

获取智能体的小部件配置。

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) — 智能体 ID。创建智能体时返回此值。

### Query parameters

- `conversation_signature` (string, optional, nullable) — 用于启动 websocket 对话的临时令牌。可通过 /v1/convai/conversation/get_signed_url 端点为智能体生成。

## Response

### 200

成功响应

- `agent_id` (string, required)
- `widget_config` (WidgetConfigResponseModel, required)

## Errors

### 422 Unprocessable Entity Error

验证错误。

- `detail` (list of ValidationError, optional)

## Types

### WidgetConfigResponseModel

- `language` (string, required)
- `variant` (enum, optional, default: full) — 组件变体
  - Allowed values: `tiny`, `compact`, `full`, `expandable`
- `placement` (enum, optional, default: bottom-right) — 小组件在屏幕上的位置
  - Allowed values: `top-left`, `top`, `top-right`, `bottom-left`, `bottom`, `bottom-right`
- `expandable` (enum, optional, default: never) — 小组件是否可展开
  - Allowed values: `never`, `mobile`, `desktop`, `always`
- `avatar` (WidgetConfigResponseModelAvatar, optional) — 小组件的头像
- `feedback_mode` (enum, optional, default: none) — 组件的反馈模式
  - 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) — 小组件的背景色
- `text_color` (string, optional, default: #000000) — 组件的文本颜色
- `btn_color` (string, optional, default: #000000) — 小组件的按钮颜色
- `btn_text_color` (string, optional, default: #ffffff) — 小组件的按钮文本颜色
- `border_color` (string, optional, default: #e1e1e1) — 小组件的边框颜色
- `focus_color` (string, optional, default: #000000) — 组件的焦点颜色
- `border_radius` (integer, optional, nullable) — 小组件的边框圆角
- `btn_radius` (integer, optional, nullable) — 小组件的按钮圆角
- `action_text` (string, optional, nullable) — 小组件的操作文本
- `start_call_text` (string, optional, nullable) — 小部件的开始通话文本
- `end_call_text` (string, optional, nullable) — 组件的结束通话文本
- `expand_text` (string, optional, nullable) — 组件的展开文本
- `listening_text` (string, optional, nullable) — 智能体正在聆听时显示的文本
- `speaking_text` (string, optional, nullable) — 智能体正在说话时显示的文本
- `shareable_page_text` (string, optional, nullable) — 分享时显示的文本
- `shareable_page_show_terms` (boolean, optional, default: true) — 是否在可分享页面显示条款和条件
- `terms_text` (string, optional, nullable) — 要显示的条款与条件文本
- `terms_html` (string, optional, nullable) — 要显示的条款和条件 HTML
- `terms_key` (string, optional, nullable) — 用于显示条款与条件的键
- `show_avatar_when_collapsed` (boolean, optional, nullable, default: false) — 小组件折叠时是否显示头像
- `disable_banner` (boolean, optional, default: false) — 是否禁用横幅
- `override_link` (string, optional, nullable) — 小组件的覆盖链接
- `markdown_link_allowed_hosts` (list of AllowlistItem, optional) — 允许用于可点击 Markdown 链接的主机名列表。使用 \{ hostname: '\*' } 可允许任何域名。留空表示不允许任何链接。
- `markdown_link_include_www` (boolean, optional, default: true) — 是否自动包含允许主机的 www. 变体
- `markdown_link_allow_http` (boolean, optional, default: true) — 允许的主机是否除 https:// 外也允许 http://
- `mic_muting_enabled` (boolean, optional, default: true) — 是否启用麦克风静音
- `transcript_enabled` (boolean, optional, default: true) — 小组件是否应在对话进行时显示转录文本
- `text_input_enabled` (boolean, optional, default: true) — 用户是否应能够发送文本消息
- `conversation_mode_toggle_enabled` (boolean, optional, default: false) — 是否在小组件中启用会话模式切换
- `default_expanded` (boolean, optional, default: false) — 小组件是否应默认展开
- `always_expanded` (boolean, optional, default: false) — 小组件是否应始终展开
- `dismissible` (boolean, optional, default: false) — 用户是否可关闭小组件
- `show_agent_status` (boolean, optional, default: false) — 是否在使用工具时显示智能体的处理中、完成和错误状态
- `show_conversation_id` (boolean, optional, default: true) — 断开连接后是否显示会话 ID。
- `strip_audio_tags` (boolean, optional, default: true) — 是否从消息中移除音频标记。
- `syntax_highlight_theme` (enum, optional, nullable) — 代码块语法高亮主题。未设置时默认由小组件自动检测。
  - Allowed values: `light`, `dark`
- `text_contents` (WidgetTextContents, optional) — 小组件的文本内容
- `styles` (WidgetStyles, optional) — 组件样式
- `show_resize_button` (boolean, optional, default: true) — 是否显示调整大小按钮
- `end_confirmation_enabled` (boolean, optional, default: false) — 结束聊天或通话前是否要求用户确认
- `supported_language_overrides` (list of string, optional, nullable)
- `language_presets` (map from string to WidgetLanguagePresetResponse, optional) — 小组件语言预设
- `text_only` (boolean, optional, default: false) — 智能体是否使用纯文本模式
- `supports_text_only` (boolean, optional, default: false) — 智能体是否可切换为纯文本模式
- `first_message` (string, optional, nullable)
- `use_rtc` (boolean, optional, nullable) — 是否使用 WebRTC 建立会话连接
- `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

小组件的头像

- OrbAvatar: OrbAvatar
- URLAvatar: URLAvatar
- ImageAvatar: ImageAvatar

### WidgetEndFeedbackConfig

- `type` (enum, optional, default: rating) — 在对话结束时收集的反馈类型
  - Allowed values: `rating`

### AllowlistItem

- `hostname` (string, required) — 允许来源的主机名

### WidgetTextContents

- `main_label` (string, optional, nullable) — Call to action displayed inside the compact and full variants.
- `start_call` (string, optional, nullable) — 开始通话按钮的文本和 ARIA 标签。
- `start_chat` (string, optional, nullable) — 开始聊天按钮的文本和 ARIA 标签（仅文本）
- `new_call` (string, optional, nullable) — 新建通话按钮的文本和 ARIA 标签。当来电者已完成至少 1 次通话、准备开始下一次通话时显示。
- `end_call` (string, optional, nullable) — 结束通话按钮的文本和 ARIA 标签。
- `mute_microphone` (string, optional, nullable) — 麦克风静音按钮的 ARIA 标签。
- `change_language` (string, optional, nullable) — 切换语言下拉菜单的 ARIA 标签。
- `collapse` (string, optional, nullable) — 折叠按钮的 ARIA 标签。
- `expand` (string, optional, nullable) — 展开按钮的 ARIA 标签。
- `copied` (string, optional, nullable) — 用户使用复制按钮复制值时显示的文本。
- `accept_terms` (string, optional, nullable) — 接受条款按钮的文本和 ARIA 标签。
- `dismiss_terms` (string, optional, nullable) — 取消条款按钮的文本和 ARIA 标签。
- `listening_status` (string, optional, nullable) — 智能体聆听时显示的状态。
- `speaking_status` (string, optional, nullable) — 智能体说话时显示的状态。
- `connecting_status` (string, optional, nullable) — 智能体连接时显示的状态。
- `chatting_status` (string, optional, nullable) — 智能体聊天时显示的状态（仅文本）
- `queue_waiting_status` (string, optional, nullable) — 在队列中等待可用智能体时显示的状态。
- `queue_waiting_status_short` (string, optional, nullable) — 等待可用智能体时显示的简短状态。
- `input_label` (string, optional, nullable) — ARIA label for the text message input.
- `input_placeholder` (string, optional, nullable) — 短信输入框的占位文本。
- `input_placeholder_text_only` (string, optional, nullable) — 短信输入框的占位文本（仅文本）
- `input_placeholder_new_conversation` (string, optional, nullable) — 开始新对话时短信输入框的占位文本（仅文本）
- `user_ended_conversation` (string, optional, nullable) — 用户结束对话时显示的提示消息。
- `agent_ended_conversation` (string, optional, nullable) — 智能体结束对话时显示的提示消息。
- `conversation_id` (string, optional, nullable) — 对话 ID 旁使用的文本标签。
- `error_occurred` (string, optional, nullable) — 发生错误时使用的文本标签。
- `queue_timed_out` (string, optional, nullable) — 队列等待超时时显示的错误消息。
- `copy_id` (string, optional, nullable) — 复制 ID 按钮使用的文本和 ARIA 标签。
- `initiate_feedback` (string, optional, nullable) — 提示用户提供反馈的文本。
- `request_follow_up_feedback` (string, optional, nullable) — 请求补充反馈详情的文本。
- `thanks_for_feedback` (string, optional, nullable) — 感谢用户提供反馈的文本。
- `thanks_for_feedback_details` (string, optional, nullable) — 用于说明用户反馈价值的附加说明文字。
- `follow_up_feedback_placeholder` (string, optional, nullable) — 后续反馈输入框的占位文本。
- `submit` (string, optional, nullable) — 提交按钮的文本和 ARIA 标签。
- `go_back` (string, optional, nullable) — 返回按钮的文本和 ARIA 标签。
- `send_message` (string, optional, nullable) — 发送消息按钮的文本和 ARIA 标签。
- `text_mode` (string, optional, nullable) — 切换至文本模式按钮的文本和 ARIA 标签。
- `voice_mode` (string, optional, nullable) — 切换到语音模式按钮的文本和 ARIA 标签。
- `switched_to_text_mode` (string, optional, nullable) — 切换到文本模式时显示的 Toast 通知。
- `switched_to_voice_mode` (string, optional, nullable) — 切换到语音模式时显示的 Toast 通知。
- `copy` (string, optional, nullable) — 复制按钮的文本和 ARIA 标签。
- `download` (string, optional, nullable) — 下载按钮的文本和 ARIA 标签。
- `wrap` (string, optional, nullable) — 自动换行切换按钮的文本和 ARIA 标签。
- `agent_working` (string, optional, nullable) — 智能体正在处理工具调用时显示的状态文本。
- `agent_done` (string, optional, nullable) — 智能体完成处理工具调用时显示的状态文本。
- `agent_error` (string, optional, nullable) — 智能体在工具调用期间遇到错误时显示的状态文本。
- `attach_file` (string, optional, nullable) — 附加文件按钮的文本和 ARIA 标签。
- `remove_file` (string, optional, nullable) — ARIA label for the remove file button.
- `file_upload_error` (string, optional, nullable) — 文件上传失败时显示的错误消息。
- `file_type_unsupported` (string, optional, nullable) — 选择不支持的文件类型时显示的错误消息，后接可接受类型列表。
- `file_too_large` (string, optional, nullable) — 文件超过最大大小限制时显示的错误消息。
- `file_limit_reached` (string, optional, nullable) — 对话达到最大文件数量时显示的错误消息。
- `typing_indicator` (string, optional, nullable) — 智能体正在输入时显示的状态文本。
- `rich_content_unavailable` (string, optional, nullable) — 无法渲染富内容时显示的备用消息。

### WidgetStyles

- `base` (string, optional, nullable) — 基础背景色。
- `base_hover` (string, optional, nullable) — 基础背景在悬停时的颜色。
- `base_active` (string, optional, nullable) — 基础背景在激活（点击）时的颜色。
- `base_border` (string, optional, nullable) — 基础背景上的边框颜色。
- `base_subtle` (string, optional, nullable) — 基础背景上的次要文本颜色。
- `base_primary` (string, optional, nullable) — 基础背景上的主文本颜色。
- `base_error` (string, optional, nullable) — 基础背景上的错误文本颜色。
- `accent` (string, optional, nullable) — 强调背景色。
- `accent_hover` (string, optional, nullable) — 强调背景在悬停时的颜色。
- `accent_active` (string, optional, nullable) — 强调背景在激活（点击）时的颜色。
- `accent_border` (string, optional, nullable) — 强调背景上的边框颜色。
- `accent_subtle` (string, optional, nullable) — 强调背景上的次要文本颜色。
- `accent_primary` (string, optional, nullable) — 强调背景上的主文本颜色。
- `overlay_padding` (double, optional, nullable) — 视口边缘的内边距。
- `button_radius` (double, optional, nullable) — 按钮圆角半径。
- `input_radius` (double, optional, nullable) — 输入字段圆角半径。
- `bubble_radius` (double, optional, nullable) — 聊天气泡圆角半径。
- `sheet_radius` (double, optional, nullable) — 面板的默认圆角半径。
- `compact_sheet_radius` (double, optional, nullable) — 紧凑模式下面板的圆角半径。
- `dropdown_sheet_radius` (double, optional, nullable) — 下拉面板圆角半径。

### WidgetLanguagePresetResponse

- `first_message` (string, optional, nullable)
- `text_contents` (WidgetTextContents, optional, nullable) — 所选语言的文本内容
- `terms_text` (string, optional, nullable) — 以此语言显示的条款与条件文本
- `terms_html` (string, optional, nullable) — 以此语言显示的条款和条件 HTML
- `terms_key` (string, optional, nullable) — 用于显示该语言条款与条件的键

### FileInputConfig

- `enabled` (boolean, optional, default: true) — 启用后，如果 LLM 支持多模态输入，用户可在聊天中附加图片、PDF 或文本文件。
- `max_files_in_memory` (integer, optional, default: 10) — 对话期间保留在内存中的最新文件数量。较旧文件会被总结并释放其字节数据。
- `max_files_per_conversation` (integer, optional, default: 10) — 用户在一次对话中可上传的文件总数。上传按文件计费。使用 -1 表示不限，或设为大于等于 max_files_in_memory 的值。

### ValidationErrorLocItems

- string
- integer

### OrbAvatar

- `type` ("orb", optional, default: orb) — 头像类型
- `color_1` (string, optional, default: #2792dc) — 头像的第一个颜色
- `color_2` (string, optional, default: #9ce6e6) — 头像的第二种颜色

### URLAvatar

- `type` ("url", optional, default: url) — 头像类型
- `custom_url` (string, optional, default: ) — 头像的自定义 URL

### ImageAvatar

- `type` ("image", optional, default: image) — 头像类型
- `url` (string, optional, default: ) — 头像的 URL

## 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**

```python
import requests

url = "https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget"

response = requests.get(url)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```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<String> response = Unirest.get("https://api.elevenlabs.io/v1/convai/agents/agent_3701k3ttaq12ewp8b7qv5rfyszkz/widget")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->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()
```