@cagent/chat-embedding-core

v0.0.2

Published

10 days ago

Javascript library to display the Agent Studio chatbot on your website

Downloads

414

0High
0Medium
0Low

dccxx

Agent Studio Embed

Javascript library to display the Agent Studio chatbot on your website

Install:

bun install --frozen-lockfile

Dev:

bun run dev

A development server will be running on http://localhost:5678 automatically. Update public/index.html to connect directly to your backend:

<!-- public/index.html -->
<script type="module">
  import Chatbot from 'https://localhost:5678/web.js'; // Change to from './web.js' to 'https://localhost:5678/web.js'
  Chatbot.init({
    chatflowid: '91e9c803-5169-4db9-8207-3c0915d71c5f', // Add your chatflowid
    apiHost: 'https://your-backend-instance.com', // Add your apiHost
  });
</script>

Build:

bun run build

Embed in your HTML

PopUp

<script type="module">
  import Chatbot from 'https://cdn.jsdelivr.net/npm/@cagent/chat-embedding-core@latest/dist/web.js';
  Chatbot.init({
    chatflowid: '<chatflowid>',
    apiHost: 'http://localhost:3000',
  });
</script>

FullPage

<script type="module">
  import Chatbot from 'https://cdn.jsdelivr.net/npm/@cagent/chat-embedding-core@latest/dist/web.js';
  Chatbot.initFull({
    chatflowid: '<chatflowid>',
    apiHost: 'http://localhost:3000',
  });
</script>
<cagent-fullchatbot></cagent-fullchatbot>

To enable full screen, add margin: 0 to body style, and confirm you don't set height and width

<body style="margin: 0">
  <script type="module">
    import Chatbot from 'https://cdn.jsdelivr.net/npm/@cagent/chat-embedding-core@latest/dist/web.js';
    Chatbot.initFull({
      chatflowid: '<chatflowid>',
      apiHost: 'http://localhost:3000',
      theme: {
        chatWindow: {
          // height: 700, don't set height
          // width: 400, don't set width
        },
      },
    });
  </script>
</body>

Configuration

You can also customize chatbot with different configuration

<script type="module">
  import Chatbot from 'https://cdn.jsdelivr.net/npm/@cagent/chat-embedding-core/dist/web.js';
  Chatbot.init({
    chatflowid: '91e9c803-5169-4db9-8207-3c0915d71c5f',
    apiHost: 'http://localhost:3000',
    chatflowConfig: {
      // topK: 2
    },
    theme: {
      disclaimer: {
        title: 'Disclaimer',
        message: 'By using this chatbot, you agree to the <a target="_blank" href="#">Terms & Condition</a>',
      },
      chatWindow: {
        showTitle: true,
        title: 'Agent Studio Bot',
        welcomeMessage: 'Hello! This is custom welcome message',
        textInput: {
          placeholder: 'Type your question',
          sendMessageSound: true,
          receiveMessageSound: true,
        },
        footer: {
          text: 'Powered by',
          company: 'Agent Studio',
          companyLink: '#',
        },
      },
    },
  });
</script>

(Experimental) Proxy Server Setup

The proxy server enhances the security of your chatbot implementation by acting as a protective intermediary layer. It removes the need to expose sensitive backend instance details in your frontend code and provides several key security benefits:

Enhanced Security: Conceals your API host and chatflow IDs from client-side exposure
Access Control: Implements strict domain-based restrictions for chatbot embedding
Secure Communication: Acts as a secure gateway for all interactions between your website and the backend instance
Authentication Management: Handles API key authentication securely on the server side, away from client exposure

This proxy server can be deployed to any Node.js hosting platform.

Quick Start

Configure environment:

# Copy .env.example to .env and configure required settings:
API_HOST=https://your-backend-instance.com
CAGENT_API_KEY=your-api-key

# Configure your chatflows:
# Format: [identifier]=[chatflowId],[allowedDomain1],[allowedDomain2],...
#
# identifier: Any name you choose (e.g., agent1, support, salesbot)
# chatflowId: The UUID of your chatflow
# allowedDomains: Comma-separated list of domains where this chat can be embedded
#
# Examples:
support=abc123-def456,https://example.com
agent1=xyz789-uvw456,https://sales.example.com
helpdesk=ghi123-jkl456,https://help.example.com,https://support.example.com

Install dependencies: (assuming you did not run bun install yet)

bun install

Start proxy server:

bun run start
# Server will be available at:
# - Local:  http://localhost:3001
# - Cloud:  [Your Platform URL]

Once the proxy server is running in production, you will be able to embed your chatbots safely without exposing your API host and chatflow IDs:

<script type="module">
  import Chatbot from 'your-proxy-server-url/web.js'; // Must be 'your-proxy-server-url/web.js'
  Chatbot.init({
    chatflowid: 'your-identifier-here', // Must match an identifier from your .env
    apiHost: 'your-proxy-server-url', // Must match the URL of your proxy server
  });
</script>

Important Notes:

To ensure secure embedding, you must explicitly whitelist the websites authorized to embed each chatbot. This configuration is done within the .env file. This also applies to your server's URL when deployed to a cloud environment, or http://localhost:3001 for local development.
Wildcard domains (*) are not supported for security reasons
Identifiers are case-insensitive (e.g., 'Support' and 'support' are treated the same)

Cloud Deployment Requirements

When deploying to cloud platforms, you must configure the environment variables directly in your platform. The proxy server will not start without these variables being properly set.

Development Mode (For Local Testing)

For full page testing, use this configuration:

<!-- public/index.html -->
<cagent-fullchatbot></cagent-fullchatbot>
<script type="module">
  import Chatbot from './web.js';
  Chatbot.initFull({
    chatflowid: 'agent1', // Must match an identifier from your .env
    apiHost: 'http://localhost:3001',
  });
</script>

Note: The development URL (http://localhost:5678) is automatically added to allowed domains in development mode.

License

Source code in this repository is made available under the MIT License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme