littleshop/TeleBot/TeleBot/CAROUSEL_FEATURE.md

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

{
  "LittleShop": {
    "ApiUrl": "https://your-api-url.com"
  }
}

Optional Settings

{
  "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.