Troubleshooting Common Issues

Troubleshooting Common Issues

Widget Not Appearing

Check your API key. Ensure the apiKey in Helpium.init() matches the widget key in Settings → Channels → Widget.

Check the script URL. The widget script URL should point to your Helpium workspace. Verify there are no typos.

Check your browser console. Open Developer Tools (F12) and look for errors in the Console tab. Common issues:

• 404 on the widget script — wrong URL
• 401 Unauthenticated — invalid API key
• CORS errors — contact support if you see these

Content Security Policy (CSP). If your site uses a strict CSP, you need to whitelist the Helpium widget domain in your script-src and connect-src directives.

AI Not Responding or Giving Poor Answers

Check your knowledge base. The AI can only answer questions covered by your published articles. Draft articles are not included in AI searches.

Generate embeddings. After adding or updating articles, embeddings are generated automatically. If the AI still can't find relevant content, go to Settings → AI & Automation → Search & Embeddings and click Regenerate Embeddings.

Check AI message limits. If your workspace has reached its monthly AI message limit, the bot will stop responding. Check your usage in Settings → Billing or upgrade your plan.

Improve article content. Write articles with clear headings, specific terminology, and comprehensive answers. The AI performs best with well-structured content.

Messages Not Sending

Check WebSocket connection. The widget uses WebSockets for real-time messaging. If messages aren't sending:

• Verify your firewall isn't blocking WebSocket connections
• Check if a VPN or proxy is interfering
• Try refreshing the page

Check conversation status. Closed conversations cannot receive new messages. The customer needs to start a new conversation.

Customer Not Being Identified

Call identify() after init(). Make sure Helpium.init() completes before calling Helpium.identify(). Use the onload callback as shown in the installation guide.

Check the email format. The email must be a valid format. Invalid emails are rejected silently.

Check the API key. Identification requires the same API key used for widget initialization.

Email Channel Not Working

Verify forwarding. Check that your email provider is forwarding to the correct Helpium address shown in Settings → Channels → Email.

Check spam filters. Ensure forwarded emails aren't being caught by spam filters before reaching Helpium.

AI Actions Failing

Test the endpoint. Use the test button on the action's settings page. Check that your API endpoint is accessible and returns valid JSON.

Check authentication. Ensure the API key or bearer token is correct and not expired.

Check timeout. If your API is slow, increase the timeout in the action settings. Default is 10 seconds.

Check parameters. Verify the parameter names match what your API expects.

Still Need Help?

If you can't resolve an issue, start a conversation with our support team using the chat widget — we're here to help!