输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
指南与API参考
指南
API

推送应用内通话消息

更新时间: 2026-09-09 06:54
复制页面
本文导读
展开章节

场景介绍

应用内通话消息，支持应用实现网络音视频通话的能力。当终端处于锁屏或解锁两种不同状态时，Push Kit将分别进行以下处理：

  • 终端处于锁屏状态时，可在锁屏上点击接听或拒绝按钮。锁屏状态下只支持接听语音。

  • 终端处于解锁状态时，网络音视频通话呼叫消息显性展示于横幅，支持用户接听视频或语音。

接听视频时会拉起应用内的接听界面。接通后，可以正常挂断（主动挂断/被动挂断）应用内通话消息。

应用内通话消息样式可参考如下示例，真实样式请以实际效果为准：

展开
锁屏 来电横幅
说明

  • 应用内通话消息的问题场景请参见指导。

  • 应用内通话消息的pushOptions.ttl建议设置为30~60秒。

约束与限制

推送应用内通话消息能力支持Phone、Tablet设备，并且从6.1.0(23)版本开始，新增支持儿童智能表。

开通权益

推送应用内通话消息需要申请场景化消息权益，请参见申请推送应用内通话消息权益。

频控规则

调测阶段，每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。

正式发布阶段，单设备单应用下每日推送消息总条数受设备消息频控限制，系统会根据使用场景和流量进行管控，不合理的使用场景系统会进行频控。

