即时通信 IM
容器与中间件专题文档捉虫活动邀您参加 > HOT
文档中心>即时通信 IM>无 UI 集成>信令相关>信令管理>Web&小程序&uni-app

Web&小程序&uni-app

最近更新时间：2024-07-03 10:35:51

我的收藏

本页目录：

概述

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







功能

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

单聊邀请

您可以使用 invite 信令接口进行点对点呼叫，对方收到邀请通知 onNewInvitationReceived 后可以选择接受、拒绝或等待超时。
接口
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);
});

取消邀请

邀请者可以在超时前且被邀请者未处理前取消邀请 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); // 取消邀请失败
});

接受邀请

被邀请者收到邀请通知 onNewInvitationReceived 后可以在超时前且邀请者取消前接受邀请 accept ，邀请者会收到接受通知 onInviteeAccepted ，所有被邀请者处理完后（包括接受、拒绝、超时）该邀请流程结束。
接口
chat.accept(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
inviteID
String
邀请的用户 ID，被邀请者收到邀请通知 onNewInvitationReceived中携带的 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); // 被邀请人接受邀请失败
});

拒绝邀请

被邀请者收到邀请通知 onNewInvitationReceived 后可以在超时前且邀请者取消前拒绝邀请 reject ，邀请者会收到拒绝邀请通知 onInviteeRejected ，所有被邀请者处理完后（包括接受、拒绝、超时）该邀请流程结束。
接口
chat.reject(options);
参数
参数 options 为 Object 类型，包含的属性值如下：
Name
Type
Description
inviteID
String
邀请的用户 ID，被邀请者收到邀请通知 onNewInvitationReceived 中携带的 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，则不会有超时通知。

应用场景案例

TIMPush 推送插件

说明：
信令中默认没有集成 TencentCloud-TIMPush 推送插件。TencentCloud-TIMPush 是腾讯云即时通信 IM Push 插件。目前推送支持小米、华为、荣耀、OPPO、vivo、魅族、APNs、一加、realme、iQOO 和 苹果等厂商通道。
如果您在使用信令时，需要在 App 中集成离线推送能力，请参见 uni-app 推送 实现。




音视频通话

在开源项目 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 中填入“举手操作”，同学们收到 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 吗？

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

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

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

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

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

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

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

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

是唯一的。inviteID 唯一标识了一组信令消息（包括邀请、同意/拒绝、超时）。
中国站
文档反馈
文档活动
message-icon联系我们
目录