Intelligent Media Services:Integrate into iOS apps

Prerequisites

• Xcode 16.0 or later is recommended, with the latest official version preferred.

• Cocoa Pods 1.9.3 or later.

• A physical device running iOS 10.0 or later.

Integrate SDKs

target '你的Target' do

  # Integrate ApsaraVideo MediaBox SDK for Alibaba Real-Time Communication (ARTC). You can integrate AliVCSDK_ARTC, AliVCSDK_Standard, or AliVCSDK_InteractiveLive
  pod 'AliVCSDK_ARTC', '~> x.x.x'
  # Integrate AICallKit SDK
  pod 'ARTCAICallKit/Chatbot', '~> 2.1.0'

  # You need to integrate AliVCInteractionMessage with a minimum version of 1.5.0
  pod 'AliVCInteractionMessage', '~> 1.5.0'
  
  ...

end

Project configuration

• Add microphone and camera permissions by opening the project info.Plist and adding NSMicrophoneUsageDescription and NSCameraUsageDescription.

• Enable Background Modes in Signing & Capabilities within the project settings. Enabling background mode is strongly recommended to continue calls after entering the background. Otherwise, you must call the end call interface in your app.

Use SDKs

// Import SDK
import ARTCAICallKit

// Create an engine instance
let engine: ARTCAIChatEngineInterface = {
    return ARTCAICallEngineFactory.createChatEngine()
}()

// Configure callbacks
self.engine.delegate = self


// Start a conversation
// userId is recommended to use the user id after logging into your app
let userId = "xxx"
// Set deviceId
let deviceId = UIDevice.current.identifierForVendor?.uuidString
let userInfo = ARTCAIChatUserInfo(userId, deviceId)
// Set AI agent. The agentId cannot be nil
let agentInfo = ARTCAIChatAgentInfo(agentId: "xxx")
let sessionId = "\(userInfo.userId)_\(agentInfo.agentId)"
self.engine.startChat(userInfo: userInfo, agentInfo: agentInfo, sessionId: self.sessionId)


// End a conversation
// If there are multiple AI Agents for messaging and conversation, you do not need to log out when ending the current conversation. Set needLogout to false
self.engine.endChat(needLogout: false)
// Otherwise, set needLogout to false and call destroy to release resources
self.engine.endChat(needLogout: true)
self.engine.destroy()


// For examples of other feature calls, see the API description

// Handle callback events (only examples without core callback operations)
public func onRequestAuthToken(userId: String, responseBlock: @escaping (ARTCAIChatAuthToken?, NSError?) -> Void) {
    // Request AuthToken. This is triggered when ChatEngine needs to perform IM logon or when the IM logon AuthToken expires
    self.fetchAuthToken(userId: userId) { authToken, error in
        responseBlock(authToken, error)
    }
}

public func onEngineStateChange(state: ARTCAIChatEngineState) {
    // The connection status of the Chat AI Agent changes
}

public func onErrorOccurs(error: NSError, requestId: String?) {
    // If requestId is not empty, an error occurred during message processing
    if let _ = requestId {
        if error.aicall_code == .ChatTextMessageReceiveFailed {
            // An error occurred while processing the text message
            return
        }
        if error.aicall_code == .ChatVoiceMessageReceiveFailed {
            // An error occurred while processing the voice message
            return
        }
        
        if error.aicall_code == .ChatPlayMessageReceiveFailed {
            // An error occurred during playback
            return
        }
        
        return
    }

    // If requestId is empty, an error occurred in the engine
    if let code = error.aicall_code {
        if code == .TokenExpired {
            // Authentication expired
        }
        else if code == .AgentNotFound {
            // AI Agent not found (agent ID does not exist)
        }
        else if code == .KickedBySystem {
            // Kicked out by the system, causing the conversation to fail
        }
        else if code == .KickedByUserReplace {
            // The same name logon caused the call to fail
        }
    }

    // Handle other errors
}

public func onUserMessageUpdated(message: ARTCAIChatMessage) {
    // The message sent by the user needs to be updated
}

public func onReceivedMessage(message: ARTCAIChatMessage) {
    // A reply message from the Chat AI Agent is received. This callback is triggered when the AI Agent has a new reply or when the status of the message changes during the current reply process
}

public func onAgentResponeStateChange(state: ARTCAIChatAgentResponseState, requestId: String?) {
    // Received a response change from the Chat AI Agent
}

public func onMessagePlayStateChange(message: ARTCAIChatMessage, state: ARTCAIChatMessagePlayState) {
    // Received a message playback status change from the Chat AI Agent
}

API description

API overview

ARTCAIChatEngineInterface

State

Retrieve the engine connection status.

var state: ARTCAIChatEngineState { get }

UserInfo

Retrieve the user information for the current session.

var userInfo: ARTCAIChatUserInfo? { get }

SessionId

Retrieve the unique identifier for the current session.

var sessionId: String? { get }

AgentInfo

