logo
当前页

呼叫邀请


功能简介

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 回调,进而收到呼叫邀请相关用户的状态变化。

示例代码

Untitled
// 监听呼叫邀请相关用户的状态变化
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info, const std::string & callID){
    for (const ZIMCallUserInfo &userInfo: info.callUserList) {
        // 状态发生变化的 userID
        std::string userID = userInfo.userID;
        // 当前最新状态
        ZIMCallUserState state = userInfo.state;
        // 透传字段,与用户调用接受、拒绝、退出接口时携带的 extended data 内容一致
        std::string extendedData = userInfo.extendedData;
    }
}
1
Copied!

2 发起呼叫邀请

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

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

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

    说明

    若客户端 B 为离线用户:

示例代码

  • 发送呼叫邀请
Untitled
// 定义回调
auto callinvite_callback = [=](std::string callID, zim::ZIMCallInvitationSentInfo info, zim::ZIMError errorInfo) {
    if (errorInfo.code != 0) {
        ShowMsg(L"发送呼叫邀请失败,callID: %s, 错误码: %d", callID, error_info.code);
    }    
    else {
        ShowMsg(L"发送呼叫邀请成功, callID: %s", callID);
    }
}

// 发起呼叫邀请
std::vector<std::string> invitees;  // 被邀请人列表
invitees.push_back("421234");       // 被邀请人id
zim::ZIMCallInviteConfig config;    

zim::ZIMPushConfig pushConfig;
// 离线推送标题,需要向离线用户发起呼叫邀请时,请填入该字段
pushConfig.title = "win_push_title";
// 离线推送内容,需要向离线用户发起呼叫邀请,请填入该字段
pushConfig.content = "win_push_content";
// 离线推送附加字段,需要向离线用户发起呼叫邀请时带上额外信息,可酌情填入该字段
pushConfig.payload = "win_push_payload";
config.pushConfig = &pushConfig;

zim_->callInvite(invitees, config, callinvite_callback); //发送呼叫邀请
1
Copied!
  • 邀请发起者收到呼叫邀请已创建的通知,示例代码如下:
Untitled
/** 邀请发起者收到呼叫邀请已创建的通知 */
virtual void onCallInvitationCreated(ZIM * /*zim*/,
                                      const ZIMCallInvitationCreatedInfo & /*info*/,
                                      const std::string & /*callID*/) {
    // 这里可以进行相关的 UI 操作
}
1
Copied!
  • 被邀请者收到邀请后的回调通知
Untitled
// 被邀请者收到邀请后的回调通知
// 此处的 callID 是用户发起呼叫后,SDK 内部生成的 ID,用于唯一标识一次呼叫邀请;之后发起人取消呼叫、被邀请人接受/拒绝呼叫,都会使用此 callID
void onCallInvitationReceived(zim::ZIM * zim, zim::ZIMCallInvitationReceivedInfo info,std::string callID) {
    ShowMsg(L"接收到邀请, 邀请者id:%s, callID: %s",info.inviter ,callID);
} 
1
Copied!

3 取消呼叫邀请

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

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

    说明

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

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

示例代码

  • 取消呼叫邀请
Untitled
auto callcancel_callback = [=](std::vector<std::string> errorInvitees, zim::ZIMError errorInfo) {
    if (errorInfo.code != 0) {
        ShowMsg(L"发送取消呼叫邀请失败,错误码: %d",error_info.code);
    }    
    else {
        ShowMsg(L"发送取消呼叫邀请成功");
    }
}

// 取消呼叫邀请
std::vector<std::string> invitees;  // 被邀请人列表
invitees.push_back("421234");       // 被邀请人id
std::string callid = "12352435";        // callid
zim::ZIMCallCancelConfig config;

zim_->callCancel(invitees, callid, config, callcancel_callback);
1
Copied!
  • 被邀请者收到取消邀请后的回调通知
Untitled
// 被邀请者收到取消邀请后的回调通知
void onCallInvitationCancelled(zim::ZIM * zim, zim::ZIMCallInvitationCancelledInfo info,std::string callID) {
    ShowMsg(L"接收到取消邀请, 邀请者id:%s, callID: %s",info.inviter ,callID);
}
1
Copied!

4 接受呼叫邀请

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

  1. 客户端 B 收到客户端 A 发来的呼叫邀请后,通过调用 callAccept 接口,接受该邀请。
  2. 客户端 B 接受邀请后,客户端 A 可以通过 onCallUserStateChanged 回调接口,收到相关通知。如果是在多人呼叫中,则所有现有呼叫成员都可通过此回调收到相关通知。

示例代码

  • 接受呼叫邀请
Untitled
// 接受呼叫邀请

auto callaccept_callback = [=](zim::ZIMError errorInfo) {
    if (errorInfo.code != 0) {
        ShowMsg(L"接受呼叫邀请失败,错误码: %d", error_info.code);
    }    
    else {
        ShowMsg(L"接受呼叫邀请成功");
    }
}

std::string callid = "12352435";        // callid
zim::ZIMCallAcceptConfig config;
zim_->callAccept(callid, config, callaccept_callback);
1
Copied!
  • 呼叫成员收到有用户接受呼叫邀请的通知
Untitled
// 呼叫成员收到有用户接受呼叫邀请的通知
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info,
                                        const std::string & callID){
    // 所有状态为 “Inviting”、“Received” 和 “Accepted” 的用户可在此处收到有用户接受呼叫邀请的通知
}
1
Copied!

5 拒绝呼叫邀请

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

  1. 客户端 B 收到客户端 A 发来的呼叫邀请后,通过调用 callReject 接口,拒绝该邀请。
  2. 客户端 B 拒绝邀请后,客户端 A 可以通过 onCallUserStateChanged 回调接口,收到相关通知。如果是在多人呼叫中,则所有现有呼叫成员都可通过此回调收到相关通知。

示例代码

  • 拒绝呼叫邀请
Untitled
// 拒绝呼叫邀请
auto callreject_callback = [=](zim::ZIMError errorInfo) {
    if (errorInfo.code != 0) {
        ShowMsg(L"拒绝呼叫邀请失败,错误码: %d",error_info.code);
    }    
    else {
        ShowMsg(L"拒绝呼叫邀请成功");
    }
}

std::string callid = "12352435";        // callid
zim::ZIMCallRejectConfig config;
zim_->callAccept(callid, config, callreject_callback );
1
Copied!
  • 呼叫成员收到有用户拒绝呼叫邀请的通知
Untitled
// 呼叫成员收到有用户拒绝呼叫邀请的通知
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info,
                            const std::string & callID){
    // 所有用户状态为 “Inviting”、“Received” 和 “Accepted” 的用户可在此处收到有用户拒绝呼叫邀请的通知
}
1
Copied!

6 超时未响应呼叫邀请

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

  1. 客户端 A(邀请者)通过 onCallUserStateChanged 回调接口,收到邀请超时、客户端未响应的通知。如果是在多人呼叫中,则所有现有呼叫成员都可通过此回调收到相关通知。
  2. 客户端 B(被邀请者)通过 onCallInvitationTimeout 回调接口,收到邀请超时、自己未响应的通知。
Untitled
// 被邀请者响应超时后,“邀请者”收到的回调通知, 超时时间单位:秒
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info,
                            const std::string & callID){
}
1
Copied!
  • 被邀请者响应超时后,“被邀请者”收到的回调通知
Untitled
// 被邀请者响应超时后,“被邀请者”收到的回调通知, 超时时间单位:秒
void onCallInvitationTimeout(zim::ZIM * zim,std::string callID) {
    ShowMsg(L"呼叫邀请超时,callID: %s",callID);
}
1
Copied!

进阶模式

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

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

发起进阶模式的呼叫邀请

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

示例代码

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

vector<std::string> invitees; // 被邀请人ID列表
    
// 邀请超时时间,单位为秒,范围 1 - 600
// mode 为呼叫邀请模式,ZIM_INVITATION_MODE_ADVANCED 表示进阶模式。
ZIMCallInviteConfig config = ZIMCallInviteConfig();
config.mode = ZIM_INVITATION_MODE_ADVANCED;
config.timeout = 90;
ZIM::getInstance()->callInvite(invitees, config, [](const std::string &callID, const ZIMCallInvitationSentInfo &info, const ZIMError &errorInfo){
  if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
    // 操作成功
    // 此处的 callID 是用户发起呼叫后,SDK 内部生成的 ID,用于唯一标识一次呼叫邀请;之后发起人取消呼叫、被邀请人接受/拒绝呼叫,都会使用此 callID
  }else{
    // 操作失败
  }
});
1
Copied!
说明

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

