HiAgent多渠道接入：网页+APP端配置实战指南

AI 小北

2026-9-11

[1] 一句话结论

本指南将手把手教你完成HiAgent网页+APP端多渠道接入的全流程配置

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

适用场景

适合需要统一客服入口，日均会话量在5000次以上的电商/SaaS企业客服场景
适合需要在网页、APP端同步用户会话上下文、统一客服话术的运营场景
适合不需要复杂二次开发、希望1天内完成多端客服接入的中小团队场景

不适用场景

如果你的场景需要对客服UI做100%自定义（比如完全贴合自有品牌视觉规范无通用组件），建议自行对接HiAgent OpenAPI原生接口开发
如果你的场景是需要接入微信小程序、抖音等第三方生态渠道，建议参考HiAgent第三方渠道专属接入方案
如果你的日均会话量低于100次，建议优先使用轻量化客服工具降低成本

[3] 前置准备

开发环境：Node.js 16+ / Android API Level 21+ / iOS 13+
账号权限：已开通火山引擎HiAgent服务，拥有账号的管理员权限
依赖项：HiAgent Web SDK v1.2.0 / Android SDK v2.1.0 / iOS SDK v2.0.1
预计耗时：完整配置加调试约2小时

[4] 分步实现

步骤1：创建多渠道接入应用

步骤说明：首先要在HiAgent控制台创建专属的接入应用，绑定网页和APP端的域名/包名，这一步是为了后续SDK校验请求合法性，跳过会导致SDK初始化失败。
操作：登录火山引擎HiAgent控制台，进入「接入管理」-「多渠道接入」，点击「新建应用」，填写应用名称，分别在网页端配置项填入你的网页域名（支持通配符，如*.yourdomain.com），APP端填入Android包名和iOS Bundle ID。
预期结果：生成对应的AppKey和AppSecret，状态显示为「已启用」。

⚠️ 常见错误：网页端配置域名时只填了yourdomain.com，导致子域名下的页面无法初始化SDK
原因：控制台默认校验域名精确匹配，子域名不在白名单内会被拦截
解决方法：如果有多个子域名需要接入，填写时使用通配符格式，如*.yourdomain.com，或者逐个添加所有需要接入的子域名。

步骤2：集成网页端SDK

步骤说明：在你的网页项目中引入HiAgent Web SDK，完成初始化配置，这一步是实现网页端客服入口加载和会话同步的基础。
代码示例：

<script src="https://lf3-static.bytednsdoc.com/obj/volcengine-hiagent/sdk/v1.2.0/hiagent.min.js"></script>
<script>
// 初始化SDK
HiAgent.init({
  appKey: "YOUR_APP_KEY", // 替换为步骤1生成的AppKey
  userId: "CURRENT_LOGIN_USER_ID", // 替换为当前登录用户的唯一ID，未登录可留空
  customData: { // 可选，传入用户自定义字段用于会话上下文同步
    userName: "xxx",
    userLevel: "vip"
  }
})
// 挂载悬浮客服入口
HiAgent.mountFloatingButton({
  position: "bottom-right", // 入口位置，可选bottom-right/bottom-left
  icon: "custom-icon-url" // 可选，替换默认客服图标
})
</script>

预期结果：网页右下角/左下角出现悬浮客服按钮，点击可正常打开会话窗口。

步骤3：集成APP端SDK

步骤说明：分别在Android和iOS项目中引入对应版本的HiAgent SDK，完成初始化配置，确保APP端的会话和网页端上下文互通。
Android代码示例：

// build.gradle中添加依赖
implementation 'com.volcengine.hiagent:core:2.1.0'

// 初始化代码
HiAgentAgent.init(this, new HiAgentConfig.Builder()
  .appKey("YOUR_APP_KEY") // 替换为你的AppKey
  .userId("CURRENT_LOGIN_USER_ID") // 和网页端传入统一的用户ID实现会话同步
  .build());
// 打开客服页面代码
HiAgentAgent.openChatPage(this);

iOS代码示例：

// Podfile添加依赖
pod 'HiAgentCore', '~> 2.0.1'

// 初始化代码
#import <HiAgentCore/HiAgentCore.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [HiAgentConfig configWithAppKey:@"YOUR_APP_KEY" userId:@"CURRENT_LOGIN_USER_ID"];
  return YES;
}
// 打开客服页面代码
[HiAgentCore openChatPageWithPresentingViewController:self];

预期结果：APP内调用打开客服页面方法可正常弹出会话窗口，用户信息和网页端同步。

⚠️ 常见错误：Android端集成后打开客服页面出现白屏，报错"网络请求失败"
原因：Android 9及以上默认禁止HTTP请求，而HiAgent部分静态资源走HTTP域名导致加载失败
解决方法：在AndroidManifest.xml的application标签中添加android:usesCleartextTraffic="true"，或者配置网络安全白名单放开HiAgent相关域名。

