logo
控制台登录/注册
文档
客户端 API
服务端 API
即时通讯
Flutter: Dart
产品简介
概述
计费说明
基本概念介绍
客户端 SDK
下载
客户端 APIlink
发布日志
升级指南
错误码
快速开始
跑通示例代码
实现基本消息收发
功能指引
用户
房间
群组
消息
会话
缓存管理
内容审核
呼叫邀请
离线推送
ZIM Audio
最佳实践
迁移方案
常见问题link
当前页

呼叫邀请

功能简介

ZIM SDK 提供了呼叫邀请功能，支持主叫向被叫（可为离线状态）发送呼叫邀请、被叫（可为离线状态）接受或拒绝邀请等完整的业务流程控制能力。呼叫邀请分为两种模式，普通模式与进阶模式。

普通模式的呼叫邀请支持用户发起、取消、接受、拒绝和超时未响应。在此基础上，进阶模式的呼叫邀请还允许用户中途邀请他人、退出以及结束呼叫。

说明

“呼叫邀请” 功能仅提供了基本的业务流程控制能力，开发者需要自行实现使用本功能的业务需求（例如，通常应用在聊天工具中，发起语音通话或视频通话邀请等场景中）。

呼叫用户状态说明

呼叫用户状态（ ZIMCallUserState ），是指用户在呼叫邀请各个环节中的状态。本节主要介绍状态如何流转，以及状态与接口/回调的关系。

状态流转

从呼叫邀请发起到呼叫结束，呼叫用户状态流转如下图所示：

状态含义触发事件适用模式
Inviting被邀请中。用户正在被邀请。
  • 普通模式。
  • 进阶模式。
Accepted已接受邀请。
  • 用户发起呼叫邀请。
  • 用户接受呼叫邀请。
Rejected已拒绝邀请。用户拒绝呼叫邀请。
Cancelled已取消邀请。
  • 用户主动取消呼叫邀请.
  • 被叫尚未应答邀请，而主叫掉线且心跳超时。
Received已收到邀请。
  • 在线用户收到邀请。
  • 离线用户在超时范围内上线。
Timeout超时未接受。被叫用户超时未响应邀请。
Quit退出。呼叫实现后，用户退出呼叫。
  • 进阶模式。
Unknown未知。请联系 ZEGO 技术支持。

状态与接口/回调的关系

在用户在进行呼叫邀请时，其呼叫用户状态会影响用户是否可以调用某些接口，或者监听某些事件。

  • 各状态可调用接口：
callInvitecallCancelcallAcceptcallRejectcallInvitecallQuitcallEnd
Inviting与呼叫用户状态无关，只需用户不在呼叫中，即可调用。与呼叫用户状态无关，只需用户发起邀请后，无人应答即可调用。✔️✔️✖✖✖
Accepted✖✖✔️✔️✔️
Rejected✖✖✖✖✖
Cancelled✖✖✖✖✖
Received✔️✔️✖✖✖
Timeout✖✖✖✖✖
Quit✖✖✖✖✖
Unknown✖✖✖✖✖
  • 各状态可监听事件：
onCallInvitationReceivedonCallInvitationTimeoutonCallInvitationCancelledonCallInvitationEndedonCallUserStateChanged
Inviting✔️✔️✔️✔️✔️
Accepted✖✖✖✔️✔️
Rejected✖✖✖✖✖
Cancelled✖✖✖✖✖
Received✖✖✔️✔️✔️
Timeout✖✖✖✖✖
Quit✖✖✖✖✔️
Unknown✖✖✖✖✖

普通模式

普通模式下，呼叫邀请的生命周期在全员响应后随即结束（所有被叫接受、拒绝、邀请超时之后）。以下，我们以客户端 A（邀请者）向客户端 B（被邀请者）发起呼叫邀请为例。

1 监听邀请者和被邀请者的状态变化

开发者可以监听 onCallUserStateChanged 回调，进而收到呼叫邀请相关用户的状态变化。

// 监听邀请者和被邀请者的状态变化
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
    for(ZIMCallUserInfo userInfo in callUserStateChangeInfo.callUserList){

        // 状态发生变化的 userID

        String userID = userInfo.userID;
        // 该用户当前最新的状态
        ZIMCallUserState state = userInfo.state;

        // 透传字段，与用户调用接受、拒绝、退出接口时携带的 extended data 内容一致
        String extendedData = userInfo.extendedData;
    }
};

2 发起呼叫邀请

客户端 A 向客户端 B 发起呼叫邀请时，流程如下：

  1. 客户端 A 注册 onCallInvitationCreated 回调接口，以便接收呼叫邀请已创建的通知；客户端 B 通过注册 onCallInvitationReceived 回调接口，以便接收客户端 A 的邀请通知。

  2. 客户端 A 通过调用 callInvite 接口，发起呼叫邀请，客户端 B 在收到邀请信息后，可以选择 接受 或者 拒绝。

    说明

    若客户端 B 为离线用户：

  • 发送呼叫邀请
// 发送呼叫邀请
List<String> invitees = []; // 被邀请人列表
invitees.add('1234'); //被邀请人 id
ZIMCallInviteConfig callInviteConfig = ZIMCallInviteConfig();
callInviteConfig.timeout = 200; //邀请超时时间，单位为秒，范围1-600

// （可选）需要向离线用户发起呼叫邀请时填写
ZIMPushConfig pushConfig = ZIMPushConfig();
pushConfig.title = "your title";
pushConfig.content = "your content";
pushConfig.payload = "your payload";
config.pushConfig = pushConfig;

ZIM
    .getInstance()
    !.callInvite(invitees, callInviteConfig)
    .then((value) => {})
    .catchError((onError) {});
  • 邀请发起者收到呼叫邀请已创建的通知，示例代码如下：
/** 邀请发起者收到呼叫邀请已创建的通知 */
ZIMEventHandler.onCallInvitationCreated = (ZIM zim, ZIMCallInvitationCreatedInfo info, String callID){

};
  • 被邀请者收到邀请后的回调通知
//被邀请者收到邀请后的回调通知
ZIMEventHandler.onCallInvitationReceived = (zim, info, callID) {
    
};

3 取消呼叫邀请

客户端 A 向客户端 B 发起呼叫邀请后、又取消邀请时，流程如下：

  1. 客户端 A 发起呼叫邀请后，如果需要取消，可以调用 callCancel 接口，主动选择取消当前邀请。

    说明

    在呼叫邀请成功创建后至其超时前，如果没有任何被叫用户接受，主叫用户主动登出或因心跳超时而掉线，也会导致呼叫邀请被取消。

  2. 邀请取消后，客户端 B 会收到 onCallInvitationCancelled 回调接口的相关通知。

  • 取消呼叫邀请
// 取消呼叫邀请
List<String> invitees;  // 被邀请人列表
invitees.add("421234");       // 被邀请人id
String callid = "12352435";        // callid
ZIMCallCancelConfig config = new ZIMCallCancelConfig();

ZIM
    .getInstance()
    !.callCancel(invitees, callID, callCancelConfig)
    .then((value) => {})
    .catchError((onError) {});
  • 被邀请者收到取消邀请后的回调通知
//被邀请者收到取消邀请后的回调通知
ZIMEventHandler.onCallInvitationCancelled = (zim, info, callID) {
    
};

4 接受呼叫邀请

客户端 B 收到客户端 A 的呼叫邀请后，选择接受邀请时，流程如下：

  1. 客户端 B 收到客户端 A 发来的呼叫邀请后，通过调用 callAccept 接口，接受该邀请。
  2. 客户端 B 接受邀请后，客户端 A 可以通过 onCallUserStateChanged 回调接口，收到相关通知。如果是在多人呼叫中，则所有现有呼叫成员都可通过此回调收到相关通知。
  • 接受呼叫邀请
ZIMCallAcceptConfig callAcceptConfig = ZIMCallAcceptConfig();
ZIM
    .getInstance()
    !.callAccept(callID, callAcceptConfig)
    .then((value) => {})
    .catchError((onError) {});
  • 呼叫成员收到有用户接受呼叫邀请的通知
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
    // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户接受呼叫邀请的通知
};

5 拒绝呼叫邀请

客户端 B 收到客户端 A 的呼叫邀请后，选择拒绝邀请时，流程如下：

  1. 客户端 B 收到客户端 A 发来的呼叫邀请后，通过调用 callReject 接口，拒绝该邀请。
  2. 客户端 B 拒绝邀请后，客户端 A 可以通过 onCallUserStateChanged 回调接口，收到相关通知。如果是在多人呼叫中，则所有现有呼叫成员都可通过此回调收到相关通知。
  • 拒绝呼叫邀请
String callID = "12352435";        // callID
ZIMCallRejectConfig rejectConfig = ZIMCallRejectConfig();
ZIM.getInstance()!.callReject(callID, rejectConfig).then((value) => {}).catchError((onError){});
  • 呼叫成员收到有用户拒绝呼叫邀请的通知
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
    // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户拒绝呼叫邀请的通知
};

6 超时未响应呼叫邀请

