This is a personal project documented to integrate Telegram chatbot with Google Cloud Vision using Python. The chatbot takes the role of a game master and assesses if the image uploaded by user passes the criteria to proceed to next stage of the game.

Tools used:

Telegram
Python 3.11
Google Cloud Vision API
Ngrok
VS Code editor

Setup

How to setup the various tools mentioned above can be found on Youtube.

Google Cloud Vision API For Image Annotation in Python - YouTube
How to Create a Telegram Bot Using Python | Python Telegram Bot Project (2025) - YouTube
How to Install Ngrok on Windows 11 | Expose your localhost to everyone | NGROK SETU P - YouTube

Create a folder to store and manage files to run this application.

Create the virtual environment.

 python -m venv venv # create virtual environment
 source venv/Scripts/activate # activate virtual environment

Install following packages for the application

 pip install flask python-telegram-bot==13.7 google-cloud-vision python-dotenv

Create a .env file in the folder to keep the Telegram bot token and the Google service account credentials

 TELE_TOKEN = '<Your telegram bot token>'
 GCP_VISION_CRED = <Path of the json file saved locally> # e.g. C:\Users\Desktop\Project\credentials.json

The folder structure may look something like this

Build the code

from flask import Flask, request
from telegram import Update, Bot
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters, CallbackContext, Dispatcher
from google.cloud import vision
from dotenv import load_dotenv
import io
import os

app = Flask(__name__)

load_dotenv()

TOKEN = os.getenv('TELE_TOKEN')
GCP_VISION_CRED = os.getenv('GCP_VISION_CRED')
bot = Bot(token=TOKEN)
dispatcher = Dispatcher(bot, None, workers=1)
client = vision.ImageAnnotatorClient.from_service_account_file(GCP_VISION_CRED)

## webhook to connect bot to Telegram server
@app.route('/webhook', methods=['POST'])
def webhook():
   update = Update.de_json(request.get_json(), bot)
   dispatcher.process_update(update)
   return 'OK'


def start(update: Update, context: CallbackContext):
    update.message.reply_text("Hello, I am your game master. Send me a photo and I will check if you can progress to the next stage.")

def handle_photo(update: Update, context: CallbackContext):
    try:
        ## Get the user's photo
        photo_file = update.message.photo[-1].get_file()
        user_image = photo_file.download('user_photo.jpg')

        ## if user's photo is saved successfully, send a confirmation message
        update.message.reply_text("Photo received. Analyzing...")

        with io.open(user_image, 'rb') as image_file:
            content = image_file.read()

            image = vision.Image(content=content)
            response = client.label_detection(image=image)
            labels = response.label_annotations

            expected_label_score = ('Animation', 0.75) ## criteria for assessment

            match_found = False

            ## Compare each label generated from Cloud Vision against the criteria
            for label in labels:
                if label.description == expected_label_score[0] and label.score >= expected_label_score[1]:
                    match_found = True
                    update.message.reply_text(f"there is a match!")
                    break

            if not match_found:
                update.message.reply_text("No match found. Try again!")


    except Exception as e:
        print(f"failed to process photo: {e}")
        update.message.reply_text(f"An error occurred while processing your photo")

dispatcher.add_handler(CommandHandler("start", start))
dispatcher.add_handler(MessageHandler(Filters.photo, handle_photo))

if __name__ == '__main__':
    app.run(port=5000, debug=True)

Run the application

Start the bot

python app.py

Open another tab in VScode and use Ngrok to expose our local server on Internet for testing purposes.

ngrok http 5000

A Ngrok url will be created. Note the url will change when session is terminated

Set Telegram webhook for Telegram to notify the bot when users interact with it. Insert your bot token and the Ngrok URL

curl "https://api.telegram.org/bot{YOUR_TOKEN}/setWebhook?url={NGROK_URL}/webhook"

Testing Telegram Chatbot

The chatbot worked as expected. :)

Conclusion

Definitely, more features can be included to enhance the game experience. Experimentation through building games or a product relatable to an individual is required to build basics or foundations of a programming language like Python which have its used case in other fields from AI to data science.

References

https://www.restack.io/p/best-telegram-bot-frameworks-ai-answer-building-telegram-bots-flask-cat-ai

Python Telegram Chatbot with Google Cloud Vision API