智能体接入指引

Appearance

智能体页面通信说明 ​

适用场景

本文档适用于以下场景：

  1. 在自己的页面中使用 iframe 嵌入智能体页面时；推荐使用 跨页通信 SDK 方案
  2. 将自己的页面嵌入到智能体页面中时；
  3. 在自己的页面中使用 winodow.open 方式打开智能体页面时；

安全提示

因window.postMessage允许向域名广播消息， 以下为智能体域名，不属于以下域名的消息请勿响应，且消息也不应向其他域名发送。

参考资料

window.postMessage 参考文档

通信流程 ​

  1. 在自己的页面中嵌入智能体页面，或使用 window.open 打开智能体页面，或将自己的页面嵌入到智能体页面中
  2. 获取智能体页面的 window 对象
  3. 向智能体页面发送消息

获取智能体页面的 window 对象 ​

  • 将智能体页面嵌入到自己的页面中时
html
<!-- 以下代码中的地址仅为示例，不可用作实际开发。 -->
<iframe
  id="iframe"
  src="https://robot.chaoxing.com/chat/web?unitId=&robotId="
></iframe>
<script>
  const iframe = document.getElementById("iframe");
  const aiWindow = iframe.contentWindow;
</script>
  • 在自己的页面中使用 winodow.open 方式打开智能体页面时
