Skip to content
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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mavrin-xv--telegram-sales-bot/badge.svg)](/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
  1. {
  2. "name": "telegram-sales-bot",
  3. "plugins": [
  4. {
  5. "name": "telegram-sales-bot",
  6. "source": "./",
  7. "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.",
  8. "version": "0.1.0"
  9. }
  10. ],
  11. "owner": {
  12. "name": "Artem Mavrin",
  13. "url": "https://github.com/mavrin-xv"
  14. }
  15. }
README.md · README · 151 lines
  1. ![telegram-sales-bot](assets/banner.png)
  2. # telegram-sales-bot
  3. **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.**
  4. The owner answers the same questions all day, and the one complaint that matters waits under them.
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. ![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%7C%20Codex%20%7C%20any%20SKILL.md%20agent-black)
  7. ![Python](https://img.shields.io/badge/bot-stdlib%20Python%203.8%2B-green)
  8. ![Offline](https://img.shields.io/badge/test-offline%20replay%2C%20no%20keys-orange)
  9. ```bash
  10. git clone https://github.com/mavrin-xv/telegram-sales-bot && cd telegram-sales-bot
  11. ./install.sh # or: ./install.sh --project
  12. ```
  13. <!-- install-notes:start -->
  14. 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`.
  15. <!-- install-notes:end -->
  16. Then in Claude Code: `/shop-bot my-catalog.json`
  17. ---
  18. ## What it solves
  19. | Pain | What the pack does |
  20. |---|---|
  21. | Same questions all day: price, stock, delivery | The bot answers from a JSON catalog and FAQ, and never invents an item or a price |
  22. | Orders lost in chat, wrong totals | Items are parsed and priced in code, the client confirms a card, the operator gets the order |
  23. | 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 |
  24. | You sell from your personal account, not a bot | Business mode drafts each reply with Send / Discard; nothing goes out without your press |
  25. | 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 |
  26. | No idea how the week went | A digest: who wrote, who ordered, who waits, what people ask for |
  27. ## What's inside
  28. | Skill | What you get | Say |
  29. |---|---|---|
  30. | `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" |
  31. | `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" |
  32. | `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" |
  33. | `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" |
  34. | `sales-digest` | Weekly digest from the message and order logs | "how did the bot do this week", "who wrote but did not buy" |
  35. Slash commands: `/shop-bot`, `/business-inbox`, `/sales-script`, `/follow-ups`, `/sales-digest`.
  36. ## Quick start
  37. ```bash
  38. S=skills/shop-assistant/scripts
  39. cp templates/catalog.json my-catalog.json # edit: shop, items, FAQ
  40. python3 $S/catalog.py validate my-catalog.json
  41. python3 $S/bot.py --catalog examples/fernhollow-tea/catalog.json \
  42. --replay examples/fernhollow-tea/updates-dm.json --llm stub --state "" # offline, no token
  43. export TELEGRAM_BOT_TOKEN=... OPERATOR_CHAT_ID=... ANTHROPIC_API_KEY=...
  44. python3 $S/bot.py --catalog my-catalog.json # live, long polling
  45. ```
  46. Sample output, from the offline replay of the invented shop in [examples/fernhollow-tea](examples/fernhollow-tea/README.md):
  47. ```
  48. client I want 2 chamomile and 1 rooibos
  49. client Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
  50. bot 2 x Chamomile Honey, 100 g = 15 USD
  51. 1 x Rooibos Vanilla, 100 g = 8.50 USD
  52. Delivery: 4 USD
  53. Total: 27.50 USD
  54. To: Dana Whitlock, +1 555 0142, 12 Elm Row, flat 3
  55. Confirm the order? [Confirm] [Change]
  56. operator NEW ORDER 1 from 5001 (Dana) ... Reply to this message to write to the client.
  57. client My gift set arrived damaged, the tin is crushed
  58. operator HANDOFF 5002 (Ivo) Reason: keyword: damaged
  59. owner (Business) Lena wrote: is the jasmine tea in stock?
  60. Draft: Jasmine Pearls, 100 g: 14 USD
  61. Want me to put an order together?
  62. [Send] [Discard]
  63. ```
  64. ## How it works
  65. ```
  66. client DM ----------------+ owner's Business chat ---+
  67. v v
  68. bot.py (long poll, state in a JSON file)
  69. |
  70. handoff words? --yes--> operator group, chat paused until /resume
  71. |
  72. v
  73. model (cached prompt: rules + catalog.py compact) or stub search
  74. |
  75. ACTION order? --> order.py prices it --> confirm card --> orders.jsonl
  76. | + operator
  77. DM: send reply | Business: draft to owner, [Send] [Discard],
  78. | refused after 24 h without a client message
  79. v
  80. messages.csv --> unanswered.py / label_replies.py / digest.py
  81. contacts.csv + sequence.json --> schedule_followups.py --> today's send list
  82. ```
  83. The model writes words. Code does the prices, the totals, the stop rules and the 24 hour check.
  84. ## Configure
  85. | Variable | Used by | What it does |
  86. |---|---|---|
  87. | `TELEGRAM_BOT_TOKEN` | `bot.py`, `inspect_updates.py --fetch` | Token from BotFather |
  88. | `OPERATOR_CHAT_ID` | `bot.py` | Chat or group that gets orders, handoffs and alerts |
  89. | `LLM_PROVIDER` | `bot.py` | `anthropic` (default), `openai` or `stub` |
  90. | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | `bot.py` | Key for the chosen provider |
  91. | `OPENAI_BASE_URL` | `bot.py` | Any OpenAI-compatible endpoint, for local models too |
  92. | `LLM_MODEL` | `bot.py` | Model name override |
  93. | `SHOP_PROMPT` | `bot.py` | Path to your edited `templates/system-prompt.md` |
  94. | `BOT_STATE` / `BOT_ORDERS` | `bot.py` | State file and order log paths |
  95. 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).
  96. ## Honest limits
  97. - Handoff words, reply labels and complaint words are English regex. Add your language before going live.
  98. - Catalog search is word overlap with aliases. A shop with vague item names needs good aliases, or the model has to do the matching.
  99. - 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.
  100. - One process, one JSON state file. Fine for a small shop, not for several bots on one state.
  101. - Payments are not handled. The operator sends the payment link.
  102. - Tested offline only: the replay runs every Bot API call against recorded updates. The live Telegram API and the model calls were not run.
  103. ## Credits
  104. - Business connection, rights and the 24 hour window follow https://core.telegram.org/bots/api (Telegram Bot API docs).
  105. - Business setup order based on https://telegrambots.github.io/book/4/business.html (MIT).
  106. - 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.
  107. - Business auto-reply bot studied at https://github.com/AbhiTheModder/tgbot-business-ai (MIT). We chose drafts over auto-replies.
  108. - 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).
  109. - Discovery questions and objection handling adapted from https://github.com/msitarzewski/agency-agents (MIT).
  110. - Sequence length, stop rule and hook variants adapted from https://github.com/boringmarketer/boring-marketing-skills (MIT).
  111. ## Contributing
  112. See [CONTRIBUTING.md](CONTRIBUTING.md). Run the commands in [AGENTS.md](AGENTS.md) before a pull request.
  113. <!-- author:start -->
  114. ## Author
  115. 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.
  116. <!-- author:end -->
  117. ## License
  118. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.