Clik Agent Widget Embed

Javascript library to display Clik Agent Embed on your website

Installation

Include the widget script in your HTML:

<script type="module">
  import Agent from 'https://unpkg.com/@clikvn/external-agent-widget-embedded/dist/web.js';
  Agent.initWidget({
    apiHost: 'https://ci-api.clik.vn/chatbot',
    agentId: '6d02b23f-465f-44ec-8766-27a82890a9b8',
  });
</script>
<clik-agent-widget></clik-agent-widget>

Configuration

Basic Configuration

Agent.initWidget({
  apiHost: string;        // Required: API host URL
  agentId: string;        // Required: Agent ID
  id?: string;            // Optional: Custom element ID
});

Full Configuration Options

Agent.initWidget({
  // Required
  apiHost: string;        // API host URL (e.g., 'https://api.clik.vn/chatbot')
  agentId: string;        // Agent ID (e.g., '6d02b23f-465f-44ec-8766-27a82890a9b8')
  
  // Optional: Voice configuration
  voice?: {
    enable?: boolean;      // Enable voice features
    livekitUrl: string;   // LiveKit WebSocket URL
  };
  
  // Optional: Override configuration
  overrideConfig?: {
    chatId?: string;      // Existing chat ID to continue conversation
    overrideConfig?: Record<string, unknown>;  // Additional config overrides
    suggestedActions?: Array<{
      title?: string;     // Action title
      label?: string;     // Action label
      action?: string;    // Action command
    }>;
    skipSuggestion?: boolean;  // Skip showing suggestions
  } & Record<string, unknown>;
  
  // Optional: Theme customization
  theme?: {
    useExternalVariables?: boolean;  // Use external CSS variables
    simplified?: boolean;            // Simplified UI mode
    welcomeMessage?: string;         // Custom welcome message
    noAutoplayMessage?: boolean;     // Disable autoplay for messages
    autoCloseAudioPlayer?: boolean;  // Auto-close audio player
    hideAudioMetadata?: boolean;     // Hide audio metadata
    avatar?: string;                 // Avatar image URL
    input?: {
      placeholder?: string;          // Input placeholder text
      recordingPlaceholder?: string; // Placeholder while recording
      transcribingPlaceholder?: string; // Placeholder while transcribing
    };
    overview?: {
      title: string;                 // Overview title (required if overview is used)
      description?: string;          // Overview description
    };
    buttons?: {
      textBtnSpeak?: string;         // Speak button text
      textBtnTalk?: string;           // Talk button text
      textBtnSubmit?: string;         // Submit button text
    };
  } & Record<string, unknown>;
  
  // Optional: Event listeners
  listeners?: {
    CONNECT?: (props: any) => void;
    DISCONNECT?: (props: any) => void;
    ON_HISTORY_LOADED?: (props: any) => void;
    ON_LINK_CLICK?: (props: any) => void;
    CMD_CALLBACK?: (props: any) => void;
    ON_NEW_CHAT?: (props: any) => void;
    ON_CLICK?: (props: any) => void;
    ON_START_RECORDING?: (props: any) => void;
    ON_CANCEL_RECORDING?: (props: any) => void;
    ON_FINISHED_RECORDING?: (props: any) => void;
    ON_SUBMIT_MESSAGE?: (props: any) => void;
    ON_FINISHED_SUBMITTING_MESSAGE?: (props: any) => void;
    ON_PLAY_AUDIO?: (props: any) => void;
    ON_PAUSE_AUDIO?: (props: any) => void;
    ON_ENDED_AUDIO?: (props: any) => void;
    ON_SUBMIT_USER_CONTACT?: (props: any) => void;
    ON_CHATBOX_TOGGLED?: (props: any) => void;
  };
  
  // Optional: Callback when widget is loaded
  onLoaded?: (tool: {
    setInput: (text?: string) => void;  // Programmatically set input text
  }) => void;
});

Examples

Basic Usage

<script type="module">
  import Agent from 'https://unpkg.com/@clikvn/external-agent-widget-embedded/dist/web.js';
  Agent.initWidget({
    apiHost: 'https://ci-api.clik.vn/chatbot',
    agentId: '6d02b23f-465f-44ec-8766-27a82890a9b8',
  });
