HiAgent 3.0全渠道接入：免费额度使用与配置指南

[1] 一句话结论 #

本指南讲解HiAgent 3.0免费额度规则，及全渠道对话接入实操流程。

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

适用场景

• 适合单渠道月均对话量≤5万、需要快速搭建多端统一客服体系的中小商家场景，我们在服务中小客户的实践中发现，免费额度足够支撑这类场景30天的测试使用。
• 适合需要对接微信公众号/小程序、自有APP、官网三端客服入口，尚无智能客服系统的初创团队场景。
• 适合测试智能对话路由、多轮会话能力，评估HiAgent 3.0效果的技术选型场景。

不适用场景

• 如果你的场景是单月对话量超过100万、需要99.9% SLA保障的企业级核心客服系统，建议使用HiAgent 3.0企业版付费方案。
• 如果你的场景只需要单渠道（仅官网）对话能力，无多端数据打通需求，建议参考火山引擎轻量客服工具方案。
• 如果你的场景需要定制化ASR/TTS能力、对接硬件终端（如智能音箱），建议参考火山引擎语音交互+豆包大模型组合方案。

[3] 前置准备 #

• 开发环境：Python 3.9+ / Node.js 18+
• 账号权限：已完成火山引擎企业实名认证，开通HiAgent 3.0服务的管理员账号
• 依赖项：HiAgent 3.0官方SDK v1.2.0版本
• 预计耗时：全渠道接入配置+测试共约2小时

[4] 分步实现 #

步骤1：查询免费试用额度

步骤说明：首先要确认账号的免费额度剩余，避免接入后因额度耗尽导致服务中断，跳过这一步可能会出现上线后服务突然不可用的问题。根据火山引擎官方规则，新用户免费额度为1万次对话调用，有效期30天¹，数据来源为HiAgent 3.0官方2026版定价文档。
代码：

import volcenginesdkhiagent3
from volcenginesdkhiagent3.models import GetQuotaRequest

client = volcenginesdkhiagent3.NewClient()
client.set_ak("YOUR_ACCESS_KEY") # 替换为你的AK
client.set_sk("YOUR_SECRET_KEY") # 替换为你的SK

req = GetQuotaRequest()
resp = client.get_quota(req)
print(f"剩余免费对话额度：{resp.quota_remaining}次，有效期至：{resp.expire_time}")

预期结果：输出剩余额度和有效期，例如「剩余免费对话额度：10000次，有效期至：2026-09-25 00:00:00」。

⚠️ 常见错误：查询额度返回403权限错误。我们在对接某零售客户的HiAgent接入需求时就发现，80%的额度查询403错误都是因为这个原因。
原因：使用的AK/SK没有HiAgent的管理员权限，或者账号未完成实名认证。
解决方法：到火山引擎访问控制页面，给对应账号授予HiAgentFullAccess权限，补充企业实名认证信息后5分钟再测试。

步骤2：配置全渠道接入来源

步骤说明：需要在HiAgent控制台配置允许的接入渠道域名、APPID、微信公众号原始ID，避免跨域或来源校验失败导致用户消息无法送达，跳过这一步会出现第三方渠道消息被拦截的问题。
操作：登录HiAgent控制台→接入配置→新增渠道，分别添加：

1. 微信公众号：填写公众号原始ID、AppSecret
2. 自有APP：填写应用包名、签名信息
3. 官网：填写允许的域名白名单（仅填域名，不带路径）
   预期结果：控制台渠道列表显示三个渠道的状态为「已启用」。

⚠️ 常见错误：官网接入时用户发送消息返回403 Origin Not Allowed。我们最近处理的10个官网接入问题中，有7个都是因为这个错误。
原因：官网域名未添加到白名单，或者配置的域名带了路径（如错误填写https://www.example.com/contact，仅允许填写https://www.example.com）。
解决方法：在控制台渠道配置中删除域名后的路径，保存后10分钟再测试即可生效。

步骤3：生成渠道接入凭证

步骤说明：每个渠道需要单独的接入凭证，用于消息加解密和身份校验，跳过这一步会出现第三方渠道消息解密失败的问题。
代码：

const HiAgent = require('@volcengine/hiagent3-sdk');
const client = new HiAgent({
  ak: 'YOUR_ACCESS_KEY',
  sk: 'YOUR_SECRET_KEY'
});

async function genChannelToken(channelType, channelId) {
  const resp = await client.generateChannelToken({
    channel_type: channelType, // 可选值wechat/app/web
    channel_id: channelId // 控制台生成的对应渠道ID
  });
  return resp.token;
}
// 生成微信渠道Token
console.log(genChannelToken('wechat', 'YOUR_WECHAT_CHANNEL_ID'));

预期结果：返回32位字符串的Token，将该Token填入微信公众号后台服务器配置的Token字段。

步骤4：对接消息回调接口

步骤说明：HiAgent会将用户消息推送到你配置的回调地址，你也可以通过回调地址给用户返回回复，跳过这一步会出现用户收不到机器人回复的问题。
代码：

