AI Chatbot & Appointment Booking

Installation guide#

Botermin – AI Chatbot & Appointment Booking, version 1.8.0

This guide takes you from uploading the files to the first working chat. For everyday use there is a second file: MANUAL.md.

1. Requirements#

Not needed: Composer, npm, a build step, a different theme or any other plugin. The mbstring extension is not required — the plugin brings its own replacement.

You will need access to an AI provider, but not before section 5 — the installation itself works without one.

2. Upload the files#

There are two ways. One is enough.

Way A: through the WordPress interface (ZIP)#

1. Pack the folder ki-chatbot-booking into a ZIP file — important: the folder itself must be inside the ZIP, not just its contents.
2. Plugins → Add New → Upload Plugin → choose the ZIP → Install Now.

Careful on Windows: a ZIP created with PowerShell (Compress-Archive) uses backslashes in the paths, and WordPress then extracts it incorrectly. Use right-click → "Send to → Compressed (zipped) folder" or 7-Zip.

Way B: via FTP/SFTP (recommended for large folders)#

Upload the complete folder ki-chatbot-booking to wp-content/plugins/. That is all — no ZIP needed.

3. Activate#

Plugins → Installed Plugins → "AI Chatbot & Appointment Booking" → Activate.

Activation does the following automatically:

• Six tables are created: …kcb_appointments, …kcb_messages, …kcb_logs, …kcb_leads, …kcb_waitlist and …kcb_clients.
• Three cron jobs are scheduled: daily clean-up, hourly calendar retry, and an hourly run for reminders, review requests and releasing unpaid holds.
• A random key for the ICS subscription feed is generated.

AI Chatbot appears in the left-hand menu with eight subpages.

After activation the bot is not yet visible — that is deliberate. You switch it on in section 7.

The interface follows the language of your WordPress installation. If your site runs in German, French, Japanese or any of the other 31 supported languages, the backend and every text the visitor sees appear in that language without further setup.

4. First check#

Open AI Chatbot → Settings. Two notices should appear at the top:

No AI provider is active yet … The chatbot is currently switched off …

Both are correct at this point. If you get a PHP error message instead, the PHP version is wrong (see section 1).

5. Enter an AI provider#

1. Open the AI providers tab.
2. Tick at least one provider and enter its API key. For customers in the EU, Mistral (EU) is a good choice — the traffic light behind it shows the data protection rating.
3. Assign a priority: 1 is asked first, 2 is the backup. Two providers make sense so the bot keeps working during an outage.
4. Save.
5. Only then click Test connection — the test runs against the stored key and shows the response time.

A stored key is never shown again. Leaving the field empty means "unchanged"; a single minus sign (-) deletes it.

Test fails? See section 9.

6. Describe the business, services and hours#

General tab: company name and, above all, the large field Business information — this is the entire knowledge base. Address, directions, parking, payment methods, frequently asked questions. What is not written there, the bot will not invent.

Appointments tab: services with duration and price. Opening hours tab: opening, closing and break per weekday.

Details are in MANUAL.md.

7. Switch it on#

General tab → tick Chatbot active → save.

Open the website in a new tab: the launcher appears in the bottom right corner.

If the bot should only appear on a particular page, additionally tick "shortcode only" and put [ki_chatbot] on that page.

8. Acceptance test (10 minutes)#

1. Ask a question that is answered in the business text → the bot replies with your own information.
2. Ask for an appointment → only genuinely free times are offered.
3. Book an appointment → confirmation email to the customer, notification to the business, entry under AI Chatbot → Calendar.
4. Check the failover: deliberately enter a wrong key for the first provider, save, and write again. The answer still arrives; the switch is recorded under Logs.
5. Afterwards enter the correct key again.

9. When something does not work#

Cache exceptions (important)#

If you use WP Rocket, WP-Optimize, LiteSpeed or similar, exclude:

• addresses containing ?kcb_termin= (customer self-service),
• the REST routes under /wp-json/kcb/v1/ (excluded by default in most plugins, but check).

Real cron job (recommended)#

Add to wp-config.php:

define( 'DISABLE_WP_CRON', true );

Then have your host call this every 15 minutes:

https://your-domain.com/wp-cron.php?doing_wp_cron

10. For resellers: several clients from one installation#

Only needed if you run the plugin for clients. It stays the same installation and the same code base:

1. Open AI Chatbot → Clients, switch reseller mode on, save.
2. Create clients: name and allowed domains (one per line, *.example.com for all subdomains).
3. Fill in the client's details (company name, knowledge base, colour, their email address and phone number, their privacy policy link). Empty fields fall back to your own base settings.
4. Copy the embed code and give it to the client:

<script src="https://your-domain.com/wp-content/plugins/ki-chatbot-booking/assets/embed.js"
        data-kcb-key="kcb…" defer></script>

The client inserts this single line before </body> on their website — on WordPress via a code snippet plugin or footer.php, for example. No plugin is installed on the client's site.

Your AI keys stay with you. Appointments, conversations and enquiries are kept separate per client. The overview shows appointments, conversations and token usage of the last 30 days — your basis for invoicing.

This section does not apply to the Single Business edition, which has no client management.

11. Updating#

With a licence key it happens by itself. Enter the key from your purchase confirmation under AI Chatbot › Licence and click "Activate". From then on WordPress announces new versions like for any other plugin, and one click on "Update" is enough.

The key does not expire. It only decides whether this website receives updates and for how many websites it is valid. If you give a website up, release it on the same screen — the place is then free for the next one.

Without a key nothing is switched off: the plugin is licensed under the GPL and keeps working exactly as before. It simply does not fetch new versions any more, and you install them by hand.

By hand: overwrite the folder ki-chatbot-booking via FTP or upload the ZIP again (WordPress asks before overwriting). Settings and appointments are kept; database changes run automatically on the next backend request.

Before larger jumps, as always: back up the database.

12. Uninstalling#

When the plugin is deleted, appointments and settings are kept on purpose — an accidental deletion must not destroy customer data.

If you really want everything removed, set the option kcb_delete_on_uninstall to 1 in the database beforehand. Then uninstall.php clears tables, options and transients on deletion.

13. What is where#

ki-chatbot-booking/
├── ki-chatbot-booking.php     start-up, widget output, shortcode, cron jobs
├── uninstall.php              deletion only on explicit consent
├── readme.txt                 WordPress standard format (English)
├── LIESMICH.txt               the same in German
├── INSTALL.md                 this file
├── MANUAL.md                  everyday use
├── INSTALLATION.md            installation guide in German
├── ANLEITUNG.md               everyday use in German
├── includes/                  the classes (logic)
├── admin/views/               the backend screens
├── assets/                    chat.js/css, admin.js/css, embed.js
└── languages/                 kcb.pot plus 33 translations (.po and .mo)

User manual#

Botermin – AI Chatbot & Appointment Booking, version 1.8.0

This manual explains the everyday use of the plugin. Uploading and activating is covered in INSTALL.md.

Contents#

1. How the bot works
2. The menu at a glance
3. General: knowledge base and abuse limits
4. AI providers and the privacy rating
5. Appearance: colours, position, launcher
6. Appointments
7. Opening hours
8. Connecting calendars
9. Enquiries and callbacks
10. Deposit (off by default)
11. Connections
12. Languages
13. Notifications
14. Privacy
15. Calendar, appointments and waiting list day to day
16. Reading the analytics
17. Logs
18. Managing clients (reseller mode)
19. What your customers see
20. Safeguards that always run

1. How the bot works#

The bot answers questions exclusively with the knowledge you give it (the General tab and optionally pages of your website). It never invents free appointments — those always come from the plugin's own availability calculation.

If it cannot answer something, it offers to forward the question and collects contact details for that. If your AI provider fails, the next one takes over automatically.

2. The menu at a glance#

AI Chatbot holds eight pages:

3. General#

Chatbot active switches the bot on or off on the website. "Shortcode only" shows it exclusively where [ki_chatbot] appears.

Business information is the single most important field — the entire knowledge base. Write down what customers ask again and again:

We are an independent car workshop in Sampletown, 14 Station Road.
Free parking directly in front of the building.
Payment by card, bank transfer or cash.
Courtesy car on request, please mention it when booking.
Technical inspection every Tuesday and Thursday, inspector on site.

Knowledge from the website (optional): instead of maintaining everything by hand, select pages and posts. If the text there changes, the bot answers with the new version automatically. The character limit keeps speed and cost in check — 6,000 is a good starting value.

Form of address: two buttons, formal or informal. The setting applies to everything a visitor sees — not just the bot's replies, but also the greeting and header of the chat window, error messages, the appointment confirmation, the reminder, the message from the waiting list, the review request, the deposit email, the page for managing an appointment and the text block for the privacy policy. The bot sticks to it even if a visitor writes differently.

In languages that have a real distinction (French, Spanish, Italian, Dutch, Polish, Japanese, Korean, Thai and others) the switch uses the proper forms of that language, not an approximation.

When switching, the plugin carries the template texts over automatically — but only those still standing unchanged as they came from the factory. If you wrote a greeting or an email yourself, your text stays; the message after saving tells you how many texts that affects so you can adjust them by hand. Check the Appearance and Appointments tabs afterwards.

Notifications to yourself (new booking, callback request) stay formal — the recipient is you, not the customer.

Tone now only describes the style, for example "friendly and matter-of-fact, short sentences". The form of address no longer belongs here.

Model behaviour: temperature 0.4 is factual, higher gets more creative (and less accurate). "History" defines how many earlier messages are sent along.

Cost cap: here you set an upper limit — per day and per month, in tokens or in euros. Whichever is reached first stops everything: the chatbot asks no AI provider until the end of the period, visitors get a matter-of-fact notice and can leave a callback request. That way a single night cannot burn the whole monthly budget. 0 means: no cap. At 80 and at 100 percent you get an email.

The money limit requires the prices per million tokens to be entered under AI providers — otherwise the plugin cannot calculate, and it says so at this point. The token limit always works. If you are unsure which value fits: below the input field you can see what you have used so far and what a million tokens currently costs you.

Currency: a three-letter code — EUR, USD, GBP, CHF, JPY, PLN and so on. It applies everywhere money appears: the cost display in the analytics, the caps, the notification emails and the deposit. Thirty currencies get their proper symbol; anything else is written with the code, which is always correct even if it is less pretty.

Abuse protection: messages per visitor in 10 minutes, characters per message, suspension period after a provider error.

4. AI providers#

Every row is one provider: checkbox, key, model, base URL, priority and the price per million tokens (for the cost calculation in the analytics — without an entry it stays empty instead of guessing).

The failover: provider 1 is asked first. If it fails — wrong key, quota empty, timeout — it is hidden for the configured suspension period and provider 2 answers. The visitor notices nothing.

The rating behind the name#

Hovering over the sign shows the reasoning. The rating is a decision aid, not legal advice — what counts is your contract with the provider.

5. Appearance#

The quickest way: click "Take colours and font from the active theme" at the top, then save. This reads your theme's colour palette and calculates the text colour on coloured backgrounds so that it stays readable. If your theme gives nothing away, the plugin says so openly instead of inventing colours.

Alternatively: one of the five colour moods (blue, green, anthracite, bordeaux, sand) or every colour individually.

Dark version: "automatic" follows the device setting — usually the best choice.

Window size changes immediately in the preview below.

Position: click one of the four boxes — top/bottom × left/right, plus the distances from the edge.

Launcher: wide with text, round or square; size 40–88 px; optional subtle pulsing; twelve included icons (speech bubble, calendar, clock, phone, tool, scissors, stethoscope …) or an image of your own.

Speech bubble at the launcher: appears next to the button after a few seconds, one click opens the chat. That is friendlier than a window opening by itself.

Open by itself: only if you really want it. Off by default on mobile, because it takes the whole screen there.

6. Appointments#

Services with name, duration and price text — the duration determines the grid.

