Operations Guide
Run aichat-go projects entirely from Telegram
Who this guide is for
You manage one or more sales-bot projects from Telegram — create new bots, update prompts, add knowledge-base content, watch chat statistics. You should never need to SSH into the server or run any binary by hand.
Every project lifecycle action lives behind a slash command in a Telegram group. There are two kinds of groups you will work with:
-
The admin lead group — one special group bound to the admin
project. From here you can control any project (create, seed, edit, list, delete).
Admin commands are prefixed with
/project_. -
A project's own lead group — the chat where leads from a specific
project are delivered. From here you can edit prompts, see stats, and view info for
that project only. These commands are short forms (
/prompt1,/stats,/info...).
Prerequisites
Before any of the commands in this guide will work, your operator must have set up the platform once. You need three things to be true:
- The aichat-go bot service is running and reachable from Telegram (the webhook is registered).
- An admin project exists in the database with a Telegram bot of its own.
- That admin bot has been added to a Telegram group, and the bot has confirmed “Lead group connected for project ‘admin’!”. That group is your admin lead group — the one where you will type all the commands below.
If any of these are missing, ask your operator to perform the one-time setup. This guide assumes a working admin lead group from here on.
Onboard a new project
Spinning up a new sales bot is a three-step flow that takes a couple of minutes. The bot does almost everything for you — you just provide a name, a content source, and a Telegram bot token.
Create the bot in BotFather
In Telegram, open @BotFather and run
/newbot. Pick a display name and a unique username ending in
_bot. BotFather replies with a token of the form
123456:AAH... — copy it.
Run /project_init in the admin lead group
Pick a short, lowercase project name (used internally and in URLs). Then choose one of three ways to give the system its starting content:
Option A — Sitemap URL (most common)
If the customer's website has a sitemap.xml, this is the easiest path:
the bot walks every page in the sitemap automatically.
Chunking completed: 156 chunks
Embeddings completed: 156 vectors
Upload completed: 42 pages, 156 chunks indexed
Test the bot: https://t.me/acme_bot
Option B — A list of specific URLs
For small sites or when you want to seed only a few pages, pass the URLs directly, comma-separated.
Option C — Attached sitemap XML file
If the sitemap is not publicly hosted (e.g. an export from the customer), attach it to the message as a file. The bot downloads it and uses it as the crawl source.
debug_info.txt file with
verbose pipeline logs (success or failure). Keep it if anything looks wrong — it
contains the full crawl trace.
--force drops the project's database rows and Qdrant
collections before recreating it. This deletes all stored chat history for that
project. Prefer /project_seed if you only want to refresh the
knowledge base.
Connect the project's lead group via deep link
After seeding finishes, the bot posts a deep link of the form
https://t.me/<bot>?startgroup=connect_<name>. Click it —
Telegram opens the “create / pick group” UI with the bot pre-attached. Create
a fresh group (e.g. “Acme Leads”) and tap Create.
The bot auto-detects the group, binds it as the lead group for that project, and confirms:
Use /help to see available commands.
/start connect_<name> message Telegram sends when it joins
the group through the deep link. If a project has no lead group connected yet, leads are
held back with a warning.
The project is now fully operational. Customers can chat with @acme_bot, and any
finished lead lands in “Acme Leads”.
Daily operations
Once a project is live, almost everything is a single command in the admin lead group. Each card below shows the command, what it does, and when to reach for it. All admin commands take the project name as the first argument so you can manage many projects from one place.
Prompts & pricing
Prompts shape what the bot says at each stage. Pricing controls how the bot answers price questions — either by pulling chunks from a dedicated price URL, or from a fallback text block you provide.
Update the Stage 1 system prompt — how the bot greets, qualifies and identifies which service the customer is asking about.
Update the Stage 2 system prompt — how the bot answers detailed questions about a specific service and collects contact info.
Update the Stage 3 (finish) prompt — the closing message the bot sends right before handing the lead off to a human.
Mark a knowledge-base URL as the “price page”. Whenever the bot has identified the customer's service, the chunks from this URL are injected into the LLM context so the bot can quote actual prices.
Fallback pricing text used when no price_url is set, or when the price page
doesn't cover the requested service. Plain prose — the bot uses it verbatim as
reference.
/prompt1, /price_url...) don't need the project
name and apply to the current chat. See
Project lead group below.
Knowledge base — add & delete URLs
The knowledge base is what the bot searches when answering customer questions. You can add new pages, replace pages that have changed, and remove pages you no longer want indexed — all without re-creating the project.
Append URLs to the existing knowledge base. The bot fetches each one, chunks it, embeds it, and indexes the chunks alongside the existing content.
Same as above, but for each URL the bot first deletes any existing chunks for that exact URL, then re-indexes. Use this when a page has been edited and you want a clean re-pull.
Remove all chunks for the given URLs from the knowledge base. Useful for deprecated services or pages the customer asked you to take down.
Re-seed an existing project
When the customer's whole site has changed and you want to start the knowledge base from
scratch — without dropping the project, its chat history, or its prompts —
use /project_seed. It runs the same crawl pipeline as /project_init
but on a project that already exists.
Re-seed from a fresh sitemap URL.
Re-seed from a fixed list of URLs.
Re-seed from an attached sitemap XML file (drop it into the same message).
/project_init --force, which drops the project and re-creates it. (That also
wipes chat history.)
Inspect & stats
Three read-only commands to see what's going on, both per-project and across the platform.
List every project in the database with its creation date. Admin and soft-deleted projects are flagged.
admin — 2026-01-09 [admin]
legacycorp — 2025-11-22 [deleted]
widgets — 2026-03-01
Show the project's UUID, language, lead group binding, and the current price URL / price prompt. Use this to confirm a project exists and is wired up correctly.
Aggregate chat statistics for a project over a time window: total chats, finished chats, unfinished (older than 24h), and average message counts.
Period syntax uses PostgreSQL interval phrases: 1 month
(default), 1 week, 3 days, 6 months. The space
matters — 1month will not work.
Total chats: 87
Finished: 23
Unfinished (>24h): 41
Unfinished total: 64
Avg messages (all): 6.3
Avg messages (finished): 11.8
Avg messages (unfinished): 4.4
Delete & restore a project
Soft-delete and restore are reversible. They flip a flag on the project — data, chat history and knowledge base remain in the database. To make the change visible to customers, your operator restarts the bot service.
Mark a project as deleted. After the next bot restart, the bot stops handling messages for that project's Telegram bot. The admin project itself cannot be deleted.
Clear the deleted flag. After restart (or after an operator re-registers the project), the bot starts answering for it again.
Other settings — /project_set
A single generic command updates any project setting that doesn't have its own dedicated command. Use it for the welcome message, language, and bot-token rotation.
Sets one project setting. Supported keys:
| Key | What it does | Restart needed? |
|---|---|---|
prompt1 |
Stage 1 system prompt (alias for /project_prompt1) |
No |
prompt2 |
Stage 2 system prompt | No |
prompt3 |
Stage 3 (finish) prompt | No |
price_url |
URL whose KB chunks are injected as pricing context | No |
price_prompt |
Fallback pricing text when there's no price URL | No |
start-reply |
The welcome message returned to users when they send /start |
No |
tg_api_key |
Rotate the Telegram bot token for the project | Yes |
language |
Project language — ru or en |
Yes |
tg_api_key and language
take effect only after the bot service restarts — the live bot caches these values at
startup. Ask your operator to restart, or wait for the next deploy.
Project lead group commands
Inside any project's own lead group (not the admin one), a shorter set of commands is available. They always apply to the project that owns the chat — you don't need to type the project name.
| Command | What it does |
|---|---|
/help |
List all commands available in this group (and admin commands too, if it's the admin group) |
/prompt |
Show the current Stage 1, Stage 2 and Stage 3 prompts |
/prompt1 [text] |
Show or update Stage 1 system prompt for this project |
/prompt2 [text] |
Show or update Stage 2 system prompt |
/prompt3 [text] |
Show or update Stage 3 (finish) prompt |
/price_prompt [text] |
Show or set fallback pricing text |
/price_url [url] |
Show or set the price URL |
/stats [period] |
Chat statistics for this project (default 1 month) |
/info |
Show this project's UUID, language, lead group, pricing config |
/settings |
Open the inline settings menu (buttons for the same commands) |
/prompt1 on its own prints the existing Stage 1 prompt — handy for
inspecting before editing.
/project_* forms manage everything else.
What end users see
For context — the customers chatting with the bot have only two commands. You don't run these; they exist so you can recognise them in transcripts.
Resets the conversation: clears the current chat history and conversation state, then
replies with the project's start-reply welcome message. Use the
/project_set <name> start-reply ... command to customise it.
Toggles per-chat debug mode for that user. When enabled, every bot reply is appended with a short trace (current stage, search hits, scoring) so you can see why the bot answered the way it did. The setting is persisted on the user's chat state.
Troubleshooting
Common issues and what they mean. If something here doesn't match what you're seeing, escalate
to your operator with the debug_info.txt file from the most recent
/project_init or /project_seed run.
“Project ‘X’ already exists. Use --force to reinit.”
Either the name is genuinely taken, or a previous /project_init attempt
partially succeeded. Three options:
- Pick a different name.
-
Use
/project_init --force <name> ...to wipe the existing project (database rows + Qdrant collections + chat history) and recreate. This is destructive. -
If you only want to refresh the knowledge base, run
/project_seed <name> ...instead — it keeps prompts, lead group binding, and chat history.
The bot was created but doesn't reply to my test messages
The two most common causes:
-
Lead group not connected. Run
/project_info <name>and look for “Lead group: not connected”. If you see that, click the deep link from the original/project_initreply and add the bot to a fresh group. Without a lead group, the bot still talks to customers but lead delivery is skipped. - Webhook not registered with Telegram. If multiple bot tokens point at the same backend, only the latest one to register wins. Ask your operator to confirm the webhook for your bot.
“Lead group is not connected yet” in a chat reply
The bot's reply contains a deep link — click it. Telegram opens the “create group with this bot” UI. Make a new group and the bot will detect it automatically. You don't need to copy any chat ID.
/project_stats shows zero chats even though the bot is busy
Check the period argument. It must be a PostgreSQL interval string with a
space: 1 month, 2 weeks, 3 days, 6
hours. Without the space (1month), the database treats it as
no-window-matches and you get zeros.
Default with no period is 1 month.
I just ran /project_delete but the bot still answers customers
Soft-delete only flips a flag in the database. Live project bundles are loaded into the
bot's memory at startup, so the change won't take effect until the bot service is
restarted. Ask your operator. /project_restore + restart will undo it.
I changed the language with /project_set ... language en but replies are still in Russian
language and tg_api_key are restart-required keys. The live
agent caches the language at startup; the database value is updated immediately, but the
live bundle keeps the old one until the next restart. The success reply explicitly says
so — ask your operator to restart the service.
A project shows up in /projects but commands say “not found”
Project names are case-sensitive. Copy the exact spelling from the
/projects output.
A new project doesn't appear in /projects right after creation via the operator
Projects created from outside Telegram (advanced CLI) need an explicit
registration step before the running bot picks them up. /project_init
from Telegram does the registration automatically; the CLI does not. Ask your operator
to register the project.
Glossary
The terms you'll see across this guide and in the bot's replies.
- Project
- One sales bot — one tenant. Has its own Telegram bot, prompts, knowledge base, and
lead group. Identified by a unique short name like
acme.
- Admin project
- The single special project whose lead group lets you run
/project_*commands against any other project. There is exactly one admin project.
- Lead group
- The Telegram group bound to a project, where finished leads are delivered. Also where you run that project's commands. Connected once via deep link.
- Knowledge base (KB)
- The indexed pages and chunks the bot searches when answering customer questions. Built
during
/project_initor/project_seed; modified with/project_add_urlsand/project_delete_urls.
- Stage 1 / 2 / 3
- The three phases of a sales conversation. Stage 1 = greet and identify the service; Stage 2 = answer detailed questions and collect contact; Stage 3 = wrap up and forward the lead to humans.
- Finished
- A chat is “finished” when Stage 3 has produced a lead and the bot has stopped replying. Finished chats with successful CRM delivery are marked “lead-sent”.
- Soft-delete
- A reversible flag on a project. The database row stays; the bot stops handling the
project after restart. Undo with
/project_restore.
- Price URL / price prompt
- Two ways to give the bot pricing context.
price_urlpoints at a KB page whose chunks are injected on demand;price_promptis a fallback prose block used when there's no URL or no relevant chunks.
- start-reply
- The welcome message the bot returns when a user sends
/start. Set with/project_set <name> start-reply <text>.
aichat-go · Operations Guide · press t to toggle theme