1V1 呼叫邀请场景

  • iOS

更新时间

场景介绍

一对一呼叫中,主叫希望找到指定用户并发起通话;被叫需要先看到来电,再决定接听或拒绝。双方尚未进入同一个音视频频道时,先由 RTM 传递邀请信令,再由 RTC 建立音视频连接。

一次完整的呼叫按以下顺序执行:

  1. 双方登录 RTM,安装呼叫邀请模块,等待或发起呼叫。
  2. 主叫向指定用户发送邀请,被叫展示来电。
  3. 被叫接听,主叫确认;各端确认邀请已接受后,开始连接 RTC。
  4. RTC 媒体建立后,界面进入通话状态。
  5. 用户静音、恢复或挂断;结束后释放媒体资源,下一次呼叫创建新邀请。

被叫拒绝、主叫在等待期间取消,都是正常业务分支,双方不进入 RTC。无人应答、网络异常或媒体未建立时,则按相应截止时间结束等待并提示原因。

Web Demo 使用双页面演示语音通话,邀请设计也可用于视频呼叫。页面上的“呼叫 ID”是用户的 RTM 用户 ID;每次邀请另有唯一的 callId,用于关联本次信令与媒体。

能力负责不负责
RTM呼叫、接听、拒绝、取消等点对点信令,消息发布结果和本端连接状态音视频传输、媒体通话状态
RTC加入频道、音视频传输、感知目标用户加入与离开呼叫邀请信令
表格内容超出当前宽度,可横向滚动查看更多列。

接入分层

呼叫功能由三层组成。Demo 中的呼叫邀请模块目前为 Web 版本,在 Objective-C 上,你需要参照它的信令协议和状态设计实现中间一层(关键代码见 3. 实现指南),再完成 App 层的工作:

层是什么负责
RTM SDK声网提供的实时消息 SDK点对点消息投递与送达结果、对方是否在线、本端连接状态与自动重连
呼叫邀请模块(invitation/)基于 RTM 点对点消息实现的呼叫逻辑。Demo 提供 Web 版本,Objective-C 上参照其协议实现定义呼叫信令协议,维护两端的呼叫状态,处理各阶段超时与邀请重试,记录失败原因
App你的业务代码安装与销毁模块、按状态渲染界面、按失败原因提示用户、接通后加入 RTC、媒体等待截止、占线策略
表格内容超出当前宽度,可横向滚动查看更多列。

呼叫邀请模块不是 RTM SDK 的接口,而是一份 Web 参考实现。在 Objective-C 上,需要参照其信令协议和状态设计自行实现。

术语

术语含义
主叫 / 被叫发起呼叫的一方 / 接收呼叫的一方,即 Caller / Callee
邀请一次呼叫在 RTM 侧的过程,从发起到出现结果为止。每次呼叫有唯一的 callId
接听消息(accepted)被叫点击接听后发给主叫的消息
确认消息(ACK)主叫收到接听消息后回给被叫的消息,被叫据此确认接通
终态邀请的最终结果:已接受、已拒绝、已取消或失败。进入终态后状态不再变化
表格内容超出当前宽度,可横向滚动查看更多列。

核心规则

  1. 将呼叫邀请模块安装在 App 已登录的唯一 RTM client 上。登出前先销毁模块,重新登录后重新安装。
  2. App 自己的点对点消息监听必须忽略 CALL_KIT_ 系列 customType。
  3. 以模块的状态驱动界面。
  4. 接受即邀请结束,之后只看 RTC。加入频道时设置媒体等待截止;挂断只离开 RTC 频道。
  5. 按失败原因提示用户。不在 App 层叠加自动重试。

1. 为什么 1V1 呼叫需要 RTM

呼叫发生在音视频通道建立之前,RTC 无法承担这一阶段的工作:

  • 发起呼叫时,被叫还不在任何 RTC 频道中,无法通过 RTC 通知对方"有来电";
  • 振铃、接听、拒绝、取消、无人应答都是业务动作,RTC 没有对应接口;
  • 主叫需要区分"对方不在线""网络异常""对方没应答"并给出不同提示,RTC 无法提供这些信息;
  • 两端需要先确认"这次呼叫已被接受",再各自加入频道,否则会出现一方已入会、另一方仍在振铃的情况。

因此呼叫需要一条独立于音视频的实时信令通道。如果用 WebSocket 或业务服务端转发自建这条通道,需要同时解决长连接维持与断线重连、按用户路由点对点消息、判断对方是否在线、确认消息是否送达,以及海量连接下的容量与可用性保障。RTM 直接提供这些能力:

