Contents
Troubleshooting - Plugixa Chat
Start here. Most reports fall into one of these, and several of them are the plugin doing exactly what it should.
The widget does not appear on the site
Work down this list. The first one that applies is almost always the cause.
| Check | Where |
|---|---|
| The widget is Active | The Status column on the Widgets screen. A new widget starts Inactive |
| It has at least one channel that is switched on and has a destination | The Channels step. An active widget with nothing to show is not drawn |
| Its rules allow the page you are looking at | The When & where step. One Show on rule limits the widget to the pages that match |
| A Device rule, or the window’s width | A “Mobile only” widget is hidden in a window 768 pixels wide or more |
| A Signed in rule | “Signed-out visitors” hides the widget from you while you are logged in. Check in a private window |
| A trigger is waiting | With After a delay, After scrolling or When the visitor is about to leave, the launcher appears later. See the When & where step |
| Your page cache | Clear it. A page cached before the widget was published does not contain it |
| You are inside a page builder | The widget is not drawn in the editing screens of Elementor, Divi, Oxygen, Beaver Builder, Brizy, WPBakery or Bricks, or in the Customizer. View the page normally |
If all of that is right, look at the page’s source for <plugixa-chat. If
it is there, the widget was printed and something in the browser is hiding
it; check the browser console for a blocked script. If it is not there, the
page was built without it, which points back at the status, the rules or a
cache.
It does not appear after the delay on later pages
It is designed to appear straight away. Once a trigger has fired for a visitor, the widget is shown at once on the next pages in the same browser tab, so they are not made to wait on every page. Open a new private window to see the trigger again.
The unread badge is gone
The badge goes away once a visitor opens the widget, and their browser remembers that. You opened it. Use a private window to see it again.
A UTM rule does not match
- A Came from rule reads the address the visitor was on before, not the
address of the page itself. With
utm_source=newsletterit matches on the page opened after the landing page, not on the landing page. - A Page address rule reads the page’s own address, but on the server. If a page cache serves the same stored page for every UTM parameter, the rule never sees it.
See UTM parameters.
A channel is missing from the widget
| Cause | Fix |
|---|---|
| The channel’s switch is off | Switch it on in its card |
| It has no destination | Fill in Destination |
| It is set to Desktop only or Mobile only | Check the three device buttons on its card, and the width of your window |
| The WeChat channel has neither an ID nor a QR image | Add one of them |
| Its card says “Not shown on your site” | The channel is not available on this site, for example a Pro channel without Pro, or Order status without WooCommerce |
| It has its own hours PRO | Check Show this channel only at certain times |
A channel was removed when I saved
A destination that starts with javascript:, data: or vbscript: is
refused, and the channel is discarded on save. The card warns beforehand:
“Links cannot run JavaScript. Use the plugixa_chat_channel_click event
instead.” To run your own code on a press, listen for that event. See
Hooks reference.
A rule disappeared when I saved
A rule with no values is discarded on save. The builder warns: “Add at least one value, or this rule will be discarded when you save.”
WhatsApp opens the wrong number, or does not open
- Type the number in international format. Choose the Country in the picker rather than typing a leading zero.
- On a computer, the link opens WhatsApp Web, which asks the visitor to log in. To offer a code to scan instead, switch on Show a QR code on computers. See QR codes.
The contact form
The form says “This form is no longer available. Refresh the page and try again.”
The widget the form belongs to is no longer Active, or its Contact form channel was removed or switched off, and the visitor is on a page loaded before that. Reloading the page shows the current widget.
The form says “Too many requests. Please wait a moment and try again.”
The visitor has sent five messages within five minutes. The limit is per visitor.
If everyone gets this message, your site is probably behind a reverse
proxy or load balancer, so every visitor appears to come from one address
and shares one limit. Tell the plugin to read the proxy’s headers by adding
this to wp-config.php:
define( 'PLUGIXA_CHAT_BEHIND_PROXY', true );
Do this only when the site really is behind a proxy you trust. See Hooks reference.
A test message is not stored
A form sent within three seconds of being opened is treated as a program and quietly discarded. The form still shows the thank-you message. Wait a few seconds before sending when you test.
The form says “This page was cached too long ago. Refresh and try again.”
Normally the form recovers from this by itself: it fetches a fresh token
and sends the message again. If visitors see the message, the form could not
get a fresh token. The usual cause is the address
/wp-json/plugixa-chat/v1/context being cached or blocked. Exclude that
address from caching in your CDN, and allow it in your security plugin.
The form says “This request did not come from this site.”
The page and the request were on different hosts, for example example.com
and www.example.com. Make sure the site is served from one address, the
one set under WordPress Settings -> General, and redirect the other to
it.
The form says “Please complete the security check and send your message again.”
Turnstile is on and the check did not pass. If the Turnstile box never appears, the site key is wrong or does not allow this domain; check the widget’s settings in your Cloudflare account. To stop using Turnstile, press Turn off Turnstile under Settings -> Leads.
No notification email arrives
Work down this list.
| Check | Where |
|---|---|
| The lead is on the Leads screen | If it is, the form works and the problem is email |
| Email me when a new lead arrives is on | Settings -> Leads |
| Send to holds the right addresses | The same tab. Empty means the site admin email |
| The spam folder | The email comes from your site, with the visitor in Reply-To |
| The site can send email at all | Try a password reset email. Many hosts need an SMTP plugin for reliable delivery |
The plugin hands the email to WordPress’s own mail function. It does not send mail itself.
The Dashboard shows nothing
| Cause | Detail |
|---|---|
| No visitor has seen a widget yet | The Activity card reads “No activity recorded yet.” |
| You just tested | Events are sent when a page is left, so move to another page and reload the Dashboard |
| A browser extension blocks the request | Privacy extensions can block the request that reports events. That affects the visitors who use them, not your figures as a whole |
| Pages are cached for more than a day | Events from a copy older than about 24 hours are refused. Set your cache to refresh pages at least daily |
| The reporting address is blocked | A security plugin or firewall that blocks unauthenticated POST requests to the REST API will block /wp-json/plugixa-chat/v1/events. Allow it |
| A retention period deleted them | Settings -> Privacy. Figures older than the period are removed daily |
Events do not reach Google Analytics, Tag Manager or the Meta Pixel
| Check | Detail |
|---|---|
| The switch is on | Settings -> Analytics |
| The tag is on the page | The plugin calls tags that are already installed. It loads none |
| The tag had loaded when the visitor clicked | A consent tool or a “delay JavaScript” optimisation can hold the tag back. Events before it loads are not queued by the plugin |
| In Tag Manager, a trigger exists | An event pushed to the data layer does nothing until a Custom Event trigger with the same name uses it |
See Tracking events.
A chat button shows a note instead of a button
“Chat button: no widget has a channel this button can open. Only editors see this note.” Visitors see nothing in its place.
| Cause | Fix |
|---|---|
| The widget the button names was deleted | Choose another widget in the block, or change widget in the shortcode |
| The channel was removed, switched off, or lost its destination | Restore it in the widget |
| The channel opens a panel | Contact form, WeChat and Order status cannot be opened by a button. Choose a link channel |
The WooCommerce product button is missing
| Check | Where |
|---|---|
| The switch is on, with a widget and a channel chosen | Settings -> WooCommerce |
| The channel still exists in that widget and has a destination | The widget’s Channels step |
| The product template | The button is attached to WooCommerce’s product summary on a classic theme, and to its Add to cart block on a block theme. A custom template that leaves those out leaves out the button too |
| Your page cache | Clear it |
The admin app
The screen is blank, or stuck loading
- Reload with the browser’s cache bypassed.
- Check the browser console. A blocked request to
/wp-json/plugixa-chat/v1/means a security plugin or firewall is refusing the REST API. - If the REST API is disabled on the site, the app cannot load its data.
“You are not allowed to do that.”
Your account lacks the capability for that action. On a new install only administrators have the plugin’s capabilities. See REST API.
“Plugixa Chat could not finish setting up its database, so parts of it will not work.”
A notice on the Plugins screen, the WordPress dashboard and the plugin’s own screens. It lists each table that could not be created and what the database said.
“The usual cause is a database user that is not allowed to create tables. Once that is put right, try again.” Press Try again on the notice. The plugin also retries by itself every five minutes.
“Plugixa Chat: dependencies are missing. Run “composer install” in the plugin directory.”
The plugin’s folder is incomplete. This happens with a copy taken straight from source control. Install the plugin from its release ZIP.
Pressing / does not open the search
The shortcut is ignored while the cursor is in a text field, and while a dialog or a menu is open, so that a slash can be typed. Click an empty part of the screen first, or click the search box in the top bar. See Getting started.
There is no full-screen button
The button is drawn only where the browser offers a full-screen mode, and not in a narrow window. Some browsers on phones and tablets offer none.
Where WordPress notices went
On the Plugixa Chat screens, WordPress admin notices are moved inside the app, under the top bar, instead of sitting above it. Nothing is hidden. On every other admin screen they are where WordPress puts them.
Pro features
A Country rule hides the widget from everyone
The site cannot tell which country a visitor is in. The rule’s editor says so. See Country and language rules PRO.
Business hours are off by a few hours
The timetable is read in the site’s timezone, not yours and not the visitor’s. Check Settings -> General -> Timezone in WordPress. See Business hours PRO.
Webhooks or CRM contacts arrive late, or not at all
Both are delivered in the background by WordPress’s scheduler, which runs
when the site is visited. On a quiet site, or one where DISABLE_WP_CRON is
set without a real cron job, deliveries wait. Set up a system cron job that
calls wp-cron.php regularly.
The state of the last delivery is shown on each webhook and each connection. Use Send a test or Check connection to try one now.
An A/B test says “Keep it running” for days
Each widget needs at least 100 views before a verdict is given, and a real difference before one is declared ahead. On a low-traffic site that takes time. See A/B tests PRO.
Getting more help
If none of this applies, contact support at plugixa.com/contact with:
- the plugin version, shown on the Plugins screen,
- your WordPress and PHP versions,
- the page address where the problem shows,
- any message from the browser console.