呼叫中邀请

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

示例代码

  • 呼叫中邀请
Untitled
// 呼叫中邀请

vector<std::string> invitees; // 被邀请人ID列表
ZIMCallingInviteConfig config = ZIMCallingInviteConfig();
ZIM::getInstance()->callingInvite(invitees, "callID", config, [](const std::string &callID, const ZIMCallingInvitationSentInfo &info,const ZIMError &errorInfo){
    if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
        // 邀请成功后的业务逻辑
    }else{
        // 根据官网错误码表处理
    }
});
1
Copied!
  • 呼叫成员收到正在邀请其他用户的通知
Untitled
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info,
                                        const std::string & callID){
    // 所有未退出、超时的成员可以在此处收到成员被呼叫邀请的通知
}
1
Copied!

主动加入呼叫或切换设备

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

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

示例代码

Untitled
// 主动加入呼叫或切换设备
zim::ZIMCallJoinConfig config;
config.extendedData = "extendedData";

ZIM::getInstance()->callJoin("callID", config, [=](const std::string &callID, const ZIMCallJoinSentInfo &info, const ZIMError &errorInfo){
    if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
        // 加入成功后的业务逻辑
    }else{
        // 根据官网错误码表处理错误
    }
});
1
Copied!

退出呼叫

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

示例代码

  • 退出呼叫
Untitled
// 退出呼叫
ZIMCallQuitConfig config = ZIMCallQuitConfig();
ZIM::getInstance()->callQuit("callID", config, [](const std::string &callID, const ZIMCallQuitSentInfo &info, const ZIMError &errorInfo){
    if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
        // 退出成功后的业务逻辑
    }else{
        // 根据官网错误码表处理错误
    }
});
1
Copied!
  • 呼叫成员收到有用户退出呼叫的通知
Untitled
void onCallUserStateChanged(ZIM * zim, const ZIMCallUserStateChangeInfo & info,
                                    const std::string & callID){
    // 退出用户本人和用户状态为 “inviting”, “received” 和 “accept” 的其他用户可在此处收到有用户员退出的通知
}
1
Copied!

结束呼叫

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

示例代码

  • 结束呼叫
Untitled
// 结束呼叫
ZIMCallEndConfig config = ZIMCallEndConfig();
ZIM::getInstance()->callEnd("callID", config, [](const std::string &callID, const ZIMCallEndedSentInfo &info, const ZIMError &errorInfo){
        if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
            // 退出成功后的业务逻辑
        }else{
            // 根据官网错误码表处理错误
        }
});
1
Copied!
  • 呼叫成员收到呼叫结束的通知
Untitled
void onCallInvitationEnded(ZIM * /*zim*/, const ZIMCallInvitationEndedInfo & /*info*/,
                                    const std::string & /*callID*/) {
    // 所有状态为 “Inviting”、“Received” 和 “Accepted” 的成员可以在此处收到呼叫结束的通知
}
1
Copied!

呼叫邀请离线推送

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

更多功能

检测邀请是否送达

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

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

inviteConfig.enableNotReceivedCheck = true;
// 发起呼叫邀请相关代码

1
Copied!

主叫发起呼叫邀请后,如果被叫在 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 处理。

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

ZIMCallInvitationQueryConfig config = ZIMCallInvitationQueryConfig();
// 单次查询 20 条呼叫邀请数据
// 超过 100 条按 100 条处理。
config.count = 20;
// 首次查询 nextFlag 填 0,代表从最新的呼叫邀请(创建时间最晚)开始
config.nextFlag = 0;
    
ZIM::getInstance()->queryCallInvitationList(config, [](const std::vector<ZIMCallInfo> &callList, long long nextFlag, const ZIMError &errorInfo){
    if(errorInfo.code == ZIM_ERROR_CODE_SUCCESS){
        if(nextFlag != 0){
            // 如果 callback 返回的 nextFlag 不为 0,代表没有完成查询所有的呼叫邀请信息。下次查询时可以传入 callback 返回的 nextFlag 继续查询剩余呼叫邀请信息
        }
    }else{
        // 根据官网错误码表处理错误
    }
});
1
Copied!

Previous

实现流程

Next

自定义推送规则