RTM 提供的能力在呼叫中的效果
USER 点对点消息呼叫、接听、拒绝、取消、确认五种信令都通过它在两个用户之间直接传递
点对点消息发送成功即表示对方已收到主叫无需等待额外回执,就能确认邀请已送达对方设备(RECEIVED_BY_CALLEE)
发送错误码 -11033(对方不在线)主叫能明确提示"对方不在线"(PEER_OFFLINE)
linkState 连接状态发送失败时判断是本端网络问题(LOCAL_NETWORK_ERROR)还是对方问题
长连接与自动重连网络短暂波动时连接自动恢复
表格内容超出当前宽度,可横向滚动查看更多列。

2. 设计原则

本节内容与平台无关。

2.1 复用 App 已登录的 RTM client

呼叫邀请模块安装在 App 已有的 RTM client 上,不创建新 client,也不负责登录和登出:

  • 传给模块的 userId 必须与 RTM 登录时使用的 UID 一致;
  • 在 login() 成功后安装模块;
  • 登出前先销毁模块,重新登录后重新安装。模块的 dispose() 会解绑模块自身的事件监听,因此销毁后需要创建新的模块实例,才能继续接收来电。

2.2 隔离邀请信令与 App 自有消息

邀请信令使用 USER Channel 点对点发送,并通过以下 customType 标识:

customType方向含义
CALL_KIT_INVITE主叫 → 被叫发起呼叫
CALL_KIT_ACCEPT(type: "accepted")被叫 → 主叫被叫接听
CALL_KIT_ACCEPT(type: "ack")主叫 → 被叫主叫确认
CALL_KIT_REFUSE被叫 → 主叫被叫拒绝
CALL_KIT_CANCEL主叫 → 被叫主叫取消
表格内容超出当前宽度,可横向滚动查看更多列。

SDK 会把收到的每条消息同时分发给模块和 App 自己注册的 message 监听。模块只处理上述 customType,App 的监听则需要主动跳过它们(代码见 3.3 接收与分发信令)。App 自己的点对点业务消息请使用独立的 customType。

每条邀请信令都可以携带 extra 字段,即 App 自定义字符串,模块原样透传。

2.3 以状态驱动界面

模块在两端各维护一份邀请状态,并在状态变化时回调。App 只需把状态映射到界面:

端状态界面可用操作
主叫SENT_TO_CALLEE正在呼叫…取消
主叫RECEIVED_BY_CALLEE正在呼叫…取消
主叫ACCEPTED_BY_CALLEE接通中,开始加入 RTC挂断
主叫REFUSED_BY_CALLEE / CANCELED / FAILURE显示结果后关闭呼叫界面(见 2.6 按失败原因提示用户)—
被叫INVITATION_RECEIVED来电界面接听、拒绝
被叫ACCEPT_SENT_TO_CALLER接通中—
被叫ACCEPTED开始加入 RTC挂断
被叫REFUSED / CANCELED_BY_CALLER / FAILURE显示结果后关闭来电界面(见 2.6 按失败原因提示用户)—
表格内容超出当前宽度,可横向滚动查看更多列。

RECEIVED_BY_CALLEE 表示邀请已送达对方设备,不代表对方已看到来电,因此界面仍显示"正在呼叫"。点击拒绝或取消后,界面立即显示结果,无需等待对方收到。

完整的状态定义与流转见 附录:邀请状态与流转。

2.4 接受即邀请结束,通话交给 RTC

主叫进入 ACCEPTED_BY_CALLEE、被叫进入 ACCEPTED 后,邀请就结束了。之后的通话完全由 RTC 负责:两端各自加入同一个 RTC 频道;挂断只需离开 RTC 频道,对方感知到你离开后结束通话,不需要发送 RTM 消息。

接受不等于接通。以下两种情况都会出现"一方在等待、另一方不会进来":

场景主叫被叫结果
被叫网络差,没收到确认消息已接受,已加入 RTC等待确认超时,邀请失败,不加入 RTC双方无法通话
被叫收到确认,但加入 RTC 失败已接受,已加入 RTC已接受,RTC 加入失败双方无法通话
表格内容超出当前宽度,可横向滚动查看更多列。

因此 App 必须设置媒体等待截止:开始建立 RTC 时计时,未在截止时间内建立媒体就结束本次通话并提示用户。Demo 默认使用 15 秒(代码见 3.6 接通后进入 RTC 与挂断)。

