API operation details

The user ID for the current call.

var userId: String? {get}

Indicates whether a call is in progress. The value is true from the time the call is connected until it ends or an error occurs. Otherwise, the value is false.

var isOnCall: Bool { get }

Information about the current agent, including the agent type, channel ID, agent UID in the channel, and the agent's running instance ID. For more information, see ARTCAICallAgentInfo.

var agentInfo: ARTCAICallAgentInfo? { get }

The state of the current agent, such as listening, thinking, and speaking. For more information, see ARTCAICallAgentState.

var agentState: ARTCAICallAgentState { get }

Sets and retrieves callback events. For more information about callback events, see ARTCAICallEngineDelegate.

weak var delegate: ARTCAICallEngineDelegate? { get set }

Starts a call.

func call(userId: String, token: String, agentInfo: ARTCAICallAgentInfo, completed:((_ error: NSError?) -> Void)?)

Parameter details:

Parameter	Type	Description
userId	String	The UID of the current user.
token	String	The token for joining the call.
agentInfo	ARTCAICallAgentInfo	The agent information.
completed	((_ error: NSError?) -> Void)?	The completion callback.

Starts a call using the call configuration.

func call(config: ARTCAICallConfig) -> Bool

Parameter details:

Parameter	Type	Description
config	ARTCAICallConfig	The call configuration.

Ends a call.

 func handup(_ stopAIAgent: Bool)

Parameter details:

Parameter	Type	Description
stopAIAgent	Bool	Specifies whether to end the current agent task at the same time.

Hangs up the call and destroys the current call engine. First, a message is sent to notify the agent to stop the call. Then, the system waits for 100 ms before it ends the call.

func handup(destroy: Bool)

Parameter details:

Parameter	Type	Description
destroy	Bool	Specifies whether to destroy the current engine after hanging up. If set to true, the destroy() method is called internally after the call is completely hung up.

The audio configuration, covering encoding settings (sample rate, number of channels, and bitrate) and scenario settings (default and music). For more information, see ARTCAICallAudioConfig. This parameter takes effect only when it is set before the call.

var audioConfig: ARTCAICallAudioConfig { set get }

The video configuration. Valid only for VisionAgent and VideoAgent. Takes effect only when set before the call. For more information, see ARTCAICallVideoConfig.

var videoConfig: ARTCAICallVideoConfig { set get }

Sets the rendering view and configuration for the local camera. Valid only for VisionAgent and VideoAgent. For more information, see ARTCAICallViewConfig.

func setLocalViewConfig(viewConfig: ARTCAICallViewConfig?)

Parameter details:

Parameter	Type	Description
viewConfig	ARTCAICallViewConfig	The view configuration. An empty value indicates that no view needs to be rendered.

Sets the rendering view configuration for the agent. Required when the agent has image rendering capabilities. Valid only for VisionAgent and VideoAgent. For more information, see ARTCAICallViewConfig.

func setAgentViewConfig(viewConfig: ARTCAICallViewConfig?)

Parameter details:

Parameter	Type	Description
viewConfig	ARTCAICallViewConfig?	The rendering view configuration, including the rendering view, rendering mode, mirror mode, and rotation mode.

Interrupts the agent's speech.

func interruptSpeaking() -> Bool

Enables or disables smart interruption.

func enableVoiceInterrupt(enable: Bool) -> Bool

Parameter details:

Parameter	Type	Description
enable	Bool	Enables or disables the feature.

Switches the voice.

func switchVoiceId(voiceId: String) -> Bool

Parameter details:

Parameter	Type	Description
voiceId	String	Voice ID

Enables or disables the speaker.

func enableSpeaker(enable: Bool) -> Bool

Parameter details:

Parameter	Type	Description
enable	Bool	Start/Stop

Enables or disables the push-to-talk mode. In this mode, the agent reports the result only after finishPushToTalk is called.

func enablePushToTalk(enable: Bool) -> Bool

Parameter details:

Parameter	Type	Description
enable	Bool	Disables or enables the mode.

Starts speaking in push-to-talk mode.

func startPushToTalk() -> Bool

Stops speaking in push-to-talk mode.

