n8n 多轮交互接口约定

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

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

1. 调用流程与职责

每轮自动交互对应两次独立请求：后端先请求主路由，再请求选中的业务 Workflow。两类 Workflow 各自通过 Webhook 接收请求并返回响应。

后端先请求主路由，再请求业务 Workflow；各自返回响应主路由后端业务 Workflow1. session_id · content · historystate · contextstate、context = 后端保存值2. target_workflow · state本轮调用目标与交接状态3. session_id · content · historystate · contextstate = 路由返回值；context 沿用4. code · script · script_paramsaction · state · context后端填充话术、执行动作、保存参数与状态
  1. 后端 → 主路由session_id · content · history · state · contextstate、context = 后端保存值
  2. 主路由 → 后端target_workflow · state本轮调用目标与交接状态
  3. 后端 → 业务 Workflowsession_id · content · history · state · contextstate = 路由返回值；context 沿用
  4. 业务 Workflow → 后端code · script · script_params · action · state · context后端填充话术、执行动作、保存参数与状态
参与方职责
后端提供对话、state 与 context；按 target_workflow 请求业务；按 code 取话术模板、用 script_params 填充动态字段，按 action 执行动作，保存完整 state 与 context。
主路由结合本轮输入、历史对话、业务状态与会话参数选择本轮目标；决定 state 保留或清空，读取 context 辅助判断。
业务 Workflow处理本轮输入，组织当前话术需要的动态参数，返回 code、script、script_params、action、完整 state 与 context，结束本轮执行。
other Workflow处理需求不明确等情况，返回澄清或兜底话术的编码与联调参考，保留已有业务状态与会话参数。

同一会话只保留一个待续接业务。继续自动交互时，下一轮由后端携带新的对话、最新 state 与 context，再次请求主路由。

2. 请求与返回

2.1 公共请求

后端请求主路由和业务 Workflow 时，使用同一套字段。以下为尚无续接状态与会话参数时的请求结构：

{
  "session_id": "<会话标识>",
  "content": "<本轮用户发言>",
  "history": "<历史对话>",
  "state": null,
  "context": {}
}
字段类型提供方式含义
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 设为主路由返回值，再请求目标业务。主路由保持 context 内容不变，由后端继续传递。

2.3 业务 Workflow 返回

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

交互完成、话术无动态参数、无需后端动作且尚无会话参数时的返回：

{
  "code": "<话术编码>",
  "script": "<参考话术>",
  "script_params": {},
  "action": null,
  "state": null,
  "context": {}
}
字段类型含义
codestring话术编码，后端据此从话术库选择模板。
scriptstring已代入本轮动态参数的参考话术，用于开发联调和调用测试。
script_paramsobject当前 code 所需的话术参数，供后端替换模板中的动态字段；没有动态参数时为 {}。
actionstring 或 null需要后端执行的单个动作标识；无需执行动作时返回 null。
stateobject 或 null本轮处理后的完整续接状态。仍需用户反馈时返回状态对象；无待续接业务时返回 null。
contextobject本轮处理后的完整会话参数。已有参数继续保留，业务按本轮结果补充或更新；尚无参数时为 {}。

后端按 code 取得模板，用 script_params 填充后展示；按 action 调用约定的动作处理逻辑，并分别用完整 state、context 替换已保存值。

同一业务可以根据不同处理结果返回不同 code。话术含义应与本轮动作、后续状态保持一致，例如等待用户确认时，对应话术应询问是否认可。

2.4 动态话术

话术库用 <话术编码>.<参数名> 标识动态字段。script_params 的键使用参数名，后端以 code + "." + 参数名 对应模板字段。例如 A_COMPLAINT_01.contract_no 对应本轮 script_params.contract_no。

  • 业务 Workflow 从会话参数、业务接口或本轮处理结果中组织话术参数。
  • 每个 code 约定所需参数的名称与含义；业务完整提供，后端展示前检查是否齐全。
  • 同一 code 下的候选话术共用同一套参数约定。
  • script_params 用于本轮话术展示；下一轮按现有请求结构传入 state、context 等字段。

2.5 后端动作

业务 Workflow 返回动作标识，后端负责执行并确认结果。例如 action: "TRANSFER_COLLECTIONS" 表示请求转催收人工客服，话术可表达“将为你转接”；转接成功或失败由后端实际执行结果确定。

action 表达本轮要执行的动作，state 表达业务是否需要下一轮续接，两者独立：

处理结果actionstate
仅询问用户，等待反馈null续接状态对象
请求执行动作，之后仍需用户反馈约定的动作标识续接状态对象
请求转人工，当前业务自动交互结束"TRANSFER_COLLECTIONS"null
正常结束，无后端动作nullnull

转人工场景中，后端负责转接失败的反馈与后续处理；转接成功后进入人工服务流程。

3. state 与 context

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 生成和更新具体业务状态。这里的“完成”指本项对话交互完成，外部业务事项按各自流程继续处理。

3.4 会话参数的保留与更新

context 在同一个 session_id 的会话期间保留，供不同轮次、不同业务使用。业务完成或切换时，state 可以清空，已有 context 继续传递。

  • 后端传入当前保存的完整 context。
  • 业务在传入参数的基础上补充或更新本轮已确认的信息，保留其他已有字段。
  • 参数无变化时原样返回；后端保存完整返回值，下一轮继续传入。
字段用途示例
context会话期间可跨轮复用的会话参数合同号、手机号。
script_params当前话术模板所需的展示参数本轮话术使用的合同号、预计反馈天数。
state当前待续接业务及其处理位置等待用户确认，下一轮进入反馈分支。
state.variables当前业务记录中需跨轮保留的业务变量验证码尝试次数。

4. 业务扩展项

扩展项定义与使用
业务 Workflow 标识各业务定义标识；主路由据此选择，后端维护标识到调用地址的映射。
code 取值按业务处理结果约定话术编码，与后端话术库对应。
script_params 内部字段按 code 约定话术参数的名称与含义；业务提供值，后端填入模板。
action 取值业务与后端共同约定动作标识，由后端维护标识到处理逻辑的映射。
resume_from 取值各业务定义可续接入口，并配置对应的入口 Switch 分支。
variables 内部字段业务定义需跨轮保留的值，随 state 返回并由后端保存。
context 内部字段按业务约定会话参数的字段与来源；后端传入，业务补充或更新，完整回传后由后端保存。

合同号与手机号在示例中均使用字符串。手机号是否验证通过、是否与合同匹配，由相应业务校验结果确定。

查看完整调用示例 →　动态话术与参数示例 →