SDK Methods

Klleon Chat SDK provides essential methods for building interactive web-based avatar communication experiences. From initialization to avatar control, this guide walks through core functionalities you can integrate into your application.

SDK Lifecycle

Managing the SDK's lifecycle properly helps prevent memory leaks and ensures stable application behavior.

KlleonChat.init(options)

Initializes the SDK and connects to the server. Should be called once during the app’s startup.

Initialization Options:

Parameter	Type	Required	Default	Description
sdk_key	string	O	-	SDK key issued by Klleon Studio
avatar_id	string	O	-	Unique ID of the avatar to be used
subtitle_code	string	X	ko_kr	Avatar speech subtitle language setting. Supported codes: ko_kr (Korean), en_us (English), ja_jp (Japanese), id_id (Indonesian), etc.
voice_code	string	X	ko_kr	Avatar speech voice language setting.
voice_tts_speech_speed	number	X	1.0	Avatar speech speed control feature. Range: 0.5 ~ 2.0
enable_microphone	boolean	X	true	When set to true, attempts voice input without requesting microphone permission. (Behavior may vary depending on browser policy.)
log_level	string	X	debug	Sets the detail level of SDK internal logs. Depending on the set level, the following logs are output: - When set to debug: All debug, info, warn, error logs are output (for development and detailed debugging) - When set to info: info, warn, error logs are output - When set to warn: warn, error logs are output - When set to error: Only error logs are output - When set to silent: All log outputs are disabled For production deployment, it is recommended to use "silent" to optimize performance and prevent unnecessary information exposure.
custom_id	string	X	-	Sets a custom device identifier or other user-defined identifier used in the client system.
user_key	string	X	-	User session management key issued through Klleon Studio's End-User creation API. It can be used for session time adjustment, etc.

Best Practice

Call KlleonChat.init() only once per SDK instance. Multiple calls are ignored internally but initializing just once helps with clarity and performance.

KlleonChat.destroy()

Cleans up all SDK-related resources such as socket connections, WebRTC streams, and event listeners.

Example:

App.tsx (SDK Lifecycle)

import { useEffect } from "react";

const App = () => {
  useEffect(() => {
    const init = async () => {
      await window.KlleonChat.init({
        sdk_key: "YOUR_SDK_KEY",
        avatar_id: "YOUR_AVATAR_ID",
        subtitle_code: "en_us",
        voice_code: "en_us",
        voice_tts_speech_speed: 1.0,
        enable_microphone: true,
        log_level: "debug",
        custom_id: "YOUR_CUSTOM_ID",
        user_key: "YOUR_USER_KEY",
      });
    };
    init();

    return () => {
      window.KlleonChat.destroy();
    };
  }, []);

  return (
    <div>
      <avatar-container />
      <chat-container />
    </div>
  );
};

export default App;

Sending Messages

KlleonChat.sendTextMessage(text)

Sends a user-entered text message to the avatar.

App.tsx (sendTextMessage)

import { useRef } from "react";

const App = () => {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSend = () => {
    const text = inputRef.current?.value.trim();
    if (text) {
      window.KlleonChat.sendTextMessage(text);
      inputRef.current.value = "";
    }
  };

  return (
    <div>
      <avatar-container />
      <chat-container />
      <input ref={inputRef} type="text" placeholder="Enter a message" />
      <button onClick={handleSend}>Send</button>
    </div>
  );
};

export default App;

Voice Input (STT: Speech-to-Text)

Use startStt() to begin voice capture and endStt() to stop and convert speech to text for the avatar.

Microphone Permission

Make sure enable_microphone: true is set in the init() options and that the browser has permission to access the mic.

KlleonChat.startStt() / KlleonChat.endStt()

App.tsx (startStt, endStt)

import { useRef } from "react";

const App = () => {
  const isRecording = useRef(false);

  const handleRecord = () => {
    if (!isRecording.current) {
      window.KlleonChat.startStt();
      isRecording.current = true;
    } else {
      window.KlleonChat.endStt();
      isRecording.current = false;
    }
  };

  return (
    <div>
      <avatar-container />
      <button onClick={handleRecord}>Toggle Recording</button>
    </div>
  );
};

export default App;

KlleonChat.cancelStt()

App.tsx (cancelStt)

const App = () => {
  const handleCancel = () => {
    window.KlleonChat.cancelStt();
  };

  return <button onClick={handleCancel}>Cancel STT</button>;
};

KlleonChat.stopSpeech()

App.tsx (stopSpeech)

const App = () => {
  const handleStopSpeech = () => {
    window.KlleonChat.stopSpeech();
  };

  return <button onClick={handleStopSpeech}>Stop Speech</button>;
};

Echo Feature

KlleonChat.echo(text)

App.tsx (echo)

const App = () => {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleEcho = () => {
    const text = inputRef.current?.value.trim();
    if (text) {
      window.KlleonChat.echo(text);
    }
  };

  return (
    <div>
      <input ref={inputRef} placeholder="Enter text to echo" />
      <button onClick={handleEcho}>Echo</button>
    </div>
  );
};

KlleonChat.startAudioEcho(audio) / KlleonChat.endAudioEcho()

App.tsx (startAudioEcho, endAudioEcho)

const App = () => {
  const audioRef = useRef<HTMLTextAreaElement>(null);

  const handleAudioEcho = () => {
    const audio = audioRef.current?.value.trim();
    if (audio) {
      window.KlleonChat.startAudioEcho(audio);
      setTimeout(() => {
        window.KlleonChat.endAudioEcho();
      }, 100);
    }
  };

  return (
    <div>
      <textarea ref={audioRef} placeholder="Enter Base64 audio string" />
      <button onClick={handleAudioEcho}>Play Audio Echo</button>
    </div>
  );
};

Why use endAudioEcho()?

It helps the system transition smoothly from voice playback to idle or next state.

Changing Avatar

KlleonChat.changeAvatar(option)

Parameter	Type	Required	Default	Description
avatar_id	string	O	-	Unique ID of the avatar to be changed
subtitle_code	string	X	Initial connection value	Avatar speech subtitle language setting. Supported codes: ko_kr (Korean), en_us (English), ja_jp (Japanese), id_id (Indonesian), etc.
voice_code	string	X	Initial connection value	Avatar speech voice language setting.
voice_tts_speech_speed	number	X	Initial connection value	Avatar speech speed control feature. Range: 0.5 ~ 2.0

App.tsx (changeAvatar)

const App = () => {
  const handleChangeAvatar = () => {
    window.KlleonChat.changeAvatar({
      avatar_id: "NEW_AVATAR_ID",
      subtitle_code: "en_us",
      voice_code: "en_us",
      voice_tts_speech_speed: 1.0,
    });
  };

  return <button onClick={handleChangeAvatar}>Change Avatar</button>;
};

Message List Management

KlleonChat.clearMessageList()

Clears the SDK’s internal message list (UI only; server data remains).

App.tsx (clearMessageList)

const App = () => {
  const handleClear = () => {
    window.KlleonChat.clearMessageList();
  };

  return <button onClick={handleClear}>Clear Messages</button>;
};