Copilot SDK API Reference

1. Integration Guide

1.1 Requirements

• iOS 11.0+
• Xcode 12.0+
• Tuya SDK >= 4.9.0

1.2 Quick Integration

Pod Configuration

pod 'SSCopilotSDK', :podspec => 'https://images.tuyacn.com/smart/app/package/developer/sdk/1739346083/SSCopilotSDK.podspec.json'

1.3 Initialization Process

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 1. Initialize Tuya SDK
    [[ThingSmartSDK sharedInstance] startWithAppKey:<#AppKey#> secretKey:<#SecretKey#>];

    // 2. Configure CopilotSDK environment (optional)
    [[CBCopilots shared] setupWithBaseURL:<#URL#>]; // Base URL
    [[CBCopilots shared] setupWithH5BaseURL:<#URL#>]; // H5 Base URL

    return YES;
}

2. Core APIs

2.1 System Configuration

2.1.1 Query AI Capability Entry Configuration

Method Name getAICapabilityConfig

Parameters

• success: Success callback
• failure: Failure callback

Return Value

• entranceType: Icon entrance display mode (0:bottom 1:top 2:both bottom and top)
• titleDefCopilotId: Default copilot ID
• titleDefCopilotVersion: Default copilot version
• type: Configuration type (0:general service 1:product service)

Example

[[CBCopilots shared] getAICapabilityConfigWithSuccess:^(NSDictionary *config) {
    NSInteger entranceType = [config[@"entranceType"] integerValue];
    NSString *defaultCopilotId = config[@"titleDefCopilotId"];
    NSString *defaultVersion = config[@"titleDefCopilotVersion"];
    NSInteger type = [config[@"type"] integerValue];
} failure:^(NSError *error) {
    // Handle error
}];

2.2 Copilot Management

2.2.1 Query Copilot List Content and Style

Method Name getCopilotList

Parameters

• homeId: Home ID
• success: Success callback, returns copilots array
• failure: Failure callback

Return Value Copilots array elements structure:

• copilotId: Copilot unique identifier
• copilotVersion: Version number
• copilotname: Name
• copilotDescription: Description
• iconURL: Icon URL
• status: Status
• subsribeStatus: Subscription status (0:subscribed, 1:unsubscribed)
• aiType: AI type
• uiType: UI type
• voiceInput: Whether voice input is supported
• voicePlayback: Whether voice playback is supported

Example

[[CBCopilots shared] getCopilotListWithHomeId:@"homeId" 
                                     success:^(NSArray *copilots) {
    // Handle copilot list
} failure:^(NSError *error) {
    // Handle error
}];

2.2.2 Query Copilot Details

Method Name getCopilotDetail

Parameters

• copilotId: Copilot ID
• version: Version number
• homeId: Home ID
• type: Type
• success: Success callback
• failure: Failure callback

Return Value Returns structure same as list item:

• copilotId: Copilot unique identifier
• copilotVersion: Version number
• copilotname: Name
• copilotDescription: Description
• iconURL: Icon URL
• status: Status
• subsribeStatus: Subscription status (0:subscribed, 1:unsubscribed)
• aiType: AI type
• uiType: UI type
• voiceInput: Whether voice input is supported
• voicePlayback: Whether voice playback is supported

Example

[[CBCopilots shared] getCopilotDetailWithId:@"copilotId"
                                   version:@"1.0"
                                   homeId:@"homeId"
                                     type:@"general"
                                  success:^(NSDictionary *detail) {
    // Handle copilot details
} failure:^(NSError *error) {
    // Handle error
}];

2.2.3 Query Copilot Usage History List

Method Name getCopilotHistory

Parameters

• homeId: Home ID
• success: Success callback
• failure: Failure callback

Return Value History array elements structure:

• copilotId: Copilot ID
• copilotVersion: Version number
• lastUseTime: Last use time (timestamp in seconds)
• useCount: Usage count

Example

[[CBCopilots shared] getCopilotHistoryWithHomeId:@"homeId"
                                        success:^(NSArray *history) {
    // Handle history records
} failure:^(NSError *error) {
    // Handle error
}];

2.3 Subscription Management

2.3.1 Subscribe to Specified Copilot

Method Name subscribeCopilot

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• copilotSrc: Source identifier
• success: Success callback
• failure: Failure callback

Return Value

• subscribeId: Subscription ID
• status: Subscription status
• createTime: Creation time

Example

[[CBCopilots shared] subscribeCopilotWithId:@"copilotId"
                                   version:@"1.0"
                                    homeId:@"homeId"
                                copilotSrc:@"ai_service"
                                   success:^(NSDictionary *result) {
    NSString *subscribeId = result[@"subscribeId"];
    NSString *status = result[@"status"];
    NSNumber *createTime = result[@"createTime"];
} failure:^(NSError *error) {
    // Handle error
}];

2.3.2 Query Copilot Subscription Status

Method Name getCopilotSubscriptionStatus

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• copilotSrc: Source identifier
• homeId: Home ID
• success: Success callback
• failure: Failure callback

Return Value

• createTime: Creation time
• status: Subscription status (subscribed/none)
• copilotId: Copilot ID
• copilotVersion: Version
• copilotSrc: Source

Example

[[CBCopilots shared] getSubscriptionStatusWithCopilotId:@"copilotId"
                                              version:@"1.0"
                                           copilotSrc:@"ai_service"
                                              homeId:@"homeId"
                                             success:^(NSDictionary *status) {
    NSString *subStatus = status[@"status"];
    NSNumber *createTime = status[@"createTime"];
} failure:^(NSError *error) {
    // Handle error
}];

2.3.3 Batch Query Copilot Subscription Status

Method Name batchGetSubscriptionStatus

Parameters

• copilots: Copilot information array, each element contains:
  • copilotId: Copilot ID
  • copilotVersion: Version number
  • copilotSrc: Source identifier
• homeId: Home ID
• success: Success callback
• failure: Failure callback

Return Value

• data: Subscription status array, each element structure same as single subscription status query

Example

NSArray *copilots = @[
    @{
        @"copilotId": @"xxx",
        @"copilotVersion": @"1.0",
        @"copilotSrc": @"ai_service"
    }
];

[[CBCopilots shared] batchGetSubscriptionStatusWithCopilots:copilots
                                                   homeId:@"homeId"
                                                  success:^(NSDictionary *result) {
    NSArray *statusList = result[@"data"];
} failure:^(NSError *error) {
    // Handle error
}];

2.4 Product Management

2.4.1 Query Product List Content and Style

Method Name getProductList

Parameters

• homeId: Home ID
• success: Success callback
• failure: Failure callback

Return Value

• normalProducts: Regular product list
• choiceProducts: Featured product list Each product contains:
• productId: Product ID
• productName: Product name
• productType: Product type
• productDescription: Product description
• iconURL: Icon URL
• promotionStatus: Promotion status (0:no promotion, 1:has promotion)
• promotionDescription: Promotion description
• serviceStatus: Service status
• orderNo: Order number

Example

[[CBCopilots shared] getProductListWithHomeId:@"homeId"
                                     success:^(NSDictionary *result) {
    NSArray *normalProducts = result[@"normalProducts"];
    NSArray *choiceProducts = result[@"choiceProducts"];
} failure:^(NSError *error) {
    // Handle error
}];

2.4.2 Query Purchased Product List

Method Name getPurchasedProductList

Parameters

• homeId: Home ID
• pageNo: Page number
• pageSize: Items per page
• success: Success callback
• failure: Failure callback

Return Value

• total: Total count
• data: Product list, structure same as product list

Example

[[CBCopilots shared] getPurchasedProductListWithHomeId:@"homeId"
                                               pageNo:1
                                             pageSize:20
                                             success:^(NSDictionary *result) {
    NSInteger total = [result[@"total"] integerValue];
    NSArray *products = result[@"data"];
} failure:^(NSError *error) {
    // Handle error
}];

2.4.3 Query Product Order List

Method Name getProductOrderList

Parameters

• homeId: Home ID
• pageNo: Page number
• pageSize: Items per page
• success: Success callback
• failure: Failure callback

Return Value

• total: Total count
• data: Order list, each order contains:
  • orderNo: Order number
  • orderName: Order name
  • createTime: Creation time
  • expiredTime: Expiration time
  • deviceId: Device ID
  • payType: Payment method
  • currencySymbol: Currency symbol
  • payAmount: Payment amount
  • productName: Product name
  • payOptionType: Payment option type

Example

[[CBCopilots shared] getProductOrderListWithHomeId:@"homeId"
                                           pageNo:1
                                         pageSize:20
                                         success:^(NSDictionary *result) {
    NSInteger total = [result[@"total"] integerValue];
    NSArray *orders = result[@"data"];
} failure:^(NSError *error) {
    // Handle error
}];

2.5 Intelligent Chat (General Chat)

2.5.1 Send Message and Get AI Reply

Method Name sendMessage

Parameters

• message: Message content to send
• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• type: Message type
• success: Success callback
• failure: Failure callback

Return Value

• answer: AI reply message content
• presetQuestions: Preset question list

Example

[[CBCopilotChat shared] sendMessage:@"Hello"
                         copilotId:@"copilotId"
                          version:@"1.0"
                           homeId:@"homeId"
                             type:@"general"
                          success:^(NSDictionary *response) {
    NSString *answer = response[@"answer"];
    NSArray *presetQuestions = response[@"presetQuestions"];
} failure:^(NSError *error) {
    // Handle error
}];

2.5.2 Get Chat History

Method Name getChatHistory

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• type: Message type
• pageNo: Page number
• pageSize: Items per page
• success: Success callback
• failure: Failure callback

Return Value Messages array, each element contains:

• role: Message role (user/assistant)
• content: Message content
• gmtCreate: Creation time
• extra: Additional information

Example

[[CBCopilotChat shared] getChatHistoryWithCopilotId:@"copilotId"
                                          version:@"1.0"
                                           homeId:@"homeId"
                                             type:@"general"
                                           pageNo:1
                                         pageSize:20
                                         success:^(NSArray *messages) {
    // Handle history messages
} failure:^(NSError *error) {
    // Handle error
}];

2.6 Daily Message

2.6.1 Set Daily Message Schedule

Method Name setDailyMessageSchedule

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• deviceId: Device ID (optional)
• triggerTime: Trigger time (HH:mm format)
• copilotSrc: Source identifier (optional)
• success: Success callback
• failure: Failure callback

Return Value

• taskId: Created schedule task ID

Example

[[CBCopilotDailyMessage shared] setScheduleWithCopilotId:@"copilotId"
                                               version:@"1.0"
                                                homeId:@"homeId"
                                              deviceId:nil
                                           triggerTime:@"08:30"
                                            copilotSrc:nil
                                               success:^(NSString *taskId) {
    // Handle returned task ID
} failure:^(NSError *error) {
    // Handle error
}];

2.6.2 Get Daily Message Schedule

Method Name getDailyMessageSchedule

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• copilotSrc: Source identifier (optional)
• success: Success callback
• failure: Failure callback

Return Value

• taskId: Task ID
• deviceId: Device ID
• triggerTime: Trigger time (HH:mm)
• status: Task status (running/success/fail)
• createTime: Creation time (timestamp in seconds)

Example

[[CBCopilotDailyMessage shared] getScheduleWithCopilotId:@"copilotId"
                                               version:@"1.0"
                                                homeId:@"homeId"
                                            copilotSrc:nil
                                               success:^(NSDictionary *result) {
    NSString *taskId = result[@"taskId"];
    NSString *triggerTime = result[@"triggerTime"];
    NSString *status = result[@"status"];
} failure:^(NSError *error) {
    // Handle error
}];

2.6.3 Get Daily Message Content

Method Name getDailyMessageDetail

Parameters

• taskId: Task ID
• success: Success callback
• failure: Failure callback

Return Value

• content: Message content
• createTime: Creation time (timestamp in seconds)
• status: Task status (running/success/fail)
• deviceId: Device ID
• triggerTime: Trigger time (HH:mm)

Example

[[CBCopilotDailyMessage shared] getMessageWithTaskId:@"taskId"
                                           success:^(NSDictionary *result) {
    NSString *content = result[@"content"];
    NSString *status = result[@"status"];
    NSString *triggerTime = result[@"triggerTime"];
} failure:^(NSError *error) {
    // Handle error
}];

2.7 Intrusion Detection

2.7.1 Get Intrusion Detection Task List

Method Name getIntrusionTasks

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• copilotSrc: Source identifier
• success: Success callback
• failure: Failure callback

Return Value

• tasks: Task list array, each task contains:
  • taskId: Task ID
  • status: Task status
  • createTime: Creation time
  • deviceId: Device ID

Example

[[CBCopilotIntrusion shared] getTasksWithCopilotId:@"copilotId"
                                         version:@"1.0"
                                          homeId:@"homeId"
                                      copilotSrc:@"ai_service"
                                        success:^(NSArray *tasks) {
    // Handle task list
} failure:^(NSError *error) {
    // Handle error
}];

2.7.2 Submit Intrusion Analysis Task

Method Name submitIntrusionAnalysis

Parameters

• image: Image to analyze
• description: Detection description
• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID
• deviceId: Device ID
• copilotSrc: Source identifier
• success: Success callback
• failure: Failure callback

Return Value

• taskId: Created task ID

Example

[[CBCopilotIntrusion shared] submitAnalysisWithImage:image
                                       description:@"Detect entrance area"
                                        copilotId:@"copilotId"
                                         version:@"1.0"
                                          homeId:@"homeId"
                                        deviceId:@"deviceId"
                                      copilotSrc:@"ai_service"
                                        success:^(NSString *taskId) {
    // Handle returned task ID
} failure:^(NSError *error) {
    // Handle error
}];

2.7.3 Delete Intrusion Detection Task

Method Name deleteIntrusionTask

Parameters

• taskId: Task ID
• success: Success callback
• failure: Failure callback

Return Value

• result: Delete result (true/false)

Example

[[CBCopilotIntrusion shared] deleteTaskWithTaskId:@"taskId"
                                        success:^(BOOL result) {
    // Handle delete result
} failure:^(NSError *error) {
    // Handle error
}];

2.7.4 Confirm Intrusion Detection Boundary

Method Name confirmIntrusionBoundary

Parameters

• taskId: Task ID
• masks: Boundary area array, each area contains:
  • top: Top boundary
  • left: Left boundary
  • right: Right boundary
  • bottom: Bottom boundary
• success: Success callback
• failure: Failure callback

Return Value

• result: Confirmation result (true/false)

Example

NSArray *masks = @[
    @{
        @"top": @100,
        @"left": @200,
        @"right": @600,
        @"bottom": @500
    }
];

[[CBCopilotIntrusion shared] confirmBoundaryWithTaskId:@"taskId"
                                              masks:masks
                                            success:^(BOOL result) {
    // Handle confirmation result
} failure:^(NSError *error) {
    // Handle error
}];

2.7.5 Get Intrusion Detection Result

Method Name getIntrusionResult

Parameters

• taskId: Task ID
• success: Success callback
• failure: Failure callback

Return Value

• status: Task status
• answer: Analysis result description

Example

[[CBCopilotIntrusion shared] getResultWithTaskId:@"taskId"
                                      success:^(NSDictionary *result) {
    NSString *status = result[@"status"];
    NSString *answer = result[@"answer"];
} failure:^(NSError *error) {
    // Handle error
}];

2.8 Camera Control

2.8.1 Initialize Camera Manager

Method Name initWithDeviceId

Parameters

• deviceId: Device ID

Return Value

• CBCopilotCameraManager instance

Example

CBCopilotCameraManager *manager = [[CBCopilotCameraManager alloc] initWithDeviceId:@"deviceId"];
manager.delegate = self;

2.8.2 Set Preview View

Method Name setupPreviewInView

Parameters

• containerView: Container view for displaying preview

Example

[manager setupPreviewInView:self.previewContainer];

2.8.3 Start Preview

Method Name startPreview

Description Start camera preview, setupPreviewInView must be called first to set the preview view

Example

[manager startPreview];

2.8.4 Stop Preview

Method Name stopPreview

Description Stop camera preview

Example

[manager stopPreview];

2.8.5 PTZ Control

Method Name startPTZControl / stopPTZControl

Parameters

• direction: PTZ control direction, available values:
  • ThingSmartPTZControlDirectionUp: Up
  • ThingSmartPTZControlDirectionDown: Down
  • ThingSmartPTZControlDirectionLeft: Left
  • ThingSmartPTZControlDirectionRight: Right

Example

// Start turning left
[manager startPTZControl:ThingSmartPTZControlDirectionLeft];

// Stop PTZ control
[manager stopPTZControl];

2.8.6 Screenshot Function

Method Name captureImageWithSuccess

Parameters

• success: Success callback, returns screenshot image and save path
• failure: Failure callback, returns error information

Return Value

• image: Screenshot image
• imagePath: Image save path

Example

[manager captureImageWithSuccess:^(UIImage *image, NSString *imagePath) {
    // Handle screenshot
} failure:^(NSError *error) {
    // Handle error
}];

2.8.7 Cleanup Resources

Method Name cleanup

Description Clean up camera-related resources, including stopping preview, disconnecting, etc.

Example

[manager cleanup];

2.8.8 Delegate Callbacks

Implement CBCopilotCameraManagerDelegate protocol to receive the following events:

Camera Connection Status

• cameraManagerDidConnect: Camera connected successfully
• cameraManagerDidDisconnect: Camera disconnected
• cameraManagerDidFailWithError: Camera connection error

Preview Status

• cameraManagerDidStartPreview: Preview started
• cameraManagerDidStopPreview: Preview stopped
• cameraManagerDidReceiveFirstFrame: Received first frame

PTZ Control

• cameraManagerDidStartPTZ: PTZ control started
• cameraManagerDidStopPTZ: PTZ control stopped
• cameraManagerDidFailPTZWithError: PTZ control error

Example

@interface YourViewController () <CBCopilotCameraManagerDelegate>
@end

@implementation YourViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.cameraManager.delegate = self;
}

#pragma mark - CBCopilotCameraManagerDelegate

- (void)cameraManagerDidConnect {
    // Handle successful connection
}

- (void)cameraManagerDidDisconnect {
    // Handle disconnection
}

@end

2.9 Picture Describer

The Picture Describer module provides AI analysis capabilities based on video content, which can intelligently analyze video clips and generate text descriptions.

2.9.1 Get Task List

Method Name getPictureDescriberTasks

Parameters

• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID (optional)
• pageNo: Page number
• pageSize: Items per page
• success: Success callback
• failure: Failure callback

Return Value

• total: Total count
• items: Task list array, each task contains:
  • taskId: Task ID
  • createTime: Creation time
  • title: Title
  • content: Analysis result content
  • copilotId: Copilot ID
  • deviceId: Device ID
  • status: Task status (running/success/fail)

Example

[[CBCopilotImageDescriber shared] getTasksWithCopilotId:@"copilotId"
                                              version:@"1.0"
                                               homeId:@"homeId"
                                               pageNo:1
                                             pageSize:20
                                             success:^(NSDictionary *result) {
    NSInteger total = [result[@"total"] integerValue];
    NSArray *tasks = result[@"items"];
    // Handle task list
} failure:^(NSError *error) {
    // Handle error
}];

2.9.2 Get Task Details

Method Name getPictureDescriberTaskDetail

Parameters

• taskId: Task ID
• success: Success callback
• failure: Failure callback

Return Value Task details dictionary, containing fields:

• taskId: Task ID
• createTime: Creation time
• title: Title
• content: Analysis result content
• copilotId: Copilot ID
• deviceId: Device ID
• status: Task status

Example

[[CBCopilotImageDescriber shared] getTaskDetailWithTaskId:@"taskId"
                                               success:^(NSDictionary *detail) {
    NSString *status = detail[@"status"];
    NSString *content = detail[@"content"];
    // Handle task details
} failure:^(NSError *error) {
    // Handle error
}];

2.9.3 Delete Task

Method Name deletePictureDescriberTask

Parameters

• taskId: Task ID
• success: Success callback
• failure: Failure callback

Return Value

• result: Delete result (true/false)

Example

[[CBCopilotImageDescriber shared] deleteTaskWithTaskId:@"taskId"
                                            success:^(BOOL result) {
    if (result) {
        // Delete successful
    }
} failure:^(NSError *error) {
    // Handle error
}];

2.9.4 Submit Analysis Task

Method Name submitPictureDescriberTask

Parameters

• deviceId: Device ID
• prefixes: Video prefix list
• copilotId: Copilot ID
• version: Copilot version number
• homeId: Home ID (optional)
• copilotSrc: Source identifier (optional)
• success: Success callback
• failure: Failure callback

Return Value

• taskId: Created task ID

Example

[[CBCopilotImageDescriber shared] submitTaskWithDeviceId:@"deviceId"
                                              prefixes:@[@"video_1", @"video_2"]
                                             copilotId:@"copilotId"
                                              version:@"1.0"
                                               homeId:@"homeId"
                                           copilotSrc:@"ai_service"
                                              success:^(NSString *taskId) {
    // Handle returned task ID
} failure:^(NSError *error) {
    // Handle error
}];

Complete Usage Example

// 1. Submit analysis task
[[CBCopilotImageDescriber shared] submitTaskWithDeviceId:@"deviceId"
                                              prefixes:@[@"video_1"]
                                             copilotId:@"copilotId"
                                              version:@"1.0"
                                               homeId:@"homeId"
                                           copilotSrc:nil
                                              success:^(NSString *taskId) {
    NSLog(@"Task submitted successfully, taskId: %@", taskId);

    // 2. Query task details
    [[CBCopilotImageDescriber shared] getTaskDetailWithTaskId:taskId
                                                    success:^(NSDictionary *detail) {
        NSString *status = detail[@"status"];
        NSString *content = detail[@"content"];
        NSLog(@"Task result: %@, %@", status, content);

        // 3. Delete task after completion
        [[CBCopilotImageDescriber shared] deleteTaskWithTaskId:taskId
                                                    success:^(BOOL result) {
            NSLog(@"Task deletion %@", result ? @"successful" : @"failed");
        } failure:^(NSError *error) {
            NSLog(@"Task deletion failed: %@", error);
        }];
    } failure:^(NSError *error) {
        NSLog(@"Get task details failed: %@", error);
    }];
} failure:^(NSError *error) {
    NSLog(@"Task submission failed: %@", error);
}];

Notes

1. Task analysis is asynchronous, results need to be queried multiple times using taskId
2. It is recommended to regularly clean up completed tasks
3. Video prefix list supports up to 5 video clips
4. Recommended pageSize for pagination interfaces should not exceed 20
5. Task status description:
   • running: Analyzing
   • success: Analysis completed
   • fail: Analysis failed

2.10 Message Management

The message management module provides functionality for managing AI Copilot messages, including message querying, deletion, and group management.

2.10.0 Initialization

The message management module is part of SSCopilotSDK, with services provided through the Message category of CBCopilotsNetwork class.

// Import header file
#import <SSCopilotSDK/CBCopilotsNetwork+Message.h>

2.10.1 Check New Message Status

Method Name checkNewMessage

Parameters None

Return Value

void(^)(BOOL hasNewMessage)

Example

[CBCopilotsNetwork checkNewMessageWithSuccess:^(BOOL hasNewMessage) {
    if (hasNewMessage) {
        // Handle new message case
    }
} failure:^(NSError *error) {
    // Handle error
}];

2.10.2 Delete Messages

Method Name removeMessages

Parameters

• msgType: Message type (1:AI copilot message)
• type: Operation type (0:group message 1:message)
• messageIds: Message ID collection, multiple IDs separated by commas. Required when type=1
• sourceMsgIds: Message source ID collection, multiple IDs separated by commas. Required when type=0

Return Value

void(^)(BOOL result)

Example

// Delete single message
[CBCopilotsNetwork removeMessagesWithType:1
                           operationType:1
                            messageIds:@"message-123"
                          sourceMsgIds:nil
                              success:^(BOOL result) {
    if (result) {
        // Delete successful
    }
} failure:^(NSError *error) {
    // Handle error
}];

// Delete group message
[CBCopilotsNetwork removeMessagesWithType:1
                           operationType:0
                            messageIds:nil
                          sourceMsgIds:@"source-123"
                              success:^(BOOL result) {
    if (result) {
        // Delete successful
    }
} failure:^(NSError *error) {
    // Handle error
}];

2.10.3 Query Message List

Method Name fetchMessageList

Parameters

• msgType: Message type (1:AI copilot message)
• msgSrcId: Message source ID
• pageNo: Page number
• pageSize: Items per page

Return Value

void(^)(NSArray<CBMessageModel *> *messages, NSInteger total)

Example

[CBCopilotsNetwork fetchMessageListWithType:1
                                msgSrcId:@"source-123"
                                 pageNo:1
                               pageSize:20
                                success:^(NSArray<CBMessageModel *> *messages, NSInteger total) {
    // Handle message list data
} failure:^(NSError *error) {
    // Handle error
}];

2.10.4 Query Message Group List

Method Name fetchMessageGroupList

Parameters

• msgType: Message type (1:AI copilot message)
• pageNo: Page number
• pageSize: Items per page

Return Value

void(^)(NSArray<CBMessageGroupModel *> *groups, NSInteger total)

Example

[CBCopilotsNetwork fetchMessageGroupListWithType:1
                                      pageNo:1
                                    pageSize:20
                                     success:^(NSArray<CBMessageGroupModel *> *groups, NSInteger total) {
    // Handle message group list data
} failure:^(NSError *error) {
    // Handle error
}];

Error Handling

The message management module defines specific error domain and error codes:

Error Domain

CBMessageErrorDomain

Error Codes

typedef NS_ENUM(NSInteger, CBMessageErrorCode) {
    CBMessageErrorInvalidParams = 1001,    // Invalid parameters
    CBMessageErrorInvalidData = 1002,      // Invalid data format
    CBMessageErrorNetworkFailed = 1003,    // Network request failed
};

Important Notes

1. Recommended pageSize for all pagination interfaces should not exceed 20
2. Message type currently only supports AI copilot messages (msgType=1)
3. Delete operation is irreversible, please use with caution
4. When querying message list, both message type and source ID must be provided
5. Error handling should provide appropriate user prompts based on CBMessageErrorCode
6. When handling large amounts of messages, it's recommended to use pagination to improve performance
7. When deleting messages, provide the correct parameters based on operation type (messageIds or sourceMsgIds)

2.11 Pet Management

The pet management module provides functionality for managing, analyzing, and tracking pet information, including basic pet information management, behavior analysis, and photo album management.

2.11.0 Initialization

The pet management module is accessed through a singleton instance. Here's an example:

// Get the pet management module instance
CBCopilotPet *pet = [CBCopilotPet sharedInstance];

2.11.1 Get Pet List

Method Name getPetList

Parameters None

Return Value

• success: Success callback, returns pet list data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getPetListWithSuccess:^(NSArray<CBPetModel *> *pets) {
    // Handle pet list data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.2 Delete Pet

Method Name deletePet

Parameters

• petId: Pet ID (UUID format)

Return Value

• success: Success callback, no return data
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] deletePetWithId:@"pet-uuid" 
                                      success:^{
    // Delete successful
} failure:^(NSError *error) {
    // Handle error
}];

2.11.3 Add Pet

Method Name addPet

Parameters

• type: Pet type (DOG/CAT)
• name: Pet name
• avatar: Avatar URL
• gender: Gender (MALE/FEMALE)
• birthday: Birthday timestamp (milliseconds)
• weight: Weight (kg)
• identityId: Identity ID (optional)

Return Value

• success: Success callback, returns pet information CBPetModel
• failure: Failure callback, returns error information NSError

Example

[pet addPetWithType:@"DOG"
              name:@"Buddy"
            avatar:@"https://example.com/avatar.jpg"
            gender:@"MALE"
          birthday:1609459200000
            weight:5.5
        identityId:@"identity-123"
           success:^(CBPetModel *pet) {
    // Handle pet information
} failure:^(NSError *error) {
    // Handle error
}];

2.11.4 Update Pet Information

Method Name updatePet

Parameters

• petId: Pet ID
• name: Pet name
• avatar: Avatar URL
• gender: Gender (MALE/FEMALE)
• birthday: Birthday timestamp (milliseconds)
• weight: Weight (kg)
• identityId: Identity ID (optional)

Return Value

• success: Success callback, returns updated pet information CBPetModel
• failure: Failure callback, returns error information NSError

Example

[pet updatePetWithId:@"pet-uuid"
               name:@"Buddy"
             avatar:@"https://example.com/avatar.jpg"
             gender:@"MALE"
           birthday:1609459200000
             weight:5.5
         identityId:@"identity-123"
            success:^(CBPetModel *pet) {
    // Handle updated pet information
} failure:^(NSError *error) {
    // Handle error
}];

