嵌入页面前端SDK

@cfx/chatdoing 是 Chatdoing 侧边栏 SDK。接入方只需要在自己的页面中通过 script 引入 SDK，然后通过 window.Chatdoing 调用方法。

SDK 当前提供 3 个业务方法：

config(options)

sendChatMessage(options) 发送素材

getRoomInfo() 获取会话详情

SDK 不对外暴露 TypeScript 类型。文档中的类型声明仅用于说明参数结构和返回数据结构。

1. 引入 SDK

其中 1.0.2 按实际发布版本替换，目前最新版就是1.0.2。

引入后，全局对象为：

window.Chatdoing

2. 基本调用流程

推荐先调用 config() 完成注册，再调用其他方法。

async function init() {
  try {
    const configResult = await window.Chatdoing.config({
      clientid: 'your-clientid',
      clientsecret: 'your-clientsecret',
    });

    if (configResult.code !== 'ok') {
      console.error('SDK 注册失败:', configResult.code, configResult.msg);
      return;
    }

    const roomInfo = window.Chatdoing.getRoomInfo();
    console.log('当前会话信息:', roomInfo);

    const sendResult = await window.Chatdoing.sendChatMessage({
      msgType: 'text',
      context: {
        text: '你好',
      },
    });

    if (sendResult.code !== 'ok') {
      console.error('消息发送失败:', sendResult.code, sendResult.msg);
      return;
    }

    console.log('消息发送成功');
  } catch (error) {
    console.error('SDK 调用异常:', error);
  }
}

sendChatMessage() 和 getRoomInfo() 必须在 config() 成功后调用。未完成注册时调用，会抛出 CONFIG_REQUIRED 异常。

3. 返回格式

正常业务成功和正常业务失败都会返回 { code, msg }。

interface ChatdoingResult {
  code: string | number;
  msg: string;
}

成功时 code 固定为 ok。

示例：

{
  "code": "ok",
  "msg": "发送成功"
}

业务失败示例：

{
  "code": "SCHEMA_REQUIRED",
  "msg": "当前会话发送 H5 或小程序时 schema 必填"
}

处理建议：

const res = await window.Chatdoing.sendChatMessage({
  msgType: 'text',
  context: {
    text: '你好',
  },
});

if (res.code !== 'ok') {
  console.error('业务失败:', res.code, res.msg);
}

4. 异常处理

网络错误、响应结构异常、未完成注册等情况会抛出异常，或返回 rejected Promise。

SDK 内部异常格式通常为：

interface ChatdoingError extends Error {
  name: 'ChatdoingError';
  code: string | number;
  message: string;
  docsUrl: string;
  response?: unknown;
}

建议所有 SDK 调用都使用 try/catch 包裹。

function getErrorMessage(error: unknown) {
  if (error instanceof Error) {
    return error.message;
  }

  return String(error);
}

try {
  const res = await window.Chatdoing.config({
    clientid: 'your-clientid',
    clientsecret: 'your-clientsecret',
  });

  if (res.code !== 'ok') {
    console.error('注册失败:', res.code, res.msg);
  }
} catch (error) {
  console.error('注册异常:', getErrorMessage(error));
}

常见异常：

{
  name: 'ChatdoingError',
  code: 'CONFIG_REQUIRED',
  message: '请先调用 config'
}

5. config(options)

window.Chatdoing.config(options): Promise<ChatdoingResult>

参数：

interface ConfigOptions {
  clientid: string;
  clientsecret: string;
}

参数说明：

参数	类型	必填	描述
`clientid`	`string`	是	应用的 clientid
`clientsecret`	`string`	是	应用的 clientsecret

示例：

try {
  const res = await window.Chatdoing.config({
    clientid: 'your-clientid',
    clientsecret: 'your-clientsecret',
  });

  if (res.code !== 'ok') {
    console.error('SDK 注册失败:', res.code, res.msg);
    return;
  }

  console.log('SDK 注册成功');
} catch (error) {
  console.error('SDK 注册异常:', error);
}

成功返回：

{
  "code": "ok",
  "msg": "sdk注册成功"
}

业务失败返回：

{
  "code": "后端返回的错误码",
  "msg": "后端返回的错误信息"
}

异常情况：

HTTP 状态码非 2xx

