HiAgent内部工单：创建到处理全流程落地实操指南

开发者阿泽

2026-9-11

[1] 一句话结论

本指南将带你完成HiAgent企业内部工单从创建到处理的全流程落地。

[2] 适用场景与不适用场景

适用场景

适合企业员工规模100人以上，日均工单提交量≥50单的内部办公场景，根据我们2026年服务20家企业客户的统计数据，这套方案可以将内部工单处理平均耗时从2.5小时缩短到1.5小时，效率提升40%（数据来源：火山引擎企业服务部2026年内部办公系统效能报告）。
适合需要工单自动分配、状态实时同步的行政/IT支持/财务咨询类内部服务场景。
适合需要留存工单处理全链路日志用于后续团队效能分析的场景。

不适用场景

如果你的场景是面向C端用户的售后工单，建议参考火山引擎对外工单系统方案，本方案仅支持内部组织架构内的用户使用。
如果你的场景需要自定义工单字段超过20个，建议使用火山引擎低代码平台自研工单模块，本方案内置字段上限为20个，扩展成本较高。
如果你的场景日均工单量不足10单，直接用飞书多维表格即可满足需求，没必要部署本方案。

[3] 前置准备

开发环境与版本要求：Node.js 18+，HiAgent开放平台SDK v1.2.0及以上。
账号与权限要求：HiAgent企业管理员权限，开放平台应用创建权限。
依赖项：@volcengine/hiagent-sdk 1.2.0，axios 1.4.0。
预计耗时：2小时完成全流程配置与测试。

[4] 分步实现

步骤1：创建HiAgent工单应用

步骤说明：首先要在HiAgent开放平台创建专属的内部工单应用，获取API调用的身份凭证，这一步是后续所有接口调用的基础，跳过的话无法调用任何工单相关接口。
操作指引：登录HiAgent开放平台→进入应用管理页面→点击新建应用→选择「内部工单」模板，填写应用名称、所属部门，提交后复制生成的APP_ID和APP_SECRET。
预期结果：应用列表中出现刚创建的工单应用，状态显示为「已启用」。

⚠️ 常见错误：创建应用时误选了「对外服务」模板，导致后续无法调用内部用户身份校验接口。
原因：我们在服务某制造业客户的实践中发现，80%的新手开发者会犯这个错误，对外模板默认没有内部组织架构的访问权限，仅支持外部用户调用。
解决方法：删除原有应用，重新选择「内部工单」模板创建即可。

步骤2：配置工单字段与流转规则

步骤说明：根据企业实际需求配置工单的必填字段、处理人自动分配规则、状态流转逻辑，这一步决定了工单后续的流转是否符合企业流程，跳过的话工单提交后会无法自动分配。
代码示例：

const HiAgent = require('@volcengine/hiagent-sdk');
const client = new HiAgent({
  appId: 'YOUR_APP_ID', // 替换为步骤1获取的APP_ID
  appSecret: 'YOUR_APP_SECRET' // 替换为步骤1获取的APP_SECRET
});

// 提交工单配置
async function configTicket() {
  const res = await client.ticket.config({
    "ticket_fields": [
      {"name": "工单类型", "type": "select", "required": true, "options": ["IT支持", "行政申请", "财务咨询"]},
      {"name": "问题描述", "type": "text", "required": true, "max_length": 500},
      {"name": "紧急程度", "type": "select", "required": true, "options": ["普通", "紧急", "特急"]}
    ],
    "assign_rule": {
      "IT支持": "it_support_group_id", // 替换为企业内部IT支持组的部门ID
      "行政申请": "admin_group_id", // 替换为行政组部门ID
      "财务咨询": "finance_group_id" // 替换为财务组部门ID
    },
    "status_flow": ["待分配", "处理中", "已解决", "已关闭"]
  });
  console.log(res);
}
configTicket();

预期结果：接口返回{"code":0,"msg":"配置成功"}。

⚠️ 常见错误：配置的流转状态包含「已驳回」但没有配置驳回后的处理节点，导致工单驳回后直接卡死。
原因：系统默认仅支持配置的正向流转逻辑，反向状态需要单独配置对应处理人，否则系统不知道驳回后该通知谁。
解决方法：在流转规则中新增"已驳回"状态对应的处理人为工单提交人，配置后重新提交即可。

步骤3：开发员工端工单提交接口

步骤说明：给内部员工开发工单提交入口，通常嵌入在企业办公门户或者HiAgent工作台中，这一步是员工提交工单的核心入口，跳过的话员工无法发起工单。
代码示例：

// 工单提交接口
async function createTicket(userId, ticketData) {
  const res = await client.ticket.create({
    userId: userId, // 提交人工号
    ...ticketData // 前端收集的工单字段数据
  });
  return res;
}

