Calendar Assistant

Telegram bot that organizes events by checking your Google Calendar availability and coordinating with participants via WhatsApp.

How it works

1. You send a message describing the event (e.g. "Lunch with Marco on Friday")
2. The bot checks your Google Calendar for free slots
3. It contacts participants on WhatsApp asking for availability
4. If someone is unavailable, it proposes a new slot (max 3 attempts)
5. Once everyone agrees, the event is confirmed on Google Calendar

Stack

• Node.js + TypeScript
• Telegraf — Telegram bot
• whatsapp-web.js — WhatsApp messaging
• Google Calendar API — availability check and event creation
• OpenAI / Anthropic Claude — natural language parsing

Setup

1. Install dependencies

npm install

2. Configure environment variables

cp .env.example .env

Fill in .env with your credentials (see below).

3. Get Google OAuth refresh token

npm run setup:google

Open the URL shown in the terminal, authorize the app, and copy the GOOGLE_REFRESH_TOKEN into .env.

4. Start the bot

npm run dev

On first run, a QR code will appear in the terminal. Scan it with WhatsApp (Settings → Linked Devices → Link a Device).

5. Verify connections

Send /ping to your Telegram bot to check that all services are connected.

Environment variables

Variable	Description
TELEGRAM_BOT_TOKEN	From @BotFather
TELEGRAM_USER_ID	Your Telegram user ID (use @userinfobot)
LLM_PROVIDER	openai or claude
OPENAI_API_KEY	From platform.openai.com
OPENAI_MODEL	Default: gpt-4o
ANTHROPIC_API_KEY	From console.anthropic.com
ANTHROPIC_MODEL	Default: claude-3-5-sonnet-20241022
GOOGLE_CLIENT_ID	From Google Cloud Console (Calendar API enabled)
GOOGLE_CLIENT_SECRET	From Google Cloud Console
GOOGLE_REDIRECT_URI	http://localhost:3000/oauth2callback
GOOGLE_REFRESH_TOKEN	Generated via npm run setup:google
GOOGLE_CALENDAR_ID	primary or a specific calendar ID
WHATSAPP_SESSION_PATH	Path to store WhatsApp session (default: ./.wwebjs_auth)

Telegram commands

Command	Description
/start	Welcome message with usage examples
/help	How the bot works
/ping	Check status of all connected services

Security

Only the Telegram user matching TELEGRAM_USER_ID can interact with the bot. All other users are silently ignored and logged.

Notes

• WhatsApp session is persisted locally — no need to scan the QR code on every restart
• Scheduling sessions are stored in memory — restarting the bot will lose pending sessions
• Max 3 slot proposals per event before giving up