Troubleshooting Guide
Find solutions to common issues and learn how to optimize your helpNINJA setup for the best performance.
Quick Solutions
Try these common solutions first before diving into detailed troubleshooting steps.
Refresh & Retry
Clear cache and reload the page
Check Browser Console
Look for JavaScript errors (F12)
Verify Usage Limits
Check if you've exceeded plan limits
Widget Installation Issues
Widget not appearing on website
Common Causes & Solutions:
- Script placement: Ensure the widget script is placed just before the closing
</body>tag - Invalid credentials: Double-check your tenant ID, site ID, and verification token in the dashboard
- Domain verification: Verify your domain is properly configured in Dashboard → Sites
- JavaScript errors: Check browser console (F12) for any error messages
- Content blockers: Ad blockers or privacy extensions may block the widget
Debugging Steps:
- Open browser developer tools (F12)
- Check the Console tab for any red error messages
- Look in the Network tab to verify the widget script loads successfully
- Confirm the widget configuration object is properly set
Widget appears but styling is broken
Possible Solutions:
- CSS conflicts: Your website's CSS may be overriding widget styles
- Z-index issues: Adjust widget position or increase z-index in configuration
- Theme compatibility: Try switching between light/dark themes
- Custom CSS: Add specific CSS rules to fix styling conflicts
/* Fix common styling conflicts */.helpninja-widget { z-index: 9999 !important; font-family: inherit !important;}ℹ️ Widget loads slowly or inconsistently
Performance Optimization:
- Async loading: Ensure the
asyncattribute is present on the script tag - Network conditions: Slow internet may delay widget initialization
- Page load timing: Widget loads after page content, which is normal
- Server location: CDN automatically serves from nearest location
🤖 Chat & AI Issues
AI not responding to messages
Check These Issues:
- Usage limits: You may have exceeded your monthly message limit
- Knowledge base: Ensure you have uploaded content for the AI to reference
- Account status: Verify your subscription is active and payments are current
- Service status: Check our status page for any ongoing issues
- Network connectivity: Ensure stable internet connection
Check your dashboard's usage meter to see if you've hit your plan's message limit.
AI responses are irrelevant or unhelpful
Improve AI Performance:
- Content quality: Upload comprehensive, well-structured documentation
- Content organization: Use clear headings and logical document structure
- Content freshness: Regularly update outdated information
- Testing queries: Test common customer questions in the dashboard
- Feedback loop: Monitor escalated conversations for improvement opportunities
Content Best Practices:
- Use FAQ format for common questions
- Include step-by-step instructions
- Add context and examples
- Keep content concise but comprehensive
ℹ️ Messages taking too long to send
Response Time Issues:
- High traffic: Response times may increase during peak usage
- Complex queries: Longer messages take more time to process
- Knowledge base size: Larger content libraries may slow responses
- Network latency: Geographic distance affects response times
Typical Response Times
1-3s
Average AI response time
Integration Issues
Slack/Teams/Discord not receiving notifications
Integration Troubleshooting:
- Webhook URL: Verify the webhook URL is correct and hasn't expired
- Channel permissions: Ensure the webhook has permission to post in the channel
- Integration status: Check integration status in Dashboard → Integrations
- Test messages: Use the "Send Test Message" feature
- Escalation rules: Verify escalation rules are properly configured
Testing Steps:
- Go to Dashboard → Integrations
- Find your integration and click "Configure"
- Click "Send Test Message"
- Check your channel for the test notification
- If test fails, verify webhook URL and permissions
Too many or too few escalation notifications
Adjust Escalation Settings:
- Confidence threshold: Adjust the confidence level trigger (default: 55%)
- Keyword filters: Refine keyword-based escalation rules
- Rate limiting: Set up notification frequency limits
- Business hours: Configure time-based escalation rules
- Rule priority: Order rules by importance
Recommended Confidence Thresholds:
Conservative: 70%
Fewer escalations
Balanced: 55%
Default setting
Aggressive: 40%
More escalations
ℹ️ Dashboard links in notifications not working
Link Troubleshooting:
- Domain configuration: Verify your helpNINJA domain is set correctly
- User permissions: Ensure team members have dashboard access
- Session management: Users may need to sign in to access conversations
- Network access: Check if corporate firewalls block access
Account & Billing Issues
Can't access dashboard or features are limited
Access Issues:
- Payment status: Check if your subscription payment is current
- Plan limits: Verify you haven't exceeded your plan's features
- User permissions: Ensure your account has the necessary role permissions
- Browser issues: Try clearing cookies or using an incognito window
If payment failed, update your payment method in billing settings to restore full access.
Unexpected billing charges or usage
Billing Investigation:
- Usage analytics: Review detailed usage breakdown in Dashboard → Analytics
- Overage charges: Check if you exceeded your plan's message limits
- Plan changes: Verify any recent plan upgrades or changes
- Billing cycle: Understand your billing date and prorations
- Invoice details: Download detailed invoices for line-item breakdown
Common Billing Scenarios:
- Overage charges when exceeding message limits
- Prorated charges when upgrading mid-cycle
- Annual billing discounts vs monthly charges
- Tax calculations based on location
Performance Issues
Dashboard loading slowly
Performance Optimization:
- Browser cache: Clear browser cache and cookies
- Network speed: Check your internet connection speed
- Browser choice: Try a different browser (Chrome, Firefox, Safari)
- Extensions: Disable browser extensions that might interfere
- Data volume: Large datasets may slow down analytics pages
ℹ️ Analytics not updating or showing incorrect data
Data Sync Issues:
- Data refresh: Analytics update every few minutes, not real-time
- Timezone settings: Verify your account timezone settings
- Date range: Check the selected date range in analytics
- Browser refresh: Hard refresh the page (Ctrl+F5 or Cmd+Shift+R)
Data Update Frequency
5 min
Analytics refresh interval
🆘 Getting Help
If you can't find a solution in this guide, our support team is here to help you get back on track.
📧 Email Support
Send us a detailed description of your issue for personalized help.
- Response within 24 hours
- Include screenshots if helpful
- Mention your plan and account details
💬 Live Chat
Chat with our support team in real-time for immediate assistance.
- Available business hours (9 AM - 6 PM EST)
- Instant responses
- Screen sharing available
Before Contacting Support
Please gather this information to help us resolve your issue faster:
- Your account email address and plan type
- Description of the problem and when it started
- Steps you've already tried to resolve it
- Screenshots or error messages (if applicable)
- Browser type and version you're using
- URL where the issue occurs
📊 System Status & Updates
🟢 Service Status
Check if the issue is related to a service outage or maintenance.
Chat API
Operational
Dashboard
Operational
Integrations
Operational
📢 Recent Updates
Stay informed about new features and improvements.
Dashboard UI improvementsDec 15
New Discord integrationDec 10
Enhanced analyticsDec 5
🛡️ Prevention Tips
Avoid Common Issues:
- Test integrations regularly with sample messages
- Monitor usage to avoid hitting plan limits
- Keep your knowledge base content up-to-date
- Review escalation rules periodically
- Update payment methods before expiration
- Clear browser cache monthly
- Use supported browsers and keep them updated
- Subscribe to our status page for outage notifications
- Document your configuration for team reference
- Train team members on proper usage