Quick Start Voice Call

This document explains how to quickly call AI Agent related backend APIs to achieve voice interaction with AI Agent.

2026-08-14

Item	Digital Human Video Call	Digital Human Live Broadcast
Interaction Mode	Two-way, the digital human responds after the user speaks	One-way, users only watch the digital human broadcast content
Use Cases	AI interaction, AI customer service, digital human tutor	Digital human live streaming, news broadcasting
Client Requires User Audio Capture	Yes	No
Digital Human Driving Mechanism	After receiving user audio, the LLM generates a response and drives the digital human via TTS	Broadcast content is fully controlled by the server; the digital human is driven via TTS
Instance Creation API	CreateDigitalHumanAgentInstance	CreateLiveDigitalHumanAgentInstance
Requires user_id and user_stream_id	Yes	No

Prerequisites

You have created a project in the ZEGOCLOUD Console and obtained a valid AppID and ServerSecret (for server API signing and RTC Token04 generation). For details, see Console - Project Info.
You have contacted ZEGOCLOUD Technical Support to enable the AI Agent related services and obtained LLM and TTS related configuration information. For details, see Console - AI Agent.
You have obtained a valid digital_human_id (for testing, you can use the public ID: 63c3aa64-1d80-4b04-a0be-1c65614eb7eb).

Note

During the test period (within 2 weeks after the AI Agent service is enabled), you can set the LLM and TTS authentication parameters to "zego_test" to use the related services. For details, see Register Agent > BODY Parameter Description.

You can also purchase LLM and TTS services supported by ZEGOCLOUD to obtain authentication information. Alternatively, you can contact ZEGOCLOUD sales to purchase TTS services directly.

Example Code

The following is the example code for the business backend that integrates the real-time interactive AI Agent API. You can refer to the example code to implement your own business logic.

Business Backend Example Code

Includes the basic capabilities of obtaining ZEGO Token, registering AI Agent, creating AI Agent instances, and deleting AI Agent instances.

The following is the client sample code. You can refer to the example code to implement your own business logic.

Android Client Sample Code

Includes the basic capabilities of logging in, publishing stream, playing stream, and exiting rooms.

iOS Client Sample Code

Includes the basic capabilities of logging in, publishing stream, playing stream, and exiting rooms.

Web Client Sample Code

Includes the basic capabilities of logging in, publishing stream, playing stream, and exiting rooms.

Flutter Client Sample Code

Includes the basic capabilities of logging in, publishing stream, playing stream, and exiting rooms.

The following video demonstrates how to run the service backend and client (Web) example code and interact with the AI Agent via voice.

Overall Business Process

Service backend: run the business backend example code and deploy the business backend.
- Integrate the real-time interactive AI Agent API to manage AI Agents.

Client: refer to the Android Quick Start, iOS Quick Start, or Web Quick Start document to run the client example code.
- Create and manage AI Agents through the business backend.
- Integrate ZEGO Express SDK for real-time communication.

After completing the above two steps, you can achieve real-time interaction between the AI Agent and real users by joining the room.

Core Implementation

Register Agent

Register Agent is used to set the basic configuration of the AI Agent, including the agent name, LLM, TTS, ASR, and other related configurations. After registration, the agent can be used as a template to create multiple instances for real-time interaction with multiple real users.

Typically, the agent configuration is relatively fixed. Once the relevant parameters (persona) are set, they do not change frequently. Therefore, it is recommended to register the agent at the appropriate time according to your business flow. The agent will not be automatically destroyed or recycled after registration. Once an agent instance is created, you can interact with the agent via voice.

Note

An agent can only be registered once (with the same ID). If you register it again, error code 410001008 will be returned.

The following is an example of calling the Register Agent API:

Server(NodeJS)

// Please replace the LLM and TTS authentication parameters (ApiKey, appid, token, etc.) in the following example with your actual authentication parameters.
async registerAgent(agentId: string, agentName: string) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=RegisterAgent  
    const action = 'RegisterAgent';  
    const body = {  
        AgentId: agentId,  
        Name: agentName,  
        LLM: {  
            Url: "https://ark.cn-beijing.volces.com/api/v3/chat/completions",  
            ApiKey: "zego_test",  
            Model: "doubao-1-5-pro-32k-250115",  
            SystemPrompt: "You are an AI Agent. Please answer the user's questions."  
        },  
        TTS: {  
            Vendor: "ByteDance",  
            Params: {  
                "app": {  
                    "appid": "zego_test",  
                    "token": "zego_test",  
                    "cluster": "volcano_tts"  
                },  
                "audio": {  
                    "voice_type": "zh_female_wanwanxiaohe_moon_bigtts"  
                }  
            }  
        }  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest<any>(action, body);  
}

Server(NodeJS)

// Please replace the LLM and TTS authentication parameters (ApiKey, appid, token, etc.) in the following example with your actual authentication parameters.
async registerAgent(agentId: string, agentName: string) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=RegisterAgent  
    const action = 'RegisterAgent';  
    const body = {  
        AgentId: agentId,  
        Name: agentName,  
        LLM: {  
            Url: "https://ark.cn-beijing.volces.com/api/v3/chat/completions",  
            ApiKey: "zego_test",  
            Model: "doubao-1-5-pro-32k-250115",  
            SystemPrompt: "You are an AI Agent. Please answer the user's questions."  
        },  
        TTS: {  
            Vendor: "ByteDance",  
            Params: {  
                "app": {  
                    "appid": "zego_test",  
                    "token": "zego_test",  
                    "cluster": "volcano_tts"  
                },  
                "audio": {  
                    "voice_type": "zh_female_wanwanxiaohe_moon_bigtts"  
                }  
            }  
        }  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest<any>(action, body);  
}

