Rich Media Messages

SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter

Speed run — just the code

import { MessageRepository } from '@amityco/ts-sdk';

// Send an image
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'image',
  data: { fileId: uploadedFileId },  // Upload file first, then attach
  caption: 'Check this out!',
});

// Send a file
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'file',
  data: { fileId: uploadedFileId },
});

// Send a custom message (link previews, polls, etc.)
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'custom',
  data: { type: 'link_preview', url: 'https://example.com', title: 'Example' },
});

Full walkthrough below ↓

Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.

Rich media messages—images, voice clips, videos, and file attachments—dramatically increase engagement and are expected in any modern chat UI. social.plus handles uploading, storage, and delivery so you only need to manage the user’s file picker and the message creation call.

Prerequisites: Basic message sending is working → Sending Messages

Limits at a Glance

Property	Limit
Max image file size	1 GB
Max video file size	1 GB
Max file attachment	1 GB
Supported image formats	jpg, png, gif, webp
Supported video formats	mp4, mov, 3gp, avi, webm
Custom data field	100 KB JSON

Quick Start: Send an Image

import { FileRepository, MessageRepository } from '@amityco/ts-sdk';

try {
  // 1. Upload
  const { data: file } = await FileRepository.uploadImage(imageBlob);

  // 2. Attach to message
  await MessageRepository.createMessage({
    subChannelId: channelId,
    dataType: 'image',
    data: { fileId: file.fileId },
    caption: 'Screenshot of the bug',
  });
} catch (error) {
  console.error('Failed to send image:', error);
}

Step-by-Step Implementation

Upload the file first

All media in social.plus follows an upload-then-send pattern. Upload the raw file to get a fileId, then reference that ID in the message.

import { FileRepository } from '@amityco/ts-sdk';

const { data: uploadedFile } = await FileRepository.uploadImage(imageBlob);
const fileId = uploadedFile.fileId;

→ File Upload

Send image and video messages

// Image
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'image',
  data: { fileId: imageFileId },
  caption: 'Optional caption text',  // Rendered below the image
});

// Video
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'video',
  data: { fileId: videoFileId },
});

Send audio and file messages

// Audio (e.g. voice note)
const { data: audio } = await FileRepository.uploadFile(audioBlob);
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'audio',
  data: { fileId: audio.fileId },
});

// Generic file (PDF, doc, zip, etc.)
const { data: doc } = await FileRepository.uploadFile(pdfBlob);
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'file',
  data: { fileId: doc.fileId },
});

Send custom messages

The custom dataType lets you send any JSON payload. Use it for link previews, poll cards, system events, or any structured message type your app needs.

// Link preview
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'custom',
  data: {
    type: 'link_preview',
    url: 'https://amity.co',
    title: 'Amity — Build Social Features',
    description: 'The platform for adding social features to your app.',
    thumbnailFileId: thumbnailId,
  },
});

// Poll
await MessageRepository.createMessage({
  subChannelId: channelId,
  dataType: 'custom',
  data: {
    type: 'poll',
    question: 'What feature do you want next?',
    options: ['Dark mode', 'Voice chat', 'Threads'],
  },
});

Your client app must know how to render each custom type. The social.plus SDK delivers the raw JSON — the UI rendering is your responsibility.

→ Custom Messages

Render media thumbnails in the message list

When querying messages, each media message includes pre-generated thumbnail URLs:

liveCollection.on('dataUpdated', (messages) => {
  messages.forEach(msg => {
    switch (msg.dataType) {
      case 'image':
        renderImage(msg.data.fileUrl, msg.caption);
        break;
      case 'audio':
        renderAudioPlayer(msg.data.fileUrl, msg.data.duration);
        break;
      case 'file':
        renderFileAttachment(msg.data.fileName, msg.data.fileSize, msg.data.fileUrl);
        break;
      case 'custom':
        renderCustomMessage(msg.data);
        break;
    }
  });
});

Connect to Moderation & Analytics

AI moderation on image content

Enable AI image moderation in Admin Console → AI Content Moderation to automatically flag or block NSFW images in chat before other users see them.→ AI Content Moderation

File size and type policy

Configure allowed file types and maximum file sizes in Admin Console → Network Settings. The SDK enforces these limits client-side before uploading.→ Network Settings

Common Mistakes

Sending fileId before the upload completes — Always await the upload call and check for errors before calling createMessage. A partially-uploaded file will produce a broken message that can’t be recovered.

Storing file URLs directly — File URLs from the social.plus CDN are signed and expire. Always store the fileId in your database, not the URL. Regenerate download URLs on demand.

Best Practices

Show upload progress

For videos and large files, display a progress bar during upload. This prevents the user from thinking the send button is broken on slow connections. The file upload callback provides a progress percentage (0–100).

Compress images before upload

Compress images to ≤ 2MB before uploading. High-res photos degrade channel load times for all members and increase storage costs. Apply client-side compression in the file picker.

Use custom type for rich cards

For complex UI elements (polls, product cards, event invites), use the custom dataType with a versioned type field. This lets you iterate on card designs server-side without forcing app updates.

Dive deeper: Messaging API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

Next Steps

Message Reactions & Replies

Let users react to and thread on your rich media messages.

Chat Moderation

Moderate images and files before they reach other members.

Direct Messages Path

Full DM build path showing where rich media fits in the flow.

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

Limits at a Glance

Quick Start: Send an Image

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps

Message Reactions & Replies

Chat Moderation

Direct Messages Path

​Limits at a Glance

​Quick Start: Send an Image

​Step-by-Step Implementation

​Connect to Moderation & Analytics

​Common Mistakes

​Best Practices

​Next Steps

Message Reactions & Replies

Chat Moderation

Direct Messages Path

Limits at a Glance

Quick Start: Send an Image

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps