Telegram AI Customer Service Bot manual

What it does

• Receives non-command text messages sent to the Telegram bot while the script is running.
• When started with /start, displays four buttons: Ordini, Resi, Pagamenti, and Operatore.
• Sends the knowledge base and the user message to the gpt-4o-mini model, then posts the model response to Telegram.
• Keeps conversation context in memory per chat; after more than 20 items, it reduces the history while retaining the system message and the latest 10 messages.
• For the Ordini, Resi, and Pagamenti buttons, sends the model a predefined prompt for the selected category.
• Shows a button to speak to an operator when the model reply contains operatore, non so, non posso, or contatta, in addition to the Operatore button available in /start.
• For an escalation, sends the configured administrator chat ID the chat name, its ID, and the time, then tells the user that an operator has been notified.
• Provides the /stats command, available only to the configured administrator chat ID, with in-memory counts for conversations, handled messages, and escalations.

What it does not do

• It does not stay online by itself: the Python process must keep running in an environment with an Internet connection.
• It does not include a web dashboard, database, conversation log files, or persistent history after a restart.
• It does not replace a human operator and cannot guarantee that an operator will reply within any particular time.
• It does not handle photos, files, voice messages, or other non-text messages as AI requests; the main handler is limited to non-command text messages.
• It does not automatically consult catalogues, orders, shipments, CRMs, websites, or other external systems: it can use only the information in your knowledge base and the conversation text.
• It does not guarantee the accuracy, completeness, or suitability of generated replies; you must review the knowledge base and behaviour before public use.

Requirements

• Product ZIP archive: You must extract bot-telegram-customer-service-ai.zip and work from the extracted folder. README.en.md is in English; original/README.md is available only in Italian.
• Python 3 and pip: The script is Python 3 and requires the dependencies listed in original/requirements.txt.
• Telegram bot and token: Create a bot with @BotFather and keep its token private. The code reads it from the BOT_TOKEN variable.
• OpenAI account and API key: The code uses the OPENAI_KEY variable to create an OpenAI client and calls the gpt-4o-mini model. The service may be paid; check the provider price list.
• Administrator chat ID: You need a numeric Telegram chat ID for the ADMIN_CHAT_ID variable, used to forward escalations and authorize the /stats command. The delivered guide names @userinfobot as a way to obtain it.
• Always-on connected environment: To receive messages, the command must remain active in polling mode. Choose a computer or server you control and on which you can manage updates and security.

Step-by-step setup

1. Extract and identify the delivered files. Download the product archive and extract it to a folder you can edit. The English guide is README.en.md. The source guide original/README.md, script comments, and default end-user messages are in Italian. Do not edit the internal archive original/package-013.original.zip; work on the files already extracted in the original folder.
2. Install Python and create an isolated environment. Install Python 3 if it is not already available. From the extracted folder, create a virtual environment so the bot libraries remain separate from other Python projects on the same computer.
3. Create the Telegram bot. Using Telegram’s standard procedure, open @BotFather, create a new bot, and copy its assigned token. Do not publish the token, send it in chat, or place it in screenshots or public repositories.
4. Prepare the OpenAI key. Using OpenAI’s standard procedure, create an API key for your account. The script uses it to send messages and the knowledge base to the gpt-4o-mini model. Keep this key secret as well.
5. Find the administrator chat ID. Retrieve your numeric Telegram chat ID. The delivered guide suggests messaging @userinfobot. This ID receives escalation messages and is the only one allowed to use /stats.
6. Create the .env file manually. The README refers to a .env.example file, but that template is not included in the delivered archive. Create original/.env manually with the following three lines. python-dotenv is loaded by the script; alternatively, you can set the same variables in the system environment. Do not add this file to public repositories.
7. Customise the knowledge base. Open original/telegram-customer-service-bot.py in a text editor and edit only the content assigned to KNOWLEDGE_BASE. Replace the placeholders for company name, products or services, returns, shipping, payments, and hours. Keep information verifiable and state clearly what the bot must do when it does not know the answer.
8. Install the delivered dependencies. With the virtual environment active, install exactly the list included in original/requirements.txt. The file requires python-telegram-bot, openai, and python-dotenv at the declared minimum versions.
9. Start polling. From the extracted folder, start the script. If BOT_TOKEN, OPENAI_KEY, or ADMIN_CHAT_ID is missing or starts with the placeholder YOUR_, the program exits and reports which configurations are missing. With valid values, the process prints its startup message and remains running.
10. Run a controlled test. Open a chat with the bot, send /start, and check that the four buttons appear. Try a non-sensitive text question and one category. Press Operatore and check that the administrator account receives the alert. Also check /stats from the chat whose ID matches ADMIN_CHAT_ID. Before public use, correct the knowledge base and flow based on the test results.

