即时通信 IM
有奖捉虫：行业应用 & 管理与支持文档专题 HOT
文档中心 > 即时通信 IM > 无 UI 集成 > 信令相关 > 信令管理 > Web&小程序&uni-app

Web&小程序&uni-app

最近更新时间：2023-07-24 10:32:47

我的收藏

本页目录：

概述

信令接口是基于 IM 消息提供的一套邀请流程控制的接口，可以实现多种实时场景，例如：
直播聊天室中进行上麦、下麦管理。
聊天场景中实现类似微信中的音视频通话功能。
教育场景中老师邀请同学们举手、发言的流程控制。
视频通话
语音通话
?
?
?
?
?
?

功能

该功能需要先登录 WebIM SDK，信令接口支持以下功能：

单聊邀请

可以使用 invite 信令接口进行点对点呼叫，对方收到邀请通知 onReceiveNewInvitation 后可以选择接受、拒绝或等待超时。
接口
chat.invite(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
userID
String
邀请的用户 ID。
data
String | undefined
自定义数据。
timeout
Number | undefined
超时时间, 设置为 0 时，不超时。
onlineUserOnly
Boolean | undefined
消息是否仅发送给在线用户的标识，默认值为 false；设置为 true，则消息既不存漫游，也不会计入未读，也不会离线推送给接收方， 并且 invite 操作也不会产生历史消息（针对该次 invite 的后续 cancel、accept、reject、timeout 操作也同样不会产生历史消息）。
offlinePushInfo
Object | undefined
?离线推送配置。
offlinePushInfo 的描述如下：
Name
Type
Description
disablePush
Boolean
true 关闭离线推送；false 开启离线推送（默认）。
disableVoipPush
Boolean
true 关闭 voip 推送（默认）；false 开启 voip 推送（开启 voip 推送需要同时开启离线推送）。
title
String
离线推送标题，该字段为 iOS 和 Android 共用。
description
String
离线推送内容，该字段会覆盖消息实例的离线推送展示文本。
extension
String
离线推送透传内容。
ignoreIOSBadge
Boolean
离线推送忽略 badge 计数（仅对 iOS 生效），如果设置为 true，在 iOS 接收端，这条消息不会使 App 的应用图标未读计数增加。
androidOPPOChannelID
String
离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID。
返回值
Promise
示例
// 邀请某个人, 设置 30s 超时, 设置离线消息推送
let promise = chat.invite({
  userID: 'user1',
  data: '',
  timeout: 30, // 设置 30s 超时
  offlinePushInfo: {
     disablePush: false, // 如果接收方不在线，则进行离线推送
     disableVoipPush: false, // 开启 voip 推送需要同时开启离线推送
     title: '', // 离线推送标题
     description: '', // 离线推送内容
     androidOPPOChannelID: '' // 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID
   }
});
promise.then(function(imResponse) { // 发送邀请信令成功
 console.warn('invite success:', imResponse)
}).catch(function(imError) {
  console.warn('invite error:', imError);
});

群聊邀请

首先需通过 建群 、加群 、退群 、解散群 以及群资料 和 群成员 相关接口完成对群组的管理，并监听群内相关事件回调 GROUP_LIST_UPDATED 。然后群成员可以在群内发起群呼叫邀请 inviteInGroup ，被邀请的群成员收到邀请通知 onReceiveNewInvitation 后可以选择接受、拒绝或等待超时。
接口
chat.inviteInGroup(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
groupID
String
群组 ID。
inviteeList
Array
被邀请人列表。
data
String | undefined
自定义数据。
timeout
Number | undefined
超时时间, 设置为 0 时，不超时。
onlineUserOnly
Boolean | undefined
消息是否仅发送给在线用户的标识，默认值为 false；设置为 true，则消息既不存漫游，也不会计入未读，也不会离线推送给接收方， 并且 invite 操作也不会产生历史消息（针对该次 invite 的后续 cancel、accept、reject、timeout 操作也同样不会产生历史消息）。
offlinePushInfo
Object | undefined
?离线推送配置。
offlinePushInfo 的描述如下：
Name
Type
Description
disablePush
Boolean
true 关闭离线推送；false 开启离线推送（默认）。
disableVoipPush
Boolean
true 关闭 voip 推送（默认）；false 开启 voip 推送（开启 voip 推送需要同时开启离线推送）。
title
String
离线推送标题，该字段为 iOS 和 Android 共用。
description
String
离线推送内容，该字段会覆盖消息实例的离线推送展示文本。
extension
String
离线推送透传内容。
ignoreIOSBadge
Boolean
离线推送忽略 badge 计数（仅对 iOS 生效），如果设置为 true，在 iOS 接收端，这条消息不会使 App 的应用图标未读计数增加。
androidOPPOChannelID
String
离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID。
返回值
Promise
示例
// 邀请群内的某些人, 设置 30s 超时, 设置离线消息推送
let promise = chat.inviteInGroup({
  groupID: 'AV1',
  inviteeList: ['user1', 'user2'],
  data: '',
  timeout: 30, // 设置 30s 超时
  offlinePushInfo: {
     disablePush: false, // 如果接收方不在线，则进行离线推送
     disableVoipPush: false, // 开启 voip 推送需要同时开启离线推送
     title: '', // 离线推送标题
     description: '', // 离线推送内容
     androidOPPOChannelID: '' // 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID
   }
});
promise.then(function(imResponse) { // 发送邀请信令成功
 console.warn('inviteInGroup success:', imResponse)
}).catch(function(imError) {
  console.warn('inviteInGroup error:', imError);
});

取消邀请

邀请者可以在超时前且被邀请者未处理前取消邀请 cancel 。被邀请者收到取消通知 onInvitationCancelled，该邀请流程结束。
接口
chat.cancel(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
inviteID
String
邀请的用户 ID， 邀请者 invite / inviteGroup 成功后，返回值中的 inviteID。
data
String | undefined
自定义数据。
返回值
Promise
示例
// 邀请发起者取消邀请
let promise = chat.cancel({
  inviteID: '38897dbf-ecd4-4b59-a132-bc31529a2b18',
  data: '',
})
promise.then(function(imResponse) { // 取消邀请成功
 console.log('cancel OK', imResponse);
}).catch(function(error) {
  console.warn('cancel failed:', error); // 取消邀请失败
});

接受邀请

被邀请者收到邀请通知 onReceiveNewInvitation 后可以在超时前且邀请者取消前接受邀请 accept ，邀请者会收到接受通知 onInviteeAccepted ，所有被邀请者处理完后（包括接受、拒绝、超时）该邀请流程结束。
接口
chat.accept(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
inviteID
String
邀请的用户 ID，被邀请者收到邀请通知 onReceiveNewInvitation中携带的 inviteID。
data
String | undefined
自定义数据。
返回值
Promise
示例
// 被邀请人接受邀请
let promise = chat.accept({
  inviteID: '38897dbf-ecd4-4b59-a132-bc31529a2b18',
  data: '',
})
promise.then(function(imResponse) { // 被邀请人接受邀请成功
 console.log('accept OK', imResponse);
}).catch(function(error) {
  console.warn('accept failed:', error); // 被邀请人接受邀请失败
});

拒绝邀请

被邀请者收到邀请通知 onReceiveNewInvitation 后可以在超时前且邀请者取消前拒绝邀请 reject ，邀请者会收到拒绝邀请通知 onInviteeRejected ，所有被邀请者处理完后（包括接受、拒绝、超时）该邀请流程结束。
接口
chat.reject(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
inviteID
String
邀请的用户 ID，被邀请者收到邀请通知 onReceiveNewInvitation 中携带的 inviteID。
data
String | undefined
自定义数据。
返回值
Promise
示例
// 被邀请人拒绝邀请
let promise = chat.reject({
  inviteID: '38897dbf-ecd4-4b59-a132-bc31529a2b18',
  data: '',
})
promise.then(function(imResponse) { // 被邀请人拒绝邀请成功
 console.log('reject OK', imResponse);
}).catch(function(error) {
  console.warn('reject failed:', error); // 被邀请人拒绝邀请失败
});

邀请超时

若邀请接口的超时时间大于0，且被邀请者未在超时时间之内响应则邀请超时，邀请者和被邀请者都会收到超时通知 onInvitationTimeout ，所有被邀请者处理完后（包括接受、拒绝、超时）该邀请流程结束。若邀请接口的超时时间等于0，则不会有超时通知。

应用场景案例

音视频通话

在开源项目 TUIKit Web Demo 、TUIKit 小程序 Demo 以及 TUIKit Uniapp Demo 中，我们基于 TRTC CallKit 组件 提供了一个适合聊天场景的1v1和多人音视频通话的方案，您可以直接基于我们提供的 Demo 进行修改适配。我们以1v1视频通话为例介绍下信令接口跟 TRTC SDK 的结合使用。
1v1视频通话的流程：
1. 邀请者根据业务层生成的 roomID 进入该 TRTC 房间，同时调用信令邀请接口 invite 发起音视频通话请求，并把 roomID 放到邀请接口的自定义字段中。
2. 被邀请者邀请通过 addSignalingListener 监听收到 TencentCloudChat.TSignaling.NEW_INVITATION_RECEIVED 邀请信令，并通过自定义数据拿到 roomID，界面开始响铃。
3. 被邀请者处理邀请通知：
接受邀请需调用信令 accept 接口，并根据 roomID 进入到 TRTC 房间，并同时调用 openCamera() 函数打开自己本地的摄像头，双方收到 TRTC SDK 的 onRemoteUserEnterRoom 回调后记录本次通话的开始时间。
拒绝邀请需调用信令 reject 接口结束本次通话。
如果被邀请者正在跟其他人通话，则调用信令 reject 接口拒绝本次邀请，并在自定义数据中告诉对方是由于本地线路忙而拒绝。
4. 接听并当双方的音视频通道建立完成后，通话的双方都会接收到 TRTC SDK 的 onUserVideoAvailable 的事件通知，表示对方的视频画面已经拿到。此时双方用户均可以调用 TRTC SDK 接口 startRemoteView 展示远端的视频画面。远端的声音默认是自动播放的。
5. 通话结束即某一方挂断电话，该用户退出 TRTC 房间。对方收到 TRTC SDK 的 onRemoteUserLeaveRoom 回调后计算通话总时长并再次发起一次邀请，此邀请的自定义数据中标明是结束通话并附带通话时长，方便 UI 界面做展示。
时序图
?
?

教育场景中老师邀请学生举手发言

在开源项目 RoomKit Demo 举手发言模式下, 老师先让同学们举手，再从举手的同学中选一个同学进行发言。详细流程如下：
1. 老师调用 inviteInGroup 接口邀请同学们举手，自定义 data 中填入“举手操作”，同学们收到 onReceiveNewInvitation 回调。
2. 同学们根据 onReceiveNewInvitation 中的 inviteeList 和 data 字段判断被邀请者里有自己且是举手操作，那么调用 accept 接口举手。
3. 如果有学生举手，所有人都可以收到 onInviteeAccepted 回调，判断 data 中的字段为“举手操作”，展示举手学生列表。
4. 老师从举手成员列表中邀请某个同学进行发言，调用 inviteInGroup 接口，此时自定义 data 中填入“发言操作”，学生们都收到 onReceiveNewInvitation 回调。
5. 学生根据 onReceiveNewInvitation 回调中的 inviteeList 和 data 字段判断被邀请者里有自己且是发言操作，则调用 accept 接口发言。
6. 如果有学生发言，所有人都可以收到 onInviteeAccepted 回调，判断 data 中的字段为“发言操作”，展示发言成员列表。

常见问题

1. 用户 A 邀请用户 B 时，用户 C 可以邀请用户 B 吗？

SDK 提供的 信令接口 本身不限制邀请的逻辑，一个用户可以同时收到多个邀请信令。对于音视频通话场景，我们的 TUICallKit 组件做了“忙线”提醒。

2. 发送信令邀请时，是否可以同时发送多个 Invite 请求？

可以，上层根据实际业务需求加以区分。

3. IM SDK 的信令接口只有邀请、同意/拒绝、取消，如何实现挂断操作？

邀请操作，上层语义可以理解成请求建连。
挂断操作，上层语义可以理解成请求挂断。
可以使用 IM SDK 的邀请接口，结合自定义 data 来表示当前的邀请是请求建连还是请求挂断，由 IM 透传给对端处理。

4. 发送信令邀请时，对于信令邀请超时的处理逻辑是怎么样的？

当邀请发送方和接收方都在线时，超时信令由接收方触发，且发送方和接收方都会收到 onInvitationTimeout 回调。
当接收方不在线时，超时信令由发送发触发，发送方会收到 onInvitationTimeout 回调。
超时信令均由 IM SDK 发出。

5. 信令回调中 inviteID 是不是唯一的？

是唯一的。inviteID 唯一标识了一组信令消息（包括邀请、同意/拒绝、超时）。
中国站


http://www.vxiaotou.com