Utilizzo i Bot di Telegram per collegare servizi esterni

Ciao a tutti, Marcus qui da ai7bot.com. Spero stiate trascorrendo un buon lunedì. Oggi voglio parlare di qualcosa che è stato un vero e proprio cambiamento silenzioso per i miei progetti di bot personali e, francamente, per come gestisco la mia vita online: l’API di Telegram Bot. Più specificamente, voglio parlare di come possiamo andare oltre il semplice “echo bot” e iniziare a costruire bot che interagiscono con servizi esterni, portando dati e azioni del mondo reale nelle nostre chat di Telegram.

Negli anni, quando qualcuno menzionava “bot,” la mia mente andava subito a incubi del servizio clienti o a strumenti di moderazione elaborati su Discord. I bot di Telegram sono sempre sembrati un po’… più semplici, magari meno potenti. Ma avevo torto. Negli ultimi anno, specialmente con l’aumento dell’interesse per gli LLM e il tentativo di renderli accessibili, mi sono trovato a fare ampio uso dei bot di Telegram per tutto, dalle ricerche rapide di dati alle attivazioni di automazioni. E la magia avviene quasi sempre quando colleghi il tuo bot a un’API.

La bellezza dell’API di Telegram Bot non è solo la sua semplicità; è la sua incredibile flessibilità. È un ponte. Un ponte tra i tuoi utenti in una chat e letteralmente qualsiasi servizio web là fuori che offre un’API. Pensaci per un secondo. I tuoi utenti non hanno bisogno di aprire un browser, accedere a un altro servizio o persino lasciare Telegram. Possono semplicemente chattare con il tuo bot e portare a termine le loro cose. È una grande cosa, specialmente nel 2026, dove tutti stanno cercando di consolidare la propria impronta digitale.

Oltre l’Eco: Perché le API Esterni sono il Miglior Amico del tuo Bot

Il mio primo bot di Telegram, tanto tempo fa, era imbarazzantemente basilare. Ripeteva semplicemente ciò che gli mandavi. Un pappagallo digitale. Carino per circa cinque minuti, poi completamente inutile. Il punto di svolta per me è arrivato quando ho voluto un modo rapido per controllare i prezzi delle criptovalute senza aprire CoinMarketCap ogni cinque minuti. È allora che ho iniziato a esplorare le API esterne.

Nel momento in cui colleghi il tuo bot a un’API esterna, smette di essere un giocattolo e inizia a essere uno strumento. Improvvisamente, il tuo bot può:

• Recuperare previsioni del tempo per qualsiasi città.
• Cercare i prezzi delle azioni.
• Tradurre testi utilizzando un servizio di traduzione.
• Ottenere definizioni da un dizionario.
• Addirittura controllare dispositivi domestici intelligenti (se hai il giusto accesso API).

Le possibilità sono infinite. È come dare al tuo bot occhi e orecchie sul resto di Internet.

Scegliere la tua API Esterna con Saggezza

Prima di pensare di scrivere codice, devi scegliere la tua API. Non tutte le API sono create uguali. Ecco cosa di solito cerco:

• Buona Documentazione: Questo è non negoziabile. Se la documentazione è scarsa o confusa, sei in un mare di problemi.
• Affidabilità: Il servizio è spesso offline? Ci sono limiti di utilizzo che possono minare il tuo bot?
• Autenticazione: Sono semplici API key, OAuth o qualcosa di più complesso? Di solito, le opzioni semplici sono migliori per il primo tentativo di un bot.
• Output JSON: La maggior parte delle API moderne restituisce dati in formato JSON, che è molto facile da gestire in Python (il mio linguaggio di scelta per i bot).

Per i nostri esempi di oggi, utilizzerò un paio di API famose e gratuite (o con un piano gratuito):

• OpenWeatherMap API: Per ottenere dati meteorologici attuali. È semplice e ampiamente utilizzata.
• RapidAPI (in particolare, un’API di dizionario tramite loro): RapidAPI è un marketplace per API ed è un ottimo modo per scoprire diversi servizi. Prenderemo un semplice dizionario API per cercare parole.

Impostare il tuo Bot di Telegram e l’Ambiente di Sviluppo

Se segui ai7bot.com da un po’, probabilmente lo sai già, ma un rapido ripasso non fa mai male:

1. Ottieni il tuo Token Bot: Parla con il BotFather su Telegram. Invia /newbot, segui le istruzioni e ti darà un token API. Tieni questo segreto!
2. Ambiente Python: Uso Python per i miei bot, nello specifico python-telegram-bot. È una libreria fantastica che astrae molte delle richieste HTTP.

Prepariamo il nostro setup base. Crea un nuovo file Python, chiamiamolo my_api_bot.py:

import os
import logging
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters

# Configura il logging
logging.basicConfig(
 format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', level=logging.INFO
)
logging.getLogger("httpx").setLevel(logging.WARNING)
logger = logging.getLogger(__name__)

# Sostituisci con il tuo token bot reale
BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN", "YOUR_TELEGRAM_BOT_TOKEN_HERE") 

async def start(update: Update, context):
 await update.message.reply_text("Ciao! Sono un bot che può recuperare informazioni da API esterne. Prova /weather [città] o /define [parola].")

async def help_command(update: Update, context):
 await update.message.reply_text("Comandi disponibili:\n/start - Ti saluta\n/help - Mostra questo messaggio\n/weather [città] - Ottieni il meteo attuale\n/define [parola] - Ottieni la definizione")

def main():
 application = Application.builder().token(BOT_TOKEN).build()

 application.add_handler(CommandHandler("start", start))
 application.add_handler(CommandHandler("help", help_command))

 # Aggiungi qui più tardi i gestori per i nostri comandi API
 # application.add_handler(CommandHandler("weather", weather_command))
 # application.add_handler(CommandHandler("define", define_command))

 application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
 main()

Ricorda di installare la libreria: pip install python-telegram-bot httpx (httpx è un client HTTP moderno che python-telegram-bot utilizza internamente).

Una nota rapida sui token API: Non hardcodare mai le tue chiavi API direttamente nel tuo codice pubblico. Utilizza variabili d’ambiente (come ho accennato con os.environ.get) o un file di configurazione separato che non viene sottoposto a controllo delle versioni. Per i test locali, sostituisci semplicemente "YOUR_TELEGRAM_BOT_TOKEN_HERE" con il tuo token effettivo per ora.

Esempio Pratico 1: Bot Meteorologico con OpenWeatherMap

Il mio primo vero “aha!” con le API esterne è stato costruire un semplice bot meteorologico. È un classico per una ragione: tutti hanno bisogno di informazioni sul meteo e OpenWeatherMap ha un’ottima opzione gratuita.

Ottenere la tua OpenWeatherMap API Key

1. Vai su OpenWeatherMap e registrati per un account gratuito.
2. Una volta effettuato l’accesso, vai alla sezione delle tue chiavi API. Troverai la tua chiave API predefinita lì.

Aggiungiamo questo alle nostre variabili d’ambiente o direttamente al nostro script per ora:

# ... (importazioni e logging) ...

OPENWEATHER_API_KEY = os.environ.get("OPENWEATHER_API_KEY", "YOUR_OPENWEATHER_API_KEY_HERE")
BASE_WEATHER_URL = "http://api.openweathermap.org/data/2.5/weather"

# ... (comandi di avvio e aiuto) ...

async def weather_command(update: Update, context):
 if not context.args:
 await update.message.reply_text("Per favore fornisci una città. Esempio: /weather Londra")
 return

 city = " ".join(context.args)
 params = {
 "q": city,
 "appid": OPENWEATHER_API_KEY,
 "units": "metric" # o "imperial" per Fahrenheit
 }

 try:
 # Utilizzando httpx direttamente per la chiamata API
 async with httpx.AsyncClient() as client:
 response = await client.get(BASE_WEATHER_URL, params=params)
 response.raise_for_status() # Solleva un'eccezione per errori HTTP (4xx o 5xx)
 data = response.json()

 if data["cod"] == 200: # Verifica se la richiesta è andata a buon fine
 weather_description = data["weather"][0]["description"].capitalize()
 temperature = data["main"]["temp"]
 feels_like = data["main"]["feels_like"]
 humidity = data["main"]["humidity"]
 wind_speed = data["wind"]["speed"]

 reply_text = (
 f"Meteo a {city.title()}:\n"
 f"Descrizione: {weather_description}\n"
 f"Temperatura: {temperature}°C (Percepita: {feels_like}°C)\n"
 f"Umidità: {humidity}%\n"
 f"Velocità del vento: {wind_speed} m/s"
 )
 else:
 reply_text = f"Impossibile trovare il meteo per {city.title()}. Controlla il nome della città."

 except httpx.HTTPStatusError as e:
 logger.error(f"Errore HTTP durante il recupero del meteo per {city}: {e.response.status_code} - {e.response.text}")
 reply_text = f"Si è verificato un errore durante il recupero dei dati meteo. Stato: {e.response.status_code}"
 except httpx.RequestError as e:
 logger.error(f"Errore di rete durante il recupero del meteo per {city}: {e}")
 reply_text = "Si è verificato un errore di rete. Per favore riprova più tardi."
 except KeyError as e:
 logger.error(f"Errore nell'analisi dei dati meteo per {city}: chiave mancante {e}. Risposta: {data}")
 reply_text = "C'è stato un problema nell'elaborazione dei dati meteo. La risposta dell'API potrebbe essere malformata."
 except Exception as e:
 logger.error(f"Errore inaspettato durante il recupero del meteo per {city}: {e}")
 reply_text = "Si è verificato un errore imprevisto."

 await update.message.reply_text(reply_text)

# ... (funzione principale) ...
def main():
 application = Application.builder().token(BOT_TOKEN).build()

 application.add_handler(CommandHandler("start", start))
 application.add_handler(CommandHandler("help", help_command))
 application.add_handler(CommandHandler("weather", weather_command)) # Aggiungi questa riga!

 application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
 main()

In questo codice, importiamo httpx per effettuare la richiesta HTTP effettiva all’API di OpenWeatherMap. Costruiamo l’URL con la nostra città e la chiave API, quindi analizziamo la risposta JSON per estrarre i dettagli meteo pertinenti. Fondamentale, ho incluso una quantità adeguata di gestione degli errori. Questo è molto importante quando si tratta di API esterne: possono fallire per vari motivi (problemi di rete, chiavi non valide, nomi di città non validi, limiti di richiesta), e non vuoi che il tuo bot smetta di funzionare.

Esempio pratico 2: Bot del dizionario con RapidAPI

RapidAPI è un marketplace dove puoi trovare e iscriverti a migliaia di API. È una risorsa fantastica. Per questo esempio, utilizziamo una semplice API di dizionario. Ne ho trovata una chiamata “Word Dictionary” di Pexel. Dovrai iscriverti a RapidAPI, abbonarti al piano gratuito di un’API di dizionario appropriata e acquisire la tua chiave RapidAPI e i dettagli dell’intestazione host.

Ottenere la tua chiave e host RapidAPI

1. Vai su RapidAPI e registrati.
2. Cerca un “API di dizionario” (ad esempio, “Word Dictionary”).
3. Vai alla pagina dell’API, iscriviti al suo piano gratuito.
4. Nella scheda “Endpoints”, vedrai frammenti di codice. Cerca la tua X-RapidAPI-Key e X-RapidAPI-Host nella sezione intestazioni del frammento Python.

Integriamo questo:

# ... (importazioni, logging, dettagli di OpenWeatherMap) ...

RAPIDAPI_KEY = os.environ.get("RAPIDAPI_KEY", "YOUR_RAPIDAPI_KEY_HERE")
RAPIDAPI_DICTIONARY_HOST = os.environ.get("RAPIDAPI_DICTIONARY_HOST", "YOUR_RAPIDAPI_DICTIONARY_HOST_HERE") # ad esempio, "word-dictionary-api.p.rapidapi.com"
DICTIONARY_BASE_URL = "https://{}/word".format(RAPIDAPI_DICTIONARY_HOST)

# ... (comandi di avvio, aiuto, meteo) ...

