File Upload

​

Upload Process

​

1. Upload File Parts

message UploadFilePart {
  uint64 upload_id = 1;
  uint32 part = 2;
  bytes data = 3;
}

​

Upload Flow

1. Generate upload ID: Create a unique upload_id on the client
2. Split file: Divide the file into chunks
3. Upload parts: Send each part with media.uploadFilePart
4. Track parts: Keep track of uploaded parts (0, 1, 2, …)
5. Get reference: After all parts are uploaded, you’ll receive an UploadedFileRef

// Generate unique upload ID
const uploadId = generateUniqueId();
const chunkSize = 512 * 1024; // 512 KB chunks

// Split file into chunks
for (let i = 0; i < file.length; i += chunkSize) {
  const chunk = file.slice(i, i + chunkSize);
  const partNumber = Math.floor(i / chunkSize);
  
  await client.call('media.uploadFilePart', {
    upload_id: uploadId,
    part: partNumber,
    data: chunk
  });
}

​

UploadedFileRef

message UploadedFileRef {
  fixed64 id = 1;
  string name = 2;
  uint32 part_count = 3;
}

​

Using Uploaded Files

message MediaRefUploadedFile {
  UploadedFileRef file = 1;
  optional string filename = 2;
  string mimetype = 3;
  FileMetadata metadata = 4;
}

​

MediaRef

message MediaRef {
  oneof ref {
    MediaRefUploadedFile uploaded = 1;
    MediaRefEmbed embed = 2;
  }
}

​

Example: Attaching to Message

const mediaRef = {
  uploaded: {
    file: uploadedFileRef,  // From upload process
    filename: 'photo.jpg',
    mimetype: 'image/jpeg',
    metadata: {
      image: {
        width: 1920,
        height: 1080,
        preview: previewBytes  // Optional thumbnail
      }
    }
  }
};

​

Best Practices

• Chunk size: Use 256 KB - 1 MB chunks for optimal performance
• Retry logic: Implement retry for failed part uploads
• Progress tracking: Track upload progress by monitoring completed parts
• Concurrent uploads: Upload multiple parts in parallel (with rate limiting)
• Metadata: Always include appropriate metadata for the file type