DEV Community

Cover image for Build a Personal Vocab-Boosting Telegram Bot with Gemini
Utkarsh Dhiman
Utkarsh Dhiman

Posted on

Build a Personal Vocab-Boosting Telegram Bot with Gemini

#javascript #ai #telegram #tutorial

Ever come across a word like serendipity or valiancy and thought, "I should write that down," only to completely forget about it five minutes later?

Yeah, me too.

Instead of carrying around a leather notebook like a 19th-century poet, let's build a private Telegram bot that does the heavy lifting for us. You send it a raw word or phrase, it runs it through Google’s lightning-fast Gemini 2.5 Flash model, and spits back a beautifully formatted dictionary card with the definition, synonyms, a custom mnemonic device, and an example sentence. Plus, you get a complete journal in Google Sheets (which we'll cover in the next blog post!).

Working example of telegram bot

Best part? It’s completely free, requires zero server maintenance, and takes about 15 minutes.

Here is the high-level blueprint of what we're building today:

       ┌───────────┐
       │ Your Phone│
       └─────┬─────┘
             │
             │ 1. Send word (e.g., "Serendipity")
             ▼
   ┌───────────────────┐
   │  Telegram Bot     │
   └─────────┬─────────┘
             │
             │ 2. Webhook HTTPS POST
             ▼
┌─────────────────────────┐
│ Google Apps Script (GAS)│ ◄─── Check: Is CHAT_ID == Owner?
└────────────┬────────────┘
             │
             │ 3. Forward prompt with strict JSON schema
             ▼
     ┌───────────────┐
     │  Gemini AI    │  (gemini-2.5-flash)
     └───────┬───────┘
             │
             │ 4. Return clean, structured JSON object
             ▼
┌─────────────────────────┐
│ Google Apps Script (GAS)│
└────────────┬────────────┘
             │
             │ 5. Parse JSON & format beautiful HTML template
             ▼
   ┌───────────────────┐
   │  Telegram Bot     │
   └─────────┬─────────┘
             │
             │ 6. Drop study card in your chat box!
             ▼
       ┌───────────┐
       │ Your Phone│
       └───────────┘
Enter fullscreen mode Exit fullscreen mode

The Secret Sauce: Demystifying Apps Script as a Free Cloud Function Engine

Normally, building an automation backend or conversational bot means provisioning an AWS EC2 instance, setting up a Node.js Express server, managing API gateways, and worrying about environment configurations. If you look into traditional serverless infrastructure like AWS Lambda or GCP Cloud Functions, you still have to deal with deployment pipelines, IAM roles, and credit card billing setups.

We aren't doing any of that.
We don't do that here

Instead, we are leveraging Google Apps Script (GAS). Most people think Apps Script is just for writing macro shortcuts inside Google Sheets, but it is actually a fully-fledged, serverless Cloud Function runtime hidden in plain sight.

When we deploy code as a Web App in GAS, Google instantly handles the deployment pipeline, provisions a public HTTPS endpoint, opens up a security layer, and listens for webhooks out of the box. Telegram pings our Apps Script cloud endpoint via a webhook, Google wakes our script up to process the incoming payload, and then it turns it back off. Total infrastructure cost: $0.00.

Let’s dive into the setup.

Step 1: Secure Your API Tokens (The Setup Phase)

Before writing any code, we need our digital access keys. We need to collect exactly three things: a Telegram bot token, your private user ID, and a Google Gemini API key.

A. Create Your Bot via BotFather

  1. Click this link to open the official Telegram bot manager: telegram.me/BotFather.
  2. Send the message /newbot to start the setup.
  3. Give your bot a friendly display name (e.g., My Vocab Journal Bot).
  4. Give your bot a unique username ending in the word bot (e.g., my_vocab_helper_bot).
  5. Copy the long HTTP API token string it gives you. Keep this secret!

B. Extract Your Private Chat ID

Because we don't want strangers using our cloud bot server and burning our free AI credits, we need to lock the application down to your personal account profile.

  1. Click this link to chat with a simple ID extractor bot: telegram.me/userinfobot.
  2. Press Start.
  3. Copy the numeric Id string it prints out immediately (e.g., 123456789). This is your unique CHAT_ID.

C. Create a Free Gemini API Key

  1. Head over to the Google AI Studio Console.
  2. Log in with your standard Google account.
  3. Click the prominent Get API Key button.
  4. Click Create API Key, select your project container, and copy the generated alphanumeric key string.

Step 2: Setting up the Google Apps Script Space

  1. Head over to script.google.com and click New Project.
  2. Rename the project to something descriptive, like Gemini Vocab Bot.
  3. Before dropping code files in, click on the gear icon (Project Settings) on the left sidebar menu drawer.

Screenshot highlighting the gear icon on the left navigation panel for Project Settings inside Google Apps Script

  1. Scroll all the way down to the bottom section titled Script Properties. This is Google's built-in secure vault for storing your private environment variables.
  2. Click Add script property three times and save these exact key-value pairs:
  3. TELEGRAM_BOT_TOKEN ➔ (Your copied Telegram token)
  4. GOOGLE_API_KEY ➔ (Your copied Gemini API key)

  5. CHAT_ID ➔ (Your numeric private Chat ID string)

  6. Click Save script properties.

Step 3: Getting the Code

We want to keep this architecture simple and modular. On the left sidebar menu, click the Editor icon (the <> symbol). You will see a single file named Code.gs. Rename it to main.gs.

Then, create two more files by clicking the + icon next to Files, choosing Script, and naming them gemini and telegram.

Visual highlighting the small '+' plus icon button next to the Files sidebar heading to create clean script tabs

All three files are available in this GitHub Gist.
From this embedded Gist copy the logic into your workspace files matching each filename:

  • Copy gemini.gs to enforce a strict structured output schema so Gemini's responses never break your layouts.
  • Copy telegram.gs to drive raw HTML text formatting delivery frames directly into chat panels.
  • Copy main.gs to act as the primary webhook controller, verifying security gates and organizing traffic patterns.

Step 4: Hooking It Up to Telegram (Deploy & Webhook)

Now for the final step: publishing your code as a live microservice and telling Telegram where to forward incoming chat messages.

A. Deploying the Script Web App

  1. Click the blue Deploy button in the top right corner, then select New Deployment.
  2. Click the gear icon next to "Select type" and choose Web App.
  3. Fill out the deployment configuration fields:
  4. Execute as: Select Me (your email address).

  5. Who has access: Select strictly Anyone. (Telegram needs public webhook access to safely hit this API).

  6. Click Deploy.

B. Bypassing the Developer Security Warning Screen

Because our custom script interacts with external networks (Telegram and Gemini), Google prompts a standard safety check sequence since it is an unverified independent development workspace. Don't worry—this is expected behaviour for your custom tools.

Screenshot pointing out the small gray 'Advanced' link at the bottom left text block of the Google login security screen

  1. When the authorization window prompts you, click Review Permissions and select your active email profile.
  2. On the screen that reads "Google hasn’t verified this app", click the tiny gray Advanced text link located at the bottom left.
  3. Click the sub-link that appears below it: Go to Gemini Vocab Bot (unsafe).
  4. Click Allow to finalize your live environment.
  5. Copy the long production Web App URL it generates (it will end in /exec).

C. Binding the Telegram Webhook

To hook your bot up to this new endpoint, open a fresh tab in your web browser, paste this URL format into your address bar (replacing the bracketed placeholders with your real values):

https://api.telegram.org/bot<YOUR_TELEGRAM_BOT_TOKEN>/setWebhook?url=<YOUR_APPS_SCRIPT_WEB_APP_URL>
Enter fullscreen mode Exit fullscreen mode

Make sure your URL doesn't contain any spaces or placeholder symbols. Your URL should look like: https://api.telegram.org/bot823499087:AAH_n4XxMg5LsdQ6XwGIrGDGf-4ryee7Haw/setWebhook?url=https://script.google.com/macros/s/AKfoyAJHafe28QP3iqV9-XjhQbnsiouf7243lonTItn_eXTlcxdfJofyUOkXxN_mKfefh12XjT2yKdBmEK/exec

Press Enter

If your screen returns a success message confirming {"ok":true,"result":true,"description":"Webhook was set"}, your cloud microservice is officially linked!

Try It Out!

Open up Telegram, pull up your brand new personal bot thread, and send it a word like unprecedented. Within a couple of seconds, you’ll get a perfectly structured, beautifully formatted study card delivered right to your pocket!

Stay tuned—in the next post, I'll show you how to expand this serverless architecture by automatically caching lookups to save AI tokens, and mapping these words into a permanent, beautiful database using Google Sheets.

Drop a comment below if your bot is live! 🚀

Top comments (0)