2.11.5 Upload AI Identity

Method Name uploadAiIdentify

Parameters

• fileId: File ID

Return Value

• success: Success callback, returns identity string NSString
• failure: Failure callback, returns error information NSError

Example

[pet uploadAiIdentify:@"file-123" 
             success:^(NSString *identity) {
    // Handle identity string
} failure:^(NSError *error) {
    // Handle error
}];

2.11.6 Check Pet Identity Registration Status

Method Name getAiIdentifyStatus

Parameters

• identity: Identity string

Return Value

• success: Success callback, returns status information NSString
• failure: Failure callback, returns error information NSError

Example

[pet getAiIdentifyStatus:@"identity-123" 
                success:^(NSString *status) {
    // Handle status information
} failure:^(NSError *error) {
    // Handle error
}];

2.11.7 Get Tag List

Method Name getTagList

Parameters None

Return Value

• success: Success callback, returns tag list data NSArray
• failure: Failure callback, returns error information NSError

Example

[pet getTagListWithSuccess:^(NSArray<CBPetTag *> *tags) {
    // Handle tag list data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.8 Add Custom Tag

Method Name addCustomTag

Parameters

• name: Tag name

Return Value

• success: Success callback, returns newly created tag data CBPetTag
• failure: Failure callback, returns error information NSError

Example

[pet addCustomTagWithName:@"Playful" 
                 success:^(CBPetTag *tag) {
    // Handle newly created tag data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.9 Delete Custom Tag

Method Name deleteCustomTag

Parameters

• tagID: Tag ID

Return Value

• success: Success callback, returns whether deletion was successful BOOL
• failure: Failure callback, returns error information NSError

Example

[pet deleteCustomTagWithID:123 
                  success:^(BOOL result) {
    // Handle deletion result
} failure:^(NSError *error) {
    // Handle error
}];

2.11.10 Get Album List

Method Name getAlbumList

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)
• size: Items per page (default 20)

Return Value

• success: Success callback, returns album list data CBAlbumResult
• failure: Failure callback, returns error information NSError

Example

[pet getAlbumListWithPetIds:@[@"pet-uuid"]
                   startTime:1609459200000
                     endTime:1612137600000
                        size:20
                     success:^(CBAlbumResult *result) {
    // Handle album list data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.11 Get Annual Album Statistics

Method Name getAlbumYearStat

Parameters

• petIds: Array of pet IDs

Return Value

• success: Success callback, returns annual statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getAlbumYearStatWithPetIds:@[@"pet-uuid"]
                                                 success:^(NSArray<CBAlbumYearStatModel *> *years) {
    // Handle annual statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.12 Get Monthly Album Statistics

Method Name getAlbumMonthStat

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)
• size: Items per page (default 20)

Return Value

• success: Success callback, returns monthly statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getAlbumMonthStatWithPetIds:@[@"pet-uuid"]
                                                startTime:1609459200000
                                                  endTime:1612137600000
                                                    size:20
                                                 success:^(NSArray<CBAlbumMonthStatModel *> *months) {
    // Handle monthly statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.13 Delete Album Content

Method Name deleteAlbumContent

Parameters

• contentId: Content ID

Return Value

• success: Success callback, no return data
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] deleteAlbumContent:123
                                         success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.11.14 Get Activity List

Method Name getActivityList

Parameters

• petIds: Array of pet IDs (optional)
• source: Data source, enumerated values:
  • ALL = 0 (All)
  • MOTION = 1 (Motion)
  • SOUND = 2 (Sound)
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)
• page: Page number
• size: Items per page (default 20)

Return Value

• success: Success callback, returns activity list data CBPetActivityResult
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getActivityListWithPetIds:@[@"pet-uuid"]
                                                source:1  // MOTION
                                            startTime:1609459200000
                                              endTime:1612137600000
                                                 page:1
                                                 size:20
                                              success:^(CBPetActivityResult *result) {
    // Handle activity list data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.15 Remove Activity Tag

Method Name removeActivityTag

Parameters

• activityId: Activity ID
• petId: Pet ID
• type: Tag type
• name: Tag name

Return Value

• success: Success callback, returns updated activity data CBPetActivity
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] removeActivityTag:@"activity-123"
                                         petId:@"pet-uuid"
                                          type:@"CUSTOM"
                                          name:@"Playing"
                                       success:^(CBPetActivity *activity) {
    // Handle updated activity data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.16 Add Activity Tag

Method Name addActivityTag

Parameters

• activityId: Activity ID
• petId: Pet ID
• type: Tag type, string values:
  • ABNORMAL (Abnormal)
  • HIGHLIGHT (Highlight moment)
  • CUSTOM (Custom)
• name: Tag name

Return Value

• success: Success callback, returns updated activity data CBPetActivity
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] addActivityTag:@"activity-123"
                                      petId:@"pet-uuid"
                                       type:@"CUSTOM"
                                       name:@"Playing"
                                    success:^(CBPetActivity *activity) {
    // Handle updated activity data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.17 Get Activity Details

Retrieved from the activity list query

2.11.18 Get Abnormal Calendar

Method Name getAbnormalCalander

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)

Return Value

• success: Success callback, returns abnormal calendar statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getAbnormalCalander:@[@"pet-uuid"]
                                        startTime:1609459200000
                                          endTime:1612137600000
                                          success:^(NSArray<CBAbnormalSummaryModel *> *summarys) {
    // Handle abnormal calendar statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.19 Get Abnormal Behavior

Method Name getAbnormalBehavor

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)
• page: Page number
• pageSize: Items per page (default 20)

Return Value

• success: Success callback, returns abnormal activity list NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getAbnormalBehavor:@[@"pet-uuid"]
                                       startTime:1609459200000
                                         endTime:1612137600000
                                            page:1
                                        pageSize:20
                                         success:^(NSArray<CBPetActivity *> *abnormals) {
    // Handle abnormal activity list data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.20 Get Pet Abnormal List

Method Name getPetAbnormalList

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)

Return Value

• success: Success callback, returns abnormal statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getPetAbnormalList:@[@"pet-uuid"]
                                       startTime:1609459200000
                                         endTime:1612137600000
                                         success:^(NSArray<CBStatisticsAbnormalModel *> *abnormals) {
    // Handle abnormal statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.21 Get Daily Activity

Method Name getDailyActivity

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)

Return Value

• success: Success callback, returns daily activity statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getDailyActivity:@[@"pet-uuid"]
                                     startTime:1609459200000
                                       endTime:1612137600000
                                       success:^(NSArray<CBDailyActiveRateModel *> *dailyActives) {
    // Handle daily activity statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.22 Get Daily Sleep

Method Name getDailySleep

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)

Return Value

• success: Success callback, returns sleeping posture statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getDailySleep:@[@"pet-uuid"]
                                  startTime:1609459200000
                                    endTime:1612137600000
                                    success:^(NSArray<CBSleepingPostureModel *> *sleepingPostures) {
    // Handle sleeping posture statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.11.23 Get Daily Behavior

Method Name getDailyBehavior

Parameters

• petIds: Array of pet IDs
• startTime: Start timestamp (milliseconds)
• endTime: End timestamp (milliseconds)

Return Value

• success: Success callback, returns daily behavior statistics data NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotPet sharedInstance] getDailyBehavior:@[@"pet-uuid"]
                                     startTime:1609459200000
                                       endTime:1612137600000
                                       success:^(NSArray<CBDailyBehaviorModel *> *dailyBehaviors) {
    // Handle daily behavior statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.12 Baby Care Management

The baby care management module provides functionality for managing, analyzing, and tracking baby information, including basic baby information management, behavior analysis, photo album management, activity records, story and voice management, etc.

2.12.0 Initialization

Before using the baby care management module, you need to initialize the CBCopilotBaby instance:

// Import header file
#import <SSCopilotSDK/CBCopilotBaby.h>

// Create instance
CBCopilotBaby *copilotBaby = [CBCopilotBaby sharedInstance];

2.12.1 Get Baby List

Method Name getBabyList

Parameters None

Return Value

void(^)(NSArray<CBBabyModel *> *babies)

Example

[copilotBaby getBabyListWithSuccess:^(NSArray<CBBabyModel *> *babies) {
    // Handle baby list
} failure:^(NSError *error) {
    // Handle error
}];

2.12.2 Add Baby

Method Name addBaby

Parameters

• name: Baby's name
• gender: Gender
• avatar: Avatar URL
• birthday: Birthday
• weight: Weight
• cameraId: Camera ID

Return Value

void(^)(CBBabyModel *baby)

Example

[copilotBaby addBabyWithName:@"Baby Name"
                     gender:@"M"
                     avatar:@"avatar_url"
                   birthday:@"2024-01-01"
                     weight:3.5
                   cameraId:@"camera_id"
                   success:^(CBBabyModel *baby) {
    // Handle successful addition
} failure:^(NSError *error) {
    // Handle error
}];

2.12.3 Update Baby Information

Method Name updateBaby

Parameters

• babyId: Baby ID
• name: Baby's name
• gender: Gender
• avatar: Avatar URL
• birthday: Birthday
• weight: Weight
• cameraId: Camera ID

Return Value

void(^)(CBBabyModel *baby)

Example

[copilotBaby updateBabyWithId:@"baby_id"
                        name:@"New Name"
                      gender:@"F"
                      avatar:@"new_avatar_url"
                    birthday:@"2024-01-01"
                      weight:4.0
                    cameraId:@"new_camera_id"
                    success:^(CBBabyModel *baby) {
    // Handle successful update
} failure:^(NSError *error) {
    // Handle error
}];

2.12.4 Delete Baby

Method Name deleteBaby

Parameters

• babyId: Baby ID

Return Value

void(^)(void)

Example

[copilotBaby deleteBabyWithId:@"baby_id"
                     success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.12.5 Get Album List

Method Name getBabyAlbumList

Parameters

• babyIdList: List of baby IDs
• timeType: Time type (year/month/day)
• startTime: Start time (UTC timestamp in ms)
• endTime: End time (UTC timestamp in ms)
• pageSize: Number of items per page
• pageNo: Page number

Return Value

void(^)(CBBabyAlbumResult *result)

Example

[copilotBaby getBabyAlbumListWithBabyIdList:@[@"baby_id"]
                                 timeType:@"month"
                               startTime:@"2024-01-01"
                                 endTime:@"2024-12-31"
                                pageSize:20
                                 pageNo:1
                                success:^(CBBabyAlbumResult *result) {
    // Handle album list
} failure:^(NSError *error) {
    // Handle error
}];

2.12.6 Delete Photo

Method Name deleteBabyPhoto

Parameters

• photoId: Photo ID

Return Value

void(^)(void)

Example

[copilotBaby deleteBabyPhotoWithId:@"photo_id"
                         success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.12.7 Add Activity Content

Method Name addBabyActivity

Parameters

• babyId: Baby ID
• tags: List of tags
• description: Activity description
• timestamp: UTC timestamp (milliseconds)

Return Value

void(^)(CBBabyActivity *activity)

Example

// Get current timestamp (milliseconds)
NSTimeInterval timestamp = [[NSDate date] timeIntervalSince1970] * 1000;

[copilotBaby addBabyActivityWithBabyId:@"baby_id"
                                tags:@[@"tag1", @"tag2"]
                        description:@"Activity description"
                         timestamp:[NSString stringWithFormat:@"%.0f", timestamp]
                          success:^(CBBabyActivity *activity) {
    // Handle successful addition
} failure:^(NSError *error) {
    // Handle error
}];

2.12.8 Update Activity Content

Method Name updateBabyActivity

Parameters

• activityId: Activity ID
• babyId: Baby ID
• tags: List of tags
• description: Activity description

Return Value

void(^)(CBBabyActivity *activity)

Example

[copilotBaby updateBabyActivityWithId:@"activity_id"
                            babyId:@"baby_id"
                              tags:@[@"tag1", @"tag2"]
                       description:@"Updated description"
                          success:^(CBBabyActivity *activity) {
    // Handle successful update
} failure:^(NSError *error) {
    // Handle error
}];

2.12.9 Get Activity Details

Refer to 2.12.11 Get Activity List, where each element represents activity details. No need to fetch details separately.

2.12.10 Delete Activity

Method Name deleteBabyActivity

Parameters

• activityId: Activity ID

Return Value

void(^)(void)

Example

[copilotBaby deleteBabyActivityWithId:@"activity_id"
                            success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.12.11 Get Activity List

Method Name getBabyActivityList

Parameters

• babyIds: List of baby IDs
• source: Source type (MOTION, SOUND; multiple types separated by commas; empty value means all)
• startTime: Start timestamp (UTC timestamp in ms)
• endTime: End timestamp (UTC timestamp in ms)
• pageSize: Number of items per page
• pageNo: Page number

Return Value

void(^)(CBBabyActivityResult *result)

Example

// Get timestamp (milliseconds)
NSTimeInterval startTimestamp = [[NSDate date] timeIntervalSince1970] * 1000;
NSTimeInterval endTimestamp = startTimestamp + 24 * 60 * 60 * 1000; // 24 hours later

[copilotBaby getBabyActivityListWithBabyIds:@[@"baby_id"]
                                   source:@"MOTION,SOUND" // or @"ALL" for all types
                               startTime:[NSString stringWithFormat:@"%.0f", startTimestamp]
                                 endTime:[NSString stringWithFormat:@"%.0f", endTimestamp]
                                pageSize:20
                                 pageNo:1
                                success:^(CBBabyActivityResult *result) {
    // Handle activity list
} failure:^(NSError *error) {
    // Handle error
}];

2.12.12 Get IPC Device List

Method Name getIpcDeviceList

Parameters None

Return Value

void(^)(NSArray<CBBabyCameraModel *> *cameras)

Example

[copilotBaby getIpcDeviceListWithSuccess:^(NSArray<CBBabyCameraModel *> *cameras) {
    // Handle device list
} failure:^(NSError *error) {
    // Handle error
}];

2.12.13 Get Statistics Data

Method Name getStatisticsData

Parameters

• babyId: Baby ID
• days: Number of days for statistics

Return Value

void(^)(CBBabyStatisticsModel *statistics)

Example

[copilotBaby getStatisticsDataWithBabyId:@"baby_id"
                                  days:30
                               success:^(CBBabyStatisticsModel *statistics) {
    // Handle statistics data
} failure:^(NSError *error) {
    // Handle error
}];

2.12.14 Get Voice Recognition Sample

Method Name getVoiceRecognitionSample

Dependencies This interface depends on BCBabyStorytellingService, internally calling the requestStoryVoiceSample method.

Parameters None

Return Value

void(^)(NSDictionary *result)

Example

[copilotBaby getVoiceRecognitionSampleWithSuccess:^(NSDictionary *result) {
    // result contains complete return content
    NSString *sample = result[@"sample"];
    // ... handle other return fields
} failure:^(NSError *error) {
    // Handle error
}];

2.12.15 Update Storytelling (Story Replay)

Method Name updateStorytelling

Dependencies This interface depends on BCBabyStorytellingService, internally calling the requestEditStory method.

Parameters

• storyId: Story ID (required)
• playTime: Play time, UTC timestamp (milliseconds) (required)
• babyId: Target baby ID (required)

Return Value

void(^)(void)

Example

// Get current timestamp (milliseconds)
NSTimeInterval playTime = [[NSDate date] timeIntervalSince1970] * 1000;

[copilotBaby updateStorytellingWithId:@"story_id"
                            playTime:[NSString stringWithFormat:@"%.0f", playTime]
                             babyId:@"baby_id"
                            success:^{
    // Handle successful update
} failure:^(NSError *error) {
    // Handle error
}];

2.12.16 Delete Storytelling

Method Name deleteStorytelling

Parameters

• storyId: Story ID

Return Value

void(^)(void)

Example

[copilotBaby deleteStorytellingWithId:@"story_id"
                            success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.12.17 Get Story List

Method Name getStoryList

Parameters None

Return Value

void(^)(NSArray<NSDictionary *> *stories)

Dictionary Structure

{
    "id": "Story ID",
    "title": "Story Title",
    "content": "Story Content",
    "voiceId": "Voice ID",
    "playTime": "Play Timestamp",
    "babyId": "Baby ID"
}

Example

[copilotBaby getStoryListWithSuccess:^(NSArray<NSDictionary *> *stories) {
    // Handle story list
    for (NSDictionary *story in stories) {
        NSString *storyId = story[@"id"];
        NSString *title = story[@"title"];
        // ... handle other fields
    }
} failure:^(NSError *error) {
    // Handle error
}];

2.12.18 Create Storytelling

Method Name createStorytelling

Parameters

• title: Story title (required)
• content: Story content (required)
• voiceId: Voice ID (required)
• playTime: Story play time, UTC timestamp (milliseconds) (required)
• babyId: Target baby ID (required)

Return Value

void(^)(NSString *storyId)

Example

// Get current timestamp (milliseconds)
NSTimeInterval playTime = [[NSDate date] timeIntervalSince1970] * 1000;

[copilotBaby createStorytellingWithTitle:@"New Story"
                               content:@"Story content here"
                              voiceId:@"voice_id"
                             playTime:[NSString stringWithFormat:@"%.0f", playTime]
                              babyId:@"baby_id"
                             success:^(NSString *storyId) {
    // Handle successful creation
} failure:^(NSError *error) {
    // Handle error
}];

2.12.19 Delete Story Voice

Method Name deleteStoryVoice

Parameters

• voiceId: Voice ID

Return Value

void(^)(void)

Example

[copilotBaby deleteStoryVoiceWithId:@"voice_id"
                          success:^{
    // Handle successful deletion
} failure:^(NSError *error) {
    // Handle error
}];

2.12.20 Get Voice List

Method Name getVoiceList

Parameters None

Return Value

void(^)(NSArray<NSDictionary *> *voices)

Dictionary Structure

{
    "id": "Voice ID",
    "name": "Voice Name",
    "url": "Voice File URL",
    "duration": "Duration (seconds)",
    "createTime": "Creation Timestamp"
}

Example

[copilotBaby getVoiceListWithSuccess:^(NSArray<NSDictionary *> *voices) {
    // Handle voice list
    for (NSDictionary *voice in voices) {
        NSString *voiceId = voice[@"id"];
        NSString *name = voice[@"name"];
        // ... handle other fields
    }
} failure:^(NSError *error) {
    // Handle error
}];

2.12.21 Get Voice Upload Path

Method Name getVoiceUploadPath

Parameters None

Return Value

void(^)(NSString *uploadPath)

Example

[copilotBaby getVoiceUploadPathWithSuccess:^(NSString *uploadPath) {
    // Handle upload path
} failure:^(NSError *error) {
    // Handle error
}];

2.12.22 Complete Voice Upload

Method Name updateFinishUploadVoice

Dependencies This interface depends on BCBabyStorytellingService, internally calling the requestStoryVoiceUploadConfirm method.

Parameters

• voiceId: Voice ID

Return Value

void(^)(void)

Example

[copilotBaby updateFinishUploadVoiceWithId:@"voice_id"
                                 success:^{
    // Handle upload completion
} failure:^(NSError *error) {
    // Handle error
}];

2.13 Security Monitoring

The security monitoring module provides device security monitoring management functions, including monitoring task creation, querying, deletion, as well as alarm event management and querying functions.

2.13.0 Initialization

The security monitoring module is part of SSCopilotSDK, with services provided through the CBCopilotSecurity class.

Getting Instance

// 1. Import header file
#import <SSCopilotSDK/CBCopilotSecurity.h>
// 2. Get security monitoring instance
CBCopilotSecurity *security = [CBCopilotSecurity shared];

Note CBCopilotSecurity is a singleton class, sharing one instance globally

2.13.1 Get Bound Device ID List

Method Name getBoundDeviceIdList

Parameters

• homeId: Home ID

Return Value

• success: Success callback, returns bound device ID array NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] getBoundDeviceIdListWithHomeId:@"your-home-id"
                                                  success:^(NSArray *deviceIds) {
    // Handle device ID list
} failure:^(NSError *error) {
    // Handle error
}];

2.13.2 Create Security Task

Method Name createSecurityTask

Parameters

• imgFileId: Image file ID
• homeId: Home ID
• imgHeight: Image height
• imgWidth: Image width
• deviceId: Device ID
• masks: Monitoring area list with top, left, right, bottom (number type)
• detTargets: Detection targets - Human, Baby, Pet, Other
• scheduleEnable: Enable scheduling
• week: Repeat days "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"
• allTime: Whether to monitor all time
• startTime: Start time in 24-hour format. e.g., "14:03"
• endTime: End time in 24-hour format. e.g., "18:03"
• timezone: Timezone e.g., "Asia/Shanghai"

Return Value

• success: Success callback, returns task ID NSString
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] createSecurityTaskWithImgFileId:@"image-file-id"
                                                   homeId:@"home-id"
                                                imgHeight:1080
                                                 imgWidth:1920
                                                 deviceId:@"device-id"
                                                    masks:@[@{@"top": @0.1, @"left": @0.1, @"right": @0.9, @"bottom": @0.9}]
                                               detTargets:@[@"Human", @"Pet"]
                                           scheduleEnable:YES
                                                    week:@[@"Mon", @"Wed", @"Fri"]
                                                 allTime:NO
                                               startTime:@"09:00"
                                                 endTime:@"18:00"
                                                timezone:@"Asia/Shanghai"
                                                 success:^(NSString *taskId) {
    // Handle task ID
} failure:^(NSError *error) {
    // Handle error
}];

2.13.3 Get Security Task List

Method Name getSecurityTaskList

Parameters

• homeId: Home ID

Return Value

• success: Success callback, returns task list data NSDictionary
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] getSecurityTaskListWithHomeId:@"home-id"
                                                 success:^(NSDictionary *data) {
    // Handle task list data
} failure:^(NSError *error) {
    // Handle error
}];

2.13.4 Delete Security Task

Method Name deleteSecurityTask

Parameters

• taskId: Task ID

Return Value

• success: Success callback
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] deleteSecurityTaskWithId:@"task-id"
                                            success:^{
    // Handle success
} failure:^(NSError *error) {
    // Handle error
}];

2.13.5 Update Task Enable Status

Method Name updateSecurityTaskEnableStatus

Parameters

• taskId: Task ID
• enable: Whether to enable

Return Value

• success: Success callback, returns updated task model CBSecurityGuardModel
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] updateSecurityTaskEnableStatusWithId:@"task-id"
                                                         enable:YES
                                                        success:^(CBSecurityGuardModel *model) {
    // Handle updated task model
} failure:^(NSError *error) {
    // Handle error
}];

