Common issues and solutions for widget integration and usage.
Running into issues? You're in the right place. This guide covers the most common problems developers encounter when integrating the widget, along with step-by-step solutions. Most issues can be resolved in just a few minutes.
🔍 Quick Debugging Tip
Open your browser's Developer Console (F12) before troubleshooting. Most widget errors will display clear messages in the console that point directly to the problem.
If the widget doesn't appear at all on your page, follow these troubleshooting steps in order:
Error: "Widget not configured" (with details about each missing data-* attribute)
Check browser console for this error message.
Ensure all required data attributes are present on the script tag:
<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>Error: "Authentication required" or "Invalid credentials"
Widget fails to authenticate with the API. This typically happens when credentials are incorrect or expired.
Authentication issues are usually straightforward to fix. Work through these checks:
client_id is correct in your OAuth application - Copy it directly from your dashboard to avoid typosStill stuck? Try creating a new OAuth application in your dashboard. Sometimes starting fresh resolves obscure configuration issues.
Error: "Origin not allowed" or widget token request rejected
Common when embedding in an iframe and the host domain is not listed in OAuth allowed origins.
Validation tip: Check the browser network tab for the token request headers and compare X-Embed-Origin with your OAuth allowed_origins entry.
Button positioning issue
Widget loads but the button is outside viewport.
position: fixedoverflow: hiddenIf hide_on_mobile is enabled in configuration, the widget will be hidden on mobile devices. Disable this setting or adjust the mobile breakpoint.
Visual problems are common and usually easy to fix. The widget is designed to be visually isolated from your page, but sometimes conflicts can occur.
Follow these steps to diagnose color issues:
Debug tip: Open the widget in your browser and use the inspect element tool to verify which CSS values are actually being applied. This will show you if your colors are loading or being overridden.
When the widget loads correctly but features don't work as expected, these solutions will help.
Network error, timeout, or session expired
User types a message and clicks send, but nothing happens or an error appears. Check browser network tab for failed requests (should show as red in the network tab).
Message sending issues usually relate to network connectivity or expired sessions. Diagnose systematically:
Quick test: If messages work in an incognito window but not in your normal browser, the issue is likely related to browser extensions or cached authentication data.
The widget requires modern browser features:
Minimum supported browsers: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
When you need additional assistance beyond this guide, these tools and resources will help you diagnose issues or get support.
Enable debug mode to see detailed logging in your browser console. This provides insights into what the widget is doing at each step:
<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-dev="true"></script>Still having issues?
Check our configuration guide or contact support with your browser console logs and configuration details.