A full-stack application that integrates a Telegram bot with Plaid’s banking API, allowing users to securely connect their bank accounts and view financial information directly through Telegram.
Unlike traditional web apps, this bot uses Telegram as the entire user interface:
/balance or /transactionsThe flow: User's Telegram App → Your Bot → Express API → PostgreSQL + Plaid → Bank Data
📘 For complete deployment instructions, see DEPLOYMENT.md
Before you begin, ensure you have the following installed:
git clone https://github.com/yourusername/telegram-plaid-bot.git
cd telegram-plaid-bot
npm install
Copy the example environment file and configure it:
cp .env.example .env
Edit .env with your credentials:
# Telegram Bot Token (get from @BotFather)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# Plaid Credentials (from Plaid Dashboard)
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret
PLAID_ENV=sandbox # Use 'sandbox' for testing, 'production' for live
# Database Connection
DATABASE_URL=postgresql://user:password@localhost:5432/telegram_plaid
# Server Configuration
PORT=3000
API_BASE_URL=http://localhost:3000
# Security (IMPORTANT: Change these!)
ENCRYPTION_KEY=your_32_character_encryption_key_here
JWT_SECRET=your_jwt_secret_here
# Logging
LOG_LEVEL=info
Important Security Notes:
ENCRYPTION_KEY must be exactly 32 characters.env file to version controlCreate the database:
createdb telegram_plaid
Initialize the schema:
npm run init-db
docker-compose up -d db
The database will be automatically initialized with the schema.
npm run dev
This uses nodemon for automatic reloading on file changes.
npm start
Build and run everything with Docker Compose:
docker-compose up -d
Stop the application:
docker-compose down
View logs:
docker-compose logs -f app
| Command | Description |
|---|---|
/start |
Welcome message and initialization |
/link |
Connect your bank account via Plaid |
/balance |
View all connected account balances |
/transactions |
View recent transactions (last 30 days) |
/help |
Display help information |
The bot also provides interactive buttons:
/link/balance/transactions/helpPOST /api/plaid/create-link-token
Content-Type: application/json
{
"telegram_id": 123456789
}
Response:
{
"success": true,
"link_token": "link-sandbox-xxx",
"expiration": "2024-01-01T12:00:00Z"
}
POST /api/plaid/exchange-token
Content-Type: application/json
{
"public_token": "public-sandbox-xxx",
"telegram_id": 123456789
}
Response:
{
"success": true,
"institution_name": "Chase"
}
GET /api/plaid/accounts/:telegram_id
Response:
{
"success": true,
"accounts": [
{
"name": "Plaid Checking",
"balance": 100.00,
"available": 95.00,
"type": "depository",
"subtype": "checking",
"institution": "Chase"
}
]
}
GET /api/plaid/transactions/:telegram_id?start_date=2024-01-01&end_date=2024-01-31
Response:
{
"success": true,
"transactions": [
{
"transaction_id": "xxx",
"name": "Uber",
"amount": 12.50,
"date": "2024-01-15",
"category": ["Transportation"],
"pending": false,
"institution": "Chase"
}
]
}
POST /api/webhook/plaid
Content-Type: application/json
{
"webhook_type": "TRANSACTIONS",
"webhook_code": "DEFAULT_UPDATE",
"item_id": "xxx"
}
Response:
{
"received": true
}
GET /health
Response:
{
"status": "ok",
"timestamp": "2024-01-01T12:00:00.000Z"
}
Plaid provides a sandbox environment for testing without real bank connections.
When using Plaid Link in sandbox mode:
user_goodpass_good1234 (if prompted)/start/link to get a link token/balance to view connected accounts/transactions to see transaction historytelegram-plaid-bot/
├── src/
│ ├── bot/ # Telegram bot
│ │ ├── index.js # Bot initialization
│ │ ├── commands/ # Command handlers
│ │ │ ├── start.js
│ │ │ ├── link.js
│ │ │ ├── balance.js
│ │ │ ├── transactions.js
│ │ │ └── help.js
│ │ └── middleware/ # Bot middleware
│ │ └── auth.js
│ ├── api/ # Express API
│ │ ├── server.js # Server setup
│ │ ├── routes/ # Route definitions
│ │ │ ├── plaid.js
│ │ │ └── webhook.js
│ │ └── controllers/ # Request handlers
│ │ ├── plaidController.js
│ │ └── webhookController.js
│ ├── services/ # Business logic
│ │ ├── plaidService.js # Plaid API wrapper
│ │ ├── userService.js # User operations
│ │ └── encryptionService.js # Token encryption
│ ├── models/ # Data models
│ │ ├── User.js
│ │ └── PlaidConnection.js
│ ├── database/ # Database setup
│ │ ├── connection.js # DB connection pool
│ │ ├── init.sql # Schema definition
│ │ └── init.js # Initialization script
│ ├── config/ # Configuration
│ │ └── index.js
│ ├── utils/ # Utilities
│ │ ├── logger.js # Winston logger
│ │ └── errorHandler.js # Error handling
│ └── index.js # Application entry point
├── .env.example # Environment template
├── .gitignore
├── package.json
├── Dockerfile
├── docker-compose.yml
├── DEPLOYMENT.md # Complete deployment guide
└── README.md
This application can be deployed to various platforms. The Telegram bot serves as your GUI - no frontend deployment needed!
heroku create my-telegram-bot
heroku addons:create heroku-postgresql:mini
git push heroku main
pm2 start src/index.jsdocker-compose up -d
.env.example and fill in your credentialsnpm run init-db📘 For detailed deployment instructions (cloud, VPS, Docker, monitoring), see DEPLOYMENT.md
.env excluded from version controlTELEGRAM_BOT_TOKEN is correctdocker-compose ps or check processdocker-compose logs app or tail -f combined.logDATABASE_URL is correctpsql -lnpm run init-dbPLAID_CLIENT_ID and PLAID_SECRETPLAID_ENV matches your credentials (sandbox/production)ENCRYPTION_KEY must be exactly 32 charactersnode -e "console.log(crypto.randomBytes(16).toString('hex'))"src/api/server.js if neededCheck application logs:
# Combined logs
tail -f combined.log
# Error logs only
tail -f error.log
# Docker logs
docker-compose logs -f app
Contributions are welcome! Please follow these steps:
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
For issues and questions:
This bot handles sensitive financial information. Always:
Happy Banking! 🏦