Everything needed to run Kivunly, including the contract for pointing it at your own backend instead of ours.
Nothing is loaded on your pages until the widget is enabled and an endpoint is set. Before that, the plugin adds no CSS, no JavaScript and no network requests.
| Setting | What it does |
|---|---|
| Enable widget | Master switch. Off means nothing loads at all. |
| Chat endpoint | The HTTPS URL that receives visitor messages and returns replies. |
| Site key | Identifies your site to the backend. With the hosted service a key only works on the domain it was issued for. |
| Bot name | Shown in the chat header. Defaults to your site title. |
| Tagline | The small line under the bot name. |
| Greeting message | The first message a visitor sees. Ask a question here rather than saying hello. |
| Teaser bubble | The small prompt near the closed chat button. Leave empty to disable. |
| Suggested questions | One per line. Shown as tappable buttons when the chat opens. |
| Position | Bottom-right or bottom-left. Left usually reads better on right-to-left sites. |
| Accent colour / header colour | Hex values used for the button, the visitor's messages and the header. |
| Logo URL | Optional image shown in the chat header. |
Kivunly's plugin is a front end. It sends one POST request per visitor message and renders what comes back, which means you can point it at any endpoint that speaks this format.
The widget POSTs JSON to your endpoint:
{
"message": "where do I start with sustainable shopping?",
"history": [
{ "role": "user", "content": "hi" },
{ "role": "assistant", "content": "Hi! What are you looking for?" }
],
"key": "your-site-key",
"page": "https://example.com/blog/current-page/"
}message — what the visitor typed, capped at 1000 characters.history — up to the last 8 messages of the current browser session, for context.key — the site key from the settings page.page — the URL the visitor is on, so the backend knows which site to answer for.{
"reply": "A good place to start is [Ethical Superstore Review](https://example.com/ethical-superstore-review/).",
"suggestions": ["Show me eco-friendly shops", "Best sustainable fashion?"]
}reply — required. Markdown links and **bold** are rendered; everything else is shown as plain text, and HTML is escaped.suggestions — optional. Rendered as tappable follow-up buttons under the answer.Any HTTPS endpoint works: a serverless function, a small server, or an automation tool such as n8n or Make. A workable backend needs four steps — validate the key, fetch the relevant pages from the site (WordPress exposes /wp-json/wp/v2/posts publicly), ask a model to answer using only those pages, and return the JSON above. Ground it properly: see why AI chat widgets invent links.
Your endpoint must allow cross-origin requests from your site's domain, since the widget calls it from the visitor's browser.
Only what is needed to produce a reply, and only to the endpoint you configured:
The plugin sets no cookies, loads no third-party scripts and sends no analytics. Conversation history lives in the browser tab's sessionStorage and disappears when the tab session ends. If you use the hosted service, its terms and privacy policy apply.
| Limit | Current value |
|---|---|
| Messages per visitor | 8 per minute |
| Messages per site | 300 per day |
| Conversation memory | Last 8 messages |
| Content refresh | Automatic, on a schedule |
| Key scope | One key per site; a key used on another domain is refused |
These are beta values intended to keep costs predictable, and they will change as the service grows. Running your own backend means your own limits.
| Symptom | Check |
|---|---|
| No chat bubble | Widget enabled? Endpoint set? Page cache cleared? |
| "Sorry, something went wrong" | The endpoint is unreachable or returned invalid JSON. Open the endpoint URL directly to confirm it is alive. |
| Answers ignore your content | The backend is not grounded in your site's pages. |
| Chat refuses with a key message | The key is wrong, or it is being used on a domain it was not issued for. |
| New posts are missing | Wait for the next content refresh; confirm the posts are public and appear in your site's REST API. |