目录

voipCall (In-App Call Management)

This module provides in-app call management functions, including reporting incoming and outgoing calls and call status to the system, as well as obtaining user tap events.

To obtain user tap events, you need to use voipCall.on to subscribe to voipCallUiEvent before the service process starts. After the service process ends, you can use voipCall.off to unsubscribe from the event.

Since: 4.1.0(11)

Modules to Import

import { voipCall } from '@kit.CallServiceKit';

VoipCallType

Enumerates call types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Value Description
VOIP_CALL_VOICE 0 Voice call.
VOIP_CALL_VIDEO 1 Video call.

VoipCallState

Enumerates call states.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Value Description
VOIP_CALL_STATE_IDLE 0 Idle state.
VOIP_CALL_STATE_RINGING 1 Incoming state.
VOIP_CALL_STATE_ACTIVE 2 Active state.
VOIP_CALL_STATE_HOLDING 3 Hold state.
VOIP_CALL_STATE_DISCONNECTED 4 Disconnected state.
VOIP_CALL_STATE_DIALING 5

Dialing.

Since: 5.0.0(12)
VOIP_CALL_STATE_ANSWERED 6

Answering.

Since: 5.0.0(12)
VOIP_CALL_STATE_DISCONNECTING 7

Disconnecting.

Since: 5.0.0(12)

VoipCallUiEvent

Enumerates call events.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Value Description
VOIP_CALL_EVENT_NONE 0 No event.
VOIP_CALL_EVENT_VOICE_ANSWER 1 Voice call answering event.
VOIP_CALL_EVENT_VIDEO_ANSWER 2 Video call answering event.
VOIP_CALL_EVENT_REJECT 3 Call rejection event.
VOIP_CALL_EVENT_HANGUP 4 Call hangup event.
VOIP_CALL_EVENT_MUTED 5

Mute event.

Since: 5.0.0(12)
VOIP_CALL_EVENT_UNMUTED 6

Unmute event.

Since: 5.0.0(12)
VOIP_CALL_EVENT_SPEAKER_ON 7

Speaker enabled event.

Since: 5.0.0(12)

(Reserved and not supported for now.)
VOIP_CALL_EVENT_SPEAKER_OFF 8

Speaker disabled event.

Since: 5.0.0(12)

(Reserved and not supported for now.)
VOIP_CALL_EVENT_MUTE_RINGTONE 9

Event of muting the ringtone by pressing a button.

Since: 6.0.2(22)

ErrorReason

Enumerates error code types.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Value Description
ERROR_NONE 0 No error.
CELLULAR_CALL_EXISTS 1 A cellular call already exists.
VOIP_CALL_EXISTS 2 An in-app call already exists.
INVALID_CALL 3 Certain call attributes (for example, call ID) are invalid.
USER_ANSWER_CELLULAR_FIRST 4 The user chooses to answer the cellular call.

VoipCallUiEventInfo

Defines call event information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Type Read-Only Optional Description
callId string No No Unique ID of an in-app call.
voipCallUiEvent VoipCallUiEvent No No In-app call event.
errorReason ErrorReason No No Error code of an in-app call.

VoipCallFailureCause

Enumerates the causes of incoming call connection failures.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Value Description
OTHER 0 Other failure causes.
ROUTE_BUSY 1 Line busy.
CONNECTION_FAILED 2 Call connection failure.

VoipCallAttribute

Defines call attributes.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Name Type Read-Only Optional Description
callId string No No Unique ID of an in-app call.
voipCallType VoipCallType No No In-app call type.
userName string No No User nickname of an in-app call.
userProfile image.PixelMap No No

User profile picture. The image processing module needs to be imported. For details, please refer to PixelMap.

The maximum dimension of the image is 221 × 221 pixels. The recommended dimension is 112 × 112 pixels. The size of the image obtained through the getPixelBytesNumber API of PixelMap must be less than 196,608 bits.
abilityName string No No Name of the app UI ability to be loaded after a call is answered.
voipCallState VoipCallState No No In-app call status.
showBannerForIncomingCall boolean No Yes

Indicates whether the app displays a notification banner for an incoming or outgoing call.

true: yes

false: no

The default value is true.

Since: 5.0.0(12)
isConferenceCall boolean No Yes

Indicates whether the call is a conference call.

true: yes

false: no

The default value is false.

Since: 5.0.0(12)
isVoiceAnswerSupported boolean No Yes

Indicates whether incoming or outgoing video calls support voice-only answering.

true: yes

false: no

The default value is true.

Since: 5.0.0(12)
isUserMuteRingToneAllowed boolean No Yes

Indicates whether the ringtone can be muted by pressing a button.

true: yes

false: no

The default value is false.

Since: 6.0.2(22)
isDialingAllowedDuringCarrierCall boolean No Yes

Indicates whether a VoIP call can be initiated during a carrier call.

true: yes

false: no

The default value is false.

Since: 6.0.2(22)

CallAudioEvent

Enumerates mute and speaker events.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 5.0.0(12)

Name Value Description
AUDIO_EVENT_MUTED 0 Mute.
AUDIO_EVENT_UNMUTED 1 Unmute.
AUDIO_EVENT_SPEAKER_ON 2 Speaker on.
AUDIO_EVENT_SPEAKER_OFF 3 Speaker off.
AUDIO_EVENT_MIC_DISABLE 5

Mute and microphone operation not allowed.

Since: 6.1.1(24)

Model restriction: This API can be used only in the stage model.

voipCall.on('voipCallUiEvent')

on(type: 'voipCallUiEvent', callback: Callback<VoipCallUiEventInfo>): void

Subscribes to voipCallUiEvent. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
type string Yes Call event type. The value is fixed at voipCallUiEvent.
callback Callback<VoipCallUiEventInfo> Yes Callback used to return the call event details object.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

voipCall.on('voipCallUiEvent', (data: voipCall.VoipCallUiEventInfo) => {
  hilog.info(0x0000, 'testTag', `Succeeded in reading callback. CallId: ${data.callId}, voipCallUiEvent: ${data.voipCallUiEvent}`);
});

voipCall.off('voipCallUiEvent')

off(type: 'voipCallUiEvent', callback?: Callback<VoipCallUiEventInfo>): void

Unsubscribes from voipCallUiEvent. This API uses an asynchronous callback to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
type string Yes Call event type. The value is fixed at voipCallUiEvent.
callback Callback<VoipCallUiEventInfo> No Callback used to return the call event details object. If this parameter is not specified, all callbacks for this event will be cancelled.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

voipCall.off('voipCallUiEvent', (data: voipCall.VoipCallUiEventInfo) => {
  hilog.info(0x0000, 'testTag', `Succeeded in reading callback. CallId: ${data.callId}, voipCallUiEvent: ${data.voipCallUiEvent}`);
});

voipCall.reportIncomingCall

reportIncomingCall(voipCallAttribute: VoipCallAttribute): Promise<ErrorReason>

Notifies an incoming call. If the incoming call connection fails, reportIncomingCallError needs to be called to notify the connection failure. Detailed call information needs to be set. For details, please refer to VoipCallAttribute. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
voipCallAttribute VoipCallAttribute Yes Detailed call information, including the user avatar, nickname, and call ID. For details, please refer to VoipCallAttribute. (When the app reports an outgoing call, the voipCallState attribute in VoipCallAttribute must be VOIP_CALL_STATE_DIALING.)

Returns:

Type Description
Promise<ErrorReason> Promise used to return the error code type.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { image } from '@kit.ImageKit';
import { voipCall } from '@kit.CallServiceKit';
import { resourceManager } from '@kit.LocalizationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { UIAbility } from '@kit.AbilityKit';
import { pushService } from '@kit.PushKit';

interface Content {
  data: string;
  callId: string;
}

export default class VoipAbility extends UIAbility {
  onCreate(): void {
    hilog.info(0x0000, 'testTag', 'VoipExtAbility onCreate.');
    try {
      pushService.receiveMessage('VoIP', this, async (data) => {
        let content: Content = JSON.parse(data.data);
        let callId: string = content.callId;

        hilog.info(0x0000, 'testTag', 'Get voip message successfully: %{public}s', callId);

        // User avatar. Set it to an object of the PixelMap type.
        const resourceMgr : resourceManager.ResourceManager = this.context.resourceManager;
        const fileData : Uint8Array = await resourceMgr.getRawFileContent('example.png');
        const buffer = fileData.buffer;
        const imageSource : image.ImageSource = image.createImageSource(buffer);
        const pixelMap : image.PixelMap = await imageSource.createPixelMap();
        if (pixelMap) {
          pixelMap.getImageInfo((err, imageInfo) => {
            if (imageInfo) {
              hilog.info(0x0000, 'testTag', `DemoPushMessageAbility imageInfo: ${imageInfo.size.width} * ${imageInfo.size.height}.`);
            }
          });
        }

        // Construct the object of call details.
        let callInfo: voipCall.VoipCallAttribute = {
          callId: callId,
          voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE,
          userName: "name",
          userProfile: pixelMap,
          abilityName: 'ability',
          voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_RINGING
        };

        // Send an incoming call notification.
        let error = await voipCall.reportIncomingCall(callInfo);
        if (error != voipCall.ErrorReason.ERROR_NONE) {
          hilog.error(0x0000, 'testTag', 'Failed to report incoming call: %{public}d', error);
          return;
        }

        hilog.info(0x0000, 'testTag', 'Get voip message end.');
      });
    } catch (err) {
      let e: BusinessError = err as BusinessError;
      hilog.error(0x0000, 'testTag', 'Failed to receive message: %{public}d %{public}s', e.code, e.message);
    }

    hilog.info(0x0000, 'testTag', 'Succeeded in registering VoIP.');
  }
}

