https://github.com/abhay-100/evnt
A tool to automate event management by creating groups and adding members via Telegram, simplifying administrative tasks.
https://github.com/abhay-100/evnt
event-management hackathon-project mtproto nextjs open-source saturdayhacknight telegram
Last synced: 7 months ago
JSON representation
A tool to automate event management by creating groups and adding members via Telegram, simplifying administrative tasks.
- Host: GitHub
- URL: https://github.com/abhay-100/evnt
- Owner: ABHAY-100
- License: mit
- Created: 2024-10-03T16:12:34.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-03T15:35:22.000Z (over 1 year ago)
- Last Synced: 2025-04-14T01:44:41.130Z (11 months ago)
- Topics: event-management, hackathon-project, mtproto, nextjs, open-source, saturdayhacknight, telegram
- Language: TypeScript
- Homepage:
- Size: 863 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# evnt.
## Overview
**evnt.** is a robust tool for automating event management, designed to simplify organizing events across different industries. By automating tasks such as creating groups and adding members,
**evnt.** enables organizers to concentrate on crafting impactful experiences instead of handling time-consuming administrative tasks.
## Preview
## Problem Statement
Organizing events like hackathons, coding contests, and workshops often requires manual participant management, such as group creation and adding members. This process is time-consuming, especially for college-hosted or small-scale events with limited resources. A streamlined, automated solution is crucial to reduce administrative effort and enhance efficiency.
**evnt.** simplifies this process by automating group creation and participant management.
## Key Features
1. **Free and Open Source**: Ideal for small-scale events, this free, open-source tool streamlines group management and participant addition, providing a cost-effective alternative to complex, expensive platforms. Customize the source code to develop solutions tailored to your unique requirements.
2. **Enhanced Privacy**: Clone and run locally for full data control and enhanced privacy.
3. **Streamlined Participant Addition**: Automatically import participant data from CSVs and add to Telegram groups, minimizing errors and streamlining onboarding.
4. **User-Friendly Interface**: A clean and intuitive interface that allows users to navigate the application with ease, making event management straightforward and efficient.
## Team Members
1. [Abhay Balakrishnan](https://github.com/ABHAY-100)
2. [Aadithya Madhav](https://github.com/aadithyayy)
3. [Elvin J Alapatt](https://github.com/Elvin2605)
4. [Joshua Sebi](https://github.com/JoshuaSebi)
## Challenges Faced
During the 15-hour hackathon, we encountered two major challenges:
- **WhatsApp API Limitations**: Accessing the API was complex and risky, with unauthorized methods leading to potential bans.
- **Switch to Telegram**: By using Telegram's official API and MTProto protocol, we unlocked full user-level capabilities, overcoming the limitations of regular bots.
This transition ensured security, flexibility, and respect for user privacy.
## Getting Started
Follow these steps to set up evnt. locally:
### Prerequisites
Ensure you have the following installed:
- Node.js (v16 or higher)
- npm
### Installation
1. Clone the Repository
```bash
git clone https://github.com/ABHAY-100/evnt.git
```
2. Navigate to the Project Directory
```bash
cd evnt
```
3. Install Dependencies
```bash
npm install
```
4. Set Up Environment Variables
- Locate the `.env.example` file in the root of the project.
- Create a new file named `.env` or `.env.local` in the root directory.
- Copy and paste the contents of `.env.example` into the newly created `.env` file.
### Configure Telegram API
5. Access Telegram Developer Tools
- Open [my.telegram.org](https://my.telegram.org) and log in with your phone number.
- After logging in, click on **API Development Tools**.
6. Create a New Application by filling out the form with an appropriate **App Title** and **Short Name**.
7. Retrieve API Credentials
- Once created, you will be shown a page with your **API_ID** and **API_HASH**.
- Copy these values and paste them into the `.env` file under their respective keys.
8. Add Telegram Phone Number in the `.env` file in international format as ```TELEGRAM_PHONE_NUMBER=+```
9. Generate `TELEGRAM_SESSION` and Update the Environment File
- Run the following command to generate the `TELEGRAM_SESSION` string
```bash
npx ts-node scripts/auth-telegram.ts
```
- Follow the instructions in the terminal to authenticate your Telegram account.
- Once the `TELEGRAM_SESSION` is generated, copy the output string.
- Open your `.env` file and add the `TELEGRAM_SESSION` key with the copied string
```bash
TELEGRAM_SESSION=
```
### Run the Application
10. Start the Application
```bash
npm run dev
```
11. Open your web browser and navigate to `http://localhost:3000` to access the app.
### How to Use?
12. Once the application is running, open it in your browser (`http://localhost:3000`), and you will see a form.
13. Select whether you want to create a group or channel using the switch option.
14. Enter the group/channel name and description in the corresponding fields.
15. Upload a CSV file containing participant data in the following format:
```bash
name, phone
johndoe, +91933222XXXX
janedoe, +91933852XXXX
```
15. If everything is configured correctly, the members will be added automatically. A success modal will appear with event statistics, and a CSV report (named `group/channelname-report.csv`) will be downloaded with a summary of the process.
## How It Works?
### Technical Implementation
The application utilizes Telegram's MTProto protocol via the `telegram` npm package, unlocking advanced capabilities beyond traditional bots. Here's a simplified breakdown:
1. Authentication & Setup
- Authenticates using Telegram’s MTProto API with API ID, API Hash, and phone number.
- Supports session persistence and handles two-factor authentication if enabled.
2. Group Creation
- Accepts a CSV file of participant details and validates phone numbers.
- Programmatically creates groups or channels, generates invite links.
3. Member Management
- Adds members by resolving phone numbers to Telegram accounts.
- Uses fallback methods like invite links or private messages for privacy-restricted users.
4. Operation Report
- Produces and downloads a detailed CSV report
## License
By contributing, you agree that your contributions will be licensed under the [MIT License](https://github.com/ABHAY-100/evnt/blob/main/LICENSE.md). See the LICENSE file for more details.
## Contributing to evnt.
Thank you for considering contributing to evnt.! Here’s how you can help make it even better.
### Reporting Issues
If you find a bug or have a suggestion, feel free to create an issue
1. Go to the [Issues tab](https://github.com/ABHAY-100/evnt/issues).
2. Click on New Issue.
3. Describe the issue or feature request clearly, and provide any relevant details or steps to reproduce.
### Contributing
We welcome any contributions! Here’s how you can contribute
1. Fork the repo and make your changes.
2. Open a pull request with a description of your changes.
3. We’ll review it and merge it!
### Code of Conduct
Please be respectful and constructive in your interactions. Let’s work together to improve evnt.!
## Built With
## Conclusion
**evnt.** is dedicated to revolutionizing the event management process for organizations or individuals by automating the process of adding the participants to groups. Our tool empowers event organizers to concentrate on creating impactful and memorable events while minimizing administrative challenges.
**Thank you for your interest in evnt.! 🤝**