Note

Please ensure all LLM parameters are correctly filled in according to the LLM service provider's official documentation. Otherwise, you may not be able to see the agent's text responses or hear the agent's voice output.
Please ensure all TTS parameters are correctly filled in according to the TTS service provider's official documentation. Otherwise, you may see the agent's text responses but not hear the agent's voice output.
If the agent cannot output text or voice, please first check whether the LLM and TTS parameter configurations are completely correct, or refer to Get AI Agent Service Status - Monitor Server Exception Events to identify the specific issue.

Create Agent Instance

You can use a registered agent as a template to create multiple agent instances to join different rooms for real-time interaction with different users. After creating an agent instance, the instance will automatically log in to the room and publish stream, while also playing the real user's stream.

After successfully creating an agent instance, the real user can interact with the agent in real time by listening for stream change events and playing the stream on the client.

Note

After the client successfully joins the room, you should immediately call this API so that the agent instance can join the room and start publishing and playing streams.

Note

By default, a maximum of 10 agent instances can exist simultaneously under one account. Creating agent instances will fail if this limit is exceeded. To adjust the limit, please contact ZEGOCLOUD sales.

The following is an example of calling the Create Agent Instance API:

Server(NodeJS)

async createAgentInstance(agentId: string, userId: string, rtcInfo: RtcInfo, messages?: any[]) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance  
    // const rtcInfo = {  
    //   RoomId: room_id,  
    //   AgentStreamId: agent_stream_id,  
    //   AgentUserId: agent_user_id,  
    //   UserStreamId: user_stream_id,  
    // };  
    const action = 'CreateAgentInstance';  
    const body = {  
        AgentId: agentId,  
        UserId: userId, // Real user ID interacting with this AI Agent instance  
        RTC: rtcInfo,  
        MessageHistory: {  
            SyncMode: 1, // Change to 0 to use history messages from ZIM  
            Messages: messages && messages.length > 0 ? messages : [],  
            WindowSize: 10  
        }  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    const result = await this.sendRequest<any>(action, body);  
    console.log("create agent instance result", result);  
    // Save the returned AgentInstanceId on the client for subsequent deletion of the agent instance.  
    return result.AgentInstanceId;  
}

Server(NodeJS)

async createAgentInstance(agentId: string, userId: string, rtcInfo: RtcInfo, messages?: any[]) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance  
    // const rtcInfo = {  
    //   RoomId: room_id,  
    //   AgentStreamId: agent_stream_id,  
    //   AgentUserId: agent_user_id,  
    //   UserStreamId: user_stream_id,  
    // };  
    const action = 'CreateAgentInstance';  
    const body = {  
        AgentId: agentId,  
        UserId: userId, // Real user ID interacting with this AI Agent instance  
        RTC: rtcInfo,  
        MessageHistory: {  
            SyncMode: 1, // Change to 0 to use history messages from ZIM  
            Messages: messages && messages.length > 0 ? messages : [],  
            WindowSize: 10  
        }  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    const result = await this.sendRequest<any>(action, body);  
    console.log("create agent instance result", result);  
    // Save the returned AgentInstanceId on the client for subsequent deletion of the agent instance.  
    return result.AgentInstanceId;  
}

After completing this step, you can create agent instances. Once the client is integrated, you can interact with the agent instance via voice.

Integrate Client SDK

Please refer to the following documents to complete client integration development:

Android

Quick Start

iOS

Quick Start

Web

Quick Start

Flutter

Quick Start

Congratulations 🎉! After completing this step, you have successfully integrated the client SDK and can interact with the agent instance in real time via voice. You can ask the agent any question by voice, and the agent will respond!

Delete Agent Instance

After deleting the agent instance, the agent instance will automatically exit the room and stop publishing stream. After the real user stops publishing stream and exits the room on the client, a complete interaction session ends.

The following is an example of calling the Delete Agent Instance API:

Server(NodeJS)

async deleteAgentInstance(agentInstanceId: string) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=DeleteAgentInstance  
    const action = 'DeleteAgentInstance';  
    const body = {  
        AgentInstanceId: agentInstanceId  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest(action, body);  
}

Server(NodeJS)

async deleteAgentInstance(agentInstanceId: string) {  
    // Request URL: https://aigc-aiagent-api.zegotech.cn?Action=DeleteAgentInstance  
    const action = 'DeleteAgentInstance';  
    const body = {  
        AgentInstanceId: agentInstanceId  
    };  
    // The sendRequest method encapsulates the request URL and common parameters. For details, see: /aiagent-server/api-reference/accessing-server-apis  
    return this.sendRequest(action, body);  
}

The above is the complete core flow for achieving real-time voice interaction with the AI Agent.

Callback Monitoring

Note

Since LLM and TTS parameters are numerous and complex, it is easy to encounter various abnormal issues during integration testing, such as the agent not responding or not speaking, due to incorrect parameter configuration. We strongly recommend that you monitor callbacks during integration testing and quickly troubleshoot issues based on callback information.

Receiving Callbacks

Click to view the callback monitoring guide. Monitor events where Event is Exception in the callbacks. You can quickly locate issues through Data.Code and Data.Message.

Exception Error Codes

Click to view the exception error code list.

Quick Start Voice Call

Quick Start Digital Human Video Call

Digital Human Introduction

Quick Start Digital Human Live Broadcast

Differences from Digital Human Video Calls

Prerequisites

Example Code

Overall Business Process

Core Implementation

Register Agent

Server(NodeJS)

Create Agent Instance

Server(NodeJS)

Integrate Client SDK

Delete Agent Instance

Server(NodeJS)

Callback Monitoring

Broadcast Troubleshooting Checklist