SDK API Reference

本文档面向第三方前端接入方，说明 @scooper/meeting-sdk 封装了哪些底层能力，以及每类方法的返回策略。

初始化

SDK 方法	底层依赖	说明
`ScooperMeetingSDK.create(config)`	无	创建 SDK 实例，不立即连接后台。
`ScooperMeetingSDK.loadDependencies(options)`	动态 `<script>`	可选：按顺序加载 jquery/dispatch/video/soft-handler。
`sdk.init(config?)`	`scooper.dispatch.initialize`、`loginByToken`、`VideoWebRtc`、`ScSoftHandler`	按配置初始化调度信令长连接、视频视窗和软手柄。
`sdk.login(token?)`	`scooper.dispatch.loginByToken`	手动登录调度后台。
`sdk.destroy(options?)`	`destroy` / `closeAll` / `unregister`	解绑监听、关闭视频和软手柄。

dispatch.token 可以是字符串，也可以是返回 Token 的函数：

const sdk = ScooperMeetingSDK.create({
  dispatch: {
    remoteBaseUrl: "https://host/dispatch-web/",
    token: () => sessionStorage.getItem("Sc-Token"),
  },
});

会议 API

SDK 方法	底层方法	功能与后台接口语义
`createMeeting(options)`	`meets.createMeetDetail` / `meets.createMeet`	创建多方视频/音频会商（`POST /meet/createMeet`）
`editMeeting(options)`	`meets.editMeet`	编辑会议名称、成员权限或访问码（`POST /meet/editMeet`）
`listMeetings({ mine })`	`meets.listMyMeets` / `meets.listMeets`	查询当前操作员创建的会议或平台全部会议列表
`getMeeting(meetId)`	`meets.getMeet`	查询指定单个会议的详细信息（`GET /meet/getMeet`）
`requestMeeting(meetId)`	`meets.requestMeet`	向后台请求并刷新本地缓存的会场详情
`requestMeetingMembers(meetId)`	`meets.requestMeetMembers`	向后台请求并刷新本地缓存的参会成员列表
`getMeetingScreenState(meetId)`	`meets.requestMeet`	读取缓存中的混屏/分屏布局及主看/屏幕共享人状态
`listMeetingRecords()`	`meets.listMeetsRecord`	查询历史会议记录列表（`GET /meet/listMeetsRecord`）
`getMeetingRecord(meetId, tel?)`	`meets.getMeetRecord`	查询指定会场或指定成员的历史会议记录（`GET /meet/getMeetRecord`）
`joinMeeting(options)`	`meets.joinVideoMember` / `joinAudioMember` / `joinMember`	邀请指定成员以视频或纯音频方式加入会商（`/meet/joinMember`）
`playMeetingVideo(options)` / `playVideo({ meetId, tel })`	`joinVideoMember` + `softHandler.answer` + `meeting:member` + `video.play`	一键邀请成员视频入会并在本端空闲视窗自动拉流上屏播放
`joinMembers(options)`	`meets.joinMembers`	批量邀请多位成员同时加入会商（`/meet/joinMembers`）
`kickMember(meetId, tel)`	`meets.kickMember`	将指定参会成员移出/剔出会场（`POST /meet/kickMember`）
`endMeeting(meetId, { destroy })`	`meets.endMeet` / `destroyMeet`	结束会议或彻底解散销毁会议（`POST /meet/endMeet`、`/meet/destroyMeet`）
`lockMeeting` / `unlockMeeting`	`meets.lock` / `unlock`	锁定会议（禁止新成员呼入）与解除锁定（`POST /meet/lock`、`/meet/unlock`）
`startRecord` / `stopRecord`	`meets.startRecord` / `stopRecord`	开启或停止全场会议视讯录制（`POST /meet/startRecord`、`/meet/stopRecord`）
`startPlayVoice` / `stopPlayVoice`	`meets.startPlayVoice` / `stopPlayVoice`	开启或停止会场背景放音/广播音频（`POST /meet/startPlayVoice`、`/meet/stopPlayVoice`）
`changeMemberLevel`	`meets.changeMemberLevel`	动态修改指定成员的席位级别与权限（`POST /meet/changeMemberLevel`）
`changeMemberToSpeaker/Audience/Chairman`	同名 meets 方法	快捷将成员角色切换为发言人、听众或主席
`changeMemberToController`	`meets.changeMemberToController`	将指定成员设为会商主控者（`POST /meet/changeMemberToController`）

members 支持底层字符串，也支持对象数组：

await sdk.createMeeting({
  name: "第三方视频会商",
  businessId: "biz-001",
  members: [
    { tel: "1001", level: "chairman" },
    { tel: "1002", level: "speak" },
  ],
  mediaType: "video",
});

创建会议后播放会场成员视频时，第三方不需要再单独调用 joinMeeting、softAnswer 或监听入会通知：

await sdk.playVideo({
  meetId: "meet-001",
  tel: "1002",
  index: 0,
  autoAnswer: true,
  joinNotifyTimeout: 15000
});

成员与当前会议

SDK 方法	说明
`getCurrentMeet()` / `getCurrentMeetId()`	读取最近一次创建或加入的会议。
`setCurrentMeet(meet)`	手动指定当前会议；传 `null` 清空。
`getMeetingMembers(meetId?)`	异步获取成员列表，省略 `meetId` 时用当前会议。
`getMeetingMembersSync(meetId?)`	同步读成员缓存。
`getMeetingMember(meetId, tel)`	获取单个成员，不存在返回 `null`。
`isMemberInMeeting(meetId, tel)`	该号码是否已在会中（读缓存，同步）。
`muteMember` / `unmuteMember(meetId, tel)`	禁言 / 解除禁言，等价于设为听众 / 发言人。
`setMemberRole(meetId, tel, role)`	设置角色：`speak` / `audience` / `chairman`。
`muteAllMembers(meetId?)` / `unmuteAllMembers(meetId?)`	全员禁言 / 解除。返回 `{ total, succeeded, failed }`，单个成员失败不中断整体流程。

joinMeeting() 若发现该号码已在会中，会跳过重复请求，直接返回 { code: 0, alreadyInMeeting: true } 并派发 meeting:alreadyInMeeting 事件。

错误处理

所有返回 Promise 的方法在依赖未就绪（dispatch / video / softHandler 未初始化）时也会 reject，可以用 .catch() 统一接住：

try {
  await sdk.makeVideoCall({ tel: "1002" });
} catch (error) {
  // error instanceof ScooperMeetingSDK.SDKError
  console.error(error.code, error.message);
}

同步方法仍然是同步 throw，需要 try/catch：playVideo、playVideos、initVideo、closeVideo、closeAllVideos、setVideoWindows、startVideoPoll、stopVideoPoll、requestMeeting、requestMeetingMembers、requestMeetingMember、getMeetingScreenState、findIncomingCallByTel、isPlaying、isMemberInMeeting。

错误对象统一为 ScooperMeetingSDK.SDKError，通过 error.code 区分原因（如 DISPATCH_NOT_FOUND、REQUEST_TIMEOUT、REQUEST_FAILED、VIDEO_CONTAINER_NOT_FOUND、JOIN_NOTIFY_TIMEOUT）。每次产生错误时也会派发 sdk:error 事件。

呼叫 API

这些方法封装 scooper.dispatch.calls，默认等待 dispatch:methodResponse。如果调用方只想发送请求，不等待后台统一响应，可传 { waitResponse: false }。

rollCall 和 groupNotify/selectNotify 还会默认继续等待 dispatch-web 使用的 dispatch:responseData 终态包（group_roll_call / group_notify）。返回对象保留请求响应字段，并在 finalResult 字段中附带终态包；不需要等待终态时传 { waitFinalResult: false }。终态包在后台没有返回时会以 FINAL_RESULT_TIMEOUT reject，超时时间可用 finalResultTimeout 覆盖。

注意：

底层 methodResponse 没有 requestId。SDK 会把 waitResponse: true 的调用串行化，避免并发时响应错配。
业务失败（code 非 0 / "0"）会 reject，不再静默 resolve。
createMeeting 优先走底层 callback，不依赖 methodResponse。

