LoginSign Up

Embedding Public AI Chat

Add Public AI Chat to your website using a simple CDN integration. No build step or complex setup required—just include the CSS and JavaScript files, and the public chat is ready to use.

Purpose

This document provides technical instructions for embedding Public AI Chat on your website. It covers CDN integration, configuration options, and troubleshooting common issues.

Scope

Covered

  • CDN-based integration method
  • Configuration options and initialization
  • HTML data attributes for automatic setup
  • JavaScript initialization method
  • Troubleshooting common errors

Not Covered

Prerequisites

  • Public AI Chat configured and enabled for your Site
  • Access key created for Public AI Chat with the correct scopes:
    • public_chat:send (required for text chat)
    • public_chat:voice (required if voice chat is enabled)
  • Website domain added to allowed origins in Public AI Chat settings
  • Access to modify your website's HTML

Important: If you plan to use voice chat, ensure your access key includes the public_chat:voice scope in addition to public_chat:send. Voice chat requires both the scope in the access key and voice chat enabled in Public AI Chat settings.

CDN Integration

The simplest way to add Public AI Chat is using the CDN method. All dependencies including Vue are bundled, so no build step is required.

Step 1: Load CSS and JavaScript

Add the following to your HTML page's <head> section:

<!-- Load Public AI Chat CSS -->
<link rel="stylesheet" href="https://cdn.clearideas.com/clearideas-chat/clearideas-chat.css">

<!-- Load Public AI Chat JavaScript (includes Vue and all dependencies) -->
<script src="https://cdn.clearideas.com/clearideas-chat/clearideas-chat.iife.js"></script>

Step 2: Initialize the Public Chat

Choose one of two initialization methods:

Method 1: HTML Data Attributes (Automatic)

Add a <div> element with data attributes. The public chat initializes automatically:

<div
  data-clearideas-chat
  data-access-key="your-access-key-here"
  data-api-base-url="https://api.clearideas.com"
  data-position="bottom-right"
  data-width="380"
  data-height="540"
></div>

Method 2: JavaScript Initialization

Use JavaScript to initialize the public chat programmatically:

<script>
  const chat = window.ClearIdeasChat.init({
    accessKey: 'your-access-key-here',
    apiBaseUrl: 'https://api.clearideas.com',
    position: 'bottom-right',
    width: 380,
    height: 540
  })
</script>

Configuration Options

Required Options

accessKey: Your Public AI Chat access key. Get this from Site Settings > Public AI Chat Settings > Public AI Chat Access Keys.

apiBaseUrl: The Clear Ideas API base URL. Use https://api.clearideas.com for production.

Optional Options

position: Where to position the public chat on the page. Options:

  • bottom-right (default)
  • bottom-left
  • top-right
  • top-left

width: Width of the public chat window in pixels. Default: 380

height: Height of the public chat window in pixels. Default: 540

openOnLoad: Whether to open the public chat automatically when the page loads. Default: false

placeholder: Placeholder text for the message input field

userName: Optional user name to associate with chat sessions

userEmail: Optional user email to associate with chat sessions

userId: Optional user ID to associate with chat sessions

voiceEnabled: Enable voice chat functionality. Default: false (uses Site configuration)

darkMode: Override dark mode detection. Set to true or false to force a specific theme

Complete Example

Here's a complete HTML example using data attributes:

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
  
  <!-- Load Public AI Chat CSS -->
  <link rel="stylesheet" href="https://cdn.clearideas.com/clearideas-chat/clearideas-chat.css">
  
  <!-- Load Public AI Chat JavaScript -->
  <script src="https://cdn.clearideas.com/clearideas-chat/clearideas-chat.iife.js"></script>
</head>
<body>
  <!-- Your website content -->
  
  <!-- Public AI Chat - Auto-initializes from data attributes -->
  <div
    data-clearideas-chat
    data-access-key="your-access-key-here"
    data-api-base-url="https://api.clearideas.com"
    data-position="bottom-right"
    data-width="380"
    data-height="540"
  ></div>
</body>
</html>

JavaScript API

When using JavaScript initialization, the init() function returns a chat instance with methods to control the public chat:

open(): Opens the public chat window