Retrieve the AI Agent information for the current session.

var agentInfo: ARTCAIChatAgentInfo? { get }

AgentResponeState

Retrieve the current AI Agent response status.

var agentResponeState: ARTCAIChatAgentResponseState { get }

VoiceIdList

Retrieve the current voice list.

var voiceIdList: [String] { get }

Delegate

Configure and query callback events.

weak var delegate: ARTCAIChatEngineDelegate? { get set }

TemplateConfig

Configure and query TemplateConfig.

var templateConfig: ARTCAIChatTemplateConfig? { get set }

Userdata

Pass user-defined information to the AI Agent.

var userData: [String: Any]? { get set }

Startchat

Initiate a chat session.

func startChat(userInfo: ARTCAIChatUserInfo, agentInfo: ARTCAIChatAgentInfo, sessionId: String?)

Parameters

Endchat

Terminate a chat session.

func endChat(needLogout: Bool)

Parameters

Sendmessage

Send a message, interrupting the current reply if necessary.

func sendMessage(request: ARTCAIChatSendMessageRequest, completed:((_ msg: ARTCAIChatMessage?, _ error: NSError?) -> Void)?)

Parameters

Querymessagelist

Request the historical message list.

func queryMessageList(request: ARTCAIChatMessageListRequest, completed:((_ msgList: [ARTCAIChatMessage]?, _ error: NSError?) -> Void)?)  

Parameters

Interruptagentresponse

Interrupt the current message reply.

func interruptAgentResponse()

Deletemessage

Delete a message.

func deleteMessage(dialogueId: String, completed:((_ error: NSError?) -> Void)?)

Parameters

Startplaymessage

Begin playback of a message.

func startPlayMessage(message: ARTCAIChatMessage, voiceId: String?, completed: ((NSError?) -> Void)?)

Parameters

Stopplaymessage

Stop message playback.

func stopPlayMessage()

Isplayingmessage

Check if a message is currently playing.

func isPlayingMessage(dialogueId: String) -> Bool

Startpushvoicemessage

Initiate push-to-talk, sending the recording in real-time. Ensure recording permission is granted.

Returns true on success, false on failure due to reasons such as incorrect status or lack of recording permission.

func startPushVoiceMessage(request: ARTCAIChatSendMessageRequest) -> Bool

Parameters

Finishpushvoicemessage

Conclude push-to-talk, indicating the voice message has been sent and awaiting the AI Agent's response.

func finishPushVoiceMessage(completed:((_ msg: ARTCAIChatMessage) -> Void)?)

Parameters

CancelPushVoiceMessage

Cancel push-to-talk, indicating the voice message send has been aborted.

func cancelPushVoiceMessage()

Destroy

Release resources.

func destroy()

Parseshareagentchat

Parse shared intelligent agent information.

func parseShareAgentChat(shareInfo: String) -> ARTCAIChatAgentShareConfig?

Parameters

GenerateShareAgentChat

Initiate a call with a shared intelligent agent.

func generateShareAgentChat(shareConfig: ARTCAIChatAgentShareConfig, userId: String, completed: ((_ agentInfo: ARTCAIChatAgentInfo?, _ authToken: ARTCAIChatAuthToken?, _ error: NSError?, _ reqId: String) -> Void)?)    

Parameters

ARTCAIChatEngineDelegate

Onerroroccurs

An error has occurred.

@objc optional func onErrorOccurs(error: NSError, requestId: String?)

Parameters

OnRequestAuthToken

Request an AuthToken when ChatEngine needs to perform an IM logon or when the IM logon AuthToken expires.

@objc optional func onRequestAuthToken(userId: String, responseBlock: @escaping (_ authToken: ARTCAIChatAuthToken?, _ error: NSError?)->Void)

Parameters

OnEngineStateChange

Notification of a change in the engine connection status.

@objc optional func onEngineStateChange(state: ARTCAIChatEngineState)

Parameters

Onreceivedmessage

Notification of a new reply or a change in the status of a message from the AI Agent.

@objc optional func onReceivedMessage(message: ARTCAIChatMessage)

Parameters

Onreceivedcustommessage

Notification of a custom message received.

@objc optional func onReceivedCustomMessage(text: String)

Parameters

Onusermessageupdated

Notification that a user-sent message needs updating.

@objc optional func onUserMessageUpdated(message: ARTCAIChatMessage)

Parameters

OnAgentResponeStateChange

Notification of a response status change from the AI Agent.

@objc optional func onAgentResponeStateChange(state: ARTCAIChatAgentResponseState, requestId: String?)

Parameters

Onmessageplaystatechange

Notification of a message playback status change from the Chat AI Agent.

@objc optional func onMessagePlayStateChange(message: ARTCAIChatMessage, state: ARTCAIChatMessagePlayState)

Parameters

ARTCAICallEngineFactory

Createchatengine

Create a default Chat AI Agent engine.

public static func createChatEngine() -> ARTCAIChatEngineInterface