CaliBOT 📅

CaliBOT is an intelligent Telegram bot that helps users manage their Google Calendar through natural language conversations. The bot leverages GPT-4o to understand user intents, process natural language requests, and perform calendar operations seamlessly.

Features

• 🗓️ Calendar Management: Create, update, delete, and query calendar events using conversational language
• 🤖 AI-Powered: Utilizes GPT-4o for natural language understanding and conversation management
• 🔄 Google Calendar Integration: Securely connects to users' Google Calendar accounts
• 💬 Contextual Conversations: Maintains conversation history to provide relevant responses
• 🧠 Intent Recognition: Automatically identifies calendar-related requests vs. small talk
• 🔐 Secure Authentication: OAuth 2.0 integration with Google Calendar API

Demo

https://github.com/user-attachments/assets/d65d8789-252c-4a87-9c47-10ba2ec6b0f1

System Design

Diagram below depicts the sytem design. However, database is not implemented yet.

Sequence Diagram

Getting Started

Prerequisites

• Python 3.10 or higher
• Google Cloud Platform account (for Calendar API access)
• Telegram Bot API token
• OpenAI API key

Installation

1. 1.Clone the repository:

git clone https://github.com/yourusername/calibot.git
cd calibot

1. 1.Install dependencies:

Make sure you have uv installed. See here for complete information.

uv pip install

1. 1.Set up environment variables:

Create a .env file in the root directory with the following variables:

TELEGRAM_API_TOKEN=your_telegram_token
OPENAI_API_KEY=your_openai_api_key
GOOGLE_CREDENTIALS_FILE=path_to_your_google_credentials.json

Setting up Google Calendar API

1. 1.Go to the Google Cloud Console
2. 2.Create a new project
3. 3.Enable the Google Calendar API
4. 4.Create OAuth 2.0 credentials (Web application type)
5. 5.Download the credentials JSON file and reference it in your .env file

Setting up Telegram Bot

1. 1.Create a new bot on Telegram using BotFather
2. 2.Get the API token and add it to your .env file

Usage

1. 1.Start the backend server:

python -m backend.app.main

1. 1.Set up a tunneling service like ngrok to expose your local server (required for Telegram webhook):

ngrok http 8060

1. 1.Update the backend_url in backend/app/main.py with your ngrok URL

1. 1.Chat with your bot on Telegram:

• Authenticate with Google when prompted
• Use natural language to manage your calendar events

Examples of Queries

• "Schedule a meeting with John tomorrow at 3pm"
• "What events do I have next Monday?"
• "Cancel my meeting with the design team"
• "Move my 2pm appointment to 4pm"
• "Schedule a doctor's appointment on March 15th at 10am for 1 hour"

Architecture

The application uses: