Event Handling

Klleon Chat SDK uses custom events to notify your application of real-time state changes and data. By subscribing to these events, you can build dynamic experiences aligned with the SDK’s behavior.

Registering and Managing Event Listeners

KlleonChat.onChatEvent(callback)

Registers a callback function that is triggered whenever a chat message related to the avatar or user is received. This allows you to build a custom chat UI without relying on the SDK’s <chat-container> component.

• callback ((data: ChatData) => void, required): A function that receives a ChatData object.

function handleChatMessage(chatData) {
  console.log("New chat message:", chatData);
}

window.KlleonChat.onChatEvent(handleChatMessage);

ChatData Object and ResponseChatType Details

ChatData Object Properties

The properties of the ChatData object passed to onChatEvent are:

Property Name	Type	Description
message	string	Content of the received message.
chat_type	string (ResponseChatType)	Indicates the type of message. For possible values, refer to the 'ResponseChatType Values Detail' tab.
time	string	String representation of the time when the message occurred. (e.g., ISO 8601 format)
id	string	Unique identifier of the message.

ResponseChatType Details

Values and meanings of the chat_type field in the ChatData object. (See BaseResponseChatType)

ResponseChatType Value	Description
TEXT	Text message sent by the avatar. Mainly occurs as an avatar response after using KlleonChat.echo() or KlleonChat.sendTextMessage() methods.
STT_RESULT	Result when user's voice (STT) is successfully converted to text.
STT_ERROR	Occurs when user voice (STT) conversion or transmission fails. Mainly occurs when there is no voice data.
WAIT	Occurs when waiting to start chatting.
WARN_SUSPENDED	Warns that chatting will be suspended soon if there is no chat for a certain period (e.g., 10 seconds).
DISABLED_TIME_OUT	Occurs when the session is suspended due to no chat for a long time.
TEXT_ERROR	Occurs when the text message sent by the user fails to transmit.
TEXT_MODERATION	Occurs when the message is filtered because the user used inappropriate language.
ERROR	Delivered when a general error occurs on the server side. (e.g., internal server error, specific request processing failure, etc.)
PREPARING_RESPONSE	Occurs when the avatar is preparing a response to the user's message.
RESPONSE_IS_ENDED	Indicates that one turn of the avatar (response that may include multiple sentences generated by LLM) has completely ended.
RESPONSE_OK	Indicates that the avatar has successfully prepared a response to the user's message or started speaking.
WORKER_DISCONNECTED	Occurs when the connection with the avatar streaming worker is disconnected.
EXCEED_CONCURRENT_QUOTA	Occurs when the connection is rejected because the maximum allowed number of concurrent users is exceeded.
START_LONG_WAIT	Occurs when the avatar transitions to a long wait state due to no interaction with the user for a specified time.
USER_SPEECH_STARTED	Occurs when the SDK starts detecting user voice input.
USER_SPEECH_STOPPED	Occurs when the SDK detects that user voice input has stopped.

ChatData Flow

Sending a Text Message

Sending a Voice Message

---

KlleonChat.onStatusEvent(callback)

Registers a callback function that is triggered when the SDK or avatar’s internal status changes.

• callback ((status: Status) => void, required): A function receiving the current status as a string.

function handleSdkStatus(currentStatus) {
  console.log("SDK Status Changed:", currentStatus);

  if (currentStatus === "VIDEO_CAN_PLAY") {
    console.log("Avatar video is ready! You can now use other SDK methods.");
  }
}

window.KlleonChat.onStatusEvent(handleSdkStatus);

SDK Method Usage Prerequisite

Most SDK methods (e.g., sending messages, STT functions) must be called only when the avatar is fully connected and in a VIDEO_CAN_PLAY state. This state is communicated through onStatusEvent. Calling methods before this state may lead to unexpected behavior.

KlleonChat.init() and event listener methods (onChatEvent, onStatusEvent) are exceptions to this rule.

Status Event Arguments

Type	Description
string (Status)	String representing the current status of the SDK and avatar. For possible values, refer to the 'Status Values Detail' table below.

Available Status Values

Status Value	Description
IDLE	SDK is initialized but not yet connected, in idle state.
CONNECTING	Status after validating and passing sdk_key and avatar_id before session connection.
CONNECTING_FAILED	Status when validation failed due to incorrect sdk_key or avatar_id values.
SOCKET_CONNECTED	Status when successfully connected to the WebSocket server.
SOCKET_FAILED	Status when WebSocket server connection failed.
STREAMING_CONNECTED	Status when successfully connected to the media streaming (WebRTC) server.
STREAMING_FAILED	Status when media streaming (WebRTC) server connection failed.
CONNECTED_FINISH	Status when all connections (WebSocket, streaming) are successfully completed.
VIDEO_LOAD	Status when avatar video data loading has started.
VIDEO_CAN_PLAY	Avatar video is ready to play and most SDK methods can be called in this prepared state.

Status Event Flow

Re-registering Callbacks

If onChatEvent or onStatusEvent is called multiple times for the same event type, only the most recently registered callback remains active. Older callbacks are automatically removed. There’s no explicit off method.