API Reference

Complete API method reference provided by AaaS Pilot Kit.

Constant Exports

Azure Region Constants (AzureSpeechRegion)

Used to configure the region for Azure Speech Service.

import {AzureSpeechRegion} from '@bdky/aaas-pilot-kit';

Asia Pacific:

Constant	Value	Description
`AzureSpeechRegion.EAST_ASIA`	`'eastasia'`	East Asia (Hong Kong)
`AzureSpeechRegion.SOUTHEAST_ASIA`	`'southeastasia'`	Southeast Asia (Singapore)
`AzureSpeechRegion.JAPAN_EAST`	`'japaneast'`	Japan East
`AzureSpeechRegion.JAPAN_WEST`	`'japanwest'`	Japan West
`AzureSpeechRegion.KOREA_CENTRAL`	`'koreacentral'`	Korea Central
`AzureSpeechRegion.AUSTRALIA_EAST`	`'australiaeast'`	Australia East
`AzureSpeechRegion.CENTRAL_INDIA`	`'centralindia'`	Central India

North America:

Constant	Value	Description
`AzureSpeechRegion.EAST_US`	`'eastus'`	East US
`AzureSpeechRegion.EAST_US_2`	`'eastus2'`	East US 2
`AzureSpeechRegion.WEST_US`	`'westus'`	West US
`AzureSpeechRegion.WEST_US_2`	`'westus2'`	West US 2
`AzureSpeechRegion.WEST_US_3`	`'westus3'`	West US 3
`AzureSpeechRegion.CENTRAL_US`	`'centralus'`	Central US
`AzureSpeechRegion.CANADA_CENTRAL`	`'canadacentral'`	Canada Central

Europe:

Constant	Value	Description
`AzureSpeechRegion.NORTH_EUROPE`	`'northeurope'`	North Europe (Ireland)
`AzureSpeechRegion.WEST_EUROPE`	`'westeurope'`	West Europe (Netherlands)
`AzureSpeechRegion.UK_SOUTH`	`'uksouth'`	UK South
`AzureSpeechRegion.FRANCE_CENTRAL`	`'francecentral'`	France Central
`AzureSpeechRegion.GERMANY_WEST_CENTRAL`	`'germanywestcentral'`	Germany West Central
`AzureSpeechRegion.SWITZERLAND_NORTH`	`'switzerlandnorth'`	Switzerland North
`AzureSpeechRegion.NORWAY_EAST`	`'norwayeast'`	Norway East

Other Regions:

Constant	Value	Description
`AzureSpeechRegion.BRAZIL_SOUTH`	`'brazilsouth'`	Brazil South
`AzureSpeechRegion.SOUTH_AFRICA_NORTH`	`'southafricanorth'`	South Africa North
`AzureSpeechRegion.UAE_NORTH`	`'uaenorth'`	UAE North

Azure Language Constants (AzureSpeechLanguage)

Used to configure the language for Azure Speech Recognition.

import {AzureSpeechLanguage} from '@bdky/aaas-pilot-kit';

Chinese:

Constant	Value	Description
`AzureSpeechLanguage.CHINESE_SIMPLIFIED_CN`	`'zh-CN'`	Simplified Chinese (Mainland China)
`AzureSpeechLanguage.CHINESE_TRADITIONAL_TW`	`'zh-TW'`	Traditional Chinese (Taiwan)
`AzureSpeechLanguage.CHINESE_TRADITIONAL_HK`	`'zh-HK'`	Traditional Chinese (Hong Kong)

English:

Constant	Value	Description
`AzureSpeechLanguage.ENGLISH_US`	`'en-US'`	English (United States)
`AzureSpeechLanguage.ENGLISH_UK`	`'en-GB'`	English (United Kingdom)
`AzureSpeechLanguage.ENGLISH_AU`	`'en-AU'`	English (Australia)
`AzureSpeechLanguage.ENGLISH_CA`	`'en-CA'`	English (Canada)
`AzureSpeechLanguage.ENGLISH_IN`	`'en-IN'`	English (India)
`AzureSpeechLanguage.ENGLISH_NZ`	`'en-NZ'`	English (New Zealand)

Asian Languages:

Constant	Value	Description
`AzureSpeechLanguage.JAPANESE_JP`	`'ja-JP'`	Japanese
`AzureSpeechLanguage.KOREAN_KR`	`'ko-KR'`	Korean
`AzureSpeechLanguage.VIETNAMESE_VN`	`'vi-VN'`	Vietnamese
`AzureSpeechLanguage.THAI_TH`	`'th-TH'`	Thai
`AzureSpeechLanguage.INDONESIAN_ID`	`'id-ID'`	Indonesian
`AzureSpeechLanguage.MALAY_MY`	`'ms-MY'`	Malay
`AzureSpeechLanguage.FILIPINO_PH`	`'fil-PH'`	Filipino
`AzureSpeechLanguage.HINDI_IN`	`'hi-IN'`	Hindi
`AzureSpeechLanguage.TAMIL_IN`	`'ta-IN'`	Tamil
`AzureSpeechLanguage.TELUGU_IN`	`'te-IN'`	Telugu

European Languages:

Constant	Value	Description
`AzureSpeechLanguage.GERMAN_DE`	`'de-DE'`	German
`AzureSpeechLanguage.FRENCH_FR`	`'fr-FR'`	French
`AzureSpeechLanguage.SPANISH_ES`	`'es-ES'`	Spanish (Spain)
`AzureSpeechLanguage.SPANISH_MX`	`'es-MX'`	Spanish (Mexico)
`AzureSpeechLanguage.ITALIAN_IT`	`'it-IT'`	Italian
`AzureSpeechLanguage.PORTUGUESE_BR`	`'pt-BR'`	Portuguese (Brazil)
`AzureSpeechLanguage.PORTUGUESE_PT`	`'pt-PT'`	Portuguese (Portugal)
`AzureSpeechLanguage.RUSSIAN_RU`	`'ru-RU'`	Russian
`AzureSpeechLanguage.DUTCH_NL`	`'nl-NL'`	Dutch
`AzureSpeechLanguage.POLISH_PL`	`'pl-PL'`	Polish
`AzureSpeechLanguage.SWEDISH_SE`	`'sv-SE'`	Swedish
`AzureSpeechLanguage.NORWEGIAN_NO`	`'nb-NO'`	Norwegian
`AzureSpeechLanguage.DANISH_DK`	`'da-DK'`	Danish
`AzureSpeechLanguage.FINNISH_FI`	`'fi-FI'`	Finnish

Middle Eastern Languages:

Constant	Value	Description
`AzureSpeechLanguage.ARABIC_SA`	`'ar-SA'`	Arabic (Saudi Arabia)
`AzureSpeechLanguage.ARABIC_AE`	`'ar-AE'`	Arabic (UAE)
`AzureSpeechLanguage.TURKISH_TR`	`'tr-TR'`	Turkish
`AzureSpeechLanguage.HEBREW_IL`	`'he-IL'`	Hebrew

Helper Functions

import {
    isValidAzureRegion,
    isValidAzureLanguage,
    getRegionDisplayName,
    getLanguageDisplayName
} from '@bdky/aaas-pilot-kit';

// Validate if region is valid
isValidAzureRegion('eastasia'); // true
isValidAzureRegion('invalid'); // false

// Validate if language is valid
isValidAzureLanguage('zh-CN'); // true
isValidAzureLanguage('invalid'); // false

// Get region display name
getRegionDisplayName('eastasia'); // '东亚（香港）'

// Get language display name
getLanguageDisplayName('zh-CN'); // '简体中文（中国大陆）'

Initialization Methods

`createAaaSPilotKit(options: IOptions): IAaaSPilotKitController`

Creates an AaaS Pilot Kit controller instance.

import {createAaaSPilotKit} from '@bdky/aaas-pilot-kit';

const controller = createAaaSPilotKit({
    token: 'your-auth-token-here',
    figureId: '209337',
    ttsPer: 'LITE_audiobook_female_1',
    // agentConfig: Required if custom agentService is not provided
    agentConfig: {
        token: 'xxxx',
        robotId: 'xxxx'
    }
});