开发步骤

  1. 参见指导获取Push Token。

  2. 在您的工程内创建一个UIAbility类型的组件，如VoIPUIAbility.ets（在项目工程的src/main/ets/entryability目录下），负责处理应用内通话消息的主流程，并完成onCreate()、onWindowStageCreate()、onDestroy()方法的覆写，代码示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. import { UIAbility } from '@kit.AbilityKit';
    2. import { pushService } from '@kit.PushKit';
    3. import { window } from '@kit.ArkUI';
    4. import { hilog } from '@kit.PerformanceAnalysisKit';
    5. import { VoipCallService } from '../service/VoipCallService';
    6. import { BusinessError } from '@kit.BasicServicesKit';
    7. 

    8. const DOMAIN = 0x0000;
    9. 

    10. export default class VoIPUIAbility extends UIAbility {
    11.   onCreate(): void {
    12.     hilog.info(DOMAIN, 'testTag', 'VoIPUIAbility onCreate');
    13. 

    14.     try {
    15.       pushService.receiveMessage('VoIP', this, async (data) => {
    16.         // 处理应用内通话消息数据
    17.         try {
    18.           await VoipCallService.processVoIPMainMsg(data.data, this.context);
    19.         } catch (error) {
    20.           hilog.error(DOMAIN, 'testTag', 'Failed to process VoIP message: %{public}d %{public}s', error.code,
    21.             error.message);
    22.         }
    23.       });
    24.     } catch (e) {
    25.       hilog.error(DOMAIN, 'testTag', `Failed to register VoIP, error: ${e.code}, ${e.message}.`);
    26.     }
    27.   }
    28. 

    29.   onWindowStageCreate(windowStage: window.WindowStage): void {
    30.     hilog.info(DOMAIN, 'testTag', 'VoIPUIAbility onWindowStageCreate.');
    31. 

    32.     windowStage.loadContent('pages/CalleePage').catch((err: BusinessError) => {
    33.       hilog.error(DOMAIN, 'testTag', `Failed to load content, error: ${err.code}, ${err.message}.`);
    34.     });
    35.   }
    36. 

    37.   onDestroy(): void {
    38.     hilog.info(DOMAIN, 'testTag', 'VoIPUIAbility onDestroy');
    39.   }
    40. }

    VoipCallService.ets（在项目工程的src/main/ets/service目录下），处理应用内通话消息，代码示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. import { voipCall } from '@kit.CallServiceKit';
    2. import { hilog } from '@kit.PerformanceAnalysisKit';
    3. import { common } from '@kit.AbilityKit';
    4. import { image } from '@kit.ImageKit';
    5. import { resourceManager } from '@kit.LocalizationKit';
    6. import { BusinessError } from '@kit.BasicServicesKit';
    7. 

    8. export interface VoipScene {
    9.   scene: string;
    10. }
    11. 

    12. export interface Content {
    13.   data: string;
    14.   header: string;
    15.   callId: string;
    16. }
    17. 

    18. const DOMAIN = 0x0000;
    19. 

    20. export class VoipCallService {
    21.   private static callId: string | undefined;
    22. 

    23.   public static async processVoIPMainMsg(data: string,
    24.     context: common.UIAbilityContext): Promise<void> {
    25.     hilog.info(DOMAIN, 'testTag', `Process VoIP message: ${data}`);
    26. 

    27.     let content: Content;
    28.     let scene: VoipScene;
    29.     let callId: string;
    30. 

    31.     try {
    32.       content = JSON.parse(data);
    33.       scene = JSON.parse(content.data);
    34.       callId = content.callId;
    35.       if (!callId) {
    36.         hilog.error(DOMAIN, 'testTag', 'CallId is null');
    37.       }
    38.       VoipCallService.callId = callId;
    39.     } catch (e) {
    40.       let err: BusinessError = e as BusinessError;
    41.       hilog.error(DOMAIN, 'testTag', 'Failed to parse VoIP message data: %{public}d %{public}s', err.code, err.message);
    42.       return;
    43.     }
    44. 

    45.     try {
    46.       // 注册voipCallUiEvent事件
    47.       voipCall.on('voipCallUiEvent', async (event) => {
    48.         hilog.info(DOMAIN, 'testTag', `Process voip call ui event: ${JSON.stringify(event)}.`);
    49. 

    50.         await VoipCallService.processVoipCallEvent(event.voipCallUiEvent);
    51.       });
    52.     } catch (err) {
    53.       let e: BusinessError = err as BusinessError;
    54.       hilog.error(DOMAIN, 'testTag', 'Failed to register event: %{public}d %{public}s', e.code, e.message);
    55.     }
    56. 

    57.     const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
    58.     let fileData: Uint8Array = new Uint8Array(0);
    59.     try {
    60.       // example.png表示用户头像，取值为“/resources/rawfile”路径下的文件名
    61.       fileData = await resourceMgr.getRawFileContent('example.png');
    62.     } catch (e) {
    63.       hilog.error(DOMAIN, 'testTag', 'Failed to get raw file: %{public}d %{public}s', e.code, e.message);
    64.     }
    65.     const buffer = fileData.buffer;
    66.     const imageSource: image.ImageSource = image.createImageSource(buffer);
    67.     const pixelMap: image.PixelMap = await imageSource.createPixelMap();
    68.     if (pixelMap) {
    69.       pixelMap.getImageInfo((err, imageInfo) => {
    70.         if (imageInfo) {
    71.           hilog.info(DOMAIN, 'testTag',
    72.             `User profile imageInfo: ${imageInfo.size.width} * ${imageInfo.size.height}.`);
    73.         } else {
    74.           hilog.error(DOMAIN, 'testTag', `Failed to obtain the image information.code is ${err.code}, message is ${err.message}`);
    75.         }
    76.       });
    77.     }
    78. 

    79.     // 构造上报来电的参数。注意，voipCallType.scene为您自定义的场景类型字段，从云侧推送消息时，请注意与端侧取值保持一致
    80.     let call: voipCall.VoipCallAttribute = {
    81.       callId: callId,
    82.       voipCallType: scene?.scene === 'video' ? voipCall.VoipCallType.VOIP_CALL_VIDEO :
    83.         voipCall.VoipCallType.VOIP_CALL_VOICE,
    84.       userName: 'push',
    85.       userProfile: pixelMap,
    86.       abilityName: 'VoIPUIAbility',
    87.       voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING
    88.     };
    89. 

    90.     try {
    91.       // 上报来电
    92.       let error = await voipCall.reportIncomingCall(call);
    93.       hilog.info(DOMAIN, 'testTag', `ReportIncomingCall result: ${error}.`);
    94.     } catch (err) {
    95.       let e: BusinessError = err as BusinessError;
    96.       hilog.error(DOMAIN, 'testTag', 'Failed to report incoming call: %{public}d %{public}s', e.code, e.message);
    97.     }
    98. 

    99.     // ...应用播放振动和铃声
    100.   }
    101. 

    102.   public static async processVoipCallEvent(event: voipCall.VoipCallUiEvent) {
    103.     try {
    104.       switch (event) {
    105.         case voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_VOICE_ANSWER:
    106.         case voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_VIDEO_ANSWER:
    107.           // 立即向Call Service Kit上报answered状态
    108.           await voipCall.reportCallStateChange(VoipCallService.callId,
    109.             voipCall.VoipCallState.VOIP_CALL_STATE_ANSWERED);
    110. 

    111.           // ...在应用内完成接听
    112. 

    113.           // 应用内接听后，向Call Service Kit上报active状态
    114.           await voipCall.reportCallStateChange(VoipCallService.callId,
    115.             voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE);
    116.           break;
    117.         case voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_REJECT:
    118.         case voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_HANGUP:
    119.           // ...应用内完成挂断
    120. 

    121.           // 向Call Service Kit上报通话状态
    122.           await voipCall.reportCallStateChange(VoipCallService.callId,
    123.             voipCall.VoipCallState.VOIP_CALL_STATE_DISCONNECTED);
    124.           break;
    125.         default: {
    126.           break;
    127.         }
    128.       }
    129.     } catch (err) {
    130.       let e: BusinessError = err as BusinessError;
    131.       hilog.error(DOMAIN, 'testTag', 'Failed to report call state change: %{public}d %{public}s', e.code, e.message);
    132.     }
    133.   }
    134. 

    135.   public static close(): void {
    136.     hilog.info(DOMAIN, 'testTag', 'Close VoIP');
    137. 

    138.     VoipCallService.processVoipCallEvent(voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_HANGUP);
    139.     try {
    140.       voipCall.off('voipCallUiEvent');
    141.     } catch (err) {
    142.       let e: BusinessError = err as BusinessError;
    143.       hilog.error(DOMAIN, 'testTag', 'Failed to unregister event: %{public}d %{public}s', e.code, e.message);
    144.     }
    145.   }
    146. }
    说明

    需要在项目工程的src/main/resources/rawfile目录下添加example.png，表示来电时的用户头像。

    • UIAbility.onCreate是同步接口，不支持异步回调，需要在onCreate生命周期的入口，完成pushService.receiveMessage()注册，并且保证在注册前没有等待异步方法执行的调用。
    • 在receiveMessage()回调中接收应用内通话消息，建议应用提前和服务器建连，用户点击接听后可以立即进行通话，并调用voipCall.on接口注册监听通话状态回调。用户点击接听或者拒绝接听之后，系统会通过应用注册的事件监听通话状态回调结果。
    • 应用需要在10秒内调用voipCall.reportIncomingCall接口上报通话来电状态，调用完成之后，系统会弹出应用内通话横幅通知。voipCall.reportIncomingCall()接口入参中的callId需要使用receiveMessage()回调中的callId。
    • 如果应用来电消息建立失败，需要调用voipCall.reportIncomingCallError()通知来电消息建立失败。如果应用在前台，通过自己的网络连接接收到来电消息，调用voipCall.reportIncomingCall接口上报了通话来电状态，后面才收到Push推送的应用内通话消息，在该消息处理中需要调用voipCall.reportIncomingCallError()上报应用线路忙。
    • 应用内通话主要有三种回调状态，分别为：接听状态、拒绝状态和挂断状态。
      • 在接听状态回调中，应用在建立连接成功之后，需要调用voipCall.reportCallStateChange接口上报通话激活状态。
      • 在拒绝接听状态回调中，应用断开和服务器的连接之后，需要调用voipCall.reportCallStateChange接口上报通话断开状态。
      • 在应用进行应用内通话的同时，若运营商来电，会弹出运营商来电接听界面，用户点击接听运营商来电之后，会回调应用内通话挂断状态，在回调方法中应用需要自行断开和服务器的连接，并调用voipCall.reportCallStateChange接口上报通话断开状态。
    • 有关应用内通话回调状态的更多信息，详情请参见Call Service Kit简介。
    • 应用上报通话来电状态之后，可以调用vibrator.startVibration触发振动，有关振动的更多详情，请参见Sensor Service Kit简介。可以使用AVPlayer播放应用铃声，音频流建议设置为铃声，usage设置为STREAM_USAGE_RINGTONE，效果为开始响铃，播放的音乐会暂停播放。同时推荐使用AudioSession管理音频焦点，可以保证接听过程中、通话过程中都保持音频焦点，详情请参见Audio Kit简介。
    • 进行音视频通话时，若您的应用处于OVERHEATED场景（设备发热严重或负载较重，Level=4），请降低码率和帧率，或关闭视频流降级为音频。相关说明请参见Basic Services Kit（基础服务）提供的接口getLevel()。

  3. 在项目工程的 src/main/ets/pages目录添加：视频接听页面CalleePage.ets，代码示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. import CallComponent from '../component/CallComponent';
    2. import { hilog } from '@kit.PerformanceAnalysisKit';
    3. 

    4. const DOMAIN = 0x0000;
    5. 

    6. @Entry
    7. @Component
    8. struct CalleePage {
    9.   @StorageLink('close') @Watch('close') end: boolean | undefined = undefined;
    10. 

    11.   aboutToAppear() {
    12.     hilog.info(DOMAIN, 'testTag', 'CalleePage aboutToAppear');
    13. 

    14.     this.end = false;
    15.   }
    16. 

    17.   private close() {
    18.     if (this.end) {
    19.       hilog.info(DOMAIN, 'testTag', 'CalleePage close');
    20. 

    21.       this.getUIContext().getRouter().back(); // 此处仅为示例（跳转返回），请根据实际情况设定路由
    22.     }
    23.   }
    24. 

    25.   aboutToDisappear() {
    26.     hilog.info(DOMAIN, 'testTag', 'CalleePage aboutToDisappear');
    27.   }
    28. 

    29.   build() {
    30.     Column() {
    31.       CallComponent({})
    32.     }
    33.   }
    34. }

    CallComponent.ets（在项目工程的src/main/ets/component目录下），代码示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. import { VoipCallService } from '../service/VoipCallService';
    2. import { voipCall } from '@kit.CallServiceKit';
    3. 

    4. @Component
    5. export default struct CallComponent {
    6.   @StorageLink('close') end: boolean | undefined = undefined;
    7. 

    8.   build() {
    9.     Flex({ direction: FlexDirection.Column, justifyContent: FlexAlign.SpaceBetween }) {
    10.       Row() {
    11.       }
    12.       .width('100%')
    13.       .justifyContent(FlexAlign.Center)
    14. 

    15.       Row({ space: 30 }) {
    16. 

    17.         Column() {
    18.           Button()
    19.             .width(80)
    20.             .height(80)
    21.             .backgroundColor(Color.Green)
    22.             .onClick(() => {
    23.               VoipCallService.processVoipCallEvent(voipCall.VoipCallUiEvent.VOIP_CALL_EVENT_VIDEO_ANSWER);
    24.             })
    25. 

    26.           Text('Answer').fontColor(Color.White).padding({ top: 5 })
    27.         }
    28. 

    29.         Column() {
    30.           Button()
    31.             .width(80)
    32.             .height(80)
    33.             .backgroundColor(Color.Red)
    34.             .onClick(() => {
    35.               this.end = true;
    36.               VoipCallService.close();
    37.             })
    38. 

    39.           Text('Hang Up').fontColor(Color.White).padding({ top: 5 })
    40.         }
    41. 

    42.       }
    43.       .width('100%')
    44.       .justifyContent(FlexAlign.Center)
    45.     }
    46.     .padding('30 10')
    47.     .backgroundColor(Color.Black)
    48.   }
    49. }

    在项目工程的 src/main/resources/base/profile/main_pages.json添加page目录，示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. {
    2.   "src": [
    3.     "pages/Index",
    4.     "pages/CalleePage"
    5.   ]
    6. }
    说明

    示例代码提供的页面效果仅供开发参考，不代表最终效果。

  4. 在项目工程的 src/main/module.json5 文件的abilities模块中配置VoIPUIAbility的 actions 信息。

    收起
    自动换行
    深色代码主题
    复制
    1. "abilities": [
    2.   // ...
    3.   {
    4.     "name": "VoIPUIAbility",
    5.     "srcEntry": "./ets/entryability/VoIPUIAbility.ets",
    6.     "launchType": "singleton",
    7.     "description": "$string:module_desc",
    8.     "startWindowIcon": "$media:startIcon",
    9.     "startWindowBackground": "$color:start_window_background",
    10.     "exported": false,
    11.     "skills": [
    12.       // 保持现有skill对象不变
    13.       // 新增一个独立的skill对象，配置actions参数为action.ohos.push.listener，有且只能有一个ability定义该action
    14.       {
    15.         "actions": [
    16.           "action.ohos.push.listener"
    17.         ]
    18.       }
    19.     ]
    20.   }
    21.   // ...
    22. ]
    • actions：内容为action.ohos.push.listener，有且只能有一个ability定义该action，若同时添加uris参数，则uris内容需为空。

  5. 应用服务端调用REST API推送消息，消息详情可参见场景化消息API接口功能介绍。

