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.
ACTIVATE_VOICE	Occurs when voice input is activated. In this state, chat input is available even if the avatar is not in VIDEO_CAN_PLAY status.
RATE_LIMIT	Request rate limit exceeded
HANDOVER_START	Handover started
HANDOVER_SUCCESS	Handover succeeded
HANDOVER_FAIL	Handover failed

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, onErrorEvent) 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_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

---

KlleonChat.onErrorEvent(callback)

Registers a callback function to receive errors occurring within the SDK. This allows you to detect and handle various error scenarios such as network failures, media playback issues, and more.

• callback ((error: ErrorData) => void, required): A function that receives an ErrorData object ({ code: ErrorCode; message: string }).

function handleError(error) {
  console.error("SDK Error:", error.code, error.message);
}

window.KlleonChat.onErrorEvent(handleError);

ErrorCode Details

Error codes are categorized into Initialization phase (occurs during init() call) and Runtime phase (occurs after VIDEO_CAN_PLAY).

ErrorCode	Phase	Description
SOCKET_FAILED	Initialization	WebSocket connection failed during initialization. Occurs when the server is unreachable or the network is unstable.
STREAMING_FAILED	Initialization	Media streaming (Agora) connection failed during initialization, or the streaming server did not respond within 10 seconds.
STREAMING_RECONNECT_FAILED	Runtime	Agora streaming connection was lost and the automatic reconnection attempt failed.
VIDEO_ELEMENT_NOT_FOUND	Runtime	After a successful streaming connection, the SDK searches for the <avatar-container> element using document.querySelector, but it does not exist in the DOM. This typically occurs when conditional rendering (e.g., toggling component visibility based on state in React) prevents the <avatar-container> from being mounted in document.body. The SDK polls every 300ms for up to 3 seconds.
SOCKET_DISCONNECTED_UNEXPECTEDLY	Runtime	The WebSocket connection was unexpectedly lost while the avatar video was playing (VIDEO_CAN_PLAY state). Caused by network interruption or server-side disconnection.
STREAMING_DISCONNECTED_UNEXPECTEDLY	Runtime	The media streaming connection was unexpectedly lost during an active session. Possible causes include network errors, token expiration, or IP/channel/UID bans.

Error Event Flow

Re-registering Callbacks

If onChatEvent, onStatusEvent, or onErrorEvent 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.