客户端 B 收到客户端 A 的呼叫邀请后，客户端 B 长时间未响应时，流程如下：

  1. 客户端 A（邀请者）通过 onCallUserStateChanged 回调接口，收到邀请超时、客户端未响应的通知。如果是在多人呼叫中，则所有现有呼叫成员都可通过此回调收到相关通知。
  2. 客户端 B（被邀请者）通过 onCallInvitationTimeout 回调接口，收到邀请超时、自己未响应的通知。
  • Callback received by the inviter after the invitee did not response within the timeout period.
// 被邀请者响应超时后,“邀请者”收到的回调通知
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
    // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户超时的通知
};
  • 被邀请者响应超时后,“被邀请者”收到的回调通知
// 被邀请者响应超时后，“被邀请者”收到的回调通知，超时时间单位：秒
ZIMEventHandler.onCallInvitationTimeout = (ZIM zim, ZIMCallInvitationTimeoutInfo info, String callID) {
    
};

进阶模式

如果您想要实现更为丰富的用户状态场景，比如多人呼叫邀请业务场景，可以参考本节内容实现进阶模式的呼叫邀请。

发起进阶模式的呼叫邀请后，呼叫邀请的生命周期延长至用户主动调用 callEnd 接口结束呼叫。在结束呼叫之前，用户还可以实现在呼叫中继续邀请他人以及退出呼叫的功能。

发起进阶模式的呼叫邀请

开发者在调用 callInvite 接口时主动设置模式为进阶模式，才能发起进阶模式的呼叫邀请。

// 向用户发送呼叫邀请 - 进阶模式

List<String> invitees = ["421234"];  // 被邀请人 ID 列表
  
ZIMCallInviteConfig config = ZIMCallInviteConfig();
config.timeout = 200; // 邀请超时时间，单位为秒，范围 1-600
//  mode 为呼叫邀请模式，advanced 表示进阶模式。
config.mode = ZIMCallInvitationMode.advanced;

// （可选）需要向离线用户发起呼叫邀请时填写
ZIMPushConfig pushConfig = ZIMPushConfig();
pushConfig.title = "your title";
pushConfig.content = "your content";
pushConfig.payload = "your payload";
config.pushConfig = pushConfig;

ZIM.getInstance()!.callInvite(invitees, config).then((ZIMCallInvitationSentResult result){
    // 此处的 callID 是用户发起呼叫后，SDK 内部生成的 ID，用于唯一标识一次呼叫邀请；之后发起人取消呼叫、被邀请人接受/拒绝呼叫，都会使用此 callID
});
说明

除了发起外，呼叫邀请的进阶模式和普通模式在取消、接受、拒绝和超时未响应上没有差别。

呼叫中邀请

在创建进阶模式呼叫邀请后，状态为 Accepted 的用户可以调用 callingInvite 接口向不在本呼叫中的用户发起邀请。但是，同一个呼叫中的参与用户不能超过 10 人（含邀请创建用户）。

  • 呼叫中邀请
// 呼叫中邀请
List<String> inviteesList = ["A","B"];
ZIMCallingInviteConfig inviteConfig = ZIMCallingInviteConfig();
// callID 通过创建进阶模式呼叫邀请的回调获取
ZIM.getInstance()!.callingInvite(inviteesList, "callID", inviteConfig).then((value) {
    //邀请成功后的业务逻辑
}).catchError((onError) {
    //根据官网错误码表处理
});
  • 呼叫成员收到正在邀请其他用户的通知
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
        // 所有用户状态为“inviting”,"received"和“accept”的用户可在此处收到有用户被呼叫邀请的通知
};

主动加入呼叫或切换设备

实现进阶模式呼叫邀请后，以下两种情况下，可以调用 callJoin 接口：

  • 没有加入呼叫的用户希望加入呼叫。
    • 对于呼叫外用户加入成功的场景，该用户的状态将流转为 accepted，此时呼叫中的所有用户收到 onCallUserStateChanged 的通知回调。
  • 多端登录用户使用设备 A 发起或接受邀请后，希望让其他设备成为新的主设备。
    • 对于切换设备的场景，呼叫内其他用户无感知。
说明
  • 主设备，是指主动调用发起、接受或加入呼叫接口参与呼叫的设备。
  • 只有主设备能感知呼叫邀请的变化，其他设备只能通过查询呼叫邀请列表来获取呼叫邀请内的数据。
// 主动加入呼叫或切换设备

ZIMCallJoinConfig joinConfig = ZIMCallJoinConfig();
joinConfig.extendedData = "extendedData";
ZIM.getInstance()?.callJoin('callID',joinConfig).then((result) => {
    // 加入成功后的业务逻辑
}).catchError((onError){
    // 根据官网错误码表处理错误
});

退出呼叫