2.13.6 Update Task Schedule

Method Name updateSecurityTaskSchedule

Parameters

• taskId: Task ID
• schedule: Schedule task model CBSecurityScheduleModel

Return Value

• success: Success callback, returns updated task model CBSecurityGuardModel
• failure: Failure callback, returns error information NSError

Example

CBSecurityScheduleModel *schedule = [[CBSecurityScheduleModel alloc] init];
// Configure schedule model
[[CBCopilotSecurity shared] updateSecurityTaskScheduleWithId:@"task-id"
                                                   schedule:schedule
                                                    success:^(CBSecurityGuardModel *model) {
    // Handle updated task model
} failure:^(NSError *error) {
    // Handle error
}];

2.13.7 Get Daily Security Record Detail List

Method Name getDailySecurityRecordDetailList

Parameters

• date: Date string

Return Value

• success: Success callback, returns daily record model CBSecurityDayRecordModel
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] getDailySecurityRecordDetailListWithDate:@"2024-03-21"
                                                            success:^(CBSecurityDayRecordModel *dayRecord) {
    // Handle daily record data
} failure:^(NSError *error) {
    // Handle error
}];

2.13.8 Get Earliest Security Record Time

Method Name getSecurityRecordEarliestTime

Parameters None

Return Value

• success: Success callback, returns creation timestamp (milliseconds) NSNumber, returns 0 if not set
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] getSecurityRecordEarliestTimeWithSuccess:^(NSNumber *createTime) {
    // Handle timestamp
} failure:^(NSError *error) {
    // Handle error
}];