Daily use

Keep the process running

Leave the Python command active in the environment you selected. If the process stops, the bot does not poll or reply until it is started again.

Start conversations with /start

The /start command sends the opening greeting and the Ordini, Resi, Pagamenti, and Operatore buttons. The first three categories create a text request sent to the model; Operatore starts the escalation.

Handle text questions

Users can send a free-text question. The bot keeps context only in memory during the current run; after a restart, conversations and counters start again from zero.

Monitor escalations

Monitor the chat set as ADMIN_CHAT_ID. The alert contains the chat name, chat ID, and time. The alert does not reply to the customer for you and does not create a ticket or queue.

Read the counters

Send /stats from the configured administrator chat. The command shows initialised conversations, messages handled by the model, and escalations collected during the current run. It returns no statistics from other chats.

Update information carefully

When policies, products, payments, shipping, or hours change, edit KNOWLEDGE_BASE and restart the script so the new text is used in new conversations.

Review replies and the human handoff

Regularly check that replies match the official information and that escalations reach an assigned person. Automated text does not replace human review.

Practical cases

Small online shop with recurring questions

A small online shop wants to make its already approved information about products, returns, shipping, and payments available on Telegram, without connecting the bot to its order system.

1. Put concise descriptions and the shop’s actual policies in KNOWLEDGE_BASE.
2. State how questions about specific orders should be handled: the bot cannot look them up automatically.
3. Start the bot and test the Ordini, Resi, and Pagamenti buttons.
4. Have unresolved requests reach the chat ID of the responsible person.

Customers can receive text replies based on the supplied material, and the staff member receives requests that need human action.

Service business with hours and conditions

A service business wants to explain consistently what it offers, its payment conditions, and support hours stated in its official information.

1. Replace the products or services section with descriptions of the services actually offered.
2. Put verified conditions and hours into the knowledge base.
3. Add instructions requiring the bot to request an operator when a question needs an individual check.
4. Test free-text messages with realistic cases that do not contain personal data.

The bot can present information defined by the business and direct exceptions to a person.

Handling return-policy questions

A seller wants to explain its return process without having the bot make a decision about an individual purchase.

1. Enter the approved return process and any applicable conditions in the POLITICHE section.
2. Write a rule requiring escalation when the customer asks for an order-specific or exception check.
3. Test the Resi button and a question requiring a check not contained in the knowledge base.
4. Confirm that the alert reaches ADMIN_CHAT_ID and reply to the customer through your normal human process.

Users receive a general policy explanation, and individual checks are brought to the operator’s attention.

Initial filter for human support

A very small team wants to use the bot as an initial contact point while keeping a person responsible for situations not covered by the knowledge base.

1. Fill KNOWLEDGE_BASE with approved replies and explicit bot limits.
2. Set the on-duty staff member’s chat ID as ADMIN_CHAT_ID.
3. Confirm that the staff member can receive Telegram messages from the bot and knows how to manage alerts.
4. Test the Operatore button and check counters with /stats from the administrator chat.

The team gets an initial channel for text questions and a Telegram alert when a human handoff is needed.

Tips

• Replace every placeholder in the knowledge base before making the bot public; generic or incomplete text can lead to unhelpful replies.
• Write clear, current, and verifiable policies; the model cannot confirm information you have not provided in its context.
• State in the knowledge base when human help is required, especially for exceptions, complaints, specific orders, or requests needing verification.
• Test /start, the three category buttons, a free-text question, the Operatore button, and /stats before sharing the bot with customers.
• Do not place or request full card numbers, passwords, tokens, identity documents, or other credentials in the knowledge base or chat.
• Keep BOT_TOKEN and OPENAI_KEY only in a protected .env file or your environment variables; rotate them through the provider if you suspect disclosure.
• Prepare and make available a privacy notice suitable for your situation: user messages and the knowledge base are sent to the OpenAI service, while escalations send chat data to the Telegram administrator.
• Arrange real monitoring for the administrator chat. The code sends an alert, but it does not assign shifts, set business hours, or verify that a person replied.
• Use only information you are entitled to communicate in the bot, and keep it current; review every knowledge-base change with someone who knows the business.
• Treat AI replies as operational drafts: verify quality, tone, and correctness before public use and after significant changes.

Troubleshooting

The program prints ERRORE DI CONFIGURAZIONE — il programma non puo' partire.

One or more of BOT_TOKEN, OPENAI_KEY, or ADMIN_CHAT_ID is missing or starts with YOUR_. This is the check the code performs before initialising the bot. Create or correct original/.env with all three keys, or set the same variables in the environment that runs Python. Restart the command without exposing the values to anyone else.

The README refers to .env.example but you cannot find it.