2.5 超时与重试:用默认值,按需调整

模块为邀请的每个等待阶段都设置了截止时间,并会在 INVITE 发送失败时自动重试。以下默认值即 Demo 的建议配置:

配置项默认值含义
sendTimeoutMs30000主叫发送邀请的总时长上限,包含重试
maxRetries2邀请发送失败后的重试次数(首次 + 2 次重试,共 3 次)
retryIntervalMs2000两次重试之间的间隔
callerInvitationExpireMs30000邀请送达后,主叫等待对方接听或拒绝的时长
calleeInvitationExpireMs30000被叫从收到来电到完成接通(含等待确认消息)的时长
表格内容超出当前宽度,可横向滚动查看更多列。

主叫和被叫各自计时,起点不同,因此两端不保证同时到期。

2.6 按失败原因提示用户

邀请结束时,回调中的 state 表示结果,失败时 reason 表示原因。建议按下表给出提示。

主叫

结果reason建议处理
REFUSED_BY_CALLEE—对方已拒绝
CANCELED—已取消
FAILUREPEER_OFFLINE对方不在线
FAILURELOCAL_NETWORK_ERROR / PUBLISH_TIMEOUT / PUBLISH_FAILED / SEND_TIMEOUT网络异常,可提供"重新呼叫"
FAILUREPEER_NO_RESPONSE对方无应答,可提供"再次呼叫"
FAILURESTOPPED无需提示
表格内容超出当前宽度,可横向滚动查看更多列。

被叫

结果reason建议处理
CANCELED_BY_CALLER—对方已取消,可记为未接来电
FAILUREINVITATION_EXPIRE来电超时,可记为未接来电
FAILUREACCEPT_ACK_TIMEOUT接通失败
FAILURELOCAL_NETWORK_ERROR网络异常
FAILURESTOPPED无需提示
表格内容超出当前宽度,可横向滚动查看更多列。

排查问题时,回调中的 trigger(触发条件)、sdkError(SDK 原始错误)和 linkStateAtFailure(失败时的网络状态)可以帮助定位原因。

2.7 多来电与占线

模块允许同时存在多个来电,每个来电独立计时、独立处理,不会自动拒绝其他来电。占线策略由 App 决定。

Demo 同一时间只保留一路通话。通话中收到新来电时,来电继续计时,用户可以拒绝;通话结束后,仍在有效期内的来电可以接听。

3. 实现指南

基础接入见 实现收发消息,凭证准备见 部署 Token 服务器 和 客户端鉴权。

以下代码基于 RTM Objective-C SDK 2.x 和 RTC iOS SDK 4.x,接口名和参数以实际接入的 SDK 版本为准。

Demo 中的呼叫邀请模块目前只有 Web 版本。本节展示如何用 Objective-C SDK 按同一套信令协议实现模块的关键环节:信令收发、超时与重试、失败原因判断和接通后的 RTC 处理。完整的状态定义与流转以附录为准。

RTM 回调默认在主线程触发(AgoraRtmClientConfig.callbackQueue 为 nil 时),示例中的状态读写和计时器都在主线程执行。主叫和被叫的邀请使用同一个 CallInvitation 类,用 isCaller 区分角色;状态名与附录一致。

3.1 信令定义与发送

每条信令都使用 USER Channel 点对点发送,customType 标识信令类型,消息体为 JSON 文本 { callId, extra, type? },其中 type 只用于 CALL_KIT_ACCEPT:

Objective-C
static NSString * const kCallKitInvite = @"CALL_KIT_INVITE";
static NSString * const kCallKitAccept = @"CALL_KIT_ACCEPT"; // type: "accepted" 或 "ack"
static NSString * const kCallKitRefuse = @"CALL_KIT_REFUSE";
static NSString * const kCallKitCancel = @"CALL_KIT_CANCEL";

static NSSet<NSString *> *CallKitTypes(void) {
    return [NSSet setWithObjects:kCallKitInvite, kCallKitAccept, kCallKitRefuse, kCallKitCancel, nil];
}

// USER 消息发送成功即表示对方已收到
- (void)sendSignalTo:(NSString *)peerUid
          customType:(NSString *)customType
              callId:(NSString *)callId
               extra:(NSString *)extra
                type:(nullable NSString *)type
          completion:(nullable void (^)(AgoraRtmErrorInfo *_Nullable error))completion {
    NSMutableDictionary *body = [@{ @"callId": callId, @"extra": extra ?: @"" } mutableCopy];
    if (type) body[@"type"] = type;
    NSData *data = [NSJSONSerialization dataWithJSONObject:body options:0 error:nil];
    NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

    AgoraRtmPublishOptions *options = [[AgoraRtmPublishOptions alloc] init];
    options.channelType = AgoraRtmChannelTypeUser;
    options.customType = customType;
    [self.rtm publish:peerUid message:text option:options
           completion:^(AgoraRtmCommonResponse *response, AgoraRtmErrorInfo *errorInfo) {
        if (completion) completion(errorInfo);
    }];
}

主叫发起呼叫时生成 callId:16 字节随机数转成 32 位大写十六进制字符串。

Objective-C
static NSString *NewCallId(void) {
    uint8_t bytes[16];
    (void)SecRandomCopyBytes(kSecRandomDefault, sizeof(bytes), bytes);
    NSMutableString *callId = [NSMutableString stringWithCapacity:32];
    for (int i = 0; i < 16; i++) [callId appendFormat:@"%02X", bytes[i]];
    return callId;
}

3.2 安装与配置

超时与重试参数使用 2.5 超时与重试:用默认值,按需调整 中的默认值,可按业务调整(单位为秒):

Objective-C
@interface InvitationOptions : NSObject
@property (nonatomic, assign) NSTimeInterval sendTimeout;            // 默认 30,INVITE 发送总截止,包含重试
@property (nonatomic, assign) NSInteger maxRetries;                  // 默认 2,发送失败后的重试次数
@property (nonatomic, assign) NSTimeInterval retryInterval;          // 默认 2,重试间隔
@property (nonatomic, assign) NSTimeInterval callerInvitationExpire; // 默认 30,主叫等待接听或拒绝
@property (nonatomic, assign) NSTimeInterval calleeInvitationExpire; // 默认 30,被叫处理来电与等待确认
@end

@implementation InvitationOptions
- (instancetype)init {
    self = [super init];
    if (self) {
        _sendTimeout = 30;
        _maxRetries = 2;
        _retryInterval = 2;
        _callerInvitationExpire = 30;
        _calleeInvitationExpire = 30;
    }
    return self;
}
@end

在 RTM 登录成功后安装模块:向已登录的 client 添加模块自己的监听,并记录连接状态,用于判断失败原因。安装时由 App 会话传入当前 MESSAGE 服务的连接状态;新加的监听不会重放登录期间已发出的 CONNECTED 事件。后续只处理 MESSAGE 服务事件,忽略 Stream Channel 的连接通知。登出前先销毁模块:移除监听,并将未结束的邀请置为 FAILURE(STOPPED)。

Objective-C
- (void)installWithMessageLinkConnected:(BOOL)messageLinkConnected {
    self.linkConnected = messageLinkConnected; // App 会话持有的 MESSAGE 服务连接状态
    [self.rtm addDelegate:self];
}

- (void)dispose {
    [self.rtm removeDelegate:self];
    for (CallInvitation *inv in self.invitations.allValues) [self fail:inv reason:CallReasonStopped];
}

- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveLinkStateEvent:(AgoraRtmLinkStateEvent *)event {
    if (event.serviceType != AgoraRtmServiceTypeMessage) return;
    self.linkConnected = (event.currentState == AgoraRtmLinkStateConnected);
    if (event.currentState == AgoraRtmLinkStateFailed) {
        // 连接彻底失败:未结束的邀请全部失败
        for (CallInvitation *inv in self.invitations.allValues) [self fail:inv reason:CallReasonLocalNetworkError];
    }
    // 暂时断连不重置截止,也不立即结束邀请
}

每个阶段使用基于本地单调时钟的截止值 endTs,不与系统日期时间或其他设备的时钟比较。计时器只负责到点唤醒检查;收到消息、用户操作或发送结果时,也先检查截止。App 回到前台时,对所有未结束的邀请执行一次 onDeadline: 检查。下面的静态时钟辅助函数放在文件作用域,实例方法放在邀请模块的 @implementation 中。

Objective-C
#import <mach/mach_time.h>

// 秒;单调时钟,包含设备休眠时间(iOS 10+)
static NSTimeInterval MonotonicNow(void) {
    static mach_timebase_info_data_t info;
    static dispatch_once_t onceToken;
    dispatch_once(&onceToken, ^{ mach_timebase_info(&info); });
    return (NSTimeInterval)mach_continuous_time() * info.numer / info.denom / NSEC_PER_SEC;
}

// CallInvitation.endTs 改为 NSTimeInterval,保存单调时钟的秒值
- (BOOL)isExpired:(CallInvitation *)inv {
    return MonotonicNow() >= inv.endTs;
}

- (void)enterStage:(CallInvitation *)inv state:(CallState)state endTs:(NSTimeInterval)endTs {
    inv.state = state;
    inv.endTs = endTs;
    inv.stageToken += 1; // 使上一阶段的计时器失效
    NSUInteger token = inv.stageToken;
    NSTimeInterval delay = MAX(0, endTs - MonotonicNow());
    __weak typeof(self) weakSelf = self;
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(delay * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        if (inv.stageToken == token) [weakSelf onDeadline:inv];
    });
    [self notifyStateChanged:inv];
}

- (void)onDeadline:(CallInvitation *)inv {
    if (inv.ended || ![self isExpired:inv]) return;
    switch (inv.state) {
        case CallStateSentToCallee:       [self fail:inv reason:CallReasonSendTimeout]; break;
        case CallStateReceivedByCallee:   [self fail:inv reason:(self.linkConnected ? CallReasonPeerNoResponse : CallReasonLocalNetworkError)]; break;
        case CallStateInvitationReceived: [self fail:inv reason:CallReasonInvitationExpire]; break;
        case CallStateAcceptSentToCaller: [self fail:inv reason:CallReasonAcceptAckTimeout]; break;
        default: break;
    }
}

// 进入终态后不再变化,迟到的消息和发送结果都不能改变它
- (void)end:(CallInvitation *)inv state:(CallState)terminal reason:(CallReason)reason {
    if (inv.ended) return;
    inv.ended = YES;
    inv.state = terminal;
    inv.reason = reason;
    inv.stageToken += 1;
    [self notifyStateChanged:inv];
}

- (void)fail:(CallInvitation *)inv reason:(CallReason)reason {
    // 主叫为 FAILURE(6),被叫为 FAILURE(16)
    [self end:inv state:(inv.isCaller ? CallStateCallerFailure : CallStateCalleeFailure) reason:reason];
}

3.3 接收与分发信令

模块的监听只处理 USER Channel 中 CALL_KIT_ 系列 customType 的消息,按信令类型分发。格式不合法、callId 不存在或发送者不是该邀请的对方时,直接忽略:

Objective-C
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
    if (event.channelType != AgoraRtmChannelTypeUser || ![CallKitTypes() containsObject:event.customType]) return;

    NSDictionary *signal = ParseSignal(event.message.stringData); // 格式不合法时返回 nil
    if (signal == nil) return;
    NSString *from = event.publisher;
    NSString *type = signal[@"type"];

    if ([event.customType isEqualToString:kCallKitInvite]) {
        [self onInviteFrom:from signal:signal];
    } else if ([event.customType isEqualToString:kCallKitAccept]) {
        if ([type isEqualToString:@"accepted"]) [self onAcceptedFrom:from signal:signal];
        else if ([type isEqualToString:@"ack"]) [self onAckFrom:from signal:signal];
    } else if ([event.customType isEqualToString:kCallKitRefuse]) {
        [self onRefuseFrom:from signal:signal];
    } else if ([event.customType isEqualToString:kCallKitCancel]) {
        [self onCancelFrom:from signal:signal];
    }
}

- (nullable CallInvitation *)find:(NSString *)callId from:(NSString *)from isCaller:(BOOL)isCaller {
    CallInvitation *inv = self.invitations[callId];
    if (inv == nil || inv.isCaller != isCaller || ![inv.remoteUid isEqualToString:from]) return nil;
    return inv;
}

如果 App 还会收发其他点对点消息,在 App 自己的监听中跳过邀请信令:

Objective-C
// App 自己的监听中
- (void)rtmKit:(AgoraRtmClientKit *)rtmKit didReceiveMessageEvent:(AgoraRtmMessageEvent *)event {
    if (event.channelType == AgoraRtmChannelTypeUser && [CallKitTypes() containsObject:event.customType]) {
        return; // 交给呼叫邀请模块处理
    }
    [self handleAppMessage:event];
}

3.4 主叫:发起与取消

发起呼叫时进入 SENT_TO_CALLEE,并设置发送总截止。发送失败时在截止前按间隔重试,次数耗尽后按 2.6 按失败原因提示用户 判断失败原因。发送成功即进入 RECEIVED_BY_CALLEE,开始等待对方响应:

