Virtual Avatar
  • iOS
  • Android : Java
  • Overview
  • Client SDKs
  • Demo app
  • Getting started
    • Integrate the SDK
    • Create a virtual avatar
    • ZegoCharacterHelper instructions
  • Guides
  • Best practice
  • Error codes
  • Server APIs

Talking avatar

Last updated:2023-03-14 17:18


ZEGOCLOUD's Virtual Avatar now supports the Talking Avatar feature, it supports real-time driving of the virtual avatar's facial movements and corresponding audio playback of text-to-speech by inputting text.


Before you begin, make sure you complete the following:

  • Contact the ZEGOCLOUD team to enable talking avatar permissions.


1 Get module source code

After downloading Avatar SDK, find and copy the apiservice folder according to SDK's root directory /helper/apiservice and paste it to your app code to get the source code of talking avatar.

  • Pay attention to the java directory, the recommended package name is: im.zego.apiservice, otherwise the source code needs to be modified.
  • Since the ZegoTextAPI depends on the Virtual Avatar SDK, the app project must include Avatar SDK.

2 (Optional) Add dependencies

In the source code, ZegoTextAPI uses the okhttp3 network library, while you are allowed to import or modify the network implementation as needed based on the actual situation.

To import dependencies without modifying the network library, run the following in your build.gradle:

dependencies {
    implementation 'com.squareup.okhttp3:okhttp:4.9.0'

3 Authentication

Before using the ZegoTextAPI, go to ZEGOCLOUD Admin Console to get your project's AppID and AppSign.

The AppID and AppSign filled in here must be the same as the information that was used to apply for authentication when creating the avatar.

public class ZegoTextLicenseCustomer {

    public static long APP_ID = 0;
    public static String APP_SIGN = "";


4 Method calls

After building a basic avatar:

  1. Initialize the ZegoTextAPI object and pass it in the Character object (can get from CharacterHelper).

    mZegoTextAPI = new ZegoTextAPI(mCharacterHelper.getCharacter());
  2. Set up the callback ITextExpressionCallback.

    mZegoTextAPI.setTextExpressionCallback(new ITextExpressionCallback() {
         * Callback when the talking avatar function starts.
        public void onStart() {
            Log.d(TAG, "text drive start");
         * Callback when an error occurs.
         * @param errorCode  For the Error Codes, refer to [Common Error Codes- Text Driver Error Codes](
        public void onError(int errorCode, String msg) {
         * Callback when the talking avatar function ends.
        public void onEnd() {
            Log.d(TAG, "text drive end");

After completing the settings, ZegoTextAPI will call back the corresponding method. The callback error codes can be defined in the static class ErrorCode of the TextConstants class. For details, refer to Error codes- Talking avatar.

  1. Call the playTextExpression method, type your text, and the avatar will make the corresponding expressions and say what you type.

    // Type the text that needs to be converted into emotions
    mZegoTextAPI.playTextExpression("Text to be played");
  • The maximum length of the text is 1000 characters/time. For extra-long texts, you may have to call this method multiple times to play in order.
  • You are allowed to adjust the audio playback logic in the source code according to the actual situation.
  1. To stop driving the avatar to talk via text, call the stopTextExpression method.
    //Stop this text drive
Page Directory