微信小程序如何实现呼叫邀请功能

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

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

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

下面以小程序实现呼叫邀请功能普通模式为例进行讲解。

小程序实现呼叫邀请功能前提条件

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

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台自助开通 ZIM 服务（详情请参考 项目管理 – 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。
• 已集成 ZIM SDK，详情请参考 快速开始 – 实现基本收发消息 的 “3 集成 SDK”。

普通模式

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

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

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

// 监听呼叫邀请相关用户的状态变化
zim.on('callUserStateChanged', (zim, info) => {
    // 相关的 callID
    const changeCallID = info.callID;
    info.callUserList.forEach(userInfo => {
        // 状态变化用户的 userID、最新用户状态、透传字段（与用户该调用接受、拒绝、退出呼叫时携带的 extended data 一致）
        const { userID, state, extendedData } = userInfo;
        // 您的业务逻辑
    });
})

2 发起呼叫邀请

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

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

• 客户端 B 通过注册 callInvitationReceived 回调接口，接收客户端 A 的邀请通知。

callInvite 说明

callInvite(invitees: string[], config: ZIMCallInviteConfig): Promise<ZIMCallInvitationSentResult>;

示例代码

向在线用户发送呼叫邀请，示例代码如下所示：

/** 向在线用户发送呼叫邀请 */
var invitees = ['xxxx'];  // 被邀请人ID列表
var config = { timeout: 200 }; //邀请超时时间，单位为秒，范围1-600   
zim.callInvite(invitees, config)
    .then(({ callID, timeout, errorInvitees }) => {
        // 操作成功
        // 此处的 callID 是用户发起呼叫后，SDK 内部生成的 ID，用于唯一标识一次呼叫邀请；之后发起人取消呼叫、被邀请人接受/拒绝呼叫，都会使用此 callID
    })
    .catch(err => {
        // 操作失败
    })

向离线用户发送呼叫邀请，示例代码如下所示：

/** 向离线用户发送呼叫邀请 */
var invitees = ['xxxx'];  // 被邀请人 ID 列表
// 如需向离线用户推送呼叫邀请相关离线消息，需要配置 pushConfig，且已集成 ZPNs SDK
var pushConfig = {
    title: 'push title',
    content: 'push content',
    payload: 'push payload'
};

var config = { 
    timeout: 200, // 邀请超时时间，单位为秒，范围1-600
    extendedData: 'your call invite extendedData',
    pushConfig,
};
zim.callInvite(invitees, config)
    .then(({ callID, timeout, errorInvitees }) => {
        // 操作成功
        // 此处的 callID 是用户发起呼叫后，SDK 内部生成的 ID，用于唯一标识一次呼叫邀请；之后发起人取消呼叫、被邀请人接受/拒绝呼叫，都会使用此 callID
    })
    .catch(err => {
        // 操作失败
    })

被邀请者收到邀请后的回调通知，示例代码如下：

/** 被邀请者收到邀请后的回调通知 */
zim.on('callInvitationReceived', (zim, { callID, inviter, timeout, extendedData }) => {
    // console.log('callInvitationReceived', { callID, inviter, timeout, extendedData })
})

3 取消呼叫邀请

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

1. 客户端 A 发起呼叫邀请后，如果需要取消，可以调用 callCancel 接口，主动选择取消当前邀请。
2. 邀请取消后，客户端 B 会收到 callInvitationCancelled 回调接口的相关通知。

callCancel 说明

callCancel(invitees: string[], callID: string, config: ZIMCallCancelConfig): Promise<ZIMCallCancelSentResult>;

示例代码

// 取消呼叫邀请
var callID = 'xxxx';
var invitees = ['xxxx'];  // 被邀请人ID列表
var config = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then(res => {
         // 操作成功
    })
    .catch(err => {
        // 操作失败
    })

// 被邀请者收到取消邀请后的回调通知
zim.on('callInvitationCancelled',(zim, { callID, inviter, extendedData }) => {
    // console.log('callInvitationCancelled', { callID, inviter, extendedData })
})

4 接受呼叫邀请

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

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

callAccept 说明

callAccept(callID: string, config: ZIMCallAcceptConfig): Promise<ZIMCallAcceptanceSentResult>;

示例代码

// 接受呼叫邀请
var callID = 'xxxx';
var config = { extendedData: 'xxxx' }; 
zim.callAccept(callID, config)
    .then(res => {
        // 操作成功
    })
    .catch(err => {
        // 操作失败
    })

// 邀请者接受邀请后的回调通知
zim.on('callUserStateChanged', (zim, info) => {
    // 相关的 callID
    const changeCallID = info.callID;
    info.callUserList.forEach(userInfo => {
        // 状态变化用户的 userID、最新用户状态、透传字段（与用户该调用接受、拒绝、退出呼叫时携带的 extended data 一致）
        const { userID, state, extendedData } = userInfo;
        // state = 1 表示接受，具体可以参考枚举 ZIMCallUserState
        if (state == 1) {
            // 您的业务逻辑
        }

    });
})

5 拒绝呼叫邀请

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

1. 客户端 B 收到客户端 A 发来的呼叫邀请后，通过调用 callReject 接口，拒绝该邀请。
2. 客户端 B 拒绝邀请后，客户端 A 可以通过 callUserStateChanged 回调接口，收到相关通知。

callReject 说明

callReject(callID: string, config: ZIMCallRejectConfig): Promise<ZIMCallRejectionSentResult>;

示例代码

// 拒绝呼叫邀请
var callID = 'xxxx';
var config = { extendedData: 'xxxx' }; 
zim.callReject(callID, config)
    .then(res => {
        // 操作成功
    })
    .catch(err => {
        // 操作失败
    })

// 邀请者拒绝邀请后的回调通知
zim.on('callUserStateChanged', (zim, info) => {
    // 相关的 callID
    const changeCallID = info.callID;
    info.callUserList.forEach(userInfo => {
        // 状态变化用户的 userID、最新用户状态、透传字段（与用户该调用接受、拒绝、退出呼叫时携带的 extended data 一致）
        const { userID, state, extendedData } = userInfo;
        // state = 2 表示接受，具体可以参考枚举 ZIMCallUserState
        if (state == 2) {
            // 您的业务逻辑
        }

    });
})

6 超时未响应呼叫邀请

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

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

示例代码

zim.on('callUserStateChanged', (zim, info) => {
    // 相关的 callID
    const changeCallID = info.callID;
    info.callUserList.forEach(userInfo => {
        // 状态变化用户的 userID、最新用户状态、透传字段（与用户该调用接受、拒绝、退出呼叫时携带的 extended data 一致）
        const { userID, state, extendedData } = userInfo;
        // state = 6 表示超时，具体可以参考枚举 ZIMCallUserState
        if (state == 6) {
            // 您的业务逻辑
        }

    });
})

// 被邀请者响应超时后，“被邀请者”收到的回调通知，超时时间单位：秒
zim.on('callInvitationTimeout', (zim, { callID }) => {
    // console.log('callInvitationTimeout', { callID })
})

进阶模式

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

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

限于篇幅，进阶模式这里不详细展开，感兴趣的朋友可以到即构 开发者文档 进行查看。