Realtime 下行事件

本文介绍扣子编程智能语音信令事件中的下行事件。

房间配置成功

• 事件类型：session.created

• 事件说明：用户成功进房后会发送此事件。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为session.created。
  data	Object	必选	事件数据，包含对话的详细信息。
  data.voice_id	String	必选	音色 ID。
  data.log_id	String	必选	服务端日志 ID，用于查找问题。

• 事件示例：

  {
      "id": "7446668538246561800",
      "event_type": "session.created",
      "data": {
          "voice_id": "134",
          "log_id":"xxx"
      }
  }
  

房间配置更新成功

• 事件类型：session.updated
• 事件说明：房间内的配置更新成功，返回房间内最新的配置。
• 事件结构：

• 事件示例：

  {
      "id": "7446668538246561890",
      "event_type": "session.update",
      "data": {
          "voice_id": "123", // 音色 ID
          "speech_rate": 0, // [-50, 100]
          "longest_silence_ms": 180000,
          "event_subscriptions": [],
          "chat_config": {
              "meta_data": {
                  "a": "123"
              },
              "custom_variables": {
                  "a": "123"
              },
              "extra_params": {
                  "a": "123"
              },
              "allow_voice_interrupt": true,
              "interrupt_config": {
                  "mode": "keyword_prefix",
                  "keyword": ["扣子"]
              },
              "plugin_interrupt_mode": "nonblocking" // 控制收到端插件执行中断信号后，没有提交端执行请求时的模型
              // 端插件的执行模型，默认不阻塞，blocking/nonblocking，阻塞的场景如果不提交端执行请求就会让语音链路一直block住
          },
          "turn_detection": {
              "type": "server_vad" // server_vad/client_vad
          },
          "asr_config": {
              "hot_words": ["扣子"],
              "enable_itn": true,
              "enable_punc": true,
              "enable_ddc": true
          } 
      }
  }
  

会话创建成功

• 事件类型：conversation.created

• 事件说明：用户成功进房后会发送此事件，收到此事件即表明房间初始化完成。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为conversation.created。
  data	Object	必选	事件数据，包含对话的详细信息。
  data.conversation_id	String	必选	会话 ID，整个房间的交互都会发生在此会话下。
  data.prologue	String	必选	智能体的开场白。

• 事件示例：

  {
      "id": "7446668538246561891",
      "event_type": "conversation.created",
      "data": {
          "conversation_id": "123",
          "prologue": ""
      }
  }
  

对话开始

• 事件类型：conversation.chat.created

• 事件说明：创建对话的事件，表示对话开始。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为conversation.chat.created。
  data	Object	必选	事件数据，包含对话的详细信息。
  data.id	String	必选	对话 ID，即对话的唯一标识。
  data.conversation_id	String	必选	会话 ID，即会话的唯一标识。
  data.bot_id	String	必选	要进行会话聊天的智能体 ID。
  data.created_at	Integer	可选	对话创建的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。
  data.last_error	Object	可选	对话运行异常时，此字段中返回详细的错误信息，包括： Code：错误码。Integer 类型。0 表示成功，其他值表示失败。 Msg：错误信息。String 类型。
  data.meta_data	Map<String, String>	可选	创建消息时的附加消息，用于传入使用方的自定义数据，获取消息时也会返回此附加消息。自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。
  data.status	String	可选	对话的运行状态。取值为 created，即对话已创建。
  data.usage	Object	可选	对话的 Token 使用情况。
  data.usage.token_count	Integer	可选	本次对话消耗的 Token 总数，包括 input 和 output 部分的消耗。
  data.usage.output_count	Integer	可选	output 部分消耗的 Token 总数。
  data.usage.input_count	Integer	可选	input 部分消耗的 Token 总数。

• 事件示例：

  {
    "id": "7446668538246561892",
    "event_type": "conversation.chat.created",
    "data": {
        "id": "123",
        "conversation_id": "123",
        "bot_id": "222",
        "created_at": 1710348675,
        "completed_at": null,
        "last_error": null,
        "meta_data": {},
        "status": "created",
        "usage": null
    }    
  }
  

对话处理中

• 事件类型：conversation.chat.in_progress