应用内通话消息

  1. 如果您需要呼叫，应用服务器可以调用REST API推送应用内通话消息，请求示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. // Request URL
    2. POST "https://push-api.cloud.huawei.com/v3/[projectId]/messages:send"
    3. 

    4. // Request Header
    5. Content-Type: application/json
    6. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
    7. push-type: 10
    8. 

    9. // Request Body
    10. {
    11.   "pushOptions": {
    12.     "ttl": 30
    13.   },
    14.   "payload": {
    15.     "extraData": "{\"scene\": \"voice\"}"
    16.   },
    17.   "target": {
    18.     "token": ["MAMzLg**********aZW"]
    19.   }
    20. }
    • [projectId]：项目ID，登录AppGallery Connect网站，选择“开发与服务”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。
    • Authorization：JWT格式字符串，可参见基于服务账号生成鉴权令牌进行获取。
    • push-type：10表示应用内通话消息场景。
    • token：Push Token，可参见获取Push Token章节获取。
    • extraData：携带的额外数据，字符串类型。详情参见VoIPCallPayload 应用内通话消息中extraData参数用法。extraData数据获取请参考示例代码。
    • ttl：消息缓存时间，建议设置为30~60秒，详见pushOptions.ttl。
说明

  • 应用内通话消息只能用于音视频通话场景唤醒应用，完成呼叫，不要通过此种类型消息来挂断来电或者和应用通信，应用应该使用自己建立的网络连接和应用通信。相比应用服务器推送Push消息，使用现有的网络连接和应用通信通常会更快，在网络不佳的情况下，推送的Push消息可能无法到达应用。

  • 应用无论是否在前台，自己的网络连接存在时，建议您通过Push推送应用内通话消息，再通过自己的网络连接发送通话消息，保证该呼叫能够到达应用。

