Skip to main content

AIChat

The AIChat module provides comprehensive AI device management and interaction capabilities, including device status monitoring, equalizer and noise reduction control, low latency mode configuration, device finding functionality, and AI chat session management with support for both text and voice communication channels.

Prerequisites

  • AI-capable device must be connected and paired with the iOS application
  • Device must support AI chat functionality (verify with isAIDeviceAPISupported)
  • Bluetooth connection must be active and stable
  • Appropriate permissions for audio input/output must be granted by the user
  • For voice wake-up features, device must support on-device wake-up capability

Data Models

TSAIDeviceBatteryInfoModel

Battery information for AI device.

PropertyTypeDescription
batteryLevelNSIntegerBattery level from 0 to 100 representing the charge percentage
isChargingBOOLIndicates whether the device is currently charging

TSAIDeviceStatusInfoModel

Current status information for the AI device.

PropertyTypeDescription
leftConnectionStatusTSAIDeviceConnectionStatusConnection status of the left device
rightConnectionStatusTSAIDeviceConnectionStatusConnection status of the right device
leftInCaseStatusTSAIDeviceInCaseStatusIn-case status of the left device
rightInCaseStatusTSAIDeviceInCaseStatusIn-case status of the right device
leftBatteryInfoTSAIDeviceBatteryInfoModel *Battery information for the left device
rightBatteryInfoTSAIDeviceBatteryInfoModel *Battery information for the right device

TSAIDeviceFindStatusInfoModel

Find status information for the AI device.

PropertyTypeDescription
leftFindStatusTSAIDeviceFindStatusFind status of the left device
rightFindStatusTSAIDeviceFindStatusFind status of the right device

Enumerations

TSAIChatStatusType

AI chat status types during conversation.

ValueDescription
TSAIChatStatusTypeEnterChatGPTEnter AI chat session
TSAIChatStatusTypeStartRecordingStart recording audio input
TSAIChatStatusTypeEndRecordingEnd recording audio input
TSAIChatStatusTypeExitChatGPTExit AI chat session
TSAIChatStatusTypeReminderOpenAppReminder to open app
TSAIChatStatusTypeIdentificationFailedSpeech recognition failed
TSAIChatStatusTypeIdentificationSuccessfulSpeech recognition successful
TSAIChatStatusTypeConfirmContentConfirm recognized content
TSAIChatStatusTypeStartAnswerStart generating answer
TSAIChatStatusTypeAnswerCompletedAnswer generation completed
TSAIChatStatusTypeAnsweringCurrently generating answer
TSAIChatStatusTypeAbnormalNoNetWorkError: no network connection
TSAIChatStatusTypeAbnormalSensitiveWordError: sensitive word detected
TSAIChatStatusTypeAbnormalCustomError: custom error

TSAIDevicePresetEQ

Preset equalizer settings for the device.

ValueDescription
TSAIDevicePresetEQUnknownUnknown or unset equalizer
TSAIDevicePresetEQSoundEffect1Sound Effect 1 preset
TSAIDevicePresetEQSoundEffect2Sound Effect 2 preset
TSAIDevicePresetEQSoundEffect3Sound Effect 3 preset
TSAIDevicePresetEQSoundEffect4Sound Effect 4 preset
TSAIDevicePresetEQSoundEffect5Sound Effect 5 preset
TSAIDevicePresetEQSoundEffect6Sound Effect 6 preset

TSAIDeviceNoiseReductionMode

Noise reduction mode settings.

ValueDescription
TSAIDeviceNoiseReductionModeUnknownUnknown noise reduction mode
TSAIDeviceNoiseReductionModeOffNoise reduction off
TSAIDeviceNoiseReductionModeOnNoise reduction on
TSAIDeviceNoiseReductionModeTransparencyTransparency mode (hear ambient sound)

TSAIDeviceLowLatencyMode

Low latency mode settings.

ValueDescription
TSAIDeviceLowLatencyModeUnknownUnknown low latency mode
TSAIDeviceLowLatencyModeOffLow latency mode off
TSAIDeviceLowLatencyModeOnLow latency mode on

TSAIDeviceConnectionStatus

Device connection status.

ValueDescription
TSAIDeviceConnectionStatusUnknownUnknown connection status
TSAIDeviceConnectionStatusDisconnectedDevice is disconnected
TSAIDeviceConnectionStatusConnectedDevice is connected

