Put your agent on your WordPress site

What the plugin does

The plugin is a thin connector. It registers your site with Qalyb, links it to your workspace with one click, and then loads the chat widget on your public pages. Everything about the agent — what it knows, how it speaks, how the widget looks — stays in the Qalyb dashboard, so you never edit the same thing in two places.

• No snippet to paste and nothing to keep in sync: the plugin fetches the current widget for your site on every page load.
• Switch agents in WordPress or in Qalyb; your site follows within a minute.
• Placement lives in WordPress: choose which pages show the widget and which visitors see it.
• Nothing loads on your public pages until you connect. Before that, the plugin adds nothing to your site.

What you control where

The split is deliberate: WordPress decides where and for whom the widget appears; Qalyb decides what it is. Nothing is duplicated, so there is nothing to drift.

In WordPress: placement and visitors

• Placement rules — a master switch, then show the widget on every page, on every page except a list of paths, or only on a list of paths. One pattern per line, * as a wildcard — for example /checkout/* to keep it off the checkout.
• Hide for roles — keep the launcher out of the way for logged-in administrators and editors while they work on the site.
• Visitor identity — off by default. When on, the name and email of a logged-in visitor are passed to the agent, so it can greet them by name and your team sees who they are in Logs and tickets. Turn it on only if your privacy policy covers sharing that data with Qalyb.
• Consent — off by default. When on, the widget loads only after the visitor accepts the cookie category you choose — functional, statistics or marketing — in your consent banner (see Consent and privacy below).

In Qalyb: the agent and how the widget looks

Instructions, knowledge, AI Actions, persona, languages — everything that makes the agent the agent — is edited on the agent itself. The widget's appearance (colors, launcher, position, welcome message, language and right-to-left layout) is edited on the site's page under Deploy, with a live preview. Changes go live on your WordPress site without touching WordPress. See Brand & appearance and the web widget guide for what you can change.

Switching agents

Change the agent from whichever side you are on. In WordPress, open the Qalyb page and use Change agent. In Qalyb, open Deploy, click the site in the Connected list, pick another agent under Agent answering your visitors and save. Either way, your site picks up the new agent within about a minute — no cache to purge and no code to touch, because the page only points at your site's loader and the loader always serves the current widget.

Caching plugins

Page caching (WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, host-level caches) is safe. The plugin prints a small, static tag that points at your site's loader; the loader is what changes when you switch agents, and browsers fetch it fresh (it is cached for at most a minute).

• You don't need to purge the cache after switching agents. Do purge it after changing placement or role rules — those change the page HTML.
• If your cache plugin delays, defers or combines JavaScript, exclude scripts containing qalyb from those optimizations. Otherwise the launcher can appear late, or only after the visitor scrolls or clicks.
• Visitor identity is only ever printed for logged-in visitors, and caching plugins skip logged-in users by default. If yours is set up to cache logged-in pages, keep identity off.

Consent and privacy

With consent off (the default), the widget loads on every page view like any other script: it keeps a visitor id in the browser so a conversation continues across pages, and it sends the visitor's messages, the page URL and their language to Qalyb.

With consent on, the plugin asks your consent banner before loading the widget and only loads it once the visitor allows the category you picked — functional, statistics or marketing. This works with banners that support the WordPress Consent API (Complianz, CookieYes, Cookiebot and others). Install and configure a compatible banner first: without one, the Consent API reports consent as granted and the widget loads normally — the plugin's page shows a notice when that is the case.

Pause, deactivate or uninstall

• Pause — on the site's page under Deploy, choose Pause widget. The launcher disappears from your site; everything else stays in place, and Resume widget brings it back.
• Disconnect — in WordPress, click Disconnect on the Qalyb page; in Qalyb, choose Disconnect site on the site's page. The widget stops immediately, the plugin stays installed, and you can reconnect any time with Connect to Qalyb (you pick the agent again).
• Deactivate the plugin — the widget stops and the site shows Plugin deactivated in Deploy. Reactivating the plugin brings it back with the same agent, no reconnection needed.
• Delete the plugin — WordPress removes the plugin's settings and the site's credentials. The site stays listed in Deploy as deactivated until you disconnect it; its conversations remain in Logs.

Troubleshooting

"Couldn't reach Qalyb"

The Qalyb page in wp-admin talks to api.qalyb.ai from your server, not from your browser. This message means that request failed. The usual causes:

• Your host blocks outgoing HTTP requests, or WordPress is configured with WP_HTTP_BLOCK_EXTERNAL. Ask your host to allow api.qalyb.ai, or add it to WP_ACCESSIBLE_HOSTS in wp-config.php.
• An outdated certificate bundle on an old server, which fails the HTTPS handshake. Your host can update it; Tools → Site Health reports HTTP request problems.
• A temporary outage. Reload the page — the plugin retries on every load, and if the very first registration failed the Connection card offers Retry registration.

Qalyb never needs to reach your site in return, so a site behind a login or on a private network can still connect.

The widget doesn't show

Check these in order, in a private browser window:

• The Qalyb page in wp-admin says Connected and names an agent. With no agent chosen, nothing loads.
• The site is not unlinked or deactivated in Qalyb (open its row under Deploy).
• The page you are looking at is not excluded by a placement rule, and your role is not in the hide-for-roles list — that is why the private window matters.
• If consent is on, accept the chosen category in your banner, and make sure the banner supports the WordPress Consent API.
• Purge your page cache after changing rules, and exclude qalyb scripts from JavaScript delay or combine features.
• If your site address changed (a new domain, or a move from http to https), open the Qalyb page in wp-admin once, or click Refresh status — that syncs the new address and refreshes the domain the widget is allowed on.
• Publishing the widget counts against your plan's channel and deployed-agent limits. On the Free plan an agent can't be deployed to a live channel, so the connection stops at an upgrade prompt.
• Open your browser's developer console: a blocked request to cdn.qalyb.ai or api.qalyb.ai points at an ad blocker or a Content-Security-Policy on your site; an Origin not allowed error means the address visitors use doesn't match the site address WordPress reports (fix it under Settings → General, then open the Qalyb page once to re-sync).