2.13.9 Get Security Record List

Method Name getSecurityRecordList

Parameters

• startDate: Start date
• endDate: End date

Return Value

• success: Success callback, returns record list NSArray
• failure: Failure callback, returns error information NSError

Example

[[CBCopilotSecurity shared] getSecurityRecordListFromDate:@"2024-03-01"
                                                  toDate:@"2024-03-21"
                                                success:^(NSArray<CBSecurityRecordsDateModel *> *recordsDateList) {
    // Handle records list
} failure:^(NSError *error) {
    // Handle error
}];

2.13.10 Search Security Record Messages

Method Name searchSecurityRecordMsgList

Parameters

• param: Query parameters NSDictionary

Return Value

• success: Success callback, returns message data CBSecurityMessageData
• failure: Failure callback, returns error information NSError

Example

NSDictionary *param = @{
    // Configure query parameters
};
[[CBCopilotSecurity shared] searchSecurityRecordMsgListWithParam:param
                                                        success:^(CBSecurityMessageData *messageData) {
    // Handle message data
} failure:^(NSError *error) {
    // Handle error
}];

2.14 Video Upload

The video upload module provides cloud storage upload functionality for video files, including obtaining pre-signed URLs and executing video upload operations.

2.14.1 Get Upload Pre-signed URL