TSAIDeviceInCaseStatus

Device in-case status.

ValueDescription
TSAIDeviceInCaseStatusUnknownUnknown in-case status
TSAIDeviceInCaseStatusOutDevice is out of case
TSAIDeviceInCaseStatusInDevice is in case

TSAIDeviceFindStatus

Device find status.

ValueDescription
TSAIDeviceFindStatusUnknownUnknown find status
TSAIDeviceFindStatusNotFindingDevice is not in finding mode
TSAIDeviceFindStatusFindingDevice is currently finding (emitting sound)

TSAIDeviceFindEvent

Events related to device finding.

ValueDescription
TSAIDeviceFindEventUnknownUnknown find event
TSAIDeviceFindEventFindLeftStart finding left device
TSAIDeviceFindEventFindRightStart finding right device
TSAIDeviceFindEventStopFindLeftStop finding left device
TSAIDeviceFindEventStopFindRightStop finding right device

TSAIDeviceSide

Device side selection.

ValueDescription
TSAIDeviceSideLeftLeft device/earbud
TSAIDeviceSideRightRight device/earbud

TSAIDeviceChatSessionEvent

AI chat session events requested by device.

ValueDescription
TSAIDeviceChatSessionEventUnknownUnknown chat session event
TSAIDeviceChatSessionEventTerminateTerminate current AI chat session
TSAIDeviceChatSessionEventInitiateWithSCOInitiate new session via SCO channel
TSAIDeviceChatSessionEventInitiateWithOpusInitiate new session via Opus encoding

TSAIChatAudioChannel

Audio channel type used for AI chat communication.

ValueDescription
TSAIChatAudioChannelUnknownUnknown or unavailable audio channel
TSAIChatAudioChannelScoSCO (Synchronous Connection-Oriented) channel
TSAIChatAudioChannelOpusInA2dpOutOpus encoded input with A2DP output
TSAIChatAudioChannelOpusInOpusOutOpus encoded input and output

TSAIEnableState

Enable/disable state.

ValueDescription
TSAIEnableStateUnknownUnknown enable state
TSAIEnableStateOffFeature is disabled
TSAIEnableStateeOnFeature is enabled

Callback Types

TSAIDeviceStatusBlock

typedef void(^TSAIDeviceStatusBlock)(TSAIDeviceStatusInfoModel *latestStatusInfo);

Invoked when device status changes.

ParameterTypeDescription
latestStatusInfoTSAIDeviceStatusInfoModel *Latest device status information model

TSAIDeviceEqualizerBlock

typedef void(^TSAIDeviceEqualizerBlock)(BOOL success, TSAIDevicePresetEQ currentEQ, NSError * _Nullable error);

Invoked when equalizer query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
currentEQTSAIDevicePresetEQCurrent equalizer preset
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceNoiseReductionModeBlock

typedef void(^TSAIDeviceNoiseReductionModeBlock)(BOOL success, TSAIDeviceNoiseReductionMode mode, NSError * _Nullable error);

Invoked when noise reduction mode query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
modeTSAIDeviceNoiseReductionModeCurrent noise reduction mode
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceLowLatencyModeBlock

typedef void(^TSAIDeviceLowLatencyModeBlock)(BOOL success, TSAIDeviceLowLatencyMode mode, NSError * _Nullable error);

Invoked when low latency mode query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
modeTSAIDeviceLowLatencyModeCurrent low latency mode
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceStatusInfoBlock

typedef void(^TSAIDeviceStatusInfoBlock)(BOOL success, TSAIDeviceStatusInfoModel * _Nullable statusInfo, NSError * _Nullable error);

Invoked when device status information query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
statusInfoTSAIDeviceStatusInfoModel * _NullableDevice status information model, nil if error
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceFirmwareVersionBlock

typedef void(^TSAIDeviceFirmwareVersionBlock)(BOOL success, NSString * _Nullable version, NSError * _Nullable error);

Invoked when firmware version query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
versionNSString * _NullableFirmware version string, nil if error
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceFindStatusInfoBlock

typedef void(^TSAIDeviceFindStatusInfoBlock)(BOOL success, TSAIDeviceFindStatusInfoModel * _Nullable statusInfo, NSError * _Nullable error);

Invoked when find status information query completes.

ParameterTypeDescription
successBOOLWhether the query succeeded
statusInfoTSAIDeviceFindStatusInfoModel * _NullableDevice find status information model, nil if error
errorNSError * _NullableError object if query failed, nil on success

TSAIDeviceFindEventBlock

typedef void(^TSAIDeviceFindEventBlock)(TSAIDeviceFindEvent findEvent);

Invoked when find status changes.

ParameterTypeDescription
findEventTSAIDeviceFindEventFind event type

API Reference

Check if device supports AI chat

- (BOOL)isAIDeviceAPISupported;
ParameterTypeDescription
ReturnBOOLYES if device supports AI chat, NO otherwise

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
if ([aiManager isAIDeviceAPISupported]) {
TSLog(@"Device supports AI chat");
} else {
TSLog(@"Device does not support AI chat");
}

Query current equalizer preset

- (void)queryAIDeviceEqualizerWithCompletion:(_Nullable TSAIDeviceEqualizerBlock)completion;
ParameterTypeDescription
completionTSAIDeviceEqualizerBlockCallback block invoked with query result

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceEqualizerWithCompletion:^(BOOL success, TSAIDevicePresetEQ currentEQ, NSError * _Nullable error) {
if (success) {
TSLog(@"Current EQ: %ld", (long)currentEQ);
} else {
TSLog(@"Failed to query EQ: %@", error.localizedDescription);
}
}];

Set equalizer preset

- (void)setAIDeviceEqualizer:(TSAIDevicePresetEQ)eq
completion:(_Nullable TSCompletionBlock)completion;
ParameterTypeDescription
eqTSAIDevicePresetEQThe equalizer preset to apply
completionTSCompletionBlockCallback block invoked when operation completes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager setAIDeviceEqualizer:TSAIDevicePresetEQSoundEffect2
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
TSLog(@"EQ set successfully");
} else {
TSLog(@"Failed to set EQ: %@", error.localizedDescription);
}
}];

Register for equalizer change notifications

- (void)registerAIDeviceEqualizerDidChanged:(void(^ _Nullable )(TSAIDevicePresetEQ latestEQ))equalizerBlock;
ParameterTypeDescription
equalizerBlockvoid(^ _Nullable )(TSAIDevicePresetEQ)Callback invoked when device EQ changes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerAIDeviceEqualizerDidChanged:^(TSAIDevicePresetEQ latestEQ) {
TSLog(@"Device EQ changed to: %ld", (long)latestEQ);
}];

Query current noise reduction mode

- (void)queryAIDeviceNoiseReductionModeWithCompletion:(_Nullable TSAIDeviceNoiseReductionModeBlock)completion;
ParameterTypeDescription
completionTSAIDeviceNoiseReductionModeBlockCallback block invoked with query result

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceNoiseReductionModeWithCompletion:^(BOOL success, TSAIDeviceNoiseReductionMode mode, NSError * _Nullable error) {
if (success) {
TSLog(@"Current noise reduction mode: %ld", (long)mode);
} else {
TSLog(@"Failed to query noise reduction mode: %@", error.localizedDescription);
}
}];

Set noise reduction mode

- (void)setAIDeviceNoiseReductionMode:(TSAIDeviceNoiseReductionMode)mode
completion:(_Nullable TSCompletionBlock)completion;
ParameterTypeDescription
modeTSAIDeviceNoiseReductionModeThe noise reduction mode to apply
completionTSCompletionBlockCallback block invoked when operation completes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager setAIDeviceNoiseReductionMode:TSAIDeviceNoiseReductionModeTransparency
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
TSLog(@"Noise reduction mode set successfully");
} else {
TSLog(@"Failed to set noise reduction mode: %@", error.localizedDescription);
}
}];

Register for noise reduction mode change notifications

- (void)registerAIDeviceNoiseReductionModeDidChanged:(void(^ _Nullable )(TSAIDeviceNoiseReductionMode latestMode))noiseReductionModeBlock;
ParameterTypeDescription
noiseReductionModeBlockvoid(^ _Nullable )(TSAIDeviceNoiseReductionMode)Callback invoked when device noise reduction mode changes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerAIDeviceNoiseReductionModeDidChanged:^(TSAIDeviceNoiseReductionMode latestMode) {
TSLog(@"Device noise reduction mode changed to: %ld", (long)latestMode);
}];

Query current low latency mode

- (void)queryAIDeviceLowLatencyModeWithCompletion:(_Nullable TSAIDeviceLowLatencyModeBlock)completion;
ParameterTypeDescription
completionTSAIDeviceLowLatencyModeBlockCallback block invoked with query result

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceLowLatencyModeWithCompletion:^(BOOL success, TSAIDeviceLowLatencyMode mode, NSError * _Nullable error) {
if (success) {
TSLog(@"Current low latency mode: %ld", (long)mode);
} else {
TSLog(@"Failed to query low latency mode: %@", error.localizedDescription);
}
}];

Set low latency mode

- (void)setAIDeviceLowLatencyMode:(TSAIDeviceLowLatencyMode)mode
completion:(_Nullable TSCompletionBlock)completion;
ParameterTypeDescription
modeTSAIDeviceLowLatencyModeThe low latency mode to apply
completionTSCompletionBlockCallback block invoked when operation completes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager setAIDeviceLowLatencyMode:TSAIDeviceLowLatencyModeOn
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
TSLog(@"Low latency mode enabled");
} else {
TSLog(@"Failed to set low latency mode: %@", error.localizedDescription);
}
}];

Register for low latency mode change notifications

- (void)registerAIDeviceLowLatencyModeDidChanged:(void(^ _Nullable)(TSAIDeviceLowLatencyMode latestMode))lowLatencyModeBlock;
ParameterTypeDescription
lowLatencyModeBlockvoid(^ _Nullable)(TSAIDeviceLowLatencyMode)Callback invoked when device low latency mode changes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerAIDeviceLowLatencyModeDidChanged:^(TSAIDeviceLowLatencyMode latestMode) {
TSLog(@"Device low latency mode changed to: %ld", (long)latestMode);
}];

Query device status

- (void)queryAIDeviceStatusWithCompletion:(_Nullable TSAIDeviceStatusInfoBlock)completion;
ParameterTypeDescription
completionTSAIDeviceStatusInfoBlockCallback block invoked with device status

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceStatusWithCompletion:^(BOOL success, TSAIDeviceStatusInfoModel * _Nullable statusInfo, NSError * _Nullable error) {
if (success && statusInfo) {
TSLog(@"Left connection: %ld, Right connection: %ld",
(long)statusInfo.leftConnectionStatus,
(long)statusInfo.rightConnectionStatus);
} else {
TSLog(@"Failed to query device status: %@", error.localizedDescription);
}
}];

Register for device status change notifications

- (void)registerAIDeviceStatusDidChanged:(void(^ _Nullable)(TSAIDeviceStatusInfoModel *latestStatusInfo))statusBlock;
ParameterTypeDescription
statusBlockvoid(^ _Nullable)(TSAIDeviceStatusInfoModel *)Callback invoked when device status changes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerAIDeviceStatusDidChanged:^(TSAIDeviceStatusInfoModel *latestStatusInfo) {
if (latestStatusInfo.leftBatteryInfo) {
TSLog(@"Left battery: %ld%%", (long)latestStatusInfo.leftBatteryInfo.batteryLevel);
}
}];

Query firmware version

- (void)queryAIDeviceFirmwareVersionWithCompletion:(_Nullable TSAIDeviceFirmwareVersionBlock)completion;
ParameterTypeDescription
completionTSAIDeviceFirmwareVersionBlockCallback block invoked with firmware version

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceFirmwareVersionWithCompletion:^(BOOL success, NSString * _Nullable version, NSError * _Nullable error) {
if (success && version) {
TSLog(@"Firmware version: %@", version);
} else {
TSLog(@"Failed to query firmware version: %@", error.localizedDescription);
}
}];

Query find status

- (void)queryAIDeviceFindStatusInfoWithCompletion:(_Nullable TSAIDeviceFindStatusInfoBlock)completion;
ParameterTypeDescription
completionTSAIDeviceFindStatusInfoBlockCallback block invoked with find status

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager queryAIDeviceFindStatusInfoWithCompletion:^(BOOL success, TSAIDeviceFindStatusInfoModel * _Nullable statusInfo, NSError * _Nullable error) {
if (success && statusInfo) {
TSLog(@"Left finding: %ld", (long)statusInfo.leftFindStatus);
}
}];