Objective-C
- (CallInvitation *)callUser:(NSString *)calleeUid extra:(NSString *)extra {
    CallInvitation *inv = [CallInvitation outgoingWithCallId:NewCallId() remoteUid:calleeUid extra:extra];
    self.invitations[inv.callId] = inv;
    [self enterStage:inv state:CallStateSentToCallee
               endTs:(MonotonicNow() + self.options.sendTimeout)];
    [self sendInvite:inv];
    return inv;
}

- (void)sendInvite:(CallInvitation *)inv {
    inv.publishing = YES;
    __weak typeof(self) weakSelf = self;
    [self sendSignalTo:inv.remoteUid customType:kCallKitInvite callId:inv.callId extra:inv.extra type:nil
            completion:^(AgoraRtmErrorInfo *error) {
        __strong typeof(weakSelf) self = weakSelf;
        if (self == nil || inv.ended || [self isExpired:inv]) return;
        inv.publishing = NO;
        if (error == nil) {
            if (inv.state != CallStateSentToCallee) return;
            [self enterStage:inv state:CallStateReceivedByCallee
                       endTs:(MonotonicNow() + self.options.callerInvitationExpire)];
        } else if (inv.retries < self.options.maxRetries) {
            inv.retries += 1;
            dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(self.options.retryInterval * NSEC_PER_SEC)),
                           dispatch_get_main_queue(), ^{
                if (!inv.ended && ![self isExpired:inv]) [self sendInvite:inv];
            });
        } else {
            [self fail:inv reason:[self classify:error]];
        }
    }];
}

- (CallReason)classify:(AgoraRtmErrorInfo *)error {
    if (error.errorCode == AgoraRtmErrorChannelReceiverOffline) return CallReasonPeerOffline;          // -11033
    if (!self.linkConnected) return CallReasonLocalNetworkError;
    if (error.errorCode == AgoraRtmErrorChannelPublishMessageTimeout) return CallReasonPublishTimeout; // -11026
    return CallReasonPublishFailed;
}

收到接听消息后立即进入接受终态并回复确认消息,不等待确认消息的发送结果。收到拒绝消息则进入拒绝终态:

Objective-C
- (void)onAcceptedFrom:(NSString *)from signal:(NSDictionary *)signal {
    CallInvitation *inv = [self find:signal[@"callId"] from:from isCaller:YES];
    if (inv == nil || inv.ended || inv.state != CallStateReceivedByCallee || [self isExpired:inv]) return;
    [self end:inv state:CallStateAcceptedByCallee reason:CallReasonNone];
    [self sendSignalTo:from customType:kCallKitAccept callId:inv.callId extra:inv.extra type:@"ack" completion:nil];
}

- (void)onRefuseFrom:(NSString *)from signal:(NSDictionary *)signal {
    CallInvitation *inv = [self find:signal[@"callId"] from:from isCaller:YES];
    if (inv == nil || inv.ended || inv.state != CallStateReceivedByCallee || [self isExpired:inv]) return;
    inv.remoteExtra = signal[@"extra"];
    [self end:inv state:CallStateRefusedByCallee reason:CallReasonNone];
}

等待期间用户点击取消时,先提交取消终态,再通知对方:

Objective-C
- (void)cancel:(CallInvitation *)inv {
    if (inv.ended) return;
    [self end:inv state:CallStateCanceled reason:CallReasonNone];
    [self sendSignalTo:inv.remoteUid customType:kCallKitCancel callId:inv.callId extra:inv.extra type:nil completion:nil];
}

在 extra 中放入 RTC 频道名等通话所需信息。

3.5 被叫:接听与拒绝

首次收到合法的邀请时创建来电并开始计时;重复的邀请复用已有来电,不刷新截止。已结束的邀请在去重窗口内保留,避免重复邀请再次触发来电:

Objective-C
- (void)onInviteFrom:(NSString *)from signal:(NSDictionary *)signal {
    if (self.invitations[signal[@"callId"]] != nil) return;
    CallInvitation *inv = [CallInvitation incomingWithCallId:signal[@"callId"] remoteUid:from remoteExtra:signal[@"extra"]];
    self.invitations[inv.callId] = inv;
    [self enterStage:inv state:CallStateInvitationReceived
               endTs:(MonotonicNow() + self.options.calleeInvitationExpire)];
}

清理建议

