A Telegram bot that allows you to scan documents and manage your Endpoints from your phone or anywhere Telegram is available.
- 📎 Scan files - Upload photos or documents directly to create structured data
- 📝 Scan text - Parse meeting notes, emails, or any text content
- 📋 List endpoints - View all your endpoints organized by category
- 📊 Check status - Monitor your API usage and subscription tier
- 🔐 Secure - API keys are encrypted and stored locally
- Message @BotFather on Telegram
- Send
/newbotand follow the prompts - Copy the bot token you receive
- Go to endpoints.work/api-keys
- Create a new API key
- Copy the key (starts with
ep_)
# Clone the repository
git clone https://github.com/adamkristopher/endpoints-telegram-bot.git
cd endpoints-telegram-bot
# Install dependencies
npm install
# Create environment file
cp .env.example .env
# Edit .env and add your TELEGRAM_BOT_TOKEN
nano .env
# Start the bot
npm run dev- Find your bot on Telegram
- Send
/start - Click "Setup API Key" and send your
ep_key
Upload a photo or document with a caption describing what to track:
📸 [photo] job tracker
📎 [document] leads - acme corp
scan: job tracker
Had a great call with Sarah from Acme Corp today.
She's interested in our enterprise plan.
Contact: sarah@acme.com
get: /leads/acme-corp
Type list or use the /list command.
| Command | Description |
|---|---|
/start |
Welcome message and setup |
/help |
Usage guide |
/setup |
Configure your API key |
/list |
Show all your endpoints |
/status |
Check API connection and usage |
| Prefix | Action | Example |
|---|---|---|
scan: |
Set prompt + scan content | scan: job tracker\nMeeting notes... |
text: |
Scan using last prompt | text: More meeting notes... |
get: |
Retrieve endpoint data | get: /leads/acme |
list |
List all endpoints | list |
# Run in development mode (with hot reload)
npm run dev
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Build for production
npm run build
# Start production build
npm startSet the WEBHOOK_URL environment variable to enable webhook mode:
TELEGRAM_BOT_TOKEN=your-token
WEBHOOK_URL=https://your-server.com/webhook
PORT=3000The bot will automatically set up the webhook when started.
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
CMD ["npm", "start"]| Variable | Required | Default | Description |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
Yes | - | Bot token from @BotFather |
ENDPOINTS_API_URL |
No | https://endpoints.work |
Endpoints API URL |
DATABASE_PATH |
No | ./data/bot.sqlite |
SQLite database path |
WEBHOOK_URL |
No | - | Webhook URL (enables webhook mode) |
WEBHOOK_SECRET |
No | - | Secret token for webhook verification |
PORT |
No | 3000 |
Server port for webhook mode |
ENCRYPTION_KEY |
No | Bot token | Key for encrypting stored API keys |
This bot uses grammY plugins for production reliability:
| Plugin | Purpose |
|---|---|
@grammyjs/auto-retry |
Automatically retries failed API requests with exponential backoff |
@grammyjs/transformer-throttler |
Prevents hitting Telegram's rate limits |
@grammyjs/files |
Simplifies file downloads from Telegram |
@grammyjs/parse-mode |
Sets default Markdown formatting for all messages |
@grammyjs/hydrate |
Provides convenient context methods |
The bot also includes:
- Proper error differentiation (GrammyError vs HttpError vs unknown)
- Health check endpoint at
/healthfor monitoring - Graceful shutdown handling
- Webhook secret token verification
- API keys are encrypted using AES-256-CBC before storage
/setupcommand only works in private chats- All user inputs are sanitized before processing
MIT
- Endpoints - The main Endpoints application
- grammY - The Telegram bot framework used
- Report Issues