Troubleshooting Guide

This guide helps you resolve common issues with RocketFlow chatbot integration and usage.

Possible Causes & Solutions:

Incorrect Chatbot ID

<!-- ❌ Wrong -->
<script src="https://cdn.getrocketflow.io/widget.js" 
        data-chatbot-id="wrong-id">
</script>

<!-- ✅ Correct -->
<script src="https://cdn.getrocketflow.io/widget.js" 
        data-chatbot-id="your-actual-chatbot-id">
</script>

Script Loading Issues
- Ensure the script loads after the DOM is ready
- Check for JavaScript errors in browser console
- Verify the CDN URL is accessible

CSS Conflicts

/* Add this to override conflicting styles */
.rocketflow-widget {
  z-index: 9999 !important;
  position: fixed !important;
}

Ad Blockers
- Some ad blockers may block the widget
- Test in incognito mode or with ad blockers disabled
- Consider using a custom domain for the widget script

Chat Not Responding

Issue: Users can send messages but get no response

Check These:

Chatbot Status
- Verify your chatbot is active in the dashboard
- Check if training is complete
- Ensure knowledge sources are properly configured
API Limits
- Check your API usage in the dashboard
- Verify you haven't exceeded rate limits
- Upgrade your plan if needed
Network Issues
- Test API connectivity: curl https://api.getrocketflow.io/v1/health
- Check firewall settings
- Verify SSL certificates

Poor Response Quality

Issue: Chatbot gives irrelevant or incorrect answers

Solutions:

Improve Training Data
- Add more relevant content to knowledge sources
- Remove outdated or incorrect information
- Use high-quality, well-structured content

Optimize Content Structure

# Good content structure

## Product Information
Our product X does Y and Z.

## Pricing
Basic plan: $10/month
Pro plan: $25/month

Adjust Settings
- Increase response length in chatbot settings
- Adjust response style (formal vs casual)
- Enable/disable specific features

Integration Issues

React/Next.js Integration

Common Issues:

Hydration Mismatch

// ❌ This can cause hydration issues
<RocketFlowWidget chatbotId="your-id" />

// ✅ Use dynamic import for client-side only
import dynamic from 'next/dynamic';

const RocketFlowWidget = dynamic(
  () => import('@rocketflow/react').then(mod => mod.RocketFlowWidget),
  { ssr: false }
);

TypeScript Errors

// Install types if available
npm install @types/rocketflow-react

// Or create your own types
declare module '@rocketflow/react' {
  export interface RocketFlowWidgetProps {
    chatbotId: string;
    position?: string;
  }
}

WordPress Integration

Plugin Issues:

Plugin Not Activating
- Check PHP version compatibility (7.4+)
- Verify file permissions
- Check for plugin conflicts
Widget Not Showing
- Clear WordPress cache
- Check theme compatibility
- Verify shortcode usage: [rocketflow id="your-chatbot-id"]

Performance Issues

Issue: Slow loading or response times

Optimization Tips:

Script Loading

<!-- Load script asynchronously -->
<script src="https://cdn.getrocketflow.io/widget.js" 
        data-chatbot-id="your-id"
        async>
</script>

CDN Optimization
- Use a CDN for your website
- Enable gzip compression
- Optimize images and assets

API Optimization

// Implement request debouncing
let timeoutId;
function debouncedRequest(message) {
  clearTimeout(timeoutId);
  timeoutId = setTimeout(() => {
    sendMessage(message);
  }, 300);
}

Analytics Issues

Issue: Analytics not showing data

Check These:

Tracking Setup
- Verify analytics is enabled in dashboard
- Check if tracking code is properly installed
- Ensure cookies are enabled
Data Processing
- Analytics data may take up to 24 hours to appear
- Check date range in analytics dashboard
- Verify chatbot is receiving traffic

Security Concerns

Issue: Security warnings or blocked requests

Solutions:

HTTPS Requirements
- Ensure your website uses HTTPS
- Update any HTTP references to HTTPS
- Check SSL certificate validity

CORS Issues

// If making direct API calls, handle CORS
fetch('https://api.getrocketflow.io/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  mode: 'cors'
});

Content Security Policy

<!-- Add to your CSP header -->
<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://cdn.getrocketflow.io; 
               connect-src 'self' https://api.getrocketflow.io;">

Debugging Tools

Browser Developer Tools

Console Logging

// Enable debug mode
window.RocketFlow = {
  debug: true,
  onError: function(error) {
    console.error('RocketFlow Error:', error);
  }
};

Network Tab
- Check for failed requests
- Verify API responses
- Monitor request timing

API Testing

# Test API connectivity
curl -X GET https://api.getrocketflow.io/v1/health

# Test chatbot response
curl -X POST https://api.getrocketflow.io/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello",
    "chatbot_id": "your-chatbot-id",
    "session_id": "test-session"
  }'

Getting Help

Before Contacting Support

Check Documentation
- Review relevant documentation sections
- Check API reference for correct usage
- Look for recent updates or changes
Gather Information
- Browser console errors
- Network request logs
- Chatbot configuration
- Steps to reproduce the issue
Test in Different Environments
- Different browsers
- Incognito/private mode
- Different devices
- Different networks

Contact Support

When contacting support, include:

Issue Description: Clear description of the problem
Expected Behavior: What should happen
Actual Behavior: What actually happens
Steps to Reproduce: Detailed steps
Environment: Browser, OS, device details
Error Messages: Any error messages or logs
Chatbot ID: Your chatbot identifier (not API key)

Support Channels:

Email: support@getrocketflow.io
Live Chat: Available in your dashboard
Documentation: docs.getrocketflow.io

Common Error Messages

Error Message	Cause	Solution
"Chatbot not found"	Invalid chatbot ID	Verify chatbot ID in dashboard
"Rate limit exceeded"	Too many requests	Wait or upgrade plan
"Unauthorized"	Invalid API key	Check API key in settings
"Widget failed to load"	Script loading issue	Check network and CDN
"No response from chatbot"	Training incomplete	Complete chatbot training

Best Practices

Regular Testing
- Test chatbot responses regularly
- Monitor analytics for issues
- Update content as needed
Performance Monitoring
- Monitor response times
- Check error rates
- Optimize based on usage patterns
Content Maintenance
- Keep knowledge sources updated
- Remove outdated information
- Add new content based on user questions
Security
- Use HTTPS everywhere
- Keep API keys secure
- Monitor for suspicious activity

Troubleshooting