呼叫邀请

---

功能简介

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

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

呼叫用户状态说明

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

状态流转

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

状态与接口/回调的关系

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

• 各状态可调用接口：

  	callInviteWithInvitees	callCancelWithInvitees	callAcceptWithCallID	callRejectWithCallID	callInviteWithInvitees	callQuit	callEnd
  Inviting	与呼叫用户状态无关，只需用户不在呼叫中，即可调用。	与呼叫用户状态无关，只需用户发起邀请后，无人应答即可调用。	✔️	✔️	✖	✖	✖
  Accepted			✖	✖	✔️	✔️	✔️
  Rejected			✖	✖	✖	✖	✖
  Cancelled			✖	✖	✖	✖	✖
  Received			✔️	✔️	✖	✖	✖
  Timeout			✖	✖	✖	✖	✖
  Quit			✖	✖	✖	✖	✖
  Unknown			✖	✖	✖	✖	✖

• 各状态可监听事件：

  	callInvitationReceived	callInvitationTimeout	callInvitationCancelled	callInvitationEnded	callUserStateChanged
  Inviting	✔️	✔️	✔️	✔️	✔️
  Accepted	✖	✖	✖	✔️	✔️
  Rejected	✖	✖	✖	✖	✖
  Cancelled	✖	✖	✖	✖	✖
  Received	✖	✖	✔️	✔️	✔️
  Timeout	✖	✖	✖	✖	✖
  Quit	✖	✖	✖	✖	✔️
  Unknown	✖	✖	✖	✖	✖

前提条件

在实现“呼叫邀请”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

• （可选）如需实现呼叫邀请离线推送，请参考下表。

  呼叫邀请离线推送发起端	呼叫邀请离线推送接收端	接收端配置参考文档
  iOS Android macOS Windows Web 小程序	iOS Android	实现离线推送 - iOS 实现离线推送 - Android

普通模式

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

1 监听呼叫邀请相关用户的状态变化

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

// 监听呼叫邀请相关用户的状态变化
-(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
    for (ZIMCallUserInfo *userInfo in info.callUserList) {
        // 用户状态发生变化的 userID
        NSString *userID = userInfo.userID;

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

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

2 发起呼叫邀请

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

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

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

   若客户端 B 为离线用户：

   • 在 timeout（邀请超时时间）内登录，即可通过 callInvitationReceived 收到呼叫邀请通知。
   • 在 timeout 外登录，请调用 queryCallInvitationListWithConfig 来 查询呼叫邀请列表。

callInviteWithInvitees 说明

- (void)callInviteWithInvitees:(NSArray<NSString *> *)invitees
                        config:(ZIMCallInviteConfig *)config
                      callback:(ZIMCallInvitationSentCallback)callback

示例代码

• 发送呼叫邀请

  // 发送呼叫邀请
  NSArray<NSString *> * invitees = @[@"421234"];  // 被邀请人列表
  
  ZIMCallInviteConfig *callInviteConfig = [[ZIMCallInviteConfig alloc] init]; 
  // 设置邀请的超时时间
  callInviteConfig.timeout = 200;
  
  // （可选）需要向离线用户发起呼叫邀请并推送相关离线通知时填写
  ZIMPushConfig *pushConfig = [[ZIMPushConfig alloc] init];
  pushConfig.title = @"your title";
  pushConfig.content = @"your content";
  pushConfig.payload = @"your payload";
  callInviteConfig.pushConfig = pushConfig;
  
  [zim callInviteWithInvitees:invitees config:callInviteConfig callback:^(NSString *callID, ZIMCallInvitationSentInfo *info,ZIMError *errorInfo){
      // 这里填发送呼叫邀请后的回调
      // 此处的 callID 是用户发起呼叫后，SDK 内部生成的 ID，用于唯一标识一次呼叫邀请；之后发起人取消呼叫、被邀请人接受/拒绝呼叫，都会使用此 callID
  }];

• 邀请发起者收到呼叫邀请已创建的通知，示例代码如下：

  /** 邀请发起者收到呼叫邀请已创建的通知 */
  - (void)zim:(ZIM *)zim
      callInvitationCreated:(ZIMCallInvitationCreatedInfo *)info
                 callID:(NSString *)callID{
      // 这里填呼叫邀请发起者收到邀请创建成功的回调通知
  }

• 被邀请者收到邀请后的回调通知

  // 被邀请者收到邀请后的回调通知
  - (void)zim:(ZIM *)zim
      callInvitationReceived:(ZIMCallInvitationReceivedInfo *)info
                      callID:(NSString *)callID{
      // 这里填被邀请者收到邀请后的回调通知
  } 

3 取消呼叫邀请

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

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

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

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

callCancelWithInvitees 说明

- (void)callCancelWithInvitees:(NSArray<NSString *> *)invitees
                        callID:(NSString *)callID
                        config:(ZIMCallCancelConfig *)config
                      callback:(ZIMCallCancelSentCallback)callback

示例代码

• 取消呼叫邀请

  // 取消呼叫邀请
  NSArray<NSString *> * invitees = @[@"421234"];  // 被邀请人列表
  NSString* callid = @"12352435";  // callid
  ZIMCallCancelConfig *callCancelConfig = [[ZIMCallCancelConfig alloc] init]; 
  
  [zim callCancelWithInvitees:invitees callID:self.callID config:callCancelConfig callback:^(NSString * _Nonnull callID, NSArray<NSString *> * _Nonnull errorInvitees, ZIMError * _Nonnull errorInfo) {
      //这里填取消呼叫邀请后的回调
  }];
  

• 被邀请者收到取消邀请后的回调通知

  // 被邀请者收到取消邀请后的回调通知
  - (void)zim:(ZIM *)zim
      callInvitationCancelled:(ZIMCallInvitationCancelledInfo *)info
                      callID:(NSString *)callID{
      // 这里填被邀请者收到取消邀请后的回调通知
  }
  

4 接受呼叫邀请

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

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

callAcceptWithCallID 说明

- (void)callAcceptWithCallID:(NSString *)callID
                      config:(ZIMCallAcceptConfig *)config
                    callback:(ZIMCallAcceptanceSentCallback)callback

示例代码

• 接受呼叫邀请

// 接受呼叫邀请
NSString* callid = @"12352435";  // callid
ZIMCallAcceptConfig*callAcceptConfig = [[ZIMCallAcceptConfig alloc] init]; 
[zim callAcceptWithCallID:self.callID config:callAcceptConfig callback:^(NSString * _Nonnull callID, ZIMError * _Nonnull errorInfo) {
    // 这里填接受呼叫邀请后的回调
}];

[zim callAcceptWithCallID:callid config:callAcceptConfig  callback:^(ZIMError *errorInfo){
    // 这里填接受呼叫邀请后的回调
}];

• 呼叫成员收到有用户接受呼叫邀请的通知

-(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
    // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户接受呼叫邀请的通知
}

5 拒绝呼叫邀请

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

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

callRejectWithCallID 说明

- (void)callRejectWithCallID:(NSString *)callID
                      config:(ZIMCallRejectConfig *)config
                    callback:(ZIMCallRejectionSentCallback)callback

示例代码

• 拒绝呼叫邀请

  // 拒绝呼叫邀请
  NSString* callid = @"12352435";  // callid
  ZIMCallRejectConfig* callRejectConfig = [[ZIMCallRejectConfig alloc] init]; 
  
  [zim callRejectWithCallID:self.callID config:callRejectConfig callback:^(NSString * _Nonnull callID, ZIMError * _Nonnull errorInfo) {
      // 这里填拒绝呼叫邀请后的回调
  }];
  

• 呼叫成员收到有用户拒绝呼叫邀请的通知

  -(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
      // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户拒绝呼叫邀请的通知
  }

6 超时未响应呼叫邀请

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

1. 客户端 A（邀请者）通过 callUserStateChanged 回调接口，收到邀请超时、客户端未响应的通知。如果是在多人呼叫中，则所有现有呼叫成员都可通过此回调收到相关通知。
2. 客户端 B（被邀请者）通过 callInvitationTimeout 回调接口，收到邀请超时、自己未响应的通知。

示例代码

• 被邀请者响应超时后，“邀请者”收到的回调通知

  // 被邀请者响应超时后，“被邀请者”收到的回调通知
  -(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
      // 所有用户状态为“Inviting”、“Accepted“和“Received”的用户可在此处收到有用户接受呼叫邀请的通知
  }

• 被邀请者响应超时后，“被邀请者”收到的回调通知

  // 被邀请者响应超时后，“被邀请者”收到的回调通知
  -(void)zim:(ZIM *)zim callInvitationTimeout:(NSString *)callID {
      // 这里填被邀请者响应超时后,“被邀请者”收到的回调通知, 超时时间单位：秒
  }

进阶模式

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

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

发起进阶模式的呼叫邀请

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

示例代码：

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

NSArray<NSString *> * invitees = @[@"421234"];  // 被邀请人列表

ZIMCallInviteConfig *callInviteConfig = [[ZIMCallInviteConfig alloc] init]; 
//  mode 为呼叫邀请模式，ZIMCallInvitationModeAdvanced 表示进阶模式。
callInviteConfig.mode = ZIMCallInvitationModeAdvanced;
// 设置邀请的超时时间
callInviteConfig.timeout = 200;

//（可选）需要向离线用户发起呼叫邀请并推送相关离线通知时填写
ZIMPushConfig *pushConfig = [[ZIMPushConfig alloc] init];
pushConfig.title = @"your title";
pushConfig.content = @"your content";
pushConfig.payload = @"your payload";
callInviteConfig.pushConfig = pushConfig;

[zim callInviteWithInvitees:invitees config:callInviteConfig callback:^(NSString *callID, ZIMCallInvitationSentInfo *info,ZIMError *errorInfo){
    // 这里填发送呼叫邀请后的回调
    // 此处的 callID 是用户发起呼叫后，SDK 内部生成的 ID，用于唯一标识一次呼叫邀请；之后发起人取消呼叫、被邀请人接受/拒绝呼叫，都会使用此 callID
}];

呼叫中邀请

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

示例代码

• 呼叫中邀请

  // 呼叫中邀请
  ZIMCallingInviteConfig *config = [[ZIMCallingInviteConfig alloc] init];
  
  // callID 通过创建进阶呼叫邀请的回调获取
  [[ZIM getInstance] callingInviteWithInvitees:@[@"invitees"] callID:self.callID config:config callback:^(NSString * _Nonnull callID, ZIMCallingInvitationSentInfo * _Nonnull info, ZIMError * _Nonnull errorInfo) {
      if(errorInfo.code != ZIMErrorCodeSuccess){
          // 根据官网错误码表处理
          return;
      }
      // 邀请成功后的业务逻辑
  }];

• 呼叫成员收到正在邀请其他用户的通知

  -(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
      // 所有用户状态为“邀请中”和“已接受”的用户可以在此处收到正在呼叫邀请一名用户的通知
  }

主动加入呼叫或切换设备

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

• 没有加入呼叫的用户希望加入呼叫。
  • 对于呼叫外用户加入成功的场景，该用户的状态将流转为 accepted，此时呼叫中的所有用户收到 callUserStateChanged 的通知回调
• 多端登录用户使用设备 A 发起或接受邀请后，希望让其他设备成为新的主设备。
  • 对于切换设备的场景，呼叫内其他用户无感知。

示例代码

// 主动加入呼叫或切换设备

ZIMCallJoinConfig *callJoinConfig = [[ZIMCallJoinConfig alloc] init];
callJoinConfig.extendedData = @"extendedData";
[[ZIM getInstance] callJoin:@"callID" config:callJoinConfig callback:^(NSString * _Nonnull callID, ZIMCallJoinSentInfo * _Nonnull info, ZIMError * _Nonnull errorInfo) {
    if(errorInfo.code == ZIMErrorCodeSuccess){

    }else{
        // 根据官网错误码表处理错误
    }
}];

退出呼叫

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

示例代码

• 退出呼叫

  // 退出呼叫
  ZIMCallQuitConfig *config = [[ZIMCallQuitConfig alloc] init];
  
  [[ZIM getInstance] callQuit:self.callID config:config callback:^(NSString * _Nonnull callID, ZIMCallQuitSentInfo * _Nonnull info, ZIMError * _Nonnull errorInfo) {
      if(errorInfo.code == ZIMErrorCodeSuccess){
          // 退出成功后的业务逻辑
      }else{
          // 根据官网错误码表处理错误
      }
  }];

• 呼叫成员收到有用户退出呼叫的通知

  -(void)zim:(ZIM *)zim callUserStateChanged:(ZIMCallUserStateChangeInfo *)info callID:(nonnull NSString *)callID{
      // 退出用户本人和状态为 “Inviting”、“Accepted“和“Received”的其他用户可以在此处收到有用户退出呼叫的通知
  }

结束呼叫

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

示例代码

• 结束呼叫

  // 结束呼叫
  ZIMCallEndConfig *config = [[ZIMCallEndConfig alloc] init];
  
  [[ZIM getInstance] callEnd:self.callID config:config callback:^(NSString * _Nonnull callID, ZIMCallEndedSentInfo * _Nonnull info, ZIMError * _Nonnull errorInfo) {
      if(errorInfo.code == ZIMErrorCodeSuccess){
          // 结束成功后的业务逻辑
      }else{
          // 根据官网错误码表处理错误
      }
  }];

• 呼叫成员收到呼叫结束的通知

  - (void)zim:(ZIM *)zim callInvitationEnded:(ZIMCallInvitationEndedInfo *)info callID:(NSString *)callID{
      // 所有用户状态为 “Inviting”、“Accepted“ 和 “Received” 的用户会收到呼叫结束的通知
  }

更多功能

检测邀请是否送达

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

ZIMCallInviteConfig *inviteConfig = [[ZIMCallInviteConfig alloc] init];
//开启暂未送达检测
inviteConfig.enableNotReceivedCheck = YES;

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

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

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

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

查询呼叫邀请列表

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

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

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