Documentation - HandyCalBot

Adding the App

Follow these steps to get started with HandyCalBot:

Step 1: Start the Bot

Open Telegram and search for @handycalbot, or click this link:

Open HandyCalBot

Click Start to begin interacting with the bot.

Step 2: Connect Your Google Calendar

To create meetings, you need to connect your Google Calendar:

/connect

The bot will send you an authorization link. Click it to:

Sign in to your Google Account
Review the permissions requested (calendar access)
Click "Allow" to authorize HandyCalBot
You'll be redirected back with a confirmation message

Tip: You can choose "Privacy Mode" during setup to limit calendar access. In Privacy Mode, the bot can only create events, not read your existing calendar.

Step 3: Set Your Timezone

After connecting, confirm or update your timezone:

/timezone

Select your timezone from the list or search for your city.

Step 4 (Optional): Connect Zoom

To add Zoom meeting links automatically to your calendar events:

/connectzoom

The bot will send you an authorization link to the Zoom App Marketplace
Sign in to your Zoom account
Review the permissions requested (meeting creation)
Click "Allow" to authorize HandyCalBot
You'll be redirected back with a confirmation message

Once connected, all new meetings created through the bot will automatically include a Zoom meeting link.

Tip: You can also install HandyCalBot directly from the Zoom App Marketplace and then link it to your Telegram account.

Troubleshooting Setup

If you run into issues during setup, check our Troubleshooting section below or visit the Support page for help.

Usage Guide

Creating Meetings (Inline Mode)

The primary way to create meetings is using Telegram's inline mode. In any chat, type:

@handycalbot 15:00 Team Standup

A dropdown will appear with your meeting. Select it to create the event.

Format examples:

@handycalbot 14:30 Project Review - Meeting at 2:30 PM today
@handycalbot tomorrow 10:00 Weekly Sync - Meeting tomorrow at 10 AM
@handycalbot 25.01 09:00 Monthly Planning - Meeting on January 25th
@handycalbot 2h Design Workshop - 2-hour meeting starting now

Bot Commands

Available commands you can use in the bot chat:

/start - Welcome message and getting started
/help - Show all available commands
/connect - Connect your Google Calendar
/connectzoom - Connect your Zoom account
/disconnect - Disconnect Google Calendar
/disconnectzoom - Disconnect Zoom account
/settings - View and change your settings
/timezone - Change your timezone
/meetings - View your upcoming meetings
/cancel - Cancel a meeting

Adding Attendees

After creating a meeting, you can add attendees by:

Email: Enter email addresses (e.g., john@example.com)
Telegram Username: Enter @username if they also use HandyCalBot

Attendees receive calendar invitations automatically via email.

Meeting Reminders

HandyCalBot sends you Telegram notifications before your meetings. Configure reminders in:

/settings

You can set custom reminder times (e.g., 15 minutes, 1 hour before).

Features

📅

Google Calendar Sync

Events are created directly in your Google Calendar with all details.

🎥

Zoom Integration

Automatically generate Zoom meeting links for your events.

👥

Attendee Invitations

Invite people by email or Telegram username.

🔔

Smart Reminders

Get notified via Telegram before your meetings start.

🌍

Multi-language Support

Available in 10 languages including English, German, Spanish, French, Russian, and more.

🔒

Privacy Mode

Opt for minimal permissions - create events without reading your calendar.

Prerequisites

A Telegram account
A Google Account with Google Calendar
(Optional) A Zoom account for video meeting links

Troubleshooting

Cannot connect Google Calendar

Make sure you're signed into the correct Google Account
Check that you clicked "Allow" on the permissions screen
Try disconnecting and reconnecting: /disconnect then /connect
Clear your browser cache and try again

Meetings not appearing in calendar

Verify your calendar is connected: /settings
Check your timezone is set correctly: /timezone
Make sure you selected the meeting from the inline dropdown

Not receiving reminders

Check that notifications are enabled in /settings
Make sure Telegram notifications are enabled on your device
Verify the meeting was created through HandyCalBot

Zoom link not being added

Ensure Zoom is connected: /connectzoom
Check that your Zoom account is active
Try disconnecting and reconnecting Zoom

Still having issues? Visit our Support page for more help options.

Removing the App

Disconnect Your Accounts

To disconnect HandyCalBot from your accounts:

1. Disconnect Google Calendar:

/disconnect

This removes the connection between HandyCalBot and your Google Calendar.

2. Disconnect Zoom (if connected):

/disconnectzoom

Revoke Access from Google

For complete removal, also revoke access from your Google Account:

Go to Google Account Permissions
Find "HandyCalBot" in the list of connected apps
Click on it and select "Remove Access"

Revoke Access from Zoom

To remove HandyCalBot from your Zoom account:

Go to Zoom App Marketplace - Installed Apps
Find "HandyCalBot" in the list of installed apps
Click on it and select "Uninstall"
Confirm the removal when prompted

What Happens When You De-authorize / Disconnect

Important - implications of removal:

OAuth tokens are deleted - Your Google and/or Zoom access tokens are immediately removed from our servers
No further access - We can no longer access your calendar, create events, or generate Zoom meeting links on your behalf
Existing events are preserved - Calendar events and Zoom meetings already created remain in your Google Calendar and Zoom account; they are NOT deleted
Preferences retained - Your user preferences (timezone, language, reminder settings) are kept in case you reconnect later
Reminders stop - You will no longer receive Telegram reminder notifications for upcoming meetings

How We Handle Your Data Upon Removal

When you disconnect or uninstall the app:

All stored OAuth tokens (Google and Zoom) are permanently deleted from our database
We do not retain any calendar content or Zoom meeting data after disconnection
Basic account data (Telegram user ID, timezone, settings) is retained to allow seamless reconnection

Complete Data Deletion

To request complete deletion of all your data, including preferences, meeting history, and any stored account information, contact us via:

Email: support@handycal.dzhurinskiy.com
GitHub: Open an issue

We will process your data deletion request within 30 days.

Stop Using the Bot

You can also simply stop the bot in Telegram:

Open the chat with @handycalbot
Tap the bot name at the top
Select "Stop Bot" or "Block User"

This prevents the bot from sending you messages, but doesn't disconnect your calendar or Zoom accounts. To fully remove access, follow the disconnection steps above.