Manuale di Bot Telegram AI Content Creator

Cosa fa

• Avvia un bot Telegram tramite polling quando BOT_TOKEN e OPENAI_KEY sono configurati.
• Con il comando /post richiede un post in italiano per linkedin, instagram, twitter o tiktok a partire dall'argomento inserito.
• Per /post applica istruzioni diverse per piattaforma, incluse soglie richieste di 3000, 2200, 280 e 300 caratteri rispettivamente.
• Con il comando /thread richiede un thread Twitter/X di sette tweet in italiano e invia il testo risultante fino ai primi 4000 caratteri.
• Con il comando /hashtag richiede fino a 30 hashtag Instagram per un argomento e aggiunge il simbolo # alle righe ricevute.
• Con il comando /calendar richiede un piano editoriale di sette giorni in formato tabella Markdown per una nicchia.
• Mostra all'avvio un messaggio di benvenuto con i comandi e una tastiera di pulsanti per piattaforme, thread e calendario.

Cosa non fa

• Non pubblica direttamente sui social, non programma post e non collega account social.
• Non genera immagini, non conserva bozze in un database e non fornisce analisi delle prestazioni.
• Non implementa il comando /caption, anche se il messaggio di benvenuto lo mostra.
• Non implementa alcuna azione per la pressione dei pulsanti mostrati in /start; usa i comandi slash registrati.
• Non offre un comando per scegliere il tono: il comando /post usa il tono professionale predefinito del codice.
• Non revisiona né approva i contenuti generati e non garantisce correttezza, originalità o conformità del testo.

Requisiti

• Archivio del pacchetto: Devi avere il file ZIP acquistato e poterlo estrarre in una cartella scrivibile.
• Python 3 e terminale: Ti servono Python 3 e l'accesso a un terminale per creare un ambiente virtuale, installare requirements.txt e mantenere il programma in esecuzione. Il pacchetto non dichiara una versione specifica di Python.
• Account Telegram e bot Telegram: Devi creare un bot tramite @BotFather e conservare il relativo token BOT_TOKEN.
• Account e chiave API OpenAI: Devi disporre di una chiave OPENAI_KEY utilizzabile con il modello indicato nel codice. L'uso del provider può essere a pagamento: verifica listino, limiti e condizioni del provider.
• Connessione Internet: È necessaria mentre il bot effettua polling su Telegram e quando inoltra le richieste di generazione a OpenAI.
• Due credenziali segrete: Servono BOT_TOKEN e OPENAI_KEY. Non inserirle in file pubblici, repository, screenshot o messaggi chat.

Installazione passo passo

1. Scarica ed estrai il pacchetto. Scarica il tuo ZIP e decomprimilo in una cartella locale. Dopo l'estrazione verifica che siano presenti telegram-content-creator-bot.py, requirements.txt, README.md, README.en.md e USER-GUIDE.en.md.
2. Apri la cartella estratta nel terminale. Apri un terminale e spostati nella cartella che contiene il file Python e requirements.txt. I comandi riportati di seguito sono per un terminale compatibile con bash; su altri sistemi usa gli equivalenti del tuo ambiente.
3. Crea il bot Telegram. In Telegram avvia la procedura standard di @BotFather per creare un bot. Copia il token assegnato e trattalo come una password: servirà come valore di BOT_TOKEN.
4. Crea o recupera la chiave OpenAI. Segui la procedura standard di OpenAI per creare una chiave API e conservala in modo sicuro. Il programma la legge con il nome OPENAI_KEY e usa il modello gpt-4o-mini.
5. Crea manualmente il file .env. Il README cita .env.example, ma questo file non è incluso nell'archivio. Crea tu un file chiamato .env nella cartella estratta e inserisci esattamente le due variabili seguenti, sostituendo solo i valori tra parentesi angolari. python-dotenv viene caricato dal programma se disponibile.
6. Crea un ambiente virtuale Python. Nella cartella del progetto crea un ambiente isolato per non mescolare queste librerie con altre installazioni Python. Attivalo prima di installare o avviare il bot.
7. Installa le dipendenze consegnate. Con l'ambiente virtuale attivo, installa le librerie elencate nel file requirements.txt. Il file richiede python-telegram-bot, openai e python-dotenv.
8. Avvia il programma. Avvia il file Python dalla stessa cartella che contiene .env. Se le due variabili mancano o iniziano con YOUR_, il programma termina con un errore di configurazione invece di avviare il bot. Il messaggio di avvio nel terminale compare prima del polling e da solo non conferma la validità delle chiavi.
9. Invia il primo comando al bot. Lascia aperto il terminale, apri in Telegram la chat con il bot che hai creato e invia /start. Per una prima richiesta usa uno dei quattro nomi di piattaforma supportati e un argomento. Se il bot risponde, copia il testo e revisionarlo prima di qualunque uso pubblico.

Uso quotidiano

Avvia prima il processo

Ogni sessione richiede che telegram-content-creator-bot.py resti in esecuzione con le dipendenze e le credenziali disponibili. Se chiudi il terminale o interrompi il processo, il bot non potrà rispondere finché non lo riavvii.

Crea un post con /post

Usa /post seguito da linkedin, instagram, twitter o tiktok e poi dall'argomento. Per esempio: /post instagram consigli per scegliere una borraccia riutilizzabile. Inserisci nell'argomento il contesto utile, perché non esistono campi separati per pubblico, obiettivo o tono.

Richiedi un thread con /thread

Usa /thread seguito dall'argomento. Il codice chiede sette tweet numerati in italiano e invia il risultato unito; se il testo supera 4000 caratteri, il bot invia solo la parte iniziale.

Richiedi hashtag con /hashtag

Usa /hashtag seguito dall'argomento. Il bot chiede al modello hashtag Instagram e restituisce al massimo 30 elementi, ciascuno con il prefisso #. Controlla pertinenza, lingua e regole della piattaforma prima di usarli.

Richiedi un piano con /calendar

Usa /calendar seguito dalla tua nicchia. Il codice chiede una tabella Markdown per sette giorni con piattaforma, tipo di contenuto, argomento, orario suggerito e hook. Considera gli orari come proposte generate, non come dati verificati per il tuo pubblico.

Usa solo i comandi realmente gestiti

Non fare affidamento su /caption né sui pulsanti mostrati dopo /start: questa versione non registra un handler per /caption o per le pressioni dei pulsanti. Usa invece /post, /thread, /hashtag e /calendar.

Casi pratici

Bozza Instagram per un piccolo negozio

Un piccolo negozio vuole preparare una bozza sul lancio di una collezione di quaderni riciclati, senza collegare il proprio account Instagram al programma.

1. Avvia il bot configurato e apri la chat Telegram.
2. Invia /post instagram lancio di una collezione di quaderni riciclati.
3. Leggi la bozza ricevuta e verifica dettagli del prodotto, disponibilità e dichiarazioni ambientali.
4. Adatta testo e hashtag al tono del marchio e pubblica manualmente con gli strumenti del social scelto.

Ottieni una bozza di testo social in italiano da sottoporre a revisione, senza pubblicazione automatica.

Spunto LinkedIn per un consulente

Un consulente desidera un punto di partenza per parlare di organizzazione del lavoro sul proprio profilo LinkedIn.

1. Apri il bot mentre il processo Python è attivo.
2. Invia /post linkedin come organizzare le priorità in un piccolo team.
3. Controlla che esempi, dati e affermazioni siano coerenti con la tua esperienza e con il pubblico.
4. Riscrivi la bozza con casi realmente verificabili e aggiungi eventuali riferimenti necessari.

Ottieni un testo iniziale con la struttura richiesta dal prompt LinkedIn, da personalizzare e validare.

Thread informativo per un formatore

Un formatore vuole preparare una sequenza breve sul tema degli errori di pianificazione del budget.

1. Invia /thread errori comuni nella pianificazione del budget personale.
2. Leggi i tweet numerati ricevuti e verifica con particolare attenzione le affermazioni finanziarie.
3. Rimuovi o correggi consigli non adatti al tuo contesto e non presentare il testo come consulenza finanziaria personalizzata.
4. Se il messaggio Telegram è troncato, conserva la parte ricevuta e prepara manualmente il resto.

Ottieni una bozza di thread in italiano da controllare e adattare, non indicazioni finanziarie affidabili o personalizzate.

Piano editoriale iniziale per un ristorante locale

Un ristorante vegetariano locale vuole raccogliere idee per la settimana, senza aspettarsi programmazione o analisi automatiche.

1. Invia /calendar ristorante vegetariano locale.
2. Esamina la tabella proposta per piattaforme, tipi di contenuto, argomenti, orari e hook.
3. Verifica menu, disponibilità, orari e norme pubblicitarie prima di usare ogni idea.
4. Trasferisci manualmente le idee approvate nel tuo calendario operativo o nel tuo strumento di pubblicazione.

Ottieni un elenco strutturato di idee per sette giorni, da pianificare e pubblicare con strumenti esterni.

Consigli

• Formula l'argomento in modo concreto, indicando prodotto, pubblico, problema o angolazione direttamente nel testo del comando.
• Per /post usa solo linkedin, instagram, twitter o tiktok in minuscolo; un nome diverso usa internamente le impostazioni LinkedIn ma mantiene nel messaggio l'etichetta del nome inserito.
• Aspettati contenuti in italiano: sia i prompt del programma sia l'interfaccia del bot sono prevalentemente in italiano.
• Tratta ogni risultato come una bozza. Verifica fatti, fonti, diritti, citazioni, marchi, promozioni e dichiarazioni prima di pubblicare.
• Mantieni una copia locale delle bozze approvate: il codice consegnato non salva cronologia, calendari o contenuti in un database.
• Non inserire nel tema dati personali, informazioni riservate, numeri di carte o password. Valuta basi giuridiche, informative privacy e condizioni del provider se tratti dati personali.
• Conserva BOT_TOKEN e OPENAI_KEY in un gestore di segreti o in un file locale escluso dal controllo versione; rigenerale presso il provider se ritieni siano stati esposti.
• Controlla condizioni, limiti e costi di Telegram e OpenAI prima dell'uso continuativo; il pacchetto non indica prezzi di terze parti.
• Prova una richiesta breve prima di usare argomenti complessi e correggi manualmente il risultato invece di presumere che il modello abbia rispettato ogni istruzione.

Risoluzione dei problemi

Il programma termina subito con ERRORE DI CONFIGURAZIONE.

Nel test senza credenziali il programma ha segnalato BOT_TOKEN e OPENAI_KEY non configurati. Il controllo blocca anche valori che iniziano con YOUR_. Crea o correggi il file .env nella cartella del progetto con entrambe le variabili, oppure esportale nell'ambiente prima dell'avvio. Non lasciare valori segnaposto.

Non trovo .env.example.

README.md e README.en.md lo citano, ma il file non è presente nell'archivio consegnato. Crea manualmente un file .env con una riga BOT_TOKEN e una riga OPENAI_KEY, usando i nomi esatti mostrati nel manuale.

Python segnala che manca un modulo, ad esempio telegram, openai o dotenv.

Le dipendenze non sono state installate nell'interprete Python con cui stai avviando il bot oppure l'ambiente virtuale non è attivo. Attiva .venv e ripeti python -m pip install -r requirements.txt. Avvia poi il programma con python dello stesso ambiente.

Il bot mostra i pulsanti ma toccandoli non accade nulla.

Il codice crea la tastiera ma non registra un CallbackQueryHandler per gestire callback dei pulsanti. Invia i comandi slash supportati direttamente nella chat: /post, /thread, /hashtag o /calendar.

Il comando /caption non risponde come previsto.

Il messaggio di /start elenca /caption, ma nel codice non esiste un CommandHandler registrato per questo comando. Non usare /caption in questa versione. Per una caption usa /post instagram seguito da una descrizione testuale dell'argomento.

Il bot risponde con un messaggio di uso del comando.

Manca l'argomento richiesto, oppure /post non ha almeno piattaforma e argomento. Usa /post linkedin argomento, /thread argomento, /hashtag argomento o /calendar nicchia. Per /post scegli una delle quattro piattaforme supportate.

Dopo l'avvio il bot non risponde o una generazione non arriva.

Il polling Telegram e ogni generazione dipendono da Internet, dalle credenziali, dall'accesso API e dalla disponibilità dei servizi esterni. Il codice non include un flusso specifico di recupero errori per queste richieste. Controlla che il processo sia ancora attivo, che la connessione funzioni e che chiavi, limiti, fatturazione e condizioni dei provider siano validi. Consulta l'errore tecnico nel terminale senza condividere segreti.

Un thread ricevuto sembra incompleto.

Il codice unisce i tweet e invia soltanto i primi 4000 caratteri del risultato. Chiedi un argomento più circoscritto oppure prepara e completa manualmente il thread. Non presumere che tutte le sette parti siano state consegnate se il messaggio è stato tagliato.

Limiti da conoscere

• Il programma è progettato per chiedere contenuti in italiano; le guide inglesi documentano il pacchetto ma non traducono l'interfaccia o i prompt del bot.
• La generazione richiede servizi esterni e connessione Internet. Disponibilità, limiti, condizioni e costi dei provider sono esterni al pacchetto e possono variare.
• I testi AI possono contenere errori, contenuti inappropriati o affermazioni non verificate. Revisiona sempre accuratezza, diritti, trasparenza pubblicitaria e regole della piattaforma prima della pubblicazione.
• Non inviare dati personali o riservati nei comandi senza una base giuridica appropriata, adeguate informative privacy e una valutazione del trattamento verso i provider coinvolti.
• Il comando /post non convalida un nome di piattaforma sconosciuto: per la generazione usa allora le impostazioni LinkedIn, mentre il titolo della risposta conserva il nome digitato.
• Il codice non implementa moderazione, approvazione, archiviazione, pubblicazione, programmazione o analisi dei contenuti.
• README.md dichiara uso personale e commerciale illimitato e vieta la rivendita del file. Per decisioni legali fai riferimento ai termini applicabili e, se necessario, a un professionista qualificato.

Domande frequenti

Devo usare per forza il file .env?

No. Il programma legge BOT_TOKEN e OPENAI_KEY dall'ambiente e prova anche a caricare .env con python-dotenv. Poiché .env.example non è incluso, creare un .env locale è il modo più semplice per molti utenti.

Quali piattaforme accetta /post?

Usa linkedin, instagram, twitter o tiktok. Questi sono i quattro nomi presenti nella configurazione PLATFORMS del codice.

Il bot crea testi in inglese?

No come comportamento configurato. I prompt del programma chiedono contenuti in italiano e l'interfaccia è prevalentemente in italiano. Le due guide con suffisso .en.md sono documentazione in inglese, non una traduzione del software.

Posso scegliere il tono del post dal comando?

No. La funzione interna prevede un parametro tone, ma il solo comando /post registrato la richiama con il valore professionale predefinito; non esiste una sintassi utente per cambiarlo.

Perché /caption è mostrato ma non funziona?

È elencato nel testo di benvenuto, ma non è stato registrato alcun gestore del comando nella versione consegnata.

I pulsanti di /start sostituiscono i comandi?

No. I pulsanti vengono visualizzati, ma non esiste un handler di callback che ne gestisca la pressione. Usa i comandi slash supportati.

Il bot pubblica o programma i post per me?

No. Restituisce testo in chat Telegram; non contiene connessioni a account social, funzioni di pubblicazione o calendario automatico.