Configuration

Configuration Reference

All settings are defined in config.yaml (in the config/ directory). Copy from config-sample.yaml before editing.

---

Bot Identity

Setting	Type	Default	Description
bot_token	string	(required)	Telegram Bot API token from @BotFather (e.g., 123456789:AbCdeFghIjKlMnOpQrStUvWxYz)
staffchat_id	string	(required)	Supergroup chat ID where staff receive tickets (negative number, e.g., -1001234567890)
owner_id	string	(required)	Your Telegram user ID — the bot owner who has admin privileges
staffchat_type	enum	'telegram'	Staff communication platform: 'telegram' or 'signal'
staffchat_parse_mode	enum	'MarkdownV2'	Formatting mode for messages sent to staff chat: 'MarkdownV2', 'Markdown', or 'plaintext'
mongodb_uri	string	—	MongoDB connection URI for ticket storage (e.g., mongodb://localhost:27017/support)

---

Spam Protection

Setting	Type	Default	Description
spam_time	integer (ms)	300000 (5 min)	Time window in milliseconds during which the message limit applies. A user sending more than spam_cant_msg messages within this period will be temporarily blocked and notified. Set to 0 to disable spam protection entirely.
spam_cant_msg	integer	5	Number of messages allowed within the spam_time window before rate limiting kicks in

Example: With default settings (spam_time: 300000, spam_cant_msg: 5), a user can send up to 5 messages per 5 minutes. A 6th message triggers a spam warning and blocks further forwarding until the window resets.

---

Ticket Behavior

Setting	Type	Default	Description
allow_private	boolean	false	Enables "Reply in private" button on user messages in staff chat. When pressed, opens a 1-on-1 private tunnel between the staff member and the user (visible only to them). An "End Private Chat" button closes the tunnel.
direct_reply	boolean	false	Requires allow_private: true. Instead of creating a relay tunnel, forwards the staff member directly to the user's Telegram profile for direct messaging.
auto_close_tickets	boolean	false	Automatically closes a ticket after the first staff reply. A closed ticket cannot receive further replies unless reopened with /reopen.
anonymous_tickets	boolean	true	Hides the user's Telegram ID from tickets in the staff chat for privacy.
anonymous_replies	boolean	false	Hides the staff member's name from responses sent back to users — replies appear as coming from the bot directly.

---

Display Options

Setting	Type	Default	Description
show_auto_replied	boolean	false	Forwards auto-replied messages (from autoreply rules or LLM) to the staff chat for visibility. Automatically enabled when use_llm: true.
show_user_ticket	boolean	false	Displays the ticket ID in bot responses sent back to users, so they can reference it in follow-up conversations.
clean_replies	boolean	false	Removes staff attribution signatures from forwarded replies — messages appear without "from [staff name]" attribution.
pass_start	boolean	false	Forwards the /start command message to the staff chat instead of handling it automatically with the welcome message. Useful for custom onboarding flows.
parse_mode	enum	'Markdown'	Formatting mode for bot responses sent to end users: 'Markdown', 'MarkdownV2', or 'HTML'. See Markdown for syntax reference.

---

Logging

Setting	Type	Default	Description
log_level	enum	'NONE'	Controls debug log output written to debug.log: 'NONE' (no logging), 'ERROR' (errors only), or 'INFO' (all events)
dev_mode	boolean	true	Shows a "Dev mode is on" notice with every bot message, alerting users that the bot may experience delays or errors. Disable in production.

---

Language Strings

All user-facing messages are customizable under the language: section. See Commands for which strings correspond to which commands.

language:
  startCommandText: "Welcome in our support chat! Ask your question here."
  faqCommandText: "Get this bot at: github.com"
  helpCommandText: "*Available commands:* /help /faq /id"
  helpCommandStaffText: "..."  # Staff-specific help text with command descriptions
  contactMessage: "Thank you for contacting us. We will answer as soon as possible."
  blockedSpam: "You sent quite a number of questions in the last while. Please calm down and wait until staff reviews them."

Complete String Reference

Key	Used In	Description
startCommandText	/start command response	Welcome message shown when user first interacts with bot
faqCommandText	/faq command response	FAQ content displayed to users
helpCommandText	/help (user)	Help text for end users
helpCommandStaffText	/help (staff in group)	Extended help text with staff commands listed
contactMessage	After first user message	Acknowledgment sent to user after ticket is created
blockedSpam	Spam rate limit triggered	Warning shown when user exceeds spam threshold
ticket	Ticket prefix	Label used in ticket messages (e.g., "Ticket #123")
closed	Closed ticket label	Status text appended to closed tickets
acceptedBy	Staff reply attribution	Text like "was accepted by [staff name]" on forwarded replies
dear	Reply salutation prefix	Greeting prepended to staff replies (e.g., "Hi")
regards	Reply sign-off	Closing appended to staff replies (e.g., "Regards,")
from	Attribution label	Label in "from [staff name]" attribution on forwarded messages
msg_sent	System notification	Confirmation when a message is sent to user
file_sent	System notification	Confirmation when a file is sent to user
usr_with_ticket	Context label	Text identifying the user associated with a ticket
banned	Ban notification	Status text shown when a user is banned
replyPrivate	Button label	Text on "Reply in private" button (requires allow_private)
services	Category intro	Message before category selection list
customer	User reference	Label used for customer/user references
msgForwarding	Forward notification	Info message when messages are forwarded to a group
back	Navigation button	Text on "Go back" navigation buttons in category flow
whatSubCategory	Subcategory prompt	Question shown before subcategory selection
prvChatEnded	Private chat close	Notification that private chat has ended
prvChatOpened	Private chat open (staff)	Notification to staff member when private chat opens
prvChatEnd	End button label	Text on "End Private Chat" button
prvChatOpenedCustomer	Private chat open (user)	Notification to user when private chat is opened by staff
instructionsSent	Instructions forwarded	Confirmation that instructions were sent in private chat
openTickets	/open command header	Title text for the /open tickets list
support	General label	Support department name used in various contexts
prvChatOnly	Error message	Shown when a private-chat-only command is used elsewhere
ticketClosed	Close notification	Message to user when staff closes their ticket
links	Direct links header	Title for direct support links section
textFirst	File warning	Prompt asking users to send text before images
ticketClosedError	Reply error	Shown when trying to reply to a closed ticket
automatedReply	Auto-reply label	Label on automated/canned responses
automatedReplyAuthor	Auto-reply signature	Author attribution on auto-replied messages
doesntHelp	Feedback button	"This does not help" feedback option on auto-replies
automatedReplySent	Staff notification	Confirmation to staff when an automated reply was sent
ticketReopened	Reopen confirmation	Notification when a ticket is reopened with /reopen
regardsGroup	Group sign-off	Department/group name in reply sign-offs

All language strings support MarkdownV2 formatting.

---

Autoreply Rules

Keyword-based canned responses. When a user message contains the question keyword (case-insensitive substring match), the answer is sent automatically. First matching rule wins.

autoreply:
  - question: "install"
    answer: "You can install using our [Getting Started guide](https://github.com/bostrot/telegram-support-bot/wiki/Getting-started)"
  - question: "refund policy"
    answer: "We offer full refunds within 30 days of purchase."

---

LLM / AI Auto-reply

Enable AI-powered responses using any LiteLLM-compatible proxy (supports OpenAI, Anthropic, Mistral, etc.):

Setting	Type	Default	Description
use_llm	boolean	false	Enable LLM-powered auto-replies. Automatically sets show_auto_replied: true.
llm_api_key	string	—	API key for the LLM provider or LiteLLM proxy
llm_base_url	string	—	Base URL of the LLM API endpoint (e.g., https://api.openai.com/v1)
llm_model	string	—	Model identifier (e.g., gpt-4o, mistralai/ministral-3b, claude-3-haiku)
llm_knowledge	string	(empty)	Custom knowledge base text injected as context for AI responses. Use this to provide company-specific information, policies, or FAQs that the LLM should reference when generating replies.

---

Categories

Route tickets from different user topics to specific staff groups. See Categories for full documentation and examples.

categories:
  - name: "Technical Support"
    group_id: "-1009876543210"
  - name: "Sales"
    subgroups:
      - name: "Enterprise"
        group_id: "-1001112223334"
      - name: "Small Business"
        group_id: "-1005556667778"

---

Signal Integration

Use Signal as the staff communication platform instead of Telegram. See Addons → Signal for setup details.

Setting	Type	Default	Description
signal_enabled	boolean	false	Enable Signal integration
signal_number	string	—	Phone number for the Signal account used by staff (e.g., "+1234567890")
signal_host	string	"localhost:8080"	Host and port of the signal-cli REST API container

---

Web Chat Widget

Embed a web chat widget on your website. See Addons → Web Chat for details.

Setting	Type	Default	Description
web_server	boolean	false	Enable the built-in web chat HTTP server
web_server_port	integer	8080	Port the web server listens on
web_server_ssl_cert	string	—	Path to SSL certificate file for HTTPS (e.g., "../src/web/ssl.crt")
web_server_ssl_key	string	—	Path to SSL private key file for HTTPS (e.g., "../src/web/ssl.key")