chatleadr Docs

Install on WordPress

The plugin connects your WordPress site to your Chatleadr account and renders the widget for you. It writes nothing into your theme and nothing into your WordPress database, and it changes nothing on a live site until you activate the bot in step 3. It adds one Chatleadr screen to the WordPress admin, where Overview and Recent Leads read back the conversations and leads from this site. Leads from WhatsApp, Instagram or another website are on the Leads page in Chatleadr.

Requires WordPress 5.8 or newer and PHP 7.4 or newer.

WordPress admin: Chatleadr Settings & Rules chatleadr Overview Settings & Rules Billing Recent Leads Version 1.1.6 Authentication •••••••••••••••••••••••• Save Connection From Bot Settings → Deployment in your Chatleadr dashboard. Page Visibility Rules Control exactly where the bot is allowed to load on your website. Publish on all public pages Unchecked, the bot renders nowhere unless an Included Path forces it. Show in WordPress Admin Section For testing the bot while logged in as an admin. Included Paths If populated, the bot displays ONLY on these paths. /pricing Excluded Paths Never loads here. Matched from the start of the URL. /checkout Save Rules
The plugin's own screen inside WordPress admin. Page Visibility Rules decide where the widget loads, and an Included Path list, once it has anything in it, becomes the only place it loads.

1. Install and Activate#

In the Chatleadr dashboard, open your bot's Channels tab, then the WordPress card, and download the plugin ZIP. In your WordPress admin, go to Plugins → Add New → Upload Plugin, upload the ZIP and activate it. A Chatleadr entry appears in the admin menu.

2. Connect With Your Secret Key#

An Owner or Admin of the workspace creates the key and pastes it into the plugin:

  1. On the same WordPress card you downloaded the ZIP from, click Create secret key. The key appears once.
  2. Click Copy. Chatleadr does not show the key again after you close the window.
  3. In the WordPress admin, open Chatleadr Settings, paste the key into Secret Key on the Settings & Rules tab, and click Save Connection. The screen reports Successfully connected to Chatleadr! when the key works.

When the card says the bot already has a key and you no longer have it, click Replace key. The old key stops working at once, so paste the new one into the plugin straight away.

To disconnect the site, click Disconnect on the WordPress card. The secret key stops working, so the plugin can no longer load your leads, statistics or settings until you create a new key and paste it in. The chat on the site does not use the secret key, so visitors see no change. To take the chat off the site, deactivate the plugin.

Connect From the Plugin Instead#

The plugin can connect the site to a bot you already have without a key. An Owner or Admin of the workspace chooses the bot, within 15 minutes of starting the connection.

  1. On the Chatleadr screen in the WordPress admin, click I Already Have an Account. In a version of the plugin before 1.1.5, click Create Free Account instead. Chatleadr opens in a new tab, and the WordPress screen shows a six-digit Connection code.
  2. Sign in to Chatleadr if you are not signed in already. Chatleadr lists the bots in your workspace. You enter the code on this tab only, so if you closed it, click Reopen Onboarding Tab on the WordPress screen.
  3. Choose the bot for this site.
  4. In Connection code, enter the code from the WordPress screen.
  5. Click Connect bot. If the bot already has a secret key, Chatleadr asks before replacing it, because the plugin on any site still using the old key can no longer load your leads, statistics or settings.
  6. Return to WordPress and leave the Chatleadr screen open. The site connects within a few seconds.

If you have no Chatleadr account yet, click Create Free Account in step 1 instead. The first bot you build during signup is the one that connects, and it needs no code.

If you already have an account, the plugin connects only a bot you already have. To use a new bot for the site, create it on the Bots page first, then connect it with its secret key.

After five wrong codes, Chatleadr closes the connection and no bot is connected. To start again, click Cancel and Connect Manually on the Chatleadr screen in WordPress, then click I Already Have an Account. WordPress shows a new code.

The plugin accepts a bot only when the bot's Domain is not set or names this site. A subdomain counts either way, so a bot set up for example.com connects to shop.example.com. Chatleadr shows the reason beside any bot the plugin would not accept, and you cannot choose that bot.

A version of the plugin that shows no connection code cannot connect a bot you already have. Connect that bot with its secret key instead.

3. Activate the Bot#

Once connected, the settings screen shows an Activate Bot control, and until it is switched on the plugin renders nothing. To try the bot on your own pages first, activate it and turn on Preview mode: show only to logged-in staff in Visibility Settings, which shows the widget only to logged-in users who can edit posts.

4. Choose Where It Appears#

Visibility Settings control which parts of the site show the widget. Start with everywhere, then narrow it where a chat launcher is unhelpful, such as checkout or a landing page with its own call to action.

5. Check It Worked#

Check the install with the steps in install on any website.

Common Problems#

"Invalid Secret Key or Chatleadr API is unreachable." Either the key is wrong or the host is blocking outbound HTTPS to api.chatleadr.com. Retype the key first, then ask the host about outbound connections.

"The connection timed out. Start again from this screen." This belongs to the Create Free Account auto-connect path. Connect with your secret key instead, or retry with other plugins temporarily deactivated.

Connected and activated, but no widget. Check Visibility Settings, then clear your caching plugin's cache, which may be serving a page built before you activated the bot.

The widget appears twice. The plugin is running and the manual snippet is also in the theme. Remove the snippet.

Common Questions#

Is the Secret Key the Same as the Bot Key?#

No. The bot key identifies a bot to the widget and is visible in page source. The secret key authorises a site to act for your account and stays private. The plugin uses the secret key, the manual snippet the bot key.

Does the Plugin Work With Caching Plugins?#

Yes. The widget fetches its configuration from Chatleadr each time it loads, so a cached page still runs the current bot. Clear the cache after activating the bot and after changing Visibility Settings, because those two decisions are built into the page.

Can I Run Different Bots on Different Pages?#

The plugin runs one bot per site, chosen by the secret key you saved. To run a second bot on particular pages, add that bot's manual snippet to those pages and use Visibility Settings to keep the plugin's bot off them.

Will a Theme Update Break the Installation?#

No. The plugin renders the widget itself and holds the configuration in Chatleadr, so nothing lives in theme files. That is the main reason to prefer it over the manual snippet on WordPress.