async def define_command(update: Update, context):
 if not context.args:
 await update.message.reply_text("Per favore fornisci una parola da definire. Esempio: /define efemerale")
 return

 word = " ".join(context.args).lower()
 headers = {
 "X-RapidAPI-Key": RAPIDAPI_KEY,
 "X-RapidAPI-Host": RAPIDAPI_DICTIONARY_HOST
 }
 params = {"word": word}

 try:
 async with httpx.AsyncClient() as client:
 response = await client.get(DICTIONARY_BASE_URL, headers=headers, params=params)
 response.raise_for_status()
 data = response.json()

 if data and isinstance(data, list) and data[0].get("meaning"):
 meanings = data[0]["meaning"]
 reply_parts = [f"Definizioni per '{word.title()}':"]
 
 for part_of_speech, defs in meanings.items():
 reply_parts.append(f"\n*{part_of_speech.capitalize()}*:")
 for i, definition_obj in enumerate(defs):
 definition = definition_obj.get("definition", "Nessuna definizione disponibile.")
 reply_parts.append(f" {i+1}. {definition}")
 
 reply_text = "\n".join(reply_parts)
 else:
 reply_text = f"Impossibile trovare definizioni per '{word.title()}'. Controlla la tua ortografia?"

 except httpx.HTTPStatusError as e:
 logger.error(f"Errore HTTP durante il recupero della definizione per {word}: {e.response.status_code} - {e.response.text}")
 reply_text = f"Si è verificato un errore durante il recupero dei dati del dizionario. Stato: {e.response.status_code}"
 except httpx.RequestError as e:
 logger.error(f"Errore di rete durante il recupero della definizione per {word}: {e}")
 reply_text = "Si è verificato un errore di rete. Per favore riprova più tardi."
 except Exception as e:
 logger.error(f"Errore inaspettato durante il recupero della definizione per {word}: {e}")
 reply_text = "Si è verificato un errore imprevisto."
 
 await update.message.reply_text(reply_text)

# ... (funzione principale) ...
def main():
 application = Application.builder().token(BOT_TOKEN).build()

 application.add_handler(CommandHandler("start", start))
 application.add_handler(CommandHandler("help", help_command))
 application.add_handler(CommandHandler("weather", weather_command))
 application.add_handler(CommandHandler("define", define_command)) # Aggiungi questa riga!

 application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
 main()

Questo esempio di dizionario mostra come gestire le API che richiedono intestazioni personalizzate per l’autenticazione (come X-RapidAPI-Key e X-RapidAPI-Host di RapidAPI). Inoltre, l’analisi della risposta JSON può essere un po’ più complessa, poiché le API di dizionario spesso restituiscono strutture annidate. Ho aggiunto un po’ di logica per scorrere le diverse parti del discorso e le loro definizioni.

Indicazioni pratiche per il tuo prossimo progetto bot

Ok, quindi hai visto come connettere il tuo bot di Telegram a un paio di diverse API esterne. Cosa dovresti portare via da questo?

1. Inizia semplice, poi espandi: Non cercare di costruire il prossimo ChatGPT già dal primo giorno. Fai funzionare un bot di eco di base, poi aggiungi un’integrazione API, poi un’altra. Itera.
2. La gestione degli errori è tua amica: Sul serio, non posso stressare abbastanza questo punto. I servizi esterni falliranno. La tua connessione internet può interrompersi. Anticipalo e gestiscilo con grazia nel tuo codice. I tuoi utenti ti ringrazieranno.
3. Leggi la documentazione API (sì, sul serio): Dedica del tempo a comprendere come funziona l’API, quali parametri si aspetta e come appare il formato della sua risposta. Ti risparmia molte noie in seguito.
4. Rispetta i limiti di richiesta: La maggior parte delle API a piano gratuito ha limiti di richiesta (ad es., 50 chiamate al minuto). Se il tuo bot diventa popolare, potresti raggiungere questi limiti. Progetta il tuo bot per gestirli (ad es., dicendo all’utente di aspettare o aggiornando il tuo piano API).
5. Proteggi le tue chiavi API: Non inserire mai informazioni sensibili direttamente nel tuo repository. Usa variabili di ambiente o un file di configurazione separato. Questo è cruciale per la sicurezza e la manutenzione.
6. Pensa all’esperienza dell’utente: Quanto sono chiari i messaggi del tuo bot? Guida l’utente se fa un errore? Un bot potente è utile solo se le persone possono usarlo facilmente.

Costruire bot che interagiscono con API esterne è dove inizia il vero divertimento. Trasforma la tua semplice interfaccia di chat in un potente centro comandi per tutti i tipi di servizi internet. Il mio consiglio? Scegli un’API per un servizio che usi quotidianamente – magari controllare i punteggi della tua squadra sportiva preferita, o tracciare pacchi, o persino gestire la tua lista di cose da fare – e prova a costruire un bot per questo. Imparerai molto e potresti costruire qualcosa di veramente utile per te e per gli altri.

Buona costruzione di bot e ci vediamo nel prossimo post!

🕒 Published: April 4, 2026