n8n 多轮交互接口约定

1. 调用流程与职责

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

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

2. 请求与返回

2.1 公共请求

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

{
  "session_id": "<会话标识>",
  "content": "<本轮用户发言>",
  "history": "<历史对话>",
  "state": null,
  "context": {}
}

2.2 主路由返回

以上述空状态请求为例：

{
  "target_workflow": "<业务workflow标识>",
  "state": null
}

后端按 target_workflow 选择业务调用地址，沿用原请求的 session_id、content、history 和完整 context，将 state 设为主路由返回值，再请求目标业务。主路由保持 context 内容不变，由后端继续传递。

2.3 业务 Workflow 返回

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

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

{
  "code": "<话术编码>",
  "script": "<参考话术>",
  "data": null,
  "state": null,
  "context": {}
}

后端分别用完整 state、context 替换已保存值。

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

2.4 data：话术参数与后端动作

data 有值时包含以下两个字段；没有动作、话术动态参数或其他约定数据时，返回 data: null。

话术参数

后端根据 code 从话术库取得模板，再用 data.script_params 中的值填入模板。

例如，话术库中的 A_COMPLAINT_01（用 {{ }} 示意待填内容）：

关于合同 {{A_COMPLAINT_01.contract_no}} 的扣费问题，
我们预计在 {{A_COMPLAINT_01.feedback_days}} 个工作日内反馈。
你是否认可这个安排？

业务 Workflow 返回的相关字段：

{
  "code": "A_COMPLAINT_01",
  "data": {
    "action": null,
    "script_params": {
      "contract_no": "HT20260001",
      "feedback_days": 3
    }
  }
}

后端取出这条模板，将合同号填为 HT20260001、反馈天数填为 3，用户最终看到：

关于合同 HT20260001 的扣费问题，
我们预计在 3 个工作日内反馈。
你是否认可这个安排？

话术库负责模板，业务 Workflow 提供本次要填入的值，后端完成填充和展示。

每条话术需要哪些参数，由话术库与业务 Workflow 共同约定；同一编码下的候选话术使用相同参数。业务提供完整值，后端展示前检查是否齐全。

后端动作

例如 data.action: "TRANSFER_COLLECTIONS" 表示请求转催收人工客服。后端负责执行转接、确认结果，并处理失败情况；转接成功后进入人工服务流程。

data 用于本轮展示与动作处理，state 用于下一轮业务续接，两者独立。

3. state 与 context

state 保存业务处理进度，context 保存会话参数。后端保存两者，并在下一轮请求时传入。

3.1 state：下一轮如何继续业务

state 保存当前业务的处理进度，以及下一轮继续处理所需的业务变量。没有待继续的业务时，返回 null。

有待续接业务时使用以下结构，两处 <业务workflow标识> 保持一致：

{
  "routing": {
    "active_workflow": "<业务workflow标识>"
  },
  "workflows": {
    "<业务workflow标识>": {
      "status": "waiting_input",
      "resume_from": "<续接入口>"
    }
  }
}

例如，业务询问用户是否认可安排后，将 resume_from 设为 handle_feedback。后端保存这份状态。下一轮主路由确认继续该业务后，业务新执行从入口开始，通过 Switch 进入处理反馈的分支。没有本业务记录时，从首次处理分支开始。

业务变量保存在 state.workflows.<业务workflow标识>.variables 中，例如验证码已尝试次数；业务按需提供，没有跨轮变量时可以省略。

3.2 主路由如何交接 state

• target_workflow：本轮调用哪个业务 Workflow。
• state.routing.active_workflow：当前保留的是哪个业务的续接状态。

主路由根据本轮对话，按以下规则保留或清空 state。

例如，投诉处理中，用户说“你理解错了”，主路由选择 other 进行澄清，同时保留投诉状态。因此，本轮调用目标是 other，状态中保存的业务仍是投诉。下一轮再由主路由结合对话与状态判断归属。

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

3.3 context：会话参数如何保留和更新

context 保存同一个 session_id 会话期间可跨轮、跨业务使用的参数，例如合同号、手机号。

例如，后端已保存合同号，请求中的会话参数为：

{
  "context": {
    "contract_no": "HT20260001"
  }
}

用户本轮补充手机号，业务保留原合同号，并返回更新后的完整参数：

{
  "context": {
    "contract_no": "HT20260001",
    "phone_no": "13800000000"
  }
}

后端保存返回的完整 context，下一轮继续传入。业务根据本轮已确认的信息补充或更新参数，保留其他已有字段；无变化时原样返回，尚无参数时为 {}。

业务交互完成或切换时，state 可以清空，已有 context 继续保留。

4. 业务扩展项

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

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