Start an agent call by passing parameters that customize the call behavior for your business scenario.
Feature description
When you start a call, you can pass parameters to the agent to control its running status and conversation responses. For more information about business implementations, see AI interviews, Spoken language coaching, and Emotional companionship.
The agent supports two startup methods. Choose a method that fits your business scenario:
-
Start from the server-side: High flexibility, strong extensibility, and consistency.
-
Start from the client: Low connection latency, minimal dependencies, and high independence.
Parameters such as greetings, voice, and language that you configure in the console are overwritten when the agent starts. You can also call the UpdateAIAgentInstance - Update AI agent instance configuration API to modify the configuration during a call.
Start an agent from the server-side
Call the Create an AI agent call instance API to initiate a call. The response is sent to the client, which uses the returned information to join the call. When you start the call, you can configure the AIAgentConfig parameter. For more information, see Start an agent call using a server-side API.
Start an agent from the client
To start a call from the client, configure <a baseurl="t2844192_v4_2_0.xdita" data-node="5707963" data-root="69463" data-tag="xref" href="t2938416.xdita#L2uxx" id="ecb192782d0yu">ARTCAICallAgentConfig</a> in ARTCAICallConfig after you create and initialize the engine. For the startup flow for each client, see Android Integration Overview, iOS Integration Overview, Web Integration Overview, and Harmony Integration Overview.
Android
ARTCAICallAgentConfig
Configurable parameters for a call.
Parameter | Type | Description |
agentGreeting | String | The agent's welcome message. If you leave this empty, the agent's configured value is used. Maximum length: 100 characters. |
wakeUpQuery | String | An instruction from the user before the call starts, which the agent responds to immediately after the call begins. |
agentMaxIdleTime | int | The maximum idle time for the agent. Unit: seconds. If the time is exceeded, the agent automatically goes offline. Default value: 600. |
userOnlineTimeout | int | The timeout period for the agent to shut down the task if the user does not join the call. Default value: 60. |
userOfflineTimeout | int | The timeout period for the agent to shut down the task after the user leaves the call. Default value: 5. |
enablePushToTalk | boolean | Specifies whether to enable push-to-talk mode. |
agentGracefulShutdown | boolean | Specifies whether to enable graceful shutdown. This allows the agent to finish speaking the current sentence before stopping. |
volume | int | The agent's speaking volume. Valid values: 0 to 400. Default value: 100. |
workflowOverrideParams | String | Workflow override parameters |
enableIntelligentSegment | boolean | Specifies whether to enable intelligent sentence segmentation. |
asrConfig | Speech recognition configuration | |
ttsConfig | Speech synthesis configuration | |
llmConfig | Large language model configuration | |
avatarConfig | Digital human configuration | |
interruptConfig | Interruption configuration | |
voiceprintConfig | Voiceprint-based noise reduction configuration | |
turnDetectionConfig | Turn detection configuration | |
experimentalConfig | Customized, non-productized configuration | |
ARTCAICallAgentVcrConfig | VCR configuration |
iOS
ARTCAICallAgentConfig
The startup and runtime configuration for the call agent.
Property | Type | Description |
agentGreeting | String? | The agent's welcome message. If this is empty, the agent's configured value is used. |
wakeUpQuery | String? | A user command given before the call starts. This allows the agent to respond immediately after the call begins. |
agentMaxIdleTime | Int32 | The maximum idle time for the agent before it automatically goes offline. Unit: seconds. Default value: 600s. |
userOnlineTimeout | Int32 | The timeout period for the agent to close the task if the user does not join the call. Default value: 60s. |
userOfflineTimeout | Int32 | The timeout period for the agent to close the task after the user leaves the call. Default value: 5s. |
enablePushToTalk | Bool | Specifies whether to enable push-to-talk mode. |
agentGracefulShutdown | Bool | Specifies whether to enable graceful shutdown. |
volume | Int32 | The agent's speaking volume. Valid values: 0 to 400. Default value: 100. |
workflowOverrideParams | [String: Any]? | The workflow override parameters. |
enableIntelligentSegment | Bool | The switch for intelligent sentence segmentation. |
asrConfig | The speech recognition configuration. | |
ttsConfig | The speech synthesis configuration. | |
llmConfig | The large language model configuration. | |
avatarConfig | The digital human configuration. | |
interruptConfig | The interruption configuration. | |
voiceprintConfig | The voiceprint-based noise suppression configuration. | |
turnDetectionConfig | The turn detection configuration. | |
experimentalConfig | The non-production customized configuration. | |
vcrConfig | The VCR configuration. |
Web
AICallAgentConfig
Configuration for starting and running a call agent.
Property | Type | Description |
agentGreeting (Optional) | string | The agent's welcome message. If this is left empty, the value configured for the agent is used. The message can be up to 100 characters long. |
wakeUpQuery (Optional) | string | The user's instruction before the call starts. The agent responds immediately after the call starts. |
agentMaxIdleTime | number | The maximum idle time for the agent, in seconds. The agent automatically goes offline if the time is exceeded. Default value: 600s. |
userOnlineTimeout | number | The timeout period for the agent to close the task if the user does not join the meeting. Default value: 60s. |
userOfflineTimeout | number | The timeout period for the agent to close the task after the user leaves the meeting. Default value: 5s. |
enablePushToTalk | boolean | Specifies whether to enable push-to-talk mode. |
agentGracefulShutdown | boolean | Specifies whether to enable graceful shutdown. If enabled, the agent stops after broadcasting the current sentence. |
volume | number | The agent's speaking volume. Valid values: 0 to 400. Default value: 100. |
workflowOverrideParams | JSONObject | Workflow overwrite parameters. |
enableIntelligentSegment | boolean | The switch for intelligent sentence segmentation. |
asrConfig | Speech recognition configuration. | |
ttsConfig | Speech synthesis configuration. | |
llmConfig | Large language model configuration. | |
avatarConfig | Digital human configuration. | |
interruptConfig | Interruption configuration. | |
voiceprintConfig | Voiceprint noise reduction configuration. | |
turnDetectionConfig | Turn detection configuration. | |
experimentalConfig | JSONObject | Non-productized custom configuration. |
vcrConfig | VCR configuration. |
Harmony
ARTCAICallAgentConfig
The startup and runtime configuration for a call agent.
Property name | Type | Description |
agentGreeting | string | The agent's welcome message. If this is empty, the value configured for the agent is used. |
wakeUpQuery | string | An instruction from the user before the call starts, which the agent responds to immediately after the call begins. For example: "What's the weather like today?" |
agentMaxIdleTime | number | The maximum idle time for the agent in seconds. If the time is exceeded, the agent automatically goes offline. The default value is 600s. A value of -1 disables automatic shutdown, meaning the agent will never go offline automatically. |
userOnlineTimeout | number | The timeout period for the agent to close the task if the user does not join the session. The default value is 60s. If you set this to a value less than 0, the setting is not sent to the server, and the server-side default of 60s is used. |
userOfflineTimeout | number | The timeout period for the agent to close the task after the user leaves the session. The default value is 5s. If you set this to a value less than 0, the setting is not sent to the server, and the server-side default of 5s is used. |
enablePushToTalk | boolean | Specifies whether to enable push-to-talk mode. |
agentGracefulShutdown | boolean | Specifies whether to enable graceful shutdown. With graceful shutdown, when the agent is stopped, it finishes its current speech before stopping. The speech can last for a maximum of 10 seconds. |
volume | number | The agent's speaking volume. The value ranges from 0 to 400. The output volume is calculated as: (Voice output volume in the workflow) × volume/100. The default value is 100. If you set this parameter to a value less than 0, the setting is not sent to the server, and the server-side default value of 100 is used. |
workflowOverrideParams | Record<string, RecordValueType> | The workflow override parameters. |
enableIntelligentSegment | boolean | The switch for intelligent sentence segmentation. When enabled, sentence breaks in the user's speech are intelligently merged into a single sentence. |
preConnectAudioUrl | string | The sound effect to play after the connection is established but before the welcome message. You can provide a URL. The welcome message is still played after the sound effect finishes. |
asrConfig | The speech recognition configuration. | |
ttsConfig | The speech synthesis configuration. | |
llmConfig | The large language model (LLM) configuration. | |
avatarConfig | The digital human configuration. | |
interruptConfig | The interruption configuration. | |
voiceprintConfig | The voiceprint denoising configuration. | |
turnDetectionConfig | The turn detection configuration. | |
experimentalConfig | The non-production, custom configuration. | |
vcrConfig | The VCR configuration. | |
ambientConfig | The environment configuration. | |
backChannelingConfigs | The configuration module for the back-channeling feature. When configured, the system randomly plays short back-channeling phrases at specific trigger points. | |
autoSpeechForLlmPendingConfig | The configuration for the agent to automatically speak when there is a delay in the LLM response. | |
autoSpeechForUserIdleConfig | The configuration for the agent to make an inquiry when the user is silent. |