Ai Ai Chat

AI Chat

Run an AI voice chat session initiated by a supported device, receive conversational data and intents, and route decoded PCM audio to the active provider session when required.

Use AI Session Events to interpret AIChatEventType and AI Intents to validate recognized actions before executing them.

Device-driven AI chat lifecycle

The device requests an AI chat and declares whether speech will arrive through Opus or an app-side SCO recording. Keep the device and AI session states coordinated until the final report arrives.

1. Receive Device Request — The device requests a new AI chat and specifies SCO or Opus as the speech-input channel.
2. Prepare Requested Audio Input — Use the channel declared by the device: receive Opus packets from the device, or prepare app-side SCO recording.
3. Start AI Chat — Start the provider-backed session with the prepared configuration.
4. Confirm Startup — Retain the session and report start success or failure to an Opus device when required.
5. Capture or Forward Speech — SCO captures the device microphone through the app; Opus is sent by the device, decoded, and appended to the retained session.
6. Consume AI Results — Handle chat data, intents, voice data, VAD, and session events.
7. Deliver Response — Render text and allow configured AI voice playback over the selected output path.
8. Coordinate Stop — Handle device terminate, state conflict, auto-end, explicit stop, or runtime failure.
9. Finish and Release — Consume the final report, clear the retained session, and restore idle UI state.

Prerequisites

• AIBudsAISDK is initialized, device information is configured, and a registered provider is selected and authenticated.
• The provider supports AIChatServiceAPI.
• The device delivers AI chat session events and, for Opus input, conforms to DeviceAIChatAPI.
• Read the requested channel from the device event instead of choosing it independently in the app.

API Reference

Framework

AIBudsAI.xcframework

Import

Swift

import AIBuds
import AIBudsAI
import AIBudsAIFoundation

Objective-C

#import <AIBuds/AIBuds-Swift.h>
#import <AIBudsAI/AIBudsAI-Swift.h>

Declaration

Swift

/// Starts an AI chat session.
/// - Parameters:
///   - config: The chat session configuration.
///   - onStartSuccess: Called with the active session.
///   - onStartFailure: Called when the session cannot start.
///   - onChatData: Called when new conversational data arrives.
///   - onIntent: Called when the provider detects an intent.
///   - onVoiceData: Called when voice data is produced.
///   - onEvent: Called for session-level events.
///   - onError: Called for runtime session errors.
///   - onFinish: Called with the final session report.
static func startAIChat(
    _ config: AIChatSessionConfig = .default,
    onStartSuccess: ((
        AIChatSessionConvertible
    ) -> Void)? = nil,
    onStartFailure: ((
        Error
    ) -> Void)? = nil,
    onChatData: ((
        AIChatDataModel
    ) -> Void)? = nil,
    onIntent: ((
        AIChatIntentModel
    ) -> Void)? = nil,
    onVoiceData: ((
        AIChatVoiceDataModel
    ) -> Void)? = nil,
    onEvent: ((
        AIChatEventModel
    ) -> Void)? = nil,
    onError: ((
        NSError
    ) -> Void)? = nil,
    onFinish: ((
        AIChatSessionReportModel
    ) -> Void)? = nil
)

/// Stops the active AI chat session. This is safe when no session is active.
static func stopAIChat()

Objective-C

/// Starts an AI chat session.
/// - Parameters:
///   - config: The chat session configuration.
///   - onStartSuccess: Called with the active session.
///   - onStartFailure: Called when the session cannot start.
///   - onChatData: Called when new conversational data arrives.
///   - onIntent: Called when the provider detects an intent.
///   - onVoiceData: Called when voice data is produced.
///   - onEvent: Called for session-level events.
///   - onError: Called for runtime session errors.
///   - onFinish: Called with the final session report.
+ (void)startAIChatWithConfig:(AIBudsAIChatSessionConfig *)config
        onStartSuccess:(void (^ _Nullable)(id<AIBudsAIChatSessionConvertible> session))onStartSuccess
        onStartFailure:(void (^ _Nullable)(NSError *error))onStartFailure
        onChatData:(void (^ _Nullable)(AIBudsAIChatDataModel *chatData))onChatData
        onIntent:(void (^ _Nullable)(AIBudsAIChatIntentModel *intent))onIntent
        onVoiceData:(void (^ _Nullable)(AIBudsAIChatVoiceDataModel *voiceData))onVoiceData
        onEvent:(void (^ _Nullable)(AIBudsAIChatEventModel *event))onEvent
        onError:(void (^ _Nullable)(NSError *error))onError
        onFinish:(void (^ _Nullable)(AIBudsAIChatSessionReportModel *report))onFinish;