Method Name getUploadUrl

Parameters

• fileType: File type (e.g., video/mp4)

Return Value

• success: Success callback, returns the following parameters:
  • fileId: File ID
  • httpMethod: HTTP request method
  • uploadSignUrl: Pre-signed upload URL
• failure: Failure callback, returns NSError

Example

[[CBCopilotPet sharedInstance] getUploadUrl:@"video/mp4"
                                   success:^(NSString *fileId, NSString *httpMethod, NSString *uploadSignUrl) {
    // Handle pre-signed URL information
} failure:^(NSError *error) {
    // Handle error
}];

2.14.2 Get Pre-signed URL for Specific Copilot

Method Name getFileUploadSignWithId

Parameters

• copilotId: Copilot ID
• fileType: File type (e.g., video/mp4)

Return Value

• success: Success callback, returns a dictionary containing:
  • fileId: File ID
  • httpMethod: HTTP request method
  • uploadSignUrl: Pre-signed upload URL
• failure: Failure callback, returns NSError

Example

[CBCopilotsNetwork getFileUploadSignWithId:@"your-copilot-id"
                                 fileType:@"video/mp4"
                                 success:^(NSDictionary *result) {
    NSString *fileId = result[@"fileId"];
    NSString *httpMethod = result[@"httpMethod"];
    NSString *uploadSignUrl = result[@"uploadSignUrl"];
    // Handle pre-signed URL information
} failure:^(NSError *error) {
    // Handle error
}];