SDK 方法	底层方法	功能与后台接口语义
`requestCallStatus()`	`calls.requestCallStatus`	向后台请求并刷新操作员当前的全量呼叫/通话状态
`requestTelStatus(tel)`	`calls.requestTelStatus`	向后台请求并查询指定单号码的在线与通话状态
`requestCallIns()`	`calls.requestCallIns`	向后台请求并刷新当前呼入队列数据
`listCallStatus()`	`calls.listStatus`	查询当前全量呼叫/通话状态列表（`GET /call/listStatus`）
`listHoldCalls()`	`calls.listHold`	查询当前处于保持状态的通话列表（`GET /call/listHold`）
`listIncomingCalls()`	`calls.listCallIn`	查询当前等待接听的呼入队列列表（`GET /call/listCallIn`）
`findIncomingCallByTel(tel)`	`calls.findCallInByTel`	从本地缓存队列中按号码查找对应的呼入来电信息
`makeCall` / `makeAudioCall` / `makeVideoCall`	`calls.makeCall` / `makeAudioCall` / `makeVideoCall`	发起单点语音呼叫或视频呼叫（`POST /call/makeCall`、`/makeAudioCall`、`/makeVideoCall`）
`answerCall(tel)`	`calls.answer`	接听/应答指定号码的来电呼叫（`POST /call/answer`）
`hangupCall(tel)`	`calls.hungUp`	挂断指定号码的通话（`POST /call/hungup`）
`answerAllCalls()`	`calls.answerAll`	一键应答当前队列中的所有呼入来电（`POST /call/answerAll`）
`holdCall` / `unholdCall`	`calls.hold` / `unhold`	通话保持（将通话置于等待）与恢复通话（`POST /call/hold`、`/call/unhold`）
`transferCall({ from, to })`	`calls.transfer`	通话转接（将正在通话的号码转接至第三方目标，`POST /call/transfer`）
`retrieveCall(tel)`	`calls.retrieve`	强拉/恢复指定被转接的通话（`POST /call/retrieve`）
`tripleMonitor` / `tripleBreakin` / `tripleHungup`	同名底层方法	调度三方控制：监听通话、强插通话、强拆通话
`startCallRecord` / `stopCallRecord`	`calls.callRecord` / `callRecordEnd`	开启或停止当前单路通话录音（`POST /call/callRecord`、`/call/callRecordEnd`）
`rollCall` / `stopRollCall`	`calls.rollCall` / `stopRollCall`	发起多号码语音点名（按序轮流连通）与停止点名
`groupTurn` / `stopGroupTurn`	`calls.groupTurn` / `stopGroupTurn`	发起多号码轮询调度呼叫与停止轮询
`selectCall` / `cancelSelectCall`	`calls.selectCall` / `selectCancel`	多人选呼/组呼（`GET /dispatch-web/api/call/selectCall?meetId=...&tels=...`）与取消选呼（`GET /dispatch-web/api/call/selectCancel`）
`groupNotify` / `selectNotify`	`calls.selectNotify` / `calls.groupNotify`	组呼通知（`POST /dispatch-web/api/call/groupNotify`），支持文字转语音 (TTS, `type: "text"`) 与音频文件 (`type: "voice"`)，标准载荷为 `tels`, `files`, `type`, `times`, `notifyId`
`groupCall` / `cancelGroupCall`	`calls.groupCall` / `groupCancel`	传统群组 ID 组呼与取消（`GET /dispatch-web/api/call/groupCall`）
`groupSame` / `makeCallSame`	`calls.groupSame` / `makeCallSame`	一键组呼同振（多个被叫同时振铃，底层兼容）
`notifyRecordOperation`	`calls.notifyRecordOP`	通知语音录制、试听、删除等管理操作（`/call/notifyRecordOP`）
`dispatchSoftAnswer` / `dispatchSoftHangup` / `preemptSoftHandlerRegister`	`calls.shandleAnswer` / `shandleHungUp` / `shandlePreemptRegister`	使用 dispatch 内置软手柄能力执行应答、挂断或抢占注册

示例：

// 1. 点对点呼叫与转接
await sdk.makeVideoCall({ tel: "1002", businessId: "case-001" });
await sdk.transferCall({ from: "1002", to: "1003", businessId: "case-001" });

// 2. 多人选呼/组呼 (GET /dispatch-web/api/call/selectCall)
await sdk.selectCall({
  tels: ["142001", "1000021"],
  meetId: "yangyue1",
  autoAnswer: "",
  allAudience: ""
});

// 取消多人呼叫 (GET /dispatch-web/api/call/selectCancel?meetId=yangyue1)
await sdk.cancelSelectCall("yangyue1");

// 3. 组呼通知 (文字转语音 TTS 模式)
await sdk.groupNotify({
  tels: ["142001", "1000021"],
  files: "紧急调度通知：请全体参会人员迅速就位！",
  type: "text",
  times: 1
});

// 4. 组呼通知 (音频文件播报模式)
await sdk.groupNotify({
  tels: ["142001"],
  files: "notice.wav",
  type: "voice",
  times: 3
});

视频 API

