Telegram Calendar Bot

בוט טלגרם שמכניס אירועים ליומן Google שלך מטקסט חופשי, הודעה קולית, או תמונה — באמצעות AI.

English · עברית

---

הסוף להאסל של גוגל קלנדר

קיבלת הודעה על יומולדת בגן של הילד? מסיבה בעבודה? רוצה להזכיר לעצמך לעשות משהו ביום שישי?

עכשיו זה קל — שלח הודעה לבוט, והאירוע נכנס ליומן.

פשוט תעשה פורוורד של ההודעה, תכתוב בשפה חופשית, תשלח הודעה קולית, או תשלח תמונה של הזמנה — והבוט ידאג להכל.

איך זה עובד?

אתה שולח: "פגישה עם דני מחר ב-15:00"
   ↓
הבוט מפענח עם AI → יוצר אירוע ביומן → מאשר בטלגרם ✅

מה הבוט יודע לעשות?

שלח לבוט	מה קורה
פגישה עם דני מחר ב-15:00	אירוע מחר 15:00-16:00
יומולדת של יואב ביום שישי ב-17:00 בפארק	אירוע ביום שישי הקרוב עם מיקום
תזכיר לי בעוד שעה לצלצל לרופא	אירוע בעוד שעה מעכשיו
Team sync Monday 10am	עובד גם באנגלית
🎤 הודעה קולית	מתמלל ויוצר אירוע
📸 תמונה של הזמנה / פלאייר	חולץ פרטים מהתמונה ויוצר אירוע

כל אירוע מגיע עם כפתור מחיקה למקרה שטעית.

---

מדריך התקנה

💡 טיפ: אם אתה עובד עם Cursor / Claude, אתה יכול פשוט להדביק את המדריך הזה ולבקש מה-AI לעשות את הצעדים בשבילך.

מה צריך מראש?

שירות	מה צריך	עלות
Cloudflare	חשבון + Workers	חינם
Telegram	בוט חדש	חינם
Google Cloud	פרויקט + Calendar API	חינם
OpenAI	מפתח API (ראה פירוט למטה)	~$0.001 לאירוע
Node.js 18+	מותקן מקומית	—

---

שלב 1: יצירת בוט טלגרם

📱 לחץ לפתיחת ההוראות

1. פתח טלגרם ושלח הודעה ל-@BotFather
2. שלח /newbot ועקוב אחרי ההוראות
3. שמור את ה-Bot Token (נראה ככה: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
4. שלח הודעה כלשהי לבוט החדש שלך, ואז גש ל:

   https://api.telegram.org/bot<TOKEN>/getUpdates
   

5. מצא את ה-Chat ID שלך בתשובה ("chat":{"id":123456789})

---

שלב 2: הגדרת OpenAI

🤖 לחץ לפתיחת ההוראות

1. גש ל-OpenAI Platform וצור מפתח API חדש
2. ודא שהמודלים הבאים זמינים בחשבון שלך:

מודל	שימוש	הערות
gpt-4o	פענוח טקסט, תמונות ו-vision	מודל אחד לכל המשימות
whisper-1	תמלול הודעות קוליות	נדרש רק אם שולחים הודעות קוליות

3. בדוק ב-Settings → Limits שיש לך גישה למודלים האלה
4. ודא שיש credit בחשבון — גם $5 מספיקים לחודשים של שימוש אישי

---

שלב 3: הגדרת Google Cloud

☁️ לחץ לפתיחת ההוראות

1. גש ל-Google Cloud Console וצור פרויקט חדש
2. הפעל את Google Calendar API:
   • APIs & Services → Library
   • חפש "Google Calendar API"
   • לחץ Enable
3. צור OAuth credentials:
   • APIs & Services → Credentials
   • Create Credentials → OAuth client ID
   • סוג: Web application
   • הוסף Redirect URI זמני (נעדכן אחרי הדיפלוי):

     https://example.com/oauth/callback
     

   • שמור את ה-Client ID וה-Client Secret
   • ⚠️ חשוב: אחרי שלב 3 (דיפלוי ל-Cloudflare), תחזור לכאן ותעדכן את ה-Redirect URI לכתובת האמיתית:

     https://telegram-calendar-bot.YOUR_SUBDOMAIN.workers.dev/oauth/callback
     

4. הגדר OAuth consent screen:
   • APIs & Services → OAuth consent screen
   • בחר External
   • הוסף את המייל שלך כ-Test user

---

שלב 4: התקנה ודיפלוי

🚀 לחץ לפתיחת ההוראות

# שכפל את הפרויקט
git clone https://github.com/ofershap/telegram-calendar-bot.git
cd telegram-calendar-bot

# התקן תלויות
npm install

# התחבר ל-Cloudflare
npx wrangler login

# צור KV namespace
npx wrangler kv namespace create KV
# ← העתק את ה-ID שמוחזר

צור קובץ wrangler.toml:

name = "telegram-calendar-bot"
main = "src/index.ts"
compatibility_date = "2025-12-01"

[[kv_namespaces]]
binding = "KV"
id = "YOUR_KV_NAMESPACE_ID"   # ← הדבק את ה-ID מלמעלה

הגדר את הסודות:

echo "BOT_TOKEN" | npx wrangler secret put TELEGRAM_BOT_TOKEN
echo "CHAT_ID" | npx wrangler secret put TELEGRAM_CHAT_ID
echo "OPENAI_KEY" | npx wrangler secret put OPENAI_API_KEY
echo "CLIENT_ID" | npx wrangler secret put GOOGLE_CLIENT_ID
echo "CLIENT_SECRET" | npx wrangler secret put GOOGLE_CLIENT_SECRET
echo "primary" | npx wrangler secret put GOOGLE_CALENDAR_ID
echo "https://telegram-calendar-bot.YOUR_SUBDOMAIN.workers.dev" | npx wrangler secret put WORKER_URL

דיפלוי:

npm run deploy

🔄 אחרי הדיפלוי: חזור ל-Google Cloud Console → Credentials → ה-OAuth Client שלך (שלב 3), ועדכן את ה-Redirect URI לכתובת האמיתית שקיבלת מ-Cloudflare:

https://telegram-calendar-bot.YOUR_SUBDOMAIN.workers.dev/oauth/callback

---

שלב 5: חיבור Webhook

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://telegram-calendar-bot.YOUR_SUBDOMAIN.workers.dev/webhook"}'

שלב 6: חיבור Google Calendar

שלח הודעה כלשהי לבוט — הוא ישלח לך לינק לחיבור חשבון Google. לחץ, אשר, וסיימת.

---

ארכיטקטורה

Telegram  →  Cloudflare Worker  →  OpenAI GPT-4o (טקסט + תמונות)  →  Google Calendar API
                                →  OpenAI Whisper (תמלול קולי)

רכיב	תפקיד
Hono	Web framework קליל
Cloudflare Workers	Serverless, אפס cold starts
Cloudflare KV	שמירת OAuth tokens
OpenAI GPT-4o	פענוח טקסט, חילוץ פרטים מתמונות (vision)
OpenAI Whisper	תמלול הודעות קוליות
Google Calendar API	יצירה ומחיקה של אירועים

מבנה הפרויקט

src/
├── index.ts       # נתיבי Hono (webhook, OAuth, status)
├── handlers.ts    # טיפול בהודעות ויצירת אירועים
├── ai.ts          # OpenAI — פענוח טקסט, תמונות + תמלול
├── prompts.ts     # System prompts לטקסט ותמונות
├── google.ts      # Google Calendar API + ניהול OAuth tokens
├── telegram.ts    # Telegram Bot API helpers
└── types.ts       # TypeScript interfaces
test/
├── image-prompt.ts          # בדיקת prompt לתמונות מול OpenAI
└── fixtures/                # תמונות לבדיקה

בדיקות

אפשר לבדוק את ה-prompt לתמונות מקומית מול OpenAI API:

export $(cat .dev.vars | xargs)
npx tsx test/image-prompt.ts      # הרצה בודדת
npx tsx test/image-prompt.ts 5    # 5 הרצות לבדיקת עקביות

הבדיקה שולחת תמונה אמיתית ל-GPT-4o ומוודאת שהתוצאה (כותרת, תאריך, שעה, מיקום) תואמת את הצפוי.

---

עלויות

שירות	עלות
Cloudflare Workers	חינם (100K בקשות/יום)
Cloudflare KV	חינם (100K קריאות/יום)
OpenAI GPT-4o	~₪0.01 לאירוע (טקסט), ~₪0.05 לתמונה
OpenAI Whisper	~₪0.02 לדקת קול
Google Calendar API	חינם

שימוש אישי עולה פחות מ-₪3 בחודש.

---

פיתוח מקומי

cp wrangler.example.toml wrangler.toml
# ערוך את wrangler.toml עם ה-KV ID שלך

צור קובץ .dev.vars:

TELEGRAM_BOT_TOKEN=your_token
TELEGRAM_CHAT_ID=your_chat_id
OPENAI_API_KEY=your_key
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_secret
GOOGLE_CALENDAR_ID=primary
WORKER_URL=https://your-worker.workers.dev

npm run dev

---

English

A Telegram bot that creates Google Calendar events from natural language messages, voice notes, and images — powered by AI. Runs on Cloudflare Workers.

Send a message like "Meeting with Dan tomorrow at 3pm", a voice note, or a photo of an invitation — and it instantly appears in your Google Calendar.

Quick Start

1. Clone — git clone https://github.com/ofershap/telegram-calendar-bot.git
2. Create a Telegram bot — Message @BotFather, get a token
3. Set up OpenAI — Get an API key, ensure gpt-4o and whisper-1 models are available
4. Set up Google Cloud — Create project, enable Calendar API, create OAuth credentials
5. Deploy to Cloudflare — npm install && npx wrangler login && npm run deploy
6. Set secrets — Use npx wrangler secret put for each env var
7. Register webhook — curl to Telegram's setWebhook endpoint
8. Connect Google — Send a message to the bot, click the auth link

See the Hebrew guide above for detailed step-by-step instructions.

Features

• Natural language — "Meeting tomorrow at 3pm", "Birthday party Friday at 5"
• Voice messages — Send a voice note, it gets transcribed and parsed
• Image parsing — Send a photo of an invitation/flyer, AI extracts the event details and attaches the image to the calendar event
• Relative time — "in an hour", "next Monday" — all work
• Multi-language — Hebrew, English, and more
• Delete from chat — Each event has a delete button
• Serverless — Cloudflare Workers free tier, zero cold starts

Testing

Test the image prompt locally against OpenAI API:

export $(cat .dev.vars | xargs)
npx tsx test/image-prompt.ts      # single run
npx tsx test/image-prompt.ts 5    # 5 runs for consistency

Environment Variables

Variable	Description
TELEGRAM_BOT_TOKEN	Bot token from BotFather
TELEGRAM_CHAT_ID	Your Telegram chat ID
OPENAI_API_KEY	OpenAI API key
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret
GOOGLE_CALENDAR_ID	Calendar ID (primary for main calendar)
WORKER_URL	Your deployed worker URL

---

Author

Ofer Shapira

License

MIT © Ofer Shapiria