Widget Not Showing or Not Connecting

Common Widget Issues at a Glance

The table below covers the most frequent widget problems, their likely causes, and the fastest fix for each.

Symptom	Likely Cause	Quick Fix
Widget does not appear at all	Embed script missing or placed incorrectly	Paste the script before the closing </body> tag
Widget appears on localhost but not production	Production domain not in allowed domains list	Add your production domain in widget settings
Widget disappears after a few seconds	Zero credit balance pauses Raya	Add credits or upgrade your plan
Widget hidden on certain browsers	Ad blocker or privacy extension blocking the script	Test in incognito mode with extensions disabled
Widget stuck on "Connecting..."	Network or CSP headers blocking WebSocket	Allow *.teammates.ai in your CSP connect-src directive

If Raya's chat widget does not appear on your website, work through these steps in order. Most issues resolve at step 1 or 2.

1
Verify the embed script is installed
Open your website, right-click, select "View Page Source", and search for "teammates". You should see a <script> tag with your widget ID. If it is missing, copy the snippet from Dashboard > Raya > Chat/Widget and paste it before </body>.
2
Check your allowed domains
Go to Dashboard > Raya > Chat/Widget settings and confirm your website domain is listed under "Allowed Domains". Include both www and non-www versions if needed (e.g., example.com and www.example.com).
3
Check your credit balance
Raya pauses when your credit balance hits zero. Go to Dashboard > Billing and confirm you have available credits. The free plan includes 10 credits per month.
4
Test in incognito mode
Open your website in an incognito/private window with all browser extensions disabled. If the widget appears, an ad blocker or privacy extension on your regular browser is blocking it.
5
Check page-level show/hide rules
In widget settings, review the show/hide rules. If you configured the widget to only appear on specific pages, confirm the current page matches your rules.

If the widget loads but stays on "Connecting..." without starting a conversation, the issue is usually network-related. Follow these steps.

1
Check your Content Security Policy (CSP)
If your website uses CSP headers, add *.teammates.ai to the connect-src and script-src directives. Without this, your browser blocks the WebSocket connection Raya needs.
2
Verify the Raya employee is active
Go to Dashboard > Raya and confirm the employee status is "Active". If the employee is disabled or deleted, the widget cannot connect.
3
Test from a different network
Some corporate firewalls block WebSocket connections. Try loading the page from a mobile hotspot or a different network. If it works, ask your IT team to allow outbound HTTPS and WebSocket traffic to *.teammates.ai.
4
Check the browser console
Open DevTools (F12) and look at the Console tab for red error messages. Common errors include "Refused to connect" (CSP issue) or "WebSocket connection failed" (network issue). Share these with support if needed.