close(): Closes the public chat window

toggle(): Toggles the public chat open/closed state

sendMessage(content): Sends a message programmatically

destroy(): Removes the public chat from the page

Example:

const chat = window.ClearIdeasChat.init({
  accessKey: 'your-access-key-here',
  apiBaseUrl: 'https://api.clearideas.com'
})

// Open the chat when a button is clicked
document.getElementById('open-chat-button').addEventListener('click', () => {
  chat.open()
})

Security Considerations

CORS Configuration

Public AI Chat uses CORS (Cross-Origin Resource Sharing) to ensure only authorized websites can embed the chat. Your website's domain must be added to the allowed origins list in Public AI Chat settings.

Important: After adding a new origin, CORS changes can take up to 60 seconds to propagate. If you encounter CORS errors immediately after adding an origin, wait up to 60 seconds and try again.

Access Key Security

  • Store access keys securely
  • Never commit access keys to version control
  • Rotate access keys regularly
  • Revoke unused or compromised keys immediately
  • Use different access keys for different environments (development, staging, production)

Best Practices

  • Use HTTPS for your website to ensure secure communication
  • Validate that your domain is in the allowed origins list before embedding
  • Monitor access key usage for suspicious activity
  • Keep the Public AI Chat JavaScript and CSS files up to date

Troubleshooting

CORS Errors

Error: "Access to fetch at 'https://api.clearideas.com' from origin 'https://yourdomain.com' has been blocked by CORS policy"

Solutions:

  1. Verify your domain is added to the allowed origins list in Public AI Chat settings
  2. Ensure the domain matches exactly (including https:// and www. if applicable)
  3. Wait up to 60 seconds after adding a new origin—CORS changes can take time to propagate
  4. Check browser console for the exact origin being blocked
  5. Verify you're using the correct access key for the Site

Invalid Access Key

Error: "401 Unauthorized" or "Invalid access key"

Solutions:

  1. Verify the access key is correct and copied completely
  2. Check that the access key is active (not revoked or expired)
  3. Ensure the access key is for the correct Site
  4. Verify the access key has the required scopes:
    • public_chat:send (required for text chat)
    • public_chat:voice (required if voice chat is enabled)
  5. If voice chat isn't working, ensure the access key includes the public_chat:voice scope

Public Chat Not Appearing

Error: Public chat doesn't appear on the page

Solutions:

  1. Check browser console for JavaScript errors
  2. Verify CSS and JavaScript files are loading correctly
  3. Ensure the initialization code is executed after the page loads
  4. Check that data-clearideas-chat attribute is present (for data attribute method)
  5. Verify the access key is valid and the Site has Public AI Chat enabled

Voice Chat Not Working

Error: Voice chat button doesn't work or microphone access is denied

Solutions:

  1. Verify voice chat is enabled in Public AI Chat settings
  2. Check access key scopes: Ensure your access key includes the public_chat:voice scope. This is required in addition to enabling voice chat in settings
  3. Check that the user has granted microphone permission in their browser
  4. Ensure the website is served over HTTPS (required for microphone access)
  5. Test in different browsers—some browsers have stricter permission requirements
  6. Check browser console for permission-related errors

Important: Voice chat requires two things:

  • Voice chat enabled in Public AI Chat settings
  • An access key with the public_chat:voice scope

Both conditions must be met for voice chat to work.

Note: Voice chat requires explicit user consent for microphone access. Users must click "Allow" when prompted by their browser. This is a browser security requirement and cannot be bypassed.

Network Errors

Error: "Network error" or "Failed to fetch"

Solutions:

  1. Check internet connection
  2. Verify the API base URL is correct (https://api.clearideas.com)
  3. Check for firewall or network restrictions blocking API requests
  4. Verify the Site has Public AI Chat enabled
  5. Check browser console for detailed error messages

Styling Issues

Error: Public chat styling doesn't match your website

Solutions:

  1. Verify CSS file is loading correctly
  2. Check for CSS conflicts with your website's styles
  3. Use custom accent color in Public AI Chat settings to match your brand
  4. Test theme mode settings (system, light, dark)
  5. Check browser developer tools for CSS conflicts