Skip to main content
Visual Communication: Image messages enable rich visual communication by allowing users to share photos, screenshots, and visual content with automatic upload handling, caption support, and cross-platform compatibility.

​
Image Messaging Overview

Image messages provide powerful visual communication capabilities, allowing users to share photos, screenshots, documents, and other visual content with automatic upload processing and metadata support.

Automatic Upload

Seamless file handling
  • Automatic image upload and processing
  • Progress tracking and status updates
  • Multiple format support (JPEG, PNG, GIF, WebP)
  • Optimized compression and quality

Rich Features

Enhanced visual messaging
  • Caption and text overlay support
  • Thumbnail generation
  • Metadata and tagging
  • Threading and reply support

​
Platform Implementation

  • Mobile SDKs (iOS/Android/Flutter)
  • TypeScript SDK
Unified image handling with automatic uploadMobile SDKs provide streamlined image messaging with automatic upload processing, eliminating the need for separate upload steps.

​
Required Parameters

ParameterTypeDescription
subChannelIdStringTarget subchannel identifier for the image message
attachmentImage/URILocal image file path or URI reference

​
Optional Parameters

ParameterTypeDescription
captionStringText caption or description for the image
tagsArray<String>Message categorization and filtering tags
parentIdStringParent message ID for threaded conversations
metadataObjectCustom properties for extended functionality

​
Implementation Examples

// Create image message with local file
let imageUrl = URL(fileURLWithPath: "/path/to/local/image.jpg")
let options = AmityImageMessageCreateOptions(
    subChannelId: "subChannel-123",
    attachment: .localURL(url: imageUrl),
    caption: "Check out this amazing sunset! 🌅",
    fullImage: true,
    tags: ["photos", "nature", "sunset"],
    parentId: nil
)

do {
    let message = try await messageRepository.createImageMessage(options: options)
    print("Image message sent: \(message.messageId)")
} catch {
    // Handle upload or creation error
    print("Failed to send image: \(error)")
}
Automatic Processing: Mobile SDKs handle image upload, compression, and message creation in a single operation, providing seamless user experience with progress tracking.

​
Image Message Features

Comprehensive image format handlingSupported Formats
  • JPEG: Optimal for photos and complex images with good compression
  • PNG: Perfect for graphics, screenshots, and images requiring transparency
  • WebP: Modern format with superior compression and quality
Quality & Compression
  • Automatic Optimization: SDK handles compression for optimal delivery
  • Quality Preservation: Maintains visual quality while reducing file size
  • Progressive Loading: Supports progressive image loading for better UX
  • Multi-resolution Generation: Automatic multi-resolution transcoding for quick previews
Size Limitations
  • File Size: Platform-specific limits (typically 10-50MB)
  • Dimensions: Support for high-resolution images up to 8K
  • Aspect Ratios: All aspect ratios supported with proper scaling
Example: Quality Settings
let options = AmityImageMessageCreateOptions(
    subChannelId: "channel-123",
    attachment: .localURL(url: imageUrl),
    caption: "High quality product photo",
    fullImage: true, // Maintain full resolution
    tags: ["product", "high-quality"]
)
Real-time upload feedback and status trackingUpload States
  • Queued: Image queued for upload processing
  • Uploading: Active upload with progress percentage
  • Processing: Server-side image processing and optimization
  • Complete: Upload finished, message created successfully
  • Failed: Upload or processing failed, retry available
Progress Tracking
  • Percentage Complete: Real-time upload progress (0-100%)
  • Bytes Transferred: Detailed transfer information
  • Time Estimates: Estimated completion time
  • Speed Monitoring: Upload speed and bandwidth usage
Error Handling
  • Network Interruption: Automatic retry on connection restore
  • File Validation: Format and size validation before upload
  • Server Errors: Graceful handling of server-side issues
  • User Feedback: Clear error messages and recovery options
Example: Upload Monitoring
messageRepository.createImageMessage(subChannelId, attachment)
    .doOnNext { progress ->
        // Update UI with upload progress
        updateProgressBar(progress.percentage)
    }
    .doOnComplete {
        // Upload completed successfully
        showSuccessMessage()
    }
    .doOnError { error ->
        // Handle upload failure
        showRetryOption(error)
    }
    .subscribe()
Rich text support for image descriptionsCaption Capabilities
  • Rich Text: Support for formatting, emojis, and special characters
  • Length Limits: Generous character limits for detailed descriptions
  • Multilingual: Full Unicode support for international content
  • Mentions: User and role mentions within captions
Text vs Caption
  • Text Field: Primary message content, searchable and indexable
  • Caption Field: Image-specific description, display-optimized
  • Combined Usage: Both fields can be used simultaneously
  • Platform Differences: Some platforms merge text and caption
Best Practices
  • Descriptive Captions: Provide context and description for images
  • Accessibility: Use captions for screen reader compatibility
  • SEO Optimization: Include relevant keywords for searchability
  • Consistent Style: Maintain consistent caption formatting
Example: Rich Caption
const imageMessage = {
  subChannelId: 'channel-123',
  dataType: MessageContentType.IMAGE,
  fileId: uploadedFileId,
  caption: '🎉 Team milestone achieved! Our Q4 goals are complete. Special thanks to @sarah and @mike for their outstanding contributions. #teamwork #success',
  tags: ['milestone', 'team', 'achievement'],
  metadata: {
    achievement_type: 'quarterly_goal',
    team_members: ['sarah', 'mike'],
    quarter: 'Q4_2024'
  }
};
Efficient image handling and deliveryUpload Optimization
  • Compression: Automatic image compression to reduce upload time
  • Progressive Upload: Chunked upload for large images
  • Background Processing: Upload continues even if app is backgrounded
  • Retry Logic: Smart retry mechanisms for failed uploads
Memory Management
  • Efficient Loading: Load images on-demand to conserve memory
  • Cache Management: Intelligent caching for frequently viewed images
  • Thumbnail Usage: Use thumbnails for list views and previews
  • Memory Cleanup: Automatic cleanup of unused image data
Network Efficiency
  • Adaptive Quality: Adjust image quality based on network conditions
  • Batch Operations: Group multiple image operations when possible
  • CDN Integration: Leverage content delivery networks for fast access
  • Offline Support: Cache images for offline viewing
UI Performance
  • Lazy Loading: Load images as they come into view
  • Placeholder Images: Show placeholders while images load
  • Smooth Animations: Optimize transitions and loading animations
  • Error States: Graceful handling of failed image loads
Example: Optimized Loading
class ImageMessageWidget extends StatelessWidget {
  final AmityMessage message;
  
  Widget build(BuildContext context) {
    return FutureBuilder<ImageProvider>(
      future: loadImageOptimized(message.data['fileUrl']),
      builder: (context, snapshot) {
        if (snapshot.hasData) {
          return Image(image: snapshot.data!);
        } else if (snapshot.hasError) {
          return ErrorImageWidget();
        } else {
          return CircularProgressIndicator();
        }
      },
    );
  }
}

File Messages

Document sharing Send files, documents, and attachments

Video Messages

Video content Share video clips and recordings

Image Handling Guide

Technical details Deep dive into image processing and optimization
Implementation Strategy: Start with basic image messaging using platform-specific patterns (unified upload for mobile, two-step for web), then add features like captions, metadata, and threading. Always implement proper progress feedback and error handling for optimal user experience.