API Details

• API Name: tuya.m.ai.copilot.file.upload-sign
• API Version: 2.0
• Request Parameters:

  {
    "copilotId": "string, Copilot ID",
    "fileType": "string, file type"
  }
  

• Response Format: Dictionary containing file upload signature information

2.14.3 Upload Video File

Method Name updateVideo

Parameters

• fileUrl: Local video file URL
• httpMethod: HTTP request method (obtained from pre-signed interface)
• uploadSignUrl: Pre-signed upload URL (obtained from pre-signed interface)
• fileId: File ID (obtained from pre-signed interface)

Return Value

• success: Success callback, no return data
• failure: Failure callback, returns NSError

Example

[[CBCopilotPet sharedInstance] updateVideoWithFileUrl:localFileUrl
                                          httpMethod:httpMethod
                                       uploadSignUrl:uploadSignUrl
                                            fileId:fileId
                                           success:^{
    // Handle successful upload
} failure:^(NSError *error) {
    // Handle error
}];

2.14.4 Real-world Usage Example

Here's a complete video upload implementation example, including loading indicators, error handling, and post-success business logic:

- (void)saveAction {
    // Use weak reference to avoid retain cycles
    thing_weakify(self)

    // Show loading indicator
    [ThingProgressHUD showDefaultLoadingMessage:nil toView:self.view];

    // 1. Get upload pre-signed URL
    [self getUploadUrl:@"mp4" success:^(NSString *fileId, NSString *httpMethod, NSString *uploadSignUrl) {
        // Save fileId for later use
        self.fileId = fileId;

        // 2. Execute video upload
        [weak_self updateVideoWithFileUrl:self.videoUrl 
                              httpMethod:httpMethod 
                           uploadSignUrl:uploadSignUrl 
                                fileId:fileId 
                               success:^{
            // 3. Perform pet analysis after successful upload
            [weak_self petAnalyse:^(NSString *identity) {
                // Hide loading indicator
                [ThingProgressHUD hideHUDFor:weak_self.view];

                if (self.isEdit) {
                    // Edit mode: Post notification and dismiss current page
                    [[NSNotificationCenter defaultCenter] postNotificationName:KCBNotificationPetAnalysisResult 
                                                                    object:nil 
                                                                  userInfo:@{@"identity": identity ? : @""}];
                    [self dismissVC:nil];
                } else {
                    // Add mode: Navigate to set name page
                    [weak_self jumpToSetNameVC:identity];
                }
            } failure:^(NSError *error) {
                // Handle pet analysis failure
                [ThingProgressHUD hideHUDFor:weak_self.view];
                [ThingProgressHUD showSimpleMessage:error.localizedDescription toView:weak_self.view];
            }];
        } failure:^(NSError *error) {
            // Handle video upload failure
            [ThingProgressHUD hideHUDFor:weak_self.view];
            [ThingProgressHUD showSimpleMessage:error.localizedDescription toView:weak_self.view];
        }];
    } failure:^(NSError *error) {
        // Handle pre-signed URL failure
        [ThingProgressHUD hideHUDFor:weak_self.view];
        [ThingProgressHUD showSimpleMessage:error.localizedDescription toView:weak_self.view];
    }];
}

This example demonstrates:

1. Using thing_weakify to handle retain cycles
2. Using ThingProgressHUD to display loading status
3. Complete error handling process
4. Post-success business logic handling (including both edit and add modes)
5. Multi-level asynchronous operation handling

Important Notes

1. Ensure local file exists and is accessible before video upload
2. Default upload timeout is set to 60 seconds
3. Currently only supports MP4 format video files
4. Ensure stable network connection during upload