n8n 多轮交互接口约定

适用于需要用户补充信息、确认处理结果或继续追问的多轮交互。采用“每轮新执行 + 状态回传”,会话状态由后端保存。

下载 HTML 下载接口约定 MD 下载调用示例 MD

1. 调用流程与职责

每轮用户消息对应两次独立请求:后端先请求主路由,再请求选中的业务 Workflow。两类 Workflow 各自通过 Webhook 接收请求并返回响应。

后端先请求主路由,再请求业务 Workflow;各自返回响应主路由后端业务 Workflow1. session_id · content · history · statecontext(可选);state = 上轮保存值2. target_workflow · state本轮调用目标与交接状态3. session_id · content · history · statecontext(可选);state = 主路由返回值4. code · script · state后端按 code 查库展示,保存 state
  1. 后端 → 主路由session_id · content · history · statecontext(可选);state = 上轮保存值
  2. 主路由 → 后端target_workflow · state本轮调用目标与交接状态
  3. 后端 → 业务 Workflowsession_id · content · history · statecontext(可选);state = 主路由返回值
  4. 业务 Workflow → 后端code · script · state后端按 code 查库展示,保存 state
参与方职责
后端提供对话和已保存的状态;按 target_workflow 请求业务;按 code 从话术库选择并展示话术,保存完整 state
主路由结合本轮输入、历史对话和已有状态,选择本轮目标;决定原状态保留或清空。
业务 Workflow处理本轮输入,返回话术编码 code、联调参考 script 和完整 state,结束本轮执行。
other Workflow处理需求不明确等情况,返回澄清或兜底话术的编码与联调参考,保留已有业务状态。

同一会话只保留一个待续接业务。下一轮由后端携带新的对话与最新状态,再次请求主路由。

2. 请求与返回

2.1 公共请求

后端请求主路由和业务 Workflow 时,使用同一套字段。以下为尚无续接状态时的请求结构:

{
  "session_id": "<会话标识>",
  "content": "<本轮用户发言>",
  "history": "<历史对话>",
  "state": null
}
字段类型提供方式含义
session_idstring每轮传入会话标识。后端据此保存、取回状态与历史对话。
contentstring每轮传入本轮用户发言。
historystring每轮传入本轮之前的历史对话内容。
stateobject 或 null每次请求传入请求主路由时使用上轮保存的状态;请求业务 Workflow 时使用本轮主路由返回的状态。
contextobject按需传入对话之外的业务背景,例如后端已查询到的服务资格、产品信息。

2.2 主路由返回

以上述空状态请求为例:

{
  "target_workflow": "<业务workflow标识>",
  "state": null
}
字段类型含义
target_workflowstring本轮需要调用的业务 Workflow 标识。需求不明确时选择 other
stateobject 或 null交给本轮业务的状态;保留或清空规则见第 3 节。

后端按 target_workflow 选择业务调用地址,沿用原请求的 session_idcontenthistory 和可选 context,将 state 设为主路由返回值,再请求目标业务。

2.3 业务 Workflow 返回

所有业务 Workflow(包括 other)统一返回 codescriptstate

交互完成时的返回:

{
  "code": "<话术编码>",
  "script": "<参考话术>",
  "state": null
}
字段类型含义
codestring话术编码,后端据此从话术库选择实际展示的话术。
scriptstring参考话术,用于开发联调和调用测试时核对本轮处理结果。
stateobject 或 null本轮处理后的完整续接状态。仍需用户反馈时返回状态对象;无待续接业务时返回 null

后端根据 code 查询并展示话术,用业务返回的整份 state 替换本轮保存的状态,下一轮随请求传入主路由。

同一业务可以根据不同处理结果返回不同 code。编码对应的话术含义与 state 的后续处理保持一致,例如等待用户确认时,对应话术应询问是否认可。

3. state 结构与流转

3.1 状态结构

state: null 表示没有待续接业务。有待续接业务时使用以下结构,两处 <业务workflow标识> 保持一致:

{
  "routing": {
    "active_workflow": "<业务workflow标识>"
  },
  "workflows": {
    "<业务workflow标识>": {
      "status": "waiting_input",
      "resume_from": "<续接入口>"
    }
  }
}
字段类型含义与更新方
routing.active_workflowstring当前待续接的业务 Workflow 标识,由业务根据处理结果设置。
workflowsobject以业务 Workflow 标识为键,保存当前业务的一份续接记录,由业务 Workflow 更新。
workflows.<业务workflow标识>.statusstring当前记录使用 waiting_input,表示等待用户反馈。
workflows.<业务workflow标识>.resume_fromstring下一轮进入的业务处理分支,由该业务定义取值并更新。
workflows.<业务workflow标识>.variablesobject,可选该业务需要跨轮保留的值,内部字段由业务按需定义和更新。

每次业务新执行从入口开始:没有本业务记录时进入首次处理;已有记录时,通过入口 Switch 按 resume_from 进入相应分支。

3.2 本轮目标与待续接业务

字段表达什么
target_workflow本轮调用哪个业务,由主路由返回。
state.routing.active_workflow当前保存了哪个业务的续接状态,由业务 Workflow 返回。

需求不明确时,本轮目标可以是 other,已有状态仍指向原业务。other 返回澄清话术编码及联调参考,保留原状态,下一轮再由主路由判断归属。

3.3 状态流转

本轮情况主路由返回业务 Workflow 返回的 state
首次进入目标业务标识 + state: null需要反馈时生成状态;交互完成时为 null
继续当前业务当前业务标识 + 原状态。按本轮结果更新状态;交互完成时为 null
明确切换业务新业务标识 + state: null新业务从首次处理开始,返回自身状态,或完成后返回 null
需求不明确target_workflow: "other" + 原状态。保留原状态。

主路由决定旧续接状态的保留或清空;业务 Workflow 生成和更新具体业务状态。这里的“完成”指本项对话交互完成,外部业务事项按各自流程继续处理。

4. 业务扩展项

扩展项定义与使用
业务 Workflow 标识各业务定义标识;主路由据此选择,后端维护标识到调用地址的映射。
code 取值按业务处理结果约定话术编码,与后端话术库对应。
resume_from 取值各业务定义可续接入口,并配置对应的入口 Switch 分支。
variables 内部字段业务定义需跨轮保留的值,随 state 返回并由后端保存。
context 内部字段后端按需提供业务背景;同一轮的两次请求均携带该背景。

context 提供本轮处理所需的额外资料;variables 保留上轮业务处理形成的值。二者按具体业务需要使用。