How to Create a Public Chat for Your Website

This guide walks you through the complete process of creating a public AI chat for your website, from creating a site to embedding the chat widget. Follow these steps to enable visitors to chat with an AI assistant powered by your website's content.

Purpose

This guide provides step-by-step instructions for:

Creating a Clear Ideas Site
Importing content from your website
Configuring Public AI Chat settings
Creating access keys
Embedding the chat widget on your website
Troubleshooting common issues

Prerequisites

A Clear Ideas account with owner or admin access
A paid subscription (required for web import functionality)
Access to modify your website's HTML code
Your website's URL(s) ready for import

Step 1: Create a Site

The first step is to create a Clear Ideas Site that will store your website's content and power the public chat.

Creating a New Site

Log in to your Clear Ideas account
Click the "New Site" button (usually in the top navigation or dashboard)
Enter a Site Title that describes your website or organization
- Example: "My Company Website" or "Product Documentation"
Click Create to create the site

Your new site is now ready. You'll use this site to store content and configure the public chat.

Tip: Choose a descriptive name that makes it easy to identify this site later, especially if you plan to create multiple sites.

Step 2: Import Your Website Content

To power the public chat, you need to import content from your website into your Clear Ideas Site. You can do this in two ways:

Option A: Immediate Web Import (One-Time Import)

Use this method for a one-time import or to test import settings before creating a schedule.

Navigate to your Site in Clear Ideas
Click the Web Import button (globe pointer icon)
Enter the URL of your website (e.g., https://yourdomain.com)
Configure import options:
- URL Mask (Advanced): Optional pattern to limit which pages are imported
  - Example: https://yourdomain.com/docs/* - Only import pages under /docs/
- Follow Link Depth: Controls how many levels of links to follow
  - 1 Level: Only the current page
  - 2 Levels: Current page plus all links found on that page
  - 3 Levels: Current page plus two levels of linked pages
- File Types: Choose which content types to import
  - HTML: Import HTML pages and content
  - PDF: Import PDF files linked from the pages
Select the destination folder (defaults to Site root)
Click Import to start the import immediately

Note: Web imports consume AI Credits. The amount depends on the size and complexity of your website.

Option B: Scheduled Web Import (Automatic Recurring Imports)

Set up automatic imports that run on a schedule to keep your content synchronized with your website.

Navigate to Site Settings > Web Import Schedules
Click Create Scheduled Import
Enter the URL and configure import options (same as immediate import)
Enable the Schedule option
Configure the schedule:
- Frequency: Hourly, Daily, Weekly, or Monthly
- Time: Specific hour and minute to run (24-hour format, e.g., 09:00 for 9:00 AM)
- Days: Days of the week (for weekly) or days of the month (for monthly)
Select the destination folder
Click Create to save the schedule

Best Practices:

Start with a depth of 1 to test imports before increasing
Use URL masks to limit imports to relevant sections
Match schedule frequency to how often your website updates
Weekly or monthly schedules are common for documentation sites

Important: Scheduled imports also consume AI Credits each time they run. Monitor your AI usage to ensure you have sufficient credits.

Step 3: Configure Public AI Chat Settings

Once you have content in your Site, configure the Public AI Chat settings to customize how the chat behaves.

Accessing Public AI Chat Settings

Navigate to your Site
Go to Site Settings > Public AI Chat Settings

Required Settings

Enable Public AI Chat

Toggle Enable Public AI Chat to ON
This enables the public chat feature for your site

Allowed Origins

Add the website origins (URLs) where the public chat can be embedded. This is a security feature that ensures only authorized websites can use your chat.

In the Allowed Origins section, enter your website's URL
- Include the protocol: https://yourdomain.com or http://localhost:3000 (for testing)
Click Add to add the origin
Add additional origins as needed:
- https://www.yourdomain.com (if you use www)
- https://*.yourdomain.com (wildcard for all subdomains)
- http://localhost:3000 (for local development)

Important:

Each origin must include the protocol (http:// or https://)
Wildcard subdomains are supported (e.g., https://*.yourdomain.com)
At least one allowed origin is required when Public AI Chat is enabled
CORS changes can take up to 60 seconds to propagate after adding a new origin

Basic Configuration

Chat Name

The name of your chat assistant that appears to visitors.

Default: "Clear Ideas Public AI Chat Bot"
Example: "Support Assistant" or "Documentation Helper"

Chat Tagline

A short tagline or subtitle displayed alongside the chat name.

Example: "Your friendly AI assistant" or "Ask me anything about our products"

Hero Greeting

A prominent greeting message shown when the public chat first opens.

Example: "Welcome! I'm here to help you find exactly what you need."

Initial Greeting

The first message shown to visitors when they start a chat. Use {{chatName}} to insert the chat name dynamically.

Default: "Hi, I'm {{chatName}}. How can I help?"
Example: "Hello! I'm {{chatName}}. How can I assist you today?"

AI Behavior Customization

Brand Voice

Instructions that define how the AI should communicate. Specify tone, style, formality level, and personality.

Example: "Friendly, professional, and concise. Use simple language and avoid jargon. Always be helpful and empathetic."

Audience

Description of your target audience to help the AI tailor responses appropriately.

Example: "Small business owners with limited technical knowledge" or "Enterprise IT administrators"

Answer Length

Preferred length for AI responses. Choose from:

Brief: Short, concise answers
Concise: Moderately detailed responses
Detailed: Comprehensive explanations
Comprehensive: Extensive, thorough responses

Terminology

Custom terms or phrases the AI should use consistently. Add terms to maintain consistent language across your brand.

Example: Add terms like "AI Assistant", "Knowledge Base", or "Support Portal"

Disallowed Topics

Topics the AI should avoid or decline to discuss. The AI will politely redirect conversations away from these topics.

Example: Add topics like "pricing", "refunds", or "competitor comparisons"

Lead Capture Configuration

Meeting Link

URL to a meeting scheduler or calendar booking page. Can be included in lead capture responses.

Example: https://calendly.com/yourcompany/demo

Notification Users

Users to receive notifications when a lead is captured. Only site admins and the site owner can be selected. Maximum of 10 users.

Click the Select Users dropdown
Select users who should receive lead capture notifications
Selected users will receive notifications immediately when a visitor provides their information

Voice Chat Configuration

Enable voice-based Q&A functionality for visitors who prefer speaking over typing.

Enable Voice Chat

Toggle Enable Voice Chat to ON
Important: You must also create an access key with the public_chat:voice scope (see Step 4)

Text-to-Speech Voice

Select the voice used for converting AI text responses to audio. Choose from:

Alloy: Balanced, neutral voice
Echo: Clear, confident voice
Fable: Warm, expressive voice
Onyx: Deep, authoritative voice
Nova: Bright, energetic voice
Shimmer: Soft, gentle voice

Note: Voice chat requires user consent for microphone access. Visitors must grant permission when prompted by their browser.

Styling and UI Configuration

Accent Color

Primary accent color for the public chat interface. Can be specified as hex or RGB.

Hex example: #2866cf
RGB example: rgb(40, 102, 207)

Theme Mode

Color theme mode for the public chat:

System: Automatically match the user's system preference (default)
Light: Always use light theme
Dark: Always use dark theme

Quick Links

Quick links that appear in the public chat when it opens. Maximum of 4 links. Each link includes:

Title: Display text for the link (required)
Description: Additional context or description (optional)
URL: Full URL to navigate to (must start with http:// or https://)

Example links:

Title: "Documentation", Description: "Browse our guides", URL: https://yourdomain.com/docs
Title: "Contact Support", Description: "Get help", URL: https://yourdomain.com/support

Save Settings

After configuring all settings, click Save Public AI Chat Settings to apply your changes.

Step 4: Create an Access Key

Access keys authenticate your website with the Clear Ideas API. You need to create a widget-type access key with the appropriate scopes.

Understanding Access Key Scopes

Access keys use scopes to control permissions. Each scope enables specific functionality:

public_chat:send: Required for text chat functionality. Allows sending text messages and initializing chat conversations. This scope is required for all Public AI Chat implementations.
public_chat:voice: Required for voice chat functionality. Allows sending voice messages and receiving audio responses. This scope must be included in addition to public_chat:send if you want to enable voice chat.

Important: To enable voice chat, you must:

Enable voice chat in Public AI Chat settings (completed in Step 3)
Create an access key that includes the public_chat:voice scope

Creating an Access Key

In Site Settings > Public AI Chat Settings, scroll to the Public AI Chat Access Keys section
Click Create Access Key
Select the scopes you need:
- Text Chat: Select public_chat:send (required for all implementations)
- Voice Chat: Select public_chat:voice (required if voice chat is enabled)
Click Create Access Key
IMPORTANT: Copy the key immediately—this is the only time it is shown in full

Security Best Practices:

Store access keys securely (use environment variables or secure configuration management)
Never commit access keys to version control
Use different access keys for different environments (development, staging, production)
Rotate keys regularly for security

Viewing Installation Code

After creating an access key, you can view the installation code snippet:

In the Public AI Chat Access Keys section, find your access key
Click Install to view the installation code
The code snippet will be displayed with your access key already included

Note: If you lose your access key, you'll need to create a new one. The key is only displayed once when created.

Step 5: Get the Installation Code Snippet

The installation code snippet contains everything you need to embed the public chat on your website.

Accessing the Installation Code

Navigate to Site Settings > Public AI Chat Settings
Scroll to Public AI Chat Access Keys
Find your access key and click Install
The installation dialog will show:
- The complete code snippet
- Step-by-step instructions

Code Snippet Format

The installation code looks like this:

<link rel="stylesheet" href="https://updates.clearideas.com/chat.css">

<script src="https://updates.clearideas.com/chat.js"></script>

<script>
  const widget = window.ClearIdeasWidget.init({
    accessKey: 'your-access-key-here'
  });
</script>

Important: The code snippet will already include your actual access key. Make sure to copy the complete snippet.

Step 6: Embed the Code Snippet on Your Website

Now that you have the installation code, add it to your website.

Where to Add the Code

Add the code snippet to your website's HTML in the <head> section. This ensures the chat widget loads properly on all pages.

Step-by-Step Instructions

Copy the code snippet from the installation dialog
Open your website's HTML template or main layout file
Locate the <head> section of your HTML
Paste the code snippet into the <head> section
Save and deploy your website changes
Test the integration by visiting your website

Example HTML Structure

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
  
  <!-- Your existing head content -->
  
  <!-- Public AI Chat Widget -->
  <link rel="stylesheet" href="https://updates.clearideas.com/chat.css">
  
  <script src="https://updates.clearideas.com/chat.js"></script>
  
  <script>
    const widget = window.ClearIdeasWidget.init({
      accessKey: 'your-access-key-here'
    });
  </script>
</head>
<body>
  <!-- Your website content -->
</body>
</html>

Platform-Specific Instructions

WordPress

WordPress offers several methods to add the public chat widget. Choose the method that works best for your setup:

Method 1: Using a Plugin (Recommended)

The easiest way is to use a plugin that allows you to insert code into the header:

Install and activate a plugin like "Insert Headers and Footers" or "Code Snippets"
Navigate to the plugin settings (usually under Settings or Tools)
Paste the code snippet into the Header section
Save changes

Method 2: Using Theme Editor

If you have direct access to your theme files:

Go to Appearance > Theme Editor
Select your active theme's header.php file
Find the </head> tag
Paste the code snippet just before the closing </head> tag
Click Update File

Method 3: Using WordPress Customizer

Some themes support adding code via the Customizer:

Go to Appearance > Customize
Look for Additional CSS or Header/Footer Code options
Add the code snippet to the header section
Click Publish

Important Notes for WordPress:

Always use a child theme when editing theme files directly to prevent losing changes during theme updates
Test the chat widget after adding it to ensure it loads correctly
If using a caching plugin, clear your cache after adding the code
Consider using the plugin method for easier maintenance and to avoid theme update conflicts

React/Next.js

Add to pages/_app.js or app/layout.js:

import Head from 'next/head'

export default function App({ Component, pageProps }) {
  return (
    <>
      <Head>
        <link rel="stylesheet" href="https://updates.clearideas.com/chat.css" />
        <script src="https://updates.clearideas.com/chat.js"></script>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              const widget = window.ClearIdeasWidget.init({
                accessKey: 'your-access-key-here'
              });
            `,
          }}
        />
      </Head>
      <Component {...pageProps} />
    </>
  )
}

Vue/Nuxt

Add to nuxt.config.ts:

export default defineNuxtConfig({
  app: {
    head: {
      link: [
        { rel: 'stylesheet', href: 'https://updates.clearideas.com/chat.css' }
      ],
      script: [
        { src: 'https://updates.clearideas.com/chat.js' },
        {
          innerHTML: `
            const widget = window.ClearIdeasWidget.init({
              accessKey: 'your-access-key-here'
            });
          `
        }
      ]
    }
  }
})

Static HTML

Simply paste the code snippet into your HTML file's <head> section.

Advanced Configuration

For advanced features like consent management, programmatic control, custom positioning, and dynamic configuration updates, see the Advanced Embedding Settings guide.

Troubleshooting and FAQ

CORS Issues

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

Solutions:

Verify your domain is in allowed origins: Go to Site Settings > Public AI Chat Settings and check that your domain is listed in Allowed Origins
Check the exact domain: Ensure the domain matches exactly, including https:// and www. if applicable
- If your site uses https://www.yourdomain.com, add that exact origin
- If your site uses https://yourdomain.com, add that exact origin
- Consider adding both if you redirect between them
Wait for propagation: CORS changes can take up to 60 seconds to propagate. Wait a minute after adding a new origin and try again
Check browser console: Look at the browser console for the exact origin being blocked
Verify access key: Ensure you're using the correct access key for the Site

Common Mistakes:

Forgetting to include the protocol (https:// or http://)
Adding www. when your site doesn't use it (or vice versa)
Not waiting for CORS propagation after adding an origin

Content Security Policy (CSP) Issues

If your website uses Content Security Policy headers, you need to allow the Clear Ideas chat widget resources.

Required CSP Directives:

Add these directives to your Content Security Policy:

script-src 'self' https://updates.clearideas.com;
style-src 'self' 'unsafe-inline' https://updates.clearideas.com;
connect-src 'self' https://api.clearideas.com wss://*.clearideas.com;
img-src 'self' data: https:;

Note: The widget inherits fonts from your website using font-family: inherit. If your website uses Google Fonts or other external font sources, you'll need to include those in your CSP font-src directive. For example, if using Google Fonts:

font-src 'self' https://fonts.googleapis.com https://fonts.gstatic.com;

The widget itself doesn't load external fonts, but it will inherit any fonts loaded by your website.

Complete CSP Example:

Content-Security-Policy: 
  default-src 'self';
  script-src 'self' https://updates.clearideas.com;
  style-src 'self' 'unsafe-inline' https://updates.clearideas.com;
  connect-src 'self' https://api.clearideas.com wss://*.clearideas.com;
  img-src 'self' data: https:;
  font-src 'self' https://fonts.googleapis.com https://fonts.gstatic.com;

Note: The font-src directive above includes Google Fonts as an example. Adjust based on the fonts your website uses. If your website doesn't use external fonts, you can omit font-src or use font-src 'self'.

Where to Add CSP:

Apache: Add to .htaccess or Apache configuration
Nginx: Add to server block configuration
Cloudflare: Use Page Rules or Transform Rules

Meta Tag: Add to HTML <head>:

<meta http-equiv="Content-Security-Policy" content="script-src 'self' https://updates.clearideas.com; style-src 'self' 'unsafe-inline' https://updates.clearideas.com; connect-src 'self' https://api.clearideas.com wss://*.clearideas.com; img-src 'self' data: https:; font-src 'self' https://fonts.googleapis.com https://fonts.gstatic.com;">

Note: Adjust the font-src directive based on the fonts your website uses. If you don't use Google Fonts, remove those domains or use font-src 'self' only.

Testing CSP:

Check browser console for CSP violation errors
Use browser developer tools to see which resources are being blocked
Test in different browsers as CSP enforcement can vary

Invalid Access Key

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

Solutions:

Verify the access key is correct: Check that you copied the complete key without any extra spaces or characters
Check key status: Ensure the access key is active (not revoked or expired)
- Go to Site Settings > Public AI Chat Settings > Public AI Chat Access Keys
- Check the status of your key
Verify Site match: Ensure the access key is for the correct Site
Check scopes: Verify the access key has the required scopes:
- public_chat:send (required for text chat)
- public_chat:voice (required if voice chat is enabled)
Create a new key: If the key is lost or compromised, create a new access key

Public Chat Not Appearing

Problem: Public chat doesn't appear on the page

Solutions:

Check browser console: Look for JavaScript errors that might prevent the widget from loading
Verify files are loading: Check Network tab in browser developer tools to ensure:
- https://updates.clearideas.com/chat.css loads successfully
- https://updates.clearideas.com/chat.js loads successfully
Check initialization: Ensure the initialization code runs after the page loads
- For data attribute method, ensure data-clearideas-chat attribute is present
- For JavaScript method, ensure the script runs after the page loads
Verify Public AI Chat is enabled: Go to Site Settings > Public AI Chat Settings and ensure "Enable Public AI Chat" is toggled ON
Check access key: Verify the access key is valid and active
Check allowed origins: Ensure your website's domain is in the allowed origins list

Voice Chat Not Working

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

Solutions:

Verify voice chat is enabled: Go to Site Settings > Public AI Chat Settings and ensure "Enable Voice Chat" is toggled ON
Check access key scopes: Critical - Ensure your access key includes the public_chat:voice scope. This is required in addition to enabling voice chat in settings
Check microphone permission: Ensure the user has granted microphone permission in their browser
- Users must click "Allow" when prompted by their browser
- This is a browser security requirement and cannot be bypassed
Verify HTTPS: Ensure your website is served over HTTPS (required for microphone access)
Test in different browsers: Some browsers have stricter permission requirements
Check browser console: Look 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.

Network Errors

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

Solutions:

Check internet connection: Verify your internet connection is working
Verify API URL: Ensure the API base URL is correct (https://api.clearideas.com)
Check firewall/network restrictions: Ensure your network or firewall isn't blocking API requests
Verify Site status: Ensure the Site has Public AI Chat enabled
Check browser console: Look for detailed error messages that might indicate the specific issue

Styling Issues

Problem: Public chat styling doesn't match your website

Solutions:

Verify CSS is loading: Check that https://updates.clearideas.com/chat.css loads correctly
Check for CSS conflicts: Your website's CSS might be conflicting with the chat widget styles
- Use browser developer tools to inspect the chat widget
- Check for CSS specificity issues
Use custom accent color: Configure an accent color in Public AI Chat settings to match your brand
Test theme modes: Try different theme mode settings (system, light, dark) to see which works best
Check browser compatibility: Test in different browsers as CSS rendering can vary

Chat Not Responding or Slow Responses

Problem: Chat doesn't respond or responses are slow

Solutions:

Check Site content: Ensure your Site has content imported and indexed
Verify content indexing: Go to Site Settings > Content Indexing to ensure content is being indexed
Check AI Credits: Ensure you have sufficient AI Credits available
Review import status: Check that web imports completed successfully
Test with simple questions: Try asking simple questions to see if the issue is specific to certain queries

Access Key Only Displayed Once

Problem: I lost my access key and can't find it

Solutions:

Create a new access key: Go to Site Settings > Public AI Chat Settings > Public AI Chat Access Keys and create a new key
Update your website: Replace the old access key in your website's code with the new key
Revoke the old key: If you suspect the old key was compromised, revoke it to prevent unauthorized access

Prevention:

Always copy and save access keys immediately when created
Store keys securely (use environment variables or secure configuration management)
Never commit access keys to version control

Best Practices

Security

Store access keys securely: Use environment variables or secure configuration management
Never commit keys to version control: Add access keys to .gitignore if storing in files
Use different keys for different environments: Create separate keys for development, staging, and production
Rotate keys regularly: Create new keys periodically and revoke old ones
Monitor key usage: Check "Last Used" dates in the access keys list to identify unused or suspicious activity

Configuration

Test before going live: Test the public chat on a staging or development environment first
Start with basic settings: Begin with default settings and customize gradually
Monitor AI usage: Keep track of AI Credits consumption, especially with scheduled imports
Keep content up to date: Use scheduled imports to keep your Site content synchronized with your website

User Experience

Customize greetings: Write clear, friendly greetings that set expectations
Configure brand voice: Provide specific instructions about tone and style
Add quick links: Include links to important pages like documentation or support
Test on multiple devices: Ensure the chat works well on desktop, tablet, and mobile devices
Monitor lead captures: Respond promptly to leads captured through the chat

Performance

Optimize imports: Use URL masks and appropriate depth settings to avoid importing unnecessary content
Monitor import schedules: Check that scheduled imports are running successfully
Review content organization: Organize imported content into folders for better context retrieval

Next Steps

After successfully embedding the public chat:

Test thoroughly: Try different types of questions to ensure the chat responds appropriately
Monitor usage: Check analytics and lead captures to understand how visitors are using the chat
Iterate on settings: Adjust brand voice, greetings, and other settings based on user feedback
Keep content updated: Ensure scheduled imports are running and keeping content current
Gather feedback: Ask visitors for feedback on the chat experience and make improvements

Public AI Chat - Detailed configuration guide for all Public AI Chat settings
Embedding Public AI Chat - Technical guide for embedding the chat widget
Web Import - Learn more about importing content from websites
Creating a Site - Learn more about creating and managing Sites
Access Keys - General guide to access key management