未接来电通知

  1. 如果您需要给被叫方发送未接来电通知，应用服务器可以调用REST API推送通知消息。以通知消息为例，请求示例如下：

    收起
    自动换行
    深色代码主题
    复制
    1. // Request URL
    2. POST "https://push-api.cloud.huawei.com/v3/[projectId]/messages:send"
    3.    
    4. // Request Header
    5. Content-Type: application/json
    6. Authorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****
    7. push-type: 0
    8.    
    9. // Request Body
    10. {
    11.   "pushOptions": {
    12.     "ttl":86400
    13.   },
    14.   "payload": {
    15.     "notification": {
    16.       "category": "MISS_CALL",
    17.       "title": "通知标题",
    18.       "body": "通知内容",
    19.       "clickAction": {
    20.         "actionType": 0
    21.       },
    22.       "appMessageId": "12345"
    23.     }
    24.    },
    25.    "target": {
    26.      "token": ["MAMzLg**********aZW"]
    27.    }
    28.  }
    • push-type：0表示通知消息场景。
    • category：消息自分类类别，设置为MISS_CALL，请参见参数说明，发送消息前请确保您已申请通知消息自分类权益。
    • appMessageId：应用消息的唯一标识。主叫挂断，被叫方VoIP应用在前台时应用可以通过调用Notification Kit（用户通知服务）发送未接来电通知。被叫方VoIP应用在后台时，可以通过Push推送未接来电通知。应用可能存在前后台状态判断不准确，同一电话会产生两条未接来电，建议您通过Notification Kit和Push Kit推送的未接来电通知使用相同的appMessageId，系统会进行通知去重。
    • 其他参数说明可参见通知消息请求体参数说明。
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明