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_id、content、history 和可选 context，将 state 设为主路由返回值，再请求目标业务。

2.3 业务 Workflow 返回

所有业务 Workflow（包括 other）统一返回 code、script 和 state。

交互完成时的返回：

{
  "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 保留上轮业务处理形成的值。二者按具体业务需要使用。

查看完整调用示例 →　context 与 variables 示例 →