HeshBot：小型自託管網站聊天機械人及三種運作方式

The chat bubble on trevorheshka.com is HeshBot, a chatbot I wrote to replace the Typebot widget I had before. I wanted something small that I fully own: no build step, no framework, no third-party chat platform. The code is open source under the MIT license at github.com/YardPhantom/HeshBot.

This post covers how it's put together, the different ways you could power a bot like this, and what a small business could actually use one for.

What's in the repo

HeshBot has three parts.

The widget. heshbot.js and heshbot.css are plain JavaScript and CSS with no dependencies. A tiny launcher bubble loads the full widget only when someone clicks it, so it costs almost nothing on page load. It works from the keyboard (Enter sends, Shift+Enter adds a new line, Esc closes), uses ARIA dialog and log roles, and goes full-screen on phones. Bot replies go through a small markdown renderer that escapes everything first and then adds back a short whitelist of tags. The conversation lives in sessionStorage, so it's gone when the tab closes.

The endpoint. api/chat.php needs PHP 7.4+ and curl, so it runs on ordinary shared hosting. It calls the Google Gemini API over REST and tries a list of free-tier Flash models in order, falling back to the next one if a call fails. Around that call it does the boring work that keeps a public endpoint healthy:

• per-IP rate limiting, stored in files (the example config allows 6 messages a minute and 60 a day)
• caps on the message history it sends (12 messages, 8,000 characters)
• a same-origin check, so other sites can't use my endpoint
• JSON errors, plus a friendly message when the free quota runs out that points people to my email
• a mock reply when no API key is set, which makes local testing easy

The .htaccess file makes chat.php the only reachable file in that folder. The real config, with the API key, sits outside public_html in the home directory with chmod 600. You can also supply the key as an environment variable.

The knowledge. The bot's instructions are in api/system-prompt.md, and what it knows is in api/knowledge.md. I don't write that knowledge file by hand. tools/build_knowledge.py (standard-library Python) reads the public pages of my site, extracts the text and regenerates the file. When I edit the site, I rerun one command and the bot is up to date.

The system prompt matters more than people think. HeshBot is told to answer only from the core facts and the knowledge file, to say it doesn't know rather than guess, never to invent prices, dates, clients or credentials, to stay on topic and to ignore attempts to rewrite its rules. After 25+ years in technical support, that's the behaviour I want: a good help-desk answer is short, correct, and hands you off to a person when it's out of its depth.

Three ways to power a bot like this

HeshBot today uses the first option below. The other two are approaches I'd consider for a client, depending on budget, privacy and how open-ended the questions are. The repo doesn't include them; they're design options, not features.

1. A public API (what HeshBot does)

Send the question, the instructions and your site knowledge to a hosted model and show the reply. This is the fastest way to get good answers. HeshBot uses Gemini's free-tier Flash models, which suits a personal site. The trade-offs are that questions leave your server, and you live within someone else's quotas and pricing. That's why HeshBot has rate limits, model fallback and a polite "try again tomorrow or email me" message built in.

2. A local LLM

Run an open model on your own hardware and point the endpoint at it instead of a public API. Chats never leave your machines and there's no per-message bill, but you need hardware that can run the model, and you're responsible for keeping it up. Because HeshBot's backend is one PHP file that makes a single HTTP call, swapping the model behind it is a contained change, though you'd write that change yourself. On my AI chatbot page I mention that I also build and fine-tune custom LLM models, which is where this option leads.

3. A quick local decision model

Not every chatbot needs a language model. If most visitors ask the same dozen things (hours, location, how to book, what a service includes), a small local classifier or a set of rules can match the question to a known answer and reply instantly, at no cost, with no model to hallucinate. When a question doesn't match, it hands off to a person or to option 1 or 2. It's less conversational, but very predictable.

What it can be used for

A widget plus a short, grounded knowledge file fits a lot of small jobs. Some of the ways a bot like this could be used:

• Small-business FAQ. Hours, service areas, what's included, how to get in touch, answered from the business's own pages instead of a guess.
• Booking and intake. Collect the basics (what you need, when, how to reach you) before someone books, then point them to the booking form or email.
• Local information. A community or municipal-style site could answer "where do I find…" questions and link straight to the right page.
• Support triage. Ask a few questions, handle the simple fixes, and send everything else to a human with the details already gathered. That's Tier 1 support, which is where I started.

Booking, intake and triage would each need work beyond what's in the repo, such as forms or connections to other systems. The pattern stays the same: a small widget, a guarded endpoint, and a knowledge source you control.

Try it

Open the chat on trevorheshka.com to see HeshBot answer from the site's content. To run it yourself, clone the repo, start php -S localhost:8000 from a folder that contains it, and open the demo page. With no API key it returns a mock reply, so you can work on the widget first.

If you're a BC business thinking about a chatbot that actually knows your business, take a look at my AI chatbot page or email trevor@trevorheshka.com.