voipCall.reportOutgoingCall

reportOutgoingCall(voipCallAttribute: VoipCallAttribute): Promise<ErrorReason>

The app reports an outgoing call. Detailed call information needs to be set. For details, please refer to VoipCallAttribute. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
voipCallAttribute VoipCallAttribute Yes Detailed call information, including the user avatar, nickname, and call ID. For details, please refer to VoipCallAttribute.

Returns:

Type Description
Promise<ErrorReason> Promise used to return the error code type.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { image } from '@kit.ImageKit';
import { voipCall } from '@kit.CallServiceKit';
import { resourceManager } from '@kit.LocalizationKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { UIAbility } from '@kit.AbilityKit';
import { pushService } from '@kit.PushKit';

interface Content {
  data: string;
  callId: string;
}

export default class VoipExtAbility extends UIAbility {
  onCreate(): void {
    hilog.info(0x0000, 'testTag', 'VoipExtAbility onCreate.');
    try {
      pushService.receiveMessage('VoIP', this, async (data) => {
        let content: Content = JSON.parse(data.data);
        let callId: string = content.callId;

        hilog.info(0x0000, 'testTag', 'Get voip message successfully: %{public}s', callId);

        // User avatar. Set it to an object of the PixelMap type.
        const resourceMgr : resourceManager.ResourceManager = this.context.resourceManager;
        const fileData : Uint8Array = await resourceMgr.getRawFileContent('example.png');
        const buffer = fileData.buffer;
        const imageSource : image.ImageSource = image.createImageSource(buffer);
        const pixelMap : image.PixelMap = await imageSource.createPixelMap();
        if (pixelMap) {
          pixelMap.getImageInfo((err, imageInfo) => {
            if (imageInfo) {
              hilog.info(0x0000, 'testTag', `DemoPushMessageAbility imageInfo: ${imageInfo.size.width} * ${imageInfo.size.height}.`);
            }
          });
        }

        // Construct the object of call details.
        let callInfo: voipCall.VoipCallAttribute = {
          callId: callId,
          voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE,
          userName: "name",
          userProfile: pixelMap,
          abilityName: 'ability',
          voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_DIALING
        };

        // Send an outgoing call notification.
        let error = await voipCall.reportOutgoingCall(callInfo);
        if (error != voipCall.ErrorReason.ERROR_NONE) {
          hilog.error(0x0000, 'testTag', 'Failed to report outgoing call: %{public}d', error);
          return;
        }
        hilog.info(0x0000, 'testTag', 'Get voip message end.');
      });
    } catch (err) {
      let e: BusinessError = err as BusinessError;
      hilog.error(0x0000, 'testTag', 'Failed to receive message: %{public}d %{public}s', e.code, e.message);
    }
    
    hilog.info(0x0000, 'testTag', 'Succeeded in registering VoIP.');
  }
}

voipCall.reportCallAudioEventChange

reportCallAudioEventChange(callId: string, callAudioEvent: CallAudioEvent): Promise<void>

The app reports the mute and speaker events during a call. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
callId string Yes Unique ID of an in-app call.
callAudioEvent CallAudioEvent Yes VoIP mute/unmute and speaker events. For details, please refer to CallAudioEvent.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { UIAbility } from '@kit.AbilityKit';
import { pushService } from '@kit.PushKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

interface Content {
  data: string;
  callId: string;
}

