Gmail-n-Calendar-Bot

A Telegram bot that helps users manage email and coordinate calendars - all through conversational AI.

---

[!IMPORTANT]
Handle Your Data Responsibly: This bot interacts with your personal Gmail and Google Calendar data.
Ensure your API keys and tokens are kept secure and that you understand the permissions granted to the bot.
The developers are not responsible for any data mismanagement if you modify, self-host, or misuse the bot.

---

✨ Features

• Gmail Integration: List, read, send, and organize emails
  Send emails with proper formatting
  Apply labels for organization
  Search through your inbox
• Google Calendar Integration: List upcoming events
  Create and update calendar events
  Find available time slots
  Schedule meetings with proper time management
• Email-Calendar Coordination: Process emails for meeting requests
  Schedule calendar events from email content
  Send confirmation emails for scheduled events
  Help manage meeting-related correspondence

---

🌐 Mastra Framework for Agents

This project uses the Mastra framework for building and orchestrating AI agents.
Mastra provides a robust foundation for designing, managing, and scaling conversational and tool-using agents, making it ideal for complex digital assistant applications like this one.

---

🚀 Setup

Important: This bot requires API access to Google services (Gmail, Calendar) and a Telegram Bot Token.
Ensure you have google-credentials.json (or have completed the manual Google API setup) and the TELEGRAM_BOT_TOKEN in your .env file. These are crucial for the bot to function.

Prerequisites

• Node.js (v16+)
• npm or pnpm
• Google account for API access
• Telegram bot token (from BotFather)

Installation

1. Clone the repository:
   git clone https://github.com/boxed-dev/Gmail-n-Calendar-Bot.git cd Gmail-n-Calendar-Bot
2. Install dependencies:
   npm install or pnpm install
3. Set up Google API access:
   npm run setup-google-apis or pnpm run setup-google-apis
   This will guide you through the process of setting up Google API credentials for Gmail and Calendar access.
4. Create a .env file in the project root with your Telegram bot token:
   TELEGRAM_BOT_TOKEN=your_telegram_bot_token_from_botfather
5. Start the development server:
   npm run dev or pnpm run dev

Google API Setup (Manual)

If the automatic setup script (npm run setup-google-apis or pnpm run setup-google-apis) doesn't work for you, follow these steps:

1. Go to the Google Cloud Console.
   
2. Create a new project or select an existing one.
   
3. Navigate to APIs & Services > Library.
   
4. Enable the Gmail API and Google Calendar API.
   
5. Go to APIs & Services > Credentials.
   
6. Create OAuth 2.0 credentials (select "Desktop application" type).
   
7. Download the JSON file and save it as google-credentials.json in the project root directory.

---

🛠️ Usage

Telegram Bot Commands

The bot supports the following commands:

• /start - Initialize the bot and see available agents
  
• /gmail - Switch to the Gmail management agent
  
• /calendar - Switch to the Google Calendar management agent
  
• /assistant - Switch to the combined Email-Calendar assistant
  
• /help - Display help information

Examples

Here are some examples of what you can do with the bot:

Gmail

• "Show me my recent emails"
  
• "Do I have any unread emails from [person]?"
  
• "Send an email to [email address] about [topic]"
  
• "Read email with subject [subject]"
  

Calendar

• "What meetings do I have today?"
  
• "Schedule a meeting with [person] tomorrow at 2pm"
  
• "Find available slots for a 30-minute meeting this week"
  
• "Update my 2pm meeting to include [new details]"
  

Email-Calendar Coordination

• "Check my emails for meeting requests and schedule them"
  
• "Send a confirmation email for my meeting with [person]"
  
• "Find a good time for a meeting with [person] and send them an invitation"
  

---

🏗️ Architecture

The application is built using:

• Mastra.ai framework for agent design and orchestration
  
• Google API libraries for Gmail and Calendar access
  
• Node Telegram Bot API for messaging
  
• TypeScript for type safety
  

The bot features multiple specialized agents:

• Gmail Agent - For email management
  
• Calendar Agent - For calendar management
  
• Email-Calendar Agent - For coordinated tasks between email and calendar
  

Each agent has its own memory system to maintain context across conversations.

---

🔍 Troubleshooting

If you encounter issues with the Google API integration:

• Ensure that both Gmail API and Google Calendar API are enabled in your Google Cloud project.
  
• Check that you've completed the OAuth flow with the correct scopes (usually requested during setup-google-apis or manual setup).
  
• Verify that google-credentials.json (for API client info) and user-tokens.json (for user OAuth tokens, usually generated after first auth) exist in your project root.
  
• Try running the setup script again: npm run setup-google-apis or pnpm run setup-google-apis.
  

---

💬 Feedback & Contributions

We'd love to hear your thoughts! If you encounter any issues, have suggestions for improvement, or want to contribute:

• Please open an issue on the GitHub repository.
  
• For contributions, feel free to fork the repository and submit a pull request.
  

Your feedback and contributions are invaluable! 💌

---

License

This project is licensed under the MIT License - see the LICENSE file for details.