跳到主要内容

C2AI2X 接入模式

本文件用于帮助外部接入方选择最适合自己的 C2AI2X 接入模式，并把每条路线的“你需要做什么”讲清楚。

适合需要比较接入成本与深度的技术负责人、产品负责人，以及已经决定接入但尚未确定是否必须使用 Full API 的团队。若只想立即生成入口，可直接前往 入口创建页。

固定提醒：

  • Hosted Inbox 和 Widget Embed 是建立在 C2AI2X 之上的产品化接入层
  • 它们不是协议标准本身
  • 若你要直接对接正式协议入口，仍以 POST /api/execute 的 live contract 为准
  • 本文只帮助你选择接入模式，不冻结 provider payout / revenue share / take-rate 规则
提示一条默认原则

先用最轻的方式把入口上线并验证真实需求；只有当你确实需要回写系统、权限治理与审计时，才升级到 Full API。

推荐阅读

按接入深度选择

Hosted Inbox

零代码上线独立咨询页，先验证需求。

Widget Embed

用一段脚本把入口放进已有站点。

Full API

接入自有系统，掌控认证、执行与回执。

上线检查

在正式流量前确认幂等、重试与安全边界。

1. 三种接入模式​

1.1 Hosted Inbox​

适合：

  • 没有研发团队
  • 只想最快上线咨询入口
  • 先验证是否有真实需求

你会得到：

  • 托管链接
  • 独立咨询页
  • 可分发二维码或按钮入口

当前 MVP 形状：

  • Hosted Inbox URL 形如：https://console.zhenrobot.com/widget/{channel_key}
  • 企业侧只需要复制链接，不需要写代码
  • 线索提交后会进入供给侧 Provider Workbench

推荐场景：

  • 企业官网先试运行
  • 活动页、公众号、社群导流
  • 销售或 BD 先拿去落地

1.2 Widget Embed​

适合：

  • 可以修改网页 HTML / CMS / 插件配置
  • 希望入口保留在自己站内
  • 不想立刻进入完整 API 集成

你会得到：

  • 悬浮聊天框或嵌入式咨询卡片
  • 可配置入口位置、文案、品牌信息
  • 可携带站点来源和页面归因信息

当前 MVP snippet：

<script
  src="https://console.zhenrobot.com/embed/c2ai2x-widget.js"
  data-channel-id="CHANNEL_KEY"
  data-console-origin="https://console.zhenrobot.com"
  async
></script>

固定说明：

  • data-channel-id 在当前 MVP 中承载公开的 channel_key
  • snippet 会挂出一个 iframe，目标页形如：/widget/{channel_key}
  • widget 内的公开配置与 intake，最终仍回到 zhen-platform-core 公共路由

推荐场景：

  • 公司官网
  • 产品详情页
  • SaaS 后台
  • 合作方门户

1.3 Full API​

适合：

  • 有研发团队
  • 需要把执行结果深度写回自有系统
  • 需要自定义异步编排、状态机和权限模型

你需要负责：

  • 鉴权
  • 请求构造
  • 异步 follow-up
  • 本地状态映射
  • 错误处理和生产校验

2. 如何选择​

如果你符合以下情况，默认选择如下：

  1. 没有开发能力
    • 选 Hosted Inbox
  2. 能粘贴脚本或装插件
    • 选 Widget Embed
  3. 需要把 C2AI2X 接进自有产品逻辑
    • 选 Full API

固定建议：

  • 不要一开始就默认走 Full API
  • 先选能最快形成真实流量与真实需求回流的模式

推荐阅读

直接进入执行页

Hosted Inbox

最快上线，不改网站。

Widget Embed

入口留在你的网站里。

API 规范与接入评估

需要回写系统时进入 Full API。

参考案例卡片

按场景对照选择路线。

3. 能力差异​

3.1 Hosted Inbox​

  • 开发要求：最低
  • 上线速度：最快
  • 自定义程度：最低
  • 适合验证：最强

3.2 Widget Embed​

  • 开发要求：低
  • 上线速度：快
  • 自定义程度：中
  • 适合品牌内嵌：最强

3.3 Full API​

  • 开发要求：高
  • 上线速度：最慢
  • 自定义程度：最高
  • 适合深度系统接入：最强

4. 当前 MVP 已实现的入口​

4.1 customer / admin channel provisioning​

  • GET /api/integrations/channels
  • POST /api/integrations/channels

这两条路由由 zhen-platform-console 调用 zhen-platform-core，用于创建与列出 access-layer channels。

它们属于登录后的管理入口，不是多数需求侧团队的默认第一步；默认起步仍是创建入口、复制链接或 snippet。

4.2 public widget config / intake​

zhen-platform-core 公共契约：

  • GET /api/public/channels/{channelKey}/widget-config
  • POST /api/public/channels/{channelKey}/intake

zhen-platform-console 公共代理：

  • GET /api/public/widget/{channelId}/config
  • POST /api/public/widget/{channelId}/intake

固定解释：

  • channelKey / channelId 在当前 widget MVP 中都承载同一个公开 channel 标识
  • 业务前台和 iframe 不直接暴露 zhen-platform-core 内部状态结构

4.3 supply-side pages​

  • /provider/onboarding
  • /provider/workbench

这两页固定由 zhen-platform-console 承接。

5. 供给侧入口怎么理解​

在部分场景中，接入方还会看到“成为专家 / 接入机器人 / 注册智能体”之类的入口。

这类入口的固定解释是：

  • 它是供给侧入口，不是需求侧主流程
  • 它可以挂在官网或 widget 上
  • 真正的注册和 onboarding 仍会进入统一主链：
    • auth.zhenrobot.com
    • zhen-platform-core
    • zhen-platform-console

不要把 widget 内的供给入口理解为完整后台或完整注册系统。

5.1 当前不应从接入文档推导出的结算结论​

仅根据本页，你不应推导出以下结论：

  • 平台长期 0% 抽成
  • 平台存在固定成交抽成
  • provider payout 已经是 live shared-layer contract

当前固定边界是：

  • 接入模式已明确
  • 供给侧入口已明确
  • 具体分账、抽成与结算规则仍以平台正式 contract 为准

6. 如果你准备直接调协议​

若你已经确定要走 Full API，下一步阅读顺序固定为：

  1. 协议入口
  2. first-request
  3. quickstart
  4. auth-and-scopes
  5. api-reference

7. 一句话建议​

先用最轻的模式跑通真实需求，再升级到更重的模式。

对多数企业来说，正确顺序不是：

先读完整协议 -> 再开发

而是：

先上线入口 -> 再验证需求 -> 再升级接入深度

真实动作点​