export default class VoipExtAbility extends UIAbility {
  onCreate(): void {
    hilog.info(0x0000, 'testTag', 'VoipExtAbility onCreate.');
    try {
      pushService.receiveMessage('VoIP', this, async (data) => {
        let content: Content = JSON.parse(data.data);
        let callId: string = content.callId;

        let callAudioEvent: voipCall.CallAudioEvent = voipCall.CallAudioEvent.AUDIO_EVENT_MUTED;

        // Report call mute and speaker events.
        await voipCall.reportCallAudioEventChange(callId, callAudioEvent);
        hilog.info(0x0000, 'testTag', `Succeeded in reporting call audio event change.`);
      });
    } catch (err) {
      let e: BusinessError = err as BusinessError;
      hilog.error(0x0000, 'testTag', 'Failed to receive message: %{public}d %{public}s', e.code, e.message);
    }
    
    hilog.info(0x0000, 'testTag', 'Succeeded in registering VoIP.');
  }
}

voipCall.reportCallStateChange

reportCallStateChange(callId: string, callState: VoipCallState): Promise<void>

Notifies the system of in-app call status changes. This API uses a promise to return the result.

This API cannot be used to change the call type. For example, a voice call cannot be upgraded to a video call, and a video call cannot be downgraded to a voice call. To upgrade or downgrade a call, call the voipCall.reportCallStateChange API.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
callId string Yes Call ID.
callState VoipCallState Yes Call status. For details, please refer to VoipCallState.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

await voipCall.reportCallStateChange("callId123", voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE);
hilog.info(0x0000, 'testTag', `Succeeded in reporting call state change.`);

voipCall.reportCallStateChange

reportCallStateChange(callId: string, callState: VoipCallState, callType: VoipCallType): Promise<void>

Notifies an in-app call status change and specifies the call type. This API uses a promise to return the result.

This API supports voice answering for an incoming video call and allows switching between video and voice during an ongoing call. The correct call type must be passed.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 5.0.0(12)

Parameters:

Parameter Type Mandatory Description
callId string Yes Call ID.
callState VoipCallState Yes Call status. For details, please refer to VoipCallState.
callType VoipCallType Yes Call type. For details, please refer to VoipCallType.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

await voipCall.reportCallStateChange("callId123", voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE, voipCall.VoipCallType.VOIP_CALL_VOICE);
hilog.info(0x0000, 'testTag', `Succeeded in reporting call state change.`);

voipCall.reportIncomingCallError

reportIncomingCallError(callId: string, voipCallFailureCause: VoipCallFailureCause): Promise<void>

Notifies the system of an incoming call connection failure. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 4.1.0(11)

Parameters:

Parameter Type Mandatory Description
callId string Yes Unique ID of an in-app call.
voipCallFailureCause VoipCallFailureCause Yes Cause of an incoming call connection failure.

Returns:

Type Description
Promise<void> Promise that returns no value.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
401 Parameter error. The type of parameter should match or the number of parameters must match.
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.
1007200999 Unknown error code.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

await voipCall.reportIncomingCallError("callId123", voipCall.VoipCallFailureCause.OTHER);
hilog.info(0x0000, 'testTag', `Succeeded in reporting incoming call error.`);

voipCall.reportCallAttributeChange

reportCallAttributeChange(voipCallAttribute: VoipCallAttribute): Promise<ErrorReason>

Reports the change of call attributes. During a call, when the call attributes change, the app can call this API to update the call attributes (including the call type allowed in the current version, nickname of the in-app call user, user profile picture, and whether the call is a conference call). This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Telephony.VoipCallManager

Since: 26.0.0

Parameters:

Parameter Type Mandatory Description
voipCallAttribute VoipCallAttribute Yes Detailed call information, including the call attributes to be updated. For details, please refer to VoipCallAttribute.

Returns:

Type Description
Promise<ErrorReason> Promise used to return the error code.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1007200001 Invalid parameter value.
1007200002 Operation failed. Cannot connect to service.
1007200003 System internal error.

Example:

import { voipCall } from '@kit.CallServiceKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let newUserProfile = image.createPixelMapSync(new ArrayBuffer(100), { size: { width: 90, height: 90 } });
let updatedAttribute: voipCall.VoipCallAttribute = {
  callId: '1234567890',
  voipCallType: voipCall.VoipCallType.VOIP_CALL_VOICE,
  userName: 'UpdatedName',
  userProfile: newUserProfile,
  abilityName: 'VoipCallAbility',
  voipCallState: voipCall.VoipCallState.VOIP_CALL_STATE_ACTIVE
};

let error = await voipCall.reportCallAttributeChange(updatedAttribute);
if (error == voipCall.ErrorReason.ERROR_NONE) {
    hilog.info(0x0000, 'testTag', `Succeeded in reporting call attribute change.`);
} else {
    hilog.error(0x0000, 'testTag', 'Failed to report call attribute change: %{public}d', error);
}