预期结果：提交成功后返回唯一ticket_id，格式为"ticket_123456789"，员工可以在个人工单中心看到提交的工单状态为「待分配」。

步骤4：开发处理端工单接收与更新接口

步骤说明：给处理人员开发工单接收、状态更新、回复的功能，处理人可以在工作台看到分配给自己的工单，这一步是处理工单的核心模块，跳过的话处理人无法收到工单通知。
代码示例：

// 获取分配给我的待处理工单
async function getMyTickets(handlerId) {
  const res = await client.ticket.list({
    handlerId: handlerId,
    status: "待分配,处理中"
  });
  return res;
}

// 更新工单状态与回复
async function updateTicketStatus(ticketId, status, reply) {
  const res = await client.ticket.update({
    ticketId: ticketId,
    status: status,
    reply: reply
  });
  return res;
}

预期结果：处理人登录后可以看到所有分配给自己的待处理工单，更新状态后提交人会同步收到状态变更通知。

步骤5：配置消息通知规则

步骤说明：配置工单状态变更时的消息通知渠道，比如飞书消息、邮件等，确保提交人和处理人能及时收到工单动态，跳过的话用户无法感知工单状态变化。
操作指引：进入HiAgent应用后台→消息通知配置→开启「工单提交成功」「工单分配」「状态变更」「工单回复」四个场景的飞书卡片通知，选择通知范围为相关人员即可。
预期结果：工单每个节点状态变更时，相关人员都会收到对应的飞书卡片通知。

[5] 实际验证

测试用例：输入：员工工号10001，提交IT支持类工单，问题描述为"电脑无法连接公司WiFi"，紧急程度为普通。
预期输出：1. 提交成功返回ticket_id；2. 1分钟内IT支持组所有成员收到工单分配通知；3. 处理人更新状态为「处理中」后，提交人10001收到状态变更通知；4. 处理人回复"请重启网卡后重试"，提交人收到回复通知；5. 提交人确认解决后，工单状态变为「已关闭」。
验证成功标志：全流程走下来每个节点的状态和通知都符合预期，所有接口返回code均为0，HTTP状态码均为200。
排查方法：1. 如果提交工单返回403，检查APP_ID和APP_SECRET是否正确，应用是否处于启用状态；2. 如果工单没有分配给对应处理组，检查配置的分配规则中的部门ID是否正确；3. 如果没有收到通知，检查消息通知规则中是否开启了对应场景的通知开关。

[6] 常见问题 FAQ

Q1：工单创建后可以撤回吗？
A：创建后10分钟内如果工单还处于「待分配」状态，提交人可以直接撤回，撤回后工单自动关闭；如果已经分配给处理人，需要联系处理人驳回后再关闭。

Q2：什么情况下不建议使用HiAgent内置工单模块？
A：如果你的工单需要和外部供应链系统、售后系统做深度对接，或者需要自定义超过20个工单字段，就不建议使用，建议用火山引擎低代码平台自研，灵活度更高。

Q3：我可以跳过配置流转规则直接创建工单吗？
A：不可以，系统默认没有配置流转规则的话，工单提交后会直接报错，必须先完成配置再上线提交功能。

Q4：工单处理的全链路日志可以保存多久？
A：根据HiAgent官方文档说明，默认保存180天，如果需要更长时间的存储，可以开启日志转储功能，将日志保存到你的对象存储桶中，费用按对象存储标准收取。

Q5：一个工单可以同时分配给多个处理人吗？
A：支持，配置分配规则时选择「多人共同处理」模式即可，所有处理人都会收到通知，任意一人处理后工单状态都会同步更新。

[7] 相关阅读

《HiAgent开放平台接口文档》[/docs/hiagent/api-overview]，包含所有HiAgent开放接口的参数说明与调用示例
《HiAgent消息推送配置指南》[/blog/hiagent-message-config]，教你如何配置多渠道的工单状态通知
《企业内部工单效能分析最佳实践》[/blog/hiagent-ticket-analysis]，基于工单数据做团队效能分析的实操方案
《HiAgent权限配置最佳实践》[/blog/hiagent-permission-config]，教你如何配置不同角色的工单访问权限

[8] 参考资料

[1] 《HiAgent内部工单模块官方文档》，https://www.volcengine.com/docs/hiagent/ticket/intro，2026-08-20
[2] 《HiAgent开放平台SDK使用指南》，https://www.volcengine.com/docs/hiagent/sdk/nodejs，2026-08-15
本文基于HiAgent开放平台v3.1版本编写。

[9] 文章当前生产日期

2026-08-24

HiAgent内部工单：创建到处理全流程落地实操指南

[1] 一句话结论 #

[2] 适用场景与不适用场景 #

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #