Manuale di Bot Telegram Customer Service AI

Cosa fa

• Riceve messaggi di testo non comando inviati al bot Telegram mentre lo script è in esecuzione.
• All’avvio con il comando /start mostra quattro pulsanti: Ordini, Resi, Pagamenti e Operatore.
• Invia al modello gpt-4o-mini la knowledge base e il messaggio dell’utente, poi pubblica su Telegram la risposta restituita dal modello.
• Conserva in memoria il contesto della conversazione per chat; oltre 20 elementi riduce la cronologia mantenendo il messaggio di sistema e gli ultimi 10 messaggi.
• Per i pulsanti Ordini, Resi e Pagamenti invia al modello un prompt predefinito corrispondente alla categoria selezionata.
• Mostra un pulsante per parlare con un operatore quando nella risposta del modello compaiono operatore, non so, non posso o contatta, oltre al pulsante Operatore disponibile in /start.
• In caso di escalation invia al chat ID amministratore configurato il nome della chat, il relativo ID e l’orario, quindi informa l’utente che un operatore è stato avvisato.
• Espone il comando /stats, utilizzabile solo dal chat ID amministratore configurato, con contatori in memoria per conversazioni, messaggi gestiti ed escalation.

Cosa non fa

• Non resta online da solo: il processo Python deve continuare a essere eseguito in un ambiente con connessione Internet.
• Non include un pannello web, un database, file di log conversazioni o una cronologia persistente dopo il riavvio.
• Non sostituisce un operatore umano e non può garantire che un operatore risponda entro un determinato tempo.
• Non gestisce come richieste AI foto, file, messaggi vocali o altri messaggi non testuali; il gestore principale è limitato ai messaggi di testo non comando.
• Non consulta automaticamente cataloghi, ordini, spedizioni, CRM, siti web o altri sistemi esterni: può usare solo le informazioni che inserisci nella knowledge base e il testo della conversazione.
• Non garantisce accuratezza, completezza o idoneità delle risposte generate; devi revisionare la knowledge base e i comportamenti prima dell’uso pubblico.

Requisiti

• Archivio ZIP del prodotto: Devi estrarre bot-telegram-customer-service-ai.zip e lavorare dalla cartella estratta. Il file README.en.md è in inglese; original/README.md è disponibile solo in italiano.
• Python 3 e pip: Lo script è Python 3 e richiede l’installazione delle dipendenze elencate in original/requirements.txt.
• Bot Telegram e token: Crea un bot con @BotFather e conserva il token in modo riservato. Il codice lo legge dalla variabile BOT_TOKEN.
• Account OpenAI e chiave API: Il codice usa la variabile OPENAI_KEY per creare un client OpenAI e richiama il modello gpt-4o-mini. Il servizio può essere a pagamento: consulta il listino del provider.
• Chat ID amministratore: Serve un chat ID Telegram numerico per la variabile ADMIN_CHAT_ID, usata per inoltrare le escalation e autorizzare il comando /stats. La guida consegnata indica @userinfobot come modo per ottenerlo.
• Ambiente sempre attivo e connesso: Per ricevere messaggi il comando deve rimanere attivo in polling. Scegli un computer o server che controlli e per il quale puoi gestire aggiornamenti e sicurezza.

Installazione passo passo

1. Estrai e riconosci i file consegnati. Scarica l’archivio del prodotto ed estrailo in una cartella che puoi modificare. La guida inglese è README.en.md. La guida sorgente original/README.md, i commenti dello script e i messaggi predefiniti per gli utenti sono in italiano. Non modificare l’archivio interno original/package-013.original.zip: lavora sui file già estratti nella cartella original.
2. Installa Python e crea un ambiente isolato. Installa Python 3 se non è già disponibile. Dalla cartella estratta crea un virtual environment; così le librerie del bot restano separate da altri progetti Python sullo stesso computer.
3. Crea il bot Telegram. Con la procedura standard di Telegram, avvia @BotFather, crea un nuovo bot e copia il token assegnato. Non pubblicare il token, non inviarlo in chat e non inserirlo in screenshot o repository pubblici.
4. Prepara la chiave OpenAI. Con la procedura standard di OpenAI, crea una chiave API per il tuo account. Lo script la usa per inviare i messaggi e la knowledge base al modello gpt-4o-mini. Conserva anche questa chiave come un segreto.
5. Individua il chat ID amministratore. Recupera il tuo chat ID Telegram numerico. La guida consegnata suggerisce di scrivere a @userinfobot. Questo ID riceverà i messaggi di escalation e sarà l’unico autorizzato a usare /stats.
6. Crea manualmente il file .env. Il README cita un file .env.example, ma quel template non è presente nell’archivio consegnato. Crea quindi manualmente il file original/.env con le tre righe seguenti. python-dotenv viene caricato dallo script; in alternativa puoi impostare le stesse variabili nell’ambiente del sistema. Non aggiungere questo file a repository pubblici.
7. Personalizza la knowledge base. Apri original/telegram-customer-service-bot.py in un editor di testo e modifica solo il contenuto assegnato a KNOWLEDGE_BASE. Sostituisci i segnaposto per nome azienda, prodotti o servizi, resi, spedizioni, pagamenti e orari. Mantieni informazioni verificabili e indica esplicitamente cosa il bot deve fare quando non conosce la risposta.
8. Installa le dipendenze consegnate. Con il virtual environment attivo, installa esattamente l’elenco incluso in original/requirements.txt. Il file richiede python-telegram-bot, openai e python-dotenv con le versioni minime dichiarate.
9. Avvia il polling. Dalla cartella estratta avvia lo script. Se BOT_TOKEN, OPENAI_KEY o ADMIN_CHAT_ID mancano o iniziano con il segnaposto YOUR_, il programma termina mostrando quali configurazioni mancano. Con valori validi, il processo stampa il messaggio di avvio e resta in esecuzione.
10. Esegui un test controllato. Apri una chat con il bot, invia /start e verifica la comparsa dei quattro pulsanti. Prova una domanda di testo non sensibile e una delle categorie. Premi Operatore e controlla che l’account amministratore riceva l’avviso. Verifica anche /stats dalla chat il cui ID corrisponde a ADMIN_CHAT_ID. Prima dell’uso pubblico, correggi knowledge base e flusso in base ai risultati del test.

Uso quotidiano

Mantieni il processo in funzione

Lascia attivo il comando Python nell’ambiente scelto. Se il processo si interrompe, il bot non esegue polling e non risponde fino a un nuovo avvio.

Avvia le conversazioni con /start

Il comando /start invia il saluto iniziale e i pulsanti Ordini, Resi, Pagamenti e Operatore. Le prime tre categorie generano una richiesta testuale inviata al modello; Operatore avvia l’escalation.

Gestisci le domande di testo

Gli utenti possono inviare una domanda testuale libera. Il bot conserva il contesto soltanto in memoria durante l’esecuzione corrente; dopo un riavvio le conversazioni e i contatori ripartono da zero.

Controlla le escalation

Monitora la chat impostata come ADMIN_CHAT_ID. L’avviso contiene nome della chat, chat ID e orario. L’avviso non risponde al cliente al posto tuo e non crea un ticket o una coda.

Consulta i contatori

Invia /stats dalla chat amministratore configurata. Il comando mostra conversazioni inizializzate, messaggi gestiti dal modello ed escalation raccolte nella sessione in corso. Da altre chat il comando non restituisce statistiche.

Aggiorna le informazioni con prudenza

Quando cambiano politiche, prodotti, pagamenti, spedizioni o orari, modifica KNOWLEDGE_BASE e riavvia lo script affinché il nuovo testo venga usato nelle nuove conversazioni.

Rivedi le risposte e il flusso umano