终态后释放不再需要的回调、计时任务和大体积 extra;仅保留对方 UID、callId、终态及过期时间等最小去重记录。去重缓存应同时设置 TTL 和容量上限,TTL 覆盖本业务允许的发送重试及迟到消息窗口;活动邀请不能因缓存淘汰被删除。定期清理过期记录,账号退出时清空。若要在去重记录淘汰后仍拒绝过期邀请,业务协议还应增加可校验的消息有效期,不能只依赖接收端从“首次收到”开始计时。

用户点击接听时发送接听消息。发送期间 publishing 为 YES,界面禁用接听和拒绝按钮;发送成功后进入 ACCEPT_SENT_TO_CALLER,沿用原截止时间等待确认消息;发送失败时来电保持,用户可以再次操作:

Objective-C
- (void)accept:(CallInvitation *)inv {
    if (inv.ended || inv.state != CallStateInvitationReceived || inv.publishing || [self isExpired:inv]) return;
    inv.publishing = YES;

    [self notifyStateChanged:inv];
    __weak typeof(self) weakSelf = self;
    [self sendSignalTo:inv.remoteUid customType:kCallKitAccept callId:inv.callId extra:@"" type:@"accepted"
            completion:^(AgoraRtmErrorInfo *error) {
        __strong typeof(weakSelf) self = weakSelf;
        if (self == nil || inv.ended) return;
        inv.publishing = NO;
        if (error == nil && ![self isExpired:inv]) {
            [self enterStage:inv state:CallStateAcceptSentToCaller endTs:inv.endTs];
        } else {
            [self notifyStateChanged:inv];
        }
    }];
}

- (void)onAckFrom:(NSString *)from signal:(NSDictionary *)signal {
    CallInvitation *inv = [self find:signal[@"callId"] from:from isCaller:NO];
    if (inv == nil || inv.ended || inv.state != CallStateAcceptSentToCaller || [self isExpired:inv]) return;
    [self end:inv state:CallStateAccepted reason:CallReasonNone];
}

用户点击拒绝时,先提交拒绝终态,再通知对方。收到取消消息时,进入取消终态:

Objective-C
- (void)refuse:(CallInvitation *)inv {
    if (inv.ended || inv.state != CallStateInvitationReceived || inv.publishing) return;
    [self end:inv state:CallStateRefused reason:CallReasonNone];
    [self sendSignalTo:inv.remoteUid customType:kCallKitRefuse callId:inv.callId extra:@"" type:nil completion:nil];
}

- (void)onCancelFrom:(NSString *)from signal:(NSDictionary *)signal {
    CallInvitation *inv = [self find:signal[@"callId"] from:from isCaller:NO];
    if (inv == nil || inv.ended || [self isExpired:inv]) return;
    if (inv.state == CallStateInvitationReceived || inv.state == CallStateAcceptSentToCaller) {
        [self end:inv state:CallStateCanceledByCaller reason:CallReasonNone];
    }
}

可用 endTs 显示剩余振铃时间:MAX(0, inv.endTs - MonotonicNow())。

3.6 接通后进入 RTC 与挂断

进入接受状态后,由 App 加入 RTC,并设置媒体建立的绝对截止时间(Demo 默认 15 秒)。本地加入成功且确认目标用户的音频已开始播放(remoteAudioStateChangedOfUid 报告 AgoraAudioRemoteStateDecoding)后,取消媒体等待截止。超时、建立失败或用户挂断时,幂等清理本次媒体会话;邀请保持原有接受终态。

Objective-C
static const NSTimeInterval kMediaTimeout = 15; // App 层配置,Demo 默认 15 秒

// AgoraRtcEngineDelegate
- (void)rtcEngine:(AgoraRtcEngineKit *)engine remoteAudioStateChangedOfUid:(NSUInteger)uid
            state:(AgoraAudioRemoteState)state reason:(AgoraAudioRemoteReason)reason elapsed:(NSInteger)elapsed {
    if (!self.callActive || uid != self.remoteRtcUid) return; // remoteRtcUid:目标用户的 RTC uid
    if (state == AgoraAudioRemoteStateDecoding) self.mediaToken += 1; // 取消媒体等待截止
}

- (void)rtcEngine:(AgoraRtcEngineKit *)engine didOfflineOfUid:(NSUInteger)uid reason:(AgoraUserOfflineReason)reason {
    if (self.callActive && uid == self.remoteRtcUid) [self endCall:@"通话已结束"];
}