实现进阶模式呼叫邀请后，呼叫用户状态为 Accepted 的用户可调用 callQuit 接口退出呼叫。退出成功后，该用户的状态将流转为 quit，该用户和仍在呼叫中的其他用户都将会收到 onCallUserStateChanged 的通知回调。

  • 退出呼叫
// 退出呼叫
ZIMCallQuitConfig config = ZIMCallQuitConfig();
// callID 通过创建进阶模式呼叫邀请的回调获取
ZIM.getInstance()!.callQuit("callID", config).then((value) {
    // 退出成功后的业务逻辑
}).catchError((onError){
    // 退出失败的业务逻辑
});
  • 呼叫成员收到有用户退出呼叫的通知
ZIMEventHandler.onCallUserStateChanged = (ZIM zim, ZIMCallUserStateChangeInfo callUserStateChangeInfo, String callID){
        // 退出用户本人和用户状态为 “inviting”, “received” 和 “accept” 的其他用户可在此处收到有用户员退出呼叫的通知
};

结束呼叫

实现进阶模式呼叫邀请后，呼叫用户状态为 Accepted 的用户可调用 callEnd 接口结束呼叫。此后，所有人的状态保持不变，该呼叫的状态（callState）变为 end，状态为 Iniviting、Accepted 和 Received 的用户将会收到 onCallInvitationEnded 的通知回调。

  • 结束呼叫
// 结束呼叫
ZIMCallEndConfig config = ZIMCallEndConfig();
// callID 通过创建进阶模式呼叫邀请的回调获取
ZIM.getInstance()!.callEnd("callID", config).then((value) {
    // 结束成功后的业务逻辑
}).catchError((onError){
    // 根据官网错误码表处理错误
});
  • 呼叫成员收到呼叫结束的通知
ZIMEventHandler.onCallInvitationEnded = (ZIM zim, ZIMCallInvitationEndedInfo info, String callID) {
    
};

呼叫邀请离线推送

  • （可选）如需实现呼叫邀请离线推送，请参考下表。
呼叫邀请离线推送发起端呼叫邀请离线推送接收端接收端配置参考文档
  • iOS
  • Android
  • macOS
  • Windows
  • Web
  • 小程序
  • iOS
  • Android

更多功能

检测邀请是否送达

如需让邀请内在线用户了解其他用户是否收到邀请，从而实现相关业务逻辑，请在发起呼叫邀请时，将 ZIMCallInviteConfig 中的 enableNotReceivedCheck 修改为 true，从而开始检测邀请是否送达。

ZIMCallInviteConfig inviteConfig = ZIMCallinviteConfig();
// 开启暂未送达检测
inviteConfig.enableNotReceivedCheck = true;

// 发起呼叫邀请相关代码

主叫发起呼叫邀请后，如果被叫在 5 秒内（可联系 ZEGO 技术支持将间隔调整为 3 秒或 4 秒）因断网、未上线等原因没有接收到本次邀请：

  • 若该被叫客户端使用 2.14.0 之后版本的 ZIM SDK，其用户状态将会流转为 ZIMCallUserState.NOT_YET_RECEIVED，表示邀请暂未送达。此时可实现业务逻辑，向呼叫邀请内在线用户展示“该用户可能不在线，暂时无法接收呼叫邀请”等 UI 提示。
  • 若该被叫客户端使用 2.14.0 及之前版本的 ZIM SDK，其用户状态仍然保持为 ZIMCallUserState.INVITING。如果该状态保持 5 秒以上，也可以实现上述业务逻辑。
说明

请参考 如何监听邀请者和被邀请者的状态变化 了解更多。

随后，如果在邀请超时前，该被叫用户上线并接收该邀请，该成员的用户状态将流转为 ZIMCallUserState.RECEIVED。

查询呼叫邀请列表

通过调用 queryCallInvitationList 接口，用户可以查询与自己相关的呼叫邀请列表，单次查询上限为 100 条，超过 100 条按 100 处理。

// 查询用户自己的呼叫邀请列表 

ZIMCallInvitationQueryConfig queryCallListConfig = ZIMCallInvitationQueryConfig();
queryCallListConfig.count = 20;
queryCallListConfig.nextFlag = 0;

ZIM.getInstance()!.queryCallInvitationList(queryCallListConfig).then((ZIMCallInvitationListQueriedResult result) {
    if(result.nextFlag != 0){
      // 如果 callback 返回的 nextFlag 不为 0，代表没有完成查询所有的呼叫邀请信息。下次查询时可以传入 callback 返回的 nextFlag 继续查询剩余呼叫邀请信息
      queryCallListConfig.nextFlag = result.nextFlag;
    }
}).catchError((onError){
    // 根据官网错误码表处理错误
});

Previous

实现流程

Next

实现离线推送

当前页

返回到顶部