token 响应数据不完整

网络异常

浏览器无法写入 cookie

6. sendChatMessage(options)

发送聊天消息。

window.Chatdoing.sendChatMessage(options): Promise<ChatdoingResult>

调用前必须先 config() 成功。

参数：

interface SendChatMessageOptions {
  msgType: 'text' | 'image' | 'file' | 'video' | 'h5' | 'miniprogram';
  context:
    | TextContext
    | ImageContext
    | FileContext
    | VideoContext
    | H5Context
    | MiniProgramContext;
}

参数说明：

参数	类型	必填	描述
`msgType`	`string`	是	消息类型
`context`	`object`	是	消息内容，不同 `msgType` 对应不同结构

6.1 text

发送文本消息。

interface TextContext {
  text: string;
}

参数	类型	必填	描述
`text`	`string`	是	文本内容

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'text',
  context: {
    text: '你好',
  },
});

6.2 image

发送图片消息。

interface ImageContext {
  url: string;
  name?: string;
  previewUrl?: string;
}

参数	类型	必填	描述
`url`	`string`	是	图片地址
`name`	`string`	否	图片名称
`previewUrl`	`string`	否	图片预览地址

图片校验规则：

只允许 png、jpg 格式。

图片大小必须小于 10MB。

图片资源需要支持浏览器读取文件响应头。

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'image',
  context: {
    url: 'https://example.com/a.png',
    name: '图片名称',
    previewUrl: 'https://example.com/preview.png',
  },
});

6.3 file

发送文件消息。

interface FileContext {
  url: string;
  name: string;
}

参数	类型	必填	描述
`url`	`string`	是	文件地址
`name`	`string`	是	文件名称

文件校验规则：

文件大小必须小于 30MB。

文件资源需要支持浏览器读取文件响应头。

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'file',
  context: {
    url: 'https://example.com/a.pdf',
    name: '文件名称.pdf',
  },
});

6.4 video

发送视频消息。

interface VideoContext {
  url: string;
  name: string;
  previewUrl?: string;
}

参数	类型	必填	描述
`url`	`string`	是	视频地址
`name`	`string`	是	视频名称
`previewUrl`	`string`	否	视频封面地址

视频校验规则：

视频大小必须小于 30MB。

视频资源需要支持浏览器读取文件响应头。

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'video',
  context: {
    url: 'https://example.com/a.mp4',
    name: '视频名称.mp4',
    previewUrl: 'https://example.com/poster.jpg',
  },
});

6.5 h5

发送 H5 消息。

interface H5Context {
  url: string;
  title: string;
  description?: string;
  previewUrl?: string;
  schema?: string;
}

参数	类型	必填	描述
`url`	`string`	是	H5 页面地址
`title`	`string`	是	标题
`description`	`string`	否	描述
`previewUrl`	`string`	否	预览图地址
`schema`	`string`	否	跳转 schema

特殊规则：

当前会话归属渠道为 PhysicalQwMessageIM 时，schema 必填。

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'h5',
  context: {
    url: 'https://example.com/page',
    title: '标题',
    description: '描述',
    previewUrl: 'https://example.com/cover.png',
    schema: 'example://page',
  },
});

6.6 miniprogram

发送小程序消息。

interface MiniProgramContext {
  title: string;
  desc?: string;
  appName?: string;
  appId?: string;
  originalId?: string;
  userName?: string;
  path?: string;
  schema?: string;
  coverUrl?: string;
  iconUrl?: string;
  url?: string;
}

参数	类型	必填	描述
`title`	`string`	是	小程序标题
`desc`	`string`	否	小程序描述
`appName`	`string`	否	小程序名称
`appId`	`string`	否	小程序 appId
`originalId`	`string`	否	小程序原始 ID
`userName`	`string`	否	小程序 userName
`path`	`string`	否	小程序页面路径
`schema`	`string`	否	跳转 schema
`coverUrl`	`string`	否	封面图地址
`iconUrl`	`string`	否	图标地址
`url`	`string`	否	兜底地址

特殊规则：

当前会话归属渠道为 PhysicalQwMessageIM 时，schema 必填。

示例：