The .env.example file is listed in both delivered guides, but it is not present in the actual delivered archive. Create original/.env manually with BOT_TOKEN, OPENAI_KEY, and ADMIN_CHAT_ID, one per line, as shown in this manual.

Python reports ModuleNotFoundError for telegram, openai, or dotenv.

The dependencies are not installed in the interpreter starting the script, or the virtual environment is not active. Activate .venv and use python -m pip install -r original/requirements.txt. Then start the bot with the same python command from the active environment.

The bot does not reply after the terminal was closed or the process stopped.

The code uses app.run_polling(); when the process is not active, it cannot receive Telegram updates. Restart the script in your chosen environment and arrange an ongoing execution method that you know how to administer. Check terminal output if the process ends.

The bot does not reply to a photo, file, or voice message.

The main code handler listens only for text messages that are not commands. Ask the user to write the request as text or provide a human operator for non-text requests. Do not expect the script to process attachments automatically.

The bot returns an error when it needs to generate an AI reply.

The OpenAI provider request needs a valid key, service availability, suitable account configuration, and connectivity. The code does not implement dedicated error handling around the model call. Privately check OPENAI_KEY, account status, and the provider documentation or price list. Inspect the terminal error without publishing credentials.

Replies are generic, incorrect, or unsuitable for the business.

The model receives the default KNOWLEDGE_BASE string, which contains placeholders and general Italian rules. Replace placeholders with current official information, add clear limits, and test again. Restart the script after saving the edit.

The administrator does not receive an escalation.

ADMIN_CHAT_ID may be wrong, or Telegram message delivery to the administrator account may not be available in its current state. Check that ADMIN_CHAT_ID is the correct numeric chat ID, start a chat with the bot from the administrator account if necessary, and test the Operatore button. Check terminal errors.

The /stats command shows no data.

The handler returns immediately when the chat ID sending /stats does not exactly match ADMIN_CHAT_ID. Also, the counters are only in memory and reset on restart. Send /stats from the chat whose ID is configured as ADMIN_CHAT_ID and check the value. Treat the statistics as current-session data, not a historical report.

The user sees an operator-notified message, but no one replies.

The code sends a Telegram alert but does not assign work, monitor a human response, or manage service times. Define human coverage for ADMIN_CHAT_ID, monitor the alerts, and update the knowledge base and customer communication to reflect your actual support process.

Limits to know

• Replies are generated by an AI model and can contain errors or unintended interpretations; always review the knowledge base, tone, and edge cases before and during public use.
• The code sends user messages and the knowledge base to the OpenAI service to generate replies. Escalations send the chat name, chat ID, and time to the administrator through Telegram. Provide a privacy notice, lawful basis, and GDPR procedures appropriate to your situation.
• Do not request or collect passwords, tokens, security codes, or full card data through the bot. Handle personal data and sensitive requests through secure human procedures.
• History and statistics are in memory: they are lost at restart and are not a reliable record for support, audit, or compliance purposes.
• The bot works only while the polling process remains active and is subject to the availability of Telegram, OpenAI, the network, and your respective account configurations.
• The delivered guide gives a cost estimate for gpt-4o-mini, but pricing, availability, and actual consumption depend on the provider and your usage. Always check the OpenAI price list before enabling it.

Frequently asked questions

Which delivered files are in English and which are Italian-only?

README.en.md is the English informational guide. original/README.md is available only in Italian. original/telegram-customer-service-bot.py has Italian comments, knowledge base, and default end-user messages. requirements.txt is not a language guide but a package list.

Where is the .env.example file mentioned in the README?

It is not in the delivered archive. Create original/.env yourself with BOT_TOKEN, OPENAI_KEY, and ADMIN_CHAT_ID, or configure the same variables in the execution environment.

Can I change the information the bot uses to reply?

Yes. Edit the KNOWLEDGE_BASE string in original/telegram-customer-service-bot.py and restart the script. Add only current information that you are authorised to communicate.

Can the bot check a specific order or my website?

No. The delivered code has no integration with orders, catalogues, websites, CRMs, or databases. The bot uses the knowledge base, the user message, and in-memory conversation context.

How does the human handoff work?

The user can press Operatore in /start or the button shown after some replies. The code sends ADMIN_CHAT_ID a message with the chat name, chat ID, and time. It does not forward a complete conversation or guarantee a human response.

Do statistics remain after a restart?

No. conversations and stats are dictionaries in the Python process memory. A restart recreates them empty; /stats shows only the current run’s counters and only to the configured administrator.

How much does it cost to use the bot?

The delivered source guide states that with gpt-4o-mini an average conversation costs less than €0.001 and that 1,000 conversations per month are approximately €1. This is a statement in the delivered material, not a guarantee or verified price: check OpenAI’s price list and your account’s actual usage.