Trigger find device

- (void)findAIDeviceWithSide:(TSAIDeviceSide)side
completion:(_Nullable TSCompletionBlock)completion;
ParameterTypeDescription
sideTSAIDeviceSideThe side to find (Left or Right)
completionTSCompletionBlockCallback block invoked when operation completes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager findAIDeviceWithSide:TSAIDeviceSideLeft
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
TSLog(@"Find initiated for left device");
} else {
TSLog(@"Failed to initiate find: %@", error.localizedDescription);
}
}];

Stop find device

- (void)stopFindAIDeviceWithSide:(TSAIDeviceSide)side
completion:(_Nullable TSCompletionBlock)completion;
ParameterTypeDescription
sideTSAIDeviceSideThe side to stop finding (Left or Right)
completionTSCompletionBlockCallback block invoked when operation completes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager stopFindAIDeviceWithSide:TSAIDeviceSideLeft
completion:^(BOOL success, NSError * _Nullable error) {
if (success) {
TSLog(@"Find stopped for left device");
} else {
TSLog(@"Failed to stop find: %@", error.localizedDescription);
}
}];

Register for find status change notifications

- (void)registerAIDeviceFindStatusDidChanged:(_Nullable TSAIDeviceFindEventBlock)findEventBlock;
ParameterTypeDescription
findEventBlockTSAIDeviceFindEventBlockCallback invoked when find status changes

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerAIDeviceFindStatusDidChanged:^(TSAIDeviceFindEvent findEvent) {
switch (findEvent) {
case TSAIDeviceFindEventFindLeft:
TSLog(@"Finding left device");
break;
case TSAIDeviceFindEventStopFindLeft:
TSLog(@"Stopped finding left device");
break;
default:
break;
}
}];

Register for AI-chat session events

- (void)registerOnAIChatSessionEvent:(void(^_Nullable)(TSAIDeviceChatSessionEvent event))block;
ParameterTypeDescription
blockvoid(^_Nullable)(TSAIDeviceChatSessionEvent)Callback invoked when device requests AI-chat event

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerOnAIChatSessionEvent:^(TSAIDeviceChatSessionEvent event) {
switch (event) {
case TSAIDeviceChatSessionEventInitiateWithSCO:
TSLog(@"Device requests to initiate AI chat via SCO");
break;
case TSAIDeviceChatSessionEventTerminate:
TSLog(@"Device requests to terminate AI chat");
break;
default:
break;
}
}];

Register for delta voice data

- (void)registerOnAIChatDeltaOpusVoiceData:(void(^_Nullable)(NSData * _Nullable deltaOpusVoiceData, NSData * _Nullable deltaVoiceData))block;
ParameterTypeDescription
blockvoid(^_Nullable)(NSData *, NSData *)Callback with Opus and PCM voice data

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerOnAIChatDeltaOpusVoiceData:^(NSData * _Nullable deltaOpusVoiceData, NSData * _Nullable deltaVoiceData) {
if (deltaVoiceData) {
TSLog(@"Received %lu bytes of PCM audio data", (unsigned long)deltaVoiceData.length);
}
}];

Send AI bridge data

- (void)sendAIBridgeData:(NSData *)data;
ParameterTypeDescription
dataNSData *The AI bridge data to send

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
NSData *aiBridgeData = [[NSData alloc] initWithBytes:"AI_DATA" length:7];
[aiManager sendAIBridgeData:aiBridgeData];

Register for received AI bridge data

- (void)registerOnAIBridgeDataReceived:(void(^ _Nullable)(NSData *data))block;
ParameterTypeDescription
blockvoid(^ _Nullable)(NSData *)Callback when AI bridge data is received

Code Example:

id<TSAIManagerInterface> aiManager = [tsDevice getInterface:@protocol(TSAIManagerInterface)];
[aiManager registerOnAIBridgeDataReceived:^(NSData *data) {
TSLog(@"Received AI bridge data: %lu bytes", (unsigned long)data.length);
}];

Send WP auth bridge data

- (void)sendWPAuthBridgeData:(NSData *)data;
ParameterTypeDescription
dataNSData *The WP auth bridge data to send

Code Example:

id<TSAI