# Replyvane Chat Support (version 5.2)

A chatbot for any WordPress website. It answers visitors from your FAQ and from your website's own public pages, and optionally lets them live chat with your team.

**How it answers:**
- **Works without AI:** the built-in engine needs no API keys, outside services or running costs. Everything runs on your own site. Optional AI answers use the AI provider set up for your site in WordPress 7.0+.
- **Clicked questions** show your FAQ answers.
- **Typed questions** are matched against your FAQ first. If there's no clear match, the chatbot finds the most relevant section of your website and replies with its sentences, word for word, plus a link to the page.
- **If the website doesn't cover the question,** it shows the closest questions instead of guessing.

**Works on any site:**
- On activation it reads every public page of the site it's installed on.
- It creates starter questions from that content:
  - FAQ sections and accordions already on your pages
  - About, Contact, Prices/Plans, Services, Booking and policy pages
  - contact details and opening hours
  - WooCommerce products

**Public information only.** Pages are read exactly as a logged-out visitor sees them. Private, draft and password-protected pages, account, cart and checkout pages, anything behind a login, and addresses you list in "Pages to keep out" are never read. Accounts, orders and form entries are never touched.

## Updating from an earlier copy

Earlier private builds of this plugin used other names and folders. Version 5.2 is **Replyvane Chat Support**, in the folder `replyvane-chat-support`.

To update:
1. Upload `replyvane-chat-support.zip` under Plugins → Add New → Upload Plugin, and activate it.
2. On activation it automatically:
   - renames your database tables: questions, activity, website knowledge, and live chats and messages
   - copies all settings
   - moves Live Chat Agents to the new role
   - moves support reports
   - switches off the earlier copy
3. A notice on the Plugins screen confirms this. Then delete the earlier copy.

**AI engine:** if the earlier copy used an AI provider with its own API key, it now uses **WordPress AI** (WordPress 7.0+). Set up your provider once under **Settings → Connectors**. The API keys and model names the earlier copy stored are deleted.

The support address can be set in `wp-config.php` with `REPLYVANE_REPORTS_EMAIL` and `REPLYVANE_REPORTS_WEBHOOK`; the names used by earlier builds still work.

## Files

- `readme.txt`: the standard WordPress plugin readme (description, installation, FAQ, external services, changelog). It passes WordPress's Plugin Check with no errors or warnings.
- `README.md`: this guide.

## Install on any website

1. Upload `replyvane-chat-support.zip` under Plugins → Add New → Upload Plugin, and activate it.
2. The plugin reads the website straight away. A notice shows progress, and a second notice confirms the starter questions it created.
3. Review everything under **Replyvane → Questions**. Edit, delete or add questions freely. Questions you edit are never overwritten.
4. Check **Replyvane → Website knowledge**:
   - the list of pages the chatbot can use (make sure nothing private is there)
   - **Try a question**, which shows the answer a visitor would get
5. To test privately first, set **Settings → Who can see the chat** to **Administrators only**.

**Upgrading from an earlier version:** your existing questions, settings and chats are kept. The website is read automatically within a minute. To also create questions from the website, go to **Website knowledge** and click **Create questions from website**. Your existing questions are left as they are.

## Look and feel

Under **Replyvane → Settings → Look and feel**. A **live preview** beside the settings shows the chat window, notification and chat button, and updates as you change the name, colours, icon, font, avatars, position, notifications and engine, before you save.
- **Main colour and font** follow your theme automatically. They're read from Elementor Site Settings, a block theme's button colour and fonts, or common Customizer settings. You can choose your own instead.
- **Readable text:** text on the main colour switches between white and dark automatically, and links in the theme colour are darkened if needed.
- **Question buttons and answer bubbles** have their own background and text colours. Leave them empty to use light shades of the main colour.
- **Chat button icon:** choose one of 8 icons, or your own image from the Media Library. Tick "Fill the whole button" for photos.
- **Notifications:** when a reply arrives while the chat is closed, the button shows a counter, a short preview and a gentle pulse, and the tab title shows "(1)" if the tab is in the background. A soft sound is optional.
- **Avatars beside messages** (on by default): the chat button icon beside the chatbot's answers, a person icon beside the visitor's messages, and the team member's photo beside their live chat replies.
- **Typing indicators** in live chat work both ways:
  - Visitors see "Davia is typing…" with animated dots, beside her photo, while she writes a reply.
  - Team members see "Maria is typing…" in the inbox while the visitor writes.

  The signal is sent at most every 3 seconds while typing, lasts 6 seconds, and clears as soon as the message is sent. While someone is typing, the other side checks for new messages more often, so the reply appears quickly.
- **Team member photos** in live chat come from each person's WordPress profile (Gravatar, or a profile-picture plugin). Without one, a person icon is shown. The live chat header shows who you're chatting with.

## Answer engine: built-in or WordPress AI

Under **Settings → Answer engine**, choose how typed questions are answered:

- **Built-in (no AI)**, the default: free and instant, nothing to set up.
- **WordPress AI** (WordPress 7.0 and later): the AI provider you set up once for your whole site under **Settings → Connectors** writes the answer, through the WordPress AI Client. The plugin never contacts an AI service itself and never stores API keys. Click **Test connection** to check it.

**Rules that apply to the AI engine:**
- Only the visitor's typed question and the most relevant **public** passages of the site (plus matching FAQ answers) are sent.
- The AI is told to answer only from that content and never to invent prices, policies or links.
- If the content doesn't cover the question, the visitor sees the usual suggestions.
- If no answer comes back (no provider set up, or the provider can't be reached), the built-in engine answers instead.
- Answers are reused for the same question until the website changes, which keeps costs down.
- An "AI answer based on our website" label is shown by default.
- Clicked FAQ questions always show your own answers.

## Support

**Replyvane → Support** lets site owners send a suggestion, bug report or question, with:
- steps to reproduce and how serious the problem is
- up to 3 screenshots or log files (images, PDF, .txt/.log, 5 MB each)
- optional technical details, which can be previewed before sending: versions, theme, active plugins and chatbot settings, but no visitor or chat data

Each report is saved on the site ("Sent from this site" list) and emailed to the plugin developer.

**Plugin developer: set your support inbox before distributing.** At the top of `replyvane-chat-support.php`, set `REPLYVANE_REPORTS_EMAIL`. You can also set `REPLYVANE_REPORTS_WEBHOOK` to receive every report as JSON on your own server. Without either, reports are only saved on the site, and the Support screen says so.

Attachments are stored in `wp-content/uploads/replyvane-support/` with random names. On Apache the folder is also blocked by an `.htaccess` file. On Nginx, add a rule denying access to that folder.

## Pages to keep out

Under **Settings → Answers from your website → Pages to keep out**, tick any public page, post or product the chatbot must never read or quote.
- The list can be searched, and "Show ticked only" shows just your choices.
- **Sub-pages** of a ticked page are kept out too.
- **As soon as you save,** kept-out pages are removed from the chatbot's knowledge, and the site is re-read in the background.

Pages that are hidden automatically are shown **ticked and locked**, with the reason:
- **Login or account page**
- **WooCommerce cart / checkout / account page**, or **Hidden from the shop**
- **Hidden from search engines** (Yoast or Rank Math noindex)
- **Members only** (WooCommerce Memberships, Paid Memberships Pro, MemberPress, Restrict Content Pro)
- **Needs a login to view** (found when the site was last read)
- **Inside a kept-out page**

Private, draft and password-protected content, and users, orders, bookings and form entries, are never read and aren't listed.

**Upgrading from 4.4 or earlier:** addresses you had added to the old "keep out by address" box are converted into ticked pages automatically.

## How answers from your website work

1. **Reading.** Every public page is read (daily, and whenever a page is updated), split into sections under their headings, and stored in a searchable table. Collapsible FAQ questions (accordions, toggles, `<details>`, and Yoast or Rank Math FAQ blocks) are treated as headings, so each answer is filed under its question.
2. **Understanding the question:**
   - Filler words are ignored ("I have a question regarding… could you please explain").
   - Everyday phrases are mapped to the words websites use ("money back" → refund, "how much" → price, "companies" → corporate/business).
   - Word endings are simplified ("plans" → plan).
3. **Finding the section.** Every candidate section is scored. Words in its heading or page title count most, and rare words count more than common ones. The answer is only used when:
   - the weighted match is at least 50%, **and**
   - at least 60% of the question's words appear in that section.
4. **Writing the reply:**
   - **Short section:** shown in full under its heading.
   - **Long section:** the best-matching lines and what follows them.
   - **Question about a whole page** (e.g. "explain your membership plans"): an overview with one line per section.

   Links on the page become clickable, and the source page is linked under the answer.
5. **No confident answer:** the visitor sees the closest FAQ questions, or the "couldn't find an answer" message and the contact button. These questions appear in **Visitor activity → Typed questions with no answer**, so you can add them to your FAQ.

## Troubleshooting: typed questions only show "closest questions"

This means no answer was found on the website. Check in this order:

1. **Has the website been read?** Open **Replyvane → Website knowledge**. If "Pages the chatbot can use" is 0, click **Scan website now**. If a warning says the chatbot hasn't read your website yet, click **Read my website now**. Some hosts switch off WordPress's scheduled tasks (WP-Cron), so the automatic scan never starts; reading from this screen works without it.
2. **Does the website answer it?** Type the same question into **Try a question** on that screen.
   - **If it answers there but not in the chat,** clear your caching plugin's cache (and Cloudflare, if used), then reload the page with Ctrl+F5.
   - **If it doesn't answer there either,** the website doesn't contain a clear answer. Add it as an FAQ question, or add the information to a page and scan again.
3. **Is "Answer typed questions from the website" switched on?** It's under **Settings → Answers from your website**.

## Adding questions with JSON

1. Go to **Replyvane → Import / Export**.
2. Click **Download blank template** (or **Download current questions** to edit what you already have).
3. Edit the file in any text editor. Each question looks like this:

```json
{
  "id": "private-sessions",
  "category": "services",
  "question": "Do you offer private sessions?",
  "answer": "Yes. One-to-one sessions last 60 minutes.\n\n**Price: $95.**",
  "keywords": ["private", "one to one", "personal"],
  "links": [{ "label": "Book a session", "url": "https://example.com/booking/" }],
  "related": ["prices", "booking"],
  "featured": false,
  "order": 6,
  "active": true
}
```

4. Import the file:
   - **Add and update** adds new ids, updates matching ids, and keeps everything else.
   - **Replace everything** deletes all current questions and topics first.

The importer checks the whole file before changing anything and lists any problems, such as a missing answer, a duplicate id, or a related question that doesn't exist.

### Fields

| Field | Required | Meaning |
|---|---|---|
| `question` | Yes | What visitors click. |
| `answer` | Yes | `\n` = new line, `\n\n` = new paragraph, `- ` = bullet, `1. ` = numbered step, `**bold**`, `[text](https://…)` = link. |
| `id` | Recommended | Lowercase letters, numbers and hyphens. Re-importing the same id updates that question. |
| `category` | Recommended | Topic id from the `categories` list. |
| `keywords` | No | Words visitors might type, to help typed questions find this answer. |
| `links` | No | Up to six buttons under the answer. Web links, `mailto:` or `tel:`. |
| `related` | No | Ids of questions to suggest next. |
| `featured` | No | `true` shows it as soon as the chat opens. Aim for 5 or 6. |
| `order` | No | Lower numbers show first. |
| `active` | No | `false` hides it without deleting it. |

Topics go in `categories`: `{ "id": "services", "title": "Services", "order": 2 }`.

## Live chat

Switch it on under **Replyvane → Settings → Live chat with your team → Turn on live chat**. Switching it off hides the button and the inbox, and keeps past chats.

### For visitors

1. A **"Chat with our team"** button appears in three places: when the chat opens, under every answer, and when nothing matches a typed question.
2. What happens next depends on whether someone is available:
   - **If a team member is online** (and it's within business hours, if you set them), the visitor enters their name, email and question, and chats with your team in the same window.
   - **If nobody is online,** the same form becomes **"Leave us a message"**. The message is emailed to your team, who reply by email.
3. The chat carries on if the visitor moves to another page.

### For your team

- **Live Chat** in the dashboard menu is the inbox. Click **Go online** to receive chats.
- You stay online while any dashboard page is open in your browser. Close it for about 2 minutes and you're treated as away, so visitors never wait for someone who isn't there.
- **Take this chat** assigns it to you. If two people click at once, only the first gets it.
- You see which page the visitor asked from and which FAQ questions they opened before chatting.
- **Insert an FAQ answer** drops any FAQ answer into your reply.
- **Chat history** lists finished chats. Administrators can delete a chat, for example if a visitor asks you to remove their data.

### Replying to messages by email

Messages left while nobody was online, and chats the visitor left before anyone joined, appear under **Messages to answer by email**. Click one to open the built-in email form:
1. **To** is filled in with the visitor's name and address.
2. **Subject** is pre-filled ("Re: your message to …") and can be changed.
3. The **message** starts with "Hi (first name)," and your signature. Click anywhere in it and the cursor goes to the empty line, ready to type. **Insert an FAQ answer** adds any FAQ answer at the cursor.
4. **Send mail** sends it straight away. No email app opens.

What happens when you click **Send mail:**
- The email uses a clean layout with your site name, your reply, and the visitor's original message quoted underneath.
- It is sent **from the website's address**, with **Reply-To set to the team member**, so the visitor's reply lands in that person's inbox. You can switch to sending from the team member's own address in Settings, but that's more likely to be marked as spam.
- The sent email is saved in the conversation, marked "Email".
- The message is marked as handled and moves to Chat history.
- Finished chats with an email address can get a **follow-up email** the same way.

Delivery depends on your site's email setup. Install an email-sending plugin such as WP Mail SMTP and use an address on your own domain.

### How team members are notified

- **In the dashboard:** a sound, a desktop pop-up, a flashing tab title such as "(1) Live Chat", and a red counter in the admin bar and menu. These appear within about 10 seconds on any dashboard page, or 4 seconds on the Live Chat page. Click **Turn on desktop alerts** once to allow pop-ups.
- **By email** to the team address:
  - when a chat starts (optional)
  - when nobody has taken a chat after a set number of minutes
  - when a visitor leaves before anyone joins
  - for every message left while nobody was online

  Offline messages have Reply-To set to the visitor, so you can reply straight from your inbox.
- **Privacy:** by default, alerts say only who is waiting, not what they wrote. Turn on "Include what the visitor wrote" if your team needs it.
- **Reliable email:** WordPress's own email often lands in spam. Install an email-sending plugin such as WP Mail SMTP.

### Adding team members

Administrators can always answer chats. For other staff, go to **Users → Add New** and choose the role **Live Chat Agent**. That role can use the Live Chat inbox but can't change the website.

### Technical notes

- Messages travel by short polling: the visitor's browser checks every 3 seconds during a chat, and the team inbox every 4 seconds. This works on any host without extra servers.
- Live chat responses are sent with no-cache headers. If you use Cloudflare or a host-level cache, make sure `/wp-json/replyvane/v1/live/` is never cached.
- Visitors are identified only by a random chat key stored in their browser; the server keeps just a hash of it.
- Spam protection:
  - a hidden spam-trap field
  - at most 5 new chats per hour from one address
  - at most 60 messages per 10 minutes
- Finished chats are deleted after 90 days by default (adjustable).
- Tables: `{prefix}replyvane_live_chats` and `{prefix}replyvane_live_messages`. Email replies are saved as messages with sender `email`, and are never shown to the visitor in the chat window.

## Dashboard screens

- **Questions:** list, search, add, edit and delete questions. Set popular questions, related questions, buttons and order.
- **Topics:** rename, reorder, add or delete topics.
- **Website knowledge:**
  - what was read from the site
  - **Scan website now**
  - **Create questions from website**, which refreshes generated questions and never touches ones you added or edited
  - **Try a question**
  - the list of pages used
- **Import / Export:** import JSON, download current questions, download the blank template.
- **Visitor activity:**
  - "Typed questions with no answer" shows what visitors asked that your list doesn't cover; click one to write an answer for it.
  - Most opened questions.
  - Latest activity, with a CSV download.
- **Live Chat** (when switched on): the team inbox and chat history.
- **Settings:** who can see the chat (everyone, or administrators only for previewing), live chat on/off and its options, name, welcome message, colours, position, whether visitors can type questions, the no-answer message, the contact button, and how long activity is kept.

## Database tables

- `{prefix}replyvane_content`: the searchable copy of your public pages.
- `{prefix}replyvane_harvest`: questions and answers found on your pages.


- `{prefix}replyvane_items`: questions and answers.
- `{prefix}replyvane_log`: visitor activity. It records the time, what was clicked or typed, the page, and a random conversation id. No name, email, IP address or account is stored. Entries older than 180 days are deleted automatically (adjustable).

Topics are stored in the `replyvane_categories` option.

## Speed and scale

The question list is downloaded once per visitor (about 30 KB for the starter set) and cached by the browser. Clicking and searching happen instantly in the browser without contacting the server, apart from a tiny anonymous activity note. There is no limit on how many people can use it at once.

## For developers

- `replyvane_show_widget` filter: return false to hide the chat on specific pages.
- REST:
  - `GET /wp-json/replyvane/v1/data`: public questions
  - `GET /wp-json/replyvane/v1/answer?q=…`: answer from the website; cached until content changes; 60 per visitor per 10 minutes
  - `POST /wp-json/replyvane/v1/event`: activity
- `replyvane_kb_is_public` filter: return false to keep a page out of the website knowledge.
- `replyvane_kb_post_types` filter: change which post types are read.