SDKsHarmonyOSEnterprise

Upload file

Upload a local file to remote object storage and obtain its remote URL.

File upload is an independent infrastructure utility used for user avatars, group icons, profile attachments, or arbitrary business assets. This method operates independently of messages and does not automatically create or send a chat message.

Code example

import sdk, {
  EventOnUploadFileProgressData,
  OpenIMSDKEvent,
  UploadFileReq,
  UploadFileResp,
} from '@openimsdk/imsdk';

const cancelID = `avatar-${Date.now()}`;
const handleUploadProgress = (data: EventOnUploadFileProgressData): void => {
  setCurrentUploadProgress(data.progress);
};
const unsubscribeUploadProgress = sdk.on(
  OpenIMSDKEvent.EventOnUploadFileProgress,
  handleUploadProgress,
);

const request: UploadFileReq = {
  filepath: selectedImagePath,
  name: 'avatar.jpg',
  mimeType: 'image/jpeg',
  fileCategory: 'image',
  cancelID: cancelID,
  data: '',
};
const response: UploadFileResp = await sdk.uploadFile(request);
await updateProfileAvatar(response.url);

export function removeUploadProgressListener(): void {
  unsubscribeUploadProgress();
}

Parameters

Parameter	Type	Required	Description
`filepath`	`string`	Yes	Local filesystem path readable by the native engine.
`name`	`string`	Yes	The file name including a valid extension.
`mimeType`	`string`	Yes	Standard MIME type representing the file format.
`fileCategory`	`string`	Yes	Storage bucket category defined by the backend server.
`cancelID`	`string`	Yes	Unique string identifier generated by the application to track or cancel the task.
`data`	`string`	Yes	Pass an empty string when uploading by path; reserved for specific backend payload extensions.

Return value

Returns a Promise that resolves to an UploadFileResp object:

Property	Type	Description
`url`	`string`	The publicly accessible remote URL of the uploaded file.

State changes after the call

The EventOnUploadFileProgress callback reports only the integer progress value without an associated task identifier. If running multiple concurrent uploads, serialize them or track active jobs at the application layer to avoid progress ambiguity. Resolving the Promise indicates only that the file has uploaded successfully to remote storage; applying the URL to a user profile, group avatar, or chat message requires invoking the corresponding domain API. To abort an in-flight upload, see Cancel file upload. Call removeUploadProgressListener() to detach the event callback when the task completes.

Was this page helpful?