UnifAI Telegram Bot

A Telegram bot developed with TypeScript, integrated with UnifAI SDK, capable of dynamically calling various tools to help users complete tasks.

🌟 Features

• Intelligent Conversation: Supports multi-turn conversations with context memory
• Dynamic Tool Calling: Based on UnifAI SDK, capable of searching and using various tools
• Session Management: Automatically manages user sessions with session expiration cleanup
• Error Handling: Comprehensive error handling and retry mechanisms
• Logging System: Detailed logging with support for different levels
• Health Monitoring: Provides health check and system status endpoints
• Graceful Shutdown: Supports graceful shutdown to ensure no data loss

🏗️ Technical Architecture

src/
├── config/          # Configuration files
│   └── index.ts     # Environment variable configuration
├── services/        # Service layer
│   ├── chatSessionManager.ts  # Session management
│   ├── unifaiService.ts       # UnifAI SDK integration
│   └── telegramBot.ts         # Telegram Bot service
├── types/           # TypeScript type definitions
│   └── index.ts
├── utils/           # Utility functions
│   └── logger.ts    # Logging utility
└── index.ts         # Application entry point

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• Telegram Bot Token
• UnifAI Agent API Key

1. Clone the Project

git clone <repository-url>
cd unifai-telegram-bot

2. Install Dependencies

npm install
# or
yarn install

3. Configure Environment Variables

Copy the environment variable template file and configure it:

cp env.example .env

Edit the .env file and fill in the necessary configurations:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# UnifAI Configuration
UNIFAI_AGENT_API_KEY=your_unifai_agent_api_key_here

# OpenAI Configuration
ANTHROPIC_API_KEY=your_openai_api_key_here

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# Bot Settings
CHAT_HISTORY_LIMIT=10
MAX_MESSAGE_LENGTH=4096
RESPONSE_TIMEOUT=30000

4. Run the Project

Development mode:

npm run dev

Production mode:

npm run build
npm start

📋 Available Commands

Development Commands

• npm run dev - Start development server (supports hot reload)
• npm run build - Build the project
• npm start - Start production server
• npm test - Run tests
• npm run lint - Code linting
• npm run lint:fix - Fix code formatting issues

Bot Commands

Users can use the following commands in Telegram:

• /start - Start the bot and view welcome message
• /help - View help information
• /clear - Clear current conversation history
• /status - View system running status
• /tools - View currently available tools

🔧 API Endpoints

After the application starts, the following HTTP endpoints are available:

• GET /health - Health check endpoint
• GET /info - System information endpoint

Health Check Response Example

{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 3600,
  "memory": {
    "rss": 123456789,
    "heapTotal": 123456789,
    "heapUsed": 123456789,
    "external": 123456789
  },
  "version": "1.0.0"
}

🔨 Configuration Options

Environment Variables Description

Variable Name	Description	Default Value	Required
TELEGRAM_BOT_TOKEN	Telegram Bot Token	-	✅
UNIFAI_AGENT_API_KEY	UnifAI Agent API Key	-	✅
OPENAI_API_KEY	OpenAI API Key	-	❌
PORT	HTTP service port	3000	❌
NODE_ENV	Runtime environment	development	❌
LOG_LEVEL	Log level	info	❌
CHAT_HISTORY_LIMIT	Chat history limit	10	❌
MAX_MESSAGE_LENGTH	Maximum message length	4096	❌
RESPONSE_TIMEOUT	Response timeout (ms)	30000	❌

Getting API Keys

1. Telegram Bot Token:

   • Contact @BotFather to create a new bot
   • Follow the instructions to get the Bot Token

2. UnifAI Agent API Key:

   • Visit UnifAI Official Website
   • Register an account and get a free Agent API Key

3. OpenAI API Key (optional):

   • Visit OpenAI Official Website
   • Create an API Key

📊 Usage Examples

Basic Conversation

User: Hello!
Bot: Hello! I am an intelligent assistant powered by UnifAI that can use various tools to help you complete tasks. How can I help you?

User: What topics are trending on Google today?
Bot: Let me help you check the trending topics on Google today...
[Call tools to get information]
Based on the latest data, the trending topics on Google today include...

Tool Calling Examples

The bot will automatically search and call appropriate tools based on user needs:

• Search information
• Get weather data
• Calculate and analyze
• Document processing
• And more...

🔍 Troubleshooting

Common Issues

1. Bot not responding

   • Check if the Telegram Bot Token is correct
   • Check the log file logs/error.log
   • Confirm network connection is normal

2. UnifAI connection failure

   • Verify if the UnifAI API Key is valid
   • Check network firewall settings
   • Check console error messages

3. Tool calling failure

   • Confirm UnifAI service status
   • Check tool permission settings
   • Check detailed error logs

Log Files

• logs/combined.log - All logs
• logs/error.log - Error logs

Debug Mode

Set environment variables to enable debug mode:

LOG_LEVEL=debug npm run dev

🛠️ Development Guide

Project Structure Description

• config/: Configuration management, reads configuration from environment variables
• services/: Core business logic
  • chatSessionManager.ts: Manages user sessions and message history
  • unifaiService.ts: UnifAI SDK integration and tool calling
  • telegramBot.ts: Telegram Bot API integration
• types/: TypeScript type definitions
• utils/: Utility functions and helper modules

Adding New Features

1. Create new service classes in the services/ directory
2. Define related types in types/
3. Integrate new services in the main application
4. Add corresponding test cases

Code Standards

• Use ESLint for code linting
• Follow TypeScript strict mode
• Use meaningful variable and function names
• Add necessary comments and documentation

📝 License

This project is licensed under the MIT License. See the LICENSE file for details.

🤝 Contributing

Issues and Pull Requests are welcome!

1. Fork this project
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

📞 Support

If you encounter problems or need help:

1. Check the Issues page
2. Read the troubleshooting section of this document
3. Create a new Issue describing the problem

---

Enjoy using UnifAI Telegram Bot! 🚀