/// Stops the active AI chat session. This is safe when no session is active.
+ (void)stopAIChat;

See startAIChat and stopAIChat.

Configuration

AIChatSessionConfig exposes the settings used by AIChatSettingsController:

Property	Default	Purpose
languageForSpeechInput	App language	Hyphenated speech-input language supported by the selected provider, for example zh-CN.
audioChannel	.opusInA2dpOut	Audio transport used by this chat session. It must match the device event that starts the session.
allowUserToInterruptAIResponse	true	Whether user input may interrupt an AI response, normally voice playback.
maxPauseDurationBeforeAIResponds	0.8 seconds	Maximum permitted speech pause before the AI responds.
autoEndSessionAfterNoInputDuration	15.0 seconds	Idle duration before the session ends automatically.
enableVoicePlayback	true	Whether generated voice playback is enabled.
shouldSaveVoiceForDebugging	false	Whether diagnostic voice data is retained. Keep disabled in production unless policy explicitly permits it.
additionalOptions	[:]	Provider-specific agent, speaker, plan, prompt, intent, or denoising options.
autoSelectAgentIfNotSpecified	true	Whether the SDK selects an agent when no provider-specific agent is supplied.

Use the public AdditionalOptionKey... constants rather than hard-coded provider option keys.

Configure a Chat Session

The Demo keeps provider selection separate from the session configuration. When the user changes provider, select it first, query its supported languages, and complete app-initiated authentication before starting chat. Agent IDs, speaker IDs, intent codes, usage plans, and initial prompts are issued by the provider and must not be copied from the Demo as universal values.

Swift

let vendor: AIServiceVendor = .starBurst
AIBudsAISDK.setAIServiceVendor(vendor)

let supportedLanguages = AIBudsAISDK.allSupportedLanguages(for: vendor)
let language = supportedLanguages.first?.languageCode

var options: [String: Any] = [:]
if let agentID = providerAgentID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstAgentId] = agentID
}
if let speakerID = providerSpeakerID {
    options[AIChatSessionConfig.AdditionalOptionKeyStarburstSpeakerId] = speakerID
}

let config = AIChatSessionConfig(
    languageForSpeechInput: language,
    audioChannel: .opusInA2dpOut,
    allowUserToInterruptAIResponse: true,
    maxPauseDurationBeforeAIResponds: 0.8,
    autoEndSessionAfterNoInputDuration: 15,
    enableVoicePlayback: true,
    shouldSaveVoiceForDebugging: false,
    additionalOptions: options
)
config.autoSelectAgentIfNotSpecified = providerAgentID == nil

Objective-C

AIBudsAIServiceVendor vendor = AIBudsAIServiceVendorStarBurst;
[AIBudsAISDK setAIServiceVendor:vendor];

NSArray<AIBudsAIServiceLanguage *> *supportedLanguages =
    [AIBudsAISDK allSupportedLanguagesForVendor:vendor];
NSString *language = supportedLanguages.firstObject.languageCode;

NSMutableDictionary<NSString *, id> *options = [NSMutableDictionary dictionary];
if (self.providerAgentID.length > 0) {
    options[AIBudsAIChatSessionConfig.AdditionalOptionKeyStarburstAgentId] =
        self.providerAgentID;
}
if (self.providerSpeakerID.length > 0) {
    options[AIBudsAIChatSessionConfig.AdditionalOptionKeyStarburstSpeakerId] =
        self.providerSpeakerID;
}

AIBudsAIChatSessionConfig *config =
    [[AIBudsAIChatSessionConfig alloc]
        initWithLanguageForSpeechInput:language
        audioChannel:AIBudsAIChatAudioChannelOpusInA2dpOut
        allowUserToInterruptAIResponse:YES
        maxPauseDurationBeforeAIResponds:0.8
        autoEndSessionAfterNoInputDuration:15.0
        enableVoicePlayback:YES
        shouldSaveVoiceForDebugging:NO
        additionalOptions:options];
config.autoSelectAgentIfNotSpecified = self.providerAgentID.length == 0;

For .mltcloud, use the corresponding AdditionalOptionKeyMltCloud... constants. Only set a StarBurst usage plan or provider-specific identifier when your provider configuration supplies a valid value.

Usage Examples

The device normally initiates a chat with .initiateWithSCO or .initiateWithOpus. Copy that requested channel into the session configuration before starting AI chat. For Opus, forward the decoded PCM received from the device. For SCO, starting the .sco session establishes app-side SCO recording for the device microphone.

Swift

let config = AIChatSessionConfig.default
config.audioChannel = .opusInA2dpOut
config.languageForSpeechInput = "en-US"

AIBudsAISDK.startAIChat(
    config,
    onStartSuccess: { session in
        currentSession = session
    },
    onStartFailure: { error in
        print("Chat start failed: \(error)")
    },
    onChatData: { chatData in
        conversation.append(chatData)
    },
    onIntent: { intent in
        handle(intent)
    },
    onVoiceData: { voiceData in
        handle(voiceData)
    },
    onEvent: { event in
        handle(event)
    },
    onError: { error in
        print(error.localizedDescription)
    },
    onFinish: { report in
        currentSession = nil
        save(report)
    }
)

When the device supplies decoded 16-bit PCM for an Opus chat session, forward it to the retained session:

currentSession?.appendInt16PCM?(decodedPCMData)

Objective-C

AIBudsAIChatSessionConfig *config = [AIBudsAIChatSessionConfig defaultConfig];
config.audioChannel = AIBudsAIChatAudioChannelOpusInA2dpOut;
config.languageForSpeechInput = @"en-US";

[AIBudsAISDK startAIChatWithConfig:config
    onStartSuccess:^(id<AIBudsAIChatSessionConvertible> session) {
        self.currentSession = session;
    }
    onStartFailure:^(NSError *error) {
        NSLog(@"Chat start failed: %@", error);
    }
    onChatData:^(AIBudsAIChatDataModel *chatData) {
        [self recordChatData:chatData];
    }
    onIntent:^(AIBudsAIChatIntentModel *intent) {
        [self handleIntent:intent];
    }
    onVoiceData:^(AIBudsAIChatVoiceDataModel *voiceData) {
        [self handleVoiceData:voiceData];
    }
    onEvent:^(AIBudsAIChatEventModel *event) {
        [self handleEvent:event];
    }
    onError:^(NSError *error) {
        NSLog(@"%@", error.localizedDescription);
    }
    onFinish:^(AIBudsAIChatSessionReportModel *report) {
        self.currentSession = nil;
        [self saveReport:report];
    }];

Forward decoded PCM when required:

[self.currentSession appendInt16PCM:decodedPCMData];

Stop the Session

When the device requests termination, report the stopped state through DeviceAIChatAPI when required by the device flow, then call:

Swift

AIBudsAISDK.stopAIChat()
currentSession = nil

Objective-C

[AIBudsAISDK stopAIChat];
self.currentSession = nil;

Notes

• This is an audio-session API, not a text sendMessage / message-history API.
• Retain AIChatSessionConvertible until onFinish, an unrecoverable error, or explicit stop.
• For SCO sessions, the AIBuds AI SDK records the device microphone through the app's SCO link. For Opus sessions, the device sends Opus to the app; forward the decoded PCM through appendInt16PCM(_:).
• Avoid enabling shouldSaveVoiceForDebugging in production unless your privacy and retention policies explicitly allow it.