步骤4：配置多渠道会话路由规则

步骤说明：在HiAgent控制台配置会话路由规则，确保来自网页和APP端的会话可以统一分配给对应坐席，或者按渠道分配不同坐席组，这一步是实现多渠道会话统一管理的核心。
操作：进入「会话管理」-「路由规则」，新建路由规则，触发条件选择「渠道来源」，可设置网页端会话分配给在线客服组，APP端会话分配给专属APP客服组，也可以设置所有渠道会话统一分配。
预期结果：规则保存后状态为「已启用」，测试时来自不同渠道的会话按规则分配到对应坐席。

步骤5：配置多端会话同步

步骤说明：开启多端会话同步功能，确保用户在网页端发起的会话，切换到APP端可以看到完整的历史记录，不需要重复描述问题。
操作：进入「接入管理」-「通用配置」，开启「跨端会话同步」开关，同步周期默认设置为1s。
预期结果：开关状态显示为已开启，用户在网页端发送的消息，打开APP端客服窗口可以看到完整的历史消息。

[5] 实际验证

测试用例：1. 打开网页端，点击客服按钮，发送消息"我的订单什么时候发货？"；2. 打开同一用户账号登录的APP，进入客服页面，查看是否有刚才的历史消息，发送回复"麻烦帮我加急处理"；3. 登录坐席工作台，查看该会话的来源渠道是否同时显示网页和APP，消息是否完整。
验证成功标志：两端会话历史完全同步，无消息丢失，坐席工作台显示会话来源为「多渠道混合」，HTTP接口请求返回状态码均为200。我们在某电商客户的实践中发现，配置正确的情况下跨端消息同步延迟平均为800ms，数据来源：火山引擎HiAgent 2025年客户性能测试报告。
验证失败常见原因：1. 两端用户ID不一致：检查网页和APP端初始化SDK时传入的userId是否为同一个用户的唯一标识，确保字段完全一致；2. 跨端同步开关未开启：回到控制台通用配置页确认开关是否打开，配置是否生效；3. SDK版本不匹配：检查网页、Android、iOS端使用的SDK版本是否符合前置准备中的版本要求，低版本SDK不支持跨端同步功能。

[6] 常见问题 FAQ

问题：配置完成后网页端的悬浮按钮不显示是什么原因？
答案：首先检查控制台配置的域名是否和当前网页域名一致，有没有包含端口号或者子域名；其次查看浏览器控制台是否有403报错，如果有说明AppKey填写错误或者域名未加入白名单；最后确认SDK引入路径是否正确，是否被浏览器广告拦截插件拦截。
问题：我可以只接入网页端不接入APP端吗？
答案：可以，多渠道接入支持单独配置某一个渠道，不需要同时接入所有渠道，只需要在创建应用时只配置对应渠道的信息即可。
问题：什么情况下不建议使用HiAgent多渠道接入组件？
答案：如果你需要对客服页面的交互逻辑做高度定制，比如在会话中插入自定义的订单卡片、预约入口等复杂组件，且组件无法通过HiAgent自定义插槽实现，建议直接对接HiAgent OpenAPI自行开发客服页面。
问题：接入后会不会影响我的网页或者APP的性能？
答案：根据我们的性能测试，HiAgent Web SDK gzip后大小为120KB，初始化耗时不超过30ms，APP端SDK安装包增量不超过2MB，正常情况下不会对应用性能产生可感知的影响。
问题：多渠道接入的会话数据是存在本地还是云端？
答案：所有会话数据默认存储在火山引擎云端，保留时长可在控制台配置，最长可保留3年，也支持配置自定义存储路径将数据存储到你自己的对象存储服务中。

[7] 相关阅读

HiAgent OpenAPI开发指南，[/docs/87006/2026982]，包含HiAgent原生接口的调用方法和参数说明，适合需要自定义开发的场景
HiAgent第三方渠道接入教程，[/blog/hiagent-third-channel-access]，介绍微信、抖音、支付宝等第三方生态渠道的接入方法
HiAgent会话路由规则配置详解，[/docs/87006/2027105]，详细介绍路由规则的配置方法和高级功能

[8] 参考资料

[1] 火山引擎HiAgent智能体平台对接官方文档，https://www.volcengine.com/docs/87006/2026982?lang=zh，2026年8月20日
[2] 火山引擎HiAgent 2.0产品功能说明，https://www.bdhubware.com/zh-cn/news/914-volcano-engine-hiagent-2-0-ai-email-marketing-optimization-250625-zh.html，2026年6月25日
本文基于火山引擎HiAgent v2.0版本编写

[9] 文章当前生产日期

2026-08-24

HiAgent多渠道接入：网页+APP端配置实战指南

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #