WordPress Troubleshooting

Solutions for common issues when using the KaiCalls chat widget on your WordPress site. If your issue is not listed here, contact our support team.

Widget Not Appearing

If the chat widget icon does not show up on your site, check these common causes:

Embed code not saved correctly: Open your WordPress admin, go to where you pasted the embed code, and confirm it is still there. Some themes or plugins may strip script tags during save.
Code placed in the wrong location: The embed code should be inside the footer section (before the closing </body> tag). If it is in the header, move it to the footer and test again.
JavaScript errors on the page: Open your browser developer tools (press F12), go to the Console tab, and look for red error messages. Other plugins or theme scripts may be causing conflicts that prevent the widget from loading.
Ad blockers or browser extensions: Some ad blockers or privacy extensions may block third-party scripts. Try loading your site in an incognito window with extensions disabled.
Wrong agent ID: Double-check that the data-agent-id in your embed code matches the agent ID shown in your KaiCalls dashboard.

If the widget icon appears but the chat window does not open, or messages are not getting responses:

Agent not active: Log into your KaiCalls dashboard and confirm your agent is active and properly configured. An agent without a system prompt or voice settings may fail silently.
Network or firewall restrictions: Some hosting providers or corporate firewalls block WebSocket connections. Contact your hosting provider to ensure WebSocket traffic is allowed.
SSL/HTTPS mismatch: The widget requires your site to use HTTPS. If your WordPress site still uses HTTP, the widget script will be blocked by the browser. Enable SSL through your hosting provider or use a plugin like Really Simple SSL.
Account limits reached: Check your KaiCalls plan to make sure you have not exceeded your monthly usage limits. Upgrade your plan if needed.

If the widget appears but looks broken, overlaps content, or has incorrect colors:

CSS conflicts with your theme: Some WordPress themes apply global styles that override the widget. Try adding this CSS to your theme customizer under Additional CSS:
```
#kaicalls-widget {
  z-index: 999999 !important;
  position: fixed !important;
}
```
Widget hidden behind other elements: Fixed-position elements like cookie banners, sticky headers, or other chat plugins may cover the widget. Adjust the z-index of conflicting elements or reposition them.
Page builder interference: Some page builders (Elementor, Divi, WPBakery) add wrapper elements that affect positioning. Test on a simple page first to isolate whether the builder is causing the issue.

If you just installed the widget but do not see it, your site may be serving a cached version of the page:

Clear your WordPress cache: If you use a caching plugin (WP Rocket, W3 Total Cache, LiteSpeed Cache), purge all caches from its settings page
Clear your CDN cache: If you use Cloudflare or another CDN, purge the cache from your CDN dashboard
Clear your browser cache: Press Ctrl+Shift+R (or Cmd+Shift+R on Mac) to do a hard refresh
Wait a few minutes: Some managed WordPress hosts (WP Engine, Kinsta, Flywheel) have server-level caches that take a few minutes to refresh

If the widget works on desktop but not on mobile devices:

Viewport meta tag missing: Make sure your theme includes a proper viewport meta tag. Most modern themes include this by default.
Mobile plugins hiding scripts: Some mobile optimization plugins remove or defer scripts on mobile. Check your mobile plugin settings and whitelist the KaiCalls widget script.
Touch event conflicts: If the widget icon appears but does not respond to taps, another element may be intercepting touch events. Check for overlapping invisible elements using browser developer tools.

If none of the solutions above resolve your issue, our support team is here to help.

Email: support@kaicalls.com
Phone: 1 (417) 386-2898 (Monday-Friday, 9am-5pm CST)
Include in your message: your WordPress site URL, the browser and device you are using, and a screenshot of any error messages