SysAdmin
e1b377a042
- BTCPay Server integration - TeleBot Telegram bot - Review system - Admin area - Docker deployment configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
145 lines
5.0 KiB
Markdown
145 lines
5.0 KiB
Markdown
# Product Image Carousel Feature
|
|
|
|
## Overview
|
|
The TeleBot now supports displaying products with images in beautiful carousel format, making the shopping experience more visual and engaging.
|
|
|
|
## Features
|
|
|
|
### 🖼️ Image Carousels
|
|
- **Product Images**: Automatically displays product images from the API
|
|
- **Media Groups**: Groups up to 10 products per carousel for optimal viewing
|
|
- **Image Caching**: Downloads and caches images locally for faster loading
|
|
- **Fallback Support**: Gracefully falls back to text-only display if images fail
|
|
|
|
### 🛍️ Enhanced Browsing
|
|
- **New Command**: `/products` - Browse all products with images
|
|
- **Category Support**: `/products <categoryId>` - Browse specific category with images
|
|
- **Pagination**: Navigate through multiple pages of products
|
|
- **Single Product View**: Individual products shown with high-quality images
|
|
|
|
### 🎨 User Experience
|
|
- **Visual Appeal**: Products displayed with images, names, prices, and descriptions
|
|
- **Interactive Buttons**: Easy navigation and product selection
|
|
- **Responsive Design**: Optimized for mobile and desktop viewing
|
|
- **Fast Loading**: Cached images load instantly
|
|
|
|
## Usage
|
|
|
|
### Commands
|
|
```
|
|
/products - View all products with images
|
|
/products <categoryId> - View products in specific category
|
|
/browse - Browse categories (existing functionality)
|
|
```
|
|
|
|
### Menu Options
|
|
- **🖼️ View Products with Images** - Main menu option for image browsing
|
|
- **🛍️ Browse Categories** - Traditional category browsing
|
|
|
|
### Callback Data Format
|
|
```
|
|
products:page:<pageNumber> - Pagination for all products
|
|
products:<categoryId>:<page> - Pagination for specific category
|
|
product:<productId> - View individual product with image
|
|
```
|
|
|
|
## Technical Implementation
|
|
|
|
### Services
|
|
- **ProductCarouselService**: Handles image downloading, caching, and carousel generation
|
|
- **Image Caching**: Local file system caching in `image_cache/` directory
|
|
- **HTTP Client**: Configured for downloading product images
|
|
- **Error Handling**: Graceful fallback to text-only display
|
|
|
|
### Image Processing
|
|
- **Format Support**: JPG, PNG, WebP, and other common formats
|
|
- **Validation**: Checks image URLs before downloading
|
|
- **Caching Strategy**: Files cached with product and photo IDs
|
|
- **Memory Management**: Streams images efficiently
|
|
|
|
### Telegram Integration
|
|
- **Media Groups**: Uses `SendMediaGroupAsync` for carousels
|
|
- **Photo Messages**: Individual products with `SendPhotoAsync`
|
|
- **Inline Keyboards**: Navigation and interaction buttons
|
|
- **Error Recovery**: Fallback to text messages if media fails
|
|
|
|
## Configuration
|
|
|
|
### Required Settings
|
|
```json
|
|
{
|
|
"LittleShop": {
|
|
"ApiUrl": "https://your-api-url.com"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Optional Settings
|
|
```json
|
|
{
|
|
"Features": {
|
|
"EnableQRCodes": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## File Structure
|
|
```
|
|
TeleBot/
|
|
├── Services/
|
|
│ └── ProductCarouselService.cs # Main carousel service
|
|
├── Handlers/
|
|
│ ├── CommandHandler.cs # Updated with /products command
|
|
│ └── CallbackHandler.cs # Updated with carousel callbacks
|
|
├── UI/
|
|
│ ├── MenuBuilder.cs # Updated with new menu options
|
|
│ └── MessageFormatter.cs # Updated with carousel support
|
|
└── image_cache/ # Local image cache directory
|
|
```
|
|
|
|
## Benefits
|
|
|
|
### For Users
|
|
- **Visual Shopping**: See products before buying
|
|
- **Better Experience**: More engaging than text-only browsing
|
|
- **Faster Navigation**: Quick access to product images
|
|
- **Mobile Friendly**: Optimized for mobile devices
|
|
|
|
### For Business
|
|
- **Higher Conversion**: Visual products increase sales
|
|
- **Professional Look**: Modern, polished appearance
|
|
- **User Engagement**: More time spent browsing
|
|
- **Competitive Edge**: Stand out from text-only bots
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
- **Image Optimization**: Automatic resizing and compression
|
|
- **Lazy Loading**: Load images on demand
|
|
- **Multiple Images**: Support for product galleries
|
|
- **Image Search**: Search products by visual similarity
|
|
- **Video Support**: Product videos in carousels
|
|
|
|
### Performance Improvements
|
|
- **CDN Integration**: Use CDN for image delivery
|
|
- **Progressive Loading**: Show low-res images first
|
|
- **Batch Processing**: Optimize multiple image downloads
|
|
- **Memory Optimization**: Better memory management
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
1. **Images Not Loading**: Check API image URLs and network connectivity
|
|
2. **Slow Performance**: Clear image cache or check disk space
|
|
3. **Memory Usage**: Monitor cache size and implement cleanup
|
|
4. **API Errors**: Verify LittleShop API configuration
|
|
|
|
### Debug Information
|
|
- Check logs for image download errors
|
|
- Monitor cache directory size
|
|
- Verify product photo data from API
|
|
- Test with different image formats
|
|
|
|
## Support
|
|
For issues or questions about the carousel feature, check the logs or contact the development team.
|