- (void)startCallWithChannel:(NSString *)rtcChannel token:(NSString *)rtcToken {
    self.callActive = YES;
    NSUInteger token = ++self.mediaToken;
    __weak typeof(self) weakSelf = self;
    dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(kMediaTimeout * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
        if (weakSelf.mediaToken == token) [weakSelf endCall:@"对方未接通"];
    });

    AgoraRtcChannelMediaOptions *options = [[AgoraRtcChannelMediaOptions alloc] init];
    options.publishMicrophoneTrack = YES;
    options.autoSubscribeAudio = YES;
    int ret = [self.rtcEngine joinChannelByToken:rtcToken channelId:rtcChannel uid:self.localRtcUid
                                    mediaOptions:options joinSuccess:nil];
    if (ret != 0) [self endCall:@"通话建立失败"];
}

- (void)endCall:(NSString *)message {
    if (!self.callActive) return; // 超时、对方离开、用户挂断可能先后触发
    self.callActive = NO;
    self.mediaToken += 1;
    [self.rtcEngine leaveChannel:nil];
    [self showToast:message];
    [self backToIdle];
}

挂断时调用 [self endCall:@"通话已结束"] 即可。

4. 常见错误

App 的点对点消息监听没有过滤邀请信令

邀请信令会同时到达 App 自己的监听,被当作普通消息解析或展示。在 App 监听中忽略 CALL_KIT_ 系列 customType。

为呼叫邀请单独创建或登录一个 RTM client

同一用户维护多条连接,状态难以一致。模块应安装在 App 已登录的唯一 client 上。

销毁模块后没有重新安装

App 调用 dispose() 后,模块已解绑自身的事件监听。重新登录后需要创建新的模块实例,才能继续接收来电。

用 RTM 消息通知挂断

接受即邀请结束,挂断只需离开 RTC 频道。

把"已接受"当作"已接通"

确认消息可能丢失,RTC 可能加入失败。进入 RTC 时必须设置媒体等待截止。

对所有失败自动重拨,或在 App 层叠加重试

对方不在线时重拨仍会失败,无应答时重拨会打扰对方;模块已自动重试,叠加只会延长等待。

5. 上线检查清单

  • 呼叫邀请模块安装在已登录的唯一 RTM client 上,userId 与登录 UID 一致
  • 登出前销毁模块,重新登录后重新安装
  • App 自有的点对点消息监听忽略 CALL_KIT_ 系列 customType
  • 界面按 2.3 以状态驱动界面 渲染,publishing 时禁用操作按钮
  • 超时与重试配置已按业务确认,App 层未叠加重试
  • 主叫和被叫都按 2.6 按失败原因提示用户 给出提示
  • 进入 RTC 时设置媒体等待截止,目标用户的媒体就绪后取消
  • 挂断只离开 RTC 频道,不发 RTM 消息
  • 已定义占线策略

附录:邀请状态与流转

本附录供需要深入了解模块行为或自行实现邀请逻辑的开发者参考。

主叫状态

状态含义
IDLE(0)已创建,尚未开始
SENT_TO_CALLEE(1)正在发送邀请,包括失败后的重试
RECEIVED_BY_CALLEE(2)邀请已送达被叫,等待接听或拒绝
ACCEPTED_BY_CALLEE(3)被叫已接听(终态)
REFUSED_BY_CALLEE(4)被叫已拒绝(终态)
CANCELED(5)主叫已取消(终态)
FAILURE(6)发送失败、等待超时、网络断开或模块销毁(终态)
表格内容超出当前宽度,可横向滚动查看更多列。

被叫状态

状态含义
IDLE(10)已创建,尚未处理邀请
INVITATION_RECEIVED(11)来电中,等待用户操作;接听消息发送中也保持此状态
ACCEPT_SENT_TO_CALLER(12)接听消息已送达主叫,等待确认
ACCEPTED(13)已收到确认(终态)
REFUSED(14)被叫已拒绝(终态)
CANCELED_BY_CALLER(15)主叫已取消(终态)
FAILURE(16)来电超时、确认超时、网络断开或模块销毁(终态)
表格内容超出当前宽度,可横向滚动查看更多列。

模块的消息校验规则

模块收到邀请信令后,以下任一条件不满足即忽略该消息,不影响其他邀请:

  1. 消息格式合法,字段完整;
  2. callId 对应已有的邀请(首次收到的合法邀请会新建被叫邀请);
  3. 消息发送者与该邀请的对方 UID 一致;
  4. 当前状态允许处理该消息,且未过截止时间。