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 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, in seconds. The agent automatically goes offline after the timeout. Default: 600s. |
userOnlineTimeout | int | The timeout period for the agent to close the task if the user does not join. Default: 60s. |
userOfflineTimeout | int | The timeout period for the agent to close the task after the user leaves. Default: 5s. |
enablePushToTalk | boolean | Specifies whether to enable push-to-talk mode. |
agentGracefulShutdown | boolean | Specifies whether to enable graceful shutdown, which finishes playing the current sentence before stopping. |
volume | int | The agent's speaking volume. Range: 0 to 400. Default: 100. |
workflowOverrideParams | String | Workflow Overwrite Parameters |
enableIntelligentSegment | boolean | Intelligent sentence segmentation switch. |
asrConfig | Speech recognition configuration. | |
ttsConfig | Speech synthesis configuration. | |
llmConfig | Large language model configuration. | |
avatarConfig | Digital human configuration. | |
interruptConfig | Interruption configuration. | |
voiceprintConfig | Voiceprint denoising configuration. | |
turnDetectionConfig | Turn detection configuration. | |
experimentalConfig | Non-productized custom configuration. | |
ARTCAICallAgentVcrConfig | VCR configuration. | |
preConnectAudioUrl | String | The sound effect to play after connection and before the welcome message. You can pass a URL. The welcome message will still be played after the sound effect. |
ambientConfig | Ambient sound configuration. | |
backChannelingConfig | Backchanneling configuration module. After configuration, the system randomly plays short backchanneling phrases at specific trigger points. | |
autoSpeechForLlmPendingConfig | Configuration for the agent to automatically speak when an LLM response is delayed. | |
autoSpeechForUserIdleConfig | Configuration for the agent to make inquiries when the user is silent. |
iOS
ARTCAICallAgentConfig
Agent startup and runtime configuration for calls.
Property name | Type | Description |
agentGreeting | String? | Agent welcome message. A null value uses the agent's configured value. |
wakeUpQuery | String? | Instruction from the user before call initiation, used for the agent to respond immediately after the call starts. |
agentMaxIdleTime | Int32 | Maximum idle wait time for the agent (in seconds). The agent automatically goes offline after timeout. Default value: 600 seconds. |
userOnlineTimeout | Int32 | Time for the agent to close the task if the user does not join the channel. Default value: 60 seconds. |
userOfflineTimeout | Int32 | Time for the agent to close the task after the user leaves the channel. Default value: 5 seconds. |
enablePushToTalk | Bool | Whether to enable walkie-talkie mode. |
agentGracefulShutdown | Bool | Whether to perform graceful shutdown. |
volume | Int32 | Agent speaking volume. Range: 0–400. Default value: 100. |
workflowOverrideParams | [String: Any]? | Workflow override parameters. |
enableIntelligentSegment | Bool | Intelligent sentence segmentation switch. |
asrConfig | Speech recognition configuration. | |
ttsConfig | Speech synthesis configuration. | |
llmConfig | Large Language Model (LLM) configuration. | |
avatarConfig | Digital human configuration. | |
interruptConfig | Interruption configuration. | |
voiceprintConfig | Voiceprint denoising configuration. | |
turnDetectionConfig | Turn detection configuration. | |
experimentalConfig | Non-product customization configuration. | |
vcrConfig | VCR configuration | |
preConnectAudioUrl | String? | Sound effect played after connection but before the welcome message. Supports URL input. The welcome message still plays after the sound effect finishes. |
ambientConfig | Environment configuration | |
backChannelingConfig | Backchanneling feature configuration module. After configuration, the system randomly broadcasts short backchanneling phrases at specific trigger moments. | |
autoSpeechForLlmPendingConfig | Configuration for the agent to automatically speak when LLM response is delayed | |
autoSpeechForUserIdleConfig | Configuration for the agent to inquire when the user is silent |
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. |