Troubleshooting
Most problems come down to a handful of causes. Find your symptom below and work through the checks in order.
The chat widget is not showing
- Look in a private window. The widget is hidden from logged-in administrators. If you only checked in the browser where you are logged in to WordPress, the widget is probably working. This is the most common cause.
- Check automatic display. Under Settings → Behavior → Features, Auto-Inject on All Pages must be Active, unless you place the widget yourself with the
[ecomai_chatbot]shortcode. - Missing only on the checkout? Turn on Show on Checkout in the same section.
- Clear your caches. If you use a caching plugin or a CDN, purge it after activating the plugin or changing these settings; visitors may still be getting a stored copy of the page from before.
- Rule out a script conflict. Open the page in a private window, open the browser’s developer console and reload. If a red JavaScript error from another plugin or your theme appears before the widget loads, fix or disable that script. If your optimisation plugin combines, defers or delays JavaScript, exclude the chat script
chat.jsfrom it and test again. - Check the position. A cookie banner or another floating button can cover the chat bubble. Try the other corner under Settings → Design → Widget Position.
The AI is not answering, or shows an error
- Test the connection. Open Settings → AI Provider and click Test Connection. The status shows either Connection OK or Last test failed with the provider’s own error message, which usually names the cause.
- “No API key saved for this provider”. Paste your key and click Save Key. A key is saved per provider, so after switching provider you need that provider’s key.
- The key is rejected. Check that you copied the whole key with no spaces, that it has not been revoked in the provider’s console, and that it belongs to the provider selected on the screen.
- Quota or billing errors. A key that is valid but has no credit or has hit its spending limit also fails. Check billing in the provider’s console.
- “API key … could not be decrypted. Please re-save it.” Keys are encrypted with your site’s WordPress secret keys. After a migration or a change to the salts in
wp-config.php, enter the key again and save. - The model no longer exists. Providers retire models. Click the refresh icon next to AI Model, choose a current model and save.
- Slow answers that time out. Raise Request Timeout (seconds) under Advanced Settings. If your host blocks outgoing connections, ask them to allow HTTPS requests to your provider’s API.
- Provider outage. With a fallback provider Pro the chat switches automatically.
Customers see “I’m taking a short break right now”
This message belonged to the conversation limit of versions before 2.9.0. Since 2.9.0 the plugin has no conversation limit, Free or Pro. If you still see it, update the plugin to the current version.
“Too many messages. Please wait a moment.”
One visitor sent more messages in a minute than your limit allows. This protects your AI budget. If real customers hit it, raise Rate Limit (messages/minute) under Settings → Behavior → Limits & Language.
The AI is silent in one conversation only
That is expected when the conversation has been escalated or an agent has taken it over: the AI does not reply while a person is in charge. Open it under Inbox → Conversations and either answer or click Hand Back to Bot. See Agents and human takeover.
Problems with caching plugins
The typical symptom is a widget that opens normally but answers “Your session has expired. Please refresh the page to continue chatting.” Each page contains a short-lived security token for the chat. If a page cache serves the same stored page for longer than that token lives, visitors receive an expired token and their messages are refused.
- Confirm the cause. Purge the page cache and reload the page in a private window. If the chat works again, caching is the cause.
- Shorten the page cache lifetime. In your caching plugin, set the lifespan of cached pages to 10 hours or less. This is the usual recommendation for any WordPress feature that uses security tokens.
- Check server and CDN caching too. If your host or CDN caches full HTML pages, apply the same lifetime there.
- Don’t cache chat requests. Make sure requests to
/wp-admin/admin-ajax.phpand/wp-json/are excluded from caching. Most caching plugins exclude them by default; a custom CDN rule might not. - Design changes not visible? Purge the cache after saving on the Design screen, then reload in a private window.
The licence won’t activate
Activation happens under Settings → License. The error message shown on that screen tells you which case applies.
- “License key not found” or “License key is invalid”: copy the key again from your purchase e-mail, including the dashes, with no space before or after. The format is
WAI-XXXX-XXXX-XXXX-XXXX. - “This license is already activated on another site”: a key is tied to one site. Release the other site first, in its License screen or on the account page, then activate here. This also applies after moving from a staging address to your live domain. See moving the plugin to another domain.
- “This license has expired” or “This subscription was cancelled”: the subscription has ended. Renew it to reactivate Pro. Your data and settings are still there.
- “This license was refunded” or “has been disabled”: the key is no longer valid. If you think this is a mistake, contact support.
- “This site is no longer registered for this license”: click Deactivate this site, then activate the key again.
- “Unable to reach the licensing service”: your server could not make the outgoing HTTPS request. Try again in a few minutes. If it keeps failing, ask your host whether a firewall blocks outgoing connections from WordPress.
If Pro features are still locked right after a renewal, open the License screen and click Validate now to refresh the status.
Other common questions
The assistant gives a wrong or vague answer
Add a snippet with the right answer, then check What does the AI currently know? at the bottom of the Knowledge Base screen to confirm it is included. See Knowledge base.
A cart recovery trigger doesn’t fire
Check that Enable Proactive Chat is on, that the rule is Active, and that you are testing in a private window. Exit intent does not fire on mobile and fires once per session. See Cart recovery.
Escalation e-mails don’t arrive
Use Send Test Escalation Alert under Settings → Behavior → Escalation Settings. Then open Settings → Integrations → Email Delivery Diagnostics, which shows recent e-mail attempts and whether an SMTP plugin is detected. WordPress sites without proper SMTP sending often have their e-mails rejected as spam.
What to send us
If none of this helps, contact support with the address of the page where the problem happens, the exact error message, and the result of Test Connection. Don’t send your full API key or licence key by e-mail unless we ask for it through a secure channel.
Still stuck?
Check the troubleshooting guide, or contact support and tell us what you tried.