Klleon SDK

English

한국어
日本語

English

한국어
日本語

Appearance

Getting Started ​

Requirements ​

The SDK runs in the following environments. Check them before running.

BrowserMinimum version
Chrome / Edge92 or later
Firefox95 or later
Safari (including iOS)15.4 or later
Samsung Internet16 or later
  • HTTPS required — In an HTTP environment, the internal browser APIs the SDK relies on are unavailable, so the connection fails, and that failure can be misdiagnosed as a different error. For local development, http://localhost is allowed as an exception.
  • Microphone permission — Using voice input (STT) requires the browser's microphone permission. When initialized with enable_microphone: false, the SDK does not request permission and voice input is unavailable.

Install via CDN ​

html
<script src="https://klleon.k1.klleon.io/{VERSION}/klleon-sdk.umd.js"></script>

Replace {VERSION} with the actual version (e.g., 2.0.0). After loading, access the SDK via window.KlleonSDK.

Basic Usage ​

1. Add Components to HTML ​

html
<avatar-container style="width: 400px; height: 400px;"></avatar-container>
<chat-container></chat-container>

2. Subscribe to Events ​

To receive status changes during init(), register onStatus before calling init().

js
const SDK = window.KlleonSDK;

SDK.onStatus((status) => {
  console.log('Status changed:', status);
});

SDK.onSignal((data) => {
  console.log('Signal:', data.signal, data.payload);
});

SDK.onError((error) => {
  console.error('Error:', error.code, error.message);
});
jsx
const [status, setStatus] = useState('IDLE');

useEffect(() => {
  const SDK = window.KlleonSDK;

  SDK.onStatus((s) => setStatus(s));
  SDK.onSignal((data) => console.log(data.signal, data.payload));
  SDK.onError((error) => console.error(error.code, error.message));
}, []);

3. Initialize the SDK ​

init() resolves right after the status transitions to CONNECTED_FINISH. If initialization fails, the status returns to IDLE, and the failure surfaces only as an exception thrown by init() — not through onStatus.

js
SDK.init({
  sdk_key: 'YOUR_SDK_KEY',
  avatar_id: 'YOUR_AVATAR_ID',
}).catch((e) => console.error('Initialization failed:', e.message));
jsx
import { useEffect, useState } from 'react';

function App() {
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    const SDK = window.KlleonSDK;
    SDK.init({
      sdk_key: 'YOUR_SDK_KEY',
      avatar_id: 'YOUR_AVATAR_ID',
    })
      .catch((e) => {
        setFailed(true);
        console.error('Initialization failed:', e.message);
      });

    return () => {
      // This callback cannot wait for the async shutdown to complete, so it only starts it
      SDK.destroy();
    };
  }, []);
}

4. Send a Message ​

Send after the status becomes CONNECTED_FINISH. Calls in the disconnected (IDLE) state are ignored without throwing and only log a warning. Behavior of calls made while a connection is in progress is not guaranteed, so check the status before calling or disable the send UI.

js
if (SDK.getStatus() === 'CONNECTED_FINISH') {
  SDK.sendMessage('Hello');
}
jsx
// status comes from onStatus in step 2, failed from the init() catch in step 3
const isReady = status === 'CONNECTED_FINISH';
const label = failed ? 'Connection failed' : isReady ? 'Ready to chat' : 'Connecting';

return (
  <>
    <p>Status: {label}</p>
    <button
      onClick={() => window.KlleonSDK.sendMessage('Hello')}
      disabled={!isReady}
    >
      Send
    </button>
  </>
);

5. Shut Down the SDK ​

destroy() is an async function. await it to wait until the shutdown completes.

js
async function endSession() {
  await window.KlleonSDK.destroy();
}

Where await is not available — such as a React component's cleanup callback — you can only start the shutdown request.

Voice Input ​

js
window.KlleonSDK.startListening(); // Start STT
window.KlleonSDK.endListening();   // End STT

Full Example ​

html
<!DOCTYPE html>
<html>
<head>
  <script src="https://klleon.k1.klleon.io/{VERSION}/klleon-sdk.umd.js"></script>
</head>
<body>
  <avatar-container style="width: 400px; height: 600px;"></avatar-container>
  <chat-container></chat-container>

  <script>
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => {
      console.log('Status:', status);
    });

    SDK.onSignal((data) => {
      if (data.signal === 'RESPONSE_TEXT') {
        console.log('Avatar:', data.payload.text);
      }
    });

    SDK.onError((error) => {
      console.error('Error:', error.code, error.message);
    });

    (async () => {
      try {
        await SDK.init({
          sdk_key: 'YOUR_SDK_KEY',
          avatar_id: 'YOUR_AVATAR_ID',
        });
        SDK.sendMessage('Hello');
      } catch (e) {
        console.error('Initialization failed:', e.message);
      }
    })();
  </script>
</body>
</html>
jsx
import { useEffect } from 'react';

function App() {

  useEffect(() => {
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => console.log('Status:', status));
    SDK.onSignal((data) => console.log(data.signal, data.payload));
    SDK.onError((error) => console.error(error.code, error.message));

    SDK.init({
      sdk_key: 'YOUR_SDK_KEY',
      avatar_id: 'YOUR_AVATAR_ID',
    })
      .catch((e) => console.error(e.message));

    return () => {
      // This callback cannot wait for the async shutdown to complete, so it only starts it
      SDK.destroy();
    };
  }, []);

  return (
    <div>
      <avatar-container style={{ width: 400, height: 600 }} />
      <chat-container />
    </div>
  );
}

export default App;