Instance Methods (IAaaSPilotKitController)

`mount($container?: HTMLElement): Promise<void>`

🧩 Mount the Digital Employee to the specified DOM container.

Behavior:

If $container is provided → mount directly
If not provided → call opts.getMountContainer()
If neither is available → throw error ❌

Async: Wait for resource loading/container initialization to complete, and obtain Microphone permission at the same time.

Parameters:

$container - Optional, the DOM node to mount to

Throws: If $container is not provided and opts.getMountContainer is undefined

// Mount directly to specified container
await controller.mount(document.getElementById('avatar-container'));

// Or call without parameters, use getMountContainer from configuration
await controller.mount();

`getOptions(): Required<IOptions>`

📋 Get the complete configuration currently in effect (including default values).

Used for debugging, logging, and dynamic configuration comparison.

Returns: Complete configuration object after merging with default values

const currentOptions = controller.getOptions();
console.log('Current configuration:', currentOptions);

`playFromFullText(fullText: string): IAaaSPilotKitController`

🎬 [Non-streaming] Full text-driven playback - Suitable for pre-generated replies, announcement broadcasts.

Behavior:

Immediately start TTS synthesis + digital avatar playback
Supports interruption (if interruptible=true)

Parameters:

fullText - The complete text to be played

Returns: this (supports chaining)

controller.playFromFullText('Welcome to AaaS Pilot Kit Digital Employee service!');

`playFromStreamText(chunk: string): IAaaSPilotKitController`

🌊 [Streaming] Chunked text-driven playback - Suitable for LLM streaming output, real-time conversations.

Behavior:

Each time a text chunk is passed, it's appended in real-time and played
Supports "first sentence splitting" strategy (see opts.minSplitLen)
Supports interruption (if interruptible=true)

Example: Use with SSE/WebSocket streaming to receive Agent replies

Parameters:

chunk - New text fragment

Returns: this (supports chaining)

// Simulate streaming text
controller.playFromStreamText('Today');
controller.playFromStreamText('weather');
controller.playFromStreamText('is good.');

`playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>`

⏳ Wait for current playback to complete before playing new content (queuing mode).

Used for scenarios like inserting "important announcements".

Behavior:

If currently playing → wait for playback to finish before playing new content
If not playing → play immediately
Does not trigger interruption logic (even if interruptible=true)
Can dynamically cancel queuing through shouldStillPlay

Parameters:

text - Text to be played
shouldStillPlay - Optional, check before playing whether playback is still needed (return false to cancel)

Returns: Promise<boolean> → true=played, false=cancelled

const played = await controller.playWaitFor('System notification: Maintenance will be performed shortly');
if (played) {
    console.log('Notification played');
}

`mute(muted: boolean): IAaaSPilotKitController`

🔇 Mute control - Takes effect immediately, does not affect playback queue.

Behavior:

muted=true → Stop audio output (visual lip-sync still synchronized)
muted=false → Restore audio
Triggers emitter 'mute' event

Parameters:

muted - Whether to mute

Returns: this (supports chaining)

// Mute
controller.mute(true);

// Unmute
controller.mute(false);

`interrupt(reason?: string): IAaaSPilotKitController`

🛑 Manually interrupt current conversation flow.

Behavior:

Stop audio capture
Cancel Agent request
Interrupt digital avatar playback
Trigger 'interrupt' event

Usually triggered by user clicking "interrupt button" or voice activation.

Parameters:

reason - Optional, reason for interruption (for logging/analytics)

Returns: this (supports chaining)

// User clicks interrupt button
controller.interrupt('User manual interruption');

`dispose(): IAaaSPilotKitController`

🗑️ Destroy instance - Release all resources (RTC, audio, rendering, event listeners).

⚠️ After calling, this instance can no longer be used! You must call createAaaSPilotKit again to create a new one.

Returns: this (supports chaining, but method calls after this will error)

// Clean up resources when component unmounts
controller.dispose();

`input(text: string): IAaaSPilotKitController`

💬 Manual text input (simulating user voice input) → triggers complete conversation flow.

Behavior:

Skip ASR, send text directly to Agent
Subsequent flow is identical to voice input (Agent → TTS → Playback)

Use cases: Debugging, accessibility input, chat box integration

Parameters:

text - User input text

Returns: this (supports chaining)

// Simulate user input
controller.input('I want to learn about product features');

`setInterruptible(interruptible: boolean): IAaaSPilotKitController`

🔄 Dynamically toggle "allow interruption" - Can be adjusted at any time during conversation, takes effect immediately.

Parameters:

interruptible - Whether to allow interruption

Returns: this (supports chaining)

// Disable interruption during important announcement
controller.setInterruptible(false);
controller.playFromFullText('Important notice: System will undergo maintenance in 5 minutes');

// Restore interruption function after announcement
controller.setInterruptible(true);

`setLocale(locale: string): IAaaSPilotKitController`

🌐 Dynamically switch SDK interface language (v1.1.2+) - Switch language at runtime, takes effect immediately.

Behavior:

Switch language of SDK internal message texts (such as error prompts, status messages, etc.)
Automatically clear compilation cache to ensure new language takes effect immediately
Affects all components using i18n

Parameters:

locale - Target language code (such as 'en', 'ja', 'ko')

Returns: this (supports chaining)

// Switch to English
controller.setLocale('en');

// Chaining
controller.setLocale('ja').playFromFullText('こんにちは');

Detailed usage: See Internationalization (i18n)

`getLocale(): string`

🌐 Get current SDK interface language (v1.1.2+)

Returns: Current language code

const currentLocale = controller.getLocale(); // 'zh'

Detailed usage: See Internationalization (i18n)

`checkNeedsManualActivation(): boolean`

🚦 Check if "manual activation" is needed (such as browser policy blocking autoplay).

When returning true, must call activateManually() after user interaction to play audio.

Common on mobile/muted browsers for first playback.

Returns: boolean - whether manual activation is needed

if (controller.checkNeedsManualActivation()) {
    showActivationButton();
}

`activateManually(): Promise<void>`

✅ Manually activate audio context (resolve browser autoplay policy restrictions).

🔹 Must be called in user gesture event (click/touch)!

For example: call when user clicks "Start Conversation" button.

Async: Wait for Digital Employee avatar video stream and audio stream context to restore successfully.

Throws: May fail to activate if not called in user gesture

// Activate in user click event
activateButton.onclick = async () => {
    try {
        await controller.activateManually();
        hideActivationButton();
        console.log('Audio activated');
    } catch (error) {
        console.error('Activation failed:', error);
    }
};

`checkAudioDevice(): Promise<void>`

🎙️ Check microphone device availability - Perform 4-level progressive detection (API support → HTTPS → device enumeration → permission → stream acquisition).

Method signature: async checkAudioDevice(): Promise<void>

Return value:

Returns Promise<void>
Detection results are sent via microphone_available event

Usage scenarios:

Proactively check device status before user clicks "Start Conversation"
Diagnose after ASR startup fails
Periodically check device connection status (e.g., when user plugs/unplugs headphones)

Detection levels:

API support detection - Check if browser supports MediaDevices API
HTTPS detection - Check if in secure context (HTTPS or localhost)
Device enumeration - Check if audio input devices can be listed
Permission detection - Check if user granted microphone permission
Stream acquisition - Check if audio stream can be successfully obtained

Performance tips:

First detection takes ~100-500ms (mainly getUserMedia)
Results cached for 5 seconds, repeated calls <1ms (avoid frequent permission popups)

Example code:

// Basic usage: listen to detection results
controller.emitter.on('microphone_available', (result) => {
  if (!result.available) {
    // Show friendly error message
    alert(result.userMessage);
  } else {
    console.log('Device normal, found', result.devices?.length, 'microphones');
  }
});

// Execute detection
await controller.checkAudioDevice();

// Proactively check before "Start Conversation"
startButton.onclick = async () => {
  // Check device first
  await controller.checkAudioDevice();

  // microphone_available event will trigger here
  // If device unavailable, event listener will show error message
};

// Listen to detection results
controller.emitter.on('microphone_available', (result) => {
  if (result.available) {
    // Device available, allow continuing operation
    enableVoiceButton();
  } else {
    // Device unavailable, disable voice function
    disableVoiceButton();
    showToast(result.userMessage);
  }
});

// Advanced usage: provide specific solutions based on error type
controller.emitter.on('microphone_available', (result) => {
  if (!result.available) {
    switch (result.error) {
      case 'PERMISSION_DENIED':
        showPermissionGuide();
        break;
      case 'HTTPS_REQUIRED':
        showHTTPSWarning();
        break;
      case 'DEVICE_NOT_READABLE':
        showDeviceBusyWarning();
        break;
      default:
        alert(result.userMessage);
    }
  }
});

await controller.checkAudioDevice();

Error type description: See FAQ - Error Code Table error codes 3100-3105

Related events: microphone_available - Receive detection results

Related configuration: checkAudioDeviceBeforeStart - Auto-detect before ASR starts

`keepAlive(): IAaaSPilotKitController`

🕰️ Reset session timeout timer - "I'm still using it, don't exit!"

Behavior:

Restart counting opts.timeoutSec from 0
Delay triggering timeout event (inactivity)

Use cases: Call when user is browsing page, typing, filling forms

Returns: this (supports chaining)

// Keep session alive when user has activity
document.addEventListener('mousedown', () => {
    controller.keepAlive();
});

document.addEventListener('keydown', () => {
    controller.keepAlive();
});

Chaining Example

// Support chaining
controller
    .setInterruptible(false)
    .playFromFullText('Welcome to our service')
    .keepAlive();

Exception Handling

try {
    await controller.mount(containerElement);
    controller.playFromFullText('Initialization successful');
}
catch (e) {
    console.error('Initialization failed:', e);
    // Handle error
}

Constant Exports​

Azure Region Constants (AzureSpeechRegion)​

Azure Language Constants (AzureSpeechLanguage)​

Helper Functions​

Initialization Methods​

createAaaSPilotKit(options: IOptions): IAaaSPilotKitController​

Instance Methods (IAaaSPilotKitController)​

mount($container?: HTMLElement): Promise<void>​

getOptions(): Required<IOptions>​

playFromFullText(fullText: string): IAaaSPilotKitController​

playFromStreamText(chunk: string): IAaaSPilotKitController​

playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>​

mute(muted: boolean): IAaaSPilotKitController​

interrupt(reason?: string): IAaaSPilotKitController​

dispose(): IAaaSPilotKitController​

input(text: string): IAaaSPilotKitController​

setInterruptible(interruptible: boolean): IAaaSPilotKitController​

setLocale(locale: string): IAaaSPilotKitController​

getLocale(): string​

checkNeedsManualActivation(): boolean​

activateManually(): Promise<void>​

checkAudioDevice(): Promise<void>​

keepAlive(): IAaaSPilotKitController​

Chaining Example​

Exception Handling​

Constant Exports

Azure Region Constants (AzureSpeechRegion)

Azure Language Constants (AzureSpeechLanguage)

Helper Functions

Initialization Methods

`createAaaSPilotKit(options: IOptions): IAaaSPilotKitController`

Instance Methods (IAaaSPilotKitController)

`mount($container?: HTMLElement): Promise<void>`

`getOptions(): Required<IOptions>`

`playFromFullText(fullText: string): IAaaSPilotKitController`

`playFromStreamText(chunk: string): IAaaSPilotKitController`

`playWaitFor(text: string, shouldStillPlay?: () => boolean): Promise<boolean>`

`mute(muted: boolean): IAaaSPilotKitController`

`interrupt(reason?: string): IAaaSPilotKitController`

`dispose(): IAaaSPilotKitController`

`input(text: string): IAaaSPilotKitController`

`setInterruptible(interruptible: boolean): IAaaSPilotKitController`

`setLocale(locale: string): IAaaSPilotKitController`

`getLocale(): string`

`checkNeedsManualActivation(): boolean`

`activateManually(): Promise<void>`

`checkAudioDevice(): Promise<void>`

`keepAlive(): IAaaSPilotKitController`

Chaining Example

Exception Handling