Telegram Listener

The Telegram Listener application listens for new messages from specified Telegram channels or chats and processes user data by syncing it with an Airtable database. It can also upload user avatars to Cloudinary if available. This tool is useful for tracking sales intents, signals, or any other actionable events from Telegram.

---

Features

• Connects to Telegram using your account credentials (API ID, API Hash, and session string).
• Listens for new messages in specified chats.
• Extracts user information from messages and syncs it with Airtable.
• Uploads user avatars to Cloudinary and stores the URL in Airtable.
• Dockerized for easy deployment.

---

Prerequisites

• Node.js (v18 or higher recommended)
• Yarn (or npm)
• Telegram API credentials: Get your API ID and Hash
• Airtable account and API key: Airtable API
• Cloudinary account for image uploads: Cloudinary
• (Optional) Docker for containerized deployment

---

Getting Started

1. Clone the Repository

git clone git@github.com:incodellc/telegram-listener.git
cd telegram-listener

2. Install Dependencies

yarn install
# or
npm install

3. Configure Environment Variables

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

API_ID=your_telegram_api_id
API_HASH=your_telegram_api_hash
API_SESSION=your_telegram_session_string # Leave empty on first run
AIRTABLE_API_KEY_TOKEN=your_airtable_api_key
AIRTABLE_BASE_ID=your_airtable_base_id
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret

• On the first run, leave API_SESSION empty. The app will prompt you to log in and generate a session string.

4. Run the Application

yarn start:prod
# or
npm run start:prod

• You will be prompted for your Telegram phone number, password (if 2FA is enabled), and the login code sent to your Telegram app.
• After successful login, the session string will be saved for future runs.

5. (Optional) Run with Docker

Build and run the container:

docker-compose up --build

---

Project Structure

• index.js — Main entry point, handles Telegram connection and message listening.
• users.js — Handles user lookup, Airtable sync, and avatar upload to Cloudinary.
• docker/ — Dockerfile for building the app container.
• .env — Environment variables (not committed to git).
• package.json — Project dependencies and scripts.

---

Customization

• Listening to Chats: Edit the chats array in index.js to specify which chat IDs to listen to.
• Airtable Schema: Ensure your Airtable base has a Users table with fields matching those referenced in users.js.

---

Troubleshooting

• Session Issues: If you have trouble logging in, delete the API_SESSION value in .env and restart the app to re-authenticate.
• Airtable/Cloudinary Errors: Double-check your API keys and base IDs.
• Docker Issues: Ensure your .env file is present and correct before building the container.

---

License

MIT

---

Author

Oleg Meleshko qu1ze34@gmail.com