Konradodocs

Install the WordPress plugin

Put your live chat on a WordPress site with the Konrado AI plugin, and let it recognize customers who are logged in.

WordPress
Website
Your Konrado live chat on every page of your WordPress site

The Konrado AI plugin puts your agent's live chat on every page of a WordPress site. You install the plugin, paste one ID and save. You do not edit your theme or paste any code. It takes about 5 minutes. Not on WordPress? Install the chat on your website.

The plugin is not in the WordPress.org plugin directory, so a search in Add New Plugin does not find it. Download it from the Konrado console, or as main.zip. The source code is public at github.com/konradoai/wordpress-plugin.

How the plugin works

The plugin adds one script tag to the footer of every page:

<script async src="https://app.konrado.ai/website-chat/v1/loader.js" data-konrado-widget-id="wgt_…"></script>

That tag loads the chat of your Live chat channel. Everything visitors see in the chat is set in Konrado, not in WordPress: the colors, the greeting, the languages and the position. A change there shows on the next page load, with nothing to do in WordPress.

The plugin has three settings under Settings › Konrado AI:

SettingRequiredWhat it does
Chat IDYesConnects the site to your Live chat channel. Starts with wgt_
Recognize customers who are logged in to WordPressNoTells Konrado who a logged-in visitor is. Off to start with
Signing secretWith the checkboxShows once the checkbox is ticked. Proves to Konrado that the customer's details come from your site

What the plugin cannot do

Not possibleWhy
Change how the chat looks or behavesThe look, greeting, languages and position are set in Konrado
Turn the chat on or offUse the chat's Status page in Konrado. Deactivating the plugin removes the chat from the site
Show the chat on some pages onlyThe plugin loads the chat on every page whose theme calls the footer
Give Konrado a customer's orders, invoices, services or tickets on its ownThe plugin sends the WordPress user as wp:<user ID>, which matches no client in your help desk. Send the real client ID
Update itselfDownload the ZIP again and upload it. Update the plugin

Before you start

  • WordPress 5.7 or newer and PHP 7.4 or newer. The plugin is tested up to WordPress 7.1.
  • A WordPress account that can install plugins, usually an Administrator.
  • A Konrado agent with a Live chat channel.
  • A theme that calls wp_footer(). Almost every theme does.

Install the plugin

Download it from Konrado

Open AgentsLive chatInstall. On the Snippet tab, under Choose your platform, pick WordPress and click Download plugin (.zip). Keep the page open: step 3 shows your Chat ID with a copy button.

The WordPress steps of the Install page: Download plugin (.zip), Setup guide, and the Chat ID with its copy button

The button downloads wordpress-plugin-main.zip, the current version of the plugin.

Upload it to WordPress

In WordPress, open Plugins › Add New Plugin. In WordPress 7 the menu item reads Add Plugin. Click Upload Plugin, then Choose File, pick the ZIP and click Install Now.

The WordPress Add Plugins page with Upload Plugin open and wordpress-plugin-main.zip chosen

Activate it

WordPress shows Plugin installed successfully. Click Activate Plugin. Konrado AI now sits in the plugin list with a Settings link. Until you add a Chat ID, the Plugins screen reminds you: Konrado AI is active, but the chat will not appear until you add your Chat ID.

The WordPress Plugins screen with Konrado AI active, its Settings link and the reminder to add the Chat ID

The plugin's folder is called wordpress-plugin-main, the folder name inside the ZIP. That is expected. You do not need to rename it.

Paste your chat ID

Open Settings › Konrado AI. Paste the Chat ID from the Install page into Chat ID: wgt_ followed by 32 characters. Leave the checkbox unticked for now and click Save Changes.

The Konrado AI settings in WordPress with the Chat ID filled in and the logged-in customers checkbox unticked

A value that is not a Chat ID gets That is not a valid Chat ID. It starts with "wgt_" - copy it from your Konrado dashboard. WordPress keeps the previous value. Plugin version 1.0.1 and older call the field Widget ID. It is the same ID.

Check the chat on your site

Open any page of your site in a new browser window. The chat button sits in the bottom corner. Open it and send a test message.

No button? Check that the chat is on: the switch on AgentsLive chatStatus must read Enabled.

Recognize logged-in customers

This part is optional. Use it when visitors have accounts on your WordPress site, such as WooCommerce customers or members. When a logged-in customer opens the chat, Konrado knows their name and e-mail address and does not have to ask.

Copy the secret key

On the Install page, unfold Identity verification under the install steps. If there is no key yet, click Generate secret key. Then click Copy secret key, next to the masked key. You do not need to reveal the key to copy it.

The Identity verification panel: the masked secret key with its reveal and copy buttons, the last rotation date and the warning to treat the key like a password

Paste it into WordPress

In Settings › Konrado AI, tick Recognize customers who are logged in to WordPress. The Signing secret field appears. Paste the key and click Save Changes.

The Konrado AI settings with the logged-in customers checkbox ticked and the masked Signing secret

With the checkbox ticked and no secret, the page warns: Recognizing logged-in customers needs the signing secret. Until you add it, every visitor chats anonymously.

To test it, log in to your site as a customer, open a page and ask the chat for your name and e-mail. Konrado answers with the details of the WordPress account.

VisitorWhat Konrado knows
Logged in, right keyTheir verified name and e-mail
Not logged inNothing. The chat is anonymous
Logged in, wrong or missing keyNothing. The chat falls back to anonymous, with no error

If you use a page cache, do not cache pages for logged-in users. The customer's details are signed into the page each time it renders, and a signature works once, for five minutes. Most caching plugins already skip logged-in users. Anonymous visitors are not affected.

Security model

Security model

Treat the signing secret like a password. Anyone who has it can pose as any of your customers to Konrado. Keep it only in the plugin settings, never in a ticket, a screenshot or a document. If it leaks, open the menu next to the key under Identity verification, click Rotate and paste the new key into WordPress.

The Chat ID is public. It is in the source of every page, and it only says which Live chat channel to load. To choose which sites may load your chat, open the Domains tab of the Install page, turn on Only allow embedding the agent on specific domains and add your site's domain.

When recognition is on, the plugin identifies a customer like this:

  • Your server signs the details while WordPress renders the page. The secret never reaches the browser.
  • The plugin reads the logged-in WordPress user and signs a short token (HS256) with the signing secret. The token goes into the chat's script tag as data-konrado-user-token.
  • Konrado checks the signature with the same key. Only a valid, unexpired, unused token identifies the visitor. Anything else counts as an anonymous visitor.
  • Visitors who are not logged in get the plain script tag, with no token.

The token holds these fields:

FieldValue
subThe customer ID, wp:<WordPress user ID> unless you change it
emailThe WordPress user's e-mail address, shown to Konrado
nameThe WordPress user's display name, shown to Konrado
iat, expWhen it was issued, and when it expires, five minutes later
jtiA random value, so each token works once

Customer ID and your help desk

Konrado reads sub as the customer's client ID in your help desk, such as WHMCS. For a matching client, Konrado can read that client's own invoices, services and tickets.

A WordPress user ID is a different number: WordPress user 5 is not help desk client 5. So the plugin sends it with a wp: prefix, which matches no client. Out of the box, Konrado knows only the customer's name and e-mail, not their account.

If your WordPress users are also help desk clients and you store each user's client ID, a developer can send the real client ID with the konrado_ai_customer_id filter. For example, in a small custom plugin or your child theme's functions.php:

add_filter('konrado_ai_customer_id', function ($id, $user) {
    return get_user_meta($user->ID, 'whmcs_client_id', true) ?: '';
}, 10, 2);

An empty string sends no identity for that user, so they chat anonymously. Return a client ID only when it surely belongs to that WordPress user. Read how identity verification works.

Update the plugin

The plugin does not update itself. To install a newer version:

  1. Download the ZIP again from the Install page, with WordPress picked.
  2. In WordPress, upload it under Plugins › Add New Plugin › Upload Plugin.
  3. WordPress sees that the plugin is installed and offers to replace it with the uploaded one. Confirm.

Your Chat ID, the checkbox and the signing secret stay.

If something is wrong

What you seeWhat to do
The chat button does not appearCheck that the Chat ID is saved under Settings › Konrado AI. The Plugins screen warns when it is missing
The chat button still does not appearCheck that the chat's Status page in Konrado reads Enabled
The chat works on another site but not on yoursIf Only allow embedding the agent on specific domains is on, add your site's domain on the Domains tab
The script tag is missing from the page sourceYour theme must call wp_footer(). Switch to a default theme for a moment to check, then ask the theme's author
That is not a valid Chat IDCopy the ID again with the copy button on the Install page: wgt_ followed by 32 characters
Konrado does not recognize a logged-in customerCheck that the checkbox is ticked and Signing secret is filled in
Recognition stopped workingSomeone probably rotated the key. Copy the current key from Identity verification into Signing secret
Recognition works only after you clear the cacheKeep logged-in users out of your page cache. A cached page carries an expired or used token
Konrado knows the name and e-mail but not the customer's accountThat is the default. Send the real client ID
WordPress asks for FTP details when you uploadWordPress cannot write to its plugins folder, a hosting setting. Unzip the plugin into wp-content/plugins/ with your hosting file manager or FTP, then activate it under Plugins

Remove the plugin

  1. In WordPress, open Plugins, click Deactivate under Konrado AI, then Delete. This also removes the plugin's three settings.
  2. If you used logged-in customer recognition, rotate or remove the secret key under Identity verification.
  3. To stop the chat everywhere it is installed, turn it off on AgentsLive chatStatus.

Last updated on

On this page