小天互连 Web/H5 SDK 接入指南

初始化 SDK 实例。所有后续方法调用都必须通过该实例进行。

返回值：XtelfAPI 实例

var xtelf = XtelfAPI.init({
  userSdkKey: "QnJJY0tWSC84aU05...",
  appId: "0fe6a4b2b52b4ff28d4ac918",
  webTitle: "OA协同办公",
  oaApiBaseUrl: "https://oa.example.com/"
});

在指定的 DOM 元素上自动显示未读消息数角标。调用后每 2 秒轮询一次未读数，自动创建/更新/移除角标 DOM。

<div id="msg-icon" style="position: relative;">
  <img src="chat-icon.png" />
</div>

<script>
  var xtelf = XtelfAPI.init({ userSdkKey: "..." });
  xtelf.addChatNumPushEvent("msg-icon");
</script>

使用 OA 系统的 Token 和用户 ID 认证，直接打开聊天首页。适用于 OA 系统免密集成场景，无需 userSdkKey。

// 默认：打开页面
xtelf.oaOpenWebChat("oa-token-xxx", "user_zhangsan");

// returnUrl：获取 URL
var url = xtelf.oaOpenWebChat("oa-token-xxx", "user_zhangsan", { returnUrl: true });

打开完整的聊天界面。传入目标 ID 时直接进入与该用户或群的聊天；不传时进入消息列表首页。包含完整的底部导航（消息、通讯录、我的）。

// 默认：打开聊天
xtelf.openWebChat("user001");

// returnUrl：获取 URL 用于 iframe
var url = xtelf.openWebChat("user001", { returnUrl: true });

// 不指定目标，获取消息列表 URL
var listUrl = xtelf.openWebChat(null, { returnUrl: true });

打开精简的独立聊天窗口，隐藏左侧菜单（PC）/ 底部导航和返回按钮（H5），用户只能在当前会话中操作，无法切换到其他功能。适用于嵌入式客服、工单沟通等场景。

// 默认：打开独立聊天
xtelf.openWebChatOnly("kefu_001");

// returnUrl：嵌入 iframe（推荐用于客服场景）
var url = xtelf.openWebChatOnly("kefu_001", { returnUrl: true });
document.getElementById("chatFrame").src = url;

打开消息列表，但隐藏导航菜单（PC 隐藏左侧栏 / H5 隐藏底部 Tab 栏）。用户可以浏览和选择会话，但无法进入通讯录、个人中心等页面。

// 默认：打开无菜单聊天
xtelf.openWebChatNoMenu();

// returnUrl
var url = xtelf.openWebChatNoMenu({ returnUrl: true });

调用后端接口创建业务群组，创建成功后自动打开该群聊天。适用于 OA 审批流、项目协作等需要按业务自动建群的场景。

// 默认：创建群并打开聊天
xtelf.createGroupAndChat(
  "approval-2024-001", "oa-approval",
  ["zhang_san", "li_si"], "采购审批讨论群"
);

// returnUrl：创建群后获取 URL
xtelf.createGroupAndChat(
  "approval-2024-001", "oa-approval",
  ["zhang_san", "li_si"], "采购审批讨论群",
  { returnUrl: true }
).then(function(url) {
  if (url) document.getElementById("chatFrame").src = url;
});

根据业务 ID 和类型查询已有的业务群，找到后直接打开该群聊天。

// 默认：打开群聊天
xtelf.openGroupAndChat("approval-2024-001", "oa-approval");

// returnUrl
xtelf.openGroupAndChat("approval-2024-001", "oa-approval", { returnUrl: true })
  .then(function(url) {
    if (url) document.getElementById("chatFrame").src = url;
  });

根据业务 ID 和类型查询已有的业务群，打开该群的聊天记录页面（只读查看模式）。

// 默认：打开聊天记录
xtelf.openGroupChatRecord("approval-2024-001", "oa-approval");

// returnUrl
xtelf.openGroupChatRecord("approval-2024-001", "oa-approval", { returnUrl: true })
  .then(function(url) {
    if (url) document.getElementById("recordFrame").src = url;
  });

向指定业务群中添加新成员。操作成功后弹出提示，不跳转页面。

xtelf.addGroupMember(
  "approval-2024-001",
  "oa-approval",
  ["wang_wu", "zhao_liu"]
);

从指定业务群中移除成员。操作成功后弹出提示，不跳转页面。

xtelf.delGroupMember(
  "approval-2024-001",
  "oa-approval",
  ["zhao_liu"]
);