Initial release
This commit is contained in:
Alessandro Santini
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Flowise Telegram Bot
|
||||
|
||||
A Telegram bot that integrates with Flowise AI to provide conversational AI capabilities. This bot allows users to interact with your Flowise chatflows directly through Telegram.
|
||||
|
||||
## Features
|
||||
|
||||
- Seamless integration with Flowise AI
|
||||
- Easy-to-use Telegram interface
|
||||
- Support for custom chatflows
|
||||
- Environment-based configuration
|
||||
- Docker support for easy deployment
|
||||
- Conversational memory support
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.13+
|
||||
- Docker and Docker Compose
|
||||
- Poetry for Python dependency management
|
||||
- A Telegram Bot Token (obtained from [@BotFather](https://t.me/botfather))
|
||||
- A running Flowise instance with API access
|
||||
|
||||
## Dependencies
|
||||
|
||||
- python-telegram-bot (>=21.10,<22.0)
|
||||
- flowise (>=1.0.4,<2.0.0)
|
||||
- python-dotenv (>=1.0.1,<2.0.0)
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd flowise-telegram
|
||||
```
|
||||
|
||||
2. Install dependencies using Poetry:
|
||||
```bash
|
||||
poetry install
|
||||
```
|
||||
|
||||
3. Create a `.env` file in the root directory with the following variables:
|
||||
```env
|
||||
TELEGRAM_API_KEY=your_telegram_bot_token
|
||||
FLOWISE_API_KEY=your_flowise_api_key
|
||||
FLOWISE_API_URL=your_flowise_url
|
||||
FLOWISE_CHATFLOW_ID=your_chatflow_id
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
- `TELEGRAM_API_KEY`: Your Telegram bot token from BotFather
|
||||
- `FLOWISE_API_KEY`: API key from your Flowise instance
|
||||
- `FLOWISE_API_URL`: URL of your Flowise instance (e.g., http://localhost:3000)
|
||||
- `FLOWISE_CHATFLOW_ID`: ID of the chatflow you want to use (found in the Flowise dashboard URL when editing a flow)
|
||||
|
||||
### Docker Configuration
|
||||
|
||||
The project includes both a `docker-compose.yml` file for running Flowise and a `Dockerfile` for containerizing the bot.
|
||||
|
||||
To start Flowise:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### Running with Local Build
|
||||
To build and run the bot locally with Docker:
|
||||
```bash
|
||||
# Build the Docker image
|
||||
docker build -t flowise-telegram-bot .
|
||||
|
||||
# Run the container
|
||||
docker run --env-file .env --network host flowise-telegram-bot
|
||||
```
|
||||
|
||||
#### Running with Pre-built Image
|
||||
You can also use the pre-built image from GitHub Container Registry:
|
||||
```bash
|
||||
docker run --env-file .env --network host ghcr.io/OWNER/flowise-telegram:latest
|
||||
```
|
||||
Replace `OWNER` with your GitHub username.
|
||||
|
||||
Note: We use `--network host` to allow the bot container to communicate with Flowise running on localhost.
|
||||
|
||||
### CI/CD
|
||||
|
||||
The project includes a GitHub Actions workflow that automatically:
|
||||
- Builds the Docker image
|
||||
- Pushes it to GitHub Container Registry (ghcr.io)
|
||||
- Tags images based on:
|
||||
- Git branches
|
||||
- Git tags (v*.*.*)
|
||||
- Commit SHA
|
||||
|
||||
The workflow runs on:
|
||||
- Push to main branch
|
||||
- Pull requests to main branch
|
||||
- New version tags
|
||||
|
||||
### Flowise Chatflow Setup
|
||||
|
||||
1. Access Flowise at http://localhost:3000 after starting Docker
|
||||
2. Create a new chatflow
|
||||
3. Set up the following nodes:
|
||||
- **Chat Trigger**: Entry point for the conversation
|
||||
- **LLM (Language Model)**: Choose your preferred model (e.g., OpenAI, Anthropic)
|
||||
- **Conversation Memory**: Add memory to maintain context
|
||||
- **Agent**: Configure the agent with appropriate tools and settings
|
||||
- **Output Parser**: Format the response for Telegram
|
||||
|
||||
4. Configure the Agent node:
|
||||
- Set "Agent Type" to "Conversational"
|
||||
- Add system message to define bot behavior
|
||||
- Connect memory to maintain conversation context
|
||||
- Add relevant tools if needed
|
||||
|
||||
5. Enable API access for your chatflow:
|
||||
- Click on the "Chat Trigger" node
|
||||
- Enable "API Endpoint"
|
||||
- Save the chatflow
|
||||
|
||||
6. Copy the chatflow ID from the URL when editing the flow
|
||||
7. Configure your API key in Flowise settings
|
||||
|
||||
Example System Message for Agent:
|
||||
```
|
||||
You are a helpful AI assistant integrated with Telegram. Your responses should be:
|
||||
1. Concise and clear
|
||||
2. Formatted appropriately for Telegram
|
||||
3. Helpful and informative
|
||||
4. Natural and conversational
|
||||
|
||||
Always maintain a friendly and professional tone. If you don't know something, say so directly.
|
||||
```
|
||||
|
||||
## Running the Bot
|
||||
|
||||
1. Start the bot using Python:
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
2. Start a conversation with your bot on Telegram
|
||||
3. Send a message to test the integration
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
flowise-telegram/
|
||||
├── main.py # Main bot implementation
|
||||
├── docker-compose.yml # Docker configuration
|
||||
├── .env # Environment configuration
|
||||
├── README.md # Project documentation
|
||||
└── .gitignore # Git ignore rules
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Local Development
|
||||
|
||||
1. Start Flowise using Docker:
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
2. Run the bot in development mode:
|
||||
```bash
|
||||
python main.py
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. Update the code in `main.py`
|
||||
2. Test your changes locally
|
||||
3. Commit changes with descriptive messages
|
||||
4. Push to your repository
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Bot not responding**
|
||||
- Check if your Telegram token is correct
|
||||
- Verify the bot is running
|
||||
- Check Python logs for errors
|
||||
|
||||
2. **Flowise connection errors**
|
||||
- Ensure Flowise container is running (`docker ps`)
|
||||
- Verify your Flowise URL and API key
|
||||
- Check if Flowise is accessible in your browser
|
||||
|
||||
3. **Missing responses**
|
||||
- Verify your chatflow ID is correct
|
||||
- Ensure the chatflow is properly configured in Flowise
|
||||
- Check if the chatflow works in Flowise UI
|
||||
|
||||
4. **Memory Issues**
|
||||
- Verify the Conversation Memory node is properly connected
|
||||
- Check memory configuration in the Agent node
|
||||
- Test the chatflow in Flowise UI to verify memory retention
|
||||
|
||||
### Logs
|
||||
|
||||
To view logs:
|
||||
- Bot logs: Run the bot directly to see output
|
||||
- Flowise logs: `docker compose logs -f flowise`
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Commit your changes
|
||||
4. Push to the branch
|
||||
5. Create a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
Reference in New Issue
Block a user