Controlla regolarmente che le risposte siano coerenti con le informazioni ufficiali e che le escalation arrivino a una persona incaricata. Il testo automatico non sostituisce la revisione umana.

Casi pratici

Piccolo negozio online con domande ricorrenti

Un piccolo negozio online vuole rendere disponibili in Telegram le informazioni già approvate su prodotti, resi, spedizioni e pagamenti, senza collegare il bot al proprio sistema ordini.

1. Inserisci in KNOWLEDGE_BASE descrizioni concise e politiche effettive del negozio.
2. Indica come gestire domande sugli ordini specifici: il bot non può consultarli automaticamente.
3. Avvia il bot e prova i pulsanti Ordini, Resi e Pagamenti.
4. Fai arrivare le richieste non risolte al chat ID della persona responsabile.

I clienti possono ricevere risposte testuali basate sul materiale inserito e l’addetto riceve le richieste che richiedono un intervento umano.

Attività di servizi con orari e condizioni

Un’attività di servizi desidera spiegare in modo uniforme ciò che offre, le condizioni di pagamento e gli orari di supporto riportati nelle proprie informazioni ufficiali.

1. Sostituisci la sezione prodotti o servizi con le descrizioni dei servizi effettivamente offerti.
2. Inserisci condizioni e orari verificati nella knowledge base.
3. Aggiungi istruzioni affinché il bot chieda l’operatore quando una domanda richiede un controllo individuale.
4. Testa messaggi liberi usando casi realistici ma privi di dati personali.

Il bot può presentare le informazioni definite dall’attività e indirizzare le eccezioni a una persona.

Gestione di richieste di reso

Un venditore vuole spiegare il proprio processo di reso senza far prendere al bot decisioni sul singolo acquisto.

1. Inserisci nella sezione POLITICHE la procedura di reso approvata e le eventuali condizioni applicabili.
2. Scrivi una regola che imponga l’escalation se il cliente chiede la verifica di un ordine o di un’eccezione.
3. Fai provare il pulsante Resi e una domanda che richieda una verifica non presente nella knowledge base.
4. Controlla che l’avviso raggiunga ADMIN_CHAT_ID e rispondi al cliente attraverso il tuo normale processo umano.

Gli utenti ricevono una spiegazione generale della politica e le verifiche individuali vengono portate all’attenzione dell’operatore.

Filtro iniziale per il supporto umano

Un team molto piccolo vuole usare il bot come primo punto di contatto, mantenendo una persona responsabile delle situazioni non coperte dalla knowledge base.

1. Compila KNOWLEDGE_BASE con le risposte approvate e con limiti espliciti del bot.
2. Imposta il chat ID dell’addetto di turno come ADMIN_CHAT_ID.
3. Conferma che l’addetto può ricevere messaggi Telegram dal bot e che sa gestire gli avvisi.
4. Verifica il pulsante Operatore e controlla i contatori con /stats dalla chat amministratore.

Il team ottiene un canale iniziale per domande testuali e una segnalazione Telegram quando serve il passaggio umano.

Consigli

• Sostituisci ogni segnaposto nella knowledge base prima di rendere pubblico il bot; testo generico o incompleto può produrre risposte poco utili.
• Scrivi politiche chiare, aggiornate e verificabili; il modello non può confermare informazioni che non hai fornito nel contesto.
• Indica nella knowledge base quando chiedere l’intervento umano, specialmente per eccezioni, reclami, ordini specifici o richieste che richiedono verifiche.
• Prova /start, i tre pulsanti di categoria, una domanda libera, il pulsante Operatore e /stats prima di condividere il bot con i clienti.
• Non inserire nella knowledge base né chiedere in chat numeri completi di carte, password, token, documenti o altre credenziali.
• Tieni BOT_TOKEN e OPENAI_KEY soltanto nel file .env protetto o nelle variabili d’ambiente del tuo ambiente; ruotali presso il provider se sospetti una divulgazione.
• Predisponi e rendi accessibile un’informativa privacy adatta al tuo caso: i messaggi dell’utente e la knowledge base vengono inviati al servizio OpenAI, mentre le escalation inviano dati della chat all’amministratore Telegram.
• Configura un presidio reale della chat amministratore. Il codice invia un avviso, ma non assegna turni, non imposta orari e non verifica che una persona abbia risposto.
• Usa nel bot solo informazioni che hai diritto di comunicare e che sono aggiornate; rivedi ogni modifica alla knowledge base con chi conosce l’attività.
• Tratta le risposte AI come bozze operative: verifica qualità, tono e correttezza prima dell’uso con il pubblico e dopo modifiche significative.

Risoluzione dei problemi

Il programma stampa ERRORE DI CONFIGURAZIONE — il programma non puo' partire.

Uno o più valori BOT_TOKEN, OPENAI_KEY o ADMIN_CHAT_ID mancano oppure iniziano con YOUR_. Questo è il controllo che il codice esegue prima di inizializzare il bot. Crea o correggi original/.env con tutte e tre le chiavi oppure imposta le stesse variabili nell’ambiente che esegue Python. Riavvia il comando senza mostrare i valori a terzi.

Il README cita .env.example ma non riesci a trovarlo.

Il file .env.example è elencato in entrambe le guide consegnate, ma non è presente nell’archivio effettivamente fornito. Crea manualmente original/.env con BOT_TOKEN, OPENAI_KEY e ADMIN_CHAT_ID, ciascuno su una riga, come indicato in questo manuale.

Python segnala ModuleNotFoundError per telegram, openai o dotenv.

Le dipendenze non sono installate nell’interprete che sta avviando lo script oppure il virtual environment non è attivo. Attiva .venv e usa python -m pip install -r original/requirements.txt. Avvia poi il bot con lo stesso comando python dell’ambiente attivato.

Il bot non risponde dopo che il terminale è stato chiuso o il processo si è fermato.

Il codice usa app.run_polling(); quando il processo non è attivo non può ricevere aggiornamenti da Telegram. Riavvia lo script nell’ambiente scelto e organizza una modalità di esecuzione continuativa che sai amministrare. Controlla i messaggi del terminale se il processo termina.

Il bot non risponde a una foto, a un file o a un messaggio vocale.

Il gestore principale del codice ascolta soltanto messaggi di testo che non sono comandi. Chiedi all’utente di scrivere la richiesta come testo oppure prevedi un operatore per le richieste non testuali. Non aspettarti che lo script elabori automaticamente allegati.

Il bot restituisce un errore quando deve generare una risposta AI.

La richiesta al provider OpenAI richiede una chiave valida, disponibilità del servizio, una configurazione account idonea e connettività. Il codice non implementa una gestione degli errori specifica attorno alla chiamata al modello. Controlla in modo riservato OPENAI_KEY, lo stato dell’account e la documentazione o il listino del provider. Esamina il messaggio di errore del terminale senza pubblicare credenziali.

Le risposte sono generiche, errate o in una forma non adatta all’attività.

Il modello riceve la stringa KNOWLEDGE_BASE predefinita, che contiene segnaposto e regole generali in italiano. Sostituisci i segnaposto con informazioni ufficiali e aggiornate, aggiungi limiti chiari e testa nuovamente. Riavvia lo script dopo aver salvato la modifica.

L’amministratore non riceve l’escalation.

ADMIN_CHAT_ID può essere errato o la consegna del messaggio Telegram all’account amministratore può non essere disponibile nel suo stato attuale. Verifica che ADMIN_CHAT_ID sia il chat ID numerico corretto, avvia una chat con il bot dall’account amministratore se necessario e prova il pulsante Operatore. Controlla gli errori nel terminale.

Il comando /stats non mostra dati.

Il gestore restituisce subito se l’ID della chat che invia /stats non coincide esattamente con ADMIN_CHAT_ID. Inoltre i contatori sono soltanto in memoria e si azzerano al riavvio. Invia /stats dalla chat il cui ID è configurato in ADMIN_CHAT_ID e verifica il valore. Considera le statistiche come dati della sessione corrente, non come report storico.

L’utente riceve l’avviso che un operatore è stato avvisato, ma nessuno risponde.

Il codice invia un avviso Telegram ma non assegna l’attività, non monitora una risposta umana e non gestisce tempi di servizio. Definisci un presidio umano per ADMIN_CHAT_ID, controlla gli avvisi e aggiorna la knowledge base e le comunicazioni al cliente affinché riflettano il tuo effettivo processo di assistenza.

Limiti da conoscere

• Le risposte sono generate da un modello AI e possono contenere errori o interpretazioni non previste; rivedi sempre knowledge base, tono e casi limite prima e durante l’uso pubblico.
• Il codice invia messaggi dell’utente e knowledge base al servizio OpenAI per generare le risposte. Le escalation inviano nome della chat, chat ID e orario all’amministratore via Telegram. Predisponi informativa privacy, base giuridica e procedure GDPR appropriate al tuo caso.
• Non chiedere né raccogliere tramite il bot password, token, codici di sicurezza o dati completi di carte. Gestisci dati personali e richieste riservate tramite procedure sicure e umane.
• La cronologia e le statistiche sono in memoria: vengono perse al riavvio e non costituiscono un registro affidabile per assistenza, audit o conformità.
• Il bot funziona solo mentre il processo di polling resta attivo ed è soggetto alla disponibilità di Telegram, OpenAI, rete e delle rispettive configurazioni del tuo account.
• La guida consegnata riporta una stima dei costi per gpt-4o-mini, ma prezzi, disponibilità e consumo effettivo dipendono dal provider e dall’uso. Verifica sempre il listino OpenAI prima dell’attivazione.

Domande frequenti

Quali file consegnati sono in inglese e quali solo in italiano?

README.en.md è la guida informativa in inglese. original/README.md è disponibile solo in italiano. original/telegram-customer-service-bot.py contiene commenti, knowledge base e messaggi predefiniti per gli utenti in italiano. requirements.txt non è una guida linguistica ma un elenco di pacchetti.

Dov’è il file .env.example citato nel README?

Non è presente nell’archivio consegnato. Crea tu original/.env con BOT_TOKEN, OPENAI_KEY e ADMIN_CHAT_ID oppure configura le stesse variabili nell’ambiente di esecuzione.

Posso modificare le informazioni che il bot usa per rispondere?

Sì. Modifica la stringa KNOWLEDGE_BASE in original/telegram-customer-service-bot.py e riavvia lo script. Inserisci solo informazioni aggiornate che sei autorizzato a comunicare.

Il bot può controllare un ordine specifico o il mio sito?

No. Nel codice consegnato non ci sono integrazioni con ordini, cataloghi, siti, CRM o database. Il bot usa la knowledge base, il messaggio dell’utente e il contesto della conversazione in memoria.

Come funziona il passaggio a un operatore?

L’utente può premere Operatore in /start o il pulsante mostrato dopo alcune risposte. Il codice invia un messaggio a ADMIN_CHAT_ID con nome della chat, chat ID e orario. Non inoltra una conversazione completa e non garantisce una risposta umana.

Le statistiche restano disponibili dopo un riavvio?

No. conversations e stats sono dizionari in memoria nel processo Python. Un riavvio li ricrea vuoti; /stats mostra solo i contatori della sessione attiva e solo all’amministratore configurato.

Quanto costa usare il bot?

La guida sorgente consegnata afferma che con gpt-4o-mini una conversazione media costa meno di €0,001 e che 1000 conversazioni al mese corrispondono a circa €1. È un’indicazione del materiale consegnato, non una garanzia o un prezzo verificato: controlla il listino OpenAI e il consumo effettivo del tuo account.