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

本文介绍扣子编程 WebSocket 双向流式对话事件中的上行事件，双向流式对话下行事件请参见[双向流式对话下行事件](/developer_guides/streaming_chat_downlink_event)。
## 更新对话配置 {#91642fa8}

* **事件类型**：`chat.update`
* **事件说明**：此事件可以更新当前对话连接的配置项，若更新成功，会收到 `chat.updated` 的下行事件，否则，会收到 `error` 下行事件。
* **事件结构**：

<!-- @cols-width: 186,115,100,453 -->
| | | | | \
|**参数** |**类型** |**是否必选** |**说明** |
|---|---|---|---|
| | | | | \
|id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
| | | | | \
|event_type |String |必选 |固定为 `chat.update`。 |
| | | | | \
|data |Object |可选 |事件数据，包含对话配置的详细信息。 |
| | | | | \
|data.chat_config |Object |可选 |对话配置。 |
| | | | | \
|data.chat_config.meta_data |Map<String, String> |可选 |附加信息，通常用于封装一些业务相关的字段。查看对话消息详情时，系统会透传此附加信息。自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。 |
| | | | | \
|data.chat_config.custom_variables |Map<String, String> |可选 |智能体中定义的变量。在智能体 prompt 中设置变量 {{key}} 后，可以通过该参数传入变量值，同时支持 Jinja2 语法。详细说明可参考变量示例。变量名只支持英文字母和下划线。 |
| | | | | \
|data.chat_config.extra_params |Map<String, String> |可选 |附加参数，通常用于特殊场景下指定一些必要参数供模型判断，例如指定经纬度，并询问智能体此位置的天气。自定义键值对格式，其中键（key）仅支持设置为： |\
| | | | |\
| | | |* `latitude`（纬度，此时值（Value）为纬度值，例如 39.9800718）。 |\
| | | |* `longitude`（经度，此时值（Value）为经度值，例如 116.309314）。 |
| | | | | \
|data.chat_config.user_id |String |可选 |标识当前与智能体的用户，由使用方自行定义、生成与维护。`user_id` 用于标识对话中的不同用户，不同的 `user_id`，其对话的上下文消息、数据库等对话记忆数据互相隔离。如果不需要用户数据隔离，可将此参数固定为一个任意字符串，例如 123，abc 等。 |
| | | | | \
|data.chat_config.conversation_id |String |可选 |标识对话发生在哪一次会话中。会话是智能体和用户之间的一段问答交互。一个会话包含一条或多条消息。对话是会话中对智能体的一次调用，智能体会将对话中产生的消息添加到会话中。可以使用已创建的会话，会话中已存在的消息将作为上下文传递给模型。创建会话的方式可参考创建会话。对于一问一答等不需要区分 conversation 的场合可不传该参数，系统会自动生成一个会话。不传的话会默认创建一个新的 conversation。 |
| | | | | \
|data.chat_config.auto_save_history |Boolean |可选 |是否保存本次对话记录。 |\
| | | | |\
| | | |* `true`：（默认）会话中保存本次对话记录，包括本次对话的模型回复结果、模型执行中间结果。 |\
| | | |* `false`：会话中不保存本次对话记录，后续也无法通过任何方式查看本次对话信息、消息详情。在同一个会话中再次发起对话时，本次会话也不会作为上下文传递给模型。 |
| | | | | \
|data.chat_config.parameters |Map<String, any> |可选 |设置对话流的自定义输入参数的值，具体用法和示例代码可参考[为自定义参数赋值](/tutorial/variable)。  |\
| | | | |\
| | | |* 对话流的输入参数 USER_INPUT 应在 `additional_messages` 中传入，在 parameters 中的 USER_INPUT 不生效。  |\
| | | |* 如果 `parameters` 中未指定 `CONVERSATION_NAME` 或其他输入参数，则使用参数默认值运行对话流；如果指定了这些参数，则使用指定值。 |
| | | | | \
|data.input_audio |Object |可选 |输入音频格式。 |
| | | | | \
|data.input_audio.format |String |可选 |输入音频的格式，支持 `pcm`、`wav`、`ogg`。默认为 `wav`。 |
| | | | | \
|data.input_audio.codec |String |可选 |输入音频的编码，支持 `pcm`、`opus`、`g711a`、`g711u`。默认为 `pcm`。 |\
| | | |如果音频编码格式为 `g711a` 或 `g711u`，`format` 请设置为 `pcm`。 |
| | | | | \
|data.input_audio.sample_rate |Integer |可选 |输入音频的采样率，默认是 24000。支持 8000、16000、22050、24000、32000、44100、48000。 |\
| | | |如果音频编码格式 `codec` 为 `g711a` 或 `g711u`，音频采样率需设置为 8000。 |
| | | | | \
|data.input_audio.channel |Integer |可选 |输入音频的声道数，支持 1（单声道）、2（双声道）。默认是 1（单声道）。 |
| | | | | \
|data.input_audio.bit_depth |Integer |可选 |输入音频的位深，默认是 16，支持8、16和24。 |
| | | | | \
|data.output_audio |Object |可选 |输出音频格式。 |
| | | | | \
|data.output_audio.codec |String |可选 |输出音频编码，支持 `pcm`、`g711a`、`g711u`、`opus`、`mp3`。默认是 `pcm`。 |\
| | | |:::tip 说明 |\
| | | |当 `codec` 设置为 `pcm`、`g711a`或 `g711u`时，你可以通过 `pcm_config` 配置 PCM 音频参数。 |\
| | | |::: |
| | | | | \
|data.output_audio.pcm_config |Object |可选 |* 当 `codec` 设置为 `pcm`、`g711a` 或 `g711u` 时，用于配置 PCM 音频参数。 |\
| | | |* 当 `codec` 设置为 `opus`、`mp3` 时，不需要设置此字段。 |\
| | | | |\
| | | |:::tip 说明 |\
| | | |* 当 `codec` 设置为 `pcm` 时，返回的 PCM 数据将固定为单声道，采样深度为 16 位。 |\
| | | |* 当 `codec` 设置为 `g711a`或 `g711u` 时，返回的数据将是 8000kHz 采样率，单声道，采样深度为 8 位。 |\
| | | |::: |
| | | | | \
|data.output_audio.pcm_config.sample_rate |Integer |可选 |输出 `pcm` 音频的采样率，默认是 24000。支持 8000、16000、22050、24000、32000、44100、48000。 |\
| | | |:::tip 说明 |\
| | | |当 `codec` 设置为 `g711a` 或 `g711u`时，sample_rate 自动设置为 8000，且不能更改。 |\
| | | |::: |
| | | | | \
|data.output_audio.pcm_config.frame_size_ms |Float | 可选 |输出每个 pcm 包的时长，单位 ms，默认不限制。取值范围：0~1000。 |
| | | | | \
|data.output_audio.pcm_config. limit_config |Object |可选 |输出音频限流配置，默认不限制。 |\
| | | |:::tip 说明 |\
| | | |如需实现输出 PCM 音频限流，还需要配置  |\
| | | |`data.output_audio.pcm_config.frame_size_ms`参数。 |\
| | | |::: |
| | | | | \
|data.output_audio.pcm_config. limit_config.period |Integer |可选 |周期的时长，单位为秒。例如设置为 10 秒，则以 10 秒作为一个周期。 |
| | | | | \
|data.output_audio.pcm_config. limit_config.max_frame_num |Integer |可选 |周期内，最大返回 pcm 包数量。 |
| | | | | \
|data.output_audio.opus_config |Object |可选 |当 `codec` 设置为 `pcm`、`mp3` 时，不需要设置此字段。 |
| | | | | \
|data.output_audio.opus_config.sample_rate |Integer |可选 |编码成 `opus` 时的 pcm 采样率，默认 24k。支持 8000、12000、16000、24000、48000。 |
| | | | | \
|data.output_audio.opus_config.bitrate |Integer |可选 |输出 `opus` 的码率，默认 48000。 |
| | | | | \
|data.output_audio.opus_config.use_cbr |Boolean |可选 |输出 `opus` 是否使用 CBR 编码，默认为 `false`。 |
| | | | | \
|data.output_audio.opus_config.frame_size_ms |Float |可选 |输出 `opus` 的帧长，默认是 10。可选值： |\
| | | |2.5、5、10、20、40、60 |
| | | | | \
|data.output_audio.opus_config.limit_config |Object |可选 |输出音频限流配置，默认不限速。 |
| | | | | \
|data.output_audio.opus_config.limit_config.period |Integer |可选 |周期的时长，单位为秒。例如设置为 10 秒，则以 10 秒作为一个周期。 |
| | | | | \
|data.output_audio.opus_config.limit_config.max_frame_num |Integer |可选 |周期内最大返回的 Opus 帧数量。 |
| | | | | \
|data.output_audio.mp3_config |Object |可选 |* 当 `codec` 设置为 `mp3` 时，用于配置 mp3 音频参数。 |\
| | | |* 当 `codec` 设置为 `opus`、`pcm`、`g711a`、`g711u` 时，不需要设置此字段。 |
| | | | | \
|data.output_audio.mp3_config.sample_rate |Integer |可选 |输出 `mp3` 音频的采样率，默认是 44100。支持 32000、44100、48000。 |
| | | | | \
|data.output_audio.mp3_config.bit_rate |Integer |可选 |输出 `mp3` 音频的码率，支持 8000~1600000。 |
| | | | | \
|data.output_audio.speech_rate |Integer |可选 |输出音频的语速，取值范围 [-50, 100]，默认为 0。-50 表示 0.5 倍速，100 表示 2 倍速。 |
| | | | | \
|data.output_audio.loudness_rate |Integer |可选 |输出音频的音量，取值范围 [-50, 100]，默认为 0。-50 表示 0.5 倍音量，100 表示 2 倍音量。 |
| | | | | \
|data.output_audio.voice_id |String |可选 |输出音频的音色 ID，默认是柔美女友音色。你可以调用[查看音色列表](/developer_guides/list_voices) API 查看当前可用的所有音色 ID。 |
| | | | | \
|data.output_audio.context_texts |String |可选 |语音合成的辅助信息，用于控制合成语音的整体情绪（如悲伤、生气）、方言（如四川话、北京话）、语气（如撒娇、暧昧、吵架、夹子音）、语速（快慢）及音调（高低）等。默认为空。 |\
| | | |示例：用低沉沙哑的语气、带着沧桑与绝望地说。 |\
| | | |:::tip 说明 |\
| | | |* 仅当 `voice_id` 为豆包语音合成大模型 2.0 音色时才支持该参数，具体音色列表请参见[系统音色列表](/dev_how_to_guides/sys_voice)。 |\
| | | |* 更多关于豆包语音合成 2.0 的 `context_texts` 示例和效果可参考[语音指令-示例库](https://www.volcengine.com/docs/6561/1871062?lang=zh#_1-2-%F0%9F%92%A1%E8%AF%AD%E9%9F%B3%E6%8C%87%E4%BB%A4-%E7%A4%BA%E4%BE%8B%E5%BA%93) |\
| | | |::: |
| | | | | \
|data.output_audio.emotion_config |Object |可选 |设置多情感音色的情感和情感值，仅当 `voice_id` 为多情感音色时才支持该配置。 |
| | | | | \
|data.output_audio.emotion_config.emotion |String |可选 |设置多情感音色的情感类型。不同音色支持的情感范围不同，可以通过[系统音色列表](https://www.coze.cn/open/docs/dev_how_to_guides/sys_voice)查看各音色支持的情感。默认为空。枚举值如下： |\
| | | | |\
| | | |* happy-开心 |\
| | | |* sad-悲伤 |\
| | | |* angry-生气 |\
| | | |* surprised-惊讶 |\
| | | |* fear-恐惧 |\
| | | |* hate-厌恶 |\
| | | |* excited-激动 |\
| | | |* coldness-冷漠 |\
| | | |* neutral-中性 |\
| | | | |\
| | | |:::tip 说明 |\
| | | |你需要在对话流开始节点的输入参数中增加 `_voice_emotion` 参数，用于向对话流传递多情感音色的情感类型配置。 |\
| | | |::: |
| | | | | \
|data.output_audio.emotion_config.emotion_scale |Float |可选 |情感值用于量化情感的强度。数值越高，情感表达越强烈，例如： “开心” 的情感值 5 比 1 更显兴奋。 |\
| | | |取值范围：1.0~5.0，默认值：4.0。 |
| | | | | \
|data.voice_processing_config |Object |可选 |语音处理能力配置。 |\
| | | |:::tip 说明 |\
| | | |仅扣子企业旗舰版支持该配置。 |\
| | | |::: |
| | | | | \
|data.voice_processing_config.enable_ans |Boolean |可选 |主动噪声抑制。自动识别并过滤掉背景环境中的各种噪音（如键盘声、空调声、街道嘈杂声），让说话者的声音更清晰。 |\
| | | |此功能与下面的 `enable_pdns`（声纹降噪）只能**二选一开启**，不能同时使用。 |
| | | | | \
|data.voice_processing_config.enable_pdns |Boolean |可选 |声纹降噪。专门针对**特定说话人**的声音进行优化，能更精准地保留目标人声。 |\
| | | |此功能与上面的 `enable_ans`只能**二选一开启**，不能同时使用。 |\
| | | |提供两种模式，你可以根据需要选择： |\
| | | | |\
| | | |* 自动提取：设置简单，开箱即用。默认为该模式。**降噪生效稍微有延迟**，服务端需要先听你说一会儿话才能提取出你的声纹特征，在此期间降噪效果可能不佳。另外，提取声纹会受到用户说话场景影响，准确性上可能会弱于主动设置。 |\
| | | |* 主动设置：**降噪效果更精准、更快速**，在对话开始时就立即生效。不过需要提前录制声纹并在 `voice_print_feature_id` 中设置声纹 ID。 |
| | | | | \
|data.voice_processing_config.voice_print_feature_id |String |可选 |目标说话人的声纹 ID。当你选择开启 `enable_pdns`（声纹降噪）并希望使用**主动设置**模式时，需要在此处填入你提前录制好的声纹 ID。 |\
| | | |你可以通过扣子编程录制声纹，具体请参见[声纹识别](/guides/voiceprint_recognition)，或通过[创建声纹](/developer_guides/create_voiceprint) API 上传声纹并获取声纹 ID。 |
| | | | | \
|data.event_subscriptions |Array<String> |可选 |需要订阅下行事件的事件类型列表。不设置或者设置为空为订阅所有下行事件。 |
| | | | | \
|data.need_play_prologue |Boolean |可选 |是否需要播放开场白，默认为 false。 |
| | | | | \
|data.prologue_content |String |可选 |自定义开场白，need_play_prologue 设置为 true 时生效。如果不设定自定义开场白则使用智能体上设置的开场白。 |
| | | | | \
|data.turn_detection |Object |可选 |转检测配置。 |
| | | | | \
|data.turn_detection.type |String |可选 |语音检测类型，用于控制语音交互的检测方式，枚举值： |\
| | | | |\
| | | |* **server_vad** ：自由对话模式，语音数据会传输到服务器端进行实时分析，服务器端的语音活动检测算法会判断用户是否在说话。 |\
| | | |* **client_interrupt**：（默认）按键说话模式，由客户端控制语音的开始与结束。 |\
| | | |* **semantic_vad**：采用语义判停的自由对话模式（**此功能仅对企业旗舰版用户开放**），由服务端识别语义来判断是否停止说话。 |
| | | | | \
|data.turn_detection.prefix_padding_ms |Integer |可选 |`server_vad` 模式下，VAD 检测到语音之前要包含的音频量，单位为 ms。默认为 600ms。 |
| | | | | \
|data.turn_detection.silence_duration_ms |Integer |可选 |`server_vad` 模式下，检测语音停止的静音持续时间，单位为 ms。默认为 500ms。 |
| | | | | \
|data.turn_detection.semantic_vad_config |Object |可选 |`semantic_vad` 模式下，配置判定语音停止的语义检测策略。 |
| | | | | \
|data.turn_detection.semantic_vad_config.silence_threshold_ms |Integer |可选 |当用户暂停说话时，持续静音多久后，触发语义判停检测。单位为 ms。默认为 300ms。 |
| | | | | \
|data.turn_detection.semantic_vad_config.semantic_unfinished_wait_time_ms |Integer |可选 |当语义检测判断该语句未结束时，持续静音多久后，扣子编程认定语音结束。单位为 ms。默认为 500ms。取值范围为 100~2000。 |
| | | | | \
|data.turn_detection.interrupt_config |Object |可选 |`server_vad` 模式下，配置语音对话的打断策略。 |\
| | | |默认采用发声即打断模式，即在检测到语音输入时会中断智能体的输出。 |
| | | | | \
|data.turn_detection.interrupt_config.mode |String |可选 |配置通过关键词打断，包括: |\
| | | | |\
| | | |* `keyword_contains`模式下，说话内容**包含**关键词才会打断模型回复。例如关键词"扣子"，用户正在说“你好呀扣子......” / “扣子你好呀”，模型回复都会被打断。 |\
| | | |* `keyword_prefix`模式下，说话内容**前缀匹配**关键词才会打断模型回复。例如关键词"扣子"，用户正在说“扣子你好呀......”，模型回复就会被打断，而用户说“你好呀扣子......”，模型回复不会被打断。 |\
| | | | |\
| | | |详细配置方法请参见[通过关键词打断语音对话](/tutorial/keywords_interruption)。 |
| | | | | \
|data.turn_detection.interrupt_config.keywords |Array<String> |可选 |打断的关键词配置，最多同时限制 5 个关键词，每个关键词限定长度在 6~24 个字节以内（2~8个汉字以内），不能有标点符号。 |
| | | | | \
|data.asr_config |Object |可选 |语音识别配置，包括热词和上下文信息，以便优化语音识别的准确性和相关性。 |
| | | | | \
|data.asr_config.hot_words |Array<String> |可选 |请输入热词列表，以便提升这些词汇的识别准确率。如果设置的热词数量超出以下数量限制，超出部分将自动截断。 |\
| | | | |\
| | | |* `data.asr_config.stream_mode` 为`output_no_stream`时：hot_words 支持 5000 tokens。 |\
| | | |* `data.asr_config.stream_mode` 为`bidirectional_stream`时： hot_words 支持 100 tokens。 |
| | | | | \
|data.asr_config.context |String |可选 |请输入上下文信息。 |\
| | | |最多输入 800 个 Tokens，超出部分将自动截断。 |
| | | | | \
|data.asr_config.user_language |String  |可选  |用户说话的语种，默认为 `common`支持**中英文、上海话、闽南语，四川、陕西、粤语**识别。**仅在** **`data.asr_config.stream_mode` 为`output_no_stream`时可以指定设置语种。**当将其设置为下方特定键时，它可以识别指定语言。  |\
| | | | |\
| | | |* 英语：en-US |\
| | | |* 日语：ja-JP |\
| | | |* 印尼语：id-ID |\
| | | |* 西班牙语：es-MX |\
| | | |* 葡萄牙语：pt-BR |\
| | | |* 德语：de-DE |\
| | | |* 法语：fr-FR |\
| | | |* 韩语：ko-KR |\
| | | |* 菲律宾语：fil-PH |\
| | | |* 马来语：ms-MY |\
| | | |* 泰语：th-TH |\
| | | |* 阿拉伯语：ar-SA |\
| | | | |\
| | | |例如，如果输入音频是德语，则此参数传入de-DE |
| | | | | \
|data.asr_config.enable_ddc |Boolean |可选  |将语音转为文本时，是否启用语义顺滑。默认为 `true`。 |\
| | | | |\
| | | |* `true`：系统在进行语音处理时，会去掉识别结果中诸如 “啊”“嗯” 等语气词，使得输出的文本语义更加流畅自然，符合正常的语言表达习惯，尤其适用于对文本质量要求较高的场景，如正式的会议记录、新闻稿件生成等。 |\
| | | |* `false`：系统不会对识别结果中的语气词进行处理，识别结果会保留原始的语气词。 |
| | | | | \
|data.asr_config.enable_itn |Boolean |可选  |将语音转为文本时，是否开启文本规范化（ITN）处理，将识别结果转换为更符合书面表达习惯的格式以提升可读性。默认为 `true`。 |\
| | | |开启后，会将口语化数字转换为标准数字格式，示例： |\
| | | | |\
| | | |* 将`两点十五分`转换为 `14:15`。 |\
| | | |* 将`一百美元`转换为 `$100`。 |
| | | | | \
|data.asr_config.enable_punc |Boolean |可选  |将语音转为文本时，是否给文本加上标点符号。默认为 `true`。 |
| | | | | \
|data.asr_config.stream_mode |String |可选 |ASR 识别的模式。 |\
| | | | |\
| | | |* `output_no_stream`：不会逐字返回语音识别结果，而是等整段语音结束后统一输出完整文本。异步语音消息场景中推荐使用该模式，会整合整句音频信息做上下文分析，减少实时截断导致的误差，提升准确率。 |\
| | | |* `bidirectional_stream`（默认值）：逐字的返回语音识别的结果。 |
| | | | | \
|data.asr_config.enable_nostream |Boolean |可选 |是否开启**二次识别模式**： |\
| | | | |\
| | | |* `true`：会实时返回逐字识别的文本；当一句话结束时，会结合整句音频进行上下文分析并重新识别，生成优化后的识别结果并返回。这种机制既能满足客户实时上屏的需求，又能确保最终结果的识别准确率。 |\
| | | |* `false`（默认值）：仅进行一次实时识别，逐字返回文本，不会在一句话结束时重新识别分句，可能存在一定的识别误差。 |
| | | | | \
|data.asr_config.enable_emotion |Boolean |可选 |识别说话人的情绪。仅在 `data.asr_config.stream_mode` 为`output_no_stream`时生效。默认为`false`。 |\
| | | |支持的情绪标签包括： |\
| | | | |\
| | | |* `angry`：表示情绪为生气 |\
| | | |* `happy`：表示情绪为开心 |\
| | | |* `neutral`：表示情绪为平静或中性 |\
| | | |* `sad`：表示情绪为悲伤 |\
| | | |* `surprise`：表示情绪为惊讶 |
| | | | | \
|data.asr_config.enable_gender |Boolean |可选 |是否开启识别说话人的性别（male/female），仅在 `data.asr_config.stream_mode` 为`output_no_stream`时生效。默认为`false`。 |\
| | | |:::tip 说明 |\
| | | |你需要在对话流开始节点的输入参数中增加 `_voice_gender` 参数，以便对话流获取识别后的说话人性别。 |\
| | | |::: |
| | | | | \
|data.asr_config.sensitive_words_filter |Object |可选 |敏感词过滤功能，支持以下 3 种过滤方式： |\
| | | | |\
| | | |* 过滤系统敏感词，并替换为`*`。 |\
| | | |* 过滤自定义敏感词，并替换为空。 |\
| | | |* 过滤自定义敏感词，并替换为`*`。 |
| | | | | \
|data.asr_config.sensitive_words_filter.system_reserved_filter |Boolean |可选 |是否过滤系统自带的敏感词，并将匹配到的敏感词替换为`*`。（系统自带敏感词主要包含一些限制级词汇）。默认为`false`。 |
| | | | | \
|data.asr_config.sensitive_words_filter.filter_with_empty |Array<string> |可选 |自定义需替换为空的敏感词列表。 |
| | | | | \
|data.asr_config.sensitive_words_filter.filter_with_signed |Array<string> |可选 |自定义需替换为 `*` 的敏感词列表。 |
| | | | | \
|data.voice_print_config |Object<String> |可选 |声纹识别配置。 |
| | | | | \
|data.voice_print_config.group_id |String |可选 |声纹组 ID。语音通话时，扣子编程会在该声纹组内进行查找匹配对应的声纹，当声纹匹配度高于 `score` 阈值，则认为是同一个人的声音。 |\
| | | |你可以通过[查看声纹组列表](https://www.coze.cn/open/docs/developer_guides/list_voiceprint_group) API 查看声纹组 ID。 |
| | | | | \
|data.voice_print_config.score |Integer |可选 |声纹匹配的命中阈值，即声音匹配度的最低标准。当声音匹配度达到或超过该阈值时，扣子编程才会认定声纹匹配成功。你可以根据应用的安全性要求进行自定义设置。如果匹配了多轮声纹，扣子编程会取相似度最高的一个。 |\
| | | |取值范围：0~100，默认值：40。 |
| | | | | \
|data.voice_print_config.reuse_voice_info |Boolean |可选 |当本轮对话未命中任何声纹时，是否沿用历史声纹信息。 |\
| | | | |\
| | | |* `true`：未命中声纹时，智能体将返回上一次命中的声纹。适用于连续对话场景，当收音不好等情况导致声纹没能正确被识别时，保障对话的连贯性。 |\
| | | |* `false`：（默认值）未命中声纹时，智能体返回空的声纹信息。 |


* **事件示例**：



:::: tabs
@tab 输出音频为 pcm

```JSON
{
    "id": "event_id",
    "event_type": "chat.update",
    "data": {
        "chat_config": {
            "auto_save_history": true, // 保存历史记录。默认 true
            "conversation_id": "xxxx", // conversation_id
            "user_id": "xxx",  // 标识当前与智能体的用户，由使用方自行定义、生成与维护。user_id 用于标识对话中的不同用户，不同的 user_id，其对话的上下文消息、数据库等对话记忆数据互相隔离。如果不需要用户数据隔离，可将此参数固定为一个任意字符串
            "meta_data": {}, // 附加信息,通常用于封装一些业务相关的字段。查看对话消息详情时,系统会透传此附加信息。
            "custom_variables": {}, // 智能体中定义的变量。在智能体prompt中设置变量{{key}}后,可以通过该参数传入变量值,同时支持Jinja2语法。详细说明可参考变量示例。变量名只支持英文字母和下划线。
            "extra_params": {},   // 附加参数,通常用于特殊场景下指定一些必要参数供模型判断,例如指定经纬度,并询问智能体此位置的天气。自定义键值对格式,其中键(key)仅支持设置为:latitude:纬度,此时值(Value)为纬度值,例如39.9800718。longitude:经度,此时值(Value)为经度值,例如116.309314。
            "parameters": {"custom_var_1": "测试"}
        },
        "input_audio": {         // 输入音频格式
            "format": "pcm",       // 输入音频格式，支持 pcm/wav/ogg。默认 wav
            "codec": "pcm",         // 输入音频编码。 pcm/opus。默认 pcm
            "sample_rate": 24000,  // 采样率
            "channel": 1, // 通道数
            "bit_depth": 16 // 位深
        },
        "output_audio": {        // 输出音频格式
            "codec": "pcm",       
            "pcm_config": {
                "sample_rate": 16000,  // 默认  24000
                "frame_size_ms": 50,
                "limit_config": {
                    "period": 1,
                    "max_frame_num": 22
                }
            },
            "speech_rate": 0,  // 回复的语速，取值范围 [-50, 100]，默认为 0，-50 表示 0.5 倍速，100 表示 2倍速
            "voice_id": "7426720361733046281"
        }
    }
}
```



@tab 输出音频为 opus

```JSON
{
    "id": "event_id",
    "event_type": "chat.update",
    "data": {
        "chat_config": {
            "auto_save_history": true, // 保存历史记录。默认 true
            "conversation_id": "xxxx", // conversation_id
            "user_id": "xxx",  // 标识当前与智能体的用户，由使用方自行定义、生成与维护。user_id 用于标识对话中的不同用户，不同的 user_id，其对话的上下文消息、数据库等对话记忆数据互相隔离。如果不需要用户数据隔离，可将此参数固定为一个任意字符串
            "meta_data": {}, // 附加信息,通常用于封装一些业务相关的字段。查看对话消息详情时,系统会透传此附加信息。
            "custom_variables": {}, // 智能体中定义的变量。在智能体prompt中设置变量{{key}}后,可以通过该参数传入变量值,同时支持Jinja2语法。详细说明可参考变量示例。变量名只支持英文字母和下划线。
            "extra_params": {},   // 附加参数,通常用于特殊场景下指定一些必要参数供模型判断,例如指定经纬度,并询问智能体此位置的天气。自定义键值对格式,其中键(key)仅支持设置为:latitude:纬度,此时值(Value)为纬度值,例如39.9800718。longitude:经度,此时值(Value)为经度值,例如116.309314。
            "parameters": {"custom_var_1": "测试"}
        },
        "input_audio": {         // 输入音频格式
            "format": "pcm",       // 输入音频格式，支持 pcm/wav/ogg。默认 wav
            "codec": "pcm",         // 输入音频编码。 pcm/opus。默认 pcm
            "sample_rate": 24000,  // 采样率
            "channel": 1, // 通道数
            "bit_depth": 16 // 位深
        },
        "output_audio": {        // 输出音频格式
            "codec": "opus",     
            "opus_config": {
                "bitrate": 48000,   // 码率
                "use_cbr": false,     // 是否使用 cbr 编码
                "frame_size_ms": 10,   // 帧长(单位ms)
                "limit_config": {
                    "period": 2,   // 周期（单位 s）
                    "max_frame_num": 240 // 周期内返回最大 opus 帧数量
                }
            },
            "speech_rate": 0,  // 回复的语速，取值范围 [-50, 100]，默认为 0，-50 表示 0.5 倍速，100 表示 2倍速
            "voice_id": "7426720361733046281"
        }
    }
}
```



::::

## 流式上传音频片段 {#98463f78}

* **事件类型**：`input_audio_buffer.append`
* **事件说明**：流式向服务端提交音频的片段。
* **事件结构**：
   <!-- @cols-width: 100,100,100,444 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.append`。 |
   | | | | | \
   |data |Object |必选 |事件数据，包含音频片段信息。 |
   | | | | | \
   |data.delta |String |必选 |base64 编码后的音频片段。 |

* **事件示例**：

```JSON
{
  "id": "event_id",
  "event_type": "input_audio_buffer.append",
  "data": {
     "delta": "base64EncodedAudioDelta"
  }
}
```

## 提交音频 {#d53cac91}

* **事件类型**：`input_audio_buffer.complete`
* **事件说明**：客户端发送 `input_audio_buffer.complete` 事件来告诉服务端提交音频缓冲区的数据。服务端提交成功后会返回 `input_audio_buffer.completed` 事件。在 `server_vad` 模式下，提交此事件无效。
* **事件结构**：
   <!-- @cols-width: 100,100,100,450 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.complete`。 |

* **事件示例**：

```JSON
{
  "id": "event_id",
  "event_type": "input_audio_buffer.complete"
}
```

## 清除缓冲区音频 {#81e635d4}

* **事件类型**：`input_audio_buffer.clear`
* **事件说明**：客户端发送 `input_audio_buffer.clear` 事件来告诉服务端清除缓冲区的音频数据。服务端清除完后将返回 `input_audio_buffer.cleared` 事件。在 `server_vad` 模式下，提交此事件无效。
* **事件结构**：
   <!-- @cols-width: 100,100,100,429 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `input_audio_buffer.clear`。 |

* **事件示例**：

```JSON
{
  "id": "event_1",
  "event_type": "input_audio_buffer.clear"
}
```

## 手动提交对话内容 {#46f6a7d0}

* **事件类型**：`conversation.message.create`
* **事件说明**：若 `role=user`，提交事件后就会生成语音回复，适合如下的场景，比如帮我解析 xx 链接，帮我分析这个图片的内容等。若 `role=assistant`，提交事件后会加入到对话的上下文。
* **事件结构**：
   <!-- @cols-width: 136,100,100,500 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `conversation.message.create`。 |
   | | | | | \
   |data |Object |必选 |事件数据，包含对话内容的详细信息。 |
   | | | | | \
   |data.role |String |必选 |发送这条消息的实体。取值：`user`（代表该条消息内容是用户发送的）、`assistant`（代表该条消息内容是智能体发送的）。 |
   | | | | | \
   |data.content_type |String |必选 |消息内容的类型，支持设置为： |\
   | | | | |\
   | | | |* `text`：文本 |\
   | | | |* `object_string`：多模态内容，即文本和文件的组合、文本和图片的组合。 |
   | | | | | \
   |data.content |String |必选 |消息的内容，支持纯文本、多模态（文本、图片、文件混合输入）、卡片等多种类型的内容。当 content_type 为 `object_string`时，content 的结构和详细参数说明请参见[object_string object](/developer_guides/chat_v3#ff7MfGyngc)。 |

* **事件示例**：

```JSON
{
  "id": "7446668538246561826",
  "event_type": "conversation.message.create",
  "data": {
     "role": "user", // user/assistant
     "content_type": "object_string", // text/object_string
     "content": "[{\"type\":\"text\",\"text\":\"帮我看看这个PDF里有什么内容？\"},{\"type\":\"file\",\"file_url\":\"<url id=\\\"cumqdq0onf4lro6iakgg\\\" type=\\\"url\\\" status=\\\"failed\\\" title=\\\"\\\" wc=\\\"0\\\">https://lf3-appstore-sign.oceancloudapi.com/ocean-cloud-tos/eaafba63-0d96-4ea6-b60c-fbadcf2c25e9.?lk3s=edeb9e45&x-expires=1718296132&x-signature=YtlsUsvSeLJi6x31I%2F4S9X53Y6Y%3D</url> \"}]"
  }
}
```

## 清除上下文 {#aa86f213}

* **事件类型**：`conversation.clear`
* **事件说明**：清除上下文，会在当前 conversation 下新增一个 section，服务端处理完后会返回 `conversation.cleared` 事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,549 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |固定为 `conversation.clear`。 |

* **事件示例**：
   ```JSON
   {
     "id": "event_1",
     "event_type": "conversation.clear"
   }
   ```


## 提交端插件执行结果 {#aacdcb41}

* **事件类型**：`conversation.chat.submit_tool_outputs`
* **事件说明**：你可以将需要客户端执行的操作定义为插件，对话中如果触发这个插件，会收到一个 `event_type = "conversation.chat.requires_action"` 的下行事件，此时需要执行客户端的操作后，通过此上行事件来提交插件执行后的结果。
* **事件结构**：

<!-- @cols-width: 145,100,100,514 -->
| | | | | \
|**参数** |**类型** |**是否必选** |**说明** |
|---|---|---|---|
| | | | | \
|id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
| | | | | \
|event_type |String |必选 |固定为 `conversation.chat.submit_tool_outputs`。 |
| | | | | \
|data |Object |必选 |事件数据，包含工具执行结果的详细信息。 |
| | | | | \
|data.chat_id |String |必选 |对话的唯一标识。你可以在扣子编程智能语音对话下行的`conversation.chat.requires_action`事件，通过 data.id 字段查看此 ID。 |
| | | | | \
|data.tool_outputs |Array |必选 |工具执行结果。 |
| | | | | \
|data.tool_outputs[].tool_call_id |String |必选 |上报运行结果的 ID。你可以在扣子编程智能语音对话信令事件的 `tool_calls` 字段下查看此 ID。 |
| | | | | \
|data.tool_outputs[].output |String |必选 |工具的执行结果。 |


* **事件示例**：

```JSON
{
  "id": "744666853824656xxxx",
  "event_type": "conversation.chat.submit_tool_outputs",
  "data": {
      "chat_id": "74466752759xxxx",
      "tool_outputs": [
          {
              "tool_call_id": "BUJJRUUVEhJGERVeEkRDFV5HEkJAXktLQBZeEEAXREpLSxZFR****=",
              "output": "{\"url\":\"<url id=\\\"cumqdq0onf4lro6iakh0\\\" type=\\\"url\\\" status=\\\"failed\\\" title=\\\"\\\" wc=\\\"0\\\">https://lf3-bot-platform-tos-sign.coze.cn/bot-studio-bot-platform/bot_files/323733792754xxx/image/jpeg/7446661351415529491/blob</url> ****\"}"
          }
      ]
  }
}
```

## 打断智能体输出 {#0554db7d}

* **事件类型**：`conversation.chat.cancel`
* **事件说明**：发送此事件可取消正在进行的对话，中断后，服务端将会返回 `conversation.chat.canceled` 事件。
* **事件结构**：
   <!-- @cols-width: 100,100,100,447 -->
   | | | | | \
   |**参数** |**类型** |**是否必选** |**说明** |
   |---|---|---|---|
   | | | | | \
   |id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
   | | | | | \
   |event_type |String |必选 |必填 `conversation.chat.cancel`。 |

* **事件示例**：
   ```JSON
   {
     "id": "7446668538246561827",
     "event_type": "conversation.chat.cancel"
   }
   ```


## 语音合成 {#620367d0}

* **事件类型**：`input_text.generate_audio`
* **事件说明**：你可以主动提交一段文字用来做语音合成，提交的消息不会触发智能体的回复，只会合成音频内容下发到客户端。提交事件的时候如果智能体正在输出语音会被中断输出。适合在和智能体聊天过程中客户端长时间没有响应，智能体可以主动说话暖场的场景。
* **事件结构**：

<!-- @cols-width: 145,100,100,514 -->
| | | | | \
|**参数** |**类型** |**是否必选** |**说明** |
|---|---|---|---|
| | | | | \
|id |String |必选 |客户端自行生成的事件 ID，方便定位问题。 |
| | | | | \
|event_type |String |必选 |固定为 `input_text.generate_audio`。 |
| | | | | \
|data |Object |必选 |事件数据。 |
| | | | | \
|data.mode |String |必选 |消息内容的类型，支持设置为： |\
| | | | |\
| | | |* `text`：文本 |
| | | | | \
|data.text |string |可选 |当 `mode == text` 时候必填。长度限制 (0, 1024) 字节 |


* **事件示例**：

```JSON
{
  "id": "744666853824656xxxx",
  "event_type": "input_text.generate_audio",
  "data": {
      "mode": "text",
      "text": "亲，你怎么不说话了。"
  }
}
```