This monorepo contains the source code for the DMe framework. It provides a solid foundation to easily build and deploy a Telegram bot notification system. It comes with an optimized message queue and dispatching system to ensure reliable delivery of notifications, a ready-to-use user onboarding component for React dApps that allows users to subscribe with a single click or QR scan, and a predefined set of commands for users to manage their subscribed wallets.
It is designed for anyone to clone or fork and use it as a starting point to build their own Telegram notification system, without worrying about the complexities of the underlying messaging system.
- Features
- Getting Started
- Example
- Project Structure
- Telegram Bot Commands
- Queuing Messages
- Subscribed Wallets
- Onboarding Modal Component
- Database
- Deployment
- Need Help?
| Feature | Description |
|---|---|
| Optimized Notifications | Reliable Telegram delivery out of the box. No complex setup required. |
| From Pull to Push | Trigger relevant, contextual messages based on wallet activity. Keep your users informed in real-time without them having to check your dashboard. |
| Telegram Bot | Prebuilt bot with wallet linkage and user controls. No need to build your own interface. |
| Telegram Mini App (Coming Soon) | Richer Telegram UI via a lightweight, integrated Telegram Mini App. |
| Onboarding Component | React component for instant onboarding. Users click a link or scan a QR. No wallet connection needed. |
| Zero Installs | No apps, no browser extensions. Everything runs through Telegram. |
| Easy Deployment | Runs as a single-node service. Self-host or deploy in your cloud infra. |
| White Label | Customize components with your own branding and front-end logic. |
| Data Flexibility | Compatible with SQLite, Postgres, MySQL, or MongoDB. Use your preferred stack. You own your user's data, eliminating exposure to third-party risks. |
| Built for Simplicity | Deliver what drives user engagement, retention, and re-activation. DMe handles delivery logic; you focus on wallet signals. |
| Attribution Dashboard (Coming Soon) | Track delivery, opens, and basic interaction metrics to measure messaging impact. |
| Open Source | This framework is fully open source. You can inspect, extend, and contribute to its codebase. It’s actively maintained and open to community feedback and contributions. |
To set up a Telegram notification system using the DMe framework, follow these steps:
Talk to @BotFather on Telegram to create a new bot and obtain your bot token.
Clone the DMe monorepo to your local machine:
git clone [email protected]:BootNodeDev/dme-monorepo.git && cd dme-monorepoInstall Node.js version 22.19.0. We recommend using nvm for Node.js version management:
nvm install 22.19.0
nvm use 22.19.0Install pnpm package manager:
npm install -g pnpmInstall the required dependencies using pnpm:
pnpm installcd packages/serverCopy the example environment file and update it with your bot token:
cp .env.example .envFill in the BOT_TOKEN value with the token you received from BotFather.
Other environment variables are optional and include sensible defaults for getting started.
The cleanup feature is configured via CLEANUP_CRON (default: daily at midnight) and CLEANUP_CUTOFF (default: 1 week retention).
Start the development server with:
pnpm devReplace {botname} in the link below with your bot's username (without the @ symbol) and open it in your browser:
https://t.me/{botname}?start=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
For example, if your bot name is @MyBot, use:
https://t.me/MyBot?start=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
Click Start in Telegram to begin the conversation with your bot.
You should receive a welcome message and a test message every 10 seconds from the SampleJob, confirming that everything is working correctly.
To customize behavior, open packages/server/src/index.ts and comment out or remove the SampleJob.
You can then create your own jobs to send custom notifications to users.
You can checkout to the example/uniswap branch to see a working example of the DMe framework used to notify Uniswap liquidity providers about their position status.
The example extends the base framework by adding three jobs that periodically make requests to the revert.finance API to fetch subscribed user position data and send notifications based on certain conditions:
This job checks if any of the user's Uniswap V3 liquidity positions are out of range (i.e., the current price is outside the position's tick range). If a position is found to be out of range, the user receives a notification alerting them of this status along with a link to the Uniswap interface to manage their position.
This job monitors the fees accrued in the user's Uniswap V3 liquidity positions. If the fees exceed a predefined threshold, the user is notified with a reminder to collect their earnings, along with a link to the Uniswap interface for easy access.
Sends a summary of the total values of the user's liquidity positions along with PnL information.
The example also demonstrates how commands can be customized—for instance, obtaining position data of a user that just subscribed to the bot and sending a welcome message with a summary of their current positions.
Note: The example is provided for educational purposes and may require further customization to fit specific use cases or production environments.
The monorepo is organized into the following packages:
packages/server: The main server application that runs the Telegram bot and handles user interactions, message dispatching, and job scheduling.packages/onboarding-modal: A React component that provides a user-friendly onboarding experience for linking Telegram accounts with their wallet addresses.
The server package is built with TypeScript and uses the grammy framework for Telegram bot interactions, Prisma for database management, and node-cron for scheduling jobs.
The file structure is organized as follows:
packages/
├── server/ # Main server application
│ └── src/
│ ├── prisma/ # Prisma schema and migrations
│ ├── scripts/ # Utility scripts. Includes a script to run integration tests
│ └── src/
│ ├── handlers/ # Telegram bot command handlers. Includes /start, /add, /remove, /list base commands
│ ├── jobs/ # Scheduled jobs for sending notifications. Includes the dispatch job in charge of sending messages from the queue, cleanup job for old messages, and a sample job
│ ├── services/ # Services used to abstract database and Telegram API interactions.
│ └── tests/ # Utility functions for testing
└── onboarding-modal/ # React component for user onboarding
├── lib/ # Components and styles that will be exported into the package
└── src/ # Example usage of the component
You can do whatever you want with the code in this monorepo. The current structure is just a suggestion to help you get started with a solid foundation for building your own Telegram notification system. Given that it is focused on solving user onboarding and message queue and dispatch for you.
Imagine that you want to send alerts to your users when their Aave positions are at risk of liquidation. You could rely on the existing onboarding and message dispatching system, and just add a new job that periodically checks your users' Aave positions using the Aave API. When a position is at risk (because the health factor is under 1.5, for example), you can use the MessageService to send a notification to the user, leveraging all the built-in features like rate limiting, retries, and markdown formatting.
In this case, you would add an aave.ts service to the services folder and a new health.ts job to the jobs folder that uses the Aave service to fetch user positions and build the message to be sent with the MessageService.create method, then instantiate them in the index.ts file.
The DMe framework includes a set of predefined commands that users can use to interact with the Telegram bot. These commands allow users to manage their subscriptions and get information about their linked wallets.
| Command | Description |
|---|---|
/start [address] |
Starts a conversation with the bot. If a wallet address is provided, it is linked to the user. |
/add <address> |
Links an additional wallet address to the user's Telegram account. |
/remove <index> |
Unlinks a wallet address from the user's Telegram account. The index is the number to the left of the address provided in /list. |
/list |
Lists all wallet addresses linked to the user's Telegram account. |
Keep in mind that you need to add these commands to your bot through BotFather manually for them to show up in the Telegram UI. If you don't, users can still use the commands, but they won't see them in the command list when they type / in the chat with your bot.
The MessageService is the main component you will be using to queue messages to users, ensuring reliable delivery with built-in rate limiting and retry logic. All messages should be created using the MessageService.create or MessageService.createForUser methods.
MessageService.create(content: string, address: string, options?: MessageOptions) Creates a message targeted for a certain wallet address. The message will be queued and delivered to all users that have linked that address. This should be used to send messages to users based on wallet activity.
MessageService.createForUser(content: string, userId: number, options?: MessageOptions) Creates a message targeted for a specific user. This should be used to send messages that are not related to wallet activity, such as welcome messages or responses to user commands.
MessageOptions include:
- priority: number - Sets the priority of the message. Higher priority messages are sent first. This allows you to prioritize certain messages over others. Default is 0 for create, and 1000 for createForUser. This is to ensure that command replies are sent before any other queued messages.
- maxAttempts: number - Sets the maximum number of attempts to send the message. Default is 5, this is configurable via the
MAX_ATTEMPTSenvironment variable.
Messages are formatted to support MarkdownV2 when queued. See the Telegram documentation for more details.
You probably want to get a list of all subscribed wallets in order to check their activity and send notifications accordingly. You can use the WalletService for this purpose.
WalletService.listAll(options?: { take?: number; skip?: number }) Returns a list of all unique wallet addresses that have been linked by users. You can use the take and skip options for pagination.
Using pagination is important if you have a large number of subscribed wallets, as it allows you to process them in batches and avoid overwhelming your system.
The message queue is prepared to handle a large number of messages, but if you want to keep your instance running smoothly, it's a good idea to process wallets in chunks.
The framework includes a React component that can be integrated into your React dApp to facilitate user onboarding. This component consists of a button that, when clicked, opens a modal dialog. The modal displays a QR code that the user can scan with their phone to easily start a conversation with the Telegram bot and link their wallet address for notifications in a single action. The modal also provides a link as an alternative to open Telegram directly in the browser.
pnpm install @bootnodedev/dme-onboarding-modalimport "@bootnodedev/dme-onboarding-modal/lib/index.css";import { Button } from "@bootnodedev/dme-onboarding-modal";
function Navbar() {
return (
<nav>
<Button
modal={{
bot: "MyBot",
address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
title: "Stay Updated",
description:
"Scan the QR code or click the button below to get started.",
cta: "Open Telegram",
}}
/>
</nav>
);
}The wallet address can be obtained from your dApp's Web3 provider, such as MetaMask or WalletConnect.
The framework uses SQLite as the default database, which is file-based and requires no additional setup. The database file is created automatically in the packages/server/prisma directory.
If you want to use another database, update the DATABASE_URL in the .env file accordingly and modify the Prisma schema in packages/server/prisma/schema.prisma to match your database provider.
For example, to use PostgreSQL, update the provider in the schema file to:
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}And set the DATABASE_URL to something like this:
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"For more details about supported databases and handling migrations, check the Prisma documentation.
If you change the database provider, you must also update the
DATABASE_URLused for integration tests inpackages/server/scripts/test.sh. This script is designed to help you set up the testing database efficiently (e.g., by running a PostgreSQL Docker container).
What to go to production NOW? BootNode can help with everything, from analyzing and converting off/on-chain data into actionable notifications all the way down to prepping or even running the infra. Reach out: Email / Telegram / BootNode.dev
This project is licensed under the MIT License - see the LICENSE file for details.