</script>
<clik-agent-widget></clik-agent-widget>

With Custom Configuration

<script type="module">
  import Agent from 'https://unpkg.com/@clikvn/external-agent-widget-embedded/dist/web.js';
  Agent.initWidget({
    apiHost: 'https://ci-api.clik.vn/chatbot',
    agentId: '6d02b23f-465f-44ec-8766-27a82890a9b8',
    overrideConfig: {
      chatId: 'f6a855d2-7edc-4fb8-9dd3-74204aa1e2a2',
      skipSuggestion: true,
      overrideConfig: {
        vars: {
          TOUR_CODE: 'TOUR_K9EK76KTX7K4',
          LANGUAGE: 'VN',
        },
      },
    },
    theme: {
      simplified: true,
      autoCloseAudioPlayer: true,
      hideAudioMetadata: true,
      welcomeMessage: 'Welcome! How can I help you?',
      input: {
        placeholder: 'Type your message...',
      },
    },
    listeners: {
      ON_LINK_CLICK: (props) => {
        console.log('Link clicked:', props);
      },
      ON_NEW_CHAT: (props) => {
        console.log('New chat started:', props);
      },
    },
    onLoaded: (tool) => {
      // Use the tool to programmatically interact with the widget
      tool.setInput('Hello!');
    },
  });
</script>
<clik-agent-widget></clik-agent-widget>

With Voice Support

<script type="module">
  import Agent from 'http://localhost:3000/web.js';
  Agent.initWidget({
    apiHost: 'https://ci-api.clik.vn/chatbot',
    agentId: '6d02b23f-465f-44ec-8766-27a82890a9b8',
    voice: {
      enable: true,
      livekitUrl: 'wss://your-livekit-server.com',
    },
  });
</script>
<clik-agent-widget></clik-agent-widget>

With Custom Element ID

<script type="module">
  import Agent from 'http://localhost:3000/web.js';
  Agent.initWidget({
    id: 'my-custom-widget',
    apiHost: 'https://ci-api.clik.vn/chatbot',
    agentId: '6d02b23f-465f-44ec-8766-27a82890a9b8',
  });
</script>
<div id="my-custom-widget"></div>

API Methods

initWidget(config)

Initializes the widget with the provided configuration.

Parameters:

• config: AgentWidgetType & { id?: string } - Configuration object

Throws:

• Error if the widget element (<clik-agent-widget>) is not found in the DOM

destroy()

Destroys and removes the widget from the DOM.

import Agent from 'http://localhost:3000/web.js';
Agent.destroy();

Event Types

The following events are available for the listeners configuration:

• CONNECT - Fired when connection is established
• DISCONNECT - Fired when connection is lost
• ON_HISTORY_LOADED - Fired when chat history is loaded
• ON_LINK_CLICK - Fired when a link is clicked
• CMD_CALLBACK - Fired on command callback
• ON_NEW_CHAT - Fired when a new chat is started
• ON_CLICK - Fired on general click events
• ON_START_RECORDING - Fired when voice recording starts
• ON_CANCEL_RECORDING - Fired when voice recording is cancelled
• ON_FINISHED_RECORDING - Fired when voice recording finishes
• ON_SUBMIT_MESSAGE - Fired when a message is submitted
• ON_FINISHED_SUBMITTING_MESSAGE - Fired when message submission completes
• ON_PLAY_AUDIO - Fired when audio playback starts
• ON_PAUSE_AUDIO - Fired when audio playback is paused
• ON_ENDED_AUDIO - Fired when audio playback ends
• ON_SUBMIT_USER_CONTACT - Fired when user contact is submitted
• ON_CHATBOX_TOGGLED - Fired when chatbox is toggled open/closed

Tool API

When the widget is loaded, the onLoaded callback receives a tool object with the following methods:

setInput(text?: string)

Programmatically set the input text in the widget.

onLoaded: (tool) => {
  tool.setInput('Hello, I need help!');
}