func finishPushToTalk() -> Bool

Cancels the current speech in push-to-talk mode.

func cancelPushToTalk() -> Bool

Mutes or unmutes the microphone.

func muteMicrophone(mute: Bool) -> Bool

Parameter details:

Parameter	Type	Description
mute	Bool	Mutes or unmutes the microphone.

Stops or resumes the playback of the agent's audio stream.

func muteAgentAudioPlaying(mute: Bool) -> Bool

Parameter details:

Parameter	Type	Description
mute	Bool	Specifies whether to mute the playback.

This parameter must be set when you use a visual agent and takes effect only when it is set before the call. The visual configuration includes the resolution and frame rate. For more information, see ARTCAICallVisionConfig.

var visionConfig: ARTCAICallVisionConfig { set get }

Disables or enables the camera.

func muteLocalCamera(mute: Bool) -> Bool

Parameter details:

Parameter	Type	Description
mute	Bool	Disables or enables mute.

Switches between the front and rear cameras.

func switchCamera() -> Bool

Parses the information of a shared agent. On success, returns an ARTCAICallAgentShareConfig instance that you can use to start a shared agent call.

func parseShareAgentCall(shareInfo: String) -> ARTCAICallAgentShareConfig?

Parameter details:

Parameter	Type	Description
shareInfo	String	The information of the shared agent, which can be generated in the console.

Starts a shared agent call.

func generateShareAgentCall(shareConfig: ARTCAICallAgentShareConfig, userId: String, completed: ((_ rsp: ARTCAICallAgentInfo?, _ token: String?, _ error: NSError?, _ reqId: String) -> Void)?)

Parameter details:

Parameter	Type	Description
shareConfig	ARTCAICallAgentShareConfig	The configuration of the shared agent, including the share ID, agent type, time-to-live (TTL), template configuration, and region. You can view the definition in the SDK.
userId	String	The ID of the currently logged-on user.
completed	((_ rsp: ARTCAICallAgentInfo?, _ token: String?, _ error: NSError?, _ reqId: String) -> Void)?	The event for operation completion.

Obtain the RTC engine.

func getRTCInstance() -> AnyObject?

Sends a text message to the agent.

func sendTextToAgent(req: ARTCAICallSendTextToAgentRequest) -> Bool

Parameter details:

Parameter	Type	Description
req	ARTCAICallSendTextToAgentRequest	The message struct to send.

Sends a custom message to the server. Must be called after the call is connected.

func sendCustomMessageToServer(msg: String) -> Bool

Parameter details:

Parameter	Type	Description
msg	String	The content to send.

Updates the system prompt for the large language model (LLM). Must be called after the call is connected.

func updateLlmSystemPrompt(prompt: String) -> Bool

Parameter details:

Parameter	Type	Description
prompt	String	The prompt.

Updates the parameters for Alibaba Cloud Model Studio.

func updateBailianAppParams(params: [String: Any]) -> Bool

Parameter details:

Parameter	Type	Description
params	[String: Any]	The parameters for Alibaba Cloud Model Studio.

Updates the Video Content Recognition (VCR) configuration.

 func updateVcrConfig(vcrConfig: ARTCAICallAgentVcrConfig) -> Bool

Parameter details:

Parameter	Type	Description
vcrConfig	ARTCAICallAgentVcrConfig	VCR configuration.

Starts custom frame capture for a visual understanding agent. After this is started, voice interaction is disabled. Must be called after the call is connected.

func startVisionCustomCapture(req: ARTCAICallVisionCustomCaptureRequest) -> Bool

Parameter details:

Parameter	Type	Description
req	ARTCAICallVisionCustomCaptureRequest	The configuration information.

Stops custom frame capture for a visual understanding agent. Must be called after the call is connected.

func stopVisionCustomCapture() -> Bool

Updates the threshold for voice activity detection. A period of silence longer than this threshold is considered a sentence break.

func updateAsrMaxSilence(duration: Int32) -> Bool

Parameter details:

Parameter	Type	Description
duration	Int32	The duration in milliseconds. The value ranges from 200 ms to 1200 ms.