• 事件说明：服务端正在处理对话。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为conversation.chat.in_progress。
  data	Object	必选	事件数据，包含对话的详细信息。
  data.id	String	必选	对话 ID，即对话的唯一标识。
  data.conversation_id	String	必选	会话 ID，即会话的唯一标识。
  data.bot_id	String	必选	要进行会话聊天的智能体 ID。
  data.created_at	Integer	可选	对话创建的时间。格式为 10 位的 Unixtime 时间戳，单位为秒。
  data.last_error	Object	可选	对话运行异常时，此字段中返回详细的错误信息，包括： Code：错误码。Integer 类型。0 表示成功，其他值表示失败。 Msg：错误信息。String 类型。
  data.meta_data	Map<String, String>	可选	创建消息时的附加消息，用于传入使用方的自定义数据，获取消息时也会返回此附加消息。自定义键值对，应指定为 Map 对象格式。长度为 16 对键值对，其中键（key）的长度范围为 1～64 个字符，值（value）的长度范围为 1～512 个字符。
  data.status	String	可选	对话的运行状态。取值为 in_progress，即智能体正在处理中。
  data.usage	Object	可选	对话的 Token 使用情况。
  data.usage.token_count	Integer	可选	本次对话消耗的 Token 总数，包括 input 和 output 部分的消耗。
  data.usage.output_count	Integer	可选	output 部分消耗的 Token 总数。
  data.usage.input_count	Integer	可选	input 部分消耗的 Token 总数。

• 事件示例：

  {
    "id": "7446668538246561892",
    "event_type": "conversation.chat.in_progress",
    "data": {
        "id": "123",
        "conversation_id": "123",
        "bot_id": "222",
        "created_at": 1710348675,
        "completed_at": null,
        "last_error": null,
        "meta_data": {},
        "status": "in_progress",
        "usage": null
    }
  }
  

增量消息

• 事件类型：conversation.message.delta

• 事件说明：增量消息，通常是 type=answer 时的增量消息。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为conversation.message.delta。
  data	Object	必选	事件数据，包含消息的详细信息。
  data.id	String	必选	Message ID，即消息的唯一标识。
  data.conversation_id	String	必选	此消息所在的会话 ID。
  data.bot_id	String	必选	编写此消息的智能体 ID。此参数仅在对话产生的消息中返回。
  data.chat_id	String	必选	Chat ID。此参数仅在对话产生的消息中返回。
  data.meta_data	Map<String, String>	可选	创建消息时的附加消息，获取消息时也会返回此附加消息。
  data.role	String	必选	发送这条消息的实体。取值：user（代表该条消息内容是用户发送的）、assistant（代表该条消息内容是智能体发送的）。
  data.content	String	必选	消息的内容，支持纯文本、多模态（文本、图片、文件混合输入）、卡片等多种类型的内容。
  data.content_type	String	必选	消息内容的类型，取值包括： text：文本。 object_string：多模态内容，即文本和文件的组合、文本和图片的组合。 card：卡片。此枚举值仅在接口响应中出现，不支持作为入参。
  data.type	String	必选	消息类型。 question：用户输入内容。 answer：智能体返回给用户的消息内容，支持增量返回。如果工作流绑定了 messge 节点，可能会存在多 answer 场景，此时可以用流式返回的结束标志来判断所有 answer 完成。 function_call：智能体对话过程中调用函数（function call）的中间结果。 tool_output：调用工具 （function call）后返回的结果。 tool_response：调用工具 （function call）后返回的结果。 follow_up：如果在智能体上配置打开了用户问题建议开关，则会返回推荐问题相关的回复内容。 verbose：多 answer 场景下，服务端会返回一个 verbose 包，对应的 content 为 JSON 格式，content.msg_type =generate_answer_finish 代表全部 answer 回复完成。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "conversation.message.delta",
    "data": {
        "id": "msg_006",
        "role": "assistant",
        "type": "answer",
        "content": "你好你好",
        "content_type": "text",
        "chat_id": "123",
        "conversation_id": "123",
        "bot_id": "222"
    }
  }
  

消息已完成

• 事件类型：conversation.message.completed
• 事件说明：消息已完成（用户或智能体）。此时事件中带有所有 message.delta 的拼接结果，且每个消息均为 completed 状态。
• 事件结构：

• 事件示例：

{
  "id": "event_1",
  "event_type": "conversation.message.completed",
  "data": {
    "id": "msg_002",
    "role": "assistant",
    "type": "function_call",
    "content": "{\"name\":\"toutiaosousuo-search\",\"arguments\":{\"cursor\":0,\"input_query\":\"今天的体育新闻\",\"plugin_id\":7281192623887548473,\"api_id\":7288907006982012986,\"plugin_type\":1}}",
    "content_type": "text",
    "chat_id": "123",
    "conversation_id": "123",
    "bot_id": "222"
  }
}