await window.Chatdoing.sendChatMessage({
  msgType: 'miniprogram',
  context: {
    title: '小程序标题',
    desc: '小程序描述',
    appName: '小程序名称',
    appId: 'wx123456',
    originalId: 'gh_xxx',
    userName: 'gh_xxx@app',
    path: '/pages/index/index',
    schema: 'weixin://dl/business/?t=xxx',
    coverUrl: 'https://example.com/cover.png',
    iconUrl: 'https://example.com/icon.png',
    url: 'https://example.com/fallback',
  },
});

6.7 sendChatMessage 返回

成功返回：

{
  "code": "ok",
  "msg": "发送成功"
}

常见业务失败：

code	msg
`INVALID_IMAGE_URL`	图片地址不能为空
`IMAGE_HEAD_FAILED`	图片文件信息获取失败
`INVALID_IMAGE_TYPE`	图片仅支持 png、jpg 格式
`IMAGE_SIZE_UNAVAILABLE`	无法获取图片大小
`IMAGE_TOO_LARGE`	图片大小需小于 10MB
`INVALID_FILE_URL`	文件地址不能为空
`FILE_HEAD_FAILED`	文件信息获取失败
`FILE_SIZE_UNAVAILABLE`	无法获取文件大小
`FILE_TOO_LARGE`	文件大小需小于 30MB
`INVALID_VIDEO_URL`	视频地址不能为空
`VIDEO_HEAD_FAILED`	视频信息获取失败
`VIDEO_SIZE_UNAVAILABLE`	无法获取视频大小
`VIDEO_TOO_LARGE`	视频大小需小于 30MB
`SCHEMA_REQUIRED`	当前会话发送 H5 或小程序时 schema 必填
`POST_MESSAGE_FAILED`	消息发送失败

未先调用 config() 时会抛出异常：

{
  name: 'ChatdoingError',
  code: 'CONFIG_REQUIRED',
  message: '请先调用 config'
}

7. getRoomInfo()

获取当前会话信息

获取原始外部联系人id、群id，使用响应中的chatID，调用查询渠道原始id 进行换取

window.Chatdoing.getRoomInfo(): unknown

调用前必须先 config() 成功。

如果当前还没有会话信息，返回 undefined。

返回字段：

字段	字段名	类型	描述
`chatID`	会话ID	`string`	会话ID
`chatName`	会话名称	`string`	会话名称
`chatType`	会话类型	`string`	`SingleType` = 单聊 `GroupType` = 群聊
`chatChannel`	会话归属渠道	`string`	`DemoIM`：演示 `WeChatKFIM`：微信客服 `EComIM`：ECom `QwMessageIM`：云端企微托管 rpa `QwMessageSidebarIM`：会话存档侧边栏 `MultiQwMessageIM`：云端企微托管员工组 rpa `PhysicalQwMessageIM`：实体设备 rpa `OpenKFIM`：通用客服 `DouYinIM`：抖音私信
`chatStatus`	会话状态	`string`	`ChatStatusNormal` = 正常 `ChatStatusNanualService` = 人工服务 `ChatStatusAIService` = AI服务 `ChatStatusCompletedService` = 服务完成
`contactID`	好友ID	`string`	仅会话类型为单聊返回
`contactName`	好友名称	`string`	仅会话类型为单聊返回
`roomID`	群ID	`string`	仅会话类型为群聊返回
`roomName`	群名称	`string`	仅会话类型为群聊返回
`userID`	托管账号ID	`string`
`userName`	托管账号名称	`string`
`staffUserID`	登录员工ID	`string`
`staffName`	登录员工名称	`string`
`staffPhone`	登录员工手机	`string`

示例：

try {
  const roomInfo = window.Chatdoing.getRoomInfo();
  console.log('当前会话信息:', roomInfo);
} catch (error) {
  console.error('获取会话信息异常:', error);
}

未先调用 config() 时会抛出异常：

{
  name: 'ChatdoingError',
  code: 'CONFIG_REQUIRED',
  message: '请先调用 config'
}

1. 引入 SDK#

2. 基本调用流程#

3. 返回格式#

4. 异常处理#

5. config(options)#

6. sendChatMessage(options)#

6.1 text#

6.2 image#

6.3 file#

6.4 video#

6.5 h5#

6.6 miniprogram#

6.7 sendChatMessage 返回#

7. getRoomInfo()#

8. 完整示例#