Call Service Kit实战：HarmonyOS来去电企业服务卡

鸿蒙专家

在快递物流、外卖派送、专车出行这类ToB业务中，客服或配送人员与客户的每一次通话，都是传递关键信息的黄金窗口。如果能在系统原生的来去电接听页面上，直接展示实时订单状态、配送地址和预计送达时间，就能让一线人员无需切换应用即可掌握全部业务上下文。过去这种底层通话拦截与UI渲染能力被系统牢牢锁死，但在HarmonyOS NEXT 6.1.1（API 24）中，华为通过@kit.CallServiceKit向通过资质审核的企业级应用开放了这一通道。开发者可以派生专属的CallerInfoQueryExtensionAbility，向原生通话界面注入结构化的富文本业务数据。本文从零梳理接入流程，并在端侧完成一个来去电企服信息展示的实战搭建。

一、Call Service Kit能力概述

Call Service Kit是HarmonyOS的系统级通信中枢，向上层应用提供状态订阅、VoIP集成等进阶能力。在6.1.1版本中，该套件新增了企业服务信息展示能力，允许合规应用接入系统的电话识别链路。当通话触发时，系统通话应用拉起已注册的应用Extension，下发对方号码，应用返回一组结构化业务数据，由系统来去电UI按标准模板进行原生级渲染。

二、核心API与数据模型

本次开放的核心位于CallerInfoQueryExtensionAbility扩展能力基类，新增了一个生命周期方法与一个环境开关查询函数。

2. // 查询陌生号码识别总开关状态，以及当前应用是否被用户授予识别权限
3. queryNumberIdentifySwitchState(context: Context): SwitchState;
5. // 来/去电核心回调，使用Promise异步响应
6. onQueryBusinessServiceData(phoneNumber: string): Promise<Array<BusinessServiceData>>;

复制代码

BusinessServiceData支持强类型定制字段。例如numberIdentify.BusinessServiceType.DELIVERY枚举明确当前渲染为“派送模式”，系统将自动适配单号、地址、倒计时等字段的展示样式。

三、AGC资质申请与冲突排序规则

值得强调的是，这一功能并非普通API随开随用。由于涉及通信隐私，仅限企业开发者使用。申请流程为：登录AppGallery Connect（AGC），进入项目设置中的开放能力管理，手动申请“企业服务信息展示”特权，等待1-3个工作日的人工审查。获批后需重新拉取Debug Profile并替换签名文件，设备底座才会放行这段代码。

当系统装有多款应用同时竞争同一通电话的展示位时，系统仅展示第一条企业服务信息数据。若多款应用具备同等权限，则按应用包名（Bundle Name）字典序排队，排第一的独占展示权。

四、实战：构建CallerInfoQueryExtensionAbility

在应用工程内创建Extension文件entry/src/main/ets/businessservicedataquery/EntryBusinessServiceDataQueryExtAbility.ets，核心实现如下：

2. import { CallerInfoQueryExtensionAbility, numberIdentify } from '@kit.CallServiceKit';
4. export default class EntryBusinessServiceDataQueryExtAbility extends CallerInfoQueryExtensionAbility {
5.   // 来去电时由系统通话应用主动调用该接口查询企业联系人信息
6.   async onQueryBusinessServiceData(phoneNumber: string): Promise<Array<numberIdentify.BusinessServiceData>> {
7.     console.info(`[CallServiceKitDemo] 触发企业服务信息查询，当前号码: ${phoneNumber}`);
8.     return new Promise<Array<numberIdentify.BusinessServiceData>>((resolve, reject) => {
9.       // 业务实战：从RDB关系型数据库或本地高速KVStore检索该号码关联的运单
10.       let isSuccess = true;
11.       if (isSuccess) {
12.         console.info(`[CallServiceKitDemo] 数据查询成功，开始组装派送单数据...`);
13.         // 返回符合派送业务类型的特征数据包
14.         resolve([{
15.           type: numberIdentify.BusinessServiceType.DELIVERY,
16.           delivery: {
17.             customerName: "骑兵连孙德胜",
18.             deliveryNumber: "SF1008611",
19.             deliveryStatus: "正在派送中",
20.             deliveryAddress: "鸿蒙研发中心三号楼",
21.             deliveryTimeout: "今天 18:00 前",
22.             deliveryStatusColor: numberIdentify.DeliveryStatusColor.GREEN
23.           }
24.         }]);
25.       } else {
26.         reject("未命中本地缓存订单");
27.       }
28.     });
29.   }
30. }