对话完成

• 事件类型：conversation.chat.completed
• 事件说明：表示对话已完成。
• 事件结构：

• 事件示例：

{
  "id": "event_1",
  "event_type": "conversation.chat.completed",
  "data": {
      "id": "123",
      "chat_id": "123",
      "conversation_id": "123",
      "bot_id": "222",
      "created_at": 1710348675,
      "completed_at": 1710348675,
      "last_error": null,
      "meta_data": {},
      "status": "completed",
      "usage": {
          "token_count": 3397,
          "output_tokens": 1173,
          "input_tokens": 2224
      }
  }   
}

端插件请求

• 事件类型：conversation.chat.requires_action
• 事件说明：对话中断，需要使用方上报工具的执行结果。
• 事件结构：

• 事件示例：

  {
      "id": "7446668538246561821",
      "event_type": "conversation.chat.requires_action",
      "data": {
          "id": "7434369946098090003",
          "conversation_id": "7434368393420996671",
          "bot_id": "7379165428687536166",
          "created_at": 1730949143,
          "completed_at": 1730949146,
          "last_error": {
              "code": 0,
              "msg": ""
          },
          "status": "requires_action",
          "usage": {
              "token_count": 0,
              "output_count": 0,
              "input_count": 0
          },
          "required_action": {
              "type": "submit_tool_outputs",
              "submit_tool_outputs": {
                  "tool_calls": [
                      {
                          "id": "BUJJS0JKQ0dHR0VeFkNCQF5HEEZBXhJFEUJeEhFCRkESSktDREISSUI=",
                          "type": "function",
                          "function": {
                              "name": "get_current_temperature",
                              "arguments":"{\'location\":\'深圳\'}"
                          },
                          "require_info": null
                      }
                  ]
              }
          },
          "section_id": "7434368393420996671"
      }
  } 
  

对话失败

• 事件类型：conversation.chat.failed
• 事件说明：此事件用于标识对话失败。
• 事件结构：

• 事件示例：

{
  "id": "event_1",
  "event_type": "conversation.chat.failed",
  "data": {
      "id": "123",
      "chat_id": "123",
      "conversation_id": "123",
      "bot_id": "222",
      "created_at": 1710348675,
      "failed_at": 1710348675,
      "last_error": {
          "code": 1,
          "msg": "发生异常"
      },
      "meta_data": {},
      "status": "failed",
      "usage": {
          "token_count": 3397,
          "output_tokens": 1173,
          "input_tokens": 2224
      }
  }   
}

用户开始说话

• 事件类型：audio.user.speech_started

• 事件说明：此事件表示服务端识别到用户正在说话。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为audio.user.speech_started。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "audio.user.speech_started",
    "data": {}
  }
  

用户结束说话

• 事件类型：audio.user.speech_stopped
• 事件说明：此事件表示服务端识别到用户已停止说话。
• 事件结构：

• 事件示例：

{
  "id": "event_1",
  "event_type": "audio.user.speech_stopped",
  "data": {}
}

智能体开始说话

• 事件类型：audio.agent.speech_started

• 事件说明：此事件表示智能体正在说话。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为audio.agent.speech_started。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "audio.agent.speech_started",
    "data": {}
  }
  

智能体结束说话

• 事件类型：audio.agent.speech_stopped

• 事件说明：此事件表示智能体已停止说话。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为audio.agent.speech_stopped。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "audio.agent.speech_stopped",
    "data": {}
  }
  

安抚配置更新成功

• 事件类型：session.pre_answer.updated

• 事件说明：房间内的安抚配置更新成功，返回房间内最新的安抚配置。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为 session.pre_answer.updated。
  data	Object	必选	事件数据，包含安抚策略的详细信息。
  data.pre_answer	Object	必选	安抚策略配置。
  data.pre_answer.type	String	必选	安抚策略类型，可选类型有： none：取消安抚策略，默认值。 audio：根据用户上传的音频文件作为安抚语。 text：根据用户输入的文本生成安抚语。 bot：指定另一个智能体作为安抚语的生成载体。
  data.pre_answer.file_id	String	可选	仅在 audio 模式下生效，用户需要先通过上传文件接口上传一个音频文件，传入该接口返回的 file_id。当前仅支持 wav/mp3 音频文件。
  data.pre_answer.pre_answer_list	Array	可选	仅在 text 模式下生效，用户可以输入一批文本，会在触发安抚策略时随机选取一段文本作为安抚语播放。
  data.pre_answer.bot_id	String	可选	仅在 bot 模式下生效，ASR 识别的文本会同时请求这个 BotID，并将该智能体回复的内容作为安抚语。传入的智能体必须是属于当前用户的智能体。该策略会消耗额外的 Token。
  data.trigger	Object	可选	安抚策略的触发配置。
  data.trigger.type	String	必选	安抚策略的触发类型，可选类型有： mandatory：必定触发安抚策略，默认值。 time-trigger：一段时间后模型没有生成回复，就会触发安抚策略。 event-driven：模型触发 function call 就会触发安抚策略。
  data.trigger.time_after	Integer	可选	仅在 time-trigger 模式下生效，指定在等待多长时间后触发安抚策略，单位为 ms，取值范围 [0, 3000]，默认值为 1500ms。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "session.pre_answer.updated",
    "data": {
        "pre_answer": {
            "type": "bot",
            "file_id": "",
            "pre_answer_list": [""],
            "bot_id": "23452423"
        },
        "trigger": {
            "type": "mandatory",
            "time_after": 1500
        }
    }
  }
  

安抚已生成

• 事件类型：conversation.chat.pre_answer

• 事件说明：此事件表明触发了安抚策略。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为 conversation.chat.pre_answer。
  data	Object	必选	事件数据，包含安抚语的详细信息。
  data.content	String	可选	安抚语的内容。若选择 audio 安抚策略，则该字段为空。
  data.usage	Object	可选	本次安抚语消耗的 Token 信息，仅在使用 bot 安抚策略时展示该字段。
  data.usage.token_count	Integer	可选	本次安抚语消耗的 Token 总数，包括 input 和 output 部分的消耗。
  data.usage.output_count	Integer	可选	output 部分消耗的 Token 总数。
  data.usage.input_count	Integer	可选	input 部分消耗的 Token 总数。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "conversation.chat.pre_answer",
    "data": {
        "content": "",
        "usage": {
            "token_count": 0,
            "output_tokens": 0,
            "input_tokens": 0
        }
    }
  }
  

用户语音识别字幕

• 事件类型：conversation.audio_transcript.delta

• 事件说明：用户语音识别的中间值，每次返回都是全量文本。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为conversation.audio_transcript.delta。
  data	Object	必选	事件数据，包含语音识别的中间值。
  data.content	String	必选	语音识别的中间值。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "conversation.audio_transcript.delta",
    "data": {
        "content": "今天的"
    }
  }
  

更新房间模式成功

• 事件类型：mode.updated
• 事件说明：房间模式更新成功，返回最新的房间模式设置。
• 事件结构：

• 事件示例：

{
    "id": "",
    "event_type": "mode.updated",
    "data": {
        "mode": "chat",
        "chat": {
            "user_language": "common"
        }
    }
}

用户开始说话

• 事件类型：input_audio_buffer.started

• 事件说明：表示服务端成功处理用户开始说话事件。

• 事件结构：

  参数	类型	是否必选	说明
  id	string	必选	服务端生成的唯一 ID。
  event_type	string	必选	固定为 input_audio_buffer.started。

• 事件示例：

  {
      "id": "7446668538246561827",
      "event_type": "input_audio_buffer.start",
      "data": {}
  }
  

用户结束说话

• 事件类型：input_audio_buffer.completed

• 事件说明：表示服务端成功处理用户结束说话事件。

• 事件结构：

  参数	类型	是否必选	说明
  id	string	必选	服务端生成的唯一 ID。
  event_type	string	必选	固定为 input_audio_buffer.completed。

• 事件示例：

  {
      "id": "7446668538246561827",
      "event_type": "input_audio_buffer.completed",
      "data": {}
  }
  

发生错误

• 事件类型：error

• 事件说明：对话过程中的错误事件。

• 事件结构：

  参数	类型	是否必选	说明
  id	String	必选	服务端生成的唯一 ID。
  event_type	String	必选	固定为error。
  data	Object	必选	事件数据，包含错误的详细信息。
  data.code	Integer	必选	错误码。错误码列表请参见Realtime 事件错误码。
  data.msg	String	必选	错误信息。
  data.detail	Object	必选	错误的详细信息。
  data.detail.logid	String	必选	服务端日志 ID。

• 事件示例：

  {
    "id": "event_1",
    "event_type": "error",
    "data": {
        "code": 1,
        "msg": "发生异常",
        "detail": {
            "logid": ""
        }
    }
  }