Qunivex for WordPress

1What it does

The plugin is two independent features sharing one settings screen. Most sites use only the first, and nothing about the second is required — leaving its fields blank simply means the editor panel never appears.

2Requirements

• WordPress 6.0 or newer.
• PHP 7.4 or newer.
• A Qunivex account with at least one project. The chat bubble works on every plan, including the Free Trial.
• For the editor assistant only: a plan that includes API access — Starter or Pro.

The plugin is licensed GPLv2 or later. It works on single-site and multisite installs; on multisite the settings are per site, since each site normally wants its own agent.

3Installing

The plugin is submitted to the WordPress.org directory and awaiting review. Until that clears, you install it by uploading the zip — a normal, fully supported WordPress install path, and the same file that will be published to the directory.

1. In WordPress, go to Plugins → Add New → Upload Plugin.
2. Choose qunivex-wordpress-0.1.0.zip and click Install Now.
3. Click Activate.

Activating changes nothing visible on your site yet. The plugin deliberately prints no markup until a widget key is saved, so an activated-but-unconfigured install is inert rather than broken.

4The settings screen

Activation adds one screen, at Settings → Qunivex. It is the only page the plugin adds and the only place it stores anything.

The entry appears only once the plugin is activated — uploading alone does not add it. Viewing or saving the screen requires the manage_options capability.

Every field

Widget Public KeyRequired for the bubble

Your agent's public widget key, starting qvx-. Find it on your project's Overview or Deployments page in the Qunivex dashboard. Public by design: it identifies the agent, is restricted by domain, and carries no account access.

Show on every pageCheckbox

Ticked, the bubble is added to every front-end page automatically. Unticked, it appears only where you place the [qunivex_chat] shortcode.

API KeyAssistant only

A Qunivex API key, starting qvx-live-. Create one on the API Keys page of your dashboard. Unlike the widget key this is a real credential; it is stored in your WordPress database and used only in server-side requests.

Agent IDAssistant only

Which agent writes for you, as QXA-…. A project id (QXP-…) also works and uses that project's main agent.

Qunivex Base URLAdvanced

Defaults to https://qunivex.com. Change it only if you run a self-hosted Qunivex instance — pointing it anywhere else stops both halves of the plugin from working.

5The chat bubble

Paste your widget key into Widget Public Key, tick Show on every page, and save. That is the entire setup.

Settings → Qunivex

What gets added to your pages

On a page where the bubble is enabled, the plugin prints one script tag in the footer, immediately before </body>:

<script src="https://qunivex.com/widget.js" data-agent="qvx-…"></script>

That is the same embed any non-WordPress site pastes by hand. The plugin exists because a WordPress user has nowhere convenient to paste it, not because the widget behaves differently here. No stylesheet, no jQuery dependency and no additional requests are added to pages where the bubble is switched off.

6Allowed domains

The widget only answers on domains you have explicitly allowed on your project's Deployments page, so copying your key onto another site does nothing. If your WordPress domain is not on that list, the script tag loads and the bubble never appears.

Two rules are worth knowing, because they explain almost every "I added it and it is still blocked":

• Enter the bare hostname — example.com, not https://example.com/ and not example.com:443. A hostname automatically covers the apex, every subdomain and any port, so example.com also allows www.example.com.
• For a local install, add the IP with its port, like 127.0.0.1:8000. An IP entry that names a port matches only that port, and an IP is never treated as having subdomains.

A blocked domain shows up as a 403 on /api/public/agents/…/config in your browser's console.

7Shortcode

To put the bubble on specific pages only, leave Show on every page unticked and add the shortcode to those posts or pages:

[qunivex_chat]

The shortcode renders nothing where it sits — it asks for the widget, and the script tag is still printed in the footer. So it works anywhere in the content, and putting it in a post twice still loads the widget once.

In the block editor, add a Shortcode block; in the classic editor, type it into the content. It also works in a widget area or a template through do_shortcode().

8Editor assistant

Optional, and off until configured. Fill in both API Key and Agent ID, and a Qunivex AI Assistant panel appears in the sidebar of the post editor — on posts, pages, and any custom post type that supports the editor.

Settings → Qunivex

Type what you want written, optionally tick Include the current post content to give the agent what you have so far, and press Generate. The reply arrives in the panel with Copy and Insert into post beside it — nothing is written into your post unless you ask for it.

Which agent writes

The agent named in Agent ID answers with everything it is configured with in Qunivex — its model, system prompt, knowledge base, tools and guardrails. An agent grounded in your product documentation writes about your product; a general one writes generically. It does not have to be the same agent as your chat bubble, and on many sites it should not be: the bubble answers customers, the assistant writes in your house voice.

How requests are billed

Each generation is one call against your plan's monthly API allowance (Starter: 5,000 calls, Pro: 25,000 calls). That allowance is separate from your public chat quota, so writing posts never eats into the conversations your bubble can have. Requests go to https://qunivex.com/v1 from your WordPress server — see the API reference if you want to call the same endpoint yourself.

9Appearance

Colours, the launcher icon, the avatar, the welcome message, starter questions and the pre-chat form are all configured in Qunivex on your project's Appearance page — not in WordPress. The plugin has no styling options of its own, on purpose: the widget renders inside your page but is styled entirely by the agent's own configuration, so a theme change cannot break it and it looks the same wherever that agent is embedded.

Appearance changes are fetched live and take effect on the next page load. They do not require a WordPress cache purge, unlike turning the widget on or off, which changes the printed HTML.

10Data & privacy

What the plugin stores and sends, stated plainly:

• It creates one option row in your WordPress database, qunivex_options, holding the five settings above. It creates no tables, no posts and no user meta.
• It stores no visitor data in WordPress. Conversations happen between the visitor's browser and Qunivex; nothing about them is written to your database.
• Your API key never reaches a browser. Assistant requests are made from your WordPress server; the key is not printed into any page or exposed to the editor's JavaScript.
• The front end contacts Qunivex when the bubble is enabled, to load the widget script and the agent's display configuration. Sites in jurisdictions requiring consent for third-party services should treat this like any other embedded service.
• Deleting the plugin removes its option row, on every site of a multisite network. Deactivating leaves it in place, so your settings survive a temporary deactivation.

See the Qunivex privacy policy for what happens to conversations on our side.

11Troubleshooting

Almost every report is one of these. The first one splits the problem in half before you change anything.

12Updates & removal

While the plugin is distributed as a zip it does not auto-update. To move to a newer version, download the current zip and upload it over the installed copy; WordPress will ask you to confirm the replacement and your settings are preserved. Once the directory listing is live, one-click updates begin working automatically because the zip already uses the qunivex folder name.

Deactivating stops the plugin and removes the bubble from your site, but keeps your settings. Deleting removes the plugin's single option row entirely, including the stored API key.

Questions, or something not covered here? Get in touch — or see the other integrations if you want your agent somewhere besides your website.