Image and File Uploads

Stream Chat allows you to upload images, videos, and other files to the Stream CDN or your own CDN. Uploaded files can be used as message attachments, user avatars, or channel images.

Uploading Files to a Channel

Files uploaded to a channel can be attached to messages. You can either upload a file first and then attach it to a message, or let the SDK handle the upload when sending a message with attachments.

const response1 = await channel.sendImage(
  file1,
  file1.name,
  file1.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`Image upload: ${pct}%`);
    },
  },
);

const response2 = await channel.sendFile(
  file2,
  file2.name,
  file2.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`File upload: ${pct}%`);
    },
  },
);

await channel.sendMessage({
  text: "Check these out",
  attachments: [
    {
      type: "image",
      asset_url: response1.file,
      thumb_url: response1.file,
    },
    {
      type: "file",
      asset_url: response2.file,
      title: file2.name,
    },
  ],
});

Uploading Standalone Files

Files not tied to a specific channel can be used for user avatars and channel images, i.e. stored in the image or image_url field of a user or channel object.

const { file: imageUrl } = await client.uploadImage(
  imageFile,
  imageFile.name,
  imageFile.type,
  undefined,
  // Optional
  {
    onUploadProgress: (e) => {
      const pct = e.total ? Math.round((100 * e.loaded) / e.total) : 0;
      console.log(`Image: ${pct}%`);
    },
  },
);

// Example: use the image URL as a user avatar
await client.partialUpdateUser({
  id: userId,
  set: { image: imageUrl },
});

Deleting Files

Delete uploaded files to free storage space. Deleting a file from the CDN does not remove it from message attachments that reference it.

// Delete from channel
await channel.deleteFile(fileURL);
await channel.deleteImage(imageURL);

File Requirements

Images

Other Files

Configuring Allowed File Types

Stream allows every extension and MIME type by default. Your app can be configured to be more restrictive through file_upload_config and image_upload_config:

Set them in the Dashboard under Chat Overview > Upload Configuration, or with the App Settings endpoint.

Uploads Rejected by Your Configuration

Upload restrictions live on the app, not on the device. A client SDK cannot read or change them, so the same limits apply to every upload from every SDK, and a client integration has to handle the rejection rather than prevent it.

Rejection happens at upload time, before the message is sent. The upload call fails and returns no attachment URL, so the message never gets the attachment. Handle the failure and tell the user which rule they hit. A file over the size limit returns HTTP 413 with Stream code 22, listed in API error codes.

Access Control and Link Expiration

Stream CDN URLs include a signature that validates access to the file. Only channel members can access files uploaded to that channel.

To check when a link expires, examine the Expires query parameter in the URL (Unix timestamp).

Image Resizing

Append query parameters to Stream CDN image URLs to resize images on the fly.

Using Your Own CDN

All SDKs support custom CDN implementations. Implement a custom file uploader to use your own storage solution.

messageComposer.attachmentManager.setCustomUploadFn(async (file) => {
  const result = await customCDN.upload(file);
  return { file: result.url };
});