Updates the Text-to-Speech (TTS) playback speed. All TTS types are supported. The value ranges from 0.5 to 2.0.

func updateTtsSpeechRate(rate: Double) -> Bool

Parameter details:

Parameter	Type	Description
rate	Double	The speech rate. The value ranges from 0.5 to 2.0.

Creates an ARTC engine in advance. If not called, the engine is created when the call starts.

func createRTCEngine()

Releases resources.

func destroy()

The call encountered an error.

@objc optional func onErrorOccurs(code: ARTCAICallErrorCode)

Parameter details:

Parameter	Type	Description
code	ARTCAICallErrorCode	The error type.

The Call Agent is now running.

@objc optional func onAgentStarted()

The call has started.

@objc optional func onCallBegin()

Call ended

@objc optional func onCallEnd()

Is the agent video active?

@objc optional func onAgentVideoAvailable(available: Bool)

Parameter details:

Parameter	Type	Description
available	Bool	Available

Is the agent's audio active?

@objc optional func onAgentAudioAvailable(available: Bool)

Parameter details:

Parameter	Type	Description
available	Bool	Indicates whether the audio is available.

This callback is triggered when the ARTC engine is created. You can call getRTCInstance in this callback to retrieve the ARTC engine instance.

@objc optional func onRTCEngineCreated()

Specifies whether walkie-talkie mode is enabled for the current call.

@objc optional func onPushToTalk(enable: Bool)

Parameter details:

Parameter	Type	Description
enable	Bool	Indicates whether the mode is enabled.

The current agent is about to end the call.

@objc optional func onAgentWillLeave(reason: Int32, message: String)

Parameter details:

Parameter	Type	Description
reason	Int32	The reason for leaving: 2001 (idle exit) or 0 (other).
message	String	The description of the reason for leaving.

This callback is triggered when a custom message is received from the current agent.

@objc optional func onReceivedAgentCustomMessage(data: [String: Any]?)

Parameter details:

Parameter	Type	Description
data	[String: Any]?	The message content.

Agent status changes

@objc optional func onAgentStateChanged(state: ARTCAICallAgentState)

Parameter details:

Parameter	Type	Description
state	ARTCAICallAgentState	The current state of the agent: listening, thinking, or speaking.

Network state changes

@objc optional func onNetworkStatusChanged(uid: String, quality: ARTCAICallNetworkQuality)

Parameter details:

Parameter	Type	Description
uid	String	The ID of the current speaker.
quality	ARTCAICallNetworkQuality	The network quality, including excellent, good, fair, poor, very poor, disconnected, and unknown.

A notification of a volume change.

@objc optional func onVoiceVolumeChanged(uid: String, volume: Int32)

Parameter details:

Parameter	Type	Description
uid	String	The UID of the current speaker.
volume	Int32	The volume, ranging from 0 to 255.

A notification that the user's question is recognized by the agent.

@objc optional func onUserSubtitleNotify(text: String, isSentenceEnd: Bool, sentenceId: Int)

Parameter details:

Parameter	Type	Description
text	String	The question text recognized by the agent.
isSentenceEnd	Bool	Indicates whether the current text is the final result for this sentence.
sentenceId	Int	The ID of the sentence to which the current text belongs.

A notification of the agent's response.

@objc optional func onVoiceAgentSubtitleNotify(text: String, isSentenceEnd: Bool, userAsrSentenceId: Int)

Parameter details:

Parameter	Type	Description
text	String	The response text from the agent.
isSentenceEnd	Bool	Indicates whether the current text is the last sentence of this response.
userAsrSentenceId	Int	The ID of the sentence that answers the user's question.

The LLM has completed its response.

@objc optional func onLLMReplyCompleted(text: String, userAsrSentenceId: Int)

Parameter details:

Parameter	Type	Description
text	String	The text output by the LLM.
userAsrSentenceId	Int	The ID of the sentence that answers the user's question.

The tone for the current call has changed.

@objc optional func onVoiceIdChanged(voiceId: String)

Parameter details:

Parameter	Type	Description
voiceId	String	The current voice ID.

Indicates whether voice barge-in is enabled for the current call.

@objc optional func onVoiceInterrupted(enable: Bool)

