Troubleshooting Guide

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

Possible Causes & Solutions:

Incorrect Chatbot ID

<!-- ❌ Wrong -->
<script type="module" data-chat-id="wrong-id"
        src="https://widget.getrocketflow.io/rkt-chat-loader.js"></script>

<!-- ✅ Correct — copy it from Dashboard → your chatbot → Embed -->
<script type="module" data-chat-id="your-actual-chatbot-id"
        src="https://widget.getrocketflow.io/rkt-chat-loader.js"></script>

Script Loading Issues
- Check for JavaScript errors in the browser console
- Verify https://widget.getrocketflow.io/rkt-chat-loader.js is reachable from your network
- The script is an ES module (type="module"), so it loads deferred by default — no extra async/defer attributes are needed
CSS Conflicts

The widget renders inside a container with the id rkt-widget-container. If your site's styles push it off-screen or under other elements:
```
#rkt-widget-container {
  z-index: 9999 !important;
}
```
Ad Blockers
- Some ad blockers or privacy extensions may block third-party widgets
- Test in incognito/private mode with extensions disabled

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
Rate Limits
- Each chatbot has a configurable message rate limit (default: 20 messages per 240 seconds per session)
- Adjust it in your chatbot's settings if legitimate users hit it
Platform Status
- Check status.getrocketflow.io for the live health of all RocketFlow services
- Test API connectivity: curl https://app.getrocketflow.io/api/public/healthcheck

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
- Refine the chatbot's prompt and personality in settings
- Adjust the AI model and temperature
- Enable guardrails to keep answers on-topic

Integration Issues

React / Next.js

The widget is added with a plain script tag — there is no npm package to install. In Next.js, use next/script in your root layout:

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          type="module"
          data-chat-id="your-chatbot-id"
          src="https://widget.getrocketflow.io/rkt-chat-loader.js"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Other Platforms (WordPress, Webflow, Shopify, …)

Paste the embed snippet into any place your platform allows custom HTML — a footer scripts setting, a custom-code section, or the theme's base template. The widget needs nothing else from the page.

Analytics Issues

Issue: Analytics not showing data

Check These:

Traffic
- Verify the widget is actually loading on your site
- Analytics only records sessions where visitors open or interact with the chat
Date Range
- Check the date range selected in the analytics dashboard
- Recent activity can take a few minutes to appear

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

You don't need any CORS configuration to use the widget. Chat messages are sent same-origin inside the widget's iframe (to widget.getrocketflow.io/api/chat) and proxied to the RKT API server-side — the browser never makes a cross-origin chat request.

This also resolved an iOS Safari issue (September 2026) where messages were sent but replies never arrived (TypeError: Load failed): mobile WebKit failed the cross-origin preflighted POST the widget previously made directly to app.getrocketflow.io. No action is needed on your site — the fix is entirely inside the widget.
Content Security Policy

If your site enforces a CSP, allow these origins:
```

<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://widget.getrocketflow.io;
               frame-src https://widget.getrocketflow.io;
               connect-src 'self' https://app.getrocketflow.io https://widget.getrocketflow.io;">
```
- script-src / frame-src: the loader script and the chat iframe are served from widget.getrocketflow.io.
- connect-src https://app.getrocketflow.io: the loader fetches your chatbot's configuration (colors, welcome message) from the RKT API.
- Requests made inside the iframe (chat messages, real-time sync) are governed by the iframe's own origin, not your page's CSP.

Debugging Tools

Browser Developer Tools

Console Logging
- Open DevTools → Console on the page embedding the widget. Errors from the loader script are logged there.
- Errors inside the chat itself (message send/stream failures) are logged in the widget iframe's console, prefixed with [rkt-chat], and are also reported to RocketFlow automatically — include your chatbot ID and the approximate time when contacting support and we can look them up.
Network Tab
- Check for failed requests
- Verify API responses
- Monitor request timing

API Testing

# Test API connectivity
curl https://app.getrocketflow.io/api/public/healthcheck

# Fetch your chatbot's public configuration
curl https://app.getrocketflow.io/api/public/chatbot/your-chatbot-id

You can also check the live status of all RocketFlow services at status.getrocketflow.io.

Getting Help

Before Contacting Support

Gather Information
- Browser console errors
- Network request logs
- Steps to reproduce the issue
- Chatbot ID: Your chatbot identifier (never share your API key)
Test in Different Environments
- Different browsers
- Incognito/private mode
- Different devices and networks

Support Channels:

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

Common Error Messages

Error Message	Cause	Solution
"Chatbot not found"	Invalid chatbot ID	Verify chatbot ID in dashboard
"Rate limit exceeded"	Too many messages in a session	Wait, or raise the chatbot's rate limit in settings
"Unauthorized"	Invalid API key (REST/MCP API)	Check API keys in Settings → API Keys
"Widget failed to load"	Script blocked or unreachable	Check network, ad blockers, and CSP

Best Practices

Regular Testing
- Test chatbot responses regularly
- Monitor analytics for issues
- Update content as needed
Content Maintenance
- Keep knowledge sources updated (or enable auto-retrain)
- Remove outdated information
- Add new content based on user questions
Security
- Use HTTPS everywhere
- Keep API keys secret and rotate them if exposed
- Restrict the chatbot to your domains in its settings

Troubleshooting