Troubleshooting

Common issues and solutions to help you resolve problems with your OpenSpeechAI chat widget and agent configuration.

If your widget isn't showing up on your website after adding the script, here are the most common causes and solutions.

Script placement is incorrect - The widget script must be placed right before the closing </body> tag in your HTML. If it's in the <head> section or after the </body> tag, the widget won't load properly. Open your website's HTML and verify the script is in the correct location.

Widget ID is wrong - Double-check that you copied the complete script from the Widget tab. The widget ID in the script URL must match your agent's widget ID. If you recently created a new agent or regenerated the script, make sure you're using the latest version.

Browser cache is showing old version - Your browser might be caching an old version of your website without the widget. Clear your browser cache and hard refresh the page (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac). Try viewing your site in an incognito/private browsing window to bypass cache completely.

Content Security Policy blocking the script - Some websites use Content Security Policy (CSP) headers that block external scripts. If you have CSP enabled, you need to allow scripts from widget.openspeechai.com. Check with your web developer or hosting provider to update your CSP configuration.

Script URL is incorrect - Make sure the script URL starts with https://widget.openspeechai.com/widgets/chat-widget.js. Any typos or modifications to this URL will prevent the widget from loading.

Messages Not Sending

If your widget appears but messages aren't sending or you see errors, here's how to diagnose and fix the issue.

Origin not allowed - This is the most common cause. Your website's domain isn't in your allowed origins list. Open your browser's developer console (press F12) and look for errors mentioning "Origin not allowed" or "CORS error". To fix this, go to your agent's Widget tab, scroll to Allowed Origins, and add your website's domain. See the Widget Security guide for detailed instructions.

Network connectivity issues - Check your internet connection. If you're on a slow or unstable network, messages might fail to send. Try refreshing the page and sending the message again.

Browser console shows errors - Open your browser's developer console (F12) and check the Console tab for error messages. These errors often point directly to the problem. Copy the error message and contact support at shri@openspeechai.com if you can't resolve it.

Agent Not Responding Correctly

If your agent is giving incorrect, irrelevant, or unhelpful responses, the issue is usually in your agent configuration or knowledge base.

Knowledge base not connected - If your agent should be answering questions based on your documentation but isn't, check that a knowledge base is connected to your agent. Go to Agents, click your agent, click the Edit icon, and verify a knowledge base is selected in the dropdown.

System prompt is too vague - Generic instructions like "Be helpful" don't give your agent enough guidance. Your system prompt should be specific about the agent's role, tone, what it should and shouldn't do, and what information it has access to. See the Agent Configuration guide for detailed instructions and examples.

Temperature setting is wrong - If responses are too robotic and repetitive, your temperature might be too low. If responses are too creative or inconsistent, your temperature might be too high. Most agents work best between 0.3 and 0.5. Adjust the temperature in your agent's configuration and test the results.

Knowledge base content is outdated - If your agent is giving old information, your knowledge base might not reflect current content. Check when you last updated your knowledge base. If your website or documentation has changed, recrawl URLs or upload new files to keep your agent's knowledge current.

Knowledge Base Issues

Problems with adding content to your knowledge base or getting your agent to use that content correctly.

PDF files won't process - OpenSpeechAI supports PDFs with actual text content. Scanned PDFs or image-based PDFs won't work because they don't contain extractable text. If you have a scanned document, use OCR software to convert it to a text-based PDF first, or save the content as a TXT file instead.

Website crawling is blocked - Some websites use Cloudflare or other security services that block automated crawling. If OpenSpeechAI can't access your website, you have two options: whitelist OpenSpeechAI's crawling service with your security provider, or export your website content as PDF or TXT files and upload them directly instead.

Content not updating after recrawl - After recrawling a URL, the old content is replaced with the new version. If you're still seeing outdated responses, make sure you recrawled the correct URL and that the recrawl completed successfully. Check the knowledge base files table to verify the update timestamp.

Files are too large - Very large files (over 10MB) may take longer to process or fail entirely. If you have large PDFs, consider splitting them into smaller sections by topic or chapter. This also makes it easier for your agent to find relevant information quickly.

Customization Not Showing

If you changed your widget's appearance or settings but don't see the updates on your website.

Changes weren't saved - After making changes in the Widget tab, you must click the Save Changes button at the bottom. If you navigated away without saving, your changes were discarded. Make your changes again and verify the "Settings updated successfully" message appears.

Browser cache is showing old widget - Your browser might be displaying a cached version of the widget. Clear your browser cache and hard refresh the page (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on Mac). The updated widget should appear after refreshing.

Widget script not updated - If you regenerated your widget script or changed widget IDs, make sure you copied the new script from the Widget tab and replaced the old one on your website. The widget ID in your website's script must match the current widget ID.

Checking Browser Console

Many issues can be diagnosed by checking your browser's developer console. Here's how to access it and what to look for.

To open the developer console, press F12 on your keyboard (or right-click anywhere on your page and select "Inspect" or "Inspect Element"). Click the Console tab to see error messages and warnings.

Look for messages in red - these are errors. Common error messages include:

Origin not allowed or CORS error - Your domain isn't in allowed origins
Failed to load resource - The widget script couldn't load from the server
Refused to load script - Content Security Policy is blocking the widget

Copy any error messages you see. These help identify the exact problem and are useful if you need to contact support.

Getting Help

If you've tried these troubleshooting steps and still can't resolve your issue, contact support at shri@openspeechai.com.

When reaching out, include:

A description of the problem and what you're trying to do
Your website URL where the widget should appear
Any error messages from the browser console
What troubleshooting steps you've already tried

The more details you provide, the faster we can help you resolve the issue.

Last updated: November 18, 2024

Widget Not Appearing on Website