AI Chatbot

Let visitors get instant answers without creating a ticket. The chatbot is a floating chat widget you add to any website with a single script tag. It answers questions using only your knowledge base — the same docs that power your hosted documentation site — and offers a one-click escalation to a real ticket when it can’t help.

How it works

1. A visitor clicks the chat bubble and asks a question.
2. Scitor searches your knowledge base for relevant articles.
3. An AI model writes a short answer grounded in those articles, with links to the sources.
4. If nothing relevant is found — or the visitor wants a human — the chat offers a contact form. Submitting it creates a GitHub Issue or Discussion through the same pipeline as web forms, with the chat transcript attached so your team has full context.

The bot answers in the language the visitor writes in.

Setup

1. Enable the chatbot in scitor.yaml

chatbot:
  enabled: true

2. Add the widget to your website

Use the form ID from your docs contact form or any form created with /create-form:

<script
  src="https://api.scitor.io/widget/chat.js"
  data-form="YOUR_FORM_ID"
  async
></script>

That’s it. The widget renders a floating chat bubble in the corner of the page.

Customization

All customization lives in the chatbot section of scitor.yaml:

chatbot:
  enabled: true
  locale: nl            # UI language: en (default), nl, de, fr
  color: "#22C55E"      # widget color (defaults to your docs color)
  position: left        # right (default) or left
  title: "Helpdesk"     # header title (default: "Support")
  escalation: true      # allow raising a ticket from the chat (default: true)
  suggestedQuestions:   # up to 4 tappable chips shown when chat is empty
    - How do I reset my password?
    - What's included in the Pro plan?
  instructions: |       # custom tone / style guidance (max 2 000 chars)
    Reply concisely. Use a friendly, informal tone.

Overriding individual texts

Every visible string can be overridden, on top of the chosen locale:

chatbot:
  enabled: true
  locale: en
  strings:
    greeting: "Hi! Ask me anything about Acme."
    escalateButton: "Talk to a human"

Available keys: greeting, inputPlaceholder, send, escalateButton, escalateTitle, escalateNote, nameLabel, emailLabel, subjectLabel, messageLabel, submit, submitted, submittedDetail, noAnswer, quotaExceeded, turnLimit, error, close, restart, openLabel, sourcesLabel, transcriptHeader, feedbackUp, feedbackDown, feedbackThanks.

Suggested questions

Define up to four question chips that appear when the chat panel is first opened (before the visitor has typed anything). Clicking a chip fills the input and sends the question immediately.

chatbot:
  enabled: true
  suggestedQuestions:
    - How do I reset my password?
    - What's included in the Pro plan?
    - How do I cancel my subscription?
    - Where can I find my invoice?

Chips are shown only once per conversation — they disappear as soon as the visitor sends their first message. You can define 1–4 questions; each is capped at 200 characters. Omit the key (or leave the list empty) to show no chips.

Per-answer feedback

Per-answer feedback is always enabled — no configuration needed. Each bot answer shows a 👍 / 👎 pair so visitors can signal whether the answer was helpful. Feedback is one-shot per answer — a visitor cannot change their vote once cast.

• Thumbs up — increments the positive feedback counter for the day.
• Thumbs down — increments the negative feedback counter and records the question text as a knowledge gap (PII-stripped) so you can see which topics need better documentation.

Feedback counters are visible in Insights → Chatbot. The feedbackUp, feedbackDown, and feedbackThanks strings can be overridden via the strings key if you want custom labels.

Custom tone and instructions

Add a free-form instructions block to steer the bot’s tone and style:

chatbot:
  enabled: true
  instructions: |
    Reply concisely — no long introductions.
    Use an informal, friendly tone.
    When visitors ask about pricing, always mention the 14-day free trial.

The instructions are injected into the answer-generation prompt as optional guidance. Up to 2 000 characters.

Chatbot analytics

Conversation metrics are aggregated per day and surfaced in Insights → Chatbot in your dashboard. No full transcripts are stored — only the counters below.

Headline rates shown at the top of the dashboard:

• Deflection rate — share of conversations that received an answer and did not escalate.
• Escalation rate — share of conversations that ended in a support ticket.
• Feedback ratio — share of 👍 votes out of all votes cast.

You can navigate between months using the arrows at the top of the page. Daily bar charts show volume over the selected month.

Knowledge gap reports

Questions the bot couldn’t answer — and answers visitors rated 👎 — are recorded as knowledge gaps and surfaced in Insights → Knowledge Gaps. Near-duplicate questions are clustered by similarity, so you see “20 visitors asked about X” rather than 20 separate rows.

From the Knowledge Gaps page you can:

• Filter gaps by type and date range:
  • No answer (no_answer) — the bot couldn’t find relevant content in your knowledge base.
  • Thumbs down (thumbs_down) — the visitor rated a bot answer as unhelpful.
  • Escalated after answer (escalated_after_answer) — the visitor chose to open a support ticket even though the bot had answered.
• Click Create docs issue on any cluster to open a pre-filled GitHub issue in your repository so your team can write or improve the relevant documentation.

Privacy: Only the text of the visitor’s question is stored, never their name, email, or any identifying information. The question text is PII-stripped before storage (emails, phone numbers, and other common patterns are removed). Gaps are retained for 90 days and then automatically deleted.

Knowledge sources

The chatbot answers from your knowledge base — the Markdown files in your repository’s docs folder. PDF files in the docs folder are indexed too (up to 4 MB each), so you can drop in existing manuals, datasheets, or guides without converting them:

docs/
├── getting-started/
│   └── index.md
└── manuals/
    └── router-setup.pdf

After a docs build, new and changed content becomes available to the chatbot within a few hours (the search index refreshes periodically).

Escalation

When the bot can’t answer, it says so and offers a Contact support button (you can also keep it always visible). The escalation form asks for name, email, subject, and message — the subject is pre-filled with the visitor’s first question. The conversation so far is appended to the ticket, and a note above the form tells the visitor that it will be shared.

Escalations go through the exact same pipeline as web form submissions: a GitHub Issue or Discussion is created, AI triage and labels are applied, and you reply with /send as usual.

Staying on topic and abuse prevention

The chatbot is locked to your documentation. Several safeguards are built in and need no configuration:

• Grounded answers only — if your knowledge base doesn’t contain the answer, the bot says it doesn’t know and offers escalation. It never answers from general knowledge, so off-topic requests (recipes, homework, anything unrelated) get a polite refusal.
• Relevance gate — before writing an answer, the bot first searches your knowledge base. If nothing relevant is found, it skips straight to the “no answer” response and offers escalation — it doesn’t try to improvise. This keeps answers grounded and keeps off-topic traffic from generating filler.
• Prompt-injection resistance — instructions hidden in visitor messages (“ignore your rules”, “pretend you are…”) are treated as data, not commands.
• Rate limiting — per-visitor message limits, plus a daily limit per site. When a limit is reached, the widget automatically falls back to the contact form, so visitors can always reach you.
• Input limits — messages are capped in length and the conversation context is bounded.

See Limits & Quotas for the exact chatbot limits and what happens when each is reached.

Short answers and long conversations

Chatbot answers are intentionally short and to the point — the bot is built to point visitors to the right place in your docs, not to write essays. Answer length is capped.

Conversations also have a length cap. After a visitor has exchanged a number of messages with the bot in one conversation, the bot stops answering and offers the contact form instead, so a long back-and-forth that isn’t getting resolved turns into a ticket your team can pick up. The exact cap is listed in Limits & Quotas.

Answer caching

Identical, repeated questions are answered from a short-lived cache instead of being regenerated every time. This is completely transparent to visitors: a cached answer looks exactly like a fresh one and carries the same source links. Caching makes popular questions faster and keeps the assistant affordable to run.

The cache is tied to your published knowledge base. When you rebuild your docs (push a change), the cache is invalidated automatically — visitors immediately get answers based on the new content, never a stale one. See Privacy for what the cache does and doesn’t store.

Privacy

Conversations are not stored on Scitor’s servers. The transcript lives in the visitor’s browser for the duration of the tab session and is only persisted if the visitor chooses to escalate — at which point it becomes part of the ticket, like any other form submission.

The conversation survives a page refresh (it’s kept for the tab session), so visitors can browse your site mid-conversation without losing context. The ↻ button in the widget header clears the transcript and starts a fresh conversation.

About the answer cache: the cache stores answers keyed by question, not conversations. A cache entry is a published answer plus its source links, looked up by the (PII-stripped, normalized) question text — exactly like the knowledge-gap signal. It contains no visitor identifiers, no transcripts, and nothing tying an answer to a person. Cached answers come only from your published knowledge base, never from a previous visitor’s wording.

When the chatbot is unavailable

The widget always degrades gracefully — whenever AI answering is unavailable for any reason, the same chat bubble opens the contact form directly, so visitors can still reach you. This happens when:

• the AI assistant is temporarily disabled, or your knowledge base isn’t published yet;
• a rate or usage limit is reached (per-visitor rate, daily site limit, monthly conversation allotment — see Limits & Quotas);
• the conversation reaches its length cap (the bot offers the form to continue with a human);
• the widget is loaded from a domain you haven’t registered, if you’ve configured an allowed-origins list.

In every case the visitor can still send their question through the contact form — they’re never left at a dead end.