SDK 方法	底层方法	说明
`initVideo(container, options)`	`new VideoWebRtc(container, options)`	初始化视频窗口。
`playVideo({ video })`	`video.play(index, video, id, options)`	播放一路普通视频。
`playVideo({ meetId, tel })`	`joinVideoMember` + `video.play`	视频会商入会播放；SDK 内部等待 `meeting:member` 后再播放。
`playVideos(items)`	`video.playAll` 或循环 `play`	批量播放。
`closeVideo(idOrIndex)`	`close` / `closeByVideo`	按窗口或视频 ID 关闭。
`closeAllVideos(isSave)`	`closeAll`	关闭全部视频。
`startVideoPoll` / `stopVideoPoll`	`startPoll` / `stopPoll`	视频轮巡控制。
`playByOrderExpandWindow(video, id?, options?)`	`video.play`	按空闲窗口顺序播放，满格时自动扩屏（1→4→6→9→16）。
`isPlaying(video)`	—	返回该视频所在窗口编号，未播放返回 `-1`。
`isPlayingByIndex(index)`	—	指定窗口当前是否在播放。
`getPlayingWindows()`	—	返回所有窗口的占用快照。
`setVideoWindows(n)` / `setWindowsNum(n)`	`setWindowsNum`	设置分屏数量。

playVideo 未显式传 index 时会自动分配空闲窗口；传了数字 index 则定点播放。

视频相关配置

配置项	默认值	说明
`video.syncToken`	`true`	是否把鉴权 token 写入 sessionStorage 供 `scooper.video` 读取。
`video.syncTokenKeys`	`["sc-auth","meetWebToken","videoWebToken"]`	同步写入的 key。默认不含裸 `token` 键，避免覆盖宿主应用登录态。
`meeting.autoPlayMemberVideo`	`true`	收到成员入会通知时自动上屏；显式调用 `playMeetingVideo` 的成员不会重复上屏。
`meeting.autoCloseMemberVideo`	`true`	收到成员离会通知时自动关闭其窗口。

软手柄 API

SDK 方法	底层方法	说明
`initSoftHandler(options)`	`ScSoftHandler.createSoftHandler`	创建独立软手柄。
`registerSoftHandler(info?)`	`softHandler.register`	注册 SIP/Janus 软手柄。
`unregisterSoftHandler()`	`softHandler.unregister`	注销软手柄。
`softCall` / `softNewCall`	`call` / `newcall`	发起软手柄呼叫。
`softAnswer(media?)`	`answer`	应答软手柄呼入。
`softHangup()`	`hangup`	挂断软手柄呼叫。
`setSoftHandlerVideoContainer({ remoteVideo, localVideo })`	`softHandler.setVideoContainer`	绑定本地/远端 video 元素。
`enableCamera(enabled?)` / `disableCamera()`	`deviceControl.enableCamera`	开关本地摄像头。
`toggleCamera(enabled?)`	`deviceControl.enableCamera`	切换摄像头；省略参数时基于当前状态取反。
`isCameraEnabled()`	—	摄像头当前是否开启。
`muteMicrophone(isMute?)`	`softHandler.audioInputMuted`	麦克风静音开关，返回实际生效状态。
`isMicrophoneMuted()`	—	麦克风当前是否静音。

软手柄自应答配置：

配置项	默认值	说明
`softHandler.autoAnswerSelfCall`	`true`	收到 `incomingcall/autoAnswer`，也就是 `SoftHandlerEvent.IN_CALL_ANSWER` 时，SDK 自动调用 `softHandler.answer(...)`。
`softHandler.autoAnswerDispatchCall`	`true`	`answerCall` 或 `joinMeeting({ controllerTel, tel })` 后，在应答窗口内收到 `notifyType=call_dispatch` 的软手柄呼入时自动应答。
`softHandler.dispatchAnswerTimeout`	`5000`	调度应答号码的有效窗口，单位毫秒。

事件 API

SDK 方法	说明
`sdk.on(event, handler)`	监听单个 SDK 事件，返回取消监听函数。
`sdk.once(event, handler)`	监听一次。
`sdk.onAny((event, payload) => {})`	监听所有 SDK 事件。
`callbacks.onEvent(event, payload)`	初始化时配置全局回调。
`callbacks.onMeetingStatus(payload)` 等具名回调	与 `ScooperMeetingSDK.EVENT` 一一对应。

后台 channel、dispatch.event_const、SDK 事件和具名 callback 的完整对照见 docs/event-listeners.md。

初始化​

会议 API​

成员与当前会议​

错误处理​

呼叫 API​

视频 API​

视频相关配置​

软手柄 API​

事件 API​

初始化