Workstations (optional): lifting platforms, chairs, rooms or staff. Only with these do several appointments run at the same time. Each workstation can be limited to particular services.

Careful with existing data: appointments from before this setting have no workstation and block everything as a precaution.

Time grid: grid, buffer between appointments, lead time (how close to the hour a booking may be made), advance booking (how far into the future).

Blocked days: one date per line, format 2026-12-24.

Self-service: customers reschedule or cancel their appointment themselves through the link from the confirmation email — up to the configured deadline.

Waiting list: if everything is full, the bot registers those interested. When an appointment frees up, emails go out automatically — in order of registration.

Review request: X hours after the appointment, an email with a link to your Google profile. Without a stored link nothing is sent.

Email templates with placeholders: {name} {email} {service} {datum} {uhrzeit} {dauer} {firma} {telefon} {notiz} {terminlink} {bewertungslink}

The placeholder names stay German in every language — they are keys, not text.

7. Opening hours#

Opening, closing and lunch break per weekday. Ticking "Closed" takes the day out entirely. Free slots arise exclusively from this calculation.

8. Connecting calendars#

The internal calendar always runs and decides on availability. In addition, in any combination:

Google Calendar — create a project in the Google Cloud Console, enable the Calendar API, create an OAuth client (web application) and enter exactly the redirect address shown in the tab. Then enter client ID and secret, save, Connect with Google.

Apple / iCloud (CalDAV) — create an app-specific password at appleid.apple.com, enter the calendar address, your Apple ID and that password, then Test connection. Same procedure for Nextcloud.

ICS subscription feed — for every calendar without a write interface. Anyone who knows the address sees the appointments: do not share it publicly, and regenerate it if in doubt.

A calendar error never prevents a booking: the appointment is stored internally, the transfer is flagged and retried every hour.

9. Enquiries and callbacks#

If the bot cannot answer something, it offers to forward the question and asks for a name and how to get in touch. You get an email straight away; the enquiry appears under AI Chatbot → Enquiries.

There you can filter open/done, add a note and jump to the matching conversation. The number in the menu shows open enquiries.

10. Deposit#

This feature is switched off by default. Only when you switch it on and store credentials is anything charged at all.

Methods: Stripe (card, Apple Pay, Google Pay), PayPal.me or bank transfer with an explanatory text. Amount uniform or per service.

How it works with a deposit: the appointment is at first only held. Confirmation, calendar entry and email follow only once the payment arrives. If payment does not arrive, the slot is released again after the configured period — and the waiting list is told.

For Stripe, enter the address shown in the tab for the event checkout.session.completed in your account under Developers → Webhooks. With PayPal.me the incoming payment cannot be verified automatically; there you confirm the appointment by hand.

11. Connections#

The same bot, the same calendar, different entry points:

• Telegram: create a bot with @BotFather, enter the token, save, then click "Register webhook with Telegram".
• WhatsApp: enter the access token and the sender phone number ID. The number ID is in the Meta developer portal under WhatsApp › API setup.
• Instagram: access token of the account linked to your Facebook page. The account must be a business account and allow messages from tools in the Instagram settings.
• Facebook Messenger: its own page access token — not the Instagram one. The page ID may stay empty; then the page belonging to the token answers.

All three Meta services share one webhook address. That address and the verify token are at the bottom of the tab; enter both in the developer portal under Webhooks and subscribe to the fields. Which channel is meant is recognised by the sender of the notification.

Test connection. Every connection has its own button. It only asks the provider who you are — nothing is sent and nothing is changed. If it works, the bot, account or page name appears at the top; if not, the provider's error text is shown in plain words.

If nothing arrives: look under Logs. If a message arrives whose channel is not ticked here, that is recorded there — then only the tick is missing and the fault is not with Meta.

A credentials field stays unchanged when saving as long as it is empty. A single hyphen deletes the stored value.

Instead of quick-choice buttons, free times are listed there as text.

12. Languages#

Accepted languages: a tick for every language your business can genuinely advise in, and the rank — 1 is the primary language, 2 the secondary and so on.

If someone writes in a language that is not ticked, the bot does not simply answer in your language, but gives a matter-of-fact notice — first in the visitor's language, then in your primary language, along with phone and email.

It is about the language skills of your business, not a rejection of the person — and a way to reach you always stays open. If you want it worded differently, enter your own text ({sprachen}, {firma}).

In this case no request goes to the AI provider — it costs nothing.

Note the difference: this tab decides in which languages the bot advises. The language of the interface — backend, buttons, email templates — follows the WordPress installation and needs no setting here.

13. Notifications#

Here you decide what you get an email about — and what not.

Recipient. If the field stays empty, everything goes to the address from the appointment settings. If you want the post directed elsewhere (office, shared mailbox), enter it here; the appointment settings stay untouched.

The switches.

Every notification contains name, contact, service and time — you do not have to open the backend to look.

Emails to the customer. The last switch concerns not you but your customers: confirmation and cancellation. Only switch it off if you inform your customers another way — without a confirmation the customer has nothing in hand, no calendar file and no link for managing their appointment.

The reminder before the appointment and the review request remain under Appointments, because the texts for them live there.

If no email arrives: WordPress sends mail through the server. A sending plugin such as WP Mail SMTP with a real mailbox is more reliable than the server default, which often ends up in the spam filter.

14. Privacy#

Consent before the first message, retention period for chat histories (0 = do not store at all), link to the privacy policy.

Under Settings → Privacy of WordPress there is a ready-made suggested text that names the active providers with their country and adds a paragraph on third-country transfers as soon as a provider that is not green is active.

Appointments and histories are hooked into the WordPress export and erasure tools (Tools → Export/Erase Personal Data).

15. Day to day#

Calendar#

Month view with all appointments, today highlighted, cancelled ones struck through. At the bottom you add an appointment manually — it blocks the time for the bot and is transferred to the connected calendars as well.

Appointments#

Filter by period and status, search, multiple selection, bulk cancellation (optionally with a customer email) and CSV export for Excel. The "Calendar" column shows whether the transfer worked.

Waiting list#

Who is waiting, who has been notified, who has booked. If an appointment is cancelled, the emails go out automatically.

16. Reading the analytics#

Choose the period at the top (7, 30, 90 or 365 days).

• Conversations / messages / bookings and the booking rate — how many conversations lead to an appointment.
• Course per day as bars.
• Providers, consumption and cost: tokens in and out per provider. For costs to appear, enter the prices per million tokens under AI providers — without an entry the column stays empty instead of guessing.
• Most frequent keywords: what appears often here belongs in the knowledge base or on the website.
• Channels and languages show where the enquiries come from.

17. Logs#

Top: which provider answered how often and whether it is currently suspended. Middle: events — here you see every failover, email and calendar error. Bottom: the conversation histories, viewable one by one.

18. Managing clients#

(only with reseller mode switched on)

List of all clients with domains, appointments, conversations and token usage of the last 30 days — your basis for invoicing.

Per client: company name, knowledge base, colour, title, greeting, their email address and phone number, their privacy policy link. Empty fields fall back to your base settings. Below that, the embed code to copy and the access key (regenerable at any time — the old code stops working).

Your AI keys and calendar connections stay centrally with you. Appointments, conversations and enquiries are kept separate per client.

19. What your customers see#

The bot names only genuinely free times and offers them as buttons.

After the booking a confirmation card appears with "Add to calendar" and "Manage appointment". At the same time the confirmation email goes to the customer and the notification to you.

20. Safeguards#

These run without you doing anything:

• At most 20 messages per visitor in 10 minutes (configurable) and 5 bookings per visitor per hour.
• Length limit per message, all input validated on the server, output as text instead of HTML.
• Hidden honeypot field against automated requests.
• IP addresses are never stored in clear text, only as a short-lived checksum for the rate limit.
• Appointments are checked for overlaps before and after saving — with two simultaneous bookings exactly one survives.
• All backend actions protected by nonce and capability checks.
• In reseller mode: domain binding per client and separated data.