A friendly, step-by-step guide to setting up your Bot Marley AI chatbot and getting the most out of it. No coding required — if you can edit a WordPress page, you can configure Bot Marley.
This guide is written for site owners. Follow it top to bottom the first time, then use it as a reference whenever you want to tweak something.
Applies to Bot Marley 0.12.0 and newer.
Bot Marley is a self-hosted AI chatbot that turns your website into a smart assistant. It reads your own pages and posts and answers visitors’ questions using only what’s actually on your site — so it stays accurate and on-topic.
Because it’s self-hosted, your content and conversations stay in your WordPress site, and you connect your own AI provider. There are no per-conversation fees: you only pay your AI provider for what you use.
What it’s great at: answering “how much does X cost?”, “do you ship to…?”, “what’s your return policy?”, guiding shoppers, and capturing leads — 24/7, in the visitor’s own language. With a Pro licence it also powers an AI-driven site search.
Setting up takes about 10 minutes. Here’s the short checklist so nothing blocks you halfway through.
You’ll get the smoothest experience if you have these ready before you begin.
Good to know: Bot Marley never stores your API keys. You connect your provider once in WordPress (Settings → Connectors) and every compatible plugin shares it safely.
Compatibility (needs Bot Marley 0.9.10 or newer):
If you just want the bot running fast, these are the only three things you must do. Each one has its own detailed section below.
Do them in order — the widget won’t switch on until the first two are done.
That’s it — open your site and the chat launcher appears in the corner.
Bot Marley doesn’t come with its own AI; it uses the provider you choose. This keeps you in control of costs, data location, and which model answers your visitors. You only need one provider.
The process is always the same: create an API key on the provider’s platform, then paste it into WordPress once. Keys are shown only once when you create them — copy the key straight away and store it somewhere safe.
Which one should I pick? If you just want to try it for free, start with Google Gemini (free tier, no card) — but note its free limits are very low, so for a live chatbot plan on enabling billing. For production most people use OpenAI or Anthropic — both need a small prepaid credit but are rock-solid.
Google’s free tier works immediately with rate limits and needs no credit card.
⚠️ The free tier’s limits are very low (a handful of requests per minute, shared quotas that run out fast). It’s fine for trying Bot Marley out, but with real visitors the chatbot will regularly hit the limit and fail to answer. For the chatbot to work correctly we recommend setting up billing and moving to a paid plan — Gemini’s paid usage is inexpensive, and paid traffic also gets priority capacity at peak times.
Official docs: ai.google.dev/gemini-api/docs/api-key
OpenAI’s API needs prepaid credit; without it, requests fail even with a valid key.
Official docs: platform.claude.com/docs
Now hand the key to WordPress — you only do this once.
Back in Bot Marley → Settings, the Status line confirms the AI Client is detected. You can optionally pin a specific provider there, or leave it on Site default and let WordPress choose. The model is always chosen by the provider — there are no stale model lists to maintain.
Tip: Prefer to keep data in a specific region (for example the EU)? Choose a provider that offers it — you control which one Bot Marley talks to.
The knowledge base is everything the bot is allowed to know. Bot Marley reads the content you select and uses only that to answer — so a good knowledge base means good answers.
Spend a couple of minutes here and you’ll dramatically cut the questions that reach your inbox. This is all on the Bot Marley → Knowledge page.
Pick which content feeds the bot. Posts and pages are included by default; add custom post types, and — on WP 7.1+ — uploaded PDFs and documents.
Fill in your company name, email, WhatsApp number, phone, and address here. When set, the contact details override anything found in your content, so the bot always shares the right, up-to-date contacts and never an old number buried in an old post.
The bot is also deliberately restrained about when it brings contacts up: it shares them when the visitor asks how to reach you, when it genuinely can’t answer, or when you’ve set an objective like Lead visitors to the contact page. It does not tack a “contact us” invitation onto every reply — a good answer about a product stays about the product.
Tell the bot where your Contact, Booking, Login, Cart, FAQ, Return Policy, Terms, and Privacy Policy pages live. A handy “pick page” button lets you select them instead of typing URLs.
The Privacy Policy is special: it’s required, and it’s the link shown in the consent notice above the chat.
Paste one rule per line to remove pages from the knowledge base. You can match an exact URL, contains:/word/, or starts:/path/. Matching pages are dropped from the index and never cited.
The widget is the chat bubble your visitors see. Here you switch it on and make it feel like part of your brand. Everything is on the Bot Marley → Widget page.
Take a minute to match your colours and welcome message — a personalised widget gets far more use than a generic one.
Finding the right delay: too short feels pushy, too long and nobody sees it. Around 6–10 seconds is a good default — enough time for the visitor to start reading before the bot says hello.
botmarley- for the chat, bm-search- for search) — safe to target, no Shadow DOM.Pro: a Pro licence adds an option to hide the “powered by Bot Marley” credit from both the chat widget and the search.
The Behaviour page sets your bot’s personality and its do’s and don’ts. It’s how you make the assistant sound like your brand while staying accurate.
Whatever tone you pick, the golden rule never changes: the bot answers only from your content and never makes things up. Find it under Bot Marley → Behaviour.
Choose the voice that fits your brand:
The tone changes how the bot phrases things — never what it’s allowed to say. Grounding always wins, so even the Witty bot won’t invent facts.
Objectives are the heart of the Behaviour page. It’s a simple grid where each goal has three states:
The goals you can steer include leading visitors to the contact page, to WhatsApp, or to the booking page; providing information about services; answering FAQs; customer support and troubleshooting; collecting and qualifying leads; sharing opening hours and location; and helping schedule appointments.
With WooCommerce, the Bot Marley → WooCommerce page adds a second, sales-focused grid: provide detailed product info, share pricing and variants, guide the purchase, upsell, promote offers, explain shipping/returns, share stock, help track orders, compare products, and reduce cart abandonment.
If an activated objective can’t work with your current setup, the grid tells you. The moment you flag a goal green, a ⚠️ appears before it and a small yellow note explains what’s missing — for example Lead visitors via WhatsApp without a WhatsApp number, Collect leads with the lead form switched off, or (on the WooCommerce page) Help track orders with Order tracking disabled. Objectives left grey or blocked never nag you — the one exception is Promote offers set to red while coupons are enabled, which warns you that the block also switches coupon suggestions off. Toggle the objective off (or fix the missing piece) and the warning disappears.
Keep it focused — max 3 green goals per page. A bot told to do ten things at once does none of them well: every extra “always pursue this” waters the others down. Each page (Behaviour and WooCommerce) caps you at 3 active green goals, warning you when you hit the limit. Red “never” rules have no limit — restrictions stack up cleanly.
A good starter combo for a service business: green on Answer FAQs, Lead visitors to the contact page, and Collect leads; red on anything you never want mentioned. For a shop: green on Provide detailed product information, Guide the purchase, and Reduce cart abandonment.
What the bot says when the answer genuinely isn’t on your site. Leave it empty for a polished default (in the widget’s language) that gracefully invites the visitor to get in touch, or write your own.
Regardless of your settings, the bot always follows a few non-negotiable rules you can’t switch off: no legal/medical/financial advice, never reveals or asks for passwords, credentials or payment details (whoever asks, however it’s framed), never collects personal data in the chat itself (it points visitors to the contact page or lead form instead), never mentions or compares with competitors, and never negotiates prices. These show as locked red rows at the top of the grid.
Bot Marley can turn a conversation into a contact. When the bot suggests getting in touch, a short form appears right inside the chat — no extra plugin needed.
Every submission is emailed to you with the conversation, so you have full context to follow up. You configure this on the Widget page.
Bot Marley is multilingual out of the box, and it works on two levels that are worth understanding separately.
1. The AI’s answers. The bot reads the visitor’s message, detects its language, and replies in that same language — even if your site is only written in one. A German visitor asking a question in German gets a German answer built from your (say, Italian) content. This happens automatically for every conversation, with no configuration.
2. The widget’s fixed texts. The buttons, the consent notice, the lead-form labels, the placeholder — these are the interface, not the answers. They come from a built-in dictionary and are set by the Widget language option:
15 languages ship for the interface: English, Italian, Spanish, French, German, Portuguese, Dutch, Polish, Russian, Turkish, Arabic, Chinese, Japanese, Korean, and Greek. Right-to-left languages (Arabic) are laid out correctly.
Customising the wording. The welcome message, fallback message, and lead-form title/thank-you can be tailored per language: next to each of those fields is an Edit translations link that opens a small editor with a box for every language. Fill in only the ones you care about — any language you leave blank falls back to that language’s own clean default, never to another language.
Multilingual sites: WPML users get an extra bonus — your custom widget strings are registered with WPML String Translation, so your translators can manage them in the usual place.
If you run a shop, the Pro WooCommerce integration turns Bot Marley into a sales assistant that actually helps close the sale — the deepest shop integration of any self-hosted WordPress chatbot. Everything below lives under Bot Marley → WooCommerce and needs WooCommerce plus a Pro licence.
Tick “Let the AI see the visitor’s current cart” (on by default) and the bot reads the live cart while it talks. It can answer “what’s in my cart?”, nudge toward free-shipping thresholds (“you’re €12 away from free delivery”), and help the visitor finish an order they’ve already started — using what’s actually in the cart right now.
Whenever the bot mentions a specific product it shows a tidy product card with the image, price, and an Add to Cart button (plus a link to the product page). Everything is pulled live from WooCommerce, so prices and availability are always current, and the visitor can buy without leaving the chat.
Turn on “Let the AI know about active coupons and suggest them” (off by default), then build a short list of coupon rules — while the switch is off, the push level and rules grey out (your rules are kept, just inactive). Each rule points at a real WooCommerce coupon and gives it a condition — when the bot may offer it:
Conditional rules are checked against the live cart in real time, so a coupon only comes up when it genuinely applies — conditional coupons are always presented in the context of the cart that earned them, never as generic promotions. The discount wording is read straight from the real coupon, and in chat the code appears as a small label in your brand colour with a one-tap copy button next to it. Expired, deleted, or fully-redeemed coupons are skipped automatically.
Two settings quietly take precedence, so your configuration can never contradict itself:
A single Push level slider (1–5) sets how forward the bot is about coupons:
| Level | Behaviour |
|---|---|
| 1 | Almost never — only if the visitor explicitly asks about discounts |
| 2 | Rarely — only on clear price hesitation |
| 3 | Balanced — when relevant to the conversation (default) |
| 4 | Often — proactively when the rules match |
| 5 | Always — mention it in every conversation |
When several coupons match, the bot picks the single best one for the visitor, ranked by how specifically it fits the cart (product in cart → category in cart → cart total → always available), instead of dumping a list — unless the visitor explicitly asks for all available discounts.
Rules that quietly shape which products the bot pushes (visitors are never told these rules exist). Each targets one product or a whole category, in four modes:
Hiding also affects search. A hidden product is removed before the bot ever sees it — and because the chatbot and the Pro AI Site Search share one index, it also drops out of site search (no result cards, no autocomplete). Use Hide to make a product invisible everywhere; use Don’t promote to stop pushing it while keeping it searchable.
The one exception: the visitor’s own cart. If a hidden product is already in the cart, the bot treats it completely normally — names it, states its price, and helps with quantities, totals, shipping and checkout. Denying what the visitor can plainly see in their own cart would make no sense.
Tick “Let the AI read the logged-in customer’s recent orders” (off by default) so shoppers can ask “where’s my order?”. It’s an early BETA, deliberately cautious:
Because it’s BETA, test it on your own store (place an order, log in, ask about it) before pointing customers at it.
The WooCommerce page has its own objectives grid (green/red/grey, same 3 active goals limit as Behaviour): reduce cart abandonment, upsell related products, share pricing and variants, promote offers, guide the purchase, and more — shaping the bot’s sales intent on top of everything above.
⚠️ This feature is in a phased rollout and is not switched on yet. For now, the Bot Marley → Search page shows a short preview of what’s coming; there’s nothing to configure. The rest of this section describes how it will work once it lands — come back when it’s live.
The same knowledge base that powers the chatbot can power your site search. Instead of WordPress’s basic keyword search, visitors get instant suggestions and meaning-based results (semantic on WP 7.1+, keyword on 7.0). It’s all on the Bot Marley → Search page and needs a Pro licence.
Nothing changes on your site until you set it up — so you’re always in control of where search appears.
shortcode, and point this field at it. Once set, normal WordPress searches (theme search boxes, ?s= URLs) are redirected here — WooCommerce product searches stay scoped to products.A compact search box can go anywhere, in two styles you set as the default on the Search page:
The quickest way to place one is the menu:
For anywhere else — a page, a sidebar, a footer, a block — you use shortcodes.
Everything is the one shortcode . A single attribute,
display, decides its shape:
| Shape | Shortcode | What the visitor sees |
|---|---|---|
| Full search (default) | | A search bar with inline results on the same page. This is the one that goes on your results page. |
| Compact bar |
| Just an input bar. Submitting sends the visitor to your results page. |
| Icon + popup |
| Just a magnifier icon; clicking it opens the search popup. |
Two more attributes fine-tune any of them:
| Attribute | Values | What it does |
|---|---|---|
type | a post-type slug — product, post, page… | Restricts the search to that one content type. Omit it to search everything. |
width | small · medium · wide · full · or a custom 80% / 900px | Overrides the page-wide Results width for the full search. |
Worked examples:
→ full search (everything)
→ full search, products only
→ full search, wider layout → a search bar (e.g. sidebar) → a magnifier + popup (e.g. header)
How the pieces connect:
Typical setup: create a page “Search results”, put
on it, set it as the Search results page, then drop
in your header (or add the widget to a menu). Visitors search from the icon anywhere and always land on your formatted results page.
Results always follow the active site language (WPML/Polylang), and the results-page link is translated for you (WPML, Polylang, TranslatePress).
Most sites never need to touch these, but a few knobs let you balance answer quality against cost. They’re on the Bot Marley → Settings page.
Start with the defaults — they’re sensible — and adjust only if you have a reason to.
| Setting | What it does | Suggested |
|---|---|---|
| Retrieved chunks (top-k) | How much of your content the bot reads per question. Higher = more thorough, but costs more. | Default 5 |
| Temperature | How creative the wording is. Lower = more factual and on-brand. | Default 0.2 |
| Max messages per session | Caps messages per visitor to prevent abuse. 0 = unlimited. Sessions reset after 24h of inactivity. | Set a limit on busy sites |
| Max message length | Longest single message a visitor can send (50–2000). | Default 280 |
| Site behind proxy / CDN | Enables correct per-visitor rate limiting when you’re behind Cloudflare or similar. Only turn on if you actually are. | Off unless behind a proxy |
Watching costs? Lower top-k, set a max messages per session, and keep temperature low. These three together keep your AI bill predictable.
The Statistics dashboard shows how your chatbot and search are performing, so you can see what’s working and where visitors get stuck. It’s available with a Pro licence under Bot Marley → Statistics, with a date-range picker for the last 7 / 30 / 90 days.
Use it to spot the questions you should answer better on your site — and, if you run a shop, to see what the bot earned.
Statistics live in three small tables in your own database and are cleaned up automatically every day, so they never grow unbounded. Two controls keep them as light as you like:
⚠️ Automatic heads-up: if the data ever gets heavy, Bot Marley shows a gentle notice — on the Statistics page and across your WordPress admin — telling you the current size and offering to clear it or shorten retention right there. Nothing is deleted without your click.
Bot Marley is built to keep you in control of your data. Your knowledge base and chat history stay in your own WordPress database — there’s no third-party chatbot company holding your information.
The only thing sent outside your site is the AI request itself (the visitor’s question plus the relevant snippets of your content), which goes to the AI provider you chose and control.
Before you contact support, check here — the vast majority of setup hiccups are one of these, and each has a quick fix.
Work through the symptom that matches, and you’ll usually be back up and running in under a minute.
“The AI Client is not available.” You’re either below WordPress 7.0 or haven’t connected a provider yet. Add a valid key under Settings → Connectors.
The bot gives empty answers or always uses the fallback. Two usual causes: indexing hasn’t run (open Knowledge and check there’s a content count), or your AI account has no active billing/credit. Fix both and re-test.
The bot sometimes can’t answer (“I’m sorry, but I can’t answer right now.”). That generic line appears when your AI provider momentarily fails — an overloaded model (Gemini’s 503 at peak times), an exhausted free-tier quota (429), or similar. Visitors never see the raw technical error: Bot Marley retries automatically — up to twice, with a short pause — and only then shows that translated generic message. The real error is kept for you in Statistics → Error log (the LOGS link) and in the server’s PHP error log. When the connector keeps hitting its limits, WordPress also shows a warning at the top of every admin page with the 7-day count and links to check your provider plan or switch AI service. If it happens often: add billing/credit to your provider account (free tiers have tight per-minute quotas; paid traffic gets priority), or switch provider in Bot Marley → Settings.
The widget won’t switch on. Set a Privacy Policy URL on the Knowledge page — it’s required before the chat can go live.
I updated a page but the bot doesn’t know. Turn on Auto-sync content changes, or click Reindex All Content after major edits.
The bot gave an old phone number or email. Fill in the Contact Information fields on the Knowledge page — they override anything in your content.
A lead came in but no email arrived. Check the Notification email on the Widget page (empty = your admin email), and that the visitor didn’t untick the transcript-consent box. If emails generally struggle to leave your site, that’s a hosting/deliverability matter (SPF/DKIM), not the plugin.
Search results look cramped or too narrow. On the Search page, raise the Results width (Small → Medium/Wide/Full) — the default is deliberately narrow.
My AI bill is higher than expected. Lower top-k, set a max messages per session, and keep temperature low.
Still stuck after all this? That’s exactly what support is for — reach out from your customer portal and we’ll help.