概述
信令接口是基于 IM 消息提供的一套邀请流程控制的接口,可以实现多种实时场景,例如:
直播聊天室中进行上麦、下麦管理。
聊天场景中实现类似微信中的音视频通话功能。
教育场景中老师邀请同学们举手、发言的流程控制。
视频通话 | 语音通话 |
| |
功能
单聊邀请
接口
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 | 离线推送透传内容。 |
androidInfo | Object | undefined | Android 推送配置。v3.3.2 起支持。 |
apnsInfo | Object | undefined | iOS 推送配置。v3.3.2 起支持。 |
androidInfo 的描述如下:
Name | Type | Description |
sound | String | Android 离线推送声音设置。只支持华为、小米和谷歌。 小米手机在 Android 8.0 及以上版本必须设置 androidInfo.XiaoMiChannelID,请您参考:小米自定义铃声。 谷歌手机 FCM 推送在 Android 8.0 及以上系统设置声音提示,必须设置 androidInfo.FCMChannelID。 自定义铃音需要设置声音文件路径。例如: androidInfo.sound = "shake.xxx" 对应 uniapp "nativeResources/android/res/raw/shake.xxx" 音频文件. 对应原生应用的 "/res/raw/shake.xxx" 音频文件。 |
XiaoMiChannelID | String | 小米手机 MIUI 10 及以上的通知类别(Channel)适配字段。 |
OPPOChannelID | String | OPPO 手机 Android 8.0 及以上的 NotificationChannel 通知适配字段。 |
FCMChannelID | String | Google 手机 Android 8.0 及以上的通知渠道字段。 |
VIVOClassification | String | VIVO 手机推送消息分类,0:运营消息,1:系统消息,默认为1。 |
VIVOCategory | String | VIVO 手机用来标识消息类型。 |
HuaWeiCategory | String | 华为手机用来标识消息类型。 |
apnsInfo 的描述如下:
Name | Type | Description |
sound | String | iOS 离线推送声音设置。
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND,表示接收时不会播放声音。 当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND,表示接收时播放系统声音。 自定义铃音需要设置声音文件路径。例如: apnsInfo.sound = "shake.xxx" 对应 uniapp "nativeResources/ios/Resources/shake.xxx" 文件,uniapp 必须为正式包。 对应原生 Xcode 工程中的 "shake.xxx" 音频文件。 |
ignoreIOSBadge | Boolean | 离线推送忽略 badge 计数(仅对 iOS 生效),默认为 false,设置为 true 时,在 iOS 接收端,这条消息不会使 App 的应用图标未读计数增加。 |
disableVoipPush | Boolean | true 关闭 voip 推送(默认);false 开启 voip 推送(开启 voip 推送需要同时开启离线推送) |
返回值
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 ,被邀请的群成员收到邀请通知 onNewInvitationReceived 后可以选择接受、拒绝或等待超时。
接口
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 | 离线推送透传内容。 |
androidInfo | Object | undefined | Android 推送配置。v3.3.2 起支持。 |
apnsInfo | Object | undefined | iOS 推送配置。v3.3.2 起支持。 |
androidInfo 的描述如下:
Name | Type | Description |
sound | String | Android 离线推送声音设置。只支持华为、小米和谷歌。 小米手机在 Android 8.0 及以上版本必须设置 androidInfo.XiaoMiChannelID,请您参考:小米自定义铃声。 谷歌手机 FCM 推送在 Android 8.0 及以上系统设置声音提示,必须设置 androidInfo.FCMChannelID。 自定义铃音需要设置声音文件路径。例如: androidInfo.sound = "shake.xxx" 对应 uniapp "nativeResources/android/res/raw/shake.xxx" 音频文件. 对应原生应用的 "/res/raw/shake.xxx" 音频文件。 |
XiaoMiChannelID | String | 小米手机 MIUI 10 及以上的通知类别(Channel)适配字段。 |
OPPOChannelID | String | OPPO 手机 Android 8.0 及以上的 NotificationChannel 通知适配字段。 |
FCMChannelID | String | Google 手机 Android 8.0 及以上的通知渠道字段。 |
VIVOClassification | String | VIVO 手机推送消息分类,0:运营消息,1:系统消息,默认为1。 |
VIVOCategory | String | VIVO 手机用来标识消息类型。 |
HuaWeiCategory | String | 华为手机用来标识消息类型。 |
apnsInfo 的描述如下:
Name | Type | Description |
sound | String | iOS 离线推送声音设置。
当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_NO_SOUND,表示接收时不会播放声音。 当 apnsInfo.sound = TencentCloudChat.TYPES.IOS_OFFLINE_PUSH_DEFAULT_SOUND,表示接收时播放系统声音。 自定义铃音需要设置声音文件路径。例如: apnsInfo.sound = "shake.xxx" 对应 uniapp "nativeResources/ios/Resources/shake.xxx" 文件,uniapp 必须为正式包。 对应原生 Xcode 工程中的 "shake.xxx" 音频文件。 |
ignoreIOSBadge | Boolean | 离线推送忽略 badge 计数(仅对 iOS 生效),默认为 false,设置为 true 时,在 iOS 接收端,这条消息不会使 App 的应用图标未读计数增加。 |
disableVoipPush | Boolean | true 关闭 voip 推送(默认);false 开启 voip 推送(开启 voip 推送需要同时开启离线推送) |
返回值
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);});
取消邀请
接口
chat.cancel(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name | Type | Description |
inviteID | String | |
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); // 取消邀请失败});
接受邀请
被邀请者收到邀请通知 onNewInvitationReceived 后可以在超时前且邀请者取消前接受邀请 accept ,邀请者会收到接受通知 onInviteeAccepted ,所有被邀请者处理完后(包括接受、拒绝、超时)该邀请流程结束。
接口
chat.accept(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name | Type | Description |
inviteID | String | |
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); // 被邀请人接受邀请失败});
拒绝邀请
被邀请者收到邀请通知 onNewInvitationReceived 后可以在超时前且邀请者取消前拒绝邀请 reject ,邀请者会收到拒绝邀请通知 onInviteeRejected ,所有被邀请者处理完后(包括接受、拒绝、超时)该邀请流程结束。
接口
chat.reject(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
Name | Type | Description |
inviteID | String | |
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,则不会有超时通知。
应用场景案例
TIMPush 推送插件
说明:
信令中默认没有集成 TencentCloud-TIMPush 推送插件。TencentCloud-TIMPush 是腾讯云即时通信 IM Push 插件。目前推送支持小米、华为、荣耀、OPPO、vivo、魅族、APNs、一加、realme、iQOO 和 苹果等厂商通道。
音视频通话
在开源项目 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 界面做展示。教育场景中老师邀请学生举手发言
1. 老师调用 inviteInGroup 接口邀请同学们举手,自定义
data
中填入“举手操作”,同学们收到 onNewInvitationReceived 回调。2. 同学们根据 onNewInvitationReceived 中的
inviteeList
和 data
字段判断被邀请者里有自己且是举手操作,那么调用 accept 接口举手。3. 如果有学生举手,所有人都可以收到 onInviteeAccepted 回调,判断
data
中的字段为“举手操作”,展示举手学生列表。4. 老师从举手成员列表中邀请某个同学进行发言,调用 inviteInGroup 接口,此时自定义
data
中填入“发言操作”,学生们都收到 onNewInvitationReceived 回调。5. 学生根据 onNewInvitationReceived 回调中的
inviteeList
和 data
字段判断被邀请者里有自己且是发言操作,则调用 accept 接口发言。6. 如果有学生发言,所有人都可以收到 onInviteeAccepted 回调,判断
data
中的字段为“发言操作”,展示发言成员列表。常见问题
1. 用户 A 邀请用户 B 时,用户 C 可以邀请用户 B 吗?
2. 发送信令邀请时,是否可以同时发送多个 Invite 请求?
可以,上层根据实际业务需求加以区分。
3. Chat SDK 的信令接口只有邀请、同意/拒绝、取消,如何实现挂断操作?
邀请操作,上层语义可以理解成请求建连。
挂断操作,上层语义可以理解成请求挂断。
可以使用 Chat SDK 的邀请接口,结合自定义 data 来表示当前的邀请是请求建连还是请求挂断,由 Chat 透传给对端处理。
4. 发送信令邀请时,对于信令邀请超时的处理逻辑是怎么样的?
当邀请发送方和接收方都在线时,超时信令由接收方触发,且发送方和接收方都会收到
onInvitationTimeout
回调。当接收方不在线时,超时信令由发送发触发,发送方会收到
onInvitationTimeout
回调。超时信令均由 Chat SDK 信令模块发出。
5. 信令回调中 inviteID 是不是唯一的?
是唯一的。inviteID 唯一标识了一组信令消息(包括邀请、同意/拒绝、超时)。