Back to search
telegram-sales-bot
MarketplaceWorks with Claude CodeGitHub
A Telegram sales assistant that answers from your catalog and prices orders in code.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/mavrin-xv--telegram-sales-bot)HTML
<a href="/listings/mavrin-xv--telegram-sales-bot"><img src="/api/listings/mavrin-xv--telegram-sales-bot/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
S=skills/shop-assistant/scripts cp templates/catalog.json my-catalog.json # edit: shop, items, FAQ python3 $S/catalog.py validate my-catalog.json python3 $S/bot.py --catalog examples/fernhollow-tea/catalog.json \ --replay examples/fernhollow-tea/updates-dm.json --llm stub --state "" # offline, no token export TELEGRAM_BOT_TOKEN=... OPERATOR_CHAT_ID=... ANTHROPIC_API_KEY=... python3 $S/bot.py --catalog my-catalog.json # live, long polling
Sample output, from the offline replay of the invented shop in [examples/fernhollow-tea](examples/fernhollow-tea/README.md):
client I want 2 chamomile and 1 rooibos
client Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
bot 2 x Chamomile Honey, 100 g = 15 USD
1 x Rooibos Vanilla, 100 g = 8.50 USD
Delivery: 4 USD
Total: 27.50 USD
To: Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
Confirm the order? [Confirm] [Change]
operator NEW ORDER 1 from 5001 (Dana) ... Reply to this message to write to the client.
client My gift set arrived damaged, the tin is crushed
operator HANDOFF 5002 (Ivo) Reason: keyword: damaged
owner (Business) Lena wrote: is the jasmine tea in stock?
Draft: Jasmine Pearls, 100 g: 14 USD
Want me to put an order together?
[Send] [Discard]What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 15 lines
- {
- "name": "telegram-sales-bot",
- "plugins": [
- {
- "name": "telegram-sales-bot",
- "source": "./",
- "description": "A Telegram sales assistant for a small shop: answers DMs from a JSON catalog, prices orders in code with a confirm card, hands chats to a human operator, drafts replies in the owner's Telegram Business chats for approval, plus a chat sales script, follow-up sequences with stop rules and a weekly digest. Stdlib Python, offline replay mode.",
- "version": "0.1.0"
- }
- ],
- "owner": {
- "name": "Artem Mavrin",
- "url": "https://github.com/mavrin-xv"
- }
- }
README.md · README · 151 lines
- 
- # telegram-sales-bot
- **A Telegram sales assistant for a small shop: it answers DMs from your catalog, takes orders with totals priced in code, hands hard chats to a person, and drafts replies in your own Telegram Business chats for you to approve. It comes with a chat sales script, follow-up sequences and a weekly digest.**
- The owner answers the same questions all day, and the one complaint that matters waits under them.
- [](LICENSE)
- 
- 
- 
- ```bash
- git clone https://github.com/mavrin-xv/telegram-sales-bot && cd telegram-sales-bot
- ./install.sh # or: ./install.sh --project
- ```
- <!-- install-notes:start -->
- Other ways in: as a Claude Code plugin, run `/plugin marketplace add mavrin-xv/telegram-sales-bot` and then `/plugin install telegram-sales-bot@telegram-sales-bot`. For Codex or another agent that reads `SKILL.md`, copy the folders under `skills/` into its skills directory. On Windows, run `install.sh` from Git Bash or WSL and type `py -3` where these docs say `python3`.
- <!-- install-notes:end -->
- Then in Claude Code: `/shop-bot my-catalog.json`
- ---
- ## What it solves
- | Pain | What the pack does |
- |---|---|
- | Same questions all day: price, stock, delivery | The bot answers from a JSON catalog and FAQ, and never invents an item or a price |
- | Orders lost in chat, wrong totals | Items are parsed and priced in code, the client confirms a card, the operator gets the order |
- | A refund or an angry client gets a bot answer | Handoff words and the model's own flag pass the chat to a person; `/resume` gives it back |
- | You sell from your personal account, not a bot | Business mode drafts each reply with Send / Discard; nothing goes out without your press |
- | Nobody knows what to write next or when to stop | A sales script from real replies, plus follow-up sequences that stop on reply, order or block |
- | No idea how the week went | A digest: who wrote, who ordered, who waits, what people ask for |
- ## What's inside
- | Skill | What you get | Say |
- |---|---|---|
- | `shop-assistant` | The bot: catalog Q&A, order card with confirm, operator handoff, unanswered alerts, offline replay | "set up a Telegram bot for my shop", "the bot should take orders" |
- | `business-inbox` | Telegram Business setup, draft approval flow, 24 hour reply window, a checker for connection problems and late chats | "reply to my clients from my account", "who is waiting for an answer" |
- | `sales-script` | Reply labels (unsubscribe and complaints first), a chat script with AECR objection handling | "write a sales script for my chats", "label these replies" |
- | `follow-up-sequences` | 4 or 7 step sequences, one step a day, stop rules, a daily send list | "follow up with people who did not buy", "what do I send today" |
- | `sales-digest` | Weekly digest from the message and order logs | "how did the bot do this week", "who wrote but did not buy" |
- Slash commands: `/shop-bot`, `/business-inbox`, `/sales-script`, `/follow-ups`, `/sales-digest`.
- ## Quick start
- ```bash
- S=skills/shop-assistant/scripts
- cp templates/catalog.json my-catalog.json # edit: shop, items, FAQ
- python3 $S/catalog.py validate my-catalog.json
- python3 $S/bot.py --catalog examples/fernhollow-tea/catalog.json \
- --replay examples/fernhollow-tea/updates-dm.json --llm stub --state "" # offline, no token
- export TELEGRAM_BOT_TOKEN=... OPERATOR_CHAT_ID=... ANTHROPIC_API_KEY=...
- python3 $S/bot.py --catalog my-catalog.json # live, long polling
- ```
- Sample output, from the offline replay of the invented shop in [examples/fernhollow-tea](examples/fernhollow-tea/README.md):
- ```
- client I want 2 chamomile and 1 rooibos
- client Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
- bot 2 x Chamomile Honey, 100 g = 15 USD
- 1 x Rooibos Vanilla, 100 g = 8.50 USD
- Delivery: 4 USD
- Total: 27.50 USD
- To: Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
- Confirm the order? [Confirm] [Change]
- operator NEW ORDER 1 from 5001 (Dana) ... Reply to this message to write to the client.
- client My gift set arrived damaged, the tin is crushed
- operator HANDOFF 5002 (Ivo) Reason: keyword: damaged
- owner (Business) Lena wrote: is the jasmine tea in stock?
- Draft: Jasmine Pearls, 100 g: 14 USD
- Want me to put an order together?
- [Send] [Discard]
- ```
- ## How it works
- ```
- client DM ----------------+ owner's Business chat ---+
- v v
- bot.py (long poll, state in a JSON file)
- |
- handoff words? --yes--> operator group, chat paused until /resume
- |
- v
- model (cached prompt: rules + catalog.py compact) or stub search
- |
- ACTION order? --> order.py prices it --> confirm card --> orders.jsonl
- | + operator
- DM: send reply | Business: draft to owner, [Send] [Discard],
- | refused after 24 h without a client message
- v
- messages.csv --> unanswered.py / label_replies.py / digest.py
- contacts.csv + sequence.json --> schedule_followups.py --> today's send list
- ```
- The model writes words. Code does the prices, the totals, the stop rules and the 24 hour check.
- ## Configure
- | Variable | Used by | What it does |
- |---|---|---|
- | `TELEGRAM_BOT_TOKEN` | `bot.py`, `inspect_updates.py --fetch` | Token from BotFather |
- | `OPERATOR_CHAT_ID` | `bot.py` | Chat or group that gets orders, handoffs and alerts |
- | `LLM_PROVIDER` | `bot.py` | `anthropic` (default), `openai` or `stub` |
- | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | `bot.py` | Key for the chosen provider |
- | `OPENAI_BASE_URL` | `bot.py` | Any OpenAI-compatible endpoint, for local models too |
- | `LLM_MODEL` | `bot.py` | Model name override |
- | `SHOP_PROMPT` | `bot.py` | Path to your edited `templates/system-prompt.md` |
- | `BOT_STATE` / `BOT_ORDERS` | `bot.py` | State file and order log paths |
- Business mode needs Telegram Premium on the owner's account and Business Mode switched on for the bot in BotFather. Steps: [setup checklist](skills/business-inbox/references/setup-checklist.md).
- ## Honest limits
- - Handoff words, reply labels and complaint words are English regex. Add your language before going live.
- - Catalog search is word overlap with aliases. A shop with vague item names needs good aliases, or the model has to do the matching.
- - The bot cannot write first. Telegram allows a bot to message only users who started it, and Business replies only within 24 hours of the client's last message.
- - One process, one JSON state file. Fine for a small shop, not for several bots on one state.
- - Payments are not handled. The operator sends the payment link.
- - Tested offline only: the replay runs every Bot API call against recorded updates. The live Telegram API and the model calls were not run.
- ## Credits
- - Business connection, rights and the 24 hour window follow https://core.telegram.org/bots/api (Telegram Bot API docs).
- - Business setup order based on https://telegrambots.github.io/book/4/business.html (MIT).
- - Drafts with Send / Discard, owner-only buttons and draft expiry inspired by https://github.com/NousResearch/hermes-labs-plugins/tree/main/telegram-business (MIT). No code copied.
- - Business auto-reply bot studied at https://github.com/AbhiTheModder/tgbot-business-ai (MIT). We chose drafts over auto-replies.
- - Bot and human session state with a summary on resume inspired by https://n8n.io/workflows/3350-telegram-ai-bot-to-human-handoff-for-sales-calls/ (n8n template, free).
- - Discovery questions and objection handling adapted from https://github.com/msitarzewski/agency-agents (MIT).
- - Sequence length, stop rule and hook variants adapted from https://github.com/boringmarketer/boring-marketing-skills (MIT).
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md). Run the commands in [AGENTS.md](AGENTS.md) before a pull request.
- <!-- author:start -->
- ## Author
- Built and maintained by [Artem Mavrin](https://github.com/mavrin-xv). This repo is one of a set of agent skill packs for marketing and operations work. Each one installs on its own; the full list is in [agent-skill-packs](https://github.com/mavrin-xv/agent-skill-packs). If a pack saved you an afternoon, a star helps other people find it.
- <!-- author:end -->
- ## License
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.