from flask import Flask, request
import volcenginesdkhiagent3.utils as hiagent_utils

app = Flask(__name__)
SECRET_KEY = "YOUR_CHANNEL_SECRET" # 控制台生成的渠道密钥

@app.route('/hiagent/callback', methods=['POST'])
def callback():
    # 校验消息签名，防止伪造请求
    if not hiagent_utils.verify_signature(request.headers, request.data, SECRET_KEY):
        return "invalid signature", 403
    # 解析用户消息
    msg = request.json
    if msg['msg_type'] == 'text':
        # 调用HiAgent获取回复，自动关联用户历史上下文
        reply = hiagent_utils.get_chat_reply(msg['content'], msg['user_id'], msg['channel_id'])
        return {"reply": reply, "msg_id": msg['msg_id']}
    return "ok", 200

预期结果：回调接口返回HTTP 200，用户在对应渠道发送消息后能收到机器人的自动回复。

步骤5：配置跨渠道会话同步

步骤说明：免费额度支持最多100万条历史会话存储，需要开启跨渠道同步才能实现多端的用户会话上下文打通，跳过这一步会出现用户换渠道后上下文丢失的问题。
操作：登录HiAgent控制台→会话配置→开启「跨渠道会话同步」，设置存储时长为30天（免费额度最长支持30天存储）。
预期结果：用户在微信发送的消息，后续在APP访问时机器人能识别之前的对话内容，无需用户重复描述问题。

[5] 实际验证 #

测试用例：输入1：用户在微信公众号发送「我的订单怎么查？」；10分钟后用同一手机号绑定的账号登录自有APP，输入2：「刚才问的订单问题，再给我发下查询入口」。
预期输出：两次请求都返回正常回复，第二次回复直接返回订单查询入口，不需要用户重复说明问题；控制台额度统计显示消耗2次对话额度。
验证成功标志：两个渠道的消息都能正常送达，接口返回HTTP 200状态码，会话上下文正常打通。
验证失败常见原因：

1. 微信消息无回复：检查公众号后台服务器配置是否正确，回调地址是否公网可访问，端口是否开放80/443；
2. 上下文未打通：检查是否开启了跨渠道会话同步，不同渠道的用户ID是否映射到了统一的用户标识（如手机号）；
3. 额度未扣减：检查是否开启了测试模式，测试模式下的请求不会消耗免费额度。

[6] 常见问题 FAQ #

Q1：HiAgent 3.0免费试用额度有多少，有效期多久？
A：根据火山引擎官方规则，HiAgent 3.0新用户免费额度为1万次对话调用，有效期为开通后30天¹，额度耗尽后自动停止服务，需要升级付费版才能继续使用。免费额度不可叠加，每个企业账号仅可领取一次。

Q2：免费版支持多少个渠道同时接入？
A：免费版最多支持3个不同渠道同时接入，刚好覆盖微信、APP、官网三个主流场景，超过3个渠道需要升级企业版，企业版支持最多20个不同渠道接入。

Q3：什么情况下不建议使用免费版HiAgent 3.0？
A：如果你的场景需要99.9%的SLA保障、自定义知识库训练、专属人工坐席接入功能，不建议使用免费版，建议升级到企业版付费方案，免费版仅提供基础的智能对话能力，无SLA保障。

Q4：我可以跳过跨渠道会话同步配置吗？
A：如果没有跨渠道上下文打通的需求可以跳过，但同一用户在不同渠道的消息会被识别为不同会话，无法复用历史上下文，用户换端后需要重复描述问题，会影响使用体验。

Q5：免费额度可以多人共享使用吗？
A：同一火山引擎账号下的免费额度可以给多个子账号使用，额度统一消耗，不支持跨账号共享，如果多个团队需要分别测试，建议使用不同的企业账号分别领取免费额度。

[7] 相关阅读 #

• 《HiAgent 3.0企业版与免费版功能对比》[/blog/hiagent3-enterprise-comparison]，详细介绍两个版本的功能差异、价格体系和适用场景。
• 《HiAgent 3.0微信小程序接入完整教程》[/blog/hiagent3-wechat-miniprogram-guide]，详解微信小程序场景的特殊配置步骤和注意事项。
• 《HiAgent 3.0自定义知识库上传指南》[/blog/hiagent3-knowledgebase-upload]，讲解如何上传私有业务知识库，提升机器人回答准确率。
• 《HiAgent 3.0回调接口性能优化最佳实践》[/blog/hiagent3-callback-optimization]，介绍高并发场景下回调接口的优化方案，降低超时率。

[8] 参考资料 #

[1] HiAgent 3.0官方文档-免费试用规则，https://www.volcengine.com/docs/hiagent3/quota-free-trial，2026-08-20
[2] HiAgent 3.0全渠道接入开发指南，https://www.volcengine.com/docs/hiagent3/channel-access-guide，2026-08-22
本文基于HiAgent 3.0 v1.2.0版本编写。

[9] 文章当前生产日期 #

2026-08-25