API & Developers

Your support bot, on your website too

The same Knowa bot that answers on Telegram can answer on your site — through a drop-in chat widget or a simple REST API. Unknown questions still reach a human: your admin is notified on Telegram, along with any integration errors.

Get an API key Raw docs (api.md)

Building with an AI coding agent? Point it at knowa.solutions/api.md (also listed in /llms.txt) — a single self-contained markdown file with the full spec, error codes, code samples, and an OpenAPI schema.

1. Get your tenant bot

The flow is unchanged: create a bot with @BotFather and we activate it. Your admin manages the knowledge base and every setting from inside Telegram.

2. Request an API key

API keys are issued by the Knowa team per bot, with an optional allow-list of the domains your site runs on. You see the full key exactly once; it can be revoked anytime.

3. Embed or integrate

Paste one script tag for the ready-made chat widget, or call the REST API from your own UI. Same knowledge base, same settings, same answers as your Telegram bot.

Zero code

One script tag. Done.

The widget renders a floating chat bubble, handles sessions, escalation fallbacks, and error states for you.

html

<script
  src="https://api.knowa.solutions/widget.js"
  data-api-key="knw_live_YOUR_KEY"
  data-brand="Acme Support"
  data-color="#2563eb"
  data-greeting="Hi! Ask me anything about Acme."
></script>

Drop it before </body> on any page. Configure it with data attributes:

data-api-key — required, your key.
data-brand — chat header title.
data-color — accent color (hex).
data-position — right (default) or left.
data-greeting — the first message visitors see.

No build step, no dependencies, ~6 KB. Works on any stack — plain HTML, WordPress, Shopify, Webflow, React, anything that renders a script tag.

REST API

POST /api/v1/ask

Authenticate with your key, send a question, get a grounded answer — or a clean escalation when the bot doesn't know.

curl

curl -X POST https://api.knowa.solutions/api/v1/ask \
  -H "Authorization: Bearer knw_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I reset my password?",
    "session_id": "visitor-42-session-1",
    "visitor_name": "Jane",
    "page_url": "https://acme.com/help"
  }'

Field	Type	Description
question	string · required	The user's question (1–4000 chars, any language).
session_id	string · optional	Per-visitor conversation id. Keeps the last 3 Q/A turns for 15 minutes so follow-ups have context.
visitor_name	string · optional	Shown to your admin if the question is escalated.
page_url	string · optional	Page the question was asked from — included in escalations.

Answered

200 OK

{
  "ok": true,
  "request_id": "f3a09c1d2b4e5a67",
  "answer": "You can reset your password from Settings → Security → Reset password.",
  "escalated": false,
  "cached": false
}

Unknown question → escalated to your admin on Telegram

200 OK

{
  "ok": true,
  "request_id": "9d2c4b1a0e8f7c65",
  "answer": null,
  "escalated": true,
  "cached": false,
  "fallback_message": "I don't have that answer yet, but I've forwarded your question to the team — they'll follow up shortly."
}

GET /api/v1/status

Health-check your integration: bot status, knowledge-base size, and usage.

200 OK

{
  "ok": true,
  "bot": { "brand_name": "AcmeCorp", "status": "active", "expires_at": "2027-02-11T00:00:00.000Z" },
  "knowledge_base": { "documents": 12, "indexed_chunks": 431 },
  "usage": { "questions_answered": 1289 }
}

Errors

Every error is { ok: false, error: { code, message } }.

HTTP	Code	Meaning
400	invalid_request	Body failed validation — error.details lists the field problems.
401	missing_api_key / invalid_api_key	No key sent, or the key is unknown / revoked.
403	origin_not_allowed	Browser Origin isn't on the key's allow-list.
403	subscription_inactive	The bot's subscription is paused or expired.
429	rate_limited	Over the per-key limit (60/min). Honour the Retry-After header.
500	internal_error	Server-side failure — your admin is automatically alerted on Telegram.

Code examples

Integrate in any language

javascript

async function askSupport(question, sessionId) {
  const res = await fetch("https://api.knowa.solutions/api/v1/ask", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer knw_live_YOUR_KEY",
    },
    body: JSON.stringify({ question, session_id: sessionId }),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  // answer is null when escalated to a human — show the fallback instead
  return data.answer ?? data.fallback_message;
}

python

import requests

def ask_support(question: str, session_id: str | None = None) -> str:
    r = requests.post(
        "https://api.knowa.solutions/api/v1/ask",
        headers={"Authorization": "Bearer knw_live_YOUR_KEY"},
        json={"question": question, "session_id": session_id},
        timeout=30,
    )
    data = r.json()
    if not data.get("ok"):
        raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
    return data["answer"] or data["fallback_message"]

Built-in guardrails, human in the loop

Answers come only from your knowledge base — the bot never invents anything. When it can't answer, the exact question (with the visitor's name and page) is forwarded to your admin on Telegram. Integration errors alert your admin too, so nothing fails silently.

API keys stored hashed, revocable instantly
Per-key origin allow-list for browser usage
60 requests/minute per key (429 + Retry-After beyond that)
Session context: last 3 turns kept 15 minutes for follow-ups
CORS enabled — call it straight from the browser

Ready to put your bot on your site?

Tell us which domains you're integrating and we'll issue your API key.

Request an API key Read the full docs