Parameter details:

Parameter	Type	Description
enable	Bool	Indicates whether the feature is enabled.

The agent has been interrupted.

@objc optional func onSpeakingInterrupted(reason: ARTCAICallSpeakingInterruptedReason)

Parameter details:

Parameter	Type	Description
reason	ARTCAICallSpeakingInterruptedReason	The reason, such as interruption by a specific word.

This callback indicates whether custom frame capture mode is enabled for the current visual understanding call.

@objc optional func onVisionCustomCapture(enable: Bool)

Parameter details:

Parameter	Type	Description
enable	Bool	Indicates whether the mode is enabled.

Agent digital human: First-frame rendering

@objc optional func onAgentAvatarFirstFrameDrawn()

When a human agent is about to take over

@objc optional func onHumanTakeoverWillStart(takeoverUid: String, takeoverMode: Int)

Parameter details:

Parameter	Type	Description
takeoverUid	String	The UID of the human.
takeoverMode	Int	1: indicates that the human's voice is used for output. 0: indicates that the agent's voice is used for output.

This callback is triggered when the human takeover is connected.

@objc optional func onHumanTakeoverConnected(takeoverUid: String)

Parameter details:

Parameter	Type	Description
takeoverUid	String	The UID of the human.

A notification of the agent's emotion.

@objc optional func onAgentEmotionNotify(emotion: String, userAsrSentenceId: Int)

Parameter details:

Parameter	Type	Description
emotion	String	The emotion label, such as neutral, happy, angry, or sad.
userAsrSentenceId	Int	The ID of the sentence that answers the user's question.

A callback for the availability of the agent's message channel. After this callback is triggered, you can send messages to the agent.

@objc optional func onAgentDataChannelAvailable()

This callback is triggered when a VCR result is received from the current agent. For more information, see ARTCAICallAgentVcrResult.

@objc optional func onReceivedAgentVcrResult(result: ARTCAICallAgentVcrResult)

The connection status can change during a call.

@objc optional func onConnectionStatusChange(status: ARTCAICallConnectionStatus, reason: Int32)

Parameter details:

Parameter	Type	Description
status	ARTCAICallConnectionStatus	The status code: Init: The initialization is complete. Disconnected: The network connection is disconnected. Connecting: A network connection is being established. Connected: The network is connected. Reconnecting: The network connection is being re-established. Failed: The network connection failed.
reason	Int	Cause

Audio loopback latency.

@objc optional func onAudioDelayInfo(sentenceId: Int32, delayMs: Int64)

Parameter details:

Parameter	Type	Description
sentenceId	Int32	The sentence ID.
delayMs	Int64	The audio loopback latency in milliseconds.

If you play background music through the ARTC instance during the current call, this playback callback is triggered.

 @objc optional func onAudioAccompanyStateChanged(state: ARTCAICallAudioAccompanyState, errorCode: ARTCAICallAudioAccompanyErrorCode)

Parameter details:

Parameter	Type	Description
state	ARTCAICallAudioAccompanyState	The playback state of the background music: • ARTCAICallAudioAccompanyStarted (100): Playback starts. • ARTCAICallAudioAccompanyStopped (101): Playback stops. • ARTCAICallAudioAccompanyPaused (102): Playback is paused. • ARTCAICallAudioAccompanyResumed (103): Playback resumes. • ARTCAICallAudioAccompanyEnded (104): Playback is complete. • ARTCAICallAudioAccompanyBuffering (105): Buffering. • ARTCAICallAudioAccompanyBufferingEnd (106): Buffering ends. • ARTCAICallAudioAccompanyFailed (107): Playback failed.
errorCode	ARTCAICallAudioAccompanyErrorCode	The playback error code: • ARTCAICallAudioAccompanyNoError (0): No error. • ARTCAICallAudioAccompanyUnknowError (-1): An unknown error occurred. • ARTCAICallAudioAccompanyOpenFailed (-100): Failed to open the file. • ARTCAICallAudioAccompanyDecodeFailed (-101): Failed to decode the file.

Creates a default engine instance.

public static func createEngine() -> ARTCAICallEngineInterface