js
// 以下代码中的地址仅为示例，不可用作实际开发。
const aiWindow = window.open("https://robot.chaoxing.com/chat/web?unitId=&robotId=", "_blank);
  • 将自己的页面嵌入到智能体页面中时
js
const aiWindow = window.parent;

请求消息格式 ​

js
const message = {
  type: "CXBOT:xxx", // 消息类型，请注意固定格式
  data: {}, // 参数
};
aiWindow.postMessage(message, targetOrigin);

响应消息格式 ​

js
const event = {
  type: "CXBOT_PAGE:xxx", // 消息类型，请注意固定格式
  data: {}, // 数据
};

window.addEventListener("message", (event) => {
  const { type, data } = event.data;
  if (type === "CXBOT_PAGE:xxx") {
    // 处理消息
  }
});

智能体页面支持的能力 ​

能力标记说明

  • SDK
    该能力允许通过跨页通信 SDK 调用
  • IFRAME
    该能力允许通过 iframe 嵌入调用

发送消息 CXBOT:send ​

SDK
IFRAME

向智能体页面发送一条消息，该消息将发送到聊天区域内

js
const message = {
  type: "CXBOT:send",
  data: {
    text: "要发送的消息内容",
    hidden: false, // 是否隐藏该消息，为 true 时不展示在聊天区域，仅发送到服务端
  },
};
aiWindow.postMessage(message, targetOrigin);

场景：利用此接口将嵌入节点数据提交给智能体 ​

部分场景下，嵌入节点数据需要提交给智能体，例如嵌入的 iframe 中有表单数据，需要提交给智能体。

提示

嵌入的表单可能会被作为历史消息展示，为保证不会重复填写表单，请使用 bot_msg 字段作为唯一 ID，对表单数据进行序列化存储，并在历史消息中查找该 ID 对表单进行禁用和回填。

表单数据提交

js
const message = {
  type: "CXBOT:send",
  data: {
    text: `JSON序列化后的表单数据，例如：JSON.stringify([{"name": "name", "value": "张三"}, {"name": "age", "value": "18"}])`,
    hidden: true, // 隐藏该消息，仅发送到服务端
  },
};
aiWindow.postMessage(message, targetOrigin);

向输入框写入内容 CXBOT:inputText ​

SDK
IFRAME

将文本写入到输入框内，不会自动发送到聊天区域

js
const message = {
  type: "CXBOT:inputText",
  data: {
    text: "要写入的消息内容",
  },
};
aiWindow.postMessage(message, targetOrigin);

iframe 全屏 CXBOT:requestFullscreen ​

IFRAME

将指定 firame 全屏

js
const message = {
  type: "CXBOT:requestFullscreen",
  data: {
    selector: "iframeId", // 请从页面地址栏中获取，字段为 bot_msg
  },
};
aiWindow.postMessage(message, targetOrigin);

退出 iframe 全屏 CXBOT:cancelFullscreen ​

IFRAME

退出全屏

js
const message = {
  type: "CXBOT:cancelFullscreen",
  data: {
    selector: "iframeId", // 请从页面地址栏中获取，字段为 bot_msg
  },
};
aiWindow.postMessage(message, targetOrigin);

重设iframe尺寸 CXBOT:resizeMessage ​

SDK
IFRAME

提示

该能力仅适用于将自己的页面作为消息嵌入到智能体页面时。

智能体消息将会为页面地址栏注入 bot_msg 字段，该字段表示智能体的消息 ID，请在消息发送时携带该字段。

同时智能体消息还会为页面地址栏注入 bot_referer 字段，该字段表示智能体消息的来源页面地址，可将该字段的值直接作为 targetOrigin。

注意

  1. width 只允许输入百分比的值 例如: "100%"，且宽度仅适用于嵌入在智能体消息内的 iframe，智能体页面其余地方嵌入的 iframe 不允许配置宽度
  2. height 允许携带 px 作为单位
js
const message = {
  type: "CXBOT:resizeMessage",
  data: {
    messageId: "消息 ID", // 请从页面地址栏中获取，字段为 bot_msg
    height: "消息高度", // 允许携带 px 作为单位
    width: "消息宽度", // 只允许输入百分比的值 例如: "100%"
  },
};
aiWindow.postMessage(message, targetOrigin);

清屏 CXBOT:clearScreen ​

SDK
IFRAME

清空聊天区域的消息，允许传递参数指定保留的消息数量（从前到后保留，默认保留 1 条）

js
const message = {
  type: "CXBOT:clearScreen",
  data: {
    length: 1, // 保留的消息数量
  },
};
aiWindow.postMessage(message, targetOrigin);

获取智能体页面的页签列表 CXBOT:getTabs ​

注意

该能力仅在智能体页面存在多页签时可用

SDK
IFRAME
js
const message = {
  type: "CXBOT:getTabs",
};
aiWindow.postMessage(message, targetOrigin);

切换智能体页面的页签 CXBOT:switchTab ​

注意

该能力仅在智能体页面存在多页签时可用

SDK
js
const message = {
  type: "CXBOT:switchTab",
  data: {}, // 使用 getTabs 获取到的 tabs 列表中的完整对象
};
aiWindow.postMessage(message, targetOrigin);

弹出提示 CXBOT:alert ​

SDK
IFRAME
js
const message = {
  type: "CXBOT:alert",
  data: {
    title: "提示标题",
    text: "提示内容",
  },
};
aiWindow.postMessage(message, targetOrigin);

设置附加数据 CXBOT:setWsExtraData ​

SDK
IFRAME

该能力允许在发送消息时携带附加数据，该数据将作为 CXBOT:send 或用户提问的一部分发送到服务端

注意

  1. 不支持以下数据类型：Date RegExp Function Map Set WeakMap WeakSet 等
  2. 设置附加数据时无需对数据进行序列化
js
const message = {
  type: "CXBOT:setWsExtraData",
  data: {
    key1: "value1",
    key2: "value2",
    key3: {
      key4: "value4",
    },
  },
};
aiWindow.postMessage(message, targetOrigin);

场景：利用此接口为任务流初始化参数设置数据 ​

提示

此接口与 CXBOT:send 配合使用时，请注意时序问题，建议延迟 200ms 后再调用 CXBOT:send

js
const message = {
  type: "CXBOT:setWsExtraData",
  data: {
    taskId: "任务流 ID",
    chatModel: "APP", // 固定字段，固定值
    // taskInitParams 为固定字段，用于任务流数据初始化
    taskInitParams: {
      key: "value", // key 字段需要在任务流开始节点的初始化参数设置里声明
    },
  },
};
aiWindow.postMessage(message, targetOrigin);

页面多语言切换 CXBOT:setLang ​

SDK
IFRAME

该能力允许用户自行切换页面展示语言

可选语言：

  • zh-CN 简体中文
  • en-US 英文
js
const message = {
  type: "CXBOT:setLang",
  data: {
    lang: "en-US",
  },
};
aiWindow.postMessage(message, targetOrigin);

设置消息摘要 CXBOT:setContext ​

SDK
IFRAME

该能力允许在展示消息时携带消息摘要，摘要信息将作为聊天上下文交予大模型理解使用

提示

  1. 消息摘要仅支持字符串类型，推荐使用 markdown 描述您的摘要
  2. 若对同一 messageId 多次设置摘要，则只会保留最后一次设置的摘要内容。
  3. 对于生成式摘要，推荐使用 messageId 作为唯一标识并自行存储摘要内容，以确保相同的 messageId 不会产生不同的摘要内容。
js
const message = {
  type: "CXBOT:setContext",
  data: {
    messageId: "消息 ID", // 请从页面地址栏中获取，字段为 bot_msg
    conversationId: "会话 ID", // 请从页面地址栏中获取，字段为 bot_conversation
    content: "聊天上下文内容,例如: '你好'",
  },
};
aiWindow.postMessage(message, targetOrigin);

学习通 jsbridge SDK 消息代理 ​

IFRAME

该能力允许嵌入在智能体页面 iframe 使用学习通 jsbridge SDK的能力

注意

  1. 该能力仅在智能体页面作为浏览器顶级页面时可用
  2. 该能力不支持需要接收返回数据的 jsbridge 能力，即需要调用jsbridge.bind方法的能力不可使用该代理
js
const message = {
  type: "CX_JS_BRIDGE_PROXY",
  action: "", // 学习通 SDK 的动作
  params: {}, // 学习通 SDK 的参数
};
aiWindow.postMessage(message, targetOrigin);

最近更新: