Upload a file

uploadFile() is an independent upload capability for user avatars, group avatars, profile attachments, and other application files. It does not belong to the message domain and does not create a message automatically.

Parameters

The following snippet focuses on the upload call. If the UI needs progress updates, register the progress and completion events described below before calling uploadFile() so that a small file cannot finish before the listeners are attached.

const uploadTaskID = crypto.randomUUID();
const uploadEventID = `${uploadTaskID}/${file.name}`;

const { data } = await openimsdk.uploadFile({
  name: file.name,
  contentType: file.type || 'application/octet-stream',
  uuid: uploadTaskID,
  file,
});

await saveAvatarURL(data.url);

When the Promise resolves, use data.url as the remote resource URL. It means only that the upload request succeeded; it does not mean the avatar profile has been updated or a chat message has been created or sent. Complete the subsequent business write separately. If the resource will be used in chat, create the corresponding message object from the returned URL and then send it explicitly.

Listen for upload progress

SdkEvent.OnProgress reports upload progress, while SdkEvent.UploadComplete provides completion information. Keep stable handler references and call off() with those same references when the account or state layer is destroyed:

import { SdkEvent } from '@openim/wasm-client-sdk';

function handleUploadProgress({ data }) {
  if (data.clientMsgID !== uploadEventID) return;
  updateUploadProgress(data.clientMsgID, data.progress);
}

function handleUploadComplete({ data }) {
  if (data.uuid !== uploadEventID) return;
  completeUpload(
    data.uuid,
    data.fileSize,
    data.streamSize,
    data.storageSize,
  );
}

openimsdk.on(SdkEvent.OnProgress, handleUploadProgress);
openimsdk.on(SdkEvent.UploadComplete, handleUploadComplete);

function removeUploadListeners() {
  openimsdk.off(SdkEvent.OnProgress, handleUploadProgress);
  openimsdk.off(SdkEvent.UploadComplete, handleUploadComplete);
}

UploadComplete provides FileUploadProgress in data. The WASM wrapper composes its uuid as ${uuid supplied to uploadFile()}/${file.name}, so the example matches events with uploadEventID. fileSize is the original file size, streamSize is the processed stream size, and storageSize is the size of the stored remote object. All size fields are measured in bytes.

Keep the application-generated uploadTaskID and use the composed uploadEventID to associate SDK events with the task. Do not match concurrent uploads by filename alone or by array position.