复制代码

在module.json5中注册Extension，type必须指定为callerInfoQuery：

2. {
3.   "module": {
4.     "extensionAbilities": [
5.       {
6.         "name": "EntryBusinessServiceDataQueryExtAbility",
7.         "srcEntry": "./ets/businessservicedataquery/EntryBusinessServiceDataQueryExtAbility.ets",
8.         "type": "callerInfoQuery",
9.         "exported": true
10.       }
11.     ]
12.   }
13. }

复制代码

五、运行效果与验证

在调试设备上激活功能，需要进入系统“电话”App，点击右上角“更多”进入“设置”，找到“陌生号码和信息识别”，开启总开关并激活已安装应用的应用子开关。完成上述步骤后，用另一部手机拨打测试机号码，原生接听界面会在号码下方展示绿色信息卡片，显示“SF1008611 | 正在派送中 | 鸿蒙研发中心三号楼”。接线员无需切换后台即可获取客户的全部订单状态。

六、避坑要点

1. 严格的时间约束：onQueryBusinessServiceData接口执行耗时必须控制在1秒（1000ms）以内，超时即判定查询失败。因此绝不能在回调内发起即时的HTTP远端请求。正确做法是App后台静默预拉取数据，或通过推送将数据落盘到本地SQLite/KVStore，在回调时直接扫描本地存储，确保10毫秒级返回。

2. AbilityStage连坐陷阱：系统拉起Extension前会先创建宿主应用的AbilityStage。若AbilityStage.onCreate阶段承载了大量耗时逻辑，如超大SO库解压、白屏加载等，会牵连Extension启动延误，触发超时。涉及通话展示特权的应用，Stage阶段代码必须保持极致精简。

七、总结

Call Service Kit的这次开放，让HarmonyOS NEXT在系统底层通话界面实现了与企业级应用生态的融合。这种原生赋权为B端应用带来了显著的体验提升。与此同时，AGC资质准入和1秒查询超时这两条红线，是所有接入该能力的开发者必须时刻守住的底线。

热心网友6

干货满满！正好最近在调研鸿蒙企业通话能力，这篇把从资质申请到Extension落地的完整链路讲得很清楚。尤其那个“包名排序独占展示位”的规则，对多应用竞争场景太关键了，感谢避坑。后续有机会能再聊聊BusinessServiceData里其他业务类型（比如出行、快递）的字段适配吗？

热心网友6

好文。这个Kit对企业场景确实是刚需，尤其外卖、物流这种，以前想抢系统通话页面的展示位根本没门路，现在鸿蒙愿意开放底层通道，算是个大突破。 不过有几个点想请教下细节： 1. `BusinessServiceData` 里除了 `DELIVERY` 这种类型，官方目前还开放了哪些枚举？比如快递取件、网约车接驾，是不是都用同一套字段还是各自有专属模板？ 2. 如果应用查询耗时比较长（比如网络请求），系统那边有没有超时限制？超时后会直接踢掉还是展示一个空壳？ 3. 文中提到“系统仅展示第一条企业服务信息”，这个“第一条”是指按包名排完序后的第一个有效结果吗？如果第一个应用返回空数组，会不会自动落到第二个？ 另外老哥有没有测试过在通话记录或者通话详情页里，这些注入的数据会不会保留？目前看只有你来去电页面的截图，详情页没提。如果能延伸到通话记录里，那价值就更大了。

热心网友6

感谢分享！这个企业服务信息展示能力确实很实用，尤其对物流、外卖这类强通话依赖的场景，能在系统来电界面直接看到订单上下文，能省掉不少切换应用的麻烦。有个问题想请教下：如果应用已经拿到“企业服务信息展示”资质，但用户在系统设置里手动关闭了某个应用的识别权限，这时候`queryNumberIdentifySwitchState`返回的状态是直接拦截回调，还是仍然会触发`onQueryBusinessServiceData`只是最终不展示？另外，`BusinessServiceData`里那些字段（比如配送状态颜色、倒计时）是系统固定模板，还是允许开发者传自定义样式？期待后续能分享更多落地细节。