Browse SDKs · Android
Platform
SDKsAndroid

Upload a file

Upload files directly to object storage and retrieve their remote URLs using the OpenIM Android SDK.

Copy

The standalone file upload API uploads user avatars, group avatars, profile attachments, or other business assets directly to object storage. This upload operation is decoupled from the message lifecycle and does not create messages or update user profiles automatically.

Code example

File file = new File(localPath);
PutArgs args = new PutArgs(file.getAbsolutePath());
args.name = file.getName();
args.cuase = "user-avatar";

OpenIMClient.getInstance().uploadFile(
    new OnBase<String>() {
        @Override
        public void onSuccess(String result) {
            // result is the final JSON string result of the upload request.
        }

        @Override
        public void onError(int code, String error) {
            // code and error describe the failure.
        }
    },
    new OnPutFileListener() {
        @Override
        public void open(long size) {
            // size is the total byte size of the file to upload.
        }

        @Override
        public void uploadID(String id) {
            // id is the server-assigned upload task identifier.
        }

        @Override
        public void uploadComplete(long fileSize, long streamSize, long storageSize) {
            // File byte transfer is complete.
        }

        @Override
        public void complete(long size, String url, long type) {
            // url is the accessible remote resource URL.
        }
    },
    args
);

Parameters

ParameterTypeRequiredDescription
baseOnBase<String>YesCallback delivering the final success or error response of the upload request.
listenerOnPutFileListenerYesListener tracking file chunks, hashing progress, upload status, and completion.
putArgs.filepathStringYesLocal absolute file path accessible to the Android application.
putArgs.nameStringYesUpload file name. Defaults to the input path; customize as needed.
putArgs.cuaseStringNoBusiness upload reason tag. Matches the exact cuase field declared in the Android SDK's PutArgs.

Return value

The onSuccess callback receives the raw completion string, while the complete(long size, String url, long type) callback on OnPutFileListener delivers the final remote URL, total file size, and content type.

Use the returned URL in subsequent API calls to update user avatars, configure group avatars, attach media to messages, or link attachments. Uploading writes binary data to object storage but does not update domain profiles or dispatch chat messages automatically.

Progress and lifecycle callbacks

OnPutFileListener provides real-time chunk and transmission lifecycle events:

CallbackParametersDescription
opensizeFile stream opened; reports total file size in bytes.
partSizepartSize, numChunking configuration reporting individual chunk size and total chunk count.
hashPartProgressindex, size, partHashChecksum calculation completed for a single chunk.
hashPartCompletepartsHash, fileHashComplete checksum calculation finished across all chunks.
uploadIDuploadIDServer upload session ID assigned.
uploadPartCompleteindex, partSize, partHashChunk upload confirmed by the storage service.
uploadCompletefileSize, streamSize, storageSizeData transmission finished, delivering final file, stream, and storage sizes.
completesize, url, typeFull upload pipeline finished; delivers the remote resource URL.