# social.plus SDK

> social.plus is a feature-rich SDK for building chat, communities, feeds, live video, and social experiences. This document provides AI-consumable documentation for the full SDK: Getting Started, Core Concepts, Video SDK, Chat SDK, and Social SDK.

## Getting Started

### [Installation & Quick Start](https://learn.social.plus/social-plus-sdk/getting-started/overview)

> Install social.plus SDK and start building social features in minutes. Follow our straightforward setup guide.

Install the social.plus SDK and add social features to your app, whether you're building for mobile, web, or cross-platform. This guide covers setup and your first integration.

  **New to social.plus SDK?** Check out our [SDK Overview](/social-plus-sdk/overview) to learn about all available features and choose what's right for your project.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Initialize SDK | API key | Yes | iOS, Android, TypeScript, Flutter | Application API key from the social.plus Console. |
| Initialize SDK | Region / endpoint | Yes | iOS, Android, TypeScript, Flutter | Region where your social.plus application was created, such as US, EU, or SG. |
| Authenticate user | `userId` | Yes | iOS, Android, TypeScript, Flutter | Stable user identifier from your own identity system. |
| Authenticate user | `displayName` | No | iOS, Android, TypeScript, Flutter | Display name stored in the social.plus user profile. |
| Authenticate user | `authToken` | Production | iOS, Android, TypeScript, Flutter | Backend-generated auth token for production authentication. |
| Authenticate user | `sessionHandler` | Recommended | iOS, Android, TypeScript, Flutter | Token-renewal handler used by production session flows. |

    Select the SDK that matches your development environment:

        - [iOS SDK](/social-plus-sdk/getting-started/platform-setup/mobile/ios-quick-start)
        - [Android SDK](/social-plus-sdk/getting-started/platform-setup/mobile/android-quick-start)
        - [Flutter SDK](/social-plus-sdk/getting-started/platform-setup/mobile/flutter-quick-start)
        - [TypeScript SDK](/social-plus-sdk/getting-started/platform-setup/web/web-quick-start)
    1. Visit the social.plus Admin Console
    2. Navigate to **Settings** → **Integrations**
    3. Copy your API key from the **API Key** section

      Keep production API keys in environment or build configuration instead of hardcoding them in public source. Backend auth tokens and secrets must stay server-side.
    1. Install the SDK using the [platform-specific instructions](https://learn.social.plus/social-plus-sdk/getting-started/platform-setup/mobile/ios-quick-start)
    2. Initialize the SDK with your API key and the region where your social.plus application was created (US, EU, or SG)


```swift iOS
let client = try! AmityClient(apiKey: "your-api-key", region: .SG)
```


```kotlin Android
class ChatApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AmityCoreClient.setup(
            apiKey = "your-api-key",
            endpoint = AmityEndpoint.EU // optional param, defaulted as SG region
        )
    }
}
```


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');
```


```dart Flutter
void setup() async {
  await AmityCoreClient.setup(
      option: AmityCoreClientOption.create(
        apiKey: 'your-api-key',
        endpoint: AmityEndpoint.SG
      ),
      sycInitialization: true);
}
```

    Log in users to access social.plus features:
    The examples pass a `sessionHandler`; see the [Authentication guide](/social-plus-sdk/getting-started/authentication#session-handlers) for production token renewal patterns.


```swift iOS
Task { @MainActor in
    do {
        try await client.login(
            userId: "<user-id>",
            displayName: "<(optional)-display-name>",
            authToken: "<(optional)-auth-token>",
            sessionHandler: sessionHandler
        )
        print("login success")
    } catch {
        print("login failed \(error)")
    }
}
```


```kotlin Android
fun authenticate() {
    AmityCoreClient.login(userId = "userId 1", sessionHandler = sessionHandler)
        .displayName(displayName = "John Doe") // optional
        .authToken(authToken = "token") // optional
        .build()
        .submit()
        .doOnComplete {
            //success
        }
        .subscribe()
}
```


```typescript TypeScript
const { Client } = await import('@amityco/ts-sdk');

const sessionHandler: Amity.SessionHandler = {
  sessionWillRenewAccessToken(renewal) {
    renewal.renew();
  },
};

const handleConnect = async (userId: string, displayName: string) => {
  /*
   * NOTE:
   * client instance must be created prior to logging in
   *
   * createClient also accepts an optional object to specify further details
   * such as debugSession & apiEndpoint
   * ex:
   * {
   *    debugSession?: 'string',
   *    apiEndpoint?: { http?: 'http.endpoint', mqtt?: 'mqtt.endpoint'  }
   * }
   */
  const client = Client.createClient('your-api-key', 'sg');

  await Client.login({ userId, displayName }, sessionHandler);
};

handleConnect('userId', 'Bob Newton');
```


```dart Flutter
void login() async {
  await AmityCoreClient.login('userId', sessionHandler: (AccessTokenRenewal renewal) {
    renewal.renew();
  })
      .displayName('userDisplayName')
      .submit();
}
```


## What's Next?

Once you have the SDK installed and initialized, you can start building:

    Learn about session management and secure authentication flows
    Create communities, posts, and social feeds
    Build real-time messaging and channels
    Add live streaming and video features

## Platform Requirements

Make sure your development environment meets these minimum requirements:

    - Xcode 26.0+
    - iOS 14.0+
    - Swift 5.0+
    - Android 6.0 (API 23)+
    - Target SDK 36+
    - Compile SDK 36+
    - Kotlin 2.2.0+
    - Chrome 38+
    - Firefox 42+
    - Safari 9+
    - Edge 13+
    - Opera: 25+
    - React Native 0.60+
    - Node.js 14+
    - iOS 14.0+ / Android 6.0 (API 23)+
    - Flutter 3.0.0 - 4.0.0
    - Dart SDK >=3.0.0 <4.0.0
    - iOS 12.0+ / Android 4.4 (API 19)+

## Need Help?

    Get help from our community
    Explore detailed guides and API references

---

### [Authentication](https://learn.social.plus/social-plus-sdk/getting-started/authentication)

> Authentication is required to access social.plus features. This comprehensive guide will take you from basic login to production-ready authentication patterns.

## Overview & Concepts

### Authentication in social.plus

social.plus uses a **dual authentication approach** to ensure both application security and user verification:

    **Purpose**: Identifies your application to social.plus servers\
    **Scope**: Application-level authentication\
    **Usage**: Required for SDK initialization\
    **Security**: Store in app configuration; do not hardcode in public source
    **Purpose**: Server-to-server verification that the user is validated by your backend\
    **Scope**: User-level authentication with your system\
    **Usage**: Optional for development, required for production\
    **Security**: Generated by your backend, proves user is legitimate

### How Auth Tokens Work

Auth tokens enable **server-to-server communication** between social.plus and your backend:

    Your app authenticates the user with your own authentication system (login, OAuth, etc.)
    Your backend server generates an auth token for the verified user and sends it to your app. [Learn how to implement this →](/social-plus-sdk/getting-started/authentication#backend-token-generation)
    When your app logs into social.plus, the auth token proves to social.plus that your backend has verified this user
    social.plus can now trust that this user session is legitimate and validated by your system

```mermaid
sequenceDiagram
    participant User as User Device
    participant App as Your App
    participant Backend as Your Backend
    participant Social as social.plus SDK
    participant SocialAPI as social.plus API

    User->>App: Login Request
    App->>Backend: Authenticate User
    Backend->>Backend: Verify Credentials
    Backend->>Backend: Generate Auth Token
    Backend->>App: Return Auth Token
    App->>Social: login(userId, authToken)
    Social->>SocialAPI: Verify Auth Token
    SocialAPI->>SocialAPI: Validate Token Signature
    SocialAPI->>Social: Authentication Success
    Social->>App: Login Complete
    App->>User: Access Granted
```

  **Why Auth Tokens?** This approach ensures that only users who have been properly authenticated by your backend can access social.plus features, maintaining security and preventing unauthorized access.

### When Do You Need Each?


```typescript
// Production mode - API key + auth tokens
const client = Client.createClient('your-prod-api-key', 'sg');

// Secure login with auth token from your backend
await Client.login({
  userId: 'user-123',
  displayName: 'John Doe',
  authToken: 'token-generated-by-your-backend' // Proves user is verified by your system
}, sessionHandler);
```


      Auth tokens must be generated by your secure backend after verifying the user. This ensures server-to-server trust between social.plus and your authentication system.

```typescript
// Development mode - API key only (for testing)
const client = Client.createClient('your-dev-api-key', 'sg');

// Simple login without auth token (development/testing only)
await Client.login({
  userId: 'dev-user-123',
  displayName: 'Developer'
}, sessionHandler);
```


      Development mode bypasses auth token requirements for easier testing. Never use this in production as it skips your backend verification.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Initialize SDK | API key | Yes | iOS, Android, TypeScript, Flutter | Application API key from the social.plus Console. |
| Initialize SDK | Region / endpoint | Yes | iOS, Android, TypeScript, Flutter | Region where your social.plus application was created. |
| Login user | `userId` | Yes | iOS, Android, TypeScript, Flutter | Stable user identifier from your identity system. |
| Login user | `displayName` | No | iOS, Android, TypeScript, Flutter | Display name stored in the social.plus user profile. |
| Login user | `authToken` | Production | iOS, Android, TypeScript, Flutter | Backend-generated token proving your system authenticated the user. |
| Login user | `sessionHandler` | Recommended | iOS, Android, TypeScript, Flutter | Callback used to renew auth tokens when the SDK session expires. |
| Login with access token | `accessToken` | Yes | iOS, Android, TypeScript | JWT access token issued by your backend. |
| Login with access token | access token handler | Yes | iOS, Android, TypeScript | Handler registered before login so the SDK can renew access tokens. |
| Logout | None | No | iOS, Android, TypeScript, Flutter | Ends the current SDK session; secure logout revokes the access token where supported. |

## Quick Start (Basic Authentication)

### Step 1: Initialize the SDK

Start by setting up the social.plus client with your API key:


```swift iOS
let client = try! AmityClient(apiKey: "your-api-key", region: .SG)
```


```kotlin Android
AmityCoreClient.setup(
    apiKey = "your-api-key",
    endpoint = AmityEndpoint.SG
)
```


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');
```


```dart Flutter
await AmityCoreClient.setup(
  option: AmityCoreClientOption.create(
    apiKey: 'your-api-key',
    endpoint: AmityEndpoint.SG
  )
);
```


### Step 2: Login User

Authenticate users to access social.plus features:
The examples pass a `sessionHandler`; see [Session Handlers](#session-handlers) for production token renewal patterns.


```swift iOS
Task { @MainActor in
    do {
        try await client.login(
            userId: "user-123",
            displayName: "John Doe",
            authToken: "your-auth-token", // Optional for development
            sessionHandler: sessionHandler
        )
        print("Login successful")
    } catch {
        print("Login failed: \(error)")
    }
}
```


```kotlin Android
AmityCoreClient.login(userId = "user-123", sessionHandler = sessionHandler)
    .displayName(displayName = "John Doe")
    .authToken(authToken) // Optional for development
    .build()
    .submit()
    .doOnComplete {
        // Login successful
    }
    .doOnError { error ->
        // Login failed
    }
    .subscribe()
```


```typescript TypeScript
try {
    await Client.login({
        userId: 'user-123',
        displayName: 'John Doe',
        authToken: 'your-auth-token', // Optional for development
    }, sessionHandler);
    console.log('Login successful');
} catch (error) {
    console.error('Login failed:', error);
}
```


```dart Flutter
try {
    await AmityCoreClient.login('user-123')
        .displayName('John Doe')
        .authToken('your-auth-token') // Optional for development
        .submit();
    print('Login successful');
} catch (error) {
    print('Login failed: $error');
}
```


### Step 3: Check Authentication Status

Verify if a user is currently logged in:


```swift iOS
if case .established = client.sessionState {
    let currentUserId = client.currentUserId
    print("Current user: \(currentUserId ?? "")")
} else {
    // Proceed to social.plus Authentication
    // authenticateToSocialPlus()
}
```


```kotlin Android
if (AmityCoreClient.getCurrentSessionState() == SessionState.Established) {
    val currentUserId = AmityCoreClient.getUserId()
    Log.d("Auth", "Current user: $currentUserId")
} else {
    // Proceed to social.plus Authentication
    authenticateToSocialPlus()
}
```


```typescript TypeScript
// `client` is the instance returned by Client.createClient() during initialization
if (client.sessionState === Amity.SessionStates.ESTABLISHED) {
    const currentUserId = client.userId;
    console.log('Current user:', currentUserId);
} else {
    // Proceed to social.plus Authentication
    authenticateToSocialPlus();
}
```


```dart Flutter
final sessionState = await AmityCoreClient.observeSessionState().first;
if (sessionState == SessionState.Established) {
    final currentUserId = AmityCoreClient.getUserId();
    print('Current user: $currentUserId');
} else {
    // Proceed to social.plus Authentication
    authenticateToSocialPlus();
}
```


### Step 4: Logout

End the user session: For an extra layer of security, which ensures accessToken revocation prior to performing logout(). Should the SDK fail to revoke the accessToken, the SDK will not proceed to logout and will throw an exception to notify the failure.


```swift iOS
do {
    try await client.secureLogout()
} catch {
    /// Handle error from revoking accessToken here
}
```


```kotlin Android
    AmityCoreClient.secureLogout()
        .doOnComplete {
            // Void
        }
        .doOnError {
            // Exception
        }
        .subscribe()
```


```typescript TypeScript
const handleSecureLogout = async () => {
  await Client.secureLogout();
};
handleSecureLogout();
```


```dart Flutter
// Flutter SDK does not expose secureLogout() — use logout() instead.
// secureLogout (with access token revocation) is an iOS/Android/TS feature.
await AmityCoreClient.logout();
```


## Understanding Session States

Session states indicate what's happening with user authentication. social.plus SDK automatically manages these states according to the flow shown in the diagram below:

    **Ready for login** - user needs to authenticate\
    _Entry points_: App start (no session), logout, login failure
    **Login in progress** - authentication being processed\
    _Entry point_: When login() is called from notLoggedIn state
    **Fully authenticated** - SDK ready, all features available\
    _Entry points_: Successful login, successful token renewal
    **Token renewal needed** - automatic renewal attempted\
    _Entry point_: When auth token expires during established state
    **Session forcibly ended** - user banned or deleted\
    _Entry points_: User banned/deleted from established or tokenExpired states

### Session Flow

Understanding the complete session state flow helps you build responsive apps:

    **App starts**: Always begins in the `start` state, then immediately moves to:

    - **No saved session**: Moves to `notLoggedIn` state
    - **Has saved session**: Moves to `established` state (if session valid)
    **User attempts login**:

    - `notLoggedIn` → `establishing` (login in progress)
    - **Login succeeds**: `establishing` → `established`
    - **Login fails**: `establishing` → `notLoggedIn`
    **`During active use in established state`**:

    - **Token expires**: `established` → `tokenExpired`
    - **Token renewed successfully**: `tokenExpired` → `established`
    - **User banned/deleted**: `established` → `terminated`
    - **Manual logout**: `established` → `notLoggedIn`
    **`When in tokenExpired state`**:

    - **Auto-renewal succeeds**: Returns to `established` state
    - **Auto-renewal fails**: User may need to re-authenticate
    - **User banned during renewal**: Moves to `terminated` state
    - **Manual logout**: Moves to `notLoggedIn` state
    **`From terminated state`**:

    - Only way out is through logout → `notLoggedIn`
    - User must re-authenticate to access features again

  Session state diagram image temporarily removed while the asset is unavailable. The textual flow description above preserves the full logic.

### Observing Session State

Monitor session state changes to handle authentication in your app:


    {/* doc-as-test: skip (truly-illustrative: UIViewController scaffold — 'self' only valid inside a class body, not in a free function) */}
```swift
var cancellable: AnyCancellable?
// Observe session state changes
cancellable = client.$sessionState.sink { sessionState in
    switch sessionState {
    case .notLoggedIn:
        // Show login screen
        self?.showLogin()
    case .establishing:
        // Show loading indicator
        self?.showLoading()
    case .established:
        // Hide loading indicator, proceed to app
        self?.hideLoading()
        self?.proceedToApp()
    case .tokenExpired:
        // Attempt to refresh token (Optional)
        self?.showTokenRefreshIndicator()
    case .terminated:
        // Handle session termination
        self?.handleTermination()
    }
}
```


```kotlin
// Observe session state
AmityCoreClient.observeSessionState()
            .subscribeOn(Schedulers.io())
            .observeOn(AndroidSchedulers.mainThread())
            .doOnNext { sessionState: SessionState ->
                when (sessionState) {
                    is SessionState.NotLoggedIn -> {
                        // Show login screen
                        showLogin()
                    }
                    is SessionState.Establishing -> {
                        // Show loading indicator
                    }
                    is SessionState.Established -> {
                        // Hide loading indicator, proceed to app
                    }
                    is SessionState.TokenExpired -> {
                        // Attempt to refresh token (Optional)
                    }
                    is SessionState.Terminated -> {
                        // Handle session termination
                    }
                    else -> {}
                }
            }
            .doOnError {
                // Exception
            }
            .subscribe()
```


```typescript
// Listen to session state changes
import { Client } from '@amityco/ts-sdk';

const unsubscribe = Client.onSessionStateChange((state: Amity.SessionStates) => {
  switch (state) {
    case 'notLoggedIn':
      showLoginForm();
      break;
    case 'establishing':
      showLoadingSpinner();
      break;
    case 'established':
      hideLoadingSpinner();
      navigateToApp();
      break;
    case 'tokenExpired':
      showTokenRefreshIndicator();
      break;
    case 'terminated':
      handleSessionTermination();
      break;
  }
});

// Call unsubscribe() when the screen no longer needs session updates.
```


```dart
// Listen to session state changes
AmityCoreClient.observeSessionState().listen((state) {
  switch (state) {
    case SessionState.NotLoggedIn:
      // Show login screen
      showLoginScreen();
      break;
    case SessionState.Establishing:
      // Show loading indicator
      showLoadingIndicator();
      break;
    case SessionState.Established:
      // Hide loading indicator, proceed to app
      hideLoadingIndicator();
      proceedToApp();
      break;
    case SessionState.TokenExpired:
      // Attempt to refresh token (Optional)
      showTokenRefreshIndicator();
      break;
    case Terminated():
      // Handle session termination
      handleSessionTermination();
  }
});
```


## Advanced Session Management

For production apps, you'll need sophisticated session handling with automatic token refresh:

### Session Handlers for Token Refresh

Session handlers automatically manage token lifecycle:


```swift
class ProductionSessionHandler: SessionHandler {
    func sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        // Call your backend to get a fresh token
        Task {
            do {
                // let newToken = try await YourAuthService.fetchToken()
                // renewal.renewWithAuthToken(authToken: newToken)
                renewal.unableToRetrieveAuthToken() // replace with real token fetch
            }
        }
    }
}

// Use during login
let userId = "user-id"
let displayName: String? = "Display Name"
let authToken: String? = nil
let sessionHandler = ProductionSessionHandler()
try await client.login(
    userId: userId,
    displayName: displayName,
    authToken: authToken,
    sessionHandler: sessionHandler
)
```


```kotlin
class ProductionSessionHandler : SessionHandler {
    override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        // Call your backend to refresh token; renewal.renewWithAuthToken(newToken)
        // or renewal.unableToRetrieveAuthToken() on failure
    }
}

// Use during login
val productionSessionHandler = ProductionSessionHandler()
AmityCoreClient.login(userId = userId, sessionHandler = productionSessionHandler)
    .displayName(displayName)
    .authToken(authToken)
    .build()
    .submit()
```


```typescript
interface SessionHandler {
    sessionWillRenewAccessToken: (renewal: TokenRenewal) => void;
}

const createProductionSessionHandler = (): Amity.SessionHandler => ({
    sessionWillRenewAccessToken: async (renewal: Amity.AccessTokenRenewal) => {
        try {
            // Request fresh token from your backend (server-to-server)
            // Your backend re-verifies the user and generates new token
            const newToken = await AuthService.refreshToken();
            renewal.renewWithAuthToken(newToken);
        } catch (error) {
            console.error('Token refresh failed:', error);
            renewal.unableToRetrieveAuthToken();
        }
    }
});

// Use when logging in with backend-verified token
await Client.login({
        userId: 'user-123',
        displayName: 'John Doe',
        authToken: 'your-auth-token',
    }, sessionHandler);
```


```Dart
Function(AccessTokenRenewal) getProductionSessionHandler() {
  return (AccessTokenRenewal renewal) async {
    try {
      final myAuthToken = await getAuthTokenFromMyServer();
      renewal.renewWithAuthToken(myAuthToken);
    } catch (error) {
      renewal.unableToRetrieveAuthToken();
    }
  };
}

void authenticateUser() async {
// Use during login
  try {
    await AmityCoreClient.login(
      'userId',
      sessionHandler: getProductionSessionHandler(),
    ).displayName('displayName').authToken('authToken').submit();
  } catch (error) {
    // Handle authentication error
  }
}
```


## Alternative: Login with Access Token

By default, social.plus SDK handles access token management for you — you provide a `userId` and an optional `authToken`, and the SDK takes care of obtaining and refreshing access tokens behind the scenes.

**Login with Access Token** is an alternative authentication method for customers who want to manage the entire token lifecycle themselves. Instead of letting the SDK obtain tokens, your backend issues a JWT access token directly, and your app passes it to the SDK.

**Most developers should use the default login flow** described in the [Quick Start](#quick-start-basic-authentication) section above. Only use this approach if you have a specific need listed below.

### When to Use This

    Your app already has a centralized authentication system and you want social.plus sessions to be issued as part of that flow — no extra network hop from the client.
    You want to eliminate the client-to-social.plus token exchange during login so that social.plus API availability does not block your app's core login experience.

### Default Login vs. Access Token Login

| | **Default Login** | **Login with Access Token** |
|---|---|---|
| **SDK method** | `login(userId, authToken)` | `loginWithAccessToken(accessToken)` |
| **Who obtains the access token?** | The SDK handles it automatically | Your backend issues a JWT and your app passes it to the SDK |
| **Token renewal** | Session handler (`sessionWillRenewAccessToken`) | Access token handler (`onTokenRenew`) |
| **Best for** | Most integrations | SSO, custom auth backends, decoupled architectures |
| **Client-to-social.plus call during login?** | Yes — SDK exchanges credentials for a token | No — token is pre-issued by your backend |

### How It Works

```mermaid
sequenceDiagram
    participant App as Your App
    participant Backend as Your Backend
    participant SDK as social.plus SDK
    participant API as social.plus API

    App->>Backend: Request access token for user
    Backend->>Backend: Generate & sign JWT
    Backend->>App: Return JWT access token
    App->>SDK: loginWithAccessToken(accessToken)
    SDK->>API: Verify token
    API->>SDK: Session established
    SDK->>App: Login complete

    Note over SDK,API: Later, when token is about to expire...
    SDK->>App: onTokenRenew(userId)
    App->>Backend: Request new access token
    Backend->>App: Return fresh JWT
    App->>SDK: Return new token
    SDK->>API: Verify & refresh session
```

### Implementation

Integration requires three steps: implement a token handler, register it, then login.

    Create a handler that the SDK will call whenever the token needs renewal. Your handler should request a fresh JWT from your backend.
    Call `setAccessTokenHandler()` **before** logging in. This tells the SDK how to obtain a new token when the current one expires.
    Call `loginWithAccessToken()` with the JWT your backend issued. The SDK verifies it with social.plus and establishes the session.


```swift
// 1. Implement the AccessTokenHandler protocol.
//    The SDK calls `onTokenRenew` when the access token is expired
//    or about to expire. You must return a fresh JWT obtained from
//    your own authentication backend.
class MyTokenHandler: AccessTokenHandler {
    func onTokenRenew(userId: String) async throws -> String {
        // Use the provided userId to request a new JWT
        // from your authentication backend.
        let newToken = try! await fetchNewTokenFromBackend(userId: userId)
        return newToken
    }
}

// 2. Register the handler BEFORE calling loginWithAccessToken.
//    The handler must be set first so the SDK can invoke it
//    whenever a token renewal is needed.
let client = try! AmityClient(apiKey: "<api-key>")
let tokenHandler = MyTokenHandler()
client.setAccessTokenHandler(tokenHandler)

// 3. Now login with the initial access token.
//    On subsequent token renewals, the SDK will automatically
//    call onTokenRenew and re-authenticate using the returned JWT.
try! await client.loginWithAccessToken(accessToken: initialAccessToken)
```


```kotlin
// 1. Implement the AccessTokenHandler interface.
//    The SDK calls `onTokenRenew` when the access token is expired
//    or about to expire. You must return a fresh JWT obtained from
//    your own authentication backend.
val handler = object : AccessTokenHandler {
  override suspend fun onTokenRenew(userId: String): String {
    // get new token from your api; replace with real API call
    return "new-access-token"
  }
}

// 2. Register the handler BEFORE calling loginWithAccessToken.
//    The handler must be set first so the SDK can invoke it
//    whenever a token renewal is needed.
AmityCoreClient.setAccessTokenHandler(handler)

// 3. Now login with the initial access token.
//    On subsequent token renewals, the SDK will automatically
//    call onTokenRenew and re-authenticate using the returned JWT.
AmityCoreClient.loginWithAccessToken(authToken)
  .build()
  .submit()
  .subscribe()
```


```typescript
import { Client } from "@amityco/ts-sdk";

// 1. Define custom token handler.
//    The SDK calls `onTokenRenew` when the access token is expired
//    or about to expire. You must return a fresh JWT obtained from
//    your own authentication backend.
const tokenHandler = {
  async onTokenRenew(userId: string): Promise<string> {
    // Request new JWT from your authentication backend
    const response = await fetch("https://your-backend.com/api/refresh-token", {
      method: "POST",
      credentials: "include",
      userId,
    });

    const data = await response.json();
    return data.accessToken;
  },
};

// 2. Register the handler BEFORE calling loginWithAccessToken.
//    The handler must be set first so the SDK can invoke it
//    whenever a token renewal is needed.
Client.setAccessTokenHandler(tokenHandler);

// 3. Now login with the initial access token.
//    On subsequent token renewals, the SDK will automatically
//    call onTokenRenew and re-authenticate using the returned JWT.
await Client.loginWithAccessToken(initialAccessToken);
```


**Handler must be registered first.** Always call `setAccessTokenHandler()` before `loginWithAccessToken()`. If no handler is registered, the SDK cannot renew expired tokens and will throw an error.

## Security Best Practices

### Production Token Management

    Auth tokens must be generated by your secure backend to establish server-to-server trust with social.plus.

    Refer to the general API Reference introduction until the dedicated authentication endpoint page is published.


```javascript
// Example Node.js backend - generates tokens for verified users
app.post('/api/auth/social-plus-token', async (req, res) => {
  const { userId } = req.body;

  // STEP 1: Verify user is authenticated in YOUR system
  const user = await verifyUserInYourSystem(userId);
  if (!user) {
    return res.status(401).json({ error: 'User not authenticated in your system' });
  }

  // STEP 2: Generate social.plus auth token for this verified user
  const authToken = generateSocialPlusToken(userId);

  // STEP 3: Return token to your app for social.plus login
  res.json({
    authToken,
    message: 'Token generated for verified user'
  });
});
```


    **Why this approach?**

    - Your backend vouches for the user's authenticity to social.plus
    - social.plus trusts users who have valid tokens from your verified backend
    - Prevents unauthorized access to social.plus features
    - Maintains security boundary between your auth system and social.plus

### Authentication Best Practices

    - **Monitor session state changes** in your app's main navigation logic
    - **Handle token expiration gracefully** with automatic refresh
    - **Provide clear feedback** to users during state transitions
    - **Clean up subscriptions** when components unmount
    - **Use secure logout** when security is critical
    - **Store tokens securely** using platform-specific secure storage
    - **Don't ignore session state changes** - they indicate important authentication events
    - **Don't store sensitive data** when user is not authenticated
    - **Don't make API calls** before reaching `established` state
    - **`Don't forget to handle the terminated state`** - users may be banned
    - **Don't hardcode production API keys** in public source or logs
    - **Don't use plain text storage** for auth tokens

## Troubleshooting

    **Symptoms**: Login never completes, app shows loading indefinitely

    **Solutions**:

    1. Check your API key and network connection
    2. Verify authentication token is valid
    3. Ensure you're using the correct region
    4. Check for console errors or network timeouts
    **Symptoms**: Users get logged out too often

    **Solutions**:

    1. Check your backend token expiration settings
    2. Verify session handler implementation
    3. Ensure token refresh logic works correctly
    4. Consider longer token expiration for better UX
    **Symptoms**: Tokens don't refresh automatically

    **Solutions**:

    1. Verify you're passing the session handler during login
    2. Check that your backend token has appropriate expiration
    3. Ensure session handler implementation handles errors
    4. Test with shorter token expiration for debugging
    **Symptoms**: App crashes when authentication state changes

    **Solutions**:

    1. Ensure UI updates happen on the main thread
    2. Handle all possible session states in switch statements
    3. Add proper null checks and error handling
    4. Clean up observers when components unmount
    **Symptoms**: Calling `loginWithAccessToken()` throws an error before reaching the server

    **Solutions**:

    1. Ensure you called `setAccessTokenHandler()` **before** `loginWithAccessToken()` — the handler must be registered first
    2. Verify your JWT is well-formed (valid JSON Web Token structure)
    3. Check that the JWT contains the required `userId` claim
    4. Confirm your backend is signing the token with the key configured in the social.plus console
    **Symptoms**: Token expires but the SDK does not invoke your `onTokenRenew` handler

    **Solutions**:

    1. Verify you logged in via `loginWithAccessToken()` — the handler is only invoked for access-token sessions, not default `login()` sessions
    2. Check that the handler was registered with `setAccessTokenHandler()` before login
    3. Ensure the user is not globally banned — the SDK skips handler invocation for banned users

## Next Steps

    Learn about user profiles and management
    Explore social capabilities structure
    Add real-time messaging
    Configure security and settings in the Console

---

### [Visitor Mode](https://learn.social.plus/social-plus-sdk/getting-started/visitor-mode)

> Enable visitor mode to allow anonymous users to browse public content without signing in. Server-side read-only controls protect platform integrity.

Visitor mode lets anonymous users browse public content read-only, without signing in. Access is controlled server-side to protect platform integrity.

  **Visitor mode is not enabled by default.** To enable visitor mode for your network, please contact [support@social.plus](mailto:support@social.plus) with your network details.

## Overview & Concepts

### What is Visitor Mode?

Visitor mode enables **anonymous public access** to your community, allowing users to browse and discover content without requiring authentication. This feature is ideal for growth funnels, SEO optimization, and public content discovery while maintaining platform security and stability.

    **Purpose**: Anonymous users who browse public content\
    **Access**: Read-only permissions enforced server-side\
    **Tracking**: Identified by an SDK-generated device ID\
    **Use Case**: Public content discovery, growth funnel

    **Purpose**: Search engine crawlers and automated indexers\
    **Access**: Read-only permissions for content indexing\
    **Tracking**: Identified by User-Agent analysis\
    **Use Case**: SEO optimization, content discoverability

### How Visitor Mode Works

Visitor mode uses an **SDK-generated device ID** to identify anonymous users while maintaining privacy:

    The SDK generates or retrieves a stable device ID for the anonymous user
    The SDK logs in the user as a visitor using the device ID, with optional secure mode via authSignature
    social.plus server assigns the "Visitor" or "Bot" role based on the request (User-Agent for bots)
    Server-side permissions enforce read-only access, allowing content discovery without modification capabilities

```mermaid
sequenceDiagram
    participant Device as User Device
    participant App as Your App
    participant SDK as social.plus SDK
    participant API as social.plus API

    Device->>App: Access public content
    App->>SDK: getVisitorDeviceId()
    SDK->>SDK: Generate/Retrieve Device ID
    SDK->>App: Return Device ID
    App->>SDK: loginAsVisitor(deviceId)
    SDK->>API: POST /api/v5/sessions/visitor
    API->>API: Assign "Visitor" Role
    API->>SDK: Return Session (Read-Only)
    SDK->>App: Login Complete
    App->>Device: Show Public Content
```

  **Why device IDs?** This approach lets social.plus distinguish anonymous visitor sessions without requiring a signed-in user account. Visitors are restricted to read-only access, protecting community integrity.

### User Type Comparison

Understanding the different user types helps you design the right access patterns:


```typescript
// Full authenticated user with read/write access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

// ... your app setup code

await Client.login({
  userId: 'user-123',
  displayName: 'John Doe',
}, sessionHandler);
```


    **Capabilities:**

    - ✅ Full read/write access to all features
    - ✅ Real-time event connections (MQTT)
    - ✅ Push notifications
    - ✅ Create posts, comments, reactions
    - ✅ Join communities and follow users

```typescript
// Anonymous visitor with read-only access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

await Client.loginAsVisitor({
    sessionHandler,
});
```


    **Capabilities:**

    - ✅ View public posts and content
    - ✅ Browse public communities
    - ✅ View user profiles
    - ❌ No real-time connections (no MQTT)
    - ❌ No push notifications
    - ❌ Cannot create content or interact
    - ❌ Cannot join communities or follow users

```typescript
// Search engine crawler with read-only access
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

await Client.loginAsBot({ sessionHandler });
```


    **Capabilities:**

    - ✅ Index public content for SEO
    - ✅ View public posts and communities
    - ✅ Separated analytics tracking
    - ❌ No real-time connections
    - ❌ No push notifications
    - ❌ No write operations

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Initialize SDK | API key | Yes | iOS, Android, TypeScript | Application API key from the social.plus Console. |
| Initialize SDK | Region / endpoint | Yes | iOS, Android, TypeScript | Region where your social.plus application was created. |
| Get visitor device ID | None | No | iOS, Android, TypeScript | SDK returns or generates the stable anonymous device ID. |
| Login as visitor | `sessionHandler` | Recommended | iOS, Android, TypeScript | Token-renewal handler for visitor sessions. |
| Secure visitor login | `authSignature` | Secure mode | iOS, Android, TypeScript | Backend-generated HMAC signature for the visitor device ID and expiration time. |
| Secure visitor login | `authSignatureExpiresAt` | Secure mode | iOS, Android, TypeScript | Expiration timestamp that was included in the signature. |
| Login as bot | `sessionHandler` | Recommended | TypeScript | Token-renewal handler for explicit bot sessions. |
| Check user type | None | No | iOS, Android, TypeScript | SDK returns the current user type so the UI can adjust capabilities. |

## Quick Start (Visitor Mode)

### Step 1: Initialize the SDK

Start by setting up the social.plus client with your API key:


```swift iOS
let client = try! AmityClient(apiKey: "your-api-key", region: .SG)
```

```kotlin Android
AmityCoreClient.setup(
    apiKey = "your-api-key",
    endpoint = AmityEndpoint.SG
)
```

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');
```


### Step 2: Get Visitor Device ID

Generate or retrieve a unique device identifier for the visitor:


```swift iOS
let deviceId = client.getVisitorDeviceId()
print("Device ID: \(deviceId)")
```

```kotlin Android
val deviceId = AmityCoreClient.getVisitorDeviceId()
Log.d("Visitor", "Device ID: $deviceId")
```

```typescript TypeScript

const client = Client.createClient('your-api-key', 'sg');
const deviceId = await client.getVisitorDeviceId();

console.log('Device ID:', deviceId);
```


  The device ID is automatically generated and cached on first access. This unique identifier is used to track the visitor session.

### Step 3: Login as Visitor

Authenticate as an anonymous visitor to access public content:


```swift iOS
Task { @MainActor in
    do {
        // Simple visitor login (development)
        try await client.loginAsVisitor(
            authSignature: nil,
            authSignatureExpiresAt: nil,
            sessionHandler: sessionHandler
        )
        print("Visitor login successful")
    } catch {
        print("Visitor login failed: \(error)")
    }
}
```

```kotlin Android
// Simple visitor login (development)
AmityCoreClient.loginAsVisitor(sessionHandler)
    .build()
    .submit()
    .doOnComplete {
        // Visitor login successful
    }
    .doOnError { error ->
        // Visitor login failed
    }
    .subscribe()
```

```typescript TypeScript
try {
    // Simple visitor login (development)
    await Client.loginAsVisitor({ sessionHandler });
    console.log('Visitor login successful');
} catch (error) {
    console.error('Visitor login failed:', error);
}
```


### Step 4: Login as Bot (TypeScript Only)

For search engine crawlers and automated indexers:


```typescript TypeScript
try {
    await Client.loginAsBot({ sessionHandler });
    console.log('Bot login successful');
} catch (error) {
    console.error('Bot login failed:', error);
}
```


  Bot login is automatically determined by User-Agent analysis on the server. Use this method when you need explicit bot role assignment.

### Step 5: Check User Type

Verify the current user type to adapt your UI accordingly:


```swift iOS
let userType = client.currentUserType
switch userType {
case .signedIn:
    print("User is authenticated")
case .visitor:
    print("User is a visitor")
case .bot:
    print("User is a bot")
}
```

```kotlin Android
val userType = AmityCoreClient.getCurrentUserType()
when (userType) {
    AmityUserType.SIGNED_IN -> Log.d("Auth", "User is authenticated")
    AmityUserType.VISITOR -> Log.d("Auth", "User is a visitor")
    AmityUserType.BOT -> Log.d("Auth", "User is a bot")
}
```

```typescript TypeScript
import { Client, UserTypeEnum } from '@amityco/ts-sdk';

const userType = Client.getCurrentUserType();
switch (userType) {
    case UserTypeEnum.SIGNED_IN:
        console.log('User is authenticated');
        break;
    case UserTypeEnum.VISITOR:
        console.log('User is a visitor');
        break;
    case UserTypeEnum.BOT:
        console.log('User is a bot');
        break;
}
```


### Step 6: Logout

End the visitor session:


```swift iOS
do {
    try await client.secureLogout()
} catch {
    /// Handle error from revoking accessToken here
}
```

```kotlin Android
AmityCoreClient.secureLogout()
    .doOnComplete {
        // Void
    }
    .doOnError {
        // Exception
    }
    .subscribe()
```

```typescript TypeScript
const handleSecureLogout = async () => {
  await Client.secureLogout();
};

handleSecureLogout();
```


## Secure Visitor Mode (Production)

For production environments, secure visitor mode adds an extra layer of authentication by requiring cryptographic signatures for visitor sessions. Once secure mode is enabled, all visitor login requests must include a valid auth signature generated by your backend server.

  **Secure visitor mode is not enabled by default.** Even if visitor mode is enabled, secure mode must be enabled separately. Contact [support@social.plus](mailto:support@social.plus) to enable secure visitor mode for your network.

### Getting Your Visitor Secret

After visitor secure mode is enabled for your network, retrieve your visitor application secret from the Console:

    Open your social.plus Console and go to **Settings** → **Integrations**
    Scroll to the **Visitor Secure Mode Setup** section (visible only after visitor secure mode is enabled)
    Create new secret and store it securely in your backend environment variables

  **Security Best Practice:** Never expose your **secret** in client-side code, mobile apps, or version control. This secret must remain on your backend server only.

### Backend Auth Signature Generation

Your backend server must generate time-limited auth signatures using HMAC-SHA256 encryption:


```javascript
// Complete Express.js backend example
const express = require('express');
const crypto = require('crypto');
require('dotenv').config();

const app = express();
const PORT = process.env.PORT || 3000;

// Middleware to parse JSON request bodies
app.use(express.json());

// Visitor auth signature endpoint
app.post('/api/visitor/auth-signature', async (req, res) => {
  try {
    const { deviceId } = req.body;

    // Set expiration (e.g., 1 hour from now)
    const authSignatureExpiresAt = new Date(Date.now() + 3600000).toISOString();

    // Create signature using HMAC-SHA256 with your visitor secret
    const message = `deviceId=${deviceId}&authSignatureExpiresAt=${authSignatureExpiresAt}`;
    const authSignature = crypto
      .createHmac('sha256', process.env.SOCIAL_PLUS_VISITOR_APP_SECRET)
      .update(message)
      .digest('hex');

    res.json({
      authSignature,
      authSignatureExpiresAt
    });
  } catch (error) {
    console.error('Error generating auth signature:', error);
    res.status(500).json({ error: 'Failed to generate auth signature' });
  }
});

// Start server
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
```


**Setup Instructions:**

1. Install dependencies:

```bash
npm install express dotenv
```

2. Create a `.env` file in your project root:

```env
SOCIAL_PLUS_VISITOR_APP_SECRET=your_visitor_secret_from_console
PORT=3000
```

3. Run the server:

```bash
node server.js
```

  **How It Works:** The signature is created by hashing the device ID and expiration timestamp with your secret key. social.plus servers verify the signature using the same secret, ensuring the request originated from your trusted backend.

### Secure Visitor Login

Use auth signatures for production visitor sessions. Obtain `authSignature` via the API implemented in the previous step, and provide the corresponding values to the `loginAsVisitor()` function.


```swift iOS
Task { @MainActor in
    do {
        // Get device ID
        let deviceId = client.getVisitorDeviceId()

        // Request auth signature from your backend
        let (signature, expiresAt) = try await fetchAuthSignature(deviceId: deviceId)

        // Login with secure mode
        try await client.loginAsVisitor(
            authSignature: signature,
            authSignatureExpiresAt: expiresAt,
            sessionHandler: sessionHandler
        )
        print("Secure visitor login successful")
    } catch {
        print("Secure visitor login failed: \(error)")
    }
}
```

```kotlin Android
val deviceId = AmityCoreClient.getVisitorDeviceId()

// Request auth signature from your backend
fetchAuthSignature(deviceId) { signature, expiresAt ->
    AmityCoreClient.loginAsVisitor(sessionHandler)
        .authSignature(signature)
        .authSignatureExpiresAt(expiresAt)
        .build()
        .submit()
        .doOnComplete {
            // Secure visitor login successful
        }
        .doOnError { error ->
            // Secure visitor login failed
        }
        .subscribe()
}
```

```typescript TypeScript
try {
    const deviceId = await client.getVisitorDeviceId();

    // Request auth signature from your backend
    const { authSignature, authSignatureExpiresAt } =
        await fetchAuthSignature(deviceId);

    // Login with secure mode
    await Client.loginAsVisitor({
        authSignature,
        authSignatureExpiresAt,
        sessionHandler,
    });
    console.log('Secure visitor login successful');
} catch (error) {
    console.error('Secure visitor login failed:', error);
}
```


### Session Handler for Token Renewal

Implement session handlers to automatically refresh auth signatures:


```swift
class VisitorSessionHandler: SessionHandler {
    func sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        let deviceId = client.getVisitorDeviceId()

        Task {
            do {
                // Fetch new auth signature from your backend
                let (signature, expiresAt) = try await fetchAuthSignature(deviceId: deviceId)
                renewal.renewWithAuthSignature(
                    authSignature: signature,
                    authSignatureExpiresAt: expiresAt
                )
            } catch {
                print("Failed to refresh visitor token: \(error)")
                renewal.unableToRetrieveAuthSignature()
            }
        }
    }
}

// Use during visitor login
let sessionHandler = VisitorSessionHandler()
try await client.loginAsVisitor(
    authSignature: signature,
    authSignatureExpiresAt: expiresAt,
    sessionHandler: sessionHandler
)
```


```kotlin
class VisitorSessionHandler : SessionHandler {
    override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
        val deviceId = AmityCoreClient.getVisitorDeviceId()

        // Fetch new auth signature from your backend
        authRepository.fetchVisitorAuthSignature(deviceId) { authData ->
            if (authData != null) {
                renewal.renewWithAuthSignature(
                    authData.signature,
                    authData.expiresAt
                )
            } else {
                renewal.unableToRetrieveAuthToken()
            }
        }
    }
}

// Use during visitor login
val sessionHandler = VisitorSessionHandler()
AmityCoreClient.loginAsVisitor(sessionHandler)
    .authSignature(signature)
    .authSignatureExpiresAt(expiresAt)
    .build()
    .submit()
```


```typescript
const createVisitorSessionHandler = (): Amity.SessionHandler => ({
    sessionWillRenewAccessToken: async (renewal: Amity.AccessTokenRenewal) => {
        try {
            const deviceId = await client.getVisitorDeviceId();

            // Fetch new auth signature from your backend
            const { authSignature, authSignatureExpiresAt } =
                await AuthService.fetchVisitorAuthSignature(deviceId);

            renewal.renewWithAuthSignature({ authSignature, authSignatureExpiresAt });
        } catch (error) {
            console.error('Failed to refresh visitor token:', error);
            renewal.unableToRetrieveAuthSignature();
        }
    }
});

// Use during visitor login
await Client.loginAsVisitor({
    authSignature,
    authSignatureExpiresAt,
    sessionHandler: createVisitorSessionHandler(),
});
```


## Understanding Visitor Permissions

Visitor and bot users have **server-side enforced read-only permissions** to protect community integrity:

    - View public posts and content
    - Browse public communities
    - View user profiles
    - View comments and replies
    - View post reactions
    - Access public media (images, videos)

    - Create posts or stories
    - Comment or reply
    - React to posts/comments
    - Join communities
    - Follow/unfollow users
    - Report content or users
    - Send messages
    - Receive push notifications
    - Real-time event connections (MQTT)

### Permission Enforcement

All visitor restrictions are enforced **server-side** - attempting restricted actions will result in permission errors:


```typescript Error Codes
// TypeScript and Android server error codes for visitor/bot permission denial
ServerError.VISITOR_PERMISSION_DENIED: 403999
ServerError.BOT_PERMISSION_DENIED: 403998
```

```typescript Example Error Handling
try {
    await createPost({ text: 'Hello world' });
} catch (error) {
    if (String(error).includes('403999')) {
        // Show visitor upgrade prompt
        showVisitorWarning('Create an account or sign in to post');
    }
}
```


### Resource Conservation

Visitors and bots are excluded from resource-intensive features:

    **MQTT Connection**: Disabled for visitors/bots

    - No real-time event subscriptions
    - No live updates or notifications
    - Reduces server load and connection costs
    - Does not count towards CCU (Concurrent Connection Users) limits


```typescript
// SDK automatically skips MQTT connection for visitors
const userType = Client.getCurrentUserType();
if (userType === UserTypeEnum.VISITOR || userType === UserTypeEnum.BOT) {
    // mqtt.connect() is NOT called
}
```

    **Push Notifications**: Blocked for visitors/bots

    - Cannot register device tokens
    - Filtered out from notification recipient lists
    - Applies to all notification types
    - Prevents unpredictable costs from anonymous audience


```typescript
// Push notification registration is blocked
import { Client, UserTypeEnum } from '@amityco/ts-sdk';

const userType = Client.getCurrentUserType();
if (userType === UserTypeEnum.VISITOR || userType === UserTypeEnum.BOT) {
    // registerPushNotification() throws error or no-ops
}
```

    **User Listing/Search**: Hidden from results

    - Excluded from user search APIs
    - Not visible in followers/following lists
    - Hidden from user discovery features
    - Maintains authentic member directories


```typescript
// Visitors are automatically filtered from user queries
// Your queries return only signed-in users
const unsubscribe = UserRepository.searchUsers(
  { displayName: 'John' },
  ({ data: users }) => {
    // users contains only SIGNED_IN users, no VISITOR or BOT users
  },
);
```


## Daily Usage Limit

Visitor and bot users share a **daily read request quota**. Once the quota is exhausted, all subsequent read API calls return error code `400323` until the quota resets.

  The quota is shared across all read endpoints — feed, events, communities, user profiles, and so on — and its size is a network-level setting. The counter resets daily. Monthly overages are a billing concern only; the SDK never receives a monthly-limit error.

### Error Code

| Error Constant | TypeScript / Android Code | iOS Code | Trigger |
| --- | --- | --- | --- |
| `VISITOR_USAGE_LIMIT_EXCEEDED` | `400323` | `.visitorUsageLimitExceeded` / `400323` | Visitor/bot has exhausted their daily read quota |
| `VISITOR_PERMISSION_DENIED` | `403999` | `.visitorPermissionDenied` / `488999` | Visitor attempted a restricted operation |
| `BOT_PERMISSION_DENIED` | `403998` | `.botPermissionDenied` / `488998` | Bot attempted a restricted operation |

### SDK Event Subscription

The Android and TypeScript SDKs emit a visitor usage-limit event the first time error `400323` is detected per session. Subsequent failures within a 2-second window are deduplicated to avoid triggering the handler on simultaneous parallel requests.


```kotlin
// Subscribe to usage limit events after visitor login
AmityCoreClient.getVisitorUsageLimitEvents()
    .observeOn(AndroidSchedulers.mainThread())
    .doOnNext { event ->
        // Navigate to sign-in or show custom error UI
        Log.d("Visitor", "Usage limit reached for user: ${event.userId}")
    }
    .subscribe()
```


```typescript
import { Client } from '@amityco/ts-sdk';

// Subscribe to usage limit events after visitor login
const unsubscribe = Client.onVisitorUsageLimitReached(() => {
    // Navigate to sign-in or show custom error UI
    console.log('Visitor usage limit reached');
});

// Unsubscribe when cleaning up
// unsubscribe();
```


  The event is only emitted for `VISITOR` and `BOT` user types. Signed-in users never receive this event.

## Data Management & Lifecycle

### Guest User Data Cleanup

social.plus automatically removes the data of inactive guest users, so transient visitor records don't accumulate. This runs on the backend with no integrator action required, and it supports privacy compliance (such as GDPR). Actively-returning visitors keep their data, and a visitor who signs up (converts) keeps their history.

  **Event Availability**: Guest user events are available through existing webhook/event observation mechanisms configured in your social.plus console.

## Implementation Best Practices

### Visitor Mode Strategy

    **Recommended Scenarios:**

    1. **Public Content Discovery**
       - Community showcases and landing pages
       - SEO-optimized public content
       - Growth funnel entry points
       - Social media linked content
    2. **Conversion Optimization**
       - Allow browsing before signup
       - Demonstrate community value
       - Reduce friction in user journey
       - Track engagement before conversion
    3. **SEO & Indexing**
       - Enable search engine crawling
       - Improve content discoverability
       - Separate bot traffic from analytics
       - Optimize for organic search

    **Implementation Tips:**

    - Set clear upgrade prompts for interactive features
    - Track visitor-to-member conversion rates
    - Monitor guest traffic patterns
    - Use analytics to optimize conversion flow

    **Require Sign-In For:**

    1. **Private/Sensitive Content**
       - Member-only communities
       - Personal conversations
       - Restricted content
       - Premium features
    2. **High-Value Interactions**
       - Content creation
       - Community moderation
       - Direct messaging
       - Transaction-based features
    3. **Compliance Requirements**
       - Age-restricted content
       - Regulated industries
       - Terms of service acceptance
       - User accountability needs

### Security Considerations

    **Always Use Secure Mode in Production:**


```typescript
// ✅ Production: Secure visitor mode with auth signatures
await Client.loginAsVisitor({
  authSignature,        // Generated by your backend
  authSignatureExpiresAt, // With proper expiration
  sessionHandler,       // With token renewal logic
});

// ❌ Development only: Simple visitor mode
await Client.loginAsVisitor({ sessionHandler }); // No auth signature
```


    **Why Secure Mode?**

    - Prevents unauthorized visitor creation
    - Enables server verification of device identity
    - Supports automatic token renewal
    - Maintains audit trail of visitor sessions

    **Privacy-conscious approach:**

    - Visitor device IDs are pseudonymous SDK identifiers
    - Visitor mode does not require a signed-in user profile
    - Automatic cleanup of inactive visitors
    - Your app remains responsible for its own privacy notice and consent requirements

    **Best Practices:**

    - Disclose visitor tracking in privacy policy
    - Provide opt-out mechanisms where required
    - Use device IDs only for platform functionality
    - Don't link device IDs to external identifiers

## Troubleshooting

    **Symptoms**: Cannot login as visitor, permission denied errors

    **Solutions**:

    1. **Verify visitor mode is enabled** - Contact [support@social.plus](mailto:support@social.plus) if visitor mode has not been enabled for your network
    2. Check API key has visitor access permissions
    3. Ensure you're using correct region endpoint
    4. For secure mode, verify visitor secure mode is enabled for your network
    5. For secure mode, verify auth signature is correctly generated
    6. Check auth signature hasn't expired

## Next Steps

    Learn about authenticated user login and session management

    Understand user profiles and member management

    Configure community permissions and access levels

    Track visitor metrics and conversion analytics in the Console

---

### [Android](https://learn.social.plus/social-plus-sdk/getting-started/platform-setup/mobile/android-quick-start)

> Get up and running with social.plus Android SDK for Kotlin/Java applications in minutes.

Get your Android app connected to social.plus in just a few steps. This guide covers everything from installation to your first authenticated session.

## Requirements

- Android 6.0 (API 23)+
- Target SDK 36+
- Compile SDK 36+
- JVM target 1.8
- Kotlin 2.2.0+

## Installation

Add the SDK to your project using your preferred repository:


Add Maven Central to your project-level `build.gradle`:

```gradle Gradle 6.8+
dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}
```

```gradle Gradle 6.7 and below
allprojects {
    repositories {
        mavenCentral()
    }
}
```

Add the dependency to your module-level `build.gradle`:


{/* doc-as-test: skip(build-script: Gradle DSL fragment, not runtime Kotlin) */}
```kotlin Gradle (Kotlin DSL)
implementation("co.amity.android:amity-sdk:x.y.z")
```

```gradle Gradle (Groovy)
implementation 'co.amity.android:amity-sdk:x.y.z'
```


Replace `x.y.z` with the [latest version number](https://github.com/AmityCo/Amity-Social-Cloud-Android-SDK/releases).

If your minSDKVersion is below 24, there are additional configurations required. In your project build.gradle:
```
buildscript {
    repositories {
        google()
        gradlePluginPortal()
        ...
    }
    dependencies {
        ...
        classpath 'gradle.plugin.com.github.sgtsilvio.gradle:android-retrofix:0.4.1'
    }
}
```


Add Jitpack to your project-level `build.gradle`:

```gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}
```

Add the dependency:

```gradle
implementation 'com.github.AmityCo:Amity-Social-Cloud-Android-SDK:x.y.z'
```

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Initialize SDK | API key | Yes | Application API key from the social.plus Console. |
| Initialize SDK | Endpoint | No | Region endpoint such as `AmityEndpoint.US`, `EU`, or `SG`; SG is the default when omitted. |
| Initialize SDK with encryption | `dbEncryption` | No | Database encryption mode: `NONE`, `AUTH`, or `ALL`. |
| Initialize SDK with encryption | Encryption key | Required when encryption is enabled | Stable key bytes supplied to the selected database encryption mode. |
| Build configuration | SDK version | Yes | Android SDK version in the Gradle dependency declaration. |

## Initialize the SDK

Set up the client with your API key so the SDK is ready for authentication - highly recommended to do this on the application class.

```kotlin Android
AmityCoreClient.setup(apiKey = "YOUR_API_KEY")
```

  This creates the SDK client but does not yet authenticate a user. See [Authentication](/social-plus-sdk/getting-started/authentication) for the next step.

## Configuration

### Managing conflicting file generation
In your app module's build.gradle,  add the following packaging options.
```gradle
android {
    ...
    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}
```

### ProGuard Rules

If using ProGuard, add these rules to your `proguard-rules.pro`:

```pro
-keep class com.ekoapp.ekosdk.** { *; }
-keep interface com.ekoapp.ekosdk.** { *; }
-keep enum com.ekoapp.ekosdk.** { *; }
-keep class com.amity.socialcloud.** { *; }
-keep interface com.amity.socialcloud.** { *; }
-keep enum com.amity.socialcloud.** { *; }
-keep class co.amity.rxupload.** { *; }
```

If you are using the SDK version below 6.9.0. If you'd like to pass an Amity Serializable Object such as AmityPost, AmityMessage, etc. You will need to add ProGuard rules below:

```pro
-keepclassmembers class * implements java.io.Serializable {
    private static final java.io.ObjectStreamField[] serialPersistentFields;
    private void writeObject(java.io.ObjectOutputStream);
    private void readObject(java.io.ObjectInputStream);
    java.lang.Object writeReplace();
    java.lang.Object readResolve();
}
```

### Log Visibility Configuration
To control log visibility, add the following to your `build.gradle`:

```gradle
android {
    defaultConfig {
        resValue 'bool', "IS_HIDDEN_AMITY_LOG", "true"
        …
    }
    …
}
```

## Database Encryption (Optional)

The SDK does not employ database encryption by default. The database file is solely restricted to the application by the operating system, which is generally sufficient for most use cases.

Database encryption serves as an additional layer of security in the event of compromised root access. **Important**: Enabling database encryption may lead to a performance reduction of up to 15% during database read/write operations.

### Encryption Modes

**No Encryption**
Default mode with no encryption applied. Best performance.

**Token Security**
Access token storage is encrypted. **Recommended** for balanced security.

**Full Encryption**
All database files are encrypted. Maximum security.

**AUTH mode is recommended** to introduce extra security with minimal performance compromise. Choose the encryption mode that aligns with your application's specific requirements.

### Implementation


```kotlin
fun setupWithDatabaseEncryption(encryptionKey: String) {
    AmityCoreClient.setup(
        apiKey = "your-api-key",
        dbEncryption = AmityDBEncryption.AUTH(encryptionKey.toByteArray())
    )
}
```


```kotlin
fun setupWithFullEncryption(encryptionKey: String) {
    AmityCoreClient.setup(
        apiKey = "your-api-key",
        dbEncryption = AmityDBEncryption.ALL(encryptionKey.toByteArray())
    )
}
```


```kotlin
fun setupWithoutEncryption() {
    AmityCoreClient.setup(
        apiKey = "your-api-key",
        dbEncryption = AmityDBEncryption.NONE
    )
}
```


### Encryption Key Management

Enabling database encryption requires an encryption key. **You must consistently pass the same key** to the SDK. If a new key is supplied, the existing database will be erased and regenerated with the new key.

The level of security depends on your key generation and storage method. Follow industry standards for both key storage and generation.

**Add the security library dependency:**

```gradle
implementation 'androidx.security:security-crypto:1.1.0-alpha06'
```

**Secure key implementation:**


{/* doc-as-test: skip(android: uses EncryptedSharedPreferences/MasterKeys not in compile classpath) */}
```kotlin
private fun getEncryptionKey(context: Context): String {
    // Use androidx.security:security-crypto to store generated key
    val securedSharedPreferences = EncryptedSharedPreferences.create(
        "amity_encrypted_shared_prefs",
        MasterKeys.getOrCreate(MasterKeys.AES256_GCM_SPEC),
        context,
        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
    )

    val cachedKey = securedSharedPreferences.getString("amity_key", null)
    return if (cachedKey != null) {
        cachedKey
    } else {
        // Generate AES 256-bit key
        val keyGen = KeyGenerator.getInstance("AES")
        keyGen.init(256)
        val key = keyGen.generateKey()
        val encodedKey = key.encoded
        val generatedKey = String(Base64.encode(encodedKey, Base64.DEFAULT))

        // Store the key securely
        securedSharedPreferences.edit()
            .putString("amity_key", generatedKey)
            .apply()

        generatedKey
    }
}
```


**Usage in your Application class:**


{/* doc-as-test: skip(android-ui: Application class body, not standalone function) */}
```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Get or generate encryption key
        val encryptionKey = getEncryptionKey(this)

        // Setup SDK with encryption
        AmityCoreClient.setup(
            apiKey = "your-api-key",
            endpoint = AmityEndpoint.SG,
            dbEncryption = AmityDBEncryption.AUTH(encryptionKey.toByteArray())
        )
    }
}
```


### Performance Considerations

**Performance Impact**: Database encryption adds computational overhead. Consider these factors:

- **AUTH mode**: ~5-8% performance impact
- **ALL mode**: ~10-15% performance impact
- **Battery usage**: Slightly increased due to encryption/decryption operations
- **Storage**: Minimal impact on storage size

## Next Steps

Learn about session management and secure authentication flows

Start building chat and messaging features

Add posts, feeds, and social interactions

Implement live video and streaming features

## Troubleshooting

**Dependency conflicts**: Use the latest versions and ensure all Amity dependencies use the same version

**ProGuard issues**: Make sure you've added the required ProGuard rules

**Minimum SDK version**: Ensure your app's minimum SDK is at least API 23

**SDK not initialized**: Make sure you call `AmityCoreClient.setup()` in your Application class

**Authentication failures**: Verify your API key and region settings

**Network errors**: Check internet permissions and network connectivity

**Missing RxJava**: The SDK uses RxJava 2&3 - ensure you have the dependency added

**Threading issues**: Use `.subscribeOn(Schedulers.io())` for background operations

**Memory leaks**: Always dispose of your subscriptions in onDestroy()

---

### [Flutter](https://learn.social.plus/social-plus-sdk/getting-started/platform-setup/mobile/flutter-quick-start)

> Get up and running with social.plus Flutter SDK for cross-platform applications in minutes.

Get your Flutter app connected to social.plus in just a few steps. This guide covers everything from installation to your first authenticated session.

## Requirements

- Flutter 3.0.0 - 4.0.0
- Dart SDK >=3.0.0 <4.0.0
- iOS 12.0+ / Android 4.4 (API 19)+

## Installation

Add the social.plus SDK to your `pubspec.yaml`:

```yaml
dependencies:
  flutter:
    sdk: flutter
  amity_sdk: ^x.y.z  # Check latest version
```

Run the installation command:

```bash
flutter pub get
```

`pubspec.yaml` via pub.dev is the only supported installation method for the social.plus Flutter SDK. Find the latest version at [pub.dev/packages/amity_sdk](https://pub.dev/packages/amity_sdk). If you need to pin to a specific version or git ref, use Dart's standard [git-dependency syntax](https://dart.dev/tools/pub/dependencies#git-packages) in `pubspec.yaml` — no separate alternative install path is required.

## Project Configuration

Before you initialize the Flutter SDK, make sure the generated iOS and Android projects meet the native platform requirements.

These native settings usually only need to be configured once per app, but they must be in place before you run the SDK on a device or simulator.

After changing either native project configuration, rerun `flutter pub get` and rebuild the app so the generated platform projects pick up the updated settings.

Use the native Flutter project files below as your source of truth for these platform-level settings.

### iOS Configuration

Set the minimum iOS deployment target in `ios/Podfile`. The Flutter SDK example project uses a Podfile with the standard Flutter target setup, and you should set the platform version explicitly before running `pod install`.

```ruby Podfile
platform :ios, '12.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end
```

The Flutter SDK example Podfile includes the standard Runner target and leaves the `platform` line commented as `12.0`; set it explicitly in your app so CocoaPods resolves the SDK against the correct deployment target.

### Android Configuration

Keep your Android minimum SDK at Android 4.4 / API 19 or higher. The Flutter SDK example app inherits Flutter's default through `flutter.minSdkVersion`, so set an explicit value if your project overrides that default.

```groovy build.gradle
android {
    defaultConfig {
        applicationId "com.example.example"
        minSdkVersion 19
        targetSdkVersion flutter.targetSdkVersion
        versionCode flutterVersionCode.toInteger()
        versionName flutterVersionName
    }
}
```

The Flutter SDK example app uses `minSdkVersion flutter.minSdkVersion` in `example/android/app/build.gradle`; if you override it in your own app, keep the value at 19 or above to match the SDK requirements.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Install SDK | Package version | Yes | `amity_sdk` version declared in `pubspec.yaml`. |
| Initialize SDK | API key | Yes | Application API key from the social.plus Console. |
| Initialize SDK | Endpoint | No | Region endpoint passed through `AmityCoreClientOption` where your app needs a non-default region. |
| Native project setup | iOS deployment target | Yes | Minimum iOS version in `ios/Podfile`; keep it at 12.0 or above. |
| Native project setup | Android min SDK | Yes | Android minimum SDK version; keep it at API 19 or above. |

## Initialize the SDK

Create the client with your API key so the SDK is ready for authentication.

```dart Flutter
Future<void> initializeSDK() async {
  await AmityCoreClient.setup(
    option: AmityCoreClientOption.create(
      apiKey: 'YOUR_API_KEY',
    ),
  );
}
```

  This creates the SDK client but does not yet authenticate a user. See [Authentication](/social-plus-sdk/getting-started/authentication) for the next step.

## Next Steps

Learn about session management and secure authentication flows

Start building chat and messaging features

Add posts, feeds, and social interactions

Implement live video and streaming features

## Troubleshooting

**Package not found**: Make sure you've added the correct package name to pubspec.yaml

**Version conflicts**: Use `flutter pub deps` to check for dependency conflicts

**Build errors**: Run `flutter clean` and `flutter pub get` to refresh dependencies

**SDK not initialized**: Make sure you call `AmityCoreClient.setup()` before using any SDK features

**Authentication failures**: Verify your API key and region settings

**Session state issues**: Ensure you're properly listening to session state changes

**iOS build fails**: Ensure minimum iOS version is set to 12.0+

**Android build fails**: Check that minimum SDK is set to 19+

---

### [iOS](https://learn.social.plus/social-plus-sdk/getting-started/platform-setup/mobile/ios-quick-start)

> Get up and running with social.plus iOS SDK for Swift applications in minutes.

Get your iOS app connected to social.plus in just a few steps. This guide covers everything from installation to your first authenticated session.

## Requirements

- Xcode 26.0+
- iOS 14.0+
- Swift 5.0+

## Installation

    Add the social.plus SDK to your project using Swift Package Manager:

    1. In Xcode, select **File** → **Add Package Dependencies**
    2. Enter the repository URL:

```
https://github.com/AmityCo/Amity-Social-Cloud-SDK-iOS-SwiftPM
```
    3. Select **Up to Next Major Version** and click **Add Package**
    4. Choose **AmitySDK** and click **Add Package**

      Use "Up to Next Major Version" to ensure compatibility with future updates.
    1. [Download the latest iOS SDK](https://sdk.amity.co/sdk-release/ios/amitysdk.zip)
    2. Drag `AmitySDK.xcframework` to your project
    3. Select **Copy items if needed** and click **Finish**
    4. Set the **Embed** option to **Embed & Sign**

      For M1 Macs using the simulator, enable Rosetta mode for the application.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Initialize SDK | API key | Yes | Application API key from the social.plus Console. |
| Initialize SDK | Region | Yes | Region passed to `AmityClient`, such as `.US`, `.EU`, or `.SG`. |
| Objective-C bridge login | `userId` | Yes | Stable user identifier from your identity system. |
| Objective-C bridge login | `displayName` | No | Display name passed through the Swift bridge. |
| Objective-C bridge login | `authToken` | Production | Backend-generated auth token passed through the Swift bridge. |
| Objective-C bridge login | Completion callback | Yes | Callback that reports success or failure back to Objective-C. |

## Initialize the SDK

Create the client with your API key and region so the SDK is ready for authentication.

```swift iOS
import AmitySDK

let client = try! AmityClient(apiKey: "YOUR_API_KEY", region: .SG)
```

  This creates the SDK client but does not yet authenticate a user. See [Authentication](/social-plus-sdk/getting-started/authentication) for the next step.

## Objective-C Integration

  Starting with v6.0.0, AmitySDK for iOS is written in **Pure Swift**. You can still use it in Objective-C projects by creating a **Mixed-Language Project**.

  We recommend integrating AmitySDK directly into your Objective-C project and using **Swift language** to call the SDK interfaces for better compatibility and performance.

### Mixed Language Project Setup

Create Swift files with necessary interfaces/methods that interact with AmitySDK. These interfaces should be exposed with `@objc` or `@objcMembers` attributes.

When you add a new Swift file to your Objective-C project, Xcode automatically generates a bridging header file that exposes your Swift code to Objective-C.

  📖 **Learn More**: [Importing Swift into Objective-C - Apple Developer](https://developer.apple.com/documentation/swift/importing-swift-into-objective-c)

### Implementation Example

    Create a Swift file that wraps AmitySDK functionality:


```swift
// SDKLoginManager.swift
// Example of a Swift file which contains a class to interact with AmitySDK

import AmitySDK

class NoopSessionHandler: SessionHandler {
    func sessionWillRenewAccessToken(renewal: any AccessTokenRenewal) {}
}

@objc class SDKLoginManager: NSObject {

    let client: AmityClient?

    @objc init(apiKey: String) {
        self.client = try? AmityClient(apiKey: apiKey)
    }

    @objc func login(userId: String, displayName: String, authToken: String, completion: @escaping (Bool, Error?) -> Void) {
        Task {
            do {
                try await self.client?.login(
                    userId: userId,
                    displayName: displayName.isEmpty ? nil : displayName,
                    authToken: authToken.isEmpty ? nil : authToken,
                    sessionHandler: NoopSessionHandler()
                )
                completion(true, nil)
            } catch {
                completion(false, error)
            }
        }
    }

    @objc func logout() {
        Task { try? await self.client?.secureLogout() }
    }

    @objc func isLoggedIn() -> Bool {
        guard let state = self.client?.sessionState else { return false }
        if case .established = state { return true }
        return false
    }

    @objc func getCurrentUserId() -> String? {
        return self.client?.currentUserId ?? nil
    }
}
```

    Use the Swift bridge in your Objective-C code:

```objc
// ViewController.m
#import "ViewController.h"
#import "YourProjectName-Swift.h" // <- This import exposes your Swift file

@interface ViewController ()
@property (nonatomic, strong) SDKLoginManager *loginManager;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // Initialize the SDK manager
    self.loginManager = [[SDKLoginManager alloc] initWithApiKey:@"your-api-key"];
}

- (void)performLogin {
    [self.loginManager loginWithUserId:@"user-123"
                           displayName:@"John Doe"
                             authToken:@"your-auth-token"
                            completion:^(BOOL isSuccess, NSError * _Nullable error) {

        dispatch_async(dispatch_get_main_queue(), ^{
            if (isSuccess) {
                NSLog(@"Login successful");
                // Navigate to main app
                [self showMainApp];
            } else {
                NSLog(@"Login failed: %@", error.localizedDescription);
                // Show error message
                [self showErrorAlert:error.localizedDescription];
            }
        });
    }];
}

- (void)performLogout {
    [self.loginManager logout];
    NSLog(@"User logged out");
}

- (void)checkLoginStatus {
    if ([self.loginManager isLoggedIn]) {
        NSString *userId = [self.loginManager getCurrentUserId];
        NSLog(@"User is logged in: %@", userId);
    } else {
        NSLog(@"User is not logged in");
    }
}

// Helper methods
- (void)showMainApp {
    // Your navigation logic here
}

- (void)showErrorAlert:(NSString *)message {
    UIAlertController *alert = [UIAlertController alertControllerWithTitle:@"Login Error"
                                                                   message:message
                                                            preferredStyle:UIAlertControllerStyleAlert];

    UIAlertAction *okAction = [UIAlertAction actionWithTitle:@"OK"
                                                       style:UIAlertActionStyleDefault
                                                     handler:nil];
    [alert addAction:okAction];

    [self presentViewController:alert animated:YES completion:nil];
}

@end
```

### Key Considerations

    **Bridging Header**: Xcode automatically creates a bridging header when you add Swift files to an Objective-C project.

    **Import Statement**: Use `#import "YourProjectName-Swift.h"` to access Swift classes in Objective-C.

    **Target Membership**: Ensure your Swift files are added to the correct target.
    **Minimize Bridge Calls**: Create comprehensive wrapper methods rather than making frequent cross-language calls.

    **Error Handling**: Properly handle Swift optionals and errors in your Objective-C code.

    **Threading**: Always dispatch UI updates to the main queue when handling completion callbacks.
    **Module Not Found**: Ensure your project's module name doesn't contain special characters or spaces.

    **Swift Version**: Make sure your Objective-C project supports the Swift version used by AmitySDK.

    **Linker Errors**: Verify that both Objective-C and Swift files are properly linked to your target.

## Next Steps

    Learn about session management and secure authentication flows
    Start building chat and messaging features
    Add posts, feeds, and social interactions
    Implement live video and streaming features

## Troubleshooting

    **Framework not found**: Ensure you've added all required frameworks and set them to "Embed & Sign"

    **Swift version conflicts**: Ensure your project uses Swift 5.0 or later
    **SDK not initialized**: Make sure you call `AmityClient.setup(...)` in `application` delegate

    **Authentication failures**: Verify your API key and region settings

    **Permission denied**: Check that required permissions are added to Info.plist
    **M1 Mac Simulator Issues**: Enable Rosetta for your application in Xcode

---

### [TypeScript](https://learn.social.plus/social-plus-sdk/getting-started/platform-setup/web/web-quick-start)

> Get up and running with social.plus TypeScript SDK for web applications in minutes.

Get your web application connected to social.plus in just a few steps. This guide covers everything from installation to your first authenticated session.

## Requirements

### Browser Support

- Chrome 38+
- Firefox 42+
- Safari 9+
- Microsoft Edge 13+
- Opera 25+

Internet Explorer 11 is not supported. The SDK requires modern browser features.

### Framework Compatibility
    - Create React App
    - Next.js (client-side)
    - Vite React
    - Custom React setups

    - Vue 3 composition API
    - Vue 2 options API
    - Nuxt.js (client-side)
    - Vite Vue

    - Angular 12+
    - Angular CLI projects
    - Nx workspaces
    - Custom Angular setups

    - React Native
    - Svelte/SvelteKit
    - Solid.js
    - Lit Framework


## Installation

```bash
npm install @amityco/ts-sdk --save
```

```bash
yarn add @amityco/ts-sdk
```

```bash
pnpm add @amityco/ts-sdk
```


## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Initialize SDK | API key | Yes | Application API key from the social.plus Console. |
| Initialize SDK | Region | Yes | Region string passed to `Client.createClient`, such as `us`, `eu`, or `sg`. |
| Initialize SDK | Client options | No | Optional TypeScript client configuration, such as custom endpoints where supported. |

## Initialize the SDK

Create the client with your API key and region so the SDK is ready for authentication.

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('YOUR_API_KEY', 'sg');
```

  This creates the SDK client but does not yet authenticate a user. See [Authentication](/social-plus-sdk/getting-started/authentication) for the next step.

## Next Steps

Learn about session management and secure authentication flows

Start building chat and messaging features

Add posts, feeds, and social interactions

Implement live video and streaming features

## Troubleshooting

**Module not found**: Make sure you've installed the package correctly with your package manager

**TypeScript errors**: Ensure you're using TypeScript 3.7+ and have proper type definitions

**Build errors**: Check that your bundler supports ES6 modules and async/await

**Network failures**: Verify your API key and region settings

**Authentication errors**: Check that your auth token is valid and not expired

**Memory leaks**: Always call `Client.logout()` when your app unmounts

**Older browsers**: Make sure you've included the required polyfills

**Safari issues**: Ensure you're using HTTPS in production (required for WebRTC features)

## Core Concepts — Users

### [Overview](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/overview)

> Understand the SDK pages for user identity, user operations, roles, and moderation workflows.

User management in social.plus starts with your own identity system. Your app supplies a stable `userId`, then the SDK uses that ID for login, profile reads, profile updates, search, permissions, and moderation actions.

social.plus does not replace your account system. Keep private identity data in your backend, and send only the stable user ID plus social profile fields your product needs.

## Section Map

    Choose stable user IDs and understand which social profile fields the SDK stores.
    Create users, retrieve profiles, search users, update profiles, flag users, and manage token workflows.
    Check whether the current user can perform actions in global, channel, or community scopes.
    Add user reporting flows for moderator review.

## Implementation Flow

    Use an immutable ID from your own system, such as a database primary key or UUID.
    Call the SDK `login` method. If the `userId` does not exist yet, the SDK creates the user.
    Use user repository APIs for profile reads, search, query, and current-user profile updates.
    Use permission checks for protected actions and flagging APIs for reporting workflows.

## Quick Start

1. **[User Identity](/social-plus-sdk/core-concepts/user-management/user-identity)** - Decide what `userId` your app will send to social.plus.
2. **[Create User](/social-plus-sdk/core-concepts/user-management/user-operations/create-user)** - Log in or create the user through the SDK.
3. **[Get User Information](/social-plus-sdk/core-concepts/user-management/user-operations/get-user-information)** - Retrieve profiles for known users or user lists.
4. **[Search and Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users)** - Build user pickers, directories, or moderation lists.
5. **[Roles & Permissions](/social-plus-sdk/core-concepts/user-management/roles-permissions)** - Gate protected actions by user capability.

## Data Boundary

| Data | Owner | SDK behavior |
| --- | --- | --- |
| Login credentials, email, private profile data | Your app/backend | Keep this outside social.plus. |
| `userId` | Your app/backend | Sent to social.plus as the immutable user identifier. |
| Display name, description, avatar, metadata | social.plus stores what you send | Use only social profile fields needed by your product. |
| Roles, permissions, moderation state | social.plus and Console/API workflows | Read or check through SDK methods where available. |

---

### [User Identity](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-identity)

> Use stable user IDs with social.plus SDK while keeping private identity data in your own system.

social.plus SDK identifies each user by a `userId` that your app provides. The `userId` should be stable, unique, and non-sensitive because it becomes the SDK identity used by login, profile, search, permission, and moderation APIs.

Keep your source-of-truth account record, credentials, email address, and private profile data in your own system. Send social.plus only the stable `userId` and the social profile fields your experience needs.

## User ID Rules

| Rule | Recommendation |
| --- | --- |
| Stable | Use an ID that will not change for the lifetime of the account. |
| Unique | Use a value already guaranteed unique by your backend. |
| Non-sensitive | Avoid emails, phone numbers, or other personal identifiers. |
| Reusable across SDK calls | Use the same value for login, profile reads, search results, and moderation actions. |

## Recommended IDs

    Use database primary keys, UUIDs, or another immutable ID from your backend.

```text
userId: "12345"
userId: "user_abc123"
userId: "4f8b4c2d-9e1a-4f3a-8b7c-6d5e4f3a9910"
```
    Do not use identifiers that may change or expose private information.

```text
userId: "john.doe@example.com"
userId: "johndoe123"
userId: "john_doe"
```

After a user is created in social.plus, treat the `userId` as immutable.

## Stored Social Profile Fields

social.plus stores social profile and moderation fields that support SDK features. Avoid putting sensitive personal data in these fields.

| Field | Description |
| --- | --- |
| `userId` | Stable identifier supplied by your app. |
| `displayName` | User-facing profile name. |
| `description` | User-facing profile description or bio. |
| `metadata` | Custom social metadata. Do not store sensitive personal data here. |
| `avatarFileId` / `avatarCustomUrl` | Avatar image reference. |
| `roles` | Assigned roles for permissions and moderation workflows. |
| `flagCount` / `isFlaggedByMe` | Moderation reporting state. |
| `isGlobalBan` / `isDeleted` | Account moderation or deletion state exposed by SDK query results where available. |

## Parameters

| Operation | Input | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Initialize user repository | Initialized SDK client | Yes | TypeScript, iOS, Android, Flutter | The SDK must be initialized before user repository APIs are used. |
| Initialize user repository | User repository object or import | Yes | TypeScript, iOS, Android, Flutter | Platform-specific entry point for user reads, search, updates, and moderation operations. |
| Use user operation APIs | `userId`, display-name keyword, sort option, or paging control | Operation-dependent | TypeScript, iOS, Android, Flutter | Use the operation pages for method-specific inputs and result shapes. |

## Initialize the user repository

Initialize the user repository before calling user read, search, update, or moderation APIs.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';
```

```swift iOS
let userRepository = AmityUserRepository()
```

```kotlin Android
fun initUserRepository() {
    val userRepository = AmityCoreClient.newUserRepository()
}
```

```dart Flutter
void initUserRepository() {
  final userRepository = AmityCoreClient.newUserRepository();
}
```

## Related topics

    Log in or create a user with the stable `userId`.
    Choose the right SDK operation for user reads, updates, search, moderation, and tokens.

---

### [Roles & Permissions](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/roles-permissions)

> Check whether the current user can perform protected actions with social.plus SDK permission APIs.

Use `hasPermission` to decide whether the current user should see or perform protected actions such as deleting messages, editing community posts, or banning users. Permission checks are scope-aware: some checks are global, while others are evaluated for a channel or community.

Permissions are assigned through roles and membership state. The SDK checks the permissions already available for the current user and returns a Boolean-style result.

## Parameters

| Operation | Required inputs | Optional inputs | Platforms | Result shape |
| --- | --- | --- | --- | --- |
| Check global permission | Permission constant | None | TypeScript, iOS, Android, Flutter | Boolean or observable Boolean result. |
| Check channel permission | Permission constant, `channelId` | None | TypeScript, iOS, Android, Flutter | Boolean or observable Boolean result. |
| Check community permission | Permission constant, `communityId` | None | TypeScript, iOS, Android, Flutter | Boolean or observable Boolean result. |

## Check a permission

Use the scope that matches the action you are gating. For example, message deletion inside a channel should use a channel-scoped permission check, while community post editing should use a community-scoped check.

### Inputs

| Platform | Method | Required inputs | Result shape |
| --- | --- | --- | --- |
| TypeScript | `client.hasPermission(permission).currentUser()`, `.channel(channelId)`, or `.community(communityId)` | Permission string, optional scope ID | Returns `boolean`. |
| iOS | `client.hasPermission(permission)`, `forChannel:`, or `forCommunity:` | `AmityPermission`, optional scope ID | Returns `Bool` from an async call. |
| Android | `AmityCoreClient.hasPermission(permission).atGlobal()`, `.atChannel(channelId)`, or `.atCommunity(communityId).check()` | `AmityPermission`, optional scope ID | Returns `Flowable<Boolean>`. |
| Flutter | `AmityCoreClient.hasPermission(permission).atGlobal()`, `.atChannel(channelId)`, or `.atCommunity(communityId).check()` | `AmityPermission`, optional scope ID | Returns `bool`. |

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

const canEditCommunityPost = client
  .hasPermission('EDIT_COMMUNITY_POST')
  .community('community_123');

if (canEditCommunityPost) {
  // Enable edit controls.
}
```

```swift iOS
Task { @MainActor in
    let canDeleteMessage = await client.hasPermission(
        .deleteMessage,
        forChannel: "channel_123"
    )

    if canDeleteMessage {
        // Enable delete controls.
    }
}
```

```kotlin Android
fun checkChannelPermission() {
    AmityCoreClient.hasPermission(AmityPermission.DELETE_MESSAGE)
        .atChannel("channel_123")
        .check()
        .doOnNext { canDeleteMessage: Boolean ->
            if (canDeleteMessage) {
                // Enable delete controls.
            }
        }
        .subscribe()
}
```

```dart Flutter
void checkChannelPermission(String channelId) {
  final canMute = AmityCoreClient
      .hasPermission(AmityPermission.MUTE_USER_INSIDE_CHANNEL)
      .atChannel(channelId)
      .check();

  if (canMute) {
    // Enable mute controls.
  }
}
```

## Platform notes

- TypeScript permission checks are synchronous Boolean checks against current cached user, channel membership, or community membership data.
- iOS permission checks are async and return `Bool`.
- Android permission checks return `Flowable<Boolean>`.
- Flutter permission checks return `bool`.
- Use the permission constant that matches the action and scope. Permission names differ by platform enum casing, but they map to server permission strings such as `DELETE_MESSAGE`, `PIN_MESSAGE`, `EDIT_COMMUNITY_POST`, and `BAN_USER`.

## Related topics

    Understand the stable `userId` used by permission checks.
    Add user reporting actions for moderation workflows.

---

### [Create User](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/create-user)

> Learn how to create new users in social.plus SDK through the login method

social.plus SDK creates new users through the `login` method. A single call to `login` creates the account if the `userId` does not exist, or authenticates the user if it does.

The `login` method serves dual purposes: it creates new users when they don't exist and authenticates existing users when they do.

## How user creation works

When you call the `login` method:

1. **Existing user**: If a user exists with the specified `userId`, the SDK logs them in and optionally updates their `displayName`.
2. **New user**: If no user exists with the `userId`, the SDK creates a new account and logs them in automatically.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `userId` | Yes | TypeScript, iOS, Android, Flutter | Unique user identifier. Maximum length: 50 characters. |
| `displayName` | No | TypeScript, iOS, Android, Flutter | User-facing display name. Maximum length: 100 characters. |
| `authToken` | No | TypeScript, iOS, Android, Flutter | Secure token used when your app enables secure mode. |
| `sessionHandler` | Platform-dependent | TypeScript, iOS, Android, Flutter | Handles access-token renewal for authenticated sessions. |

## Log in or create a user

Call the platform login method with a `userId`; include `displayName`, `authToken`, and session renewal handling when your integration needs them.

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const sessionHandler: Amity.SessionHandler = {
  sessionWillRenewAccessToken(renewal) {
    renewal.renew();
  },
};

async function loginUser(userId: string, displayName?: string, authToken?: string) {
  Client.createClient('your-api-key', 'sg');

  await Client.login(
    {
      userId,
      displayName,
      authToken,
    },
    sessionHandler,
  );
}

await loginUser('user_123', 'Bob Newton');
```

```swift iOS
Task { @MainActor in
    do {
        try await client.login(
            userId: "<user-id>",
            displayName: "<(optional)-display-name>",
            authToken: "<(optional)-auth-token>",
            sessionHandler: sessionHandler
        )
        print("login success")
    } catch {
        print("login failed \(error)")
    }
}
```

```kotlin Android
fun authenticate() {
    AmityCoreClient.login(userId = "userId 1", sessionHandler = null)
        .displayName(displayName = "John Doe") // optional
        .authToken(authToken = "token") // optional
        .build()
        .submit()
        .doOnComplete {
            //success
        }
        .subscribe()
}
```

```dart Flutter
void login() async {
  await AmityCoreClient.login('userId', sessionHandler: (AccessTokenRenewal renewal) {
    renewal.renew();
  })
      .displayName('userDisplayName')
      .authToken('token') // optional
      .submit();
}
```

## Related topics

    Learn how to retrieve user data and profiles.
    Discover how to modify user profiles and settings.

---

### [Get User Information](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/get-user-information)

> Retrieve user profiles by ID, batch user lookups where supported, and query paginated user collections.

Retrieve user profiles for profile screens, user cards, and directory views with the user repository. Use the single-user API when you know the exact user ID, batch lookup when your SDK exposes `getUserByIds`, and `getUsers()` when you need a sorted list instead of a fixed set of IDs.

iOS and TypeScript expose live-object or live-collection wrappers for user observation. Android uses `Flowable<T>` for the same operations, while Flutter returns `Future<AmityUser>` for `getUser(userId)` and query builders for paginated collections.

## Parameters

This page covers three user-read operations. Use this table to choose the operation first, then use the inputs table in each section for the exact SDK call shape.

| Operation | Use when | Required inputs | Platforms |
| --- | --- | --- | --- |
| Get a single user | You already know one user ID and need that profile. | `userId` | TypeScript, iOS, Android, Flutter |
| Get multiple users by ID | You already have a fixed set of user IDs and need those profiles together. | `userIds` | TypeScript, Android |
| Query users | You need a sorted or paginated user list rather than a fixed set of IDs. | None globally; sort options vary by platform. | TypeScript, iOS, Android, Flutter |

## Get a single user

Use the single-user API when your app already knows the user ID and needs the latest profile details for that specific user. The examples below show the native return shape for each SDK.

### Inputs

| Platform | Method | Required inputs | Result shape |
| --- | --- | --- | --- |
| TypeScript | `UserRepository.getUser(userId, callback)` | `userId`, callback | Starts a live observer and returns an unsubscriber. |
| iOS | `userRepository.getUser(userId)` | `userId` | Returns a live object observed with an `AmityNotificationToken`. |
| Android | `userRepository.getUser(userId)` | `userId` | Returns `Flowable<AmityUser>`. |
| Flutter | `AmityCoreClient.newUserRepository().getUser(userId)` | `userId` | Returns `Future<AmityUser>`. |

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUser('user_123', ({ data: user, loading, error }) => {
  if (loading) return;

  if (error || !user) {
    console.error('Failed to get user', error);
    return;
  }

  console.log(user.userId, user.displayName);
});

// Call unsubscribe() when the screen no longer needs user updates.
```

```swift iOS
var token: AmityNotificationToken?

func observeUser() {
    let liveObject = userRepository.getUser("user_123")
    token = liveObject.observe { liveObject, error in
        guard let user = liveObject.snapshot else {
            print("error: \(String(describing: error))")
            return
        }

        print("userId: \(user.userId), displayName: \(String(describing: user.displayName))")
    }
}
```

```kotlin Android
fun getUser(userRepository: AmityUserRepository) {
    userRepository.getUser(userId = "user_123")
        .doOnNext { user: AmityUser ->
            val displayName = user.getDisplayName()
            val userId = user.getUserId()
            Log.d("UserRepo", "User: $displayName ($userId)")
        }
        .doOnError { error ->
            Log.e("UserRepo", "Failed to get user", error)
        }
        .subscribe()
}
```

```dart Flutter
Future<void> getUser() async {
  try {
    final user = await AmityCoreClient.newUserRepository().getUser('user_123');
    print('User: ${user.displayName}');
  } on AmityException catch (error) {
    print('Failed to get user: $error');
  }
}
```

## Get multiple users by ID

Use batch lookup when your app already has a fixed set of user IDs and needs those profiles together. This API is available on TypeScript and Android. For browse flows, use the query operation below.

### Inputs

| Platform | Method | Required inputs | Result shape |
| --- | --- | --- | --- |
| TypeScript | `UserRepository.getUserByIds(userIds)` | `userIds: string[]` | Returns a promise with cached user data. |
| Android | `userRepository.getUserByIds(userIds)` | `userIds: Set<String>` | Returns `Flowable<List<AmityUser>>`. |

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

async function getUsersByIds() {
  const userIds = ['user_123', 'user_456'];
  const { data: users } = await UserRepository.getUserByIds(userIds);

  users.forEach(user => {
    console.log(user.userId, user.displayName);
  });
}
```

```kotlin Android
fun getUsersByIds(
    userRepository: AmityUserRepository,
    userIds: Set<String>
) {
    userRepository.getUserByIds(userIds = userIds)
        .doOnNext { users: List<AmityUser> ->
            users.forEach { user ->
                Log.d("UserRepo", "User: ${user.getDisplayName()}")
            }
        }
        .doOnError { error ->
            Log.e("UserRepo", "Failed to get users", error)
        }
        .subscribe()
}
```

## Query users

Use `getUsers()` when you need a sorted, paginated user list for browse flows such as user directories, member pickers, or moderation tools. On TypeScript, the live collection callback also exposes `hasNextPage` and `onNextPage` when more results are available.

### Inputs

| Platform | Method | Required inputs | Optional inputs | Result shape |
| --- | --- | --- | --- | --- |
| TypeScript | `UserRepository.getUsers(params, callback)` | callback | `sortBy`, `limit` | Starts a live collection observer and returns an unsubscriber. |
| iOS | `userRepository.getUsers(sortBy)` | sort option | None in this call shape | Returns a live collection observed with an `AmityNotificationToken`. |
| Android | `userRepository.getUsers().build().query()` | None | `sortBy(...)` | Returns `Flowable<PagingData<AmityUser>>`. |
| Flutter | `AmityCoreClient.newUserRepository().getUsers()` | None | `sortBy(...)`, paging token, limit | Returns paging data through the query builder. |

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

let loadMoreUsers: (() => void) | undefined;

const unsubscribe = UserRepository.getUsers(
  { sortBy: 'lastCreated' },
  ({ data: users, loading, error, hasNextPage, onNextPage }) => {
    if (loading) return;

    if (error) {
      console.error('Failed to query users', error);
      return;
    }

    console.log(`Loaded ${users.length} users`);
    console.log(`More pages available: ${hasNextPage}`);
    loadMoreUsers = onNextPage;
  },
);

// Call loadMoreUsers?.() from your load-more action.
// Call unsubscribe() when the screen no longer needs user list updates.
```

```swift iOS
var token: AmityNotificationToken?

func queryUsersExample() {
    let liveCollection = userRepository.getUsers(.displayName)
    token = liveCollection.observe { collection, error in
        let users = collection.snapshots
        print("Loaded \(users.count) users")
    }
}
```

```kotlin Android
fun queryUsers(userRepository: AmityUserRepository) {
    userRepository.getUsers()
        .sortBy(sortOption = AmityUserSortOption.DISPLAYNAME) // optional
        .build()
        .query()
        .doOnNext { users: PagingData<AmityUser> ->
            // PagingData<AmityUser>
        }
        .doOnError {
            // Exception
        }
        .subscribe()
}
```

```dart Flutter
final _amityUsers = <AmityUser>[];
late PagingController<AmityUser> _amityUsersController;

void getUsers(AmityUserSortOption amityUserSortOption) {
  _amityUsersController = PagingController(
    pageFuture: (token) => AmityCoreClient.newUserRepository()
        .getUsers()
        .sortBy(amityUserSortOption)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(
      () {
        if (_amityUsersController.error == null) {
          _amityUsers.clear();
          _amityUsers.addAll(_amityUsersController.loadedItems);
        }
      },
    );
}
```

## Platform notes

- `getUserByIds(userIds)` is public on TypeScript and Android, but not on iOS or Flutter.
- TypeScript `getUser(...)` and `getUsers(...)` start live observers and return unsubscriber functions when your screen no longer needs updates.
- Android uses `Flowable<AmityUser>` for single-user observation and `Flowable<List<AmityUser>>` for batch lookup.
- Flutter `getUser(userId)` is a one-time `Future<AmityUser>`. If you need stream-based observation there, use `AmityCoreClient.newUserRepository().live.getUser(userId)`.

## Related topics

    Search users by display name and query user collections.

    Update the authenticated user's profile data.

---

### [Update User Information](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/update-user-information)

> Update the current user's display name, description, avatar, and metadata with social.plus SDK.

Use the user update APIs when the signed-in user changes their social profile. Client SDKs update the current user's profile fields; privileged edits to other users should be handled through admin or backend workflows.

Before setting an avatar file, upload the image first. See [Image Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/image-handling#image-upload) for the upload flow.

Only update fields that changed. The SDK update builders and patch objects let you send partial profile updates.

## Parameters

| Field | Required | Platforms | Description |
| --- | --- | --- | --- |
| `userId` | TypeScript and Flutter | TypeScript, Flutter | User ID for the profile being updated. Use the current user's ID for client-side updates. |
| `displayName` | No | TypeScript, iOS, Android, Flutter | User-facing profile name. |
| `description` | No | TypeScript, iOS, Android, Flutter | User-facing profile description or bio. |
| `avatarFileId` / uploaded avatar | No | TypeScript, iOS, Android, Flutter | Uploaded image reference used as the user's avatar. |
| `avatarCustomUrl` | No | TypeScript, iOS, Android, Flutter | An external image URL used as the user's avatar instead of an uploaded `avatarFileId`. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom social metadata. Do not store sensitive personal data here. |

Once `avatarCustomUrl` is set, the **UIKit renders it automatically** wherever a user's avatar appears — no extra wiring is needed. This is supported on Android UIKit 4.19.2+ and iOS UIKit 4.22.2+. When both `avatarFileId` and `avatarCustomUrl` are set, the custom URL takes precedence.

## Update the current user's profile

Call the platform update method with only the fields you want to change.

### Inputs

| Platform | Method | Required inputs | Optional inputs | Result shape |
| --- | --- | --- | --- | --- |
| TypeScript | `UserRepository.updateUser(userId, patch)` | `userId`, patch object | `displayName`, `description`, `avatarFileId`, `avatarCustomUrl`, `metadata` | Returns `Promise<Amity.Cached<Amity.User>>`. |
| iOS | `client.editUser(options)` | `AmityUserUpdateOptions` | Display name, description, avatar, avatar custom URL, metadata | Async call that throws on failure. |
| Android | `AmityCoreClient.editUser().build().apply()` | None beyond the active user session | `displayName`, `description`, `avatar`, `avatarCustomUrl`, `metadata` | Returns `Single<AmityUser>`. |
| Flutter | `AmityCoreClient.newUserRepository().updateUser(userId).update()` | `userId` | `displayName`, `description`, `avatarFileId`, `avatarCustomUrl`, `metadata`, `roles` | Returns `Future<AmityUser>`. |

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

async function updateUserProfile(userId: string) {
  const { data: user } = await UserRepository.updateUser(userId, {
    displayName: 'Batman',
    description: 'Hero that Gotham needs',
    metadata: {
      city: 'Gotham',
    },
  });

  console.log('Updated user:', user.displayName);
}
```

```swift iOS
func updateUserProfile() async {
    let options = AmityUserUpdateOptions()
    options.setDisplayName("Batman")
    options.setUserDescription("Hero that Gotham needs")
    options.setUserMetadata(["city": "Gotham"])

    do {
        try await client.editUser(options)
        print("User updated")
    } catch {
        print("Update failed: \(error)")
    }
}
```

```kotlin Android
fun updateUserProfile() {
    AmityCoreClient.editUser()
        .displayName(displayName = "Batman")
        .description(description = "Hero that Gotham needs")
        .metadata(metadata = JsonObject().apply {
            addProperty("city", "Gotham")
        })
        .build()
        .apply()
        .doOnSuccess { user: AmityUser ->
            Log.d("UserUpdate", "Updated user: ${user.getDisplayName()}")
        }
        .doOnError { error ->
            Log.e("UserUpdate", "Update failed", error)
        }
        .subscribe()
}
```

```dart Flutter
Future<void> updateUserProfile(String userId) async {
  try {
    final user = await AmityCoreClient.newUserRepository()
        .updateUser(userId)
        .displayName('Batman')
        .description('Hero that Gotham needs')
        .metadata({'city': 'Gotham'})
        .update();

    print('Updated user: ${user.displayName}');
  } on AmityException catch (error) {
    print('Update failed: ${error.message}');
  }
}
```

## Platform notes

- iOS and Android update the active user through `client.editUser(...)` / `AmityCoreClient.editUser()`.
- TypeScript and Flutter take a `userId` in the update call. In client apps, pass the current user's ID.
- iOS `setAvatar(...)` expects uploaded `AmityImageData`; Android `avatar(...)` expects uploaded `AmityImage`; TypeScript and Flutter use avatar file IDs or custom URLs.
- Do not store sensitive personal data in `metadata`.

## Related topics

    Retrieve updated user profiles.
    Choose stable user IDs and safe social profile fields.

---

### [Delete User](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/delete-user)

> Understand why user deletion is not exposed through client SDK user operations.

Client SDKs do not expose a public method to delete a user. Treat user deletion as a privileged admin or backend workflow, not as a client-side SDK operation.

Do not put user deletion credentials or privileged deletion flows in a client app.

## SDK Availability

| Surface | Availability |
| --- | --- |
| TypeScript SDK | No public delete-user method |
| iOS SDK | No public delete-user method |
| Android SDK | No public delete-user method |
| Flutter SDK | No public delete-user method |
| Admin/API workflow | Use the Console or a backend-controlled API integration. |

## Recommended Workflow

    Verify the requester is allowed to delete or deactivate the user account.
    Keep API credentials and audit logging outside the client app.
    Refresh user lists, member lists, profile views, and moderation tools after the backend operation completes.
    SDK query results may expose deleted-user state such as `isDeleted`; make your UI resilient to missing names or avatars.

## Alternatives

| Approach | Use when |
| --- | --- |
| Suspend or ban user | You need to block access without permanently deleting account data. |
| Remove or moderate content | The issue is content-specific rather than account-specific. |
| Hide user locally | You need a product-level visibility rule before a backend account decision is made. |

## Related topics

    Handle deleted-user state in profile and list views.
    Gate privileged admin and moderation actions.

---

### [Search and Query Users](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users)

> Search for users by display name and query paginated user collections in social.plus SDK.

Use the user repository when your app needs to find people by display name or browse a paginated user list. Search is for keyword-driven flows such as member pickers, while query is for directory-style lists where sorting and pagination matter more than a search keyword.

Deleted users are automatically excluded from search and query results.

## Parameters

This page covers two user-list operations. Choose the operation first, then use the inputs table in each section for the exact SDK call shape.

| Operation | Use when | Required inputs | Platforms |
| --- | --- | --- | --- |
| Search users by display name | You have a display-name keyword and want matching users. | Display-name keyword, callback or collection observer where required. | TypeScript, iOS, Android, Flutter |
| Query users | You need a paginated user list without a search keyword. | Callback or sort option where required. | TypeScript, iOS, Android, Flutter |

## Search users by display name

Use search when the user types a display-name keyword. Search keywords must be at least 3 characters long. When a keyword is provided, the server ranks matching results by search relevance; supported sort options can then control the returned order.

### Selecting which fields to match (`searchBy`)

By default the keyword is matched against **all** searchable user fields (display name, user id, and profile handle), so a keyword can surface users that match only by their user id. Provide `searchBy` to restrict which fields are matched — for example, display name only — so results exclude user-id-only matches.

- Omitting `searchBy` (or passing an empty value) keeps the default behavior, so existing integrations are unaffected.
- Supported field options: `displayName`, `userId`, `profileHandle`.

| Field | Platforms | TypeScript | iOS | Android |
| --- | --- | --- | --- | --- |
| Display name | TypeScript, iOS, Android | `SearchUsersByEnum.DISPLAY_NAME` | `.displayName` | `AmitySearchUserBy.DISPLAY_NAME` |
| User ID | TypeScript, iOS, Android | `SearchUsersByEnum.USER_ID` | `.userId` | `AmitySearchUserBy.USER_ID` |
| Profile handle | TypeScript, iOS, Android | `SearchUsersByEnum.PROFILE_HANDLE` | `.profileHandle` | `AmitySearchUserBy.PROFILE_HANDLE` |

TypeScript types `searchBy` as an array of `SearchUsersByEnum` values, exported from the package root. Plain string literals do not type-check.

Platform support for `searchBy` differs. iOS, Android, and TypeScript expose it on user search; Flutter support is not yet available.

### Inputs

| Platform | Method | Required inputs | Optional inputs | Result shape |
| --- | --- | --- | --- | --- |
| TypeScript | `UserRepository.searchUsers(params, callback)` | `displayName` (the keyword), callback | `searchBy`, `limit`, `matchType` | Starts a live collection observer and returns an unsubscriber. |
| iOS | `userRepository.searchUsers(keyword, searchBy:, sortBy:, matchType:)` | `keyword`, `searchBy`, `sortBy` | `matchType` | Returns a live collection observed with an `AmityNotificationToken`. |
| Android | `userRepository.searchUsers(keyword).build().query()` | `keyword` | `searchBy(...)`, `sortBy(...)`, `matchType(...)` | Returns `Flowable<PagingData<AmityUser>>`. |
| Flutter | `AmityCoreClient.newUserRepository().searchUserByDisplayName(keyword)` | `keyword` | `sortBy(...)`, `matchType(...)`, paging token, limit | Returns paging data through the query builder. |

TypeScript `UserRepository.searchUserByDisplayName(params, callback)` is deprecated in favour of `searchUsers(params, callback)`. Both accept the same parameters and return the same live collection, so switching is a rename. The deprecated method will be removed in a future major version.

TypeScript search parameters intentionally do not include `sortBy`; use `getUsers(...)` when you need TypeScript user-list sorting.

### Special character handling

With display-name sorting, users are sorted alphabetically by their display names using ICU collation for the English locale. This means that special characters such as Ä are treated as variants of A. For example, a sorted list might appear as: **adam, Älex, Alice, Arthur, charlie, Kristen**.

When providing a search keyword, the API performs an exact-match lookup for special characters:
- Searching for "Äli" only returns users whose display name contains "Äli", such as "Älise".
- Searching for "Alice" does not return "Älice".

Use the platform search method to retrieve users whose display name matches the search keyword.

```typescript TypeScript
import { SearchUsersByEnum, UserRepository } from '@amityco/ts-sdk';

let loadMoreUsers: (() => void) | undefined;

const unsubscribe = UserRepository.searchUsers(
  // `searchBy` is optional; omit it to match all fields.
  { displayName: 'Joe', limit: 20, searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data: users, loading, error, hasNextPage, onNextPage }) => {
    if (loading) return;

    if (error) {
      console.error('Failed to search users', error);
      return;
    }

    console.log(`Found ${users.length} users`);
    console.log(`More pages available: ${hasNextPage}`);
    loadMoreUsers = onNextPage;
  },
);

// Call loadMoreUsers?.() from your load-more action.
// Call unsubscribe() when the screen no longer needs search updates.
```

```swift iOS
var token: AmityNotificationToken?

func searchUserExample() {
    // `searchBy` selects which fields the keyword is matched against.
    // Use [.displayName] to match display name only; pass [] to keep the
    // default behavior (match all searchable fields).
    let liveCollection = userRepository.searchUsers(
        "<keyword>",
        searchBy: [.displayName],
        sortBy: .displayName,
        matchType: .default
    )
    token = liveCollection.observe { collection, error in
        let users = collection.snapshots
        print("Found \(users.count) users")
    }
}
```

```kotlin Android
fun searchUsers(userRepository: AmityUserRepository) {
    userRepository.searchUsers("Brian")
        .searchBy(listOf(AmitySearchUserBy.DISPLAY_NAME)) // optional; omit to match all fields
        .sortBy(sortOption = AmityUserSortOption.DISPLAYNAME) // optional
        .build()
        .query()
        .doOnNext { users: PagingData<AmityUser> ->
            // PagingData<AmityUser>
        }
        .doOnError { error ->
            Log.e("UserRepo", "Failed to search users", error)
        }
        .subscribe()
}
```

```dart Flutter
final _amityUsers = <AmityUser>[];
late PagingController<AmityUser> _amityUsersController;

void searchUserByDisplayName(String keyword) {
  _amityUsersController = PagingController(
    pageFuture: (token) => AmityCoreClient.newUserRepository()
        .searchUserByDisplayName(keyword)
        .sortBy(AmityUserSortOption.DISPLAY)
        .matchType(AmityUserSearchMatchType.DEFAULT)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(
      () {
        if (_amityUsersController.error == null) {
          _amityUsers.clear();
          _amityUsers.addAll(_amityUsersController.loadedItems);
        }
      },
    );
}
```

## Query users

Use `getUsers()` when you need a paginated user list without a display-name keyword. TypeScript query sorting supports `firstCreated` and `lastCreated`; iOS, Android, and Flutter also expose display-name sorting.

### Inputs

| Platform | Method | Required inputs | Optional inputs | Result shape |
| --- | --- | --- | --- | --- |
| TypeScript | `UserRepository.getUsers(params, callback)` | callback | `sortBy`, `limit`, `filter`, `matchType` | Starts a live collection observer and returns an unsubscriber. |
| iOS | `userRepository.getUsers(sortBy)` | `sortBy` | None in this call shape | Returns a live collection observed with an `AmityNotificationToken`. |
| Android | `userRepository.getUsers().build().query()` | None | `sortBy(...)` | Returns `Flowable<PagingData<AmityUser>>`. |
| Flutter | `AmityCoreClient.newUserRepository().getUsers()` | None | `sortBy(...)`, paging token, limit | Returns paging data through the query builder. |

Deleted users are excluded from query results.

Use the platform query method when you need a paginated user list rather than keyword search.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

let loadMoreUsers: (() => void) | undefined;

const unsubscribe = UserRepository.getUsers(
  { sortBy: 'lastCreated', limit: 20 },
  ({ data: users, loading, error, hasNextPage, onNextPage }) => {
    if (loading) return;

    if (error) {
      console.error('Failed to query users', error);
      return;
    }

    console.log(`Loaded ${users.length} users`);
    console.log(`More pages available: ${hasNextPage}`);
    loadMoreUsers = onNextPage;
  },
);

// Call loadMoreUsers?.() from your load-more action.
// Call unsubscribe() when the screen no longer needs user list updates.
```

```swift iOS
var token: AmityNotificationToken?

func queryUsersExample() {
    let liveCollection = userRepository.getUsers(.displayName)
    token = liveCollection.observe { collection, error in
        let users = collection.snapshots
        print("Loaded \(users.count) users")
    }
}
```

```kotlin Android
fun queryUsers(userRepository: AmityUserRepository) {
    userRepository.getUsers()
        .sortBy(sortOption = AmityUserSortOption.DISPLAYNAME) // optional
        .build()
        .query()
        .doOnNext { users: PagingData<AmityUser> ->
            // PagingData<AmityUser>
        }
        .doOnError { error ->
            Log.e("UserRepo", "Failed to query users", error)
        }
        .subscribe()
}
```

```dart Flutter
final _amityUsers = <AmityUser>[];
late PagingController<AmityUser> _amityUsersController;

void getUsers(AmityUserSortOption sortOption) {
  _amityUsersController = PagingController(
    pageFuture: (token) => AmityCoreClient.newUserRepository()
        .getUsers()
        .sortBy(sortOption)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(
      () {
        if (_amityUsersController.error == null) {
          _amityUsers.clear();
          _amityUsers.addAll(_amityUsersController.loadedItems);
        }
      },
    );
}
```

## Platform notes

- `searchBy` (where supported) restricts which fields the keyword matches; omit it to keep the default behavior of matching all searchable fields (display name, user id, profile handle). Flutter does not yet expose `searchBy`.
- TypeScript `searchUsers(...)` starts a live collection observer, but its search params do not expose `sortBy`. `searchUserByDisplayName(...)` is a deprecated alias with the same behaviour.
- iOS search and query methods require an `AmityUserSortOption`.
- Android and Flutter default user search/query sorting to display name when no explicit sort is provided.
- Android takes `searchBy` as a list — `searchBy(listOf(AmitySearchUserBy.DISPLAY_NAME))`. Import the enum from `com.amity.socialcloud.sdk.model.core.search.AmitySearchUserBy`; it lives in a different package from `AmityUserSortOption` and `AmityUserSearchMatchType` (`com.amity.socialcloud.sdk.api.core.user.search`).
- Use pagination controls from the callback, live collection, `PagingData`, or Flutter `PagingController` instead of loading all users at once.

## Related topics

    Retrieve one user, batch lookup users where supported, or query user collections.
    Modify user profile fields.

---

### [Flag and Unflag Users](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/flag-unflag-user)

> Flag users with an optional report type, withdraw one report or all of them, and read back which reports you filed, with social.plus SDK.

Use user flagging when a member reports another user for moderator review. Flagging does not block, ban, or delete the user; it records reporting state that moderation workflows can review.

A member can hold several reports on the same user, one per report type plus one typeless report. You can send a simple flag (just the `userId`) or a **structured report** that says _what_ is being reported and _why_, withdraw **one** report or all of them, and read back **which** reports the current member has filed so your UI can disable the options already used.

  Flag and unflag take a `userId` on TypeScript, iOS, and Android; Flutter takes an
  `AmityUser` object. Flag state is read from the loaded user object on every platform.

  Per-report-type unflag and the detailed flag-state result ship in the
  October 2026 SDK releases for TypeScript, iOS, and Android. Flutter keeps
  the boolean flag state and the all-at-once unflag.

## Parameters

| Operation             | Required inputs                                | Platforms                         | Result shape                                                                                                                          |
| --------------------- | ---------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Flag user (typeless)  | `userId`                                       | TypeScript, iOS, Android          | TypeScript returns `Promise<Amity.User>`; iOS async call throws on failure; Android returns `Completable`.                            |
| Report a profile field | `userId`, `field` (optional: `comment`)       | TypeScript, iOS, Android          | Same as flag user.                                                                                                                    |
| Report behavior       | `userId`, `reason` (optional: `comment`)       | TypeScript, iOS, Android          | Same as flag user.                                                                                                                    |
| Flag user             | `AmityUser` object                             | Flutter                           | Returns `Future<AmityUser>`.                                                                                                          |
| Unflag user           | `userId` (optional: `reportType`)              | TypeScript, iOS, Android          | TypeScript returns `Promise<boolean>`; iOS async call throws on failure; Android returns `Completable`.                               |
| Unflag user           | `AmityUser` object                             | Flutter                           | Returns `Future<AmityUser>`. Withdraws all of your reports.                                                                           |
| Quick yes/no          | user object                                    | TypeScript, iOS, Android, Flutter | `isFlaggedByMe` on the loaded user object: a boolean hint.                                                                            |
| Check flag status     | user object                                    | TypeScript, iOS, Android          | A flag-state result from `getUserFlagsByMe()` on the user: `isFlagByMe` plus the list of your own reports (`flags`). TypeScript `Promise<Amity.UserFlagByMe>`, iOS `AmityUserFlagByMe`, Android `Single<AmityUserFlagByMe>`. |
| Check flag status     | `userId`                                       | TypeScript, iOS                   | **Deprecated** repository call that still returns a boolean. TypeScript `Promise<boolean>`; iOS `Bool`.                              |

## Flag a user

Call the flag API when the current user reports another user without saying what or why. The server stores it as a typeless report.

### Inputs

| Platform   | Method                                   | Required inputs    | Result shape                                      |
| ---------- | ---------------------------------------- | ------------------ | ------------------------------------------------- |
| Android    | `userRepository.flagUser(userId)`        | `userId`           | Returns `Completable`.                            |
| iOS        | `userRepository.flagUser(withId:)`       | `userId`           | Async call that throws on failure.                |
| TypeScript | `UserRepository.flagUser(userId)`        | `userId`           | Returns `Promise<Amity.User>` — the flagged user. |
| Flutter    | `user.report().flag()`                   | `AmityUser` object | Returns `Future<AmityUser>`.                      |

```kotlin Android
fun flagUser(userRepository: AmityUserRepository, userId: String) {
    userRepository.flagUser(userId = userId)
        .doOnComplete {
            Log.d("UserFlag", "User flagged")
        }
        .doOnError { error ->
            Log.e("UserFlag", "Flag failed", error)
        }
        .subscribe()
}
```

```swift iOS
func flagUser() async {
    do {
        try await userRepository.flagUser(withId: "<user-id>")
        print("User flagged")
    } catch {
        print("Flag failed: \(error)")
    }
}
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

async function flagUser(userId: string) {
  const flagged = await UserRepository.flagUser(userId);
  console.log('Flagged:', flagged);
}
```

```dart Flutter
Future<void> flagUser(AmityUser user) async {
  try {
    final updatedUser = await user.report().flag();
    print('Flagged user: ${updatedUser.userId}');
  } on AmityException catch (error) {
    print('Flag failed: ${error.message}');
  }
}
```

## Report a profile field or behavior

When you want moderators to know _what_ is being reported and _why_, use one of two calls on TypeScript, iOS, and Android:

- **Report a profile field** with the field and an optional comment. A profile report never carries a reason.
- **Report behavior** with a required reason and an optional comment.

| Input     | Applies to       | Description                                                                                         |
| --------- | ---------------- | --------------------------------------------------------------------------------------------------- |
| `field`   | Profile report   | The profile field being reported: display name, description (bio), or avatar.                      |
| `reason`  | Behavior report  | **Required.** A predefined reason from the shared content report-reason list.                      |
| `comment` | Both             | Optional free text from the reporter, up to **300 characters** after trimming. A blank comment is not sent. |

### Inputs

| Platform   | Method                                                          | Required inputs                         | Result shape                       |
| ---------- | --------------------------------------------------------------- | --------------------------------------- | ---------------------------------- |
| Android    | `userRepository.flagUserProfile(userId, field, comment?)`       | `userId`, `field` (`AmityUserProfileField`) | Returns `Completable`.             |
| Android    | `userRepository.flagUserBehavior(userId, reason, comment?)`     | `userId`, `reason` (`AmityContentFlagReasonType`) | Returns `Completable`.     |
| iOS        | `userRepository.flagUserProfile(withId:field:comment:)`         | `userId`, `field` (`AmityUserProfileField`) | Async call that throws on failure. |
| iOS        | `userRepository.flagUserBehavior(withId:reason:comment:)`       | `userId`, `reason` (`AmityContentFlagReasonType`) | Async call that throws on failure. |
| TypeScript | `UserRepository.flagUserProfile(userId, { field, comment? })`   | `userId`, `field` (`UserProfileFieldEnum`) | Returns `Promise<Amity.User>`.     |
| TypeScript | `UserRepository.flagUserBehavior(userId, { reason, comment? })` | `userId`, `reason` (`AmityContentFlagReasonType`) | Returns `Promise<Amity.User>`.   |

### Profile fields

Your app decides the label to show the member.

| Field          | Suggested label | Android `AmityUserProfileField` | iOS `AmityUserProfileField` | TypeScript `UserProfileFieldEnum` |
| -------------- | --------------- | ------------------------------- | --------------------------- | --------------------------------- |
| Display name   | Username        | `DISPLAY_NAME`                  | `.displayName`              | `DISPLAY_NAME`                    |
| Description    | Bio             | `DESCRIPTION`                   | `.description`              | `DESCRIPTION`                     |
| Avatar         | Avatar          | `AVATAR`                        | `.avatar`                   | `AVATAR`                          |

### Reasons

A behavior report takes a reason from the shared content report-reason list, the same one used when flagging posts, comments, and messages: community guidelines, child endangerment, harassment or bullying, self-harm or suicide, violence or threatening content, selling restricted items, sexual content or nudity, spam or scams, false information, or others. See [Flag reasons](/social-plus-sdk/social/content-management/moderation/content-flagging#flag-reasons) for each platform's identifiers. The reason never carries text: for **Others**, put the reporter's explanation in `comment`.

Use **child endangerment** (`CHILD_ENDANGERMENT` on Android, `.childEndangerment` on iOS, `ChildEndangerment` on TypeScript) when a user's behavior endangers a child, including sharing suspected child sexual abuse material (CSAM).

### Rules

  - A member holds **one report per report type** on a target: one per profile field, one for behavior, and one typeless. Reporting the **same** type again updates that report; reporting a **different** type adds a new one.
  - A `comment` longer than 300 characters after trimming is rejected **before any request** is sent.
  - Unflagging without a `reportType` removes **all** of your reports on that user. Pass a `reportType` to withdraw just one — see [Unflag a user](#unflag-a-user).
  - Any other rule the server enforces returns a validation error (HTTP `422`).

### Examples

Use the behavior call when the reporter picks a reason, and the profile call when they point at a field. Add a `comment` to either when the reporter gives extra detail.

```kotlin Android
// Report a user's behavior, with a reason and a comment
userRepository.flagUserBehavior(
    userId = userId,
    reason = AmityContentFlagReasonType.SPAM_OR_SCAMS,
    comment = "Repeatedly posting promo links"
).subscribe()

// Report a profile field (no reason)
userRepository.flagUserProfile(
    userId = userId,
    field = AmityUserProfileField.AVATAR
).subscribe()
```

```swift iOS
// Report a user's behavior, with a reason and a comment
try await userRepository.flagUserBehavior(
    withId: "<user-id>",
    reason: .spamOrScams,
    comment: "Repeatedly posting promo links"
)

// Report a profile field (no reason)
try await userRepository.flagUserProfile(withId: "<user-id>", field: .avatar)
```

```typescript TypeScript
import { AmityContentFlagReasonType, UserProfileFieldEnum, UserRepository } from '@amityco/ts-sdk';

// Report a user's behavior, with a reason and a comment
await UserRepository.flagUserBehavior(userId, {
  reason: AmityContentFlagReasonType.SpamOrScams,
  comment: 'Repeatedly posting promo links',
});

// Report a profile field (no reason)
await UserRepository.flagUserProfile(userId, { field: UserProfileFieldEnum.AVATAR });
```

  To report more than one aspect of the same profile (for example the avatar
  **and** the behavior), send a separate call for each. They are stored as
  distinct reports.

  The earlier single call that took `reportType`, `reason`, and `comment`
  together (`flagUser(userId, options)` on TypeScript,
  `flagUser(userId, reportType, reason, comment)` on Android, and
  `flagUser(withId:reportType:reason:comment:)` on iOS) still works but is
  **deprecated**. Flagging with only a `userId` is not deprecated.

## Unflag a user

Call the unflag API when the current user withdraws a report from another user. Without a `reportType` it withdraws every report you filed on that user. With a `reportType` it withdraws only that one and leaves your other reports in place.

### Inputs

| Platform   | Method                                           | Required inputs                       | Result shape                       |
| ---------- | ------------------------------------------------ | ------------------------------------- | ---------------------------------- |
| Android    | `userRepository.unflagUser(userId, reportType?)` | `userId` (optional `reportType`)      | Returns `Completable`.             |
| iOS        | `userRepository.unflagUser(withId:reportType:)`  | `userId` (optional `reportType`)      | Async call that throws on failure. |
| TypeScript | `UserRepository.unflagUser(userId, options?)`    | `userId` (optional `reportType`)      | Returns `Promise<boolean>`.        |
| Flutter    | `user.report().unflag()`                         | `AmityUser` object                    | Returns `Future<AmityUser>`. Withdraws all of your reports. |

### Which report is withdrawn

| `reportType`                                               | Withdraws                                       |
| ---------------------------------------------------------- | ----------------------------------------------- |
| omitted                                                    | every report you filed on that user             |
| `displayName`, `description`, `avatarFileId`, `behavior`   | only your report of that type                   |
| `untyped`                                                  | only your typeless report (the one filed without a `reportType`) |

`untyped` exists only for unflag. It names the typeless report, which the flag API never accepts as a type and which the flag-state result returns as `reportType: null`.

  - Withdrawing a report you never filed succeeds and changes nothing, so withdrawing twice is safe.
  - Other members' reports on the same user are never affected, even of the same type.
  - After a per-type unflag you may still hold other reports on that user. Do not set a local "flagged by me" value to `false` after an unflag; read the flag state again instead.

```kotlin Android
fun unflagUser(userRepository: AmityUserRepository, userId: String) {
    // Withdraw every report you filed on this user
    userRepository.unflagUser(userId = userId)
        .doOnComplete {
            Log.d("UserFlag", "User unflagged")
        }
        .doOnError { error ->
            Log.e("UserFlag", "Unflag failed", error)
        }
        .subscribe()
}

fun withdrawBehaviorReport(userRepository: AmityUserRepository, userId: String) {
    // Withdraw only your behavior report; your other reports stay
    userRepository.unflagUser(
        userId = userId,
        reportType = AmityUserReportTypeFilter.BEHAVIOR
    ).subscribe()
}

fun withdrawTypelessReport(userRepository: AmityUserRepository, userId: String) {
    userRepository.unflagUser(
        userId = userId,
        reportType = AmityUserReportTypeFilter.UNTYPED
    ).subscribe()
}
```

```swift iOS
func unflagUser() async {
    do {
        // Withdraw every report you filed on this user
        try await userRepository.unflagUser(withId: "<user-id>")
        print("User unflagged")
    } catch {
        print("Unflag failed: \(error)")
    }
}

func withdrawBehaviorReport() async throws {
    // Withdraw only your behavior report; your other reports stay
    try await userRepository.unflagUser(withId: "<user-id>", reportType: .behavior)
}

func withdrawTypelessReport() async throws {
    try await userRepository.unflagUser(withId: "<user-id>", reportType: .untyped)
}
```

```typescript TypeScript
import { UserReportTypeFilterEnum, UserRepository } from '@amityco/ts-sdk';

// Withdraw every report you filed on this user
async function unflagUser(userId: string) {
  const unflagged = await UserRepository.unflagUser(userId);
  console.log('Unflagged:', unflagged);
}

// Withdraw only your behavior report; your other reports stay
async function withdrawBehaviorReport(userId: string) {
  await UserRepository.unflagUser(userId, { reportType: UserReportTypeFilterEnum.BEHAVIOR });
}

// Withdraw only your typeless report
async function withdrawTypelessReport(userId: string) {
  await UserRepository.unflagUser(userId, { reportType: UserReportTypeFilterEnum.UNTYPED });
}
```

```dart Flutter
Future<void> unflagUser(AmityUser user) async {
  try {
    final updatedUser = await user.report().unflag();
    print('Unflagged user: ${updatedUser.userId}');
  } on AmityException catch (error) {
    print('Unflag failed: ${error.message}');
  }
}
```

## Check which reports you filed on a user

Use the flag-state API to decide what to show: a "reported" badge, which report options to disable because the current member already used them, and a withdraw action per report. Only the current member's own reports come back; other members' reports are never exposed.

  The repository call `isUserFlaggedByMe` is **deprecated** on TypeScript and iOS.
  It still works and still returns a boolean, so nothing breaks. Read flag state
  from the user object instead: `isFlaggedByMe` for a quick yes/no and
  `getUserFlagsByMe()` for the reports. Android never had a repository call; it
  adds `getUserFlagsByMe()` next to its existing `isFlaggedByMe()`.

### Which one to use

There are two ways to read the flag state. Pick by what the screen is doing.

| When | Use | What you get |
| ---- | --- | ------------ |
| **Drawing a feed row, a list item or a "reported" badge** | The quick yes/no on the user object: Android `user.isFlaggedByMe()`, iOS `user.isFlaggedByMe`, TypeScript `user.isFlaggedByMe`, Flutter `user.isFlaggedByMe` | A boolean that **returns immediately** and never waits for a request. It is computed from the user data when the user is loaded. |
| **Showing the options to flag or unflag** | The flag-state call on the user object: Android, iOS, and TypeScript `user.getUserFlagsByMe()` | The exact reports (`isFlagByMe` and `flags`), read from the server. Call it **only when you open those options**, not for every row. When the quick yes/no is `false` it returns no reports without a request. |

The quick yes/no is a hint built from data the user object already carries:

- `false` is exact: you have not reported this user, as of the user object's last update.
- `true` means "maybe". It can be `true` for a user you did not report, because of other members' reports.
- On TypeScript, iOS and Android, the SDK checks a `true` with the server in the background, once each time the user's reports change, and remembers the answer. On TypeScript and iOS an observed user is delivered again with the checked value. On Android the checked value appears the next time the user updates.

#### Keep the quick yes/no current

A loaded user object is a snapshot: the yes/no is worked out from the user data it was built from, so a user object you already hold does **not** change after you flag or unflag. Observe the user instead, and read `isFlaggedByMe` from each update. The observer delivers a new user object after every flag or unflag, so your row or badge stays current without any request.

```kotlin Android
fun observeFlagState(userRepository: AmityUserRepository, userId: String): Disposable {
    // A new AmityUser arrives after you flag or unflag, so isFlaggedByMe() stays current
    return userRepository.getUser(userId = userId)
        .doOnNext { user: AmityUser ->
            val showReported = user.isFlaggedByMe()   // hint, no request
            // Update your row or badge here
        }
        .subscribe()
}

// Call dispose() on the returned Disposable when the screen no longer needs user updates.
```

```swift iOS
var token: AmityNotificationToken?

func observeFlagState(userId: String) {
    // A new AmityUser arrives after you flag or unflag, so isFlaggedByMe stays current
    token = userRepository.getUser(userId).observe { liveObject, error in
        guard let user = liveObject.snapshot else { return }
        let showReported = user.isFlaggedByMe   // hint, no request
        // Update your row or badge here
    }
}
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

// A new Amity.User arrives after you flag or unflag, so isFlaggedByMe stays current
const unsubscribe = UserRepository.getUser(userId, ({ data: user, loading }) => {
  if (loading || !user) return;
  const showReported = user.isFlaggedByMe; // hint, no request
  // Update your row or badge here
});

// Call unsubscribe() when the screen no longer needs user updates.
```

A report filed on another device shows once the user is refreshed. Call `getUserFlagsByMe()` when you need the exact state.

`getUserFlagsByMe()` uses the hint of the user object you call it on: when that hint is `false` (including a `false` the SDK has already confirmed) it returns no reports without a request. Call it on the user you just observed, or on a freshly loaded one, not on an object you held from before a flag or unflag.

#### Load the user, then check

`getUserFlagsByMe()` is called on a user object, so get the user first. Use this when the options to flag or unflag open. A user you already hold from a list, a profile, or a member row works too; it carries the same members.

```kotlin Android
fun openReportOptions(userRepository: AmityUserRepository, userId: String) {
    // 1. Get the user. firstOrError() takes the first value and stops.
    userRepository.getUser(userId = userId)
        .firstOrError()
        // 2. Read the exact reports now
        .flatMap { user: AmityUser -> user.getUserFlagsByMe() }
        .doOnSuccess { result ->
            val isReported = result.isFlagByMe
            // Show "Unreport" when isReported is true, otherwise "Report"
        }
        .subscribe()
}
```

```swift iOS
var token: AmityNotificationToken?

func openReportOptions(userId: String) {
    // 1. Get the user. observeOnce delivers the first value and stops.
    token = userRepository.getUser(userId).observeOnce { liveObject, error in
        guard let user = liveObject.snapshot else { return }

        Task {
            // 2. Read the exact reports now
            let result = try? await user.getUserFlagsByMe()
            let isReported = result?.isFlagByMe ?? false
            // Show "Unreport" when isReported is true, otherwise "Report"
        }
    }
}
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

async function openReportOptions(user: Amity.User) {
  // The user comes from getUser, a list, or a member row; read the exact reports now
  const { isFlagByMe } = await user.getUserFlagsByMe();
  // Show "Unreport" when isFlagByMe is true, otherwise "Report"
}

const unsubscribe = UserRepository.getUser(userId, ({ data: user, loading }) => {
  if (loading || !user) return;
  openReportOptions(user);
});
```

#### Migrating from the repository call

The repository call still works but is deprecated on TypeScript and iOS. Replace it with the user object: `isFlaggedByMe` where you drew a badge from the boolean, and `getUserFlagsByMe()` where you need the exact answer.

```swift iOS
// Before (deprecated, still returns Bool)
let isFlagged = try await userRepository.isUserFlaggedByMe(withId: userId)

// After
userRepository.getUser(userId).observeOnce { liveObject, error in
    guard let user = liveObject.snapshot else { return }
    Task {
        let isFlagged = try await user.getUserFlagsByMe().isFlagByMe
    }
}
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

// Before (deprecated, still returns a boolean)
const isFlagged = await UserRepository.isUserFlaggedByMe(userId);

// After: a badge needs no request, the options sheet reads the exact state
UserRepository.getUser(userId, async ({ data: user, loading }) => {
  if (loading || !user) return;
  const showReported = user.isFlaggedByMe;
  const { isFlagByMe } = await user.getUserFlagsByMe();
});
```

### Inputs

| Platform   | Method                                        | Required inputs    | Result shape                                                    |
| ---------- | --------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| Android    | `user.isFlaggedByMe()`                        | `AmityUser` object | Returns `Boolean`, a quick hint with no request.                |
| Android    | `user.getUserFlagsByMe()`                     | `AmityUser` object | Returns `Single<AmityUserFlagByMe>`.                            |
| iOS        | `user.isFlaggedByMe`                          | `AmityUser` object | Returns `Bool`, a quick hint with no request.                   |
| iOS        | `user.getUserFlagsByMe()`                     | `AmityUser` object | Returns `AmityUserFlagByMe` from an async call.                 |
| iOS        | `userRepository.isUserFlaggedByMe(withId:)`   | `userId`           | **Deprecated.** Returns `Bool` from an async call.              |
| TypeScript | `user.isFlaggedByMe`                          | `Amity.User` object | Returns `boolean`, a quick hint with no request.               |
| TypeScript | `user.getUserFlagsByMe()`                     | `Amity.User` object | Returns `Promise<Amity.UserFlagByMe>`.                         |
| TypeScript | `UserRepository.isUserFlaggedByMe(userId)`    | `userId`           | **Deprecated.** Returns `Promise<boolean>`.                     |
| Flutter    | `user.isFlaggedByMe`                          | `AmityUser` object | Returns `bool` from the loaded user model (yes/no only).        |

### Result

| Field                | Type                                                              | Description                                                                                         |
| -------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `isFlagByMe`         | boolean                                                           | `true` when the current member holds any report on the user.                                        |
| `flags`              | list                                                              | The current member's own reports on the user, in server order. Empty when not reported.             |
| `flags[].reportType` | `displayName`, `description`, `avatarFileId`, `behavior`, or null | Which aspect was reported. `null` is the typeless report; withdraw it with `untyped`.               |
| `flags[].reason`     | string or null                                                    | The stored reason. Present on `behavior` reports.                                                   |
| `flags[].comment`    | string or null                                                    | The stored reporter comment.                                                                        |
| `flags[].createdAt`  | date-time or null                                                 | When the report was filed. `null` for reports filed before report types existed.                    |

Every field is always present; a field the report does not carry is `null`. The result is read from the server on each call and is not cached. The one exception: when the user's quick yes/no is `false`, `getUserFlagsByMe()` returns no reports without a request.

```kotlin Android
fun checkFlagState(user: AmityUser) {
    // A hint with no request: false is exact; a true is checked with the server in the background
    Log.d("UserFlag", "Probably flagged by me: ${user.isFlaggedByMe()}")

    // The exact reports; skips the request when the hint is false
    user.getUserFlagsByMe()
        .doOnSuccess { result ->
            Log.d("UserFlag", "Flagged by me: ${result.isFlagByMe}")

            // Disable the report options the member already used
            val usedTypes = result.flags.map { it.reportType }.toSet()
            val canReportBio = AmityUserReportType.DESCRIPTION !in usedTypes
            Log.d("UserFlag", "Can report bio: $canReportBio")
        }
        .doOnError { error ->
            Log.e("UserFlag", "Flag-state check failed", error)
        }
        .subscribe()
}
```

```swift iOS
func checkFlagState(user: AmityUser) async {
    // A hint with no request: false is exact; a true is checked with the server in the background
    print("Probably flagged by me: \(user.isFlaggedByMe)")

    do {
        // The exact reports; skips the request when the hint is false
        let result = try await user.getUserFlagsByMe()
        print("Flagged by me: \(result.isFlagByMe)")

        // Disable the report options the member already used
        let usedTypes = Set(result.flags.map { $0.reportType })
        let canReportBio = !usedTypes.contains(.description)
        print("Can report bio: \(canReportBio)")
    } catch {
        print("Flag-state check failed: \(error)")
    }
}
```

```typescript TypeScript
import { UserReportTypeEnum } from '@amityco/ts-sdk';

async function checkFlagState(user: Amity.User) {
  // A hint with no request: false is exact; a true is checked with the server in the background
  console.log('Probably flagged by me:', user.isFlaggedByMe);

  // The exact reports; skips the request when the hint is false
  const { isFlagByMe, flags } = await user.getUserFlagsByMe();
  console.log('Flagged by me:', isFlagByMe);

  // Disable the report options the member already used; null marks the typeless report
  const usedTypes = new Set(flags.map(flag => flag.reportType));
  const canReportBio = !usedTypes.has(UserReportTypeEnum.DESCRIPTION);
  console.log('Can report bio:', canReportBio);
}
```

```dart Flutter
void checkFlagState(AmityUser user) {
  final isFlaggedByMe = user.isFlaggedByMe;
  print('Flagged by me: $isFlaggedByMe');
}
```

### Withdraw one of the listed reports

Each entry in `flags` maps to one unflag call. Pass its `reportType`, or `untyped` when the entry's `reportType` is `null`.

  On Android and iOS the `reportType` parameter of unflag is optional, and
  omitting it (or passing `nil`) withdraws **all** of your reports. An entry
  whose `reportType` is `null` is the typeless report: pass `untyped`, not `nil`.

```kotlin Android
fun withdrawAllListedReports(userRepository: AmityUserRepository, user: AmityUser) {
    user.getUserFlagsByMe()
        .flatMapCompletable { result ->
            Completable.concat(
                result.flags.map { flag ->
                    val filter = when (flag.reportType) {
                        AmityUserReportType.DISPLAY_NAME -> AmityUserReportTypeFilter.DISPLAY_NAME
                        AmityUserReportType.DESCRIPTION -> AmityUserReportTypeFilter.DESCRIPTION
                        AmityUserReportType.AVATAR -> AmityUserReportTypeFilter.AVATAR
                        AmityUserReportType.BEHAVIOR -> AmityUserReportTypeFilter.BEHAVIOR
                        null -> AmityUserReportTypeFilter.UNTYPED
                    }
                    userRepository.unflagUser(userId = user.getUserId(), reportType = filter)
                }
            )
        }
        .subscribe()
}
```

```swift iOS
func withdrawAllListedReports(user: AmityUser) async throws {
    let result = try await user.getUserFlagsByMe()
    for flag in result.flags {
        let filter: AmityUserReportTypeFilter
        switch flag.reportType {
        case .displayName: filter = .displayName
        case .description: filter = .description
        case .avatarFileId: filter = .avatarFileId
        case .behavior: filter = .behavior
        case .none: filter = .untyped
        @unknown default: filter = .untyped
        }
        try await userRepository.unflagUser(withId: user.userId, reportType: filter)
    }
}
```

```typescript TypeScript
import { UserReportTypeFilterEnum, UserRepository } from '@amityco/ts-sdk';

async function withdrawAllListedReports(user: Amity.User) {
  const { flags } = await user.getUserFlagsByMe();
  for (const flag of flags) {
    // A null reportType is the typeless report; unflag selects it with 'untyped'
    const reportType = flag.reportType ?? UserReportTypeFilterEnum.UNTYPED;
    await UserRepository.unflagUser(user.userId, { reportType });
  }
}
```

## Platform notes

- Flagging is a report signal for moderation review; it does not automatically block, ban, or delete the user.
- TypeScript, iOS, and Android flag and unflag by `userId`, and read flag state from the loaded user object (`isFlaggedByMe` and `getUserFlagsByMe()`). On TypeScript every user the SDK returns carries both members: a user from `getUser`, a user list, a member list, or a message preview.
- Flutter flags and unflags through the loaded `AmityUser` object, withdraws all reports at once, and exposes a boolean flag state only.
- The child endangerment reason for behavior reports ships in TypeScript 7.31.0 and in the next Android and iOS releases.
- The repository call `isUserFlaggedByMe` is deprecated on TypeScript and iOS and keeps returning a boolean: `Promise<boolean>` on TypeScript, `Bool` on iOS. Android has no repository call.
- `isFlaggedByMe` is computed from the user data when the user is loaded. `false` is exact; `true` can be a false positive, and it only reflects the user as of its last update. TypeScript, iOS and Android check a `true` with the server in the background. Use it to draw a feed row or a badge, and call `getUserFlagsByMe()` when you show the options to flag or unflag. `getUserFlagsByMe()` skips the request when `isFlaggedByMe` is `false`.
- The backend returns the updated user, including its current `flagCount`, and the SDK saves it. Read flag state after a flag or unflag when your UI needs the updated per-report list.

## Related topics

    Retrieve user details and flag status.
    Gate moderation actions with permission checks.

---

### [User Token Management](https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/user-token-management)

> Learn how to manage user authentication tokens and credentials in social.plus SDK

Use `AmityUserTokenManager` or the TypeScript `createUserToken(...)` helper to create user credentials for flows that require a user access token. This includes access to some beta features and server-side API workflows.

The generated access token is not used by normal client SDK login. Create and consume these tokens only from a backend, tool, or trusted workflow where the token is not exposed to end users.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `apiKey` | Yes | TypeScript, iOS, Android, Flutter | API key used to create the token manager or token request. Keep it in a trusted runtime when generating tokens. |
| `region` / `endpoint` | Yes | TypeScript, iOS, Android, Flutter | Region or endpoint used to route the token request. |
| `userId` | Yes | TypeScript, iOS, Android, Flutter | Unique identifier of the user whose credentials are created. |
| `displayName` | No | TypeScript, iOS, Android, Flutter | Display name associated with the user credentials when provided. |
| `authToken` / `secureToken` | No | TypeScript, iOS, Android, Flutter | Secure authentication token used when your app enables secure mode. |

## Create a user token

To create a user token, pass the user's identifier and optional secure-mode credentials from a trusted workflow.

Create the token with the SDK surface for your platform.

```typescript TypeScript
import { API_REGIONS, createUserToken } from '@amityco/ts-sdk';

const { accessToken } = await createUserToken('your-api-key', API_REGIONS.SG, {
  userId: 'user_123',
  displayName: 'Jane Doe',
  authToken: 'secure-token',
});

console.log(accessToken);
```

```swift iOS
// 1. create AmityUserTokenManager instance.
let userTokenManager = AmityUserTokenManager(apiKey: "<api-key>", region: .SG)

func createNewUserTokenExample() async {
    // 2. call `createUserToken` on AmityUserTokenManager.
    do {
        let auth = try await userTokenManager.createUserToken(
            userId: "<user-id>",
            displayName: "<(optional)-display-name>",
            authToken: "<(optional)-auth-token>"
        )
        print("auth.accessToken: \(auth.accessToken)")
    } catch {
        print("unable to create a new user token: \(error.localizedDescription)")
    }
}
```

```kotlin Android
fun createUserToken(
    userId: String,
    displayName: String,
    apiKey: String,
    endpoint: AmityEndpoint,
    authToken: String?
) {
    AmityUserTokenManager(
        apiKey = apiKey,
        endpoint = endpoint
    ).createUserToken(
        userId = userId,
        displayName = displayName,
        secureToken = authToken
    )
        .doOnSuccess { userToken : AmityUserToken ->
            // AmityUserToken
            val accessToken = userToken.accessToken
        }
        .doOnError {
            // Exception
        }
        .subscribe()
}
```

```dart Flutter
void createUserToken(String userId, String displayname, String secureToken) {
  AmityUserTokenManager(
          apiKey: "your api key", endpoint: AmityRegionalHttpEndpoint.SG)
      //displayname and secureToken are optional
      .createUserToken(userId,
          displayname: displayname, secureToken: secureToken)
      .then((AmityUserToken token) {
          log("accessToken = ${token.accessToken}");
  });
}
```

## Token security

    - Store tokens securely on the server side.
    - Use encryption for token storage.
    - Implement token rotation policies.
    - Never expose tokens in client-side code.

    - Always use HTTPS for token transmission.
    - Implement proper authentication headers.
    - Use secure communication channels.
    - Log token usage for audit purposes.

## Best Practices

    - Cache tokens to avoid unnecessary creation.
    - Implement token validation before usage.
    - Use connection pooling for better performance.
    - Handle token expiration gracefully.

    - Implement comprehensive error handling.
    - Log all token operations for debugging.
    - Provide meaningful error messages.
    - Implement retry logic for transient failures.

    - Batch token operations when possible.
    - Use background processing for token creation.
    - Implement caching strategies.
    - Monitor token usage patterns.

## Related Topics

    Learn about standard user login and authentication.
    Explore social.plus API documentation.

## Core Concepts — Content

### [File Handling](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/file)

> Upload, read, and delete generic file attachments with the social.plus SDKs.

Use file handling when your app needs to upload a generic attachment such as a PDF, document, archive, or audio-adjacent custom file. The SDK returns a file object with a `fileId`, URL, attributes, and access type. Pass that uploaded file or its `fileId` into post, comment, or message creation APIs when you want to attach it to user content.

This page covers generic files. Use the image and video pages for media-specific helpers such as image sizes, alt text, video status, and video resolution URLs.

## Platform Surface

| Platform | Upload | Fetch | Delete | Notes |
| --- | --- | --- | --- | --- |
| TypeScript | `FileRepository.uploadFile(formData, onProgress?)` | `FileRepository.getFile(fileId)` and `getFile.locally(fileId)` | `FileRepository.deleteFile(fileId)` | `formData` must include a `files` key. Upload returns an array of uploaded files. |
| iOS | `AmityFileRepository.uploadFile(_:progress:)` and `uploadFile(with:fileName:progress:)` | `getFile(fileId:)`, then `mapToFileData()` | `deleteFile(fileId:)` | URL-based upload is the source-recommended path for large local files. |
| Android | `AmityCoreClient.newFileRepository().uploadFile(uri)` | `getFile(fileId)`, then `asAmityFile()` | `deleteFile(fileId)` | Upload progress is delivered through `AmityUploadResult`. |
| Flutter | `AmityCoreClient.newFileRepository().uploadFile(file)` | Not exposed as a direct public file-repository fetch method in the current SDK | Not exposed as a direct public file-repository delete method in the current SDK | Use the uploaded `AmityFile` or file data loaded through post, comment, or message models. |

## Parameters

| Parameter | Platforms | Description |
| --- | --- | --- |
| `formData` / `file` / `url` / `uri` | TypeScript, iOS, Android, Flutter | The local file input. TypeScript expects `FormData`; iOS accepts `AmityUploadableFile` or a local `URL`; Android accepts `Uri`; Flutter accepts `File`. |
| `fileName` | iOS | Optional filename for URL-based upload. If omitted, the SDK derives the name from the URL. |
| `fileId` | TypeScript, iOS, Android | ID returned by upload or embedded in content data. Used for direct fetch and delete calls where available. |
| `onProgress` / `progress` | TypeScript, iOS, Android, Flutter | Upload progress callback or stream event. TypeScript emits a percentage; iOS emits `0.0...1.0`; Android and Flutter expose progress through `AmityUploadResult`. |
| `uploadId` | Android, Flutter | Optional lower-level identifier for tracking or canceling a specific upload. The default public upload methods generate one for you. |

## Upload A File

Upload a local file first, then use the returned `fileId` or file object in content creation APIs.


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

async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append('files', file);

  const { data: files } = await FileRepository.uploadFile(formData, percent => {
    console.log(`Upload progress: ${percent}%`);
  });

  const uploadedFile = files[0];
  return uploadedFile.fileId;
}
```

```swift iOS
let fileURL = URL(fileURLWithPath: "/tmp/document.pdf")

let uploadedFile = try await fileRepository.uploadFile(
    with: fileURL,
    fileName: "document.pdf",
    progress: { progress in
        print("Upload progress: \(progress)")
    }
)

let uploadedFileId = uploadedFile.fileId
```

```kotlin Android
val fileUri = Uri.parse("file:///tmp/document.pdf")

AmityCoreClient.newFileRepository()
    .uploadFile(fileUri)
    .doOnNext { result: AmityUploadResult<AmityFile> ->
        when (result) {
            is AmityUploadResult.PROGRESS -> {
                val progress = result.getUploadInfo().getProgressPercentage()
            }
            is AmityUploadResult.COMPLETE -> {
                val uploadedFile = result.getFile()
                val uploadedFileId = uploadedFile.getFileId()
            }
            is AmityUploadResult.ERROR -> {
                val error = AmityError.from(result.getError())
            }
            is AmityUploadResult.CANCELLED -> {
                // Upload was canceled.
            }
        }
    }
    .subscribe()
```

```dart Flutter
import 'dart:io';

final file = File('/tmp/document.pdf');

AmityCoreClient.newFileRepository()
    .uploadFile(file)
    .stream
    .listen((AmityUploadResult<AmityFile> result) {
  result.when(
    progress: (uploadInfo, cancelToken) {
      final progress = uploadInfo.getProgressPercentage();
    },
    complete: (uploadedFile) {
      final uploadedFileId = uploadedFile.fileId;
      final uploadedFileUrl = uploadedFile.getUrl;
    },
    error: (error) {
      final exception = error;
    },
    cancel: () {
      // Upload was canceled.
    },
  );
});
```


## Read File Data

Read file data when your app needs a direct file URL, filename, or MIME type for a previously uploaded file.


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

async function getFile(fileId: string) {
  const { data: file } = await FileRepository.getFile<'file'>(fileId);

  return {
    fileId: file.fileId,
    fileUrl: file.fileUrl,
    name: file.attributes.name,
    mimeType: file.attributes.mimeType,
  };
}
```

```swift iOS
let rawFile = try await fileRepository.getFile(fileId: fileId)

if rawFile.type == .file, let fileData = rawFile.mapToFileData() {
    let localURL = try await fileRepository.downloadFile(fromURL: fileData.fileURL)
    print("Downloaded file to \(localURL)")
}
```

```kotlin Android
AmityCoreClient.newFileRepository()
    .getFile(fileId)
    .doOnSuccess { rawFile: AmityRawFile ->
        if (rawFile.getFileType() == AmityFileType.FILE) {
            val file = rawFile.asAmityFile()
            val fileUrl = file.getUrl()
            val fileName = file.getFileName()
        }
    }
    .subscribe()
```

```dart Flutter
void inspectFile(AmityFile uploadedFile) {
  final uploadedFileId = uploadedFile.fileId;
  final uploadedFileUrl = uploadedFile.getUrl;
  final uploadedFileName = uploadedFile.fileName;
}
```


## Delete A File

Delete only files your app no longer needs. If a file is still referenced by a post, comment, message, user profile, community, or channel, update that content first so users do not see broken attachments.


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

async function deleteFile(fileId: string) {
  const { success } = await FileRepository.deleteFile(fileId);
  return success;
}
```

```swift iOS
try await fileRepository.deleteFile(fileId: fileId)
```

```kotlin Android
AmityCoreClient.newFileRepository()
    .deleteFile(fileId)
    .subscribe()
```


## Related Topics

    Upload images, read image metadata, and request sized image URLs.
    Upload videos and read transcoding status or resolution URLs.
    Attach uploaded files to social posts.

---

### [Image Handling](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/image-handling)

> Upload images, read image metadata, and request sized image URLs with the social.plus SDKs.

Use image handling when your app needs to upload image files for avatars, posts, comments, messages, stories, or other media surfaces. Image uploads return image file data with a `fileId`, URL, metadata, access type, and, on supported platforms, alt text.

For image posts, comments, messages, and avatars, first upload the image through the file repository, then pass the returned image object or `fileId` into the relevant creation or update API.

## Platform Surface

| Platform | Upload | Fetch | Sized URLs | Alt text |
| --- | --- | --- | --- | --- |
| TypeScript | `FileRepository.uploadImage(formData, onProgress?, altText?)` | `FileRepository.getFile(fileId)` | `FileRepository.fileUrlWithSize(fileUrl, size)` with `small`, `medium`, `large`, `full` | Upload and `updateAltText(fileId, altText)` |
| iOS | `AmityFileRepository.uploadImage(_:altText:progress:)` and `uploadImage(with:isFullImage:altText:progress:completion:)` | `getFile(fileId:)`, then `mapToImageData()` | `downloadImage(fromURL:size:)` with `AmityMediaSize.small`, `.medium`, `.large`, `.full` | Upload and `updateAltText(fileId:altText:)` |
| Android | `AmityCoreClient.newFileRepository().uploadImage(uri, altText?)` | `getFile(fileId)`, then `asAmityImage()` | `AmityImage.getUrl(AmityImage.Size)` with `SMALL`, `MEDIUM`, `LARGE` | Upload and `updateAltText(fileId, altText)` |
| Flutter | `AmityCoreClient.newFileRepository().uploadImage(file, isFullImage?)` | Not exposed as a direct public file-repository fetch method in the current SDK | `AmityImage.getUrl(AmityImageSize)` with `SMALL`, `MEDIUM`, `LARGE`, `FULL` | No public upload alt-text parameter in the current SDK |

## Parameters

| Parameter | Platforms | Description |
| --- | --- | --- |
| `formData` / `image` / `url` / `uri` / `file` | TypeScript, iOS, Android, Flutter | The image input. TypeScript accepts `FormData`; iOS accepts `UIImage` or a local image `URL`; Android accepts `Uri`; Flutter accepts `File`. |
| `altText` | TypeScript, iOS, Android | Optional accessibility text stored on the image file. Flutter's current public upload method does not expose this parameter. |
| `isFullImage` | iOS, Flutter | Whether the uploaded image should be treated as the full image. iOS documents this on the URL-based upload; Flutter exposes `isFullImage` on public upload. |
| `fileId` | TypeScript, iOS, Android | ID returned by upload or embedded in content data. Used for direct fetch, size lookup, or alt-text update where available. |
| `size` | TypeScript, iOS, Android, Flutter | Requested display size. Size names differ slightly by platform, and Android currently exposes `SMALL`, `MEDIUM`, and `LARGE`. |
| `onProgress` / `progress` | TypeScript, iOS, Android, Flutter | Upload progress callback or stream event. |

## Upload An Image

Upload an image first, then use the returned image object or `fileId` in avatar, post, comment, message, or story APIs.


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

async function uploadImage(image: File) {
  const formData = new FormData();
  formData.append('file', image);

  const { data: images } = await FileRepository.uploadImage(
    formData,
    percent => {
      console.log(`Upload progress: ${percent}%`);
    },
    'Profile photo',
  );

  return images[0].fileId;
}
```

```swift iOS
let image = UIImage()

let uploadedImage = try await fileRepository.uploadImage(
    image,
    altText: "Profile photo",
    progress: { progress in
        print("Upload progress: \(progress)")
    }
)

let imageFileId = uploadedImage.fileId
```

```kotlin Android
val imageUri = Uri.parse("file:///tmp/profile.jpg")

AmityCoreClient.newFileRepository()
    .uploadImage(uri = imageUri, altText = "Profile photo")
    .doOnNext { result: AmityUploadResult<AmityImage> ->
        when (result) {
            is AmityUploadResult.PROGRESS -> {
                val progress = result.getUploadInfo().getProgressPercentage()
            }
            is AmityUploadResult.COMPLETE -> {
                val uploadedImage = result.getFile()
                val imageFileId = uploadedImage.getFileId()
            }
            is AmityUploadResult.ERROR -> {
                val error = AmityError.from(result.getError())
            }
            is AmityUploadResult.CANCELLED -> {
                // Upload was canceled.
            }
        }
    }
    .subscribe()
```

```dart Flutter
import 'dart:io';

final image = File('/tmp/profile.jpg');

AmityCoreClient.newFileRepository()
    .uploadImage(image, isFullImage: true)
    .stream
    .listen((AmityUploadResult<AmityImage> result) {
  result.when(
    progress: (uploadInfo, cancelToken) {
      final progress = uploadInfo.getProgressPercentage();
    },
    complete: (uploadedImage) {
      final imageFileId = uploadedImage.fileId;
      final fullImageUrl = uploadedImage.getUrl(AmityImageSize.FULL);
    },
    error: (error) {
      final exception = error;
    },
    cancel: () {
      // Upload was canceled.
    },
  );
});
```


## Read Image Data

Read image data when your app needs image dimensions, alt text, or a sized image URL for rendering.


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

async function getImage(imageFileId: string) {
  const { data: image } = await FileRepository.getFile<'image'>(imageFileId);
  const mediumUrl = FileRepository.fileUrlWithSize(image.fileUrl, 'medium');

  return {
    mediumUrl,
    altText: image.altText,
    width: image.getWidth(),
    height: image.getHeight(),
  };
}
```

```swift iOS
let rawFile = try await fileRepository.getFile(fileId: imageFileId)

if rawFile.type == .image, let imageData = rawFile.mapToImageData() {
    let width = imageData.getWidth()
    let height = imageData.getHeight()

    fileRepository.downloadImage(fromURL: imageData.fileURL, size: .medium) { localURL, error in
        print("Downloaded image: \(String(describing: localURL))")
    }
}
```

```kotlin Android
AmityCoreClient.newFileRepository()
    .getFile(imageFileId)
    .doOnSuccess { rawFile: AmityRawFile ->
        val image = rawFile.asAmityImage()
        val mediumUrl = image?.getUrl(AmityImage.Size.MEDIUM)
        val width = image?.getWidth()
        val height = image?.getHeight()
        val altText = image?.getAltText()
    }
    .subscribe()
```

```dart Flutter
void inspectImage(AmityImage image) {
  final mediumUrl = image.getUrl(AmityImageSize.MEDIUM);
  final width = image.getWidth();
  final height = image.getHeight();
  final isFullImage = image.isFullImage();
}
```


## Related Topics

    Attach uploaded images to social posts.
    Attach uploaded images to comments.
    Upload and inspect generic file attachments.

---

### [Video Handling](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/video-handling)

> Upload videos and read transcoding status or resolution URLs with the social.plus SDKs.

Use video handling when your app needs to upload video files for posts, messages, stories, clips, or other media experiences. Video uploads return a video file object with a `fileId`, original URL, and, on platforms that expose it, transcoding status and a map of generated resolution URLs.

The SDK exposes upload progress and video file metadata. Playback UI, caching, retry policy, and adaptive player behavior remain application concerns.

## Platform Surface

| Platform | Upload | Fetch | Status and resolutions | Frame dimensions | Notes |
| --- | --- | --- | --- | --- | --- |
| TypeScript | `FileRepository.uploadVideo(formData, feedType?, onProgress?)` | `FileRepository.getFile(fileId)` | `status` and `videoUrl` on the returned file | `getWidth()`, `getHeight()`, and `getRotation()` on a `'video'` file. Requires `@amityco/ts-sdk` 7.27.0 or later. | `ContentFeedType` includes `story`, `clip`, `chat`, `post`, and `message`. |
| iOS | `AmityFileRepository.uploadVideo(with:progress:)` and `uploadVideo(with:feedType:progress:completion:)` | `getFile(fileId:)`, then `mapToVideoData()` | `AmityVideoData.status`, `videoUrls`, and `getVideo(resolution:)` | No dedicated accessors. Read `attributes["metadata"]["video"]` off `AmityVideoData`. | The async upload method checks for files over 1 GB. The feed-type callback overload checks 4 GB and 2 hours. |
| Android | `AmityCoreClient.newFileRepository().uploadVideo(uri, contentFeedType)` | `getFile(fileId)`, then `asAmityVideo()` | `getStatus()`, `getResolutions()`, and `getVideoUrl(resolution)` | `getWidth()`, `getHeight()`, and `getRotation()` on `AmityVideo`. Requires Android SDK 7.26.0 or later. | `AmityContentFeedType` exposes `STORY`, `CLIP`, `MESSAGE`, and `POST`. |
| Flutter | `AmityCoreClient.newFileRepository().uploadVideo(file, feedtype?)` | Not exposed as a direct public file-repository fetch method in the current SDK | `AmityVideo.getResolutions()` and `getVideoUrl(resolution)` on video objects | `fileProperties.width` and `fileProperties.height` only. Rotation is not exposed. | `AmityContentFeedType` exposes `STORY`, `POST`, `MESSAGE`, and `CLIP`. |

## Parameters

| Parameter | Platforms | Description |
| --- | --- | --- |
| `formData` / `url` / `uri` / `file` | TypeScript, iOS, Android, Flutter | The local video input. TypeScript expects `FormData` with a `files` key; iOS accepts a local `URL`; Android accepts `Uri`; Flutter accepts `File`. |
| `feedType` / `contentFeedType` / `feedtype` | TypeScript, iOS, Android, Flutter | Optional or required video context depending on platform. It tells the backend which content surface the video is for. |
| `fileId` | TypeScript, iOS, Android | ID returned by upload or embedded in content data. Used for direct fetch where available. |
| `resolution` | TypeScript, iOS, Android, Flutter | Requested generated video URL. Exposed values include original, 1080p, 720p, 480p, and 360p where available for that upload. |
| `onProgress` / `progress` | TypeScript, iOS, Android, Flutter | Upload progress callback or stream event. |

## Upload A Video

Upload a video first, then use the returned video object or `fileId` in video-based content APIs.


```typescript TypeScript
import { ContentFeedType, FileRepository } from '@amityco/ts-sdk';

async function uploadVideo(video: File) {
  const formData = new FormData();
  formData.append('files', video);

  const { data: videos } = await FileRepository.uploadVideo(
    formData,
    ContentFeedType.POST,
    percent => {
      console.log(`Upload progress: ${percent}%`);
    },
  );

  return videos[0].fileId;
}
```

```swift iOS
let videoURL = URL(fileURLWithPath: "/tmp/video.mov")

let uploadedVideo = try await fileRepository.uploadVideo(
    with: videoURL,
    progress: { progress in
        print("Upload progress: \(progress)")
    }
)

let videoFileId = uploadedVideo.fileId
```

```kotlin Android
val videoUri = Uri.parse("file:///tmp/video.mp4")

AmityCoreClient.newFileRepository()
    .uploadVideo(
        uri = videoUri,
        contentFeedType = AmityContentFeedType.POST
    )
    .doOnNext { result: AmityUploadResult<AmityVideo> ->
        when (result) {
            is AmityUploadResult.PROGRESS -> {
                val progress = result.getUploadInfo().getProgressPercentage()
            }
            is AmityUploadResult.COMPLETE -> {
                val uploadedVideo = result.getFile()
                val videoFileId = uploadedVideo.getFileId()
            }
            is AmityUploadResult.ERROR -> {
                val error = AmityError.from(result.getError())
            }
            is AmityUploadResult.CANCELLED -> {
                // Upload was canceled.
            }
        }
    }
    .subscribe()
```

```dart Flutter
import 'dart:io';

final video = File('/tmp/video.mp4');

AmityCoreClient.newFileRepository()
    .uploadVideo(video, feedtype: AmityContentFeedType.POST)
    .stream
    .listen((AmityUploadResult<AmityVideo> result) {
  result.when(
    progress: (uploadInfo, cancelToken) {
      final progress = uploadInfo.getProgressPercentage();
    },
    complete: (uploadedVideo) {
      final videoFileId = uploadedVideo.fileId;
      final resolutions = uploadedVideo.getResolutions();
    },
    error: (error) {
      final exception = error;
    },
    cancel: () {
      // Upload was canceled.
    },
  );
});
```


## Read Video Status And URLs

Read video status and resolution URLs when your UI needs to render playback or processing state. The returned video file also carries the frame dimensions, but each platform surfaces them differently — see the **Frame dimensions** column above for the accessor and the minimum SDK version.

Width and height are the **stored** (pre-rotation) values. Apply the rotation to get the displayed orientation: swap width and height when `rotation % 180 != 0`.

Flutter exposes the stored width and height but **no rotation**. Width and height alone cannot determine the display orientation of a rotated video; use a media player or parser that handles orientation metadata.


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

async function getVideo(videoFileId: string) {
  // getFile does not narrow its return type, so cast to the video file shape
  // before reading the video-only members.
  const { data } = await FileRepository.getFile(videoFileId);
  const video = data as Amity.File<'video'>;
  const playbackUrl = video.videoUrl?.['720p'] ?? video.fileUrl;

  return {
    playbackUrl,
    status: video.status,
    width: video.getWidth(),
    height: video.getHeight(),
    rotation: video.getRotation(),
  };
}
```

```swift iOS
let rawFile = try await fileRepository.getFile(fileId: videoFileId)

if rawFile.type == .video, let videoData = rawFile.mapToVideoData() {
    let status = videoData.status
    let resolutions = Array(videoData.videoUrls.keys).sorted()
    let playbackURL = videoData.getVideo(resolution: .res_720p)

    // Stored frame dimensions. iOS has no dedicated accessors — read the raw metadata.
    let videoStream = (videoData.attributes["metadata"] as? [String: Any])?["video"] as? [String: Any]
    let width = videoStream?["width"] as? Int
    let height = videoStream?["height"] as? Int
    let rotation = videoStream?["rotation"] as? Int
}
```

```kotlin Android
import com.amity.socialcloud.sdk.helper.core.asAmityVideo

AmityCoreClient.newFileRepository()
    .getFile(videoFileId)
    .doOnSuccess { rawFile: AmityRawFile ->
        val video = rawFile.asAmityVideo()
        val status = video?.getStatus()
        val resolutions = video?.getResolutions().orEmpty()
        val playbackUrl = video?.getVideoUrl(AmityVideoResolution.RES_720)
        val width = video?.getWidth()
        val height = video?.getHeight()
        val rotation = video?.getRotation()
    }
    .subscribe()
```

```dart Flutter
void inspectVideo(AmityVideo video) {
  final resolutions = video.getResolutions();
  final playbackUrl = video.getVideoUrl(AmityVideoResolution.RES_720);

  // Stored frame dimensions. They live on the file properties, not on AmityVideo,
  // and Flutter does not expose the rotation that goes with them.
  final int? width = video.fileProperties.width;
  final int? height = video.fileProperties.height;
}
```


## Related Topics

    Attach uploaded videos to social posts.
    Upload and inspect generic file attachments.
    Create short-form clip posts where supported.

---

### [Mentions](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/mentions)

> Attach user mention payloads and mention metadata when creating or editing posts, comments, and messages.

Mentions are attached to content creation or edit calls. They use two pieces of data: `mentionees` tells social.plus which users or channel are mentioned, and `metadata` stores the text ranges your UI can use to render the highlighted mention text.

  User mentions are available on posts, comments, and messages. Channel mentions are message-only.

## Platform Surface

| Platform | Mentionees payload | Mention metadata helper |
| --- | --- | --- |
| TypeScript | `mentionees: [{ type: "user", userIds: [...] }]` | Plain `metadata` object with `mentioned` entries |
| iOS | `AmityMentioneesBuilder` | `AmityMetadataMapper.metadata(mentions:)` |
| Android | `mentionUserIds` on post APIs or `mentionUsers()` on builders | `AmityMentionMetadataCreator` |
| Flutter | `mentionUsers()` on builders | `AmityMentionMetadataCreator` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `text` | Yes | Content text that includes the mention display text, such as `@alex`. |
| `mentionees` / mention builder | Yes for mention behavior | Users or channel being mentioned. Posts and comments support user mentionees; messages support user and channel mentionees. |
| `metadata` | Recommended for rendering | Metadata object containing mention text ranges under `mentioned`. |
| `type` | Yes in metadata | Use `user` for user mentions or `channel` for message channel mentions. |
| `index` | Yes in metadata | Zero-based index where the mention starts in the content text. |
| `length` | Yes in metadata | Length of the display name after the `@` character. For `@alex`, use `4`. |
| `userId` | User mentions only | ID of the mentioned user. |

## Create Content With A User Mention

The examples below create a community text post that mentions one user. Use the same mentionee and metadata pattern when creating comments or messages with the SDK-specific creation API.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const text = "Hello @alex";
const metadata = {
  mentioned: [
    {
      type: "user",
      userId,
      index: 6,
      length: 4,
    },
  ],
};

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: { text },
  metadata,
  mentionees: [{ type: "user", userIds: [userId] }],
});
```

```swift iOS
let text = "Hello @alex"
let mention = AmityMention(
    type: .user,
    index: 6,
    length: 4,
    userId: userId
)
let metadata = AmityMetadataMapper.metadata(mentions: [mention])

let mentionees = AmityMentioneesBuilder()
mentionees.mentionUsers(userIds: [userId])

let builder = AmityTextPostBuilder()
builder.setText(text)

let post = try await postRepository.createTextPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: metadata,
    mentionees: mentionees
)
```

```kotlin Android
import com.amity.socialcloud.sdk.helper.core.mention.AmityMentionMetadata
import com.amity.socialcloud.sdk.helper.core.mention.AmityMentionMetadataCreator

val text = "Hello @alex"
val mentionMetadata = AmityMentionMetadata.USER(
    userId = userId,
    index = 6,
    length = 4
)
val metadata = AmityMentionMetadataCreator(
    mentionMetaData = listOf(mentionMetadata)
).create()

postRepository.createTextPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    text = text,
    metadata = metadata,
    mentionUserIds = setOf(userId)
)
    .subscribe(
        { post -> showSuccessMessage(post.getPostId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final text = 'Hello @alex';
final metadata = AmityMentionMetadataCreator([
  AmityUserMentionMetadata(
    userId: userId,
    index: 6,
    length: 4,
  ),
]).create();

final creator = AmitySocialClient.newPostRepository()
    .createPost()
    .targetCommunity(communityId)
    .text(text);

creator.mentionUsers([userId]);
creator.metadata(metadata);

final post = await creator.createTextPost();
```


## Rendering Mentions

Use the content text and `metadata.mentioned` entries together when rendering. The `mentionees` payload identifies mentioned users or channel targets, while `metadata` identifies where the mention appears in the text.

| Metadata field | Meaning |
| --- | --- |
| `type` | `user` or `channel` |
| `index` | Start position of the mention in the text |
| `length` | Display-name length after `@` |
| `userId` | Present for user mentions |

## Notes

- Keep `metadata` and `mentionees` in sync. A highlighted `@alex` without a matching mentionee payload is only display metadata.
- Use the user IDs returned by your mention picker. Display names can change, but user IDs are the stable mention target.
- For messages, channel mentions use a channel mentionee entry. Posts and comments use user mentionees.
- Existing content models expose mention information after creation; use the model returned by the SDK or a fresh query when your UI needs server-confirmed state.

## Related Topics

    Create text posts that can carry mention metadata
    Add user mentions to comments and replies
    Use user and channel mentions in chat messages

---

### [Polls](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/poll)

> Create polls, collect votes, and manage poll lifecycle with the social.plus SDKs.

Polls are created first, then attached to poll posts when you want them to appear in a feed. The SDKs expose poll creation, voting, closing, and deletion APIs. TypeScript, iOS, and Android also expose an unvote API; the current Flutter public poll repository does not expose unvote.

## Platform Surface

| Platform | Create | Vote | Unvote | Close | Delete |
| --- | --- | --- | --- | --- | --- |
| TypeScript | `PollRepository.createPoll()` | `votePoll()` | `unvotePoll()` | `closePoll()` | `deletePoll()` |
| iOS | `AmityPollRepository.createPoll()` | `votePoll(withId:answerIds:)` | `unvotePoll(withId:)` | `closePoll(withId:)` | `deletePoll(withId:)` |
| Android | `AmitySocialClient.newPollRepository().createPoll()` | `votePoll()` | `unvotePoll()` | `closePoll()` | `deletePoll()` |
| Flutter | `AmitySocialClient.newPollRepository().createPoll()` | `vote()` | Not exposed | `closePoll()` | `deletePoll()` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `question` | Yes | Poll question text. |
| `answers` | Yes | Text or image answer options, depending on SDK and answer type. |
| `answerType` | No | Single-choice or multiple-choice poll. Defaults to single-choice where the SDK builder provides a default. |
| `closedIn` / close duration | No | Optional poll close duration. Mobile SDKs expose milliseconds or `Duration`; TypeScript passes `closedIn` through as a numeric field. |
| `pollId` | Required after creation | ID returned by poll creation and used for voting, closing, deleting, and poll posts. |
| `answerIds` | Required for voting | Answer IDs selected by the user. |

## Create A Poll

Create the poll first and keep the returned `pollId` if you need to create a poll post.


```typescript TypeScript
import { PollRepository } from "@amityco/ts-sdk";

const { data: poll } = await PollRepository.createPoll({
  question: "Which feature should we build next?",
  answerType: "single",
  answers: [
    { dataType: "text", data: "Bookmarks" },
    { dataType: "text", data: "Pinned comments" },
  ],
});

const createdPollId = poll.pollId;
```

```swift iOS
let pollRepository = AmityPollRepository()
let options = AmityPollCreateOptions()
options.setQuestion("Which feature should we build next?")
options.setAnswerType(.single)
options.setAnswer("Bookmarks")
options.setAnswer("Pinned comments")

let createdPollId = try await pollRepository.createPoll(options)
```

```kotlin Android
import com.amity.socialcloud.sdk.model.social.poll.AmityPollAnswer

val pollRepository = AmitySocialClient.newPollRepository()

pollRepository.createPoll("Which feature should we build next?")
    .answers(
        listOf(
            AmityPollAnswer.Data.TEXT("Bookmarks"),
            AmityPollAnswer.Data.TEXT("Pinned comments")
        )
    )
    .answerType(AmityPoll.AnswerType.SINGLE)
    .build()
    .create()
    .subscribe(
        { createdPollId -> showSuccessMessage(createdPollId) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final poll = await AmitySocialClient.newPollRepository()
    .createPoll(question: 'Which feature should we build next?')
    .answers(answers: [
      AmityPollAnswer.text('Bookmarks'),
      AmityPollAnswer.text('Pinned comments'),
    ])
    .answerType(answerType: AmityPollAnswerType.SINGLE)
    .create();

final createdPollId = poll.pollId;
```


## Vote And Manage A Poll

Use answer IDs from the poll object when voting. Closing and deletion use the poll ID.


```typescript TypeScript
import { PollRepository } from "@amityco/ts-sdk";

const answerIds = ["answer-id"];

const { data: votedPoll } = await PollRepository.votePoll(pollId, answerIds);
await PollRepository.unvotePoll(pollId);

const { data: closedPoll } = await PollRepository.closePoll(pollId);
const isDeleted = await PollRepository.deletePoll(pollId);
```

```swift iOS
let pollRepository = AmityPollRepository()
let answerIds = ["answer-id"]

try await pollRepository.votePoll(withId: pollId, answerIds: answerIds)
try await pollRepository.unvotePoll(withId: pollId)
try await pollRepository.closePoll(withId: pollId)
try await pollRepository.deletePoll(withId: pollId)
```

```kotlin Android
val pollRepository = AmitySocialClient.newPollRepository()
val answerIds = listOf("answer-id")

pollRepository.votePoll(pollId, answerIds)
    .subscribe(
        { showSuccessMessage("Vote submitted") },
        { error -> handleGeneralError(error) }
    )

pollRepository.unvotePoll(pollId)
    .subscribe(
        { showSuccessMessage("Vote removed") },
        { error -> handleGeneralError(error) }
    )

pollRepository.closePoll(pollId)
    .subscribe(
        { showSuccessMessage("Poll closed") },
        { error -> handleGeneralError(error) }
    )

pollRepository.deletePoll(pollId)
    .subscribe(
        { showSuccessMessage("Poll deleted") },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final pollRepository = AmitySocialClient.newPollRepository();
final answerIds = ['answer-id'];

await pollRepository.vote(pollId: pollId, answerIds: answerIds);
final closedPoll = await pollRepository.closePoll(pollId: pollId);
final isDeleted = await pollRepository.deletePoll(pollId: pollId);
```


## Notes

- Create a poll post separately after poll creation. Poll creation returns a poll ID; poll-post creation attaches that ID to feed content.
- Use `answerType` values that match each SDK: TypeScript uses `single` or `multiple`, iOS uses `.single` or `.multiple`, Android uses `AmityPoll.AnswerType`, and Flutter uses `AmityPollAnswerType`.
- Flutter currently exposes `vote`, `closePoll`, and `deletePoll`, but not an unvote method on the public poll repository.
- Deletion and close behavior depends on server-side permissions for the current user.

## Related Topics

    Attach an existing poll to a feed post
    Create regular text posts for the same feed targets
    Fetch posts that contain poll data

---

### [Reactions](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/reactions)

> Query, add, and remove reactions on posts, comments, stories, and messages with the social.plus SDKs.

Reactions let signed-in users attach a named reaction such as `like` to content. The SDKs expose the same core shape on every platform: choose a reference type, pass the content ID, and pass the reaction name.

## Platform Surface

| Platform | Query reactions | Add reaction | Remove reaction |
| --- | --- | --- | --- |
| TypeScript | `ReactionRepository.getReactions()` | `ReactionRepository.addReaction()` | `ReactionRepository.removeReaction()` |
| iOS | `AmityReactionRepository.getReactions()` | `AmityReactionRepository.addReaction()` | `AmityReactionRepository.removeReaction()` |
| Android | `AmityCoreClient.newReactionRepository().getReactions()` | `addReaction()` | `removeReaction()` |
| Flutter | `AmitySocialClient.newReactionRepository().getReactions()` | `addReaction()` | `removeReaction()` |

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `referenceType` | Yes | TypeScript, iOS, Android, Flutter | Content type being reacted to. Supported values are post, comment, story, and message. |
| `referenceId` | Yes | TypeScript, iOS, Android, Flutter | ID of the post, comment, story, or message. |
| `reactionName` | Yes for add/remove, optional for query | TypeScript, iOS, Android, Flutter | Reaction key such as `like`. Query APIs can use it as a filter. |
| `callback` / live collection observer | Query only | TypeScript, iOS, Android, Flutter | Used by live collection APIs to receive reaction updates. |

## Query Reactions

Use `reactionName` when the UI only needs one reaction type. Omit it to read all reaction types for the content.


```typescript TypeScript
import { ReactionRepository } from "@amityco/ts-sdk";

const unsubscribe = ReactionRepository.getReactions(
  {
    referenceType: "post",
    referenceId: postId,
    reactionName: "like",
  },
  ({ data }) => {
    renderResults(data);
  }
);
```

```swift iOS
let reactionRepository = AmityReactionRepository()
let reactions = reactionRepository.getReactions(
    postId,
    referenceType: .post,
    reactionName: "like"
)

token = reactions.observe { collection, error in
    guard error == nil else { return }
    let currentReactions = collection.snapshots
    showSuccessMessage(currentReactions.count)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.reaction.AmityReactionReferenceType

AmityCoreClient.newReactionRepository()
    .getReactions(
        referenceType = AmityReactionReferenceType.POST,
        referenceId = postId,
        reactionName = "like"
    )
    .subscribe(
        { reactions -> showSuccessMessage(reactions) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final reactions = AmitySocialClient.newReactionRepository()
    .getReactions(AmityPostReactionReference(referenceId: postId))
    .reactionName('like')
    .getLiveCollection();
```


## Add And Remove Reactions

Adding or removing a reaction returns completion or success from the SDK call. Keep UI counts synced from the content model or the reaction live collection.


```typescript TypeScript
import { ReactionRepository } from "@amityco/ts-sdk";

await ReactionRepository.addReaction("post", postId, "like");
await ReactionRepository.removeReaction("post", postId, "like");
```

```swift iOS
let reactionRepository = AmityReactionRepository()

try await reactionRepository.addReaction(
    "like",
    referenceId: postId,
    referenceType: .post
)

try await reactionRepository.removeReaction(
    "like",
    referenceId: postId,
    referenceType: .post
)
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.reaction.AmityReactionReferenceType

val reactionRepository = AmityCoreClient.newReactionRepository()

reactionRepository.addReaction(
    referenceType = AmityReactionReferenceType.POST,
    referenceId = postId,
    reactionName = "like"
)
    .subscribe(
        { showSuccessMessage("Reaction added") },
        { error -> handleGeneralError(error) }
    )

reactionRepository.removeReaction(
    referenceType = AmityReactionReferenceType.POST,
    referenceId = postId,
    reactionName = "like"
)
    .subscribe(
        { showSuccessMessage("Reaction removed") },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final reactionRepository = AmitySocialClient.newReactionRepository();
final reference = AmityPostReactionReference(referenceId: postId);

await reactionRepository.addReaction(reference, 'like');
await reactionRepository.removeReaction(reference, 'like');
```


## Notes

- TypeScript accepts `post`, `comment`, `story`, and `message` as reaction reference types.
- iOS, Android, and Flutter expose equivalent enum or reference classes for post, comment, story, and message.
- Message reactions use the message reaction path in the SDKs. Do not use post or comment reference types for messages.
- Reaction names are application-defined strings. Use the same values when adding, removing, and filtering.

## Related Topics

    React to comments and keep comment threads interactive
    Use the same reaction concept with story content
    Add and remove reactions on chat messages

---

### [Ads](https://learn.social.plus/social-plus-sdk/core-concepts/content-handling/ads)

> Fetch configured network ads and track ad impressions or link clicks with the social.plus SDKs.

Network ads are fetched through the core ad repository. The returned ad objects include display fields, linked advertiser or image data where available, and analytics methods for impression and click tracking.

## Platform Surface

| Platform | Fetch network ads | Track seen | Track clicked |
| --- | --- | --- | --- |
| TypeScript | `AdRepository.getNetworkAds()` | `ad.analytics.markAsSeen()` | `ad.analytics.markLinkAsClicked()` |
| iOS | `AmityAdRepository.getNetworkAds()` | `ad.analytics.markAsSeen()` | `ad.analytics.markLinkAsClicked()` |
| Android | `AmityCoreClient.newAdRepository().getNetworkAds()` | `adRepository.analytics(ad).markAsSeen()` | `adRepository.analytics(ad).markLinkAsClicked()` |
| Flutter | `AmityCoreClient.newAdRepository().getNetworkAds()` | `adRepository.analytics(ad).markAsSeen()` | `adRepository.analytics(ad).markLinkAsClicked()` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `ad` | Tracking only | Ad object returned from the network ads response. |
| `placement` | Tracking only | Where the ad was displayed. SDK enum values include feed, story, comment, chat, and chat list placements. |
| `settings` | No | Network ad settings returned with the ad list. Use them to decide how your app presents ads. |

## Fetch And Track Ads

Call the tracking methods when the ad is actually shown or when the ad link is clicked in your UI.


```typescript TypeScript
import { AdRepository } from "@amityco/ts-sdk";

const networkAds = await AdRepository.getNetworkAds();
const ad = networkAds.ads[0];

if (ad) {
  const placement = Amity.AdPlacement.FEED;
  ad.analytics.markAsSeen(placement);
  ad.analytics.markLinkAsClicked(placement);
}
```

```swift iOS
let adRepository = AmityAdRepository()
let networkAds = try await adRepository.getNetworkAds()

if let ad = networkAds.ads.first {
    ad.analytics.markAsSeen(placement: .feed)
    ad.analytics.markLinkAsClicked(placement: .feed)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.ad.AmityAdPlacement

val adRepository = AmityCoreClient.newAdRepository()

adRepository.getNetworkAds()
    .subscribe(
        { networkAds ->
            val ad = networkAds.getAds().firstOrNull()
            if (ad != null) {
                adRepository.analytics(ad).markAsSeen(AmityAdPlacement.FEED)
                adRepository.analytics(ad).markLinkAsClicked(AmityAdPlacement.FEED)
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final adRepository = AmityCoreClient.newAdRepository();
final networkAds = await adRepository.getNetworkAds();
final ads = networkAds.getAds() ?? [];

if (ads.isNotEmpty) {
  final ad = ads.first;
  await adRepository.analytics(ad).markAsSeen(AmityAdPlacement.FEED);
  await adRepository.analytics(ad).markLinkAsClicked(AmityAdPlacement.FEED);
}
```


## Notes

- Fetching ads returns both `ads` and `settings`. Use settings as display configuration from the SDK response.
- Track `markAsSeen` only after the ad is rendered in the placement you pass.
- Track `markLinkAsClicked` from the UI action that opens or handles the ad call-to-action link.
- Use the placement enum from each SDK instead of hardcoded placement strings.

## Related Topics

    Place feed ads alongside feed content
    Use story placement when ads are displayed in stories
    Coordinate ad placement with chat surfaces

## Core Concepts — Realtime

### [Live Objects & Collections](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview)

> Understand how the social.plus SDKs expose live objects and live collections for cache-backed, real-time data.

Live objects and live collections are SDK patterns for reading data that can change after your first request. They let your app subscribe to SDK-managed state instead of treating every query as a one-time network response.

Use a live object when the screen is centered on one entity, such as a post, message, channel, community, user, room, stream, poll, or story. Use a live collection when the screen renders a list, such as posts, comments, messages, members, followers, reactions, rooms, or streams.

## Platform Surface

| Platform | Live object | Live collection | Pagination | Cleanup |
| --- | --- | --- | --- | --- |
| TypeScript | `Amity.LiveObject<T>` delivered to repository callbacks such as `PostRepository.getPost()` | `Amity.LiveCollection<T>` delivered to query callbacks such as `PostRepository.getPosts()` | `onNextPage`, `hasNextPage`, `onPrevPage`, `hasPrevPage` when supported by that query | Call the returned `Amity.Unsubscriber`; also unsubscribe from any real-time topics you subscribed to |
| iOS | `AmityObject<T>` | `AmityCollection<T>` | `nextPage()`, `previousPage()`, `hasNext`, `hasPrevious`, `resetPage()` | Retain the returned `AmityNotificationToken`; call `invalidate()` or release the token |
| Android | `Flowable<T>` from repository methods such as `getPost(postId)` | `Flowable<PagingData<T>>` or `Flowable<List<T>>`, depending on the query | Android Paging 3 through `PagingData` for paged collections | Dispose the RxJava subscription or cancel the coroutine collector |
| Flutter | `Stream<T>` from live-object builders such as `live.getPost(postId)` | `LiveCollection<T>` / `LiveCollectionStream<T>` | `loadNext()`, `loadPrevious()`, `hasNextPage()`, `hasPreviousPage()`, `reset()` | Cancel stream subscriptions and call `dispose()` on live collections |

## Data Sources

Live results can be updated by more than one source:

| Source | What it means |
| --- | --- |
| Local cache | The SDK may emit cached data first so the UI can render quickly. |
| Server fetch | The SDK fetches newer data and updates the same live object or live collection. |
| Local mutation | Actions from the current device update the local SDK store and notify observers. |
| Real-time event | Events from subscribed topics update the SDK store and notify observers. |

Live objects and collections observe SDK state. They do not remove the need to subscribe to the right real-time topics where a platform exposes explicit topic subscriptions.

## Live Object

A live object tracks one entity. The SDK can emit:

| State | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Current data | `snapshot.data` | `liveObject.snapshot` | emitted `T` value | emitted `T` value |
| Loading | `snapshot.loading` | `loadingStatus` | stream lifecycle / app state | stream lifecycle / app state |
| Error | `snapshot.error` | `error` or observer `error` parameter | `onError` | stream `onError` |
| Freshness/origin | `origin` | `dataStatus` | not exposed as a shared public enum | not exposed as a shared public enum |

Typical screens: post detail, message detail, channel profile, community header, user profile, room detail, or stream detail.

## Live Collection

A live collection tracks a list. The SDK can append, refresh, or re-emit the list when local cache, server fetches, or real-time events change the underlying data.

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Current list | `collection.data` | `collection.snapshots` | `PagingData<T>` or `List<T>` emission | `LiveResult<T>.data` |
| Loading | `collection.loading` | `loadingStatus` | paging load state / Rx lifecycle | `LiveResult<T>.isFetching` and `observeLoadingState()` |
| Next page | `collection.onNextPage?.()` | `collection.nextPage()` | collect more through Paging 3 | `collection.loadNext()` |
| Reset | Recreate the query or collection | `collection.resetPage()` | invalidate/recreate the paging source or query | `collection.reset()` |

Typical screens: post feeds, comment threads, chat messages, channel lists, member lists, reaction lists, follower lists, rooms, streams, and notifications.

## Usage Notes

- Keep the live subscription for as long as the UI needs updates.
- Clean up subscriptions when the screen, component, view model, or widget is disposed.
- Treat the first emission as potentially local or loading unless the platform exposes freshness status and it says otherwise.
- Do not assume all platforms expose identical states. Use each platform's native live primitive.
- For TypeScript, subscribe to the relevant topic when you need cross-device real-time updates, then dispose both the repository observer and the topic subscription.

## Platform Guides

    Observe live objects and collections with callbacks, pagination helpers, and topic subscriptions.
    Use `AmityObject`, `AmityCollection`, notification tokens, and published snapshots.
    Use RxJava `Flowable`, Android Paging 3, and the coroutine `asFlow()` bridge.
    Use Dart streams, `LiveCollection`, `LiveResult`, and collection disposal.

## Related Topics

    Learn how real-time events update SDK state.
    Track user, channel, and room presence.

---

### [Android Live Objects & Collections](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/android)

> Observe social.plus Android SDK objects and collections with RxJava Flowable, Android Paging, and coroutine flows.

The Android SDK exposes live objects and collections through RxJava 3 streams. Singular reads such as `getPost(postId)` return `Flowable<T>`. Paged list queries return `Flowable<PagingData<T>>`. Some finite list queries return `Flowable<List<T>>`.

Use RxJava directly, or convert supported streams to Kotlin `Flow` with the SDK coroutine bridge.

## Platform Surface

| Surface | Public shape | Notes |
| --- | --- | --- |
| Live object | `Flowable<T>` | Repository methods such as `AmitySocialClient.newPostRepository().getPost(postId)`. |
| Paged live collection | `Flowable<PagingData<T>>` | Query builders such as `getPosts().targetCommunity(...).build().query()`. |
| Finite live collection | `Flowable<List<T>>` | Used by selected APIs such as get-by-IDs style queries. |
| Coroutine bridge | `Flowable<T>.asFlow()` | Import `com.amity.socialcloud.sdk.helper.core.coroutines.asFlow`. |
| Cleanup | `Disposable.dispose()` or coroutine cancellation | Dispose or cancel when the Activity, Fragment, ViewModel, or UI scope no longer needs updates. |

## Parameters

| Parameter | Used by | Platforms | Description |
| --- | --- | --- | --- |
| `postId` or another entity ID | Live object methods | Android | ID of the object to observe. |
| Query builder target | Live collection builders | Android | Scope for the collection, such as `targetCommunity(communityId)` or `targetUser(userId)`. |
| `PagingData<T>` | Paged collections | Android | The emitted paging payload consumed by RecyclerView, Paging 3, or Compose paging. |
| `subscribeOn(Schedulers.io())` | RxJava streams | Android | Runs SDK work on an IO scheduler. |
| `observeOn(AndroidSchedulers.mainThread())` | UI observers | Android | Delivers callbacks on the Android main thread for UI updates. |

## Observe A Live Object

Observe a live object when your Android UI needs one SDK object to stay current after server or local-store changes.


```kotlin Android
val disposable = AmitySocialClient.newPostRepository()
    .getPost(postId)
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(
        { post: AmityPost ->
            showSuccessMessage(post.getPostId())
        },
        { error: Throwable ->
            handleGeneralError(error)
        }
    )

disposable.dispose()
```


## Observe A Paged Live Collection

The SDK query emits `PagingData<AmityPost>`. Feed it into your Paging 3 adapter or Compose paging collector.


```kotlin Android
val disposable = AmitySocialClient.newPostRepository()
    .getPosts()
    .targetCommunity(communityId)
    .includeDeleted(false)
    .build()
    .query()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(
        { pagingData: PagingData<AmityPost> ->
            showSuccessMessage(pagingData)
        },
        { error: Throwable ->
            handleGeneralError(error)
        }
    )

disposable.dispose()
```


## Convert to Kotlin Flow

Use the coroutine bridge when the rest of your app is built around Kotlin Flow.


```kotlin Android
import com.amity.socialcloud.sdk.helper.core.coroutines.asFlow

val postFlow = AmitySocialClient.newPostRepository()
    .getPost(postId)
    .asFlow()
```


## Notes

- A live object fetches the server object and then observes the SDK local store. The internal live-object use case also checks tombstones for hard-deleted objects.
- Paged live collections use Android Paging 3, so page loading and UI load states should be handled through your Paging adapter or Compose paging integration.
- Dispose RxJava subscriptions in the matching lifecycle owner or ViewModel. For coroutines, cancel the collecting scope.
- Use `subscribeOn(Schedulers.io())` for SDK work and `observeOn(AndroidSchedulers.mainThread())` before mutating UI state.

## Related Topics

    See post-specific Android query examples.
    Configure Android notification setup alongside real-time data.

---

### [Flutter Live Objects & Collections](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/flutter)

> Observe social.plus Flutter SDK objects and collections with Dart streams, LiveCollection, and LiveResult.

The Flutter SDK exposes live objects as Dart streams and live collections through `LiveCollection` / `LiveCollectionStream`. A live collection emits `LiveResult<T>`, which contains the current `data` list and an `isFetching` flag.

## Platform Surface

| Surface | Public shape | Notes |
| --- | --- | --- |
| Live object | `Stream<T>` | Example: `AmitySocialClient.newPostRepository().live.getPost(postId)`. |
| Live collection | `LiveCollection<T>` | Returned by builders such as `getPosts().targetCommunity(...).getLiveCollection()`. |
| Collection stream | `Stream<LiveResult<T>>` | Access with `liveCollection.getStream()`. |
| Loading state | `LiveResult<T>.isFetching` or `observeLoadingState()` | Use this to drive loading indicators. |
| Pagination | `loadNext()`, `loadPrevious()`, `hasNextPage()`, `hasPreviousPage()`, `reset()` | `getStream()` also triggers the first load. |
| Cleanup | `StreamSubscription.cancel()` and `liveCollection.dispose()` | Cancel listeners and dispose the live collection when the widget or bloc is done. |

## Parameters

| Parameter | Used by | Platforms | Description |
| --- | --- | --- | --- |
| `postId` or another entity ID | Live object streams | Flutter | ID of the object to observe. |
| Query builder target | Live collections | Flutter | Scope for the collection, such as `targetCommunity(communityId)` or `targetUser(userId)`. |
| `pageSize` | Live collections | Flutter | Optional page size for `getLiveCollection(pageSize: ...)`. Defaults to 20 when omitted. |
| `LiveResult<T>.data` | Collection stream | Flutter | Current list snapshot. |
| `LiveResult<T>.isFetching` | Collection stream | Flutter | Whether the collection is currently fetching. |

## Observe A Live Object

Observe a live object when your Flutter UI needs one SDK object to stay current after server or local-cache changes.


```dart Flutter
final subscription = AmitySocialClient.newPostRepository()
    .live
    .getPost(postId)
    .listen((post) {
  final currentPostId = post.postId;
  showError(currentPostId ?? postId);
});

await subscription.cancel();
```


## Observe A Live Collection

`getStream()` emits `LiveResult<AmityPost>`. Keep the collection instance so you can load more pages and dispose it later.


```dart Flutter
final liveCollection = AmitySocialClient.newPostRepository()
    .getPosts()
    .targetCommunity(communityId)
    .getLiveCollection(pageSize: 20);

liveCollection.onError((error, stackTrace) {
  showError(error ?? stackTrace);
});

final subscription = liveCollection.getStream().listen((result) {
  final posts = result.data;
  final isFetching = result.isFetching;

  showError('${posts.length}:$isFetching');
});

if (liveCollection.hasNextPage()) {
  await liveCollection.loadNext();
}

await subscription.cancel();
await liveCollection.dispose();
```


## Notes

- `getStream()` starts the first page load for `LiveCollection`.
- Use `observeLoadingState()` when you only need loading changes.
- Call `loadNext()` only when `hasNextPage()` is true.
- Call `reset()` to clear the collection and reload the first page.
- Cancel every `StreamSubscription` and call `dispose()` on live collections that are no longer used.

## Related Topics

    See post-specific Flutter retrieval examples.
    Configure Flutter notification setup alongside real-time data.

---

### [iOS Live Objects & Collections](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/ios)

> Observe social.plus iOS SDK objects and collections with AmityObject, AmityCollection, notification tokens, and published snapshots.

The iOS SDK exposes live objects with `AmityObject<T>` and live collections with `AmityCollection<T>`. Both are `ObservableObject`s and expose published state for SwiftUI or Combine. Block observation is tied to `AmityNotificationToken`; retain the token while you need updates.

## Platform Surface

| Surface | Public API | Notes |
| --- | --- | --- |
| Live object | `AmityObject<T>` | Exposes `snapshot`, `dataStatus`, `loadingStatus`, and `error`. |
| Live collection | `AmityCollection<T>` | Exposes `snapshots`, `dataStatus`, `loadingStatus`, and `error`. |
| Block observer | `observe { ... }` | Can emit multiple times while the token is retained. |
| One-time observer | `observeOnce { ... }` | Invalidates after one notification. |
| Cleanup | `AmityNotificationToken.invalidate()` | Releasing the token also ends observation. |
| Collection pagination | `nextPage()`, `previousPage()`, `resetPage()` | Check `hasNext` or `hasPrevious` before requesting more pages. |

## Parameters And State

| Name | Applies to | Description |
| --- | --- | --- |
| `AmityNotificationToken` | Object and collection observers | Retain it strongly for the lifetime of the observation. Invalidate it when the view no longer needs updates. |
| `snapshot` | `AmityObject<T>` | The current object snapshot, or `nil` if the object is not available. |
| `snapshots` | `AmityCollection<T>` | The current collection snapshot array. |
| `dataStatus` | Object and collection | `notExist`, `local`, `fresh`, or `error`. Use this when freshness matters. |
| `loadingStatus` | Object and collection | `notLoading`, `loading`, `loaded`, or `error`. |
| `hasNext` / `hasPrevious` | Collection | Indicates whether another page can be requested. |

## Observe A Live Object

This example observes one post. Keep `token` in view-controller, view-model, or view scope; invalidate it when the screen disappears.


```swift iOS
let livePost = postRepository.getPost(withId: postId)

token = livePost.observe { observedPost, error in
    if let error = error {
        handleError(error)
        return
    }

    guard let post = observedPost.snapshot else {
        return
    }

    showSuccessMessage(post.postId)
}

func stopObservingPost() {
    token?.invalidate()
    token = nil
}
```


## Observe A Live Collection

`AmityCollection` emits through `snapshots`. Use pagination methods on the collection instance, not array indexing helpers from older SDK generations.


```swift iOS
let options = AmityPostQueryOptions(
    targetType: .community,
    targetId: communityId,
    sortBy: .lastCreated,
    deletedOption: .notDeleted,
    dataTypes: nil
)

let livePosts = postRepository.getPosts(options)

token = livePosts.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let posts = collection.snapshots
    let isFresh = collection.dataStatus == .fresh

    showSuccessMessage(posts.count)
    showSuccessMessage(isFresh)
}

if livePosts.hasNext {
    livePosts.nextPage()
}
```


## Observe Published Snapshots

`AmityObject` and `AmityCollection` are also observable from SwiftUI or Combine through published properties.


```swift iOS
var cancellable: AnyCancellable?

let livePost = postRepository.getPost(withId: postId)

cancellable = livePost.$snapshot.sink { post in
    guard let post = post else {
        return
    }

    showSuccessMessage(post.postId)
}
```


## Notes

- Current iOS SDK live objects expose `snapshot`; live collections expose `snapshots`.
- Do not use older `object`, `object(at:)`, or `count()` patterns with current live objects and collections.
- Observer callbacks are dispatched on the main thread.
- If an object has local data, the SDK can emit local state before fresh server state.
- For fresh-only flows, wait until `dataStatus == .fresh`, then invalidate the token if you do not need future updates.
- For SwiftUI, pass the live object or collection directly into the view that observes it. Nested `ObservableObject` containers can hide changes from SwiftUI.

## Related Topics

    See post-specific iOS retrieval examples.
    Learn how server events keep SDK state fresh.

---

### [TypeScript Live Objects & Collections](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/typescript)

> Observe social.plus TypeScript SDK objects and collections with callbacks, pagination helpers, and real-time topic subscriptions.

The TypeScript SDK exposes live objects and live collections through repository callbacks. A live object callback receives one object snapshot. A live collection callback receives a list snapshot plus pagination helpers when the query supports paging.

Repository observers watch SDK cache state. For cross-device real-time updates, subscribe to the topic that matches the object or collection scope, then clean up both the repository observer and the topic subscription.

## Platform Surface

| Surface | Public shape | Notes |
| --- | --- | --- |
| Live object | `Amity.LiveObject<T>` | Callback payload includes `data`, `loading`, `error`, and optional `origin`. |
| Live collection | `Amity.LiveCollection<T>` | Extends the live-object shape with `onNextPage`, `hasNextPage`, `onPrevPage`, and `hasPrevPage` where available. |
| Observer cleanup | `Amity.Unsubscriber` | Repository live methods return an unsubscribe function. |
| Real-time topic cleanup | `Amity.Unsubscriber` | `subscribeTopic()` returns a separate unsubscribe function. |
| Collection config | `Amity.LiveCollectionConfig` | Supports query policies except `no_fetch`. |

## Parameters

| Parameter | Used by | Platforms | Description |
| --- | --- | --- | --- |
| `postId` or another entity ID | Live object methods | TypeScript | ID of the object to observe, such as a post, message, channel, community, user, poll, room, or stream. |
| `params.targetType` / `params.targetId` | Collection queries such as `PostRepository.getPosts()` | TypeScript | Scope for the list. For posts, `targetType` is commonly `user` or `community`. |
| `limit` | Collection queries | TypeScript | Optional page size for the query. |
| `callback` | Object and collection methods | TypeScript | Receives each live snapshot. Handle `loading` and `error` before rendering data. |
| `onNextPage` / `hasNextPage` | Live collections | TypeScript | Use when the UI asks for the next page. Do not call `onNextPage` repeatedly without checking `hasNextPage`. |
| `subscribeTopic(topic, callback?)` | Real-time updates | TypeScript | Subscribes the active client to a topic such as `getPostTopic(post)` or `getCommunityTopic(community, SubscriptionLevels.POST)`. |

## Observe A Live Object

This example observes one post and subscribes to the post topic after the first post snapshot is available.


```typescript TypeScript
import { PostRepository, getPostTopic, subscribeTopic } from "@amityco/ts-sdk";

let unsubscribePostTopic: Amity.Unsubscriber | undefined;

const unsubscribePost = PostRepository.getPost(postId, snapshot => {
  if (snapshot.loading) {
    showLoading();
  }

  if (snapshot.error) {
    handleError(snapshot.error);
    return;
  }

  const currentPost = snapshot.data;
  renderResults(currentPost);

  if (!unsubscribePostTopic) {
    unsubscribePostTopic = subscribeTopic(getPostTopic(currentPost), error => {
      if (error) handleError(error);
    });
  }
});

function stopObservingPost() {
  unsubscribePost();
  unsubscribePostTopic?.();
}
```


## Observe A Live Collection

Use the collection callback to render the latest list. Keep the next-page function and call it only when the UI requests more data.


```typescript TypeScript
import {
  PostRepository,
  SubscriptionLevels,
  getCommunityTopic,
  subscribeTopic,
} from "@amityco/ts-sdk";

let hasMorePosts = false;
let loadNextPostsPage: (() => void) | undefined;

const unsubscribePostsTopic = subscribeTopic(
  getCommunityTopic(community, SubscriptionLevels.POST),
  error => {
    if (error) handleError(error);
  }
);

const unsubscribePosts = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    limit: 20,
    sortBy: "lastCreated",
    includeDeleted: false,
  },
  collection => {
    if (collection.loading) {
      showLoading();
    }

    if (collection.error) {
      handleError(collection.error);
      return;
    }

    renderResults(collection.data);
    hasMorePosts = collection.hasNextPage ?? false;
    loadNextPostsPage = collection.onNextPage;
  }
);

function loadMorePosts() {
  if (hasMorePosts) {
    loadNextPostsPage?.();
  }
}

function stopObservingPosts() {
  unsubscribePosts();
  unsubscribePostsTopic();
}
```


## Notes

- `getPost()`, `getMessage()`, `getChannel()`, `getCommunity()`, `getUser()`, `getPoll()`, `getRoom()`, and similar singular methods follow the same live-object callback pattern.
- Query methods such as `getPosts()`, `getComments()`, `getMessages()`, `getMembers()`, `getReactions()`, `getRooms()`, and `getStreams()` follow the live-collection callback pattern.
- The callback can emit local/cache data before server data. Use `loading`, `error`, and `origin` if your UI needs to distinguish phases.
- Keep topic subscriptions as narrow as possible. A post-detail screen should subscribe to the post topic; a community feed screen should subscribe to the community post topic.
- Always dispose the observer returned by the repository and any topic unsubscribe functions returned by `subscribeTopic()`.

## Related Topics

    See post-specific live object and collection usage.
    Subscribe to social topics for cross-device updates.

---

### [Real-time Events](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview)

> Understand how SDK topic subscriptions deliver social and chat updates into live objects and collections.

Real-time events are MQTT topic subscriptions managed by the SDK. Subscribe to the smallest topic that matches the screen, and the SDK delivers matching changes into the live objects, live collections, and local caches you already observe.

Topic subscriptions do not replace Live Objects & Collections. Use subscriptions to tell the SDK which event streams matter now, then render from the live data APIs.

## Platform Surface

| Area | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Social topics | Topic helper functions such as `getCommunityTopic`, `getPostTopic`, and `subscribeTopic` | `AmityTopic` classes with `AmityTopicSubscription` | Model `.subscription(...)` extensions plus `AmityCoreClient.subscription(...)` for follow topics | Model `.subscription(...)` extensions |
| Chat topics | `getSubChannelTopic(subChannel)` with `subscribeTopic(topic)` | `AmitySubChannelTopic` with `AmityTopicSubscription` | `subChannel.subscription()` | `subChannel.subscription()` |
| Unsubscribe | Call the `Amity.Unsubscriber` returned by `subscribeTopic` | `unsubscribeTopic(...)` | `unsubscribeTopic()` | `unsubscribeTopic()` |

## Topic Lifecycle

```mermaid
flowchart LR
    A["Screen needs live updates"] --> B["Choose model topic"]
    B --> C["Subscribe while visible"]
    C --> D["Live object or collection receives updates"]
    D --> E["Unsubscribe when no longer needed"]
```

## When to Subscribe

| UI need | Recommended topic |
| --- | --- |
| Community profile or settings changes | Community topic with community-level events |
| Community feed creation, deletion, or updates | Community topic with post events, or post-and-comment events for a full feed |
| A single post detail screen | Post topic for the post, and comment events if comments are visible |
| A comment detail or moderation surface | Comment topic |
| A user profile screen | User topic with user-level events |
| A chat thread | Subchannel topic |
| Follow/follower list changes | Follow topic on platforms that expose follow topic helpers |
| Story updates | Story topic or community-story topic where available |

## Subscription Discipline

    Topic APIs usually require an SDK model object such as `AmityCommunity`, `AmityPost`, `AmityComment`, `AmityUser`, or `AmitySubChannel`. Fetch or observe the model first, then subscribe while that model is visible.

    A community feed usually needs one community post-and-comment topic, not a separate topic for every post row. Use post or comment topics for focused detail screens.

    Unsubscribe when the screen is dismissed, the component unmounts, or the observed model changes. Logout also tears down the SDK session, but UI-level cleanup keeps each screen's ownership clear.

    A topic subscription activates event delivery. Your UI should still read from the SDK live object or live collection so cache updates, loading state, and error handling stay consistent.

## Related Topics

    Subscribe to community, post, comment, user, follow, and story topics.

    Subscribe to subchannel topics for chat thread updates.

    Observe SDK-managed live data after subscribing to the event streams your UI needs.

---

### [Chat Real-time Events](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/realtime-events/chat-realtime-events)

> Subscribe to subchannel topics for live chat thread updates.

Chat real-time event subscriptions keep a thread's live data moving while the user is viewing it. For the current SDK surface, the public chat topic documented here is the subchannel topic.

Conversation and community channel members receive many chat updates through normal SDK live objects and collections. Use a subchannel topic when the screen needs explicit realtime delivery for a specific message thread.

## Platform Surface

| Platform | Public API | Cleanup |
| --- | --- | --- |
| TypeScript | `getSubChannelTopic(subChannel)`, then `subscribeTopic(topic)` | Call the returned `Amity.Unsubscriber` |
| iOS | `AmitySubChannelTopic(subChannel:)`, then `AmityTopicSubscription().subscribeTopic(...)` | `AmityTopicSubscription().unsubscribeTopic(...)` |
| Android | `subChannel.subscription().subscribeTopic()` | `subChannel.subscription().unsubscribeTopic()` |
| Flutter | `subChannel.subscription().subscribeTopic()` | `subChannel.subscription().unsubscribeTopic()` |

## Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `subChannel` | Yes | `Amity.SubChannel` model returned by the SDK. The helper reads its `path` and subscribes to that path with a wildcard. |
| iOS | `subChannel` | Yes | `AmitySubChannel` model used to construct `AmitySubChannelTopic`. |
| Android | `subChannel` | Yes | `AmitySubChannel` model exposing the public `subscription()` method. |
| Flutter | `subChannel` | Yes | `AmitySubChannel` model exposing the public `subscription()` method. |

## Subscribe To A Subchannel

Subscribe when the thread screen becomes active, and unsubscribe when it leaves the screen or switches to another subchannel.


```typescript TypeScript
import { getSubChannelTopic, subscribeTopic } from '@amityco/ts-sdk';

function subscribeToSubChannel(subChannel: Amity.SubChannel): Amity.Unsubscriber {
  const topic = getSubChannelTopic(subChannel);

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToSubChannel(_ subChannel: AmitySubChannel) async throws {
    let topic = AmitySubChannelTopic(subChannel: subChannel)

    try await AmityTopicSubscription().subscribeTopic(topic)
}

func unsubscribeFromSubChannel(_ subChannel: AmitySubChannel) async throws {
    let topic = AmitySubChannelTopic(subChannel: subChannel)

    try await AmityTopicSubscription().unsubscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.chat.subchannel.AmitySubChannel

fun subscribeToSubChannel(subChannel: AmitySubChannel) {
    subChannel.subscription()
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}

fun unsubscribeFromSubChannel(subChannel: AmitySubChannel) {
    subChannel.subscription()
        .unsubscribeTopic()
        .subscribe()
}
```

```dart Flutter
Future<void> subscribeToSubChannel(AmitySubChannel subChannel) async {
  await subChannel.subscription().subscribeTopic();
}

Future<void> unsubscribeFromSubChannel(AmitySubChannel subChannel) async {
  await subChannel.subscription().unsubscribeTopic();
}
```


## Best Practices

    Bind the subchannel subscription to the active message thread, not to the entire chat module. Switch the subscription when the user changes threads.

    The snippets expect a real `SubChannel` model returned by the SDK. Avoid constructing topic paths manually in app code.

    After subscribing, render messages from the SDK query or live collection APIs so local cache updates and pagination stay consistent.

## Related Topics

    Query and render messages for a subchannel.

    Understand how realtime events update observed SDK data.

---

### [Social Real-time Events](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events)

> Subscribe to community, post, comment, user, follow, and story topic events.

Social real-time events let an app receive live updates for the social models that are currently visible. Use topic subscriptions for the event stream, then render from the SDK live object or live collection for the model.

Community and user-scoped topics are useful for feed screens. Post and comment topics are better for focused detail screens. The user must have access to the target community, post, comment, user, or story for events to be delivered.

## Platform Surface

| Topic | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Community | `getCommunityTopic(...)` | `AmityCommunityTopic` | `community.subscription(...)` | `community.subscription(...)` |
| Post | `getPostTopic(...)`, `getLiveReactionTopic(...)` | `AmityPostTopic` | `post.subscription(...)` | `post.subscription(...)` |
| Comment | `getCommentTopic(...)` | `AmityCommentTopic` | `comment.subscription(...)` | `comment.subscription(...)` |
| User | `getUserTopic(...)` | `AmityUserTopic` | `user.subscription(...)` | `user.subscription(...)` |
| Follow | `getMyFollowersTopic()`, `getMyFollowingsTopic()` | `AmityFollowTopic` | `AmityCoreClient.subscription(AmityTopic.FOLLOW(...))` | Not exposed in this checkout |
| Story | `getStoryTopic(...)`, `getCommunityStoriesTopic(...)` | `AmityStoryTopic` | `story.subscription()` | `story.subscription()` |

## Community Topic

Use a community topic when a screen is scoped to a community, such as a community profile, feed, or moderation surface.

### Event Levels

| Intent | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Community object changes | `SubscriptionLevels.COMMUNITY` or omit the level | `.community` | `AmityCommunityEvents.COMMUNITY` | `AmityCommunityEvents.COMMUNITY` |
| Posts in the community | `SubscriptionLevels.POST` | `.posts` | `AmityCommunityEvents.POSTS` | `AmityCommunityEvents.POSTS` |
| Comments in the community | `SubscriptionLevels.COMMENT` | `.comments` | `AmityCommunityEvents.COMMENTS` | `AmityCommunityEvents.COMMENTS` |
| Posts and comments | `SubscriptionLevels.POST_AND_COMMENT` | `.postsAndComments` | `AmityCommunityEvents.POSTS_AND_COMMENTS` | `AmityCommunityEvents.POSTS_AND_COMMENTS` |
| Stories and story comments | Use `getCommunityStoriesTopic(...)` | `.storyAndComments` | `AmityCommunityEvents.STORIES_AND_COMMENTS` | `AmityCommunityEvents.STORIES_AND_COMMENTS` |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `community` | Yes | `Amity.Community` or any subscribable object with a valid `path`. |
| TypeScript | `level` | No | Defaults to `SubscriptionLevels.COMMUNITY`. Use `POST`, `COMMENT`, or `POST_AND_COMMENT` for content updates. |
| iOS | `community` | Yes | `AmityCommunity` model used to construct `AmityCommunityTopic`. |
| iOS | `andEvent` | Yes | One `AmityCommunityEvent` value. |
| Android | `events` | Yes | One `AmityCommunityEvents` value passed to `community.subscription(events)`. |
| Flutter | `events` | Yes | One `AmityCommunityEvents` value passed to `community.subscription(events)`. |


```typescript TypeScript
import { getCommunityTopic, subscribeTopic, SubscriptionLevels } from '@amityco/ts-sdk';

function subscribeToCommunityFeed(community: Amity.Community): Amity.Unsubscriber {
  const topic = getCommunityTopic(
    community,
    SubscriptionLevels.POST_AND_COMMENT,
  );

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToCommunityFeed(_ community: AmityCommunity) async throws {
    let topic = AmityCommunityTopic(
        community: community,
        andEvent: .postsAndComments
    )

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.events.AmityCommunityEvents
import com.amity.socialcloud.sdk.model.social.community.AmityCommunity

fun subscribeToCommunityFeed(community: AmityCommunity) {
    community.subscription(AmityCommunityEvents.POSTS_AND_COMMENTS)
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```

```dart Flutter
Future<void> subscribeToCommunityFeed(AmityCommunity community) async {
  await community
      .subscription(AmityCommunityEvents.POSTS_AND_COMMENTS)
      .subscribeTopic();
}
```


## Post Topic

Use a post topic for a single post detail screen or a moderation/action surface focused on one post.

### Event Levels

| Intent | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Post object changes | `getPostTopic(post)` or `SubscriptionLevels.POST` | `.post` | `AmityPostEvents.POST` | `AmityPostEvents.POST` |
| Comments on the post | `SubscriptionLevels.COMMENT` | `.comments` | `AmityPostEvents.COMMENTS` | `AmityPostEvents.COMMENTS` |
| Live reactions | `getLiveReactionTopic(post)` | `.liveReaction` | `AmityPostEvents.LIVE_REACTION` | Not exposed in this checkout |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `post` | Yes | `Amity.Post` or subscribable post object with a valid `path`. |
| TypeScript | `level` | No | Defaults to post object events. Use `SubscriptionLevels.COMMENT` for post comments. |
| iOS | `post` | Yes | `AmityPost` model used to construct `AmityPostTopic`. |
| iOS | `andEvent` | Yes | One `AmityPostEvent` value. |
| Android | `events` | Yes | One `AmityPostEvents` value passed to `post.subscription(events)`. |
| Flutter | `events` | Yes | One `AmityPostEvents` value passed to `post.subscription(events)`. |


```typescript TypeScript
import { getPostTopic, subscribeTopic, SubscriptionLevels } from '@amityco/ts-sdk';

function subscribeToPostComments(post: Amity.Post): Amity.Unsubscriber {
  const topic = getPostTopic(post, SubscriptionLevels.COMMENT);

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToPostComments(_ post: AmityPost) async throws {
    let topic = AmityPostTopic(post: post, andEvent: .comments)

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.events.AmityPostEvents
import com.amity.socialcloud.sdk.model.social.post.AmityPost

fun subscribeToPostComments(post: AmityPost) {
    post.subscription(AmityPostEvents.COMMENTS)
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```

```dart Flutter
Future<void> subscribeToPostComments(AmityPost post) async {
  await post
      .subscription(AmityPostEvents.COMMENTS)
      .subscribeTopic();
}
```


## Comment Topic

Use a comment topic for a focused comment detail, moderation, or realtime reply surface.

### Event Levels

| Intent | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Comment object changes | `getCommentTopic(comment)` | `.comment` | `AmityCommentEvents.COMMENT` | `AmityCommentEvents.COMMENT` |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `comment` | Yes | `Amity.Comment` or subscribable comment object with a valid `path`. |
| iOS | `comment` | Yes | `AmityComment` model used to construct `AmityCommentTopic`. |
| iOS | `andEvent` | Yes | `.comment`. |
| Android | `events` | Yes | `AmityCommentEvents.COMMENT`. |
| Flutter | `events` | Yes | `AmityCommentEvents.COMMENT`. |


```typescript TypeScript
import { getCommentTopic, subscribeTopic } from '@amityco/ts-sdk';

function subscribeToComment(comment: Amity.Comment): Amity.Unsubscriber {
  const topic = getCommentTopic(comment);

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToComment(_ comment: AmityComment) async throws {
    let topic = AmityCommentTopic(comment: comment, andEvent: .comment)

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.events.AmityCommentEvents
import com.amity.socialcloud.sdk.model.social.comment.AmityComment

fun subscribeToComment(comment: AmityComment) {
    comment.subscription(AmityCommentEvents.COMMENT)
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```

```dart Flutter
Future<void> subscribeToComment(AmityComment comment) async {
  await comment
      .subscription(AmityCommentEvents.COMMENT)
      .subscribeTopic();
}
```


## User Topic

Use a user topic when a screen needs live updates for a user profile or that user's feed activity.

### Event Levels

| Intent | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| User object changes | `SubscriptionLevels.USER` or omit the level | `.user` | `AmityUserEvents.USER` | `AmityUserEvents.USER` |
| User posts | `SubscriptionLevels.POST` | `.posts` | `AmityUserEvents.POSTS` | `AmityUserEvents.POSTS` |
| User comments | `SubscriptionLevels.COMMENT` | `.comments` | `AmityUserEvents.COMMENTS` | `AmityUserEvents.COMMENTS` |
| User posts and comments | `SubscriptionLevels.POST_AND_COMMENT` | `.postsAndComments` | `AmityUserEvents.POSTS_AND_COMMENTS` | `AmityUserEvents.POSTS_AND_COMMENTS` |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `user` | Yes | `Amity.User` or subscribable user object with a valid `path`. |
| TypeScript | `level` | No | Defaults to `SubscriptionLevels.USER`. Use content levels for user-feed activity. |
| iOS | `user` | Yes | `AmityUser` model used to construct `AmityUserTopic`. |
| iOS | `andEvent` | Yes | One `AmityUserEvent` value. |
| Android | `events` | Yes | One `AmityUserEvents` value passed to `user.subscription(events)`. |
| Flutter | `events` | Yes | One `AmityUserEvents` value passed to `user.subscription(events)`. |


```typescript TypeScript
import { getUserTopic, subscribeTopic, SubscriptionLevels } from '@amityco/ts-sdk';

function subscribeToUserPosts(user: Amity.User): Amity.Unsubscriber {
  const topic = getUserTopic(user, SubscriptionLevels.POST);

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToUserPosts(_ user: AmityUser) async throws {
    let topic = AmityUserTopic(user: user, andEvent: .posts)

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.events.AmityUserEvents
import com.amity.socialcloud.sdk.model.core.user.AmityUser

fun subscribeToUserPosts(user: AmityUser) {
    user.subscription(AmityUserEvents.POSTS)
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```

```dart Flutter
Future<void> subscribeToUserPosts(AmityUser user) async {
  await user
      .subscription(AmityUserEvents.POSTS)
      .subscribeTopic();
}
```


## Follow Topic

Follow topics observe changes to the current user's follower and following lists.

The current Flutter SDK checkout does not expose a public follow topic subscription helper. Use this section for TypeScript, iOS, and Android.

### Event Levels

| Intent | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Current user's followers | `getMyFollowersTopic()` | `.myFollowers` | `AmityFollowEvents.MY_FOLLOWERS` |
| Current user's following | `getMyFollowingsTopic()` | `.myFollowing` | `AmityFollowEvents.MY_FOLLOWINGS` |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | None | No | Helpers derive the current user from the active SDK user. |
| iOS | `event` | Yes | One `AmityFollowEvent` value. |
| Android | `events` | Yes | One `AmityFollowEvents` value used to construct `AmityTopic.FOLLOW(...)`. |


```typescript TypeScript
import { getMyFollowersTopic, subscribeTopic } from '@amityco/ts-sdk';

function subscribeToMyFollowers(): Amity.Unsubscriber {
  const topic = getMyFollowersTopic();

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToMyFollowers() async throws {
    let topic = AmityFollowTopic(event: .myFollowers)

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.core.AmityCoreClient
import com.amity.socialcloud.sdk.model.core.events.AmityFollowEvents
import com.amity.socialcloud.sdk.model.core.events.AmityTopic

fun subscribeToMyFollowers() {
    AmityCoreClient.subscription(AmityTopic.FOLLOW(AmityFollowEvents.MY_FOLLOWERS))
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```


## Story Topic

Story topics observe one story or a community's story stream.

### Event Levels

| Intent | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| One story | `getStoryTopic(story)` | `AmityStoryTopic(story:andEvent:)` with `.story` | `story.subscription()` | `story.subscription()` |
| Community story stream | `getCommunityStoriesTopic(...)` | Community topic `.storyAndComments` | Community topic `STORIES_AND_COMMENTS` | Community topic `STORIES_AND_COMMENTS` |

### Parameters

| Platform | Parameter | Required | Description |
| --- | --- | --- | --- |
| TypeScript | `story` | Yes | Object with `targetId`, `targetType`, and `storyId` for `getStoryTopic`. |
| TypeScript | `targetId`, `targetType` | Yes | Community or user story target passed to `getCommunityStoriesTopic`. |
| iOS | `story` | Yes | `AmityStory` model used to construct `AmityStoryTopic`. |
| iOS | `andEvent` | Yes | `.story`. |
| Android | `story` | Yes | `AmityStory` model exposing `subscription()`. |
| Flutter | `story` | Yes | `AmityStory` model exposing `subscription()`. |


```typescript TypeScript
import { getStoryTopic, subscribeTopic } from '@amityco/ts-sdk';

function subscribeToStory(
  story: Pick<Amity.Story, 'targetId' | 'targetType' | 'storyId'>,
): Amity.Unsubscriber {
  const topic = getStoryTopic(story);

  return subscribeTopic(topic);
}
```

```swift iOS
func subscribeToStory(_ story: AmityStory) async throws {
    let topic = AmityStoryTopic(story: story, andEvent: .story)

    try await AmityTopicSubscription().subscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.social.story.AmityStory
import com.amity.socialcloud.sdk.model.social.story.subscription

fun subscribeToStory(story: AmityStory) {
    story.subscription()
        .subscribeTopic()
        .subscribe({
            showSuccessMessage("Subscribed")
        }, { error ->
            showErrorMessage(error = error)
        })
}
```

```dart Flutter
Future<void> subscribeToStory(AmityStory story) async {
  await story.subscription().subscribeTopic();
}
```


## Cleanup

Use the platform-specific unsubscribe path when the UI no longer needs the topic.


```typescript TypeScript
import { getCommunityTopic, subscribeTopic, SubscriptionLevels } from '@amityco/ts-sdk';

function mountCommunityFeed(community: Amity.Community): Amity.Unsubscriber {
  const topic = getCommunityTopic(
    community,
    SubscriptionLevels.POST_AND_COMMENT,
  );

  return subscribeTopic(topic);
}

const unsubscribe = mountCommunityFeed(community);
unsubscribe();
```

```swift iOS
func unsubscribeFromCommunityFeed(_ community: AmityCommunity) async throws {
    let topic = AmityCommunityTopic(
        community: community,
        andEvent: .postsAndComments
    )

    try await AmityTopicSubscription().unsubscribeTopic(topic)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.events.AmityCommunityEvents
import com.amity.socialcloud.sdk.model.social.community.AmityCommunity

fun unsubscribeFromCommunityFeed(community: AmityCommunity) {
    community.subscription(AmityCommunityEvents.POSTS_AND_COMMENTS)
        .unsubscribeTopic()
        .subscribe()
}
```

```dart Flutter
Future<void> unsubscribeFromCommunityFeed(AmityCommunity community) async {
  await community
      .subscription(AmityCommunityEvents.POSTS_AND_COMMENTS)
      .unsubscribeTopic();
}
```


## Related Topics

    Learn how topic subscriptions fit with live objects and collections.

    Subscribe to subchannel topics for chat threads.

---

### [Presence State](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/presence-state/overview)

> Understand which social.plus SDKs support user, channel, and room presence, and choose the right presence API.

Presence state lets your app show who is currently active. The SDK has two different presence surfaces:

- **Network presence** tracks the current user's heartbeat and lets iOS and Android apps read or sync other users' online state.
- **Room presence** tracks who is currently watching a live room. It is available on iOS, Android, and TypeScript.

Presence APIs require the presence feature to be enabled for your network. If the feature is disabled, heartbeat calls can fail with an SDK error.

## Platform Surface

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Current user heartbeat | Not available | `client.presence` | `AmityCoreClient.presence()` | Not available |
| User presence | Not available | `AmityUserPresenceRepository` | `AmityCoreClient.newUserPresenceRepository()` | Not available |
| Channel presence | Not available | `AmityChannelPresenceRepository` | `AmityChatClient.newChannelPresenceRepository()` | Not available |
| Room presence | `RoomPresenceRepository` | `AmityRoomPresenceRepository` | `AmityCoreClient.newRoomPresenceRepository()` | Not available |

## Which Presence API to Use

    Read specific users' online state, sync visible users in a list, or fetch a snapshot of online users.

    Show whether any other member of a conversation channel is online.

    Count and list users currently watching a live room.

    Start and stop the heartbeat that marks the current user or room viewer as active.

## Behavior to Know

    iOS and Android expose `isOnline` as a computed value from the user's last heartbeat. The SDK considers a user online while the last heartbeat is recent.

    User and channel sync APIs are meant for visible lists. Start syncing when an item appears, then unsync when it disappears so you stay within the SDK sync limits.

    Room presence uses room-specific heartbeat and count APIs. Use it for live rooms and viewer lists, not for general "online user" badges.

    The Flutter SDK in this checkout does not expose user, channel, or room presence repositories. Do not copy iOS, Android, or TypeScript presence snippets into Flutter integrations.

## Related Topics

    Use live data objects for SDK resources that publish real-time updates.

    Learn how event subscriptions power live chat and social experiences.

---

### [User Presence](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence)

> Read and sync user online status with AmityUserPresenceRepository on iOS and Android.

User presence lets iOS and Android apps read whether specific users are currently online. Use it for online badges, visible member lists, or a lightweight "who is online" snapshot.

The current TypeScript and Flutter SDKs in this checkout do not expose a user presence repository. Use the iOS and Android snippets below only for those platforms.

## Platform Surface

| Platform | Repository | Main APIs |
| --- | --- | --- |
| iOS | `AmityUserPresenceRepository()` | `getUserPresence(userIds:)`, `syncUserPresence(id:viewId:)`, `getSyncingUserPresence()`, `getOnlineUsersCount()`, `getOnlineUsersSnapshot()` |
| Android | `AmityCoreClient.newUserPresenceRepository()` | `getUserPresence(userIds)`, `syncUserPresence(userId, viewId)`, `getSyncingUserPresence()`, `getOnlineUsersCount()`, `getOnlineUsersSnapshot()` |
| TypeScript | Not available | Not available |
| Flutter | Not available | Not available |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| `getUserPresence` | `userIds` | Yes | User IDs to read. iOS documents a maximum of 220 IDs per call. Keep Android calls bounded for the same reason. |
| `syncUserPresence` | `id` / `userId` | Yes | User ID whose presence should be refreshed periodically while visible. |
| `syncUserPresence` | `viewId` | No | Stable view identifier. Defaults to `amity-global`; use a custom value when the same user can appear in multiple visible UI locations. |
| `unsyncUserPresence` | `id` / `userId` | Yes | User ID to remove from syncing. |
| `unsyncUserPresence` | `viewId` | No | Must match the `viewId` used when syncing if you passed a custom value. |
| `unsyncAllUserPresence` | None | No | Stops syncing all user presence tracked by the SDK presence engine. |
| `getSyncingUserPresence` | None | No | Returns iOS `AnyPublisher<[AmityUserPresence], Error>` or Android `Flowable<List<AmityUserPresence>>`. |
| `getOnlineUsersCount` | None | No | Returns the current count of online users in the network. |
| `getOnlineUsersSnapshot` | None | No | Returns a point-in-time, paginated snapshot of online users. iOS and Android load users 20 at a time. |

## User Presence Object

| Field | iOS | Android | Description |
| --- | --- | --- | --- |
| User ID | `presence.userId` | `presence.getUserId()` | The user represented by this presence record. |
| Last heartbeat | `presence.lastHeartbeat` | `presence.getLastHeartbeat()` | Last heartbeat timestamp, when available. |
| Online state | `presence.isOnline` | `presence.isOnline()` | `true` when the last heartbeat is within the SDK online threshold. |

The SDK limits active presence syncing to 20 user IDs at a time. Unsync users when their row, card, or profile preview is no longer visible.

## Read User Presence

Fetch presence for known users as a one-shot read.


```swift iOS
let repository = AmityUserPresenceRepository()

let presences = try await repository.getUserPresence(userIds: [userId])
for presence in presences {
    let isOnline = presence.isOnline
    let lastHeartbeat = presence.lastHeartbeat
    showSuccessMessage("\(presence.userId): \(isOnline)")
}
```

```kotlin Android
val repository = AmityCoreClient.newUserPresenceRepository()

repository.getUserPresence(listOf(userId))
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ presences ->
        presences.forEach { presence ->
            val isOnline = presence.isOnline()
            val lastHeartbeat = presence.getLastHeartbeat()
            showSuccessMessage("${presence.getUserId()}: $isOnline")
        }
    }, { error ->
        showErrorMessage(error = error)
    })
```


## Sync User Presence

Sync user presence while users are visible, then unsync them when the UI no longer needs updates.


```swift iOS
let repository = AmityUserPresenceRepository()

let cancellable = repository.getSyncingUserPresence()
    .sink(receiveCompletion: { completion in
        if case let .failure(error) = completion {
            handleError(error)
        }
    }, receiveValue: { presences in
        for presence in presences {
            showSuccessMessage("\(presence.userId): \(presence.isOnline)")
        }
    })

repository.syncUserPresence(id: userId)

// Call when the row or screen is no longer visible.
repository.unsyncUserPresence(id: userId)

_ = cancellable
```

```kotlin Android
val repository = AmityCoreClient.newUserPresenceRepository()

repository.getSyncingUserPresence()
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ presences ->
        presences.forEach { presence ->
            showSuccessMessage("${presence.getUserId()}: ${presence.isOnline()}")
        }
    }, { error ->
        showErrorMessage(error = error)
    })

repository.syncUserPresence(userId)

// Call when the row or screen is no longer visible.
repository.unsyncUserPresence(userId)
```


## Read Online Users Count And Snapshot

Use the count for a network-wide online total. Use the snapshot when you need actual user objects at the time of the query.


```swift iOS
let repository = AmityUserPresenceRepository()

let count = try await repository.getOnlineUsersCount()
showSuccessMessage(count)

let snapshot = try await repository.getOnlineUsersSnapshot()
let users = snapshot.users

if snapshot.canLoadMore {
    await snapshot.loadMore()
}
```

```kotlin Android
val repository = AmityCoreClient.newUserPresenceRepository()

repository.getOnlineUsersCount()
    .subscribe({ count ->
        showSuccessMessage(count)
    }, { error ->
        showErrorMessage(error = error)
    })

repository.getOnlineUsersSnapshot()
    .subscribe({ snapshot ->
        val users = snapshot.getUsers()
        if (snapshot.canLoadMore()) {
            snapshot.loadMore().subscribe()
        }
    }, { error ->
        showErrorMessage(error = error)
    })
```


## Best Practices

    Other users can only see the current user as online if the app enables presence and starts the current user's heartbeat. See <a href="/social-plus-sdk/core-concepts/realtime-communication/presence-state/heartbeat-sync">Heartbeat Sync</a>.

    Bind `syncUserPresence` to visible UI rows, cells, or cards. Call `unsyncUserPresence` during cell reuse, unmount, or screen dismissal.

    `getOnlineUsersSnapshot` is a point-in-time read. For live online badges, sync specific visible users instead.

## Related Topics

    Show whether any other member of a conversation channel is online.

    Mark the current user as online with the SDK heartbeat.

---

### [Channel Presence](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/presence-state/channel-presence)

> Sync conversation channel member presence with AmityChannelPresenceRepository on iOS and Android.

Channel presence tells your app whether any other member of a conversation channel is online. Use it for chat lists, member lists, and compact "active now" indicators.

Channel presence is available on iOS and Android only. The current TypeScript and Flutter SDKs in this checkout do not expose channel presence APIs.

## Platform Surface

| Platform | Repository | Main APIs |
| --- | --- | --- |
| iOS | `AmityChannelPresenceRepository()` | `syncChannelPresence(id:viewId:)`, `unsyncChannelPresence(id:viewId:)`, `unsyncAllChannelPresence()`, `getSyncingChannelPresence()` |
| Android | `AmityChatClient.newChannelPresenceRepository()` | `syncChannelPresence(channelId, viewId)`, `unsyncChannelPresence(channelId, viewId)`, `unsyncAllChannelPresence()`, `getSyncingChannelPresence()` |
| TypeScript | Not available | Not available |
| Flutter | Not available | Not available |

Only conversation channels support channel presence. The SDK sync limit is 20 channel IDs at a time.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| `syncChannelPresence` | `id` / `channelId` | Yes | Conversation channel ID whose members' presence should be refreshed periodically. |
| `syncChannelPresence` | `viewId` | No | Stable view identifier. Defaults to `amity-global`; use a custom value when the same channel can appear in multiple visible UI locations. |
| `unsyncChannelPresence` | `id` / `channelId` | Yes | Channel ID to remove from syncing. |
| `unsyncChannelPresence` | `viewId` | No | Must match the `viewId` used when syncing if you passed a custom value. |
| `unsyncAllChannelPresence` | None | No | Stops syncing all channel presence tracked by the SDK presence engine. |
| `getSyncingChannelPresence` | None | No | Returns iOS `AnyPublisher<[AmityChannelPresence], Error>` or Android `Flowable<List<AmityChannelPresence>>`. |

## Channel Presence Object

| Field | iOS | Android | Description |
| --- | --- | --- | --- |
| Channel ID | `presence.channelId` | `presence.getChannelId()` | The conversation channel represented by the presence record. |
| User presences | `presence.userPresences` | `presence.getUserPresences()` | Presence records for members in the channel. |
| Any other member online | `presence.isAnyMemberOnline` | `presence.isAnyMemberOnline()` | `true` when at least one member other than the current user is online. |

## Sync Channel Presence

Start syncing when a conversation channel becomes visible, then unsync it when the row or screen is gone.


```swift iOS
let repository = AmityChannelPresenceRepository()

let cancellable = repository.getSyncingChannelPresence()
    .sink(receiveCompletion: { completion in
        if case let .failure(error) = completion {
            handleError(error)
        }
    }, receiveValue: { presences in
        for presence in presences {
            let isAnyMemberOnline = presence.isAnyMemberOnline
            showSuccessMessage("\(presence.channelId): \(isAnyMemberOnline)")
        }
    })

repository.syncChannelPresence(id: channelId)

// Call when the row or screen is no longer visible.
repository.unsyncChannelPresence(id: channelId)

_ = cancellable
```

```kotlin Android
val repository = AmityChatClient.newChannelPresenceRepository()

repository.getSyncingChannelPresence()
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ presences ->
        presences.forEach { presence ->
            val isAnyMemberOnline = presence.isAnyMemberOnline()
            showSuccessMessage("${presence.getChannelId()}: $isAnyMemberOnline")
        }
    }, { error ->
        showErrorMessage(error = error)
    })

repository.syncChannelPresence(channelId)

// Call when the row or screen is no longer visible.
repository.unsyncChannelPresence(channelId)
```


## Unsync All Channel Presence

Use `unsyncAllChannelPresence` when leaving a channel list, tearing down a view model, or replacing the whole visible channel set.


```swift iOS
let repository = AmityChannelPresenceRepository()

repository.syncChannelPresence(id: channelId)

// Later, when the channel list is dismissed.
repository.unsyncAllChannelPresence()
```

```kotlin Android
val repository = AmityChatClient.newChannelPresenceRepository()

repository.syncChannelPresence(channelId)

// Later, when the channel list is dismissed.
repository.unsyncAllChannelPresence()
```


## Best Practices

    Sync a channel when its conversation row appears. Unsync during row reuse, unmount, or screen dismissal so the app stays under the 20-channel sync limit.

    `isAnyMemberOnline` is designed for compact channel-list indicators. If you need per-user badges, sync those users directly with <a href="/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence">User Presence</a>.

    Other members can only see the current user as online if the app enables presence and starts the current user's heartbeat.

## Related Topics

    Sync specific users when you need per-user online badges.

    Mark the current user as online with the SDK heartbeat.

---

### [Heartbeat Sync](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/presence-state/heartbeat-sync)

> Start and stop SDK presence heartbeats for the current user or a live room viewer.

A heartbeat tells social.plus that the current user is still active. There are two heartbeat surfaces:

- **Current user heartbeat** marks the logged-in user online for user and channel presence. It is available on iOS and Android.
- **Room heartbeat** marks the current user as present in a live room. It is available on iOS, Android, and TypeScript.

Heartbeat intervals are controlled by server-side presence settings. The SDK sends the first heartbeat immediately, then continues on the configured cadence.

## Platform Surface

| Heartbeat | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Current user heartbeat | Not available | `client.presence.startHeartbeat()` | `AmityCoreClient.presence().startHeartbeat()` | Not available |
| Room heartbeat | `RoomPresenceRepository.startHeartbeat(roomId)` | `AmityRoomPresenceRepository(roomId:)` | `AmityCoreClient.newRoomPresenceRepository().roomId(roomId)` | Not available |

## Parameters

| Operation | Platform | Parameter | Required | Description |
| --- | --- | --- | --- | --- |
| `presence.enable` / `presence().enable` | iOS, Android | None | No | Enables user presence for the current user. |
| `presence.isEnabled` / `presence().isEnabled` | iOS, Android | None | No | Checks whether user presence is enabled for the current user. |
| `presence.startHeartbeat` / `presence().startHeartbeat` | iOS, Android | None | No | Starts the current user's network presence heartbeat. |
| `presence.stopHeartbeat` / `presence().stopHeartbeat` | iOS, Android | None | No | Stops the current user's network presence heartbeat. |
| `RoomPresenceRepository.startHeartbeat` | TypeScript | `roomId` | Yes | Room ID where the current user should be counted as present. |
| `AmityRoomPresenceRepository(roomId:)` | iOS | `roomId` | Yes | Room ID used to create the room presence repository. |
| `newRoomPresenceRepository().roomId(roomId)` | Android | `roomId` | Yes | Room ID used to create the room presence repository. |

## Start the Current User Heartbeat

Use this when your app wants the current user to appear online in user and channel presence.


```swift iOS
let isEnabled = try await client.presence.isEnabled()
if !isEnabled {
    try await client.presence.enable()
}

try await client.presence.startHeartbeat()

// Call when the user should no longer appear online.
client.presence.stopHeartbeat()
```

```kotlin Android
AmityCoreClient.presence().isEnabled()
    .flatMapCompletable { isEnabled ->
        val enableIfNeeded = if (isEnabled) {
            Completable.complete()
        } else {
            AmityCoreClient.presence().enable()
        }

        enableIfNeeded.andThen(AmityCoreClient.presence().startHeartbeat())
    }
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({
        showSuccessMessage("Presence heartbeat started")
    }, { error ->
        showErrorMessage(error = error)
    })

// Call when the user should no longer appear online.
AmityCoreClient.presence().stopHeartbeat()
```


## Start a Room Heartbeat

Use room heartbeat only while the current user is watching or participating in a live room.


```swift iOS
let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

try await roomPresence.startHeartbeat()

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()
```

```kotlin Android
val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.startHeartbeat()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({
        showSuccessMessage("Room heartbeat started")
    }, { error ->
        showErrorMessage(error = error)
    })

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()
```

```typescript TypeScript
import { RoomPresenceRepository } from '@amityco/ts-sdk';

RoomPresenceRepository.startHeartbeat(roomId);

// Call when the viewer leaves the room.
RoomPresenceRepository.stopHeartbeat(roomId);
```


## Lifecycle Guidance

    Start the current user heartbeat after login when the app wants the user to appear online. Start room heartbeat only while the room screen is visible and the user should count as a viewer.

    Stop heartbeat when the user logs out, leaves the room, dismisses the screen, or your view model is deallocated. For mobile apps, also stop or pause room heartbeat when the room screen backgrounds.

    If presence is disabled for the network, heartbeat start calls can fail. Treat that as a configuration error and hide online-state UI instead of retrying forever.

## Related Topics

    Read and sync user online state after the current user heartbeat is active.

    Read live room viewer counts and online room users.

---

### [Room Presence](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/presence-state/room-presence)

> Track live room viewer heartbeat, viewer count, and online room users with room presence APIs.

Room presence tracks who is currently watching a live room. Use it for viewer counts, "who is watching" panels, and host tools that need to know which users are present in a room right now.

Room presence is available on iOS, Android, and TypeScript. It is not available in the current Flutter SDK checkout.

## Platform Surface

| Platform | Repository | Main APIs |
| --- | --- | --- |
| TypeScript | `RoomPresenceRepository` | `startHeartbeat(roomId)`, `stopHeartbeat(roomId)`, `getRoomUserCount(roomId)`, `getRoomOnlineUsers(roomId)` |
| iOS | `AmityRoomPresenceRepository(roomId:)` | `startHeartbeat()`, `stopHeartbeat()`, `getRoomUserCount()`, `getRoomOnlineUsers()` |
| Android | `AmityCoreClient.newRoomPresenceRepository().roomId(roomId)` | `startHeartbeat()`, `stopHeartbeat()`, `getOnlineUsersCount()`, `observeOnlineUsersCount(interval:)`, `getOnlineUsersSnapshot()` |
| Flutter | Not available | Not available |

## Parameters

| Operation | Platform | Parameter | Required | Description |
| --- | --- | --- | --- | --- |
| Repository creation | iOS, Android | `roomId` | Yes | Room ID whose presence should be tracked. |
| `startHeartbeat` | TypeScript | `roomId` | Yes | Room ID where the current user should be counted as present. |
| `startHeartbeat` | iOS, Android | None | No | Uses the `roomId` already bound to the repository. |
| `stopHeartbeat` | TypeScript | `roomId` | Yes | Room ID whose heartbeat should stop. |
| `stopHeartbeat` | iOS, Android | None | No | Stops the active room heartbeat managed by the repository or presence service. |
| `getRoomUserCount` / `getOnlineUsersCount` | All supported platforms | None or `roomId` | Platform-dependent | Reads the current online viewer count for the room. |
| `observeOnlineUsersCount` | Android | `interval` | No | Poll interval in seconds. Defaults to 15 seconds. |
| `getRoomOnlineUsers` / `getOnlineUsersSnapshot` | All supported platforms | None or `roomId` | Platform-dependent | Reads a point-in-time list or snapshot of online room users. Android snapshots paginate 20 users at a time. |

## Start Room Heartbeat

Start the room heartbeat when the user enters the room, and stop it when they leave. The SDK sends the first heartbeat immediately and continues at the server-configured interval.


```swift iOS
let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

try await roomPresence.startHeartbeat()

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()
```

```kotlin Android
val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.startHeartbeat()
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({
        showSuccessMessage("Room heartbeat started")
    }, { error ->
        showErrorMessage(error = error)
    })

// Call when the viewer leaves the room.
roomPresence.stopHeartbeat()
```

```typescript TypeScript
import { RoomPresenceRepository } from '@amityco/ts-sdk';

RoomPresenceRepository.startHeartbeat(roomId);

// Call when the viewer leaves the room.
RoomPresenceRepository.stopHeartbeat(roomId);
```


## Read Room User Count

Use the count as the source of truth for how many users are currently present in the room.


```swift iOS
let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let count = try await roomPresence.getRoomUserCount()
showSuccessMessage(count)
```

```kotlin Android
val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.getOnlineUsersCount()
    .subscribe({ count ->
        showSuccessMessage(count)
    }, { error ->
        showErrorMessage(error = error)
    })
```

```typescript TypeScript
import { RoomPresenceRepository } from '@amityco/ts-sdk';

const { count } = await RoomPresenceRepository.getRoomUserCount(roomId);
updateUI(count);
```


## Keep the Count Live

The count is a point-in-time read. Android provides a built-in polling stream. On iOS and TypeScript, use your own timer and choose an interval that fits the UI.


```swift iOS
let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let timer = Timer.scheduledTimer(withTimeInterval: 30, repeats: true) { _ in
    Task { @MainActor in
        if let count = try? await roomPresence.getRoomUserCount() {
            showSuccessMessage(count)
        }
    }
}

timer.invalidate()
```

```kotlin Android
val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.observeOnlineUsersCount(interval = 30)
    .subscribe({ count ->
        showSuccessMessage(count)
    }, { error ->
        showErrorMessage(error = error)
    })
```

```typescript TypeScript
import { RoomPresenceRepository } from '@amityco/ts-sdk';

const timer = setInterval(async () => {
  const { count } = await RoomPresenceRepository.getRoomUserCount(roomId);
  updateUI(count);
}, 30_000);

clearInterval(timer);
```


## Read Room Online Users

Use the online-user list when the app needs actual user objects, such as avatars in a "who is watching" panel. For large rooms, display the count as the total and treat the list as a snapshot.


```swift iOS
let roomPresence = AmityRoomPresenceRepository(roomId: roomId)

let users = try await roomPresence.getRoomOnlineUsers()
displayUserList(users)
```

```kotlin Android
val roomPresence = AmityCoreClient.newRoomPresenceRepository().roomId(roomId)

roomPresence.getOnlineUsersSnapshot()
    .subscribe({ snapshot ->
        val users = snapshot.getUsers()
        if (snapshot.canLoadMore()) {
            snapshot.loadMore().subscribe()
        }
    }, { error ->
        showErrorMessage(error = error)
    })
```

```typescript TypeScript
import { RoomPresenceRepository } from '@amityco/ts-sdk';

const { data: users } = await RoomPresenceRepository.getRoomOnlineUsers(roomId);
renderResults(users);
```


## Best Practices

    Start room heartbeat when the viewer enters the live room screen. Stop it when the viewer leaves, switches rooms, backgrounds the screen, or the view model is torn down.

    The count is the total active viewer number. The online-user list is best for UI that needs actual user objects, such as avatars or invite-to-cohost flows.

    Android defaults `observeOnlineUsersCount` to 15 seconds. On iOS and TypeScript, avoid very aggressive polling unless the count is central to the experience.

## Related Topics

    Learn when to start and stop current user and room heartbeats.

    Create social posts that reference live rooms.

---

### [Logging & Errors](https://learn.social.plus/social-plus-sdk/core-concepts/foundation/logging)

> Monitor SDK network activity during integration and handle SDK error codes safely.

Use SDK logging and error surfaces while you build and debug an integration. Keep request and response logging out of production logs unless your app has an explicit redaction and retention policy.

## SDK Surface

| Need | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Network activity observer | `Client.onNetworkActivities(callback)` | `client.observeNetworkActivities(_:)` | `AmityCoreClient.observeNetworkActivities()` | Not exposed as a public SDK observer |
| Error parsing | `error.code` from SDK errors and connection events | `AmityErrorCode(rawValue:)` | `AmityError.from(...)` | `AmityException.toAmityError()` |
| Global ban signal | `Amity.ServerError.GLOBAL_BAN` | `.globalBan` | `AmityError.USER_IS_GLOBAL_BANNED` | `AmityError.USER_IS_GLOBAL_BANNED` |

Use the network observer as a development diagnostic tool. It can expose request metadata, response metadata, and payloads depending on platform, so avoid storing raw logs that may contain user content or credentials.

## Parameters

| Platform | Callback or stream value | Notes |
| --- | --- | --- |
| TypeScript | `request`, `response` | `response` includes `data`, `status`, `statusText`, and `headers`. The API returns an unsubscriber. |
| iOS | `URLRequest?`, `HTTPURLResponse?`, `Data?` | Pass `nil` to `observeNetworkActivities` when logging should stop. |
| Android | `Flowable<AmityNetworkActivity>` | Subscribe while debugging and dispose the subscription when finished. Avoid depending on internal activity subtypes in app code. |
| Flutter | Not available | Use normal request-level error handling and your app's HTTP tooling for Flutter-specific network diagnostics. |

## Network Activity

Observe network activity only while debugging an integration, then unsubscribe or dispose the observer when the debug session ends.

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const unsubscribe = Client.onNetworkActivities((request, response) => {
  console.log(request.method, request.url);
  console.log(response.status, response.statusText);
  console.log(response.data);
});

// Stop observing when the debug session ends.
unsubscribe();
```

```swift iOS
client.observeNetworkActivities { request, response, data in
    if let request {
        print("\(request.httpMethod ?? "GET") \(request.url?.absoluteString ?? "")")
    }

    if let response {
        print("status: \(response.statusCode)")
    }

    if let data {
        print("response bytes: \(data.count)")
    }
}

// Stop observing when the debug session ends.
client.observeNetworkActivities(nil)
```

```kotlin Android
val disposable = AmityCoreClient.observeNetworkActivities()
    .doOnNext { activity ->
        print(activity)
    }
    .doOnError { exception ->
        val amityError = AmityError.from(exception)
        print(amityError)
    }
    .subscribe()

// Stop observing when the debug session ends.
disposable.dispose()
```

## Error Handling

SDK operations throw or emit platform-native errors. Convert those errors to SDK error enums before deciding whether to retry, show a user message, or end the session.

```typescript TypeScript
import { Client, MessageRepository, MessageContentType } from '@amityco/ts-sdk';

// Session-level: a global ban ends the session.
const unsubscribe = Client.onConnectionError(error => {
  if (error.code === Amity.ServerError.GLOBAL_BAN) {
    console.log('The current user is globally banned.');
  }
});

unsubscribe();

// Action-level: global mute and unsafe content reject only the failed call.
async function sendTextMessage(subChannelId: string, text: string) {
  try {
    await MessageRepository.createMessage({
      subChannelId,
      dataType: MessageContentType.TEXT,
      data: { text },
    });
  } catch (error) {
    const { code } = error as { code?: number };

    if (code === Amity.ServerError.GLOBAL_MUTE) {
      console.log('The current user is globally muted and cannot post right now.');
    } else if (code === Amity.ServerError.UNSAFE_CONTENT) {
      console.log('The content was rejected by moderation. Edit it before sending again.');
    } else {
      throw error;
    }
  }
}
```

```swift iOS
func handleSdkError(_ error: Error) {
    let sdkError = error as NSError

    guard let amityError = AmityErrorCode(rawValue: sdkError.code) else {
        showErrorMessage("Unknown SDK error", error: error)
        return
    }

    if amityError == .globalBan {
        showErrorMessage("The current user is globally banned", error: error)
    }
}
```

```kotlin Android
fun handleSdkError(exception: Throwable) {
    val amityError = AmityError.from(exception)

    if (amityError == AmityError.USER_IS_GLOBAL_BANNED) {
        print("The current user is globally banned.")
    }
}

// Action-level: global mute and unsafe content reject only the failed call.
fun sendTextMessage(subChannelId: String, text: String): Disposable {
    return AmityChatClient.newMessageRepository()
        .createTextMessage(subChannelId, text)
        .build()
        .send()
        .subscribe({}, { exception ->
            when (AmityError.from(exception)) {
                AmityError.USER_IS_GLOBAL_MUTED ->
                    print("The current user is globally muted and cannot post right now.")
                AmityError.UNSAFE_CONTENT ->
                    print("The content was rejected by moderation. Edit it before sending again.")
                else -> print(exception)
            }
        })
}
```

```dart Flutter
final Object error = AmityException(
  message: 'The current user is globally banned.',
  code: 400312,
);

if (error is AmityException) {
  final amityError = error.toAmityError();

  if (amityError == AmityError.USER_IS_GLOBAL_BANNED) {
    showError(error);
  }
}
```

## Common SDK Error Constants

| Meaning | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Globally banned user | `Amity.ServerError.GLOBAL_BAN` | `.globalBan` | `AmityError.USER_IS_GLOBAL_BANNED` | `AmityError.USER_IS_GLOBAL_BANNED` |
| Globally muted user (`400313`) | `Amity.ServerError.GLOBAL_MUTE` | `.globalMute` | `AmityError.USER_IS_GLOBAL_MUTED` | Not exposed as a public Flutter SDK enum in the current source |
| Unsafe content rejected (`400314`) | `Amity.ServerError.UNSAFE_CONTENT` | `.unsafeContent` | `AmityError.UNSAFE_CONTENT` | Not exposed as a public Flutter SDK enum in the current source |
| Unauthorized session | `Amity.ServerError.UNAUTHORIZED` | `.unauthorized` | `AmityError.UNAUTHORIZED_ERROR` | `AmityError.UNAUTHORIZED_ERROR` |
| Item not found | `Amity.ServerError.ITEM_NOT_FOUND` | `.itemNotFound` | `AmityError.ITEM_NOT_FOUND` | `AmityError.ITEM_NOT_FOUND` |
| Permission denied | `Amity.ServerError.PERMISSION_DENIED` | `.permissionDenied` | `AmityError.PERMISSION_DENIED` | `AmityError.PERMISSION_DENIED` |
| Visitor usage limit exceeded | `Amity.ServerError.VISITOR_USAGE_LIMIT_EXCEEDED` | `.visitorUsageLimitExceeded` | `AmityError.VISITOR_USAGE_LIMIT_EXCEEDED` | Not exposed as a public Flutter SDK enum in the current source |
| Visitor permission denied | `Amity.ServerError.VISITOR_PERMISSION_DENIED` | `.visitorPermissionDenied` | `AmityError.VISITOR_PERMISSION_DENIED` | Not exposed as a public Flutter SDK enum in the current source |
| Bot permission denied | `Amity.ServerError.BOT_PERMISSION_DENIED` | `.botPermissionDenied` | `AmityError.BOT_PERMISSION_DENIED` | Not exposed as a public Flutter SDK enum in the current source |
| Max blocked users reached | `Amity.ServerError.MAX_BLOCKED_USERS_REACHED` (`400324`) | `.maxBlockedUsersReached` | `AmityError.MAX_BLOCKED_USERS_REACHED` | Refer to platform SDK |
| Connection error | `Amity.ClientError.CONNECTION_ERROR` | `.connectionError` | `AmityError.CONNECTION_ERROR` | `AmityError.CONNECTION_ERROR` |

A global mute (`400313`) is not a global ban (`400312`). The user stays signed in and the session continues; only the blocked action fails. Unsafe content (`400314`) means the request was rejected by content moderation, so sending the same content again fails the same way. Neither code ends the session, so handle both as a per-action error: tell the user why the action failed instead of signing them out.

## Production Checklist

- Disable broad network payload logging outside development builds.
- Redact tokens, authorization headers, user identifiers, and message or post bodies before writing logs.
- Keep retry logic bounded and avoid retrying authorization, global-ban, global-mute, or unsafe-content errors.
- Show user-friendly messages in the app UI; keep SDK codes in developer logs and support diagnostics.
- Unsubscribe or dispose observers when the screen, debug session, or application lifecycle no longer needs them.

---

### [PII Detection](https://learn.social.plus/social-plus-sdk/core-concepts/safety-privacy/pii-detection)

> Read and redact personally identifiable information metadata on supported SDK text objects.

PII detection metadata is attached to text content when your network has PII detection enabled server-side. The native SDK helpers let apps read detected entities and produce redacted display text without changing the original post, comment, or message.

This page covers the client SDK surface only. Feature enablement, quota, billing, and moderation-console behavior are product or backend concerns and are intentionally not documented here.

## SDK Surface

| Platform | PII metadata helper | Redaction helper | Current SDK note |
| --- | --- | --- | --- |
| iOS | `getPIIData()` on `AmityPost`, `AmityComment`, and `AmityMessage` | `redactedText(piiCategories:replaceChar:)` on the same objects | Public helper API is available. |
| Android | `getPIIData()` on `AmityPost`, `AmityComment`, and `AmityMessage` | `redactedText(piiCategories, replaceChar)` on `Data.TEXT` | Public helper API is available for text data. |
| TypeScript | Not exposed in the current public SDK source | Not exposed | Use backend-provided data only if your integration has a separate API contract for it. |
| Flutter | Not exposed in the current public SDK source | Not exposed | Use native SDK helpers through platform code only if your app owns that bridge. |

## Data Model

Each detected entity is represented as a PII item.

| Field | iOS type | Android type | Meaning |
| --- | --- | --- | --- |
| `offset` | `Int` | `Int` | Start index of the detected entity in the text. |
| `length` | `Int` | `Int` | Number of characters in the detected entity. |
| `category` | `AmityPIICategory` | `AmityPII.Category` | Normalized category when the SDK has one, or an `others` value for unknown categories. |
| `confidence` | `Double` | `Double` | Detection confidence score from the server-provided metadata. |

## Categories

The current native SDK helpers define dedicated categories for these values.

| Category | iOS | Android |
| --- | --- | --- |
| Email | `.email` | `AmityPII.Category.EMAIL` |
| Phone number | `.phoneNumber` | `AmityPII.Category.PHONE_NUMBER` |
| IP address | `.ipAddress` | `AmityPII.Category.IP_ADDRESS` |
| Address | `.address` | `AmityPII.Category.ADDRESS` |
| Passport number | `.passportNumber` | `AmityPII.Category.PASSPORT_NUMBER` |
| Unknown or newer category | `.others(value)` | `AmityPII.Category.OTHERS(value)` |

Handle unknown categories deliberately. The server can introduce category strings before every client UI has a named enum case.

## Parameters

| Parameter | iOS type | Android type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `piiCategories` | `[AmityPIICategory]` | `List<AmityPII.Category>` | Empty list | Empty means redact every detected category. Provide categories to redact only selected types. |
| `replaceChar` | `Character` | `Char` | `*` | Character used to replace each redacted character. |

## Read and Redact

Use `getPIIData()` when you need entity metadata for moderation UI, highlighting, or audit views. Use `redactedText(...)` when the app should display masked text.

```swift iOS
var cancellables = Set<AnyCancellable>()

let livePost = postRepository.getPost(withId: postId)
livePost.$snapshot
    .sink { post in
        guard let post else { return }

        let piiItems = post.getPIIData()
        let redactedText = post.redactedText(
            piiCategories: [.email, .phoneNumber],
            replaceChar: "#"
        )

        piiItems.forEach { pii in
            print("\(pii.category.value): \(pii.offset)-\(pii.length)")
        }

        showSuccessMessage(redactedText)
    }
    .store(in: &cancellables)

let liveComment = commentRepository.getComment(withId: commentId)
liveComment.$snapshot
    .sink { comment in
        guard let comment else { return }
        showSuccessMessage(comment.redactedText())
    }
    .store(in: &cancellables)

let liveMessage = messageRepository.getMessage(messageId)
liveMessage.$snapshot
    .sink { message in
        guard let message else { return }
        showSuccessMessage(message.redactedText())
    }
    .store(in: &cancellables)
```

```kotlin Android
import AmityPII

val piiItems = post?.getPIIData().orEmpty()
val redactedText = (post?.getData() as? AmityPost.Data.TEXT)
    ?.redactedText(
        piiCategories = listOf(
            AmityPII.Category.EMAIL,
            AmityPII.Category.PHONE_NUMBER
        ),
        replaceChar = '#'
    )
    .orEmpty()

piiItems.forEach { pii ->
    print("${pii.category}: ${pii.offset}-${pii.length}")
}

val redactedComment = (comment?.getData() as? AmityComment.Data.TEXT)
    ?.redactedText()
    .orEmpty()

val redactedMessage = (message?.getData() as? AmityMessage.Data.TEXT)
    ?.redactedText()
    .orEmpty()

print(redactedText + redactedComment + redactedMessage)
```

## Behavior Notes

- Redaction is non-destructive: it returns a string for display and does not change the stored text.
- The native helpers skip PII ranges that overlap with mention ranges so user and channel mentions are not accidentally masked.
- Metadata can be empty even when content is text. Treat an empty list as "no PII metadata on this object", not as a detection failure.
- Android redaction is available on `Data.TEXT`; non-text post, comment, or message data returns no redacted text through this helper.
- TypeScript and Flutter do not expose public PII helper methods in the current SDK source, so do not document `getPIIData()` or `redactedText()` for those SDKs.

## Core Concepts — Push Notifications

### [Device Registration](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device)

> Register and unregister a device for push notifications with the current SDK APIs.

Device registration connects the current signed-in user to the device token that the operating system gives your app. Use it after your app has completed the platform push-notification setup and after the SDK client is initialized for a signed-in user.

The TypeScript SDK does not expose a client-side device registration API. Use the native iOS, Android, or Flutter SDK APIs on device, and use server-side/webhook flows for web delivery.

## Platform Surface

| Platform | Register | Unregister | Token argument |
| --- | --- | --- | --- |
| iOS | `client.registerPushNotification(withDeviceToken:)` | `client.unregisterPushNotification()` | `token: String` |
| Android | `AmityCoreClient.registerPushNotification()` | `AmityCoreClient.unregisterPushNotification()` | None |
| Flutter | `AmityCoreClient.registerDeviceNotification(fcmToken)` | `AmityCoreClient.unregisterDeviceNotification()` | `fcmToken: String` |
| TypeScript | Not available | Not available | Not available |

## Parameters

| Name | Platform | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | iOS | `String` | Yes | APNs device token passed to `registerPushNotification(withDeviceToken:)`. |
| `fcmToken` | Flutter | `String` | Yes | FCM token passed to `registerDeviceNotification`. |

Android registration does not accept a token argument in the current SDK API. The Android SDK registers the current signed-in user/device through `AmityCoreClient.registerPushNotification()`.

## Register A Device

Register the current signed-in user/device after platform push setup and SDK initialization are complete.


```swift iOS
try await client.registerPushNotification(withDeviceToken: "<device-token>")
```

```kotlin Android
AmityCoreClient.registerPushNotification()
    .doOnComplete {
        // Device registration completed.
    }
    .doOnError { error ->
        // Handle registration error.
    }
    .subscribe()
```

```dart Flutter
await AmityCoreClient.registerDeviceNotification(fcmToken);
```


On Android, `registerPushNotification()` is a no-op for visitor and bot users. Register only after the app has a signed-in user session.

## Unregister A Device

Call unregister when the user signs out or when this app installation should stop receiving push notifications for the currently registered user.


```swift iOS
try await client.unregisterPushNotification()
```

```kotlin Android
AmityCoreClient.unregisterPushNotification()
    .doOnComplete {
        // Device unregistration completed.
    }
    .doOnError { error ->
        // Handle unregistration error.
    }
    .subscribe()
```

```dart Flutter
await AmityCoreClient.unregisterDeviceNotification();
```


## Related Setup

Complete platform setup before calling the SDK registration API:

- [iOS Setup](./setup/ios-setup)
- [Android Setup](./setup/android-setup)
- [Flutter Setup](./setup/flutter-setup)

---

### [Push Notification Settings](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/overview)

> Choose which push notifications a user receives at user, channel, and community scope.

Push notification settings are separate from device registration. Device registration tells social.plus which app installation can receive push notifications. Settings control which push notifications the signed-in user wants to receive.

## Settings Scopes

| Scope | What it controls | SDK entrypoint |
| --- | --- | --- |
| User | Account-wide push preferences, with optional module modifiers for chat, social, and video streaming. | `notifications().user()` / `client.notificationManager` |
| Channel | Push preference for one chat channel. | `notifications().channel(channelId)` / channel notification manager |
| Community | Push preference for one community, with optional event modifiers. | `notifications().community(communityId)` / community notification manager |

The SDK exposes these scopes independently. Read and update the exact scope your product setting is changing instead of assuming a hidden precedence rule.

## Platform Availability

| Platform | User settings | Channel settings | Community settings |
| --- | --- | --- | --- |
| TypeScript | Yes | Yes | Yes |
| iOS | Yes | Yes | Yes |
| Android | Yes | Yes | Yes |
| Flutter | Yes | Yes | Yes |

## Guides

    Configure account-wide push preferences and module modifiers.
    Enable, disable, or read push settings for a channel.
    Configure community push settings and event modifiers.

## Common Model

| Concept | Meaning |
| --- | --- |
| `isEnabled` | Whether push notifications are enabled at the requested scope. |
| Module modifier | User-level setting for chat, social, or video-streaming notifications. |
| Event modifier | Community-level setting for post, comment, story, and platform-supported livestream events. |
| Role filter | Optional filter that limits notification delivery by sender role where the SDK supports modifiers. |

---

### [User Notification Settings](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/user-settings)

> Read and update account-wide push notification settings for the signed-in user.

User notification settings apply across the signed-in user's devices. Use this scope for global push preferences and module-level choices for chat, social, and video-streaming notifications.

## API surface

| Platform | Manager | Read | Enable | Disable all |
| --- | --- | --- | --- | --- |
| TypeScript | `Client.notifications().user()` | `getSettings()` | `enable(modules?)` | `disableAllNotifications()` |
| iOS | `client.notificationManager` | `getSettings()` | `enable(for:)` | `disableAllNotifications()` |
| Android | `AmityCoreClient.notifications().user()` | `getSettings()` | `enable(moduleModifiers?)` | `disableAllNotifications()` |
| Flutter | `AmityCoreClient.notifications().user()` | `getSettings()` | `enable(eventModifiers)` | `disable()` |

## Parameters

| Name | Platform | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `modules` | TypeScript | `Amity.UserNotificationModule[]` | No | Module-level settings to send with `enable`. |
| `modules` | iOS | `[AmityUserNotificationModule]?` | No | Module-level settings passed to `enable(for:)`. |
| `moduleModifiers` | Android | `List<AmityUserNotificationModule.MODIFIER>?` | No | Module modifiers passed to `enable`. |
| `eventModifiers` | Flutter | `List<UserNotificationModifier>?` | Nullable | Module modifiers passed to `enable`. |
| `roleFilter` | TypeScript, iOS, Android, Flutter | Role filter | No | Optional filter for receiving notifications only from matching sender roles. |

## Modules

| Module value | TypeScript enum | iOS case | Android/Flutter modifier |
| --- | --- | --- | --- |
| `chat` | `CHAT` | `.chat` | `CHAT` / `Chat` |
| `social` | `SOCIAL` | `.social` | `SOCIAL` / `Social` |
| `video-streaming` | `VIDEO_STREAMING` | `.videoStreaming` | `VIDEO_STREAMING` / `VideoStreaming` |

## Get user settings

Read account-wide notification settings before rendering global or module-level push controls.


```typescript TypeScript
import { Client, NotificationRolesFilterTypeEnum } from '@amityco/ts-sdk';

const settings = await Client.notifications()
  .user()
  .getSettings();

const isEnabled = settings.isEnabled;

settings.modules.forEach(module => {
  const moduleName = module.moduleName;
  const moduleEnabled = module.isEnabled;

  if (module.rolesFilter?.type === NotificationRolesFilterTypeEnum.ONLY) {
    const roleIds = module.rolesFilter.roleIds;
    updateUI({ moduleName, moduleEnabled, roleIds });
  }
});
```

```swift iOS
let notificationManager = client.notificationManager
let settings = try await notificationManager.getSettings()

let isEnabled = settings.isEnabled

for module in settings.modules {
    switch module.moduleType {
    case .chat:
        print("chat enabled: \(module.isEnabled)")
    case .social:
        print("social enabled: \(module.isEnabled)")
    case .videoStreaming:
        print("video streaming enabled: \(module.isEnabled)")
    @unknown default:
        print("unknown module enabled: \(module.isEnabled)")
    }
}
```

```kotlin Android
AmityCoreClient.notifications()
    .user()
    .getSettings()
    .doOnSuccess { settings ->
        val isEnabled = settings.isEnabled()

        settings.getModules()?.forEach { module ->
            when (module) {
                is AmityUserNotificationModule.CHAT -> {
                    val moduleEnabled = module.isEnabled()
                }
                is AmityUserNotificationModule.SOCIAL -> {
                    val moduleEnabled = module.isEnabled()
                    val rolesFilter = module.getRolesFilter()
                }
                is AmityUserNotificationModule.VIDEO_STREAMING -> {
                    val moduleEnabled = module.isEnabled()
                }
                else -> Unit
            }
        }
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()
```

```dart Flutter
final settings = await AmityCoreClient
    .notifications()
    .user()
    .getSettings();

final isEnabled = settings.isEnabled;

settings.events?.forEach((module) {
  final moduleEnabled = module.isEnabled;
  final rolesFilter = module.rolesFilter;
});
```


## Update user settings

Enable, disable, or customize account-wide notification modules after the user changes global push preferences.


```typescript TypeScript
import {
  Client,
  NotificationRolesFilterTypeEnum,
  UserNotificationModuleNameEnum,
} from '@amityco/ts-sdk';

await Client.notifications()
  .user()
  .enable([
    {
      moduleName: UserNotificationModuleNameEnum.CHAT,
      isEnabled: true,
    },
    {
      moduleName: UserNotificationModuleNameEnum.SOCIAL,
      isEnabled: true,
      rolesFilter: {
        type: NotificationRolesFilterTypeEnum.ONLY,
        roleIds: ['community-moderator'],
      },
    },
    {
      moduleName: UserNotificationModuleNameEnum.VIDEO_STREAMING,
      isEnabled: false,
    },
  ]);

await Client.notifications()
  .user()
  .disableAllNotifications();
```

```swift iOS
let notificationManager = client.notificationManager

try await notificationManager.enable(for: [
    AmityUserNotificationModule(
        moduleType: .chat,
        isEnabled: true,
        roleFilter: nil
    ),
    AmityUserNotificationModule(
        moduleType: .social,
        isEnabled: true,
        roleFilter: AmityRoleFilter.onlyFilter(withRoleIds: ["community-moderator"])
    ),
    AmityUserNotificationModule(
        moduleType: .videoStreaming,
        isEnabled: false,
        roleFilter: nil
    ),
])

try await notificationManager.disableAllNotifications()
```

```kotlin Android
val rolesFilter = AmityRolesFilter.ONLY(AmityRoles(listOf("community-moderator")))

val chatModifier = AmityUserNotificationModule.CHAT.enable()
val socialModifier = AmityUserNotificationModule.SOCIAL.enable(rolesFilter)
val videoStreamingModifier = AmityUserNotificationModule.VIDEO_STREAMING.disable()

AmityCoreClient.notifications()
    .user()
    .enable(
        moduleModifiers = listOf(
            chatModifier,
            socialModifier,
            videoStreamingModifier
        )
    )
    .doOnComplete {
        // User notification settings updated.
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()

AmityCoreClient.notifications()
    .user()
    .disableAllNotifications()
    .subscribe()
```

```dart Flutter
final rolesFilter = Only(AmityRoles(roles: ['community-moderator']));

await AmityCoreClient
    .notifications()
    .user()
    .enable([
      Chat.enable(null),
      Social.enable(rolesFilter),
      VideoStreaming.disable(),
    ]);

await AmityCoreClient
    .notifications()
    .user()
    .disable();
```


## Related

    Configure push settings for a chat channel.
    Configure push settings for social community events.

---

### [Channel Notification Settings](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/channel-settings)

> Read and update push notification settings for a single chat channel.

Channel notification settings control whether the signed-in user receives push notifications for one channel.

## API surface

| Platform | Manager | Read | Enable | Disable |
| --- | --- | --- | --- | --- |
| TypeScript | `Client.notifications().channel(channelId)` | `getSettings()` | `enable()` | `disable()` |
| iOS | `channelRepository.notificationManagerForChannel(withId:)` | `getSettings()` | `enable()` | `disable()` |
| Android | `AmityCoreClient.notifications().channel(channelId)` | `getSettings()` | `enable()` | `disable()` |
| Flutter | `AmityCoreClient.notifications().channel(channelId)` | `getSettings()` | `enable()` | `disable()` |

## Parameters

| Name | Platform | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `channelId` | TypeScript, iOS, Android, Flutter | `String` / `string` | Yes | ID of the channel whose push setting should be read or updated. |

## Get channel settings

Read channel notification settings before rendering a channel-level push toggle.


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const settings = await Client.notifications()
  .channel(channelId)
  .getSettings();

const isEnabled = settings.isEnabled;
```

```swift iOS
let notificationManager = channelRepository.notificationManagerForChannel(withId: channelId)
let settings = try await notificationManager.getSettings()

let isEnabled = settings.isEnabled
```

```kotlin Android
AmityCoreClient.notifications()
    .channel(channelId)
    .getSettings()
    .doOnSuccess { settings: AmityChannelNotificationSettings ->
        val isEnabled = settings.isEnabled()
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()
```

```dart Flutter
final settings = await AmityCoreClient
    .notifications()
    .channel(channelId)
    .getSettings();

final isEnabled = settings.isEnabled;
```


## Update channel settings

Enable or disable notifications for a channel after the user changes that channel's push preference.


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

await Client.notifications()
  .channel(channelId)
  .enable();

await Client.notifications()
  .channel(channelId)
  .disable();
```

```swift iOS
let notificationManager = channelRepository.notificationManagerForChannel(withId: channelId)

try await notificationManager.enable()
try await notificationManager.disable()
```

```kotlin Android
AmityCoreClient.notifications()
    .channel(channelId)
    .enable()
    .doOnComplete {
        // Channel push notifications enabled.
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()

AmityCoreClient.notifications()
    .channel(channelId)
    .disable()
    .doOnComplete {
        // Channel push notifications disabled.
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()
```

```dart Flutter
await AmityCoreClient
    .notifications()
    .channel(channelId)
    .enable();

await AmityCoreClient
    .notifications()
    .channel(channelId)
    .disable();
```


## Related

    Configure account-wide push preferences.
    Configure push settings for social community events.

---

### [Community Notification Settings](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/community-settings)

> Read and update push notification settings for one community.

Community notification settings control whether the signed-in user receives push notifications from one community. You can also pass event modifiers to enable or disable specific community notification events.

## API surface

| Platform | Manager | Read | Enable | Disable |
| --- | --- | --- | --- | --- |
| TypeScript | `Client.notifications().community(communityId)` | `getSettings()` | `enable(events?)` | `disable()` |
| iOS | `communityRepository.notificationManager(forCommunityId:)` | `getSettings()` | `enable(events:)` | `disable()` |
| Android | `AmityCoreClient.notifications().community(communityId)` | `getSettings()` | `enable(eventModifiers?)` | `disable()` |
| Flutter | `AmityCoreClient.notifications().community(communityId)` | `getSettings()` | `enable(eventModifiers)` | `disable()` |

## Parameters

| Name | Platform | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `communityId` | TypeScript, iOS, Android, Flutter | `String` / `string` | Yes | ID of the community whose push setting should be read or updated. |
| `events` | TypeScript, iOS | Community notification event list | No on TypeScript, yes on iOS | Event-level modifiers to send with `enable`. |
| `eventModifiers` | Android, Flutter | Community notification modifier list | No on Android, nullable on Flutter | Event-level modifiers to send with `enable`. |
| `roleFilter` | TypeScript, iOS, Android, Flutter | Role filter | No | Optional filter for receiving notifications only from matching sender roles. |

## Community events

| Event value | TypeScript enum | iOS case | Android modifier | Flutter modifier |
| --- | --- | --- | --- | --- |
| `post.created` | `POST_CREATED` | `.postCreated` | `POST_CREATED` | `PostCreated` |
| `post.reacted` | `POST_REACTED` | `.postReacted` | `POST_REACTED` | `PostReacted` |
| `comment.created` | `COMMENT_CREATED` | `.commentCreated` | `COMMENT_CREATED` | `CommentCreated` |
| `comment.replied` | `COMMENT_REPLIED` | `.commentReplied` | `COMMENT_REPLIED` | `CommentReplied` |
| `comment.reacted` | `COMMENT_REACTED` | `.commentReacted` | `COMMENT_REACTED` | `CommentReacted` |
| `story.created` | `STORY_CREATED` | `.storyCreated` | `STORY_CREATED` | `StoryCreated` |
| `story.reacted` | `STORY_REACTED` | `.storyReacted` | `STORY_REACTED` | `StoryReacted` |
| `story-comment.created` | `STORY_COMMENT_CREATED` | `.storyCommentCreated` | `STORY_COMMENT_CREATED` | `StoryCommentCreated` |
| `video-streaming.didStart` | `LIVESTREAM_START` | `.livestreamStart` | `LIVESTREAM_START` | Not exposed |

  Flutter exposes `video-streaming` as a user notification module, but this checkout does not expose a community-level livestream-start event modifier.

## Get community settings

Read community notification settings before rendering community-level or event-level push controls.


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const settings = await Client.notifications()
  .community(communityId)
  .getSettings();

const isEnabled = settings.isEnabled;

settings.events.forEach(event => {
  const eventName = event.eventName;
  const eventEnabled = event.isEnabled;
  const networkEnabled = event.isNetworkEnabled;

  updateUI({ eventName, eventEnabled, networkEnabled });
});
```

```swift iOS
let notificationManager = communityRepository.notificationManager(forCommunityId: communityId)
let settings = try await notificationManager.getSettings()

let isEnabled = settings.isEnabled

for event in settings.events {
    print("- event \(event.eventName) enabled: \(event.isEnabled)")
}
```

```kotlin Android
AmityCoreClient.notifications()
    .community(communityId)
    .getSettings()
    .doOnSuccess { settings: AmityCommunityNotificationSettings ->
        val isEnabled = settings.isEnabled()

        settings.getNotificationEvents().forEach { event ->
            when (event) {
                is AmityCommunityNotificationEvent.POST_CREATED -> {
                    val eventEnabled = event.isEnabled()
                    val networkEnabled = event.isNetworkEnabled()
                }
                else -> Unit
            }
        }
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()
```

```dart Flutter
final settings = await AmityCoreClient
    .notifications()
    .community(communityId)
    .getSettings();

final isEnabled = settings.isEnabled;

settings.events?.forEach((event) {
  final eventEnabled = event.isEnabled;
  final networkEnabled = event.isNetworkEnabled;
});
```


## Update community settings

Enable, disable, or customize community notification events after the user changes community push preferences.


```typescript TypeScript
import {
  Client,
  CommunityNotificationEventNameEnum,
  NotificationRolesFilterTypeEnum,
} from '@amityco/ts-sdk';

await Client.notifications()
  .community(communityId)
  .enable([
    {
      eventName: CommunityNotificationEventNameEnum.POST_CREATED,
      isEnabled: true,
      rolesFilter: {
        type: NotificationRolesFilterTypeEnum.ONLY,
        roleIds: ['community-moderator'],
      },
    },
    {
      eventName: CommunityNotificationEventNameEnum.STORY_REACTED,
      isEnabled: false,
    },
  ]);

await Client.notifications()
  .community(communityId)
  .disable();
```

```swift iOS
let notificationManager = communityRepository.notificationManager(forCommunityId: communityId)

try await notificationManager.enable(events: [
    AmityCommunityNotificationEvent(
        eventType: .postCreated,
        isEnabled: true,
        roleFilter: AmityRoleFilter.onlyFilter(withRoleIds: ["community-moderator"])
    ),
    AmityCommunityNotificationEvent(
        eventType: .storyReacted,
        isEnabled: false,
        roleFilter: nil
    ),
])

try await notificationManager.disable()
```

```kotlin Android
val rolesFilter = AmityRolesFilter.ONLY(AmityRoles(listOf("community-moderator")))

val postCreatedModifier = AmityCommunityNotificationEvent.POST_CREATED.enable(rolesFilter)
val storyReactedModifier = AmityCommunityNotificationEvent.STORY_REACTED.disable()

AmityCoreClient.notifications()
    .community(communityId)
    .enable(
        eventModifiers = listOf(
            postCreatedModifier,
            storyReactedModifier
        )
    )
    .doOnComplete {
        // Community notification settings updated.
    }
    .doOnError { error ->
        // Handle error.
    }
    .subscribe()

AmityCoreClient.notifications()
    .community(communityId)
    .disable()
    .subscribe()
```

```dart Flutter
final rolesFilter = Only(AmityRoles(roles: ['community-moderator']));

await AmityCoreClient
    .notifications()
    .community(communityId)
    .enable([
      PostCreated.enable(rolesFilter),
      StoryReacted.disable(),
    ]);

await AmityCoreClient
    .notifications()
    .community(communityId)
    .disable();
```


## Related

    Configure account-wide push preferences and module modifiers.
    Configure push settings for a chat channel.

---

### [Android Push Notifications](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/android-setup)

> Connect Android push tokens to the current social.plus Android SDK.

Android push setup has two separate responsibilities:

1. Configure the Android app and provider, such as Firebase Cloud Messaging.
2. Connect the provider token and signed-in device to social.plus through the SDK.

Push delivery also requires server-side credentials in the social.plus Console. The client SDK can register a device only after the platform push provider and console configuration are complete.

## SDK Surface

| Purpose | Current Android API | When to call |
| --- | --- | --- |
| Store an FCM token with the SDK push adapter | `AmityFcm.create().setup(fcmToken)` | When Firebase gives your app an FCM token, including token refresh. |
| Register the current signed-in device/user | `AmityCoreClient.registerPushNotification()` | After the SDK has a signed-in user session. |
| Unregister the current device/user | `AmityCoreClient.unregisterPushNotification()` | On sign-out or when this installation should stop receiving push notifications. |

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fcmToken` | `String` | Yes | The FCM registration token returned by Firebase for this app installation. |
| `baiduApiKey` | `String` | Only for Baidu builds | API key passed to the optional Baidu push adapter when that module is included in your Android build. |

## 1. Configure FCM

Follow the Android and Firebase setup flow for your app:

- Add `google-services.json` to your app module.
- Apply the Google Services Gradle plugin.
- Add Firebase Messaging using the version recommended for your Firebase setup.
- Request `POST_NOTIFICATIONS` at runtime on Android 13+ when your product needs visible notifications.

If your Android dependency setup installs SDK modules separately, include the FCM push adapter with the same version as your social.plus Android SDK:

```gradle Gradle
dependencies {
    implementation 'co.amity.android:amity-push-fcm:x.y.z'
}
```

Use the same `x.y.z` version you use for `co.amity.android:amity-sdk`. If your package already bundles the FCM adapter, do not add a duplicate dependency.

## 2. Upload Provider Credentials

In the social.plus Console, open **Settings > Push Notifications** and upload the Firebase service account JSON for your app. Without this server-side credential, client registration can succeed while push delivery still fails.

## 3. Connect the FCM Token

Pass every current FCM token to the SDK push adapter. Do this for the initial token and every token refresh.


```kotlin Android
import com.amity.socialcloud.sdk.push.AmityFcm

val fcmToken = "fcm-token"

AmityFcm.create()
    .setup(fcmToken)
    .subscribe()
```


The Android sample app calls the same adapter from `FirebaseMessagingService.onNewToken(token)`.

## 4. Register the Signed-In Device

After the SDK has a signed-in user session and the app has connected the FCM token, register the current device/user with social.plus.


```kotlin Android
AmityCoreClient.registerPushNotification()
    .doOnComplete {
        // Device registration completed.
    }
    .doOnError { error ->
        // Handle registration error.
    }
    .subscribe()
```


Call unregister when the user signs out or disables push for this installation.


```kotlin Android
AmityCoreClient.unregisterPushNotification()
    .doOnComplete {
        // Device unregistration completed.
    }
    .doOnError { error ->
        // Handle unregistration error.
    }
    .subscribe()
```


`registerPushNotification()` has no token parameter in the current Android SDK. The token is handled by the push adapter through `AmityFcm.create().setup(fcmToken)`.

## Optional Baidu Adapter

The Android source also contains an optional Baidu push adapter, `AmityBaidu.create(context).setup(baiduApiKey)`, for builds that include the Baidu push module. The default Android SDK build path uses the FCM adapter, so treat Baidu setup as a China-market build decision and verify the module distribution before enabling it.

## Setup Checklist

- FCM is configured in the Android app.
- The Firebase service account JSON is uploaded in the social.plus Console.
- The latest FCM token is passed to `AmityFcm.create().setup(fcmToken)`.
- The signed-in device/user is registered with `AmityCoreClient.registerPushNotification()`.
- The device is unregistered on sign-out when the app should stop receiving push notifications for that user.

---

### [Flutter Push Notification Setup](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/flutter-setup)

> Register Flutter push tokens with the current social.plus Flutter SDK.

Flutter push setup combines native platform configuration with one SDK registration call. Your app obtains the push token through Firebase or the native platform, then passes that token to the social.plus Flutter SDK after the user is signed in.

The Flutter SDK does not create Firebase projects, APNs certificates, or platform permission prompts for you. It registers the token that your app receives from those platform systems.

## SDK Surface

| Purpose | Current Flutter API | When to call |
| --- | --- | --- |
| Register the current device token | `AmityCoreClient.registerDeviceNotification(fcmToken)` | After the SDK has a signed-in user session and your app has a current token. |
| Unregister the current device | `AmityCoreClient.unregisterDeviceNotification()` | On sign-out or when this installation should stop receiving push notifications. |

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fcmToken` | `String` | Yes | The token your Flutter app receives from Firebase Messaging or the platform push provider. |

## 1. Configure Platform Push

Configure Firebase Messaging for Flutter using your app's Firebase project:

- Add the Firebase packages that match your FlutterFire setup.
- Run FlutterFire configuration for Android and iOS.
- Add `google-services.json` for Android.
- Add `GoogleService-Info.plist` for iOS.
- Enable Push Notifications capability for the iOS target.
- Upload the required push credentials in the social.plus Console under **Settings > Push Notifications**.

Keep Firebase and FlutterFire package versions in your app, not hardcoded in this docs page. Follow the version matrix for your Flutter, Firebase, and React Native toolchain.

## 2. Register the Token

Once your app has a token and the user is signed in to social.plus, register the device token with the SDK.


```dart Flutter
final fcmToken = '<fcm-token>';

await AmityCoreClient.registerDeviceNotification(fcmToken);
```


Call the same SDK method again when Firebase reports a refreshed token. The last registration replaces the previous token state for this app installation.

## 3. Unregister on Sign-Out

Unregister when the user signs out or when this app installation should stop receiving push notifications for the current social.plus user.


```dart Flutter
await AmityCoreClient.unregisterDeviceNotification();
```


## Setup Checklist

- Firebase Messaging is configured for the Flutter app.
- Android and iOS platform files are present in the correct native projects.
- APNs or FCM credentials are uploaded in the social.plus Console.
- The signed-in user token is registered through `AmityCoreClient.registerDeviceNotification(fcmToken)`.
- The device is unregistered through `AmityCoreClient.unregisterDeviceNotification()` on sign-out.

---

### [iOS Push Notifications](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/ios-setup)

> Register APNs device tokens with the current social.plus iOS SDK.

iOS push setup has two parts: configure APNs for your app, then register the APNs device token with the social.plus iOS SDK after the user is signed in.

Push notifications require an Apple Developer account, the Push Notifications capability, and valid APNs credentials uploaded in the social.plus Console.

## SDK Surface

| Purpose | Current iOS API | When to call |
| --- | --- | --- |
| Register the current device token | `client.registerPushNotification(withDeviceToken:)` | After APNs returns a device token and the SDK has a signed-in user session. |
| Unregister the current device | `client.unregisterPushNotification()` | On sign-out or when this installation should stop receiving push notifications. |

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | `String` | Yes | APNs device token converted from the `Data` value returned by iOS. |

## 1. Configure APNs

In Apple Developer Console:

1. Open **Certificates, Identifiers & Profiles**.
2. Select your app's Bundle ID.
3. Enable Push Notifications.
4. Create the APNs certificate or auth key your release process uses.

In Xcode:

1. Select your app target.
2. Open **Signing & Capabilities**.
3. Add **Push Notifications**.
4. Add background remote-notification mode only if your app needs background notification handling.

In the social.plus Console, open **Settings > Push Notifications** and upload the iOS APNs credential for the same Bundle ID.

## 2. Request System Registration

Ask the user for notification permission at a product moment that makes sense, then ask iOS to register the app for remote notifications.


```swift iOS
import UserNotifications

UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, _ in
    if granted {
        DispatchQueue.main.async {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}
```


## 3. Register the APNs Token

When iOS calls your app delegate with the device token, convert the token data to a hex string and pass it to the SDK.


```swift iOS
func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()

    Task { @MainActor in
        do {
            try await client.registerPushNotification(withDeviceToken: token)
        } catch {
            handleError(error)
        }
    }
}
```


`registerPushNotification(withDeviceToken:)` is available for signed-in users. The SDK throws for guest users.

## 4. Unregister on Sign-Out

Call unregister when the current app installation should stop receiving push notifications for the signed-in social.plus user.


```swift iOS
try await client.unregisterPushNotification()
```


## Setup Checklist

- Push Notifications capability is enabled for the app target.
- The APNs credential for the app Bundle ID is uploaded in the social.plus Console.
- The app calls `UIApplication.shared.registerForRemoteNotifications()` after permission is granted.
- The APNs device token is passed to `client.registerPushNotification(withDeviceToken:)`.
- The app calls `client.unregisterPushNotification()` on sign-out when push should stop for that user.

---

### [React Native Push Notifications](https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/react-native-setup)

> Understand React Native push-notification support in the SDK docs.

The TypeScript SDK does not currently expose a client-side push device registration API. That means a React Native app cannot complete social.plus push registration by calling a TypeScript SDK method from JavaScript.

Do not build React Native push setup around a TypeScript SDK method such as `registerPushNotification()` or `registerDeviceNotification()`. Those APIs are not exported by `@amityco/ts-sdk`.

## Current Support Boundary

| Layer | Status | What to use |
| --- | --- | --- |
| React Native JavaScript with `@amityco/ts-sdk` | No client device registration API | Use the TypeScript SDK for supported chat and social data features, not push device registration. |
| Android native SDK | Supported | Use [Android Push Notifications](./android-setup) and call the native Android SDK registration APIs. |
| iOS native SDK | Supported | Use [iOS Push Notifications](./ios-setup) and call the native iOS SDK registration APIs. |
| Flutter SDK | Supported | Use [Flutter Push Notification Setup](./flutter-setup) for Flutter apps. |

## Integration Options

For a React Native app that needs social.plus push notifications, choose one of these supported paths:

1. Implement push registration in native Android and iOS layers using the native SDKs.
2. Bridge the native registration result into React Native only for app state or UI, not as a TypeScript SDK call.
3. If you use a React Native UI Kit package, follow the UI Kit's push-notification instructions for that package. UI Kit APIs are outside this SDK-first audit.

## Console Configuration Still Applies

Even when registration happens through native code, the app still needs provider credentials in the social.plus Console:

- Android builds need the Firebase service account JSON uploaded under **Settings > Push Notifications**.
- iOS builds need the APNs credential for the app Bundle ID uploaded under **Settings > Push Notifications**.

## Related Setup

    Configure FCM and register the signed-in device through the Android SDK.
    Configure APNs and register the device token through the iOS SDK.
    Compare device registration APIs across supported SDK platforms.

## Video — Getting Started

### [Move from Stream to Room](https://learn.social.plus/social-plus-sdk/video-new/migration-guide)

> Plan SDK code changes when moving livestream integrations from legacy Stream APIs to room-based live experiences.

Use room APIs for new livestream and co-host experiences. Legacy Stream APIs still exist in the audited SDK sources, so treat this page as an application migration checklist rather than a removal timeline or data-migration promise.

  This page focuses on SDK code paths only. UIKit, Admin Console, backend API behavior, commercial timelines, and product analytics dashboards are outside this SDK-first migration guide.

## Migration Scope

| Area | Keep legacy Stream support for | Move new work to Room APIs |
| --- | --- | --- |
| Existing content | Existing Stream posts and playback screens that your product still needs to support | New live room and co-host experiences |
| Entity model | `AmityStream` / `streamId` | `AmityRoom` / `roomId` |
| Feed post type | Legacy live stream post data | Room post data with `roomId` |
| Playback source | Stream watcher or recording data | `livePlaybackUrl` and `recordedPlaybackInfos` / `recordedData` / `getRecordedPlaybackInfos()` |
| Watch analytics | Legacy stream-session logic where still used | `room.analytics()` watch-session APIs |

  Do not delete legacy Stream handling until every screen that can display old Stream posts has a fallback path. A migration usually means supporting both old Stream content and new Room content during rollout.

## Platform Surface

| Platform | Legacy Stream surface found | Room surface found | Room post creation | Migration note |
| --- | --- | --- | --- | --- |
| TypeScript | `StreamRepository`, `Amity.Stream`, `streamId` fields in legacy surfaces | `RoomRepository`, `Amity.Room` | `PostRepository.createRoomPost()` | Use room APIs for new rooms and keep stream handling for old posts. |
| iOS | `AmityStreamRepository`, `AmityStream` | `AmityRoomRepository`, `AmityRoom` | `AmityPostRepository.createRoomPost()` with `AmityRoomPostBuilder` | Retain `AmityNotificationToken` values while observing live objects or collections. |
| Android | `AmityVideoClient.newStreamRepository()`, `AmityStreamRepository`, `AmityStream` | `AmityVideoClient.newRoomRepository()`, `AmityRoomRepository`, `AmityRoom` | `AmityPostRepository.createRoomPost()` | Room APIs return Rx types; dispose subscriptions with your app lifecycle. |
| Flutter | Legacy `AmityVideoClient.newStreamRepository()` and `StreamRepository` | No current public room broadcasting repository found in this audit | No current public room post creator found in this audit | Do not promise a Flutter room migration path from SDK docs until the public API exists. |

## Concept Mapping

| Legacy Stream concept | Room-based concept | What changes in app code |
| --- | --- | --- |
| `streamId` | `roomId` | Store and pass room IDs for new room content. Keep stream IDs for legacy content. |
| `AmityStream` | `AmityRoom` | Read room status, participants, playback URLs, and recorded metadata from room models. |
| Stream repository | Room repository | Use `RoomRepository` / `AmityRoomRepository` / `newRoomRepository()` for new room flows. |
| Legacy live stream post | Room post | Create a room first, then create a room post that references the `roomId`. |
| Stream watcher URL / recordings | Room live and recorded playback fields | Pass SDK-returned room playback URLs to your app-owned player. |
| Stream session analytics | Room watch-session analytics | Use `room.analytics()` for new room watch sessions. |

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Observe room content | `roomId` | Yes | TypeScript, iOS, Android | Room ID used when replacing new Stream observation flows with room observation. |
| Create room | Room options | Yes | TypeScript, iOS, Android | Room title and configuration passed to the room repository. |
| Publish room post | `communityId` or target ID | Yes | TypeScript, iOS, Android | Feed target where the room post should be published. |
| Publish room post | `roomId` | Yes | TypeScript, iOS, Android | Room ID returned by room creation and embedded in the room post. |
| Publish room post | Text or title fields | No | TypeScript, iOS, Android | Display text used by the feed post that references the room. |

## Observe Room Content

Replace new Stream observation flows with room observation for new room-based screens. Each snippet below is standalone and uses the current room repository surface.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeRoomForMigration(roomId: string): Amity.Unsubscriber {
  return RoomRepository.getRoom(roomId, snapshot => {
    if (snapshot.error) {
      handleError(snapshot.error);
      return;
    }

    const room = snapshot.data;
    showSuccessMessage(room.status);
  });
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val disposable = AmityVideoClient.newRoomRepository()
    .getRoom(roomId)
    .subscribe(
        { room -> showSuccessMessage(room.getStatus()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    if let room = liveObject.snapshot {
        showSuccessMessage(room.status.rawValue)
    }
}
```


## Create and Publish a Room

For new room-based livestreams, create the room first. Publish it into a user or community feed by creating a room post with the returned `roomId`.


```typescript TypeScript
import { PostRepository, RoomRepository } from "@amityco/ts-sdk";

async function createAndPublishRoom(communityId: string): Promise<string> {
  const { data: room } = await RoomRepository.createRoom({
    title: "Live room",
    liveChatEnabled: true,
    type: "coHosts",
  });

  const { data: post } = await PostRepository.createRoomPost({
    targetType: "community",
    targetId: communityId,
    data: {
      roomId: room.roomId,
      text: "Join this live room",
      title: "Live room",
    },
  });

  showSuccessMessage(post.postId);

  return post.postId;
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.social.AmitySocialClient
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.social.post.AmityPost

val postRepository = AmitySocialClient.newPostRepository()

val disposable = AmityVideoClient.newRoomRepository()
    .createRoom(
        title = "Live room",
        liveChatEnabled = true
    )
    .flatMap { room ->
        postRepository.createRoomPost(
            targetType = AmityPost.TargetType.COMMUNITY,
            targetId = communityId,
            roomId = room.getRoomId(),
            text = "Join this live room",
            title = "Live room"
        )
    }
    .subscribe(
        { post -> showSuccessMessage(post.getPostId()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
func createAndPublishRoom(communityId: String) async throws -> String {
    let options = AmityRoomCreateOptions(
        title: "Live room",
        liveChatEnabled: true,
        type: .coHosts
    )

    let room = try await AmityRoomRepository().createRoom(with: options)

    let builder = AmityRoomPostBuilder(
        roomId: room.roomId,
        text: "Join this live room"
    )
    builder.setTitle("Live room")

    let post = try await AmityPostRepository().createRoomPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )

    showSuccessMessage(post.postId)

    return post.postId
}
```


## Migration Checkpoints

| Checkpoint | What to verify |
| --- | --- |
| Data model | New room-backed records store `roomId`; legacy records that still point to streams keep `streamId`. |
| Feed rendering | Feed cards branch by data type and render both legacy Stream posts and new Room posts during rollout. |
| Playback | New Room playback reads `livePlaybackUrl` for live rooms and recorded metadata only after `recorded` status. |
| Broadcasting | New broadcasts create a room and request broadcaster data before connecting your media layer. |
| Chat | If your room enables live chat, fetch the room live chat channel through the room API before rendering chat UI. |
| Analytics | Start room watch sessions only for `live` or `recorded` rooms and update watch duration from player state. |
| Lifecycle | Retain and dispose each platform's subscription/token/disposable with the screen lifecycle. |

## Rollout Strategy

1. Add room post rendering while keeping legacy Stream post rendering.
2. Create new livestreams through room APIs and create room posts for feed visibility.
3. Move playback screens to read room playback fields for room posts.
4. Wire room watch analytics after the player starts active playback.
5. Keep legacy Stream code only for content that still exists in your product.

  Room APIs do not make the SDK own camera capture, player controls, autoplay, buffering, captions, or DRM. Those remain app and media-player responsibilities.

## Related Topics

    Create rooms and retrieve broadcaster data.
    Publish an existing room into a feed.
    Choose live or recorded room playback sources.

## Video — Broadcasting

### [Broadcasting Overview](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/overview)

> SDK-backed overview of room-based live broadcasting and co-host rooms.

Room broadcasting is the current SDK path for live rooms, including co-host rooms and direct-streaming room types where the platform exposes them. Treat rooms as the social.plus record for the live session: the SDK creates, observes, updates, stops, and publishes room objects, while your app's media stack connects to the streaming provider with credentials returned by the SDK.

  This page is about the SDK room APIs. The legacy stream APIs and UIKit-level video experiences are separate surfaces.

## Platform Surface

| Platform | Current SDK surface | Notes |
| --- | --- | --- |
| TypeScript | `RoomRepository` and `PostRepository.createRoomPost()` | Supports room creation, live object/live collection observers, broadcaster data, stop/update/delete, recorded URL lookup, and room posts. |
| iOS | `AmityRoomRepository`, `AmityRoomCreateOptions`, and `AmityPostRepository.createRoomPost()` | Supports room creation, `AmityObject<AmityRoom>`, `AmityCollection<AmityRoom>`, stop/update/delete, co-host events, room token generation, and room posts. |
| Android | `AmityVideoClient.newRoomRepository()` and `AmitySocialClient.newPostRepository().createRoomPost()` | Supports room creation, `Flowable<AmityRoom>`, paging room queries, stop/update/delete, broadcaster data, recorded URLs, co-host events, and room posts. |
| Flutter | No current public room broadcasting repository found in this audit | The Flutter source has older stream APIs such as `AmityStream`, but no public `AmityRoomRepository` or room post creation surface. |

## What the SDK Owns

| Concern | SDK-owned | App-owned |
| --- | --- | --- |
| Room record | Create, read, query, update, stop, delete where supported | Choose when to create or clean up rooms |
| Feed distribution | Create a room post from an existing `roomId` where supported | Decide the target feed and product copy |
| Broadcast credentials | Return broadcaster token or URL data where supported | Hand credentials to your media or LiveKit integration |
| Live viewing | Expose room playback fields such as live playback URL and thumbnails | Build the player, controls, and viewer UX |
| Room state | Expose statuses and realtime observers | React to state transitions in UI and operations |

## Room Workflow

    Create the room with a title and optional room configuration. Use [Create Room](./create-room) for platform-specific examples.
    Publish the room to a user or community feed with `createRoomPost()`. See [Room Posts](/social-plus-sdk/social/content-management/posts/creation/room-post).
    Request broadcaster data for the room. TypeScript and Android expose typed broadcaster-data APIs; iOS exposes room token generation.
    Connect your app's media stack, such as a LiveKit client, using the returned credentials. This connection is outside the social.plus SDK.
    Observe the room object or room collection for lifecycle changes, then call the stop API when the broadcast ends.

## Room Statuses

| Status | Meaning | Platform notes |
| --- | --- | --- |
| `idle` | Room exists but is not currently live | Available across TypeScript, iOS, and Android. |
| `live` | Room is actively broadcasting | Available across TypeScript, iOS, and Android. |
| `waitingReconnect` | Room is waiting for the broadcaster to reconnect | Available across TypeScript, iOS, and Android. |
| `ended` | Live session has ended | Available across TypeScript, iOS, and Android. |
| `recorded` | Recorded playback metadata is available | Available across TypeScript, iOS, and Android. |
| `terminated` | Room was terminated | Exposed by TypeScript and iOS room status types. |
| `error` | Room entered an error state | Available across TypeScript, iOS, and Android. |

## Related Topics

    Review the room model, statuses, participants, and playback fields.
    Create a room and request broadcaster data with platform-specific SDK snippets.
    Query, observe, update, stop, and delete room records.
    Invite, remove, and observe co-host room participants.
    Use room playback fields to power viewer playback.
    Access recorded playback metadata after a room is recorded.

---

### [Rooms Overview](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/rooms-overview)

> SDK-backed model overview for live rooms, co-host rooms, playback fields, and room state.

Rooms are SDK records for live broadcasting sessions. A room can be observed as a single live object or queried as a live collection, then published into a feed by creating a room post from its `roomId`.

This page focuses on source-backed room concepts. Use [Create Room](./create-room) for runnable snippets.

## Platform Availability

| Platform | Room model | Single room observer | Room list/query | Room post |
| --- | --- | --- | --- | --- |
| TypeScript | `Amity.Room` | `RoomRepository.getRoom(roomId, callback)` | `RoomRepository.getRooms(params, callback)` | `PostRepository.createRoomPost()` |
| iOS | `AmityRoom` | `AmityRoomRepository().getRoom(withId:)` | `AmityRoomRepository().getRooms(with:)` | `AmityPostRepository().createRoomPost()` |
| Android | `AmityRoom` | `AmityVideoClient.newRoomRepository().getRoom(roomId)` | `AmityVideoClient.newRoomRepository().getRooms().build().query()` | `AmitySocialClient.newPostRepository().createRoomPost()` |
| Flutter | No current public `AmityRoom` model found | Not available | Not available | Not available |

## Room Types

| Type value | Meaning | Platform notes |
| --- | --- | --- |
| `coHosts` | Co-host live room type | TypeScript and iOS accept this value during creation. Android exposes it as `AmityRoomType.CO_HOSTS` for queries, but current `createRoom()` does not expose a room type argument. |
| `directStreaming` | Direct streaming room type | TypeScript and iOS expose this value. Android exposes it as `AmityRoomType.DIRECT_STREAMING` for queries. |

## Room Fields

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Room ID | `room.roomId` | `room.roomId` | `room.getRoomId()` |
| Status | `room.status` | `room.status` | `room.getStatus()` |
| Title and description | `title`, `description` | `title`, `description` | `getTitle()`, `getDescription()` |
| Chat channel linkage | `liveChannelEnabled`, `liveChannelId`, `getLiveChat()` | `channelEnabled`, `channelId`, `channel` | `isChannelEnabled()`, `getChannelId()`, `getChannel()` |
| Feed/post reference | `referenceType`, `referenceId`, `post` | `referenceType`, `referenceId`, `post` | `getReferenceType()`, `getReferenceId()`, `getPost()` |
| Live playback | `livePlaybackUrl`, `liveThumbnailUrl`, `liveResolution` | `livePlaybackUrl`, `liveThumbnailUrl`, `liveResolution` | `getLivePlaybackUrl()`, `getLiveThumbnailUrl()`, `getLiveResolution()` |
| Recorded playback | `recordedPlaybackInfos`, `recordedResolution` | `recordedData`, `recordedResolution` | `getRecordedPlaybackInfos()`, `getRecordedResolution()` |
| Parent and child rooms | `parentRoomId`, `childRoomIds`, `childRooms` | `parentRoomId`, `childRoomIds`, `childRooms` | `getParentRoomId()`, `getChildRoomIds()`, `getChildRooms()` |
| Creator and deletion | `createdBy`, `isDeleted`, `deletedBy` | `creatorId`, `creator`, `isDeleted`, `deletedById` | `getCreatorId()`, `getCreator()`, `isDeleted()` |
| Custom metadata | `metadata` | `metadata` | `getMetadata()` |
| Moderation | `moderation` | `moderation` | `getModeration()` |

  Android's current public `AmityRoom` model does not expose a direct `getType()` accessor even though room type is available in query filters and internal model construction.

## Participants

Participants are users who can broadcast in the room. Viewers are not room participants.

| Field | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Role/type | `type: "host" | "coHost"` | `type: String` | `ParticipantType.HOST`, `ParticipantType.CoHost`, or `ParticipantType.Unknown` |
| User ID | `userId` | `userId` | `userId` |
| Internal user ID | `userInternalId` | `userInternalId` | `userInternalId` |
| Linked user | `user` | `user` | `user` |
| Product-tag permission | `canManageProductTags` | `canManageProductTags` | `canManageProductTags` |

## Status Model

| Status | Meaning |
| --- | --- |
| `idle` | The room exists but is not broadcasting. |
| `live` | The room is currently broadcasting. |
| `waitingReconnect` | The live session is waiting for reconnection. |
| `ended` | The live session has stopped. |
| `recorded` | Recorded playback metadata is available. |
| `terminated` | The room was terminated. TypeScript and iOS expose this status. |
| `error` | The room is in an error state. |

## Room Posts and Feed Distribution

Creating a room does not by itself document a feed post in the SDK examples. To publish the room into a feed, create a room post with the room ID.

    Create a user or community feed post that references an existing room.
    Create a room before publishing it as a room post.

## Media and Playback Fields

The room model exposes media fields that your app can use for live or recorded playback. The SDK does not render the player for SDK integrations.

| Field | Availability | Use |
| --- | --- | --- |
| `livePlaybackUrl` | While live when available | Viewer playback URL. |
| `liveThumbnailUrl` | Live or reconnecting sessions when available | Live thumbnail generated by the streaming backend. |
| `liveResolution` | Live or reconnecting sessions when available | Live stream aspect ratio, width, and height. |
| `recordedPlaybackInfos` / `recordedData` | After recording is available | Recorded playback URL and thumbnail metadata. |
| `recordedResolution` | After recording is available | Recorded stream aspect ratio, width, and height. |

## Next Steps

    Create rooms and retrieve broadcaster data.
    Observe, query, update, stop, and delete rooms.
    Manage co-host invitations, removal, and permissions.
    Read recorded playback fields after processing completes.

---

### [Create Room](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/create-room)

> Create live rooms and retrieve broadcaster data with the current SDK room APIs.

Create a room before you publish it to a feed or connect a broadcaster. Room creation stores the room record and initial configuration; creating the feed post and connecting the media layer are separate steps.

  Flutter does not currently expose a public room broadcasting repository in the audited SDK source. Use TypeScript, iOS, Android, or a backend-supported flow when your product needs to create rooms.

## Parameters

| Parameter | Required | Platform support | Description |
| --- | --- | --- | --- |
| `title` | TypeScript and Android: yes. iOS initializer accepts `nil`; send a title for usable rooms. | TypeScript, iOS, Android | Room title shown in your product experience. |
| `description` | No | TypeScript, iOS, Android | Optional room description. |
| `thumbnailFileId` | No | TypeScript, iOS, Android | File ID for an uploaded thumbnail image. |
| `metadata` | No | TypeScript, iOS, Android | Custom key-value data stored with the room. |
| `liveChatEnabled` | No | TypeScript, iOS, Android | Whether the room should support live chat linkage. iOS defaults this to `true`. |
| `parentRoomId` | No | TypeScript, iOS, Android | Parent room ID for room hierarchy scenarios. |
| `participants` | No | iOS, Android | Initial participant user IDs. TypeScript room creation does not expose this field. |
| `type` | No | TypeScript, iOS | Room type such as `coHosts` / `.coHosts` or `directStreaming` / `.directStreaming`. Android creation does not expose a type argument. |

## Create a Room

Create a room with the title and configuration your product needs before publishing it or connecting a broadcaster.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const { data: room } = await RoomRepository.createRoom({
  title: "Product Launch Event",
  description: "Join us for the unveiling of our latest features",
  liveChatEnabled: true,
  type: "coHosts",
  metadata: {
    category: "education",
  },
});

showSuccessMessage(room.roomId);
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.google.gson.JsonObject

val metadata = JsonObject().apply {
    addProperty("category", "education")
}

AmityVideoClient.newRoomRepository()
    .createRoom(
        title = "Product Launch Event",
        description = "Join us for the unveiling of our latest features",
        metadata = metadata,
        liveChatEnabled = true,
        participants = listOf(userId)
    )
    .subscribe(
        { room -> showSuccessMessage(room.getRoomId()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let options = AmityRoomCreateOptions(
    title: "Product Launch Event",
    description: "Join us for the unveiling of our latest features",
    metadata: ["category": "education"],
    liveChatEnabled: true,
    participants: [userId],
    type: .coHosts
)

let room = try await AmityRoomRepository().createRoom(with: options)
showSuccessMessage(room.roomId)
```


## Create with Thumbnail or Parent Room

Use `thumbnailFileId` after uploading an image through the file APIs. Use `parentRoomId` only when your product intentionally creates a room hierarchy.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const { data: childRoom } = await RoomRepository.createRoom({
  title: "Regional Breakout",
  thumbnailFileId: imageFileId,
  parentRoomId: roomId,
  liveChatEnabled: true,
});

showSuccessMessage(childRoom.roomId);
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

AmityVideoClient.newRoomRepository()
    .createRoom(
        title = "Regional Breakout",
        thumbnailFileId = imageFileId,
        parentRoomId = roomId,
        liveChatEnabled = true
    )
    .subscribe(
        { room -> showSuccessMessage(room.getRoomId()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let options = AmityRoomCreateOptions(
    title: "Regional Breakout",
    thumbnailFileId: imageFileId,
    liveChatEnabled: true,
    parentRoomId: roomId
)

let childRoom = try await AmityRoomRepository().createRoom(with: options)
showSuccessMessage(childRoom.roomId)
```


## Get Broadcaster Data

After creating the room, request broadcaster credentials before connecting the media layer. TypeScript and Android expose broadcaster-data APIs. iOS exposes room token generation.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const broadcasterData = await RoomRepository.getBroadcasterData(roomId);

if (broadcasterData.coHostUrl && broadcasterData.coHostToken) {
  showSuccessMessage(broadcasterData.coHostUrl);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomBroadcastData

AmityVideoClient.newRoomRepository()
    .getBroadcasterData(roomId)
    .subscribe(
        { broadcasterData ->
            when (broadcasterData) {
                is AmityRoomBroadcastData.CoHosts -> {
                    showSuccessMessage(broadcasterData.getCoHostUrl())
                }
                is AmityRoomBroadcastData.DirectStreaming -> {
                    showSuccessMessage(broadcasterData.getDirectStreamUrl())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let broadcasterData = try await AmityRoomRepository()
    .generateRoomToken(withId: roomId)

let coHostUrl = broadcasterData?["coHostUrl"] as? String
let coHostToken = broadcasterData?["coHostToken"] as? String

if let coHostUrl, let coHostToken {
    showSuccessMessage("\(coHostUrl):\(coHostToken)")
}
```


  Use the returned broadcaster data with your media stack, such as a LiveKit client. The social.plus SDK returns room and credential data; it does not publish camera or microphone tracks for your SDK integration.

## Publish the Room

To show the room in a user or community feed, create a room post from the room ID.

    Create a feed post that references an existing room.
    Review room fields, statuses, participants, and playback metadata.

## Platform Notes

- TypeScript exposes `RoomRepository.createRoom()` and returns `Amity.Cached<Amity.Room>`.
- iOS creates rooms with `AmityRoomCreateOptions` and `AmityRoomRepository().createRoom(with:)`.
- Android creates rooms with `AmityVideoClient.newRoomRepository().createRoom(...)`.
- Flutter does not currently expose a public room creation API in the audited SDK source.

## Related Topics

    Observe, query, update, stop, and delete rooms after creation.
    Connect the broadcaster after retrieving credentials.

---

### [Start Broadcasting](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/start-broadcasting)

> Fetch room broadcaster credentials, hand them to your media stack, observe lifecycle changes, and stop the room.

Starting a broadcast has two parts: the social.plus SDK returns room broadcaster credentials, and your app-owned media stack uses those credentials to connect and publish audio/video. Keep those responsibilities separate in your implementation and docs.

  This page covers SDK room broadcasting APIs. Camera, microphone, LiveKit client setup, permissions, and media publishing UI are app-owned concerns after the SDK returns broadcaster data.

## Platform Surface

| Platform | Get broadcaster data | Observe lifecycle | Stop broadcast | Notes |
| --- | --- | --- | --- | --- |
| TypeScript | `RoomRepository.getBroadcasterData(roomId)` | `RoomRepository.onRoomStartBroadcasting(...)`, `onRoomEndBroadcasting(...)`, or `getRoom(...)` | `RoomRepository.stopRoom(roomId)` | `Amity.BroadcasterData` can include `coHostToken`, `coHostUrl`, and `directStreamUrl`. |
| iOS | `AmityRoomRepository().generateRoomToken(withId:)` | `AmityRoomRepository().getRoom(withId:)` live object | `AmityRoomRepository().stopRoom(withId:)` | Token response is a dictionary from `/api/v1/rooms/{roomId}/token`; read known keys defensively. |
| Android | `AmityVideoClient.newRoomRepository().getBroadcasterData(roomId)` | `getRoom(roomId)` plus room topic subscription when real-time updates are needed | `stopRoom(roomId)` | Returns `AmityRoomBroadcastData.CoHosts` or `AmityRoomBroadcastData.DirectStreaming`. |
| Flutter | No current public room broadcaster API found in this audit | Not available | Not available | The Flutter SDK source exposes older stream read APIs, not the room broadcasting repository. |

## Parameters

| Concept | Platforms | TypeScript | iOS | Android | Notes |
| --- | --- | --- | --- | --- | --- |
| Fetch credentials | TypeScript, iOS, Android | `getBroadcasterData(roomId)` | `generateRoomToken(withId:)` | `getBroadcasterData(roomId)` | Requires an existing room ID. |
| Co-host URL | TypeScript, iOS, Android | `coHostUrl?: string` | `tokenPayload["coHostUrl"]` | `AmityRoomBroadcastData.CoHosts.getCoHostUrl()` | Use as the media connection URL for co-host rooms. |
| Co-host token | TypeScript, iOS, Android | `coHostToken?: string` | `tokenPayload["coHostToken"]` | `AmityRoomBroadcastData.CoHosts.getCoHostToken()` | Use as the media access token for co-host rooms. |
| Direct stream URL | TypeScript, iOS, Android | `directStreamUrl?: string` | `tokenPayload["directStreamUrl"]` | `AmityRoomBroadcastData.DirectStreaming.getDirectStreamUrl()` | Use only for direct-streaming publisher flows. |
| Flutter room broadcasting | Flutter | Not applicable | Not applicable | Not applicable | No current public Flutter room broadcaster API found in this audit. |

### Lifecycle Parameters

| Concept | Platforms | TypeScript | iOS | Android |
| --- | --- | --- | --- | --- |
| Start event | TypeScript, iOS, Android | `onRoomStartBroadcasting(callback)` | Observe `AmityRoom.status` via `getRoom(withId:)` | Observe `getRoom(roomId)` and subscribe to `AmityRoomEvents.STREAMER` when needed |
| End event | TypeScript, iOS, Android | `onRoomEndBroadcasting(callback)` | Observe `AmityRoom.status` via `getRoom(withId:)` | Observe `getRoom(roomId)` and subscribe to `AmityRoomEvents.STREAMER` when needed |
| Stop room | TypeScript, iOS, Android | `stopRoom(roomId)` | `stopRoom(withId:)` | `stopRoom(roomId)` |
| Cleanup | TypeScript, iOS, Android | Call returned `Amity.Unsubscriber` functions | Retain and release the `AmityNotificationToken` with the screen lifecycle | Dispose Rx subscriptions and unsubscribe room topics when no longer needed |

## Get Broadcaster Data

Call this after the room exists and before connecting your app-owned media client. Co-host rooms use `coHostUrl` and `coHostToken`; direct-streaming rooms use `directStreamUrl`.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

async function getBroadcastCredentials(roomId: string) {
  const credentials = await RoomRepository.getBroadcasterData(roomId);

  if (credentials.coHostUrl && credentials.coHostToken) {
    return {
      mode: "coHosts" as const,
      url: credentials.coHostUrl,
      token: credentials.coHostToken,
    };
  }

  if (credentials.directStreamUrl) {
    return {
      mode: "directStreaming" as const,
      directStreamUrl: credentials.directStreamUrl,
    };
  }

  throw new Error("No broadcaster credentials returned for this room.");
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomBroadcastData

val disposable = AmityVideoClient.newRoomRepository()
    .getBroadcasterData(roomId)
    .subscribe(
        { broadcastData ->
            when (broadcastData) {
                is AmityRoomBroadcastData.CoHosts -> {
                    showSuccessMessage(broadcastData.getCoHostUrl())
                    showSuccessMessage(broadcastData.getCoHostToken())
                }
                is AmityRoomBroadcastData.DirectStreaming -> {
                    showSuccessMessage(broadcastData.getDirectStreamUrl())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let tokenPayload = try await AmityRoomRepository()
    .generateRoomToken(withId: roomId)

if let coHostUrl = tokenPayload?["coHostUrl"] as? String,
   let coHostToken = tokenPayload?["coHostToken"] as? String {
    showSuccessMessage(coHostUrl)
    showSuccessMessage(coHostToken)
} else if let directStreamUrl = tokenPayload?["directStreamUrl"] as? String {
    showSuccessMessage(directStreamUrl)
}
```


## Hand Credentials to Your Media Client

The SDK does not publish camera or microphone tracks. Use the returned URL/token with your media client, then let that client own connection, preview, mute, retry, and device-selection behavior.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

type ExternalMediaClient = {
  connect: (url: string, token: string) => Promise<void>;
  publishCamera: () => Promise<void>;
};

async function startCoHostBroadcast(
  roomId: string,
  mediaClient: ExternalMediaClient,
) {
  const data = await RoomRepository.getBroadcasterData(roomId);

  if (!data.coHostUrl || !data.coHostToken) {
    throw new Error("This room did not return co-host broadcaster credentials.");
  }

  await mediaClient.connect(data.coHostUrl, data.coHostToken);
  await mediaClient.publishCamera();
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomBroadcastData
import io.reactivex.rxjava3.core.Completable

fun connectExternalMedia(url: String, token: String): Completable {
    showSuccessMessage(url)
    showSuccessMessage(token)
    return Completable.complete()
}

fun publishExternalCamera(): Completable = Completable.complete()

val disposable = AmityVideoClient.newRoomRepository()
    .getBroadcasterData(roomId)
    .flatMapCompletable { broadcastData ->
        when (broadcastData) {
            is AmityRoomBroadcastData.CoHosts -> {
                connectExternalMedia(
                    url = broadcastData.getCoHostUrl(),
                    token = broadcastData.getCoHostToken()
                ).andThen(publishExternalCamera())
            }
            is AmityRoomBroadcastData.DirectStreaming -> {
                Completable.error(
                    IllegalStateException("Use directStreamUrl with your RTMP publisher.")
                )
            }
        }
    }
    .subscribe(
        { showSuccessMessage(roomId) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
func connectExternalMedia(url: String, token: String) async throws {
    showSuccessMessage(url)
    showSuccessMessage(token)
}

func publishExternalCamera() async throws {
    showSuccessMessage("camera")
}

let tokenPayload = try await AmityRoomRepository()
    .generateRoomToken(withId: roomId)

guard let coHostUrl = tokenPayload?["coHostUrl"] as? String,
      let coHostToken = tokenPayload?["coHostToken"] as? String else {
    throw NSError(domain: "Broadcast", code: 0)
}

try await connectExternalMedia(url: coHostUrl, token: coHostToken)
try await publishExternalCamera()
```


## Observe Broadcast Lifecycle

Use lifecycle updates to keep host UI, viewer entry points, and moderation tools aligned with the room status.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeBroadcastLifecycle(roomId: string): Amity.Unsubscriber {
  const stopStarted = RoomRepository.onRoomStartBroadcasting(room => {
    if (room.roomId === roomId) {
      showSuccessMessage(room.status);
    }
  });

  const stopEnded = RoomRepository.onRoomEndBroadcasting(room => {
    if (room.roomId === roomId) {
      showSuccessMessage(room.status);
    }
  });

  return () => {
    stopStarted();
    stopEnded();
  };
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.core.events.AmityRoomEvents

val roomRepository = AmityVideoClient.newRoomRepository()

val roomDisposable = roomRepository
    .getRoom(roomId)
    .subscribe(
        { room -> showSuccessMessage(room.getStatus()) },
        { error -> handleGeneralError(error) }
    )

val topicDisposable = roomRepository
    .getRoom(roomId)
    .firstOrError()
    .flatMapCompletable { room ->
        room.subscription(AmityRoomEvents.STREAMER).subscribeTopic()
    }
    .subscribe(
        { showSuccessMessage(roomId) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    if let room = liveObject.snapshot {
        showSuccessMessage(room.status.rawValue)
    }
}

showSuccessMessage(roomObservationToken != nil)
```


## Stop the Broadcast

Stop the room when the host ends the session. Disconnect your media client separately, then call the SDK stop API so social.plus room state and viewer surfaces can move out of the live state.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

async function stopBroadcast(roomId: string) {
  const { data: stoppedRoom } = await RoomRepository.stopRoom(roomId);
  showSuccessMessage(stoppedRoom.status);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val disposable = AmityVideoClient.newRoomRepository()
    .stopRoom(roomId)
    .subscribe(
        { showSuccessMessage(roomId) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let stoppedRoom = try await AmityRoomRepository()
    .stopRoom(withId: roomId)

showSuccessMessage(stoppedRoom.status.rawValue)
```


  Stopping a room ends the current broadcast session. Do not build a "restart the same room" flow unless your product and backend contract explicitly support it.

## Media Boundary

| Area | Owned by social.plus SDK | Owned by your app/media stack |
| --- | --- | --- |
| Room record | Create, observe, update, stop, delete | Product routing and host controls |
| Credentials | Return room broadcaster fields | Store only in memory and hand to the media client |
| Publishing | Not handled by social.plus SDK room APIs | Camera, microphone, preview, mute, reconnect, and permissions |
| Viewer state | Room status, live playback fields, recorded metadata | Player UI and playback SDK behavior |

## Related Topics

    Create the room before fetching broadcaster credentials.
    Invite, observe, and manage co-hosts before or during the broadcast.
    Show viewers how to watch active room broadcasts.

---

### [Live Room Viewing](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/live-viewing)

> Discover room posts, observe room playback state, and hand SDK playback URLs to your player.

Live room viewing starts from a room ID or a room post. The social.plus SDK owns room discovery, room status, live playback URLs, recorded playback metadata, and live room post collections. Your app owns the actual video player, buffering UI, autoplay policy, and platform playback SDK.

  This page covers SDK room viewing data. AVPlayer, ExoPlayer, HLS.js, browser autoplay handling, DRM, and player UI are app-owned concerns after the SDK returns a playback URL.

## Platform Surface

| Platform | Find room posts | Observe room | Live playback field | Recorded playback field |
| --- | --- | --- | --- | --- |
| TypeScript | `PostRepository.getLiveRoomPosts(...)`, `getCommunityLiveRoomPosts(...)` | `RoomRepository.getRoom(roomId, callback)` | `room.livePlaybackUrl` | `room.recordedPlaybackInfos[]` |
| iOS | `AmityPostRepository().getLiveRoomPosts()`, `getCommunityLiveRoomPosts(withIds:)` | `AmityRoomRepository().getRoom(withId:)` | `room.livePlaybackUrl` | `room.recordedData[]` |
| Android | `AmityPostRepository.getLiveRoomPosts()`, `getCommunityLiveRoomPosts(...)` | `AmityVideoClient.newRoomRepository().getRoom(roomId)` | `room.getLivePlaybackUrl()` | `room.getRecordedPlaybackInfos()` |
| Flutter | No current public room viewing API found in this audit | Not available | Not available | Not available |

## Parameters

| Concept | Platforms | TypeScript | iOS | Android |
| --- | --- | --- | --- | --- |
| Live room post collection | TypeScript, iOS, Android | `getLiveRoomPosts(callback)` | `getLiveRoomPosts()` | `getLiveRoomPosts()` |
| Community live room posts | TypeScript, iOS, Android | `getCommunityLiveRoomPosts({ communityIds })` | `getCommunityLiveRoomPosts(withIds:)` | `getCommunityLiveRoomPosts(communityIds)` |
| Room ID in post data | TypeScript, iOS, Android | `post.data.roomId` when `dataType === "room"` | `post.data?["roomId"]` when `dataType == "room"` | `AmityPost.Data.ROOM.getRoomId()` |
| Observe room | TypeScript, iOS, Android | `RoomRepository.getRoom(roomId, callback)` | `AmityRoomRepository().getRoom(withId:)` | `AmityVideoClient.newRoomRepository().getRoom(roomId)` |
| Live URL | TypeScript, iOS, Android | `room.livePlaybackUrl` | `room.livePlaybackUrl` | `room.getLivePlaybackUrl()` |
| Recorded URL | TypeScript, iOS, Android | `room.recordedPlaybackInfos[].url` | `room.recordedData[].playbackUrl` | `room.getRecordedPlaybackInfos()[].url` |

## Find Live Room Posts

Use live room post collections when your product shows a live shelf or a community-specific live section. Extract the `roomId` from room post data, then observe the room itself for playback state.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

function observeCommunityLiveRoomPosts(communityId: string): Amity.Unsubscriber {
  return PostRepository.getCommunityLiveRoomPosts(
    { communityIds: [communityId] },
    snapshot => {
      if (snapshot.error) {
        handleError(snapshot.error);
        return;
      }

      snapshot.data.forEach(post => {
        const roomData = post.data as { roomId?: string } | undefined;

        if (post.dataType === "room" && roomData?.roomId) {
          showSuccessMessage(roomData.roomId);
        }
      });
    },
  );
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.social.AmitySocialClient
import com.amity.socialcloud.sdk.model.social.post.AmityPost

val disposable = AmitySocialClient.newPostRepository()
    .getCommunityLiveRoomPosts(listOf(communityId))
    .subscribe(
        { posts ->
            posts.forEach { post ->
                val roomData = post.getData()

                if (roomData is AmityPost.Data.ROOM) {
                    showSuccessMessage(roomData.getRoomId())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var liveRoomPostsToken: AmityNotificationToken?
let liveRoomPosts = AmityPostRepository()
    .getCommunityLiveRoomPosts(withIds: [communityId])

liveRoomPostsToken = liveRoomPosts.observe { collection, error in
    if let error {
        handleGeneralError(error)
        return
    }

    collection.snapshots.forEach { post in
        if post.dataType == "room",
           let roomId = post.data?["roomId"] as? String {
            showSuccessMessage(roomId)
        }
    }
}
```


## Observe Room Playback State

Observe the room record while the viewing screen is open. A live object update can move the UI from waiting, to live playback, to ended, and later to recorded playback.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeRoomPlayback(roomId: string): Amity.Unsubscriber {
  return RoomRepository.getRoom(roomId, snapshot => {
    if (snapshot.error) {
      handleError(snapshot.error);
      return;
    }

    const room = snapshot.data;

    if (room.status === "live" && room.livePlaybackUrl) {
      showSuccessMessage(room.livePlaybackUrl);
      return;
    }

    if (room.status === "recorded") {
      showSuccessMessage(room.recordedPlaybackInfos[0]?.url);
      return;
    }

    showSuccessMessage(room.status);
  });
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

val disposable = AmityVideoClient.newRoomRepository()
    .getRoom(roomId)
    .subscribe(
        { room ->
            when (room.getStatus()) {
                AmityRoomStatus.LIVE -> {
                    room.getLivePlaybackUrl()?.let { showSuccessMessage(it) }
                }
                AmityRoomStatus.RECORDED -> {
                    room.getRecordedPlaybackInfos()
                        .firstOrNull()
                        ?.url
                        ?.let { showSuccessMessage(it) }
                }
                else -> {
                    showSuccessMessage(room.getStatus())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    guard let room = liveObject.snapshot else { return }

    switch room.status {
    case .live, .waitingReconnect:
        showSuccessMessage(room.livePlaybackUrl)
    case .recorded:
        showSuccessMessage(room.recordedData.first?.playbackUrl)
    default:
        showSuccessMessage(room.status.rawValue)
    }
}
```


## Choose a Playback Source

Keep playback source selection small and deterministic. Pass the selected URL to your own player layer only when the SDK room state has a playable source.


```typescript TypeScript
function playbackSourceForRoom(room: Amity.Room): string | undefined {
  if (room.status === "live" || room.status === "waitingReconnect") {
    return room.livePlaybackUrl;
  }

  if (room.status === "recorded") {
    return room.recordedPlaybackInfos[0]?.url;
  }

  return undefined;
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

fun playbackSourceForRoom(room: AmityRoom): String? {
    return when (room.getStatus()) {
        AmityRoomStatus.LIVE,
        AmityRoomStatus.WAITING_RECONNECT -> room.getLivePlaybackUrl()
        AmityRoomStatus.RECORDED -> room.getRecordedPlaybackInfos()
            .firstOrNull()
            ?.url
        else -> null
    }
}
```

```swift iOS
func playbackSource(for room: AmityRoom) -> String? {
    switch room.status {
    case .live, .waitingReconnect:
        return room.livePlaybackUrl
    case .recorded:
        return room.recordedData.first?.playbackUrl
    default:
        return nil
    }
}
```


### Thumbnail and Resolution

Alongside the playback URL, the room exposes a thumbnail and the stream's dimensions — useful for a poster image before playback starts and for sizing the player without waiting for the first frame.

| Field | TypeScript | iOS | Android | Available |
| --- | --- | --- | --- | --- |
| Live thumbnail | `room.liveThumbnailUrl` | `room.liveThumbnailUrl` | `room.getLiveThumbnailUrl()` | Live or reconnecting sessions, when generated |
| Live resolution | `room.liveResolution` | `room.liveResolution` | `room.getLiveResolution()` | Live or reconnecting sessions, when available |
| Recorded resolution | `room.recordedResolution` | `room.recordedResolution` | `room.getRecordedResolution()` | After the recording is available |

Resolution carries the stream's aspect ratio, width, and height. These fields can be absent early in a session, so treat them as optional and fall back to your own placeholder. See [Rooms Overview](./rooms-overview) for the full room field reference.

## Status Handling

| Status | Viewer behavior |
| --- | --- |
| `idle` | Show a waiting or scheduled state. |
| `live` | Use the live playback URL when present. |
| `waitingReconnect` | Keep the player UI available, but show reconnecting state if playback stalls. |
| `ended` | Stop live playback and show a processing state while recorded playback is not ready. |
| `recorded` | Use recorded playback metadata. |
| `error` | Show a recoverable error state and let the user retry or leave. |

  If a room is live but the SDK returns no live playback URL, do not invent a fallback URL. Treat it as unavailable for the current viewer and show a product-specific blocked, unavailable, or retry state.

## Player Boundary

| Area | Owned by social.plus SDK | Owned by your app/player |
| --- | --- | --- |
| Discovery | Live room post collections and room IDs | Placement, ranking, and empty states |
| State | Room status and live object updates | Player state machine and user-facing copy |
| Playback source | `livePlaybackUrl` and recorded playback metadata | AVPlayer, ExoPlayer, HLS.js, web video, buffering, and errors |
| Cleanup | Observer unsubscribe, token release, Rx disposal | Player teardown and audio/video session cleanup |

## Related Topics

    Fetch broadcaster credentials and start the host-side media session.
    Observe, stop, update, or delete room records.
    Handle recorded playback after a live room ends.

---

### [Live Viewer Count Config](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/viewer-count-config)

> Read the network-level configuration that governs whether viewers see the live viewer count on a livestream.

`AmityClient.getLiveViewerCountConfig()` returns the network-level configuration that governs whether the live viewer count is shown to viewers on a livestream. Admins pick one of three modes (always show, hide entirely, or show above a minimum) at the network level; the SDK reads it as a one-shot cold read and the UIKit's viewer-count element applies the rule.

  This page covers the SDK read API. The write path is admin-only and served by the Console — the SDK does not update this setting. Console UI and permissions are documented separately in [Network Settings](/analytics-and-moderation/social+-apis-and-services/network-settings).

## Platform Surface

| Platform | Entry point | Return type | Signature |
| --- | --- | --- | --- |
| TypeScript | `client.getLiveViewerCountConfig()` | `Promise<AmityLiveViewerCountConfig>` | Zero-argument, async |
| iOS | `client.getLiveViewerCountConfig()` | `AmityLiveViewerCountConfig` | `async throws` on `AmityClient` |
| Android | `AmityCoreClient.getLiveViewerCountConfig()` | `Single<AmityLiveViewerCountConfig>` | Zero-argument, RxJava |

## Modes

Three modes are available. They apply to viewers only — **hosts and co-hosts always see the actual count regardless of mode**.

| Mode | Threshold applied | Viewer behavior |
| --- | --- | --- |
| `alwaysShow` | No | Count is always visible. Default for never-configured networks. |
| `hideEntirely` | No | Viewers never see the count. Hosts and co-hosts still see it. |
| `showAboveMinimum` | Yes (inclusive) | Viewers see the count only when `count >= threshold`. |

## Config Model

| Field | Type | Description |
| --- | --- | --- |
| `mode` | `AmityLiveViewerCountMode` | Selected display mode. |
| `threshold` | `Int` | Positive integer in `[1, 1000]`. **Always present**, default `50`. Applied only under `showAboveMinimum`. |

## Read the Config

Read the config at each livestream mount. The API is a cold read — there is no observable and no real-time channel. Admin changes made mid-stream do not propagate to already-connected viewers; they take effect only on a subsequent mount (leave and rejoin).


```typescript TypeScript
import { Client, AmityLiveViewerCountMode } from "@amityco/ts-sdk";

async function shouldShowViewerCount(
  client: Amity.Client,
  currentCount: number,
  isHostOrCoHost: boolean,
): Promise<boolean> {
  if (isHostOrCoHost) {
    return true;
  }

  const config = await client.getLiveViewerCountConfig();

  switch (config.mode) {
    case AmityLiveViewerCountMode.ALWAYS_SHOW:
      return true;
    case AmityLiveViewerCountMode.HIDE_ENTIRELY:
      return false;
    case AmityLiveViewerCountMode.SHOW_ABOVE_MINIMUM:
      return currentCount >= config.threshold;
  }
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.core.AmityCoreClient
import com.amity.socialcloud.sdk.model.core.settings.AmityLiveViewerCountMode

fun observeShouldShowCount(
    currentCount: Int,
    isHostOrCoHost: Boolean,
) {
    if (isHostOrCoHost) {
        showSuccessMessage(true)
        return
    }

    AmityCoreClient.getLiveViewerCountConfig()
        .subscribe(
            { config ->
                val visible = when (config.mode) {
                    AmityLiveViewerCountMode.ALWAYS_SHOW -> true
                    AmityLiveViewerCountMode.HIDE_ENTIRELY -> false
                    AmityLiveViewerCountMode.SHOW_ABOVE_MINIMUM ->
                        currentCount >= config.threshold
                }
                showSuccessMessage(visible)
            },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
import AmitySDK

func shouldShowViewerCount(
    client: AmityClient,
    currentCount: Int,
    isHostOrCoHost: Bool
) async throws -> Bool {
    if isHostOrCoHost {
        return true
    }

    let config = try await client.getLiveViewerCountConfig()

    switch config.mode {
    case .alwaysShow:
        return true
    case .hideEntirely:
        return false
    case .showAboveMinimum:
        return currentCount >= config.threshold
    }
}
```


## Visibility Rule

The rule is evaluated in a fixed order — the first match wins.

1. **Role check first.** If the current user is a **host** or **co-host**, show the actual count. All mode-based hiding applies to viewers only.
2. **Mode branch** (viewer role):
   - `alwaysShow` — show.
   - `hideEntirely` — hide.
   - `showAboveMinimum` — show iff `count >= threshold` (inclusive).

The comparison is inclusive: at exactly `count == threshold`, the count is shown.

## Propagation Model

The SDK reads the config once when the viewer joins a stream. Changes made by an admin while the viewer is already watching **do not** update the visibility state — the viewer keeps the rule that applied at join. To pick up a new config, the viewer must leave and rejoin the stream.

Within a single mount, the visibility state still reacts to two things:

- **Count ticks.** Under `showAboveMinimum`, if the viewer count crosses the threshold naturally, the count appears or disappears without a rejoin.
- **Role changes.** A viewer promoted to co-host mid-stream immediately sees the actual count — no rejoin needed.

## Threshold Constraints

| Constraint | Value |
| --- | --- |
| Type | Positive integer |
| Minimum | `1` |
| Default | `50` |
| Maximum | `1000` |
| Comparison | Inclusive (`count >= threshold`) |

  The Console clamps admin-entered values on save: values above `1000` are clamped to `1000`; values below `1` (or empty) reset to `1`. Zero is explicitly rejected — use `alwaysShow` for "always visible" instead.

## Defaults

Never-configured networks read as `{ mode: alwaysShow, threshold: 50 }` — the backend merges defaults at read time, so no client-side fallback is required for absent fields. Every read after an admin change returns the current value; no client-side cache is required.

## Error Handling

On any read error or malformed config, **fail open** — behave as `alwaysShow` (the UIKit `LiveViewerCountElement` does this automatically), so today's behavior is never silently regressed.

  Never treat a config error as a reason to hide the count. If the admin never selected `hideEntirely`, viewers should still see it. Fail open, always.

## UIKit Integration

If you use UIKit, no wiring is needed — the [Livestream Player Page](/uikit/components/social/livestream) reads this config automatically through the built-in `LiveViewerCountElement`. Use this API only when you build a custom viewer surface and need to enforce the same visibility rule yourself.

## Related Topics

    Observe room playback state and hand playback URLs to your player.
    Manage co-host participants — co-hosts are exempt from the visibility rule.
    Ready-to-use livestream components that apply the visibility rule automatically.

---

### [Manage Rooms](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/manage-rooms)

> Observe, query, update, stop, and delete live rooms with current SDK room APIs.

Manage rooms after creation by observing a single room, querying room lists, updating room metadata, stopping a live session, or deleting a room record.

  This page covers SDK room management APIs. Media publishing, LiveKit connection handling, and player UI are app-owned concerns.

## Platform Surface

| Platform | Single room | Room list | Mutations | Notes |
| --- | --- | --- | --- | --- |
| TypeScript | `RoomRepository.getRoom(roomId, callback)` | `RoomRepository.getRooms(params, callback)` | `updateRoom()`, `stopRoom()`, `deleteRoom()` | Live callbacks return an unsubscribe function. Room list pagination uses `hasNextPage` and `onNextPage`. |
| iOS | `AmityRoomRepository().getRoom(withId:)` | `AmityRoomRepository().getRooms(with:)` | `updateRoom(withId:options:)`, `stopRoom(withId:)`, `deleteRoom(withId:)` | Retain the returned `AmityNotificationToken` while observing. |
| Android | `AmityVideoClient.newRoomRepository().getRoom(roomId)` | `AmityVideoClient.newRoomRepository().getRooms().build().query()` | `updateRoom()`, `stopRoom()`, `deleteRoom()` | Single rooms are `Flowable<AmityRoom>`; room lists are `Flowable<PagingData<AmityRoom>>`. |
| Flutter | No current public room repository found in this audit | Not available | Not available | The Flutter SDK source exposes older stream APIs, not the room broadcasting repository. |

## Parameters

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Status filter | `statuses?: Amity.RoomStatus[]` | `statuses: [AmityRoomStatus]?` | `setStatuses(Array<AmityRoomStatus>)` |
| Room type filter | `type?: Amity.RoomType` | `type: AmityRoomType?` | `setTypes(Array<AmityRoomType>)` |
| Deleted rooms | `includeDeleted?: boolean` | `isDeleted: Bool` | `setIsDeleted(Boolean?)` |
| Sort order | `sortBy?: "firstCreated"` or `"lastCreated"` | `sortBy: AmityRoomSortOption` | `setSortBy(AmityRoomSortOption?)` |
| Page size | `limit?: number` | Not exposed on `AmityRoomQueryOptions` | Paging 3 controls consumption after `PagingData` emission |

### Mutation Parameters

| Operation | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Update | `updateRoom(roomId, bundle)` | `updateRoom(withId:options:)` | `updateRoom(roomId, ...)` |
| Stop | `stopRoom(roomId)` | `stopRoom(withId:)` | `stopRoom(roomId)` |
| Delete | `deleteRoom(roomId)` | `deleteRoom(withId:)` | `deleteRoom(roomId)` |

| Update field | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Title | `title` | `title` | `title` |
| Description | `description` | `description` | `description` |
| Thumbnail | `thumbnailFileId` | `thumbnailFileId` | `thumbnailFileId` |
| Metadata | `metadata` | `metadata` | `metadata` |
| Live chat flag | `liveChatEnabled` | `channelEnabled` | `liveChatEnabled` |
| Parent room | `parentRoomId` | Not exposed by update options | Not exposed by update API |

## Get a Room

Use the single-room API when a screen needs live updates for one room.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeRoom(roomId: string): Amity.Unsubscriber {
  return RoomRepository.getRoom(roomId, snapshot => {
    if (snapshot.error) {
      handleError(snapshot.error);
      return;
    }

    showSuccessMessage(snapshot.data.status);
  });
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val disposable = AmityVideoClient.newRoomRepository()
    .getRoom(roomId)
    .subscribe(
        { room -> showSuccessMessage(room.getStatus()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    if let room = liveObject.snapshot {
        showSuccessMessage(room.status.rawValue)
    }
}
```


## Query Rooms

Use the room-list API for discovery, dashboards, moderation queues, or live-room shelves.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeLiveRooms(): Amity.Unsubscriber {
  return RoomRepository.getRooms(
    {
      statuses: ["live"],
      type: "coHosts",
      sortBy: "lastCreated",
      includeDeleted: false,
      limit: 20,
    },
    snapshot => {
      if (snapshot.error) {
        handleError(snapshot.error);
        return;
      }

      renderResults(snapshot.data);

      if (snapshot.hasNextPage) {
        snapshot.onNextPage?.();
      }
    },
  );
}
```

```kotlin Android
import androidx.paging.PagingData
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import com.amity.socialcloud.sdk.model.video.room.AmityRoomSortOption
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus
import com.amity.socialcloud.sdk.model.video.room.AmityRoomType

val disposable = AmityVideoClient.newRoomRepository()
    .getRooms()
    .setStatuses(arrayOf(AmityRoomStatus.LIVE))
    .setTypes(arrayOf(AmityRoomType.CO_HOSTS))
    .setIsDeleted(false)
    .setSortBy(AmityRoomSortOption.LastCreated)
    .build()
    .query()
    .subscribe(
        { pagingData: PagingData<AmityRoom> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomCollectionToken: AmityNotificationToken?
let options = AmityRoomQueryOptions(
    statuses: [.live],
    type: .coHosts,
    isDeleted: false,
    sortBy: .lastCreated
)

let rooms = AmityRoomRepository().getRooms(with: options)

roomCollectionToken = rooms.observe { collection, error in
    if let error {
        handleGeneralError(error)
        return
    }

    showSuccessMessage(collection.snapshots.map { $0.roomId })

    if collection.hasNext {
        collection.nextPage()
    }
}
```


  TypeScript filters by a single `type` value. Android's builder accepts `setTypes(...)` because the Android query model supports an array of room types.

## Update a Room

Update room display fields and metadata. Participants, room type, and room identity are not update fields in these APIs.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const { data: updatedRoom } = await RoomRepository.updateRoom(roomId, {
  title: "Updated Room Title",
  description: "New description",
  thumbnailFileId: imageFileId,
  metadata: {
    category: "updated",
  },
  liveChatEnabled: true,
});

showSuccessMessage(updatedRoom.roomId);
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.google.gson.JsonObject

val metadata = JsonObject().apply {
    addProperty("category", "updated")
}

AmityVideoClient.newRoomRepository()
    .updateRoom(
        roomId = roomId,
        title = "Updated Room Title",
        description = "New description",
        thumbnailFileId = imageFileId,
        metadata = metadata,
        liveChatEnabled = true
    )
    .subscribe(
        { room -> showSuccessMessage(room.getRoomId()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let options = AmityRoomUpdateOptions(
    title: "Updated Room Title",
    description: "New description",
    thumbnailFileId: imageFileId,
    metadata: ["category": "updated"],
    channelEnabled: true
)

let room = try await AmityRoomRepository()
    .updateRoom(withId: roomId, options: options)

showSuccessMessage(room.roomId)
```


## Stop or Delete a Room

Stop a live session when broadcasting ends. Delete a room when your product flow should remove the room record.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const { data: stoppedRoom } = await RoomRepository.stopRoom(roomId);
showSuccessMessage(stoppedRoom.status);

await RoomRepository.deleteRoom(roomId);
showSuccessMessage(roomId);
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val roomRepository = AmityVideoClient.newRoomRepository()

roomRepository.stopRoom(roomId)
    .andThen(roomRepository.deleteRoom(roomId))
    .subscribe(
        { showSuccessMessage(roomId) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let roomRepository = AmityRoomRepository()

let stoppedRoom = try await roomRepository.stopRoom(withId: roomId)
showSuccessMessage(stoppedRoom.status.rawValue)

try await roomRepository.deleteRoom(withId: roomId)
showSuccessMessage(roomId)
```


  Stopping a room ends the current broadcast session. Do not document or build a "restart same room" flow unless your product and backend contract explicitly support it.

## Recorded Playback Boundary

Recorded playback is intentionally separate from room lifecycle management:

- TypeScript exposes `RoomRepository.getRecordedUrl(roomId)`.
- Android exposes `getRecordedUrls(roomId)`.
- iOS reads recorded playback data from `AmityRoom.recordedData`.

See [Recorded Playback](./recorded-playback) for playback-specific guidance.

## Related Topics

    Create a room before observing or mutating it.
    Review room fields, statuses, participants, and playback metadata.
    Manage co-host invitations, removal, and permissions.

---

### [Co-Host Management](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/co-host-management)

> Invite, observe, and manage room co-hosts with current SDK room and invitation APIs.

Co-host management is built on room invitations, room participant events, and room participant mutations. Use these APIs when a room host invites another user to broadcast, when an invited user accepts or rejects the invitation, and when the host manages a co-host during the room.

  This page covers SDK co-host control APIs. LiveKit connection, camera and microphone publishing, and broadcaster UI are app-owned concerns after the SDK returns broadcaster data.

## Platform Surface

| Platform | Invite | Respond | Events | Participant control |
| --- | --- | --- | --- | --- |
| TypeScript | `room.createInvitation(userId)` | `room.getInvitations()`, `invitation.accept()`, `invitation.reject()`, `InvitationRepository.cancelInvitation(invitationId)` | `InvitationRepository.getInvitations(...)`, `RoomRepository.onRoomParticipantJoined(...)`, `onRoomParticipantRemoved(...)`, and related room events | `RoomRepository.updateCohostPermission(...)`, `removeParticipant(...)`, `leaveRoom(...)` |
| iOS | `AmityRoom.createInvitation(_:)` | `room.getInvitation()`, `invitation.accept()`, `invitation.reject()`, `room.cancelInvitation(_:)` | `AmityRoomRepository().getCoHostEvent(roomId:)` | `updateCohostPermissions(...)`, `removeParticipant(withId:userId:)`, `leaveRoom(withId:)` |
| Android | `AmityRoom.createInvitation(userId)` | `room.getInvitation()`, `invitation.accept()`, `invitation.reject()`, `invitation.cancel()` | `AmityVideoClient.newRoomRepository().getCoHostEvent(roomId)` | `updateCohostPermission(...)`, `removeRoomParticipant(...)`, `leaveRoom(...)` |
| Flutter | No current public room repository found in this audit | Not available | Not available | Not available |

## Parameters

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Invite one user | `room.createInvitation(userId)` | `room.createInvitation(userId)` | `room.createInvitation(userId)` |
| Current user's pending room invitation | `room.getInvitations()` | `room.getInvitation()` | `room.getInvitation()` |
| Accept | `invitation.accept()` | `invitation.accept()` | `invitation.accept()` |
| Reject | `invitation.reject()` | `invitation.reject()` | `invitation.reject()` |
| Cancel | `InvitationRepository.cancelInvitation(invitationId)` | `room.cancelInvitation(invitationId)` | `invitation.cancel()` |
| Invitation type value | `livestreamCohostInvite` | `.livestreamCoHostInvite` | `AmityInvitationType.LIVESTREAM_COHOST` |
| Pending status | `"pending"` | `.pending` | `AmityInvitationStatus.PENDING` |

### Event and Participant Control

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Room invitation events | `InvitationRepository.getInvitations({ targetId, targetType: "room" }, callback)` | `AmityInvitationRepository().getInvitations(targetId:targetType:)` or `AmityRoomRepository().getCoHostEvent(roomId:)` | `AmityCoreClient.newInvitationRepository().getInvitations(targetId, AmityInvitation.TargetType.ROOM.value)` or `getCoHostEvent(roomId)` |
| Co-host joined | `RoomRepository.onRoomParticipantJoined(callback)` | `AmityCoHostEventType.coHostJoined` | `AmityCoHostEvent.CoHostJoined` |
| Co-host left | `RoomRepository.onRoomParticipantLeft(callback)` | `AmityCoHostEventType.coHostLeft` | `AmityCoHostEvent.CoHostLeft` |
| Co-host removed | `RoomRepository.onRoomParticipantRemoved(callback)` | `AmityCoHostEventType.coHostRemoved` | `AmityCoHostEvent.CoHostRemoved` |
| Stage left | `RoomRepository.onRoomParticipantStageLeft(callback)` | `AmityCoHostEventType.coHostStageLeft` | No separate public sealed event in audited model |
| Product-tag permission | `updateCohostPermission(roomId, cohostId, canManageProductTags)` | `updateCohostPermissions(roomId:cohostId:canManageProductTags:)` | `updateCohostPermission(roomId, cohostId, canManageProductTags)` |
| Remove participant | `removeParticipant(roomId, participantUserId)` | `removeParticipant(withId:userId:)` | `removeRoomParticipant(roomId, userId)` |
| Leave room | `leaveRoom(roomId)` | `leaveRoom(withId:)` | `leaveRoom(roomId)` |

## Invite a Co-Host

Invite one user at a time. The invitation type is the room co-host invitation type under the hood.


```typescript TypeScript
async function inviteCoHost(room: Amity.Room, cohostUserId: string) {
  await room.createInvitation(cohostUserId);
  showSuccessMessage(cohostUserId);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom

fun inviteCoHost(room: AmityRoom, cohostUserId: String) {
    room.createInvitation(cohostUserId)
        .subscribe(
            { showSuccessMessage(cohostUserId) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func inviteCoHost(room: AmityRoom, cohostUserId: String) async throws {
    try await room.createInvitation(cohostUserId)
    showSuccessMessage(cohostUserId)
}
```


## Respond or Cancel

Invited users accept or reject the pending invitation. Hosts cancel an invitation before it is accepted.


```typescript TypeScript
import { InvitationRepository } from "@amityco/ts-sdk";

async function acceptPendingRoomInvitation(room: Amity.Room) {
  const invitation = await room.getInvitations();

  if (invitation?.status === "pending") {
    await invitation.accept();
    showSuccessMessage(invitation.invitationId);
  }
}

async function cancelRoomInvitation(invitationId: string) {
  await InvitationRepository.cancelInvitation(invitationId);
  showSuccessMessage(invitationId);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.invitation.AmityInvitation
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import io.reactivex.rxjava3.core.Completable

fun acceptPendingRoomInvitation(room: AmityRoom) {
    room.getInvitation()
        .flatMapCompletable { invitations ->
            invitations.firstOrNull()?.accept() ?: Completable.complete()
        }
        .subscribe(
            { showSuccessMessage(room.getRoomId()) },
            { error -> handleGeneralError(error) }
        )
}

fun cancelRoomInvitation(invitation: AmityInvitation) {
    invitation.cancel()
        .subscribe(
            { showSuccessMessage(invitation.getInvitationId()) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func acceptPendingRoomInvitation(room: AmityRoom) async throws {
    guard let invitation = await room.getInvitation() else { return }

    if invitation.status == .pending {
        try await invitation.accept()
        showSuccessMessage(invitation.invitationId)
    }
}

func cancelRoomInvitation(room: AmityRoom, invitationId: String) async throws {
    try await room.cancelInvitation(invitationId)
    showSuccessMessage(invitationId)
}
```


## Observe Co-Host Events

Use invitation events for invite status and participant events for active room membership changes. Keep the returned unsubscribe, disposable, or cancellable for as long as the screen needs updates.


```typescript TypeScript
import { InvitationRepository, RoomRepository } from "@amityco/ts-sdk";

function observeCoHostEvents(roomId: string): Amity.Unsubscriber {
  const stopInvitationEvents = InvitationRepository.getInvitations(
    { targetId: roomId, targetType: "room" },
    invitations => {
      invitations.forEach(invitation => {
        showSuccessMessage(invitation.status);
      });
    },
  );

  const stopJoinedEvents = RoomRepository.onRoomParticipantJoined(event => {
    if (event.room.roomId === roomId) {
      showSuccessMessage(event.actorInternalId);
    }
  });

  const stopRemovedEvents = RoomRepository.onRoomParticipantRemoved(event => {
    if (event.room.roomId === roomId) {
      showSuccessMessage(event.actorInternalId);
    }
  });

  return () => {
    stopInvitationEvents();
    stopJoinedEvents();
    stopRemovedEvents();
  };
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.core.session.model.AmityCoHostEvent

val disposable = AmityVideoClient.newRoomRepository()
    .getCoHostEvent(roomId)
    .subscribe(
        { event ->
            when (event) {
                is AmityCoHostEvent.CoHostInvited -> {
                    showSuccessMessage(event.invitation.getStatus())
                }
                is AmityCoHostEvent.CoHostJoined -> {
                    showSuccessMessage(event.actorInternalId ?: "")
                }
                is AmityCoHostEvent.CoHostRemoved -> {
                    showSuccessMessage(event.actorInternalId ?: "")
                }
                else -> {
                    showSuccessMessage(event.roomId)
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let roomRepository = AmityRoomRepository()
var coHostEventCancellable: AnyCancellable?

coHostEventCancellable = roomRepository
    .getCoHostEvent(roomId: roomId)
    .sink { event in
        switch event.type {
        case .invitationInvited,
             .invitationAccepted,
             .invitationRejected,
             .invitationCancelled:
            showSuccessMessage(event.invitation?.status.rawValue)
        case .coHostJoined,
             .coHostLeft,
             .coHostRemoved,
             .coHostStageLeft:
            showSuccessMessage(event.actorInternalId)
        default:
            showSuccessMessage(event.room.roomId)
        }
    }

showSuccessMessage(coHostEventCancellable != nil)
```


## Manage Active Co-Hosts

Hosts can update whether a co-host can manage product tags, remove a co-host from the room, and co-hosts can leave the room.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

async function updateCoHostProductPermission(
  roomId: string,
  cohostUserId: string,
) {
  const { data: updatedRoom } = await RoomRepository.updateCohostPermission(
    roomId,
    cohostUserId,
    true,
  );

  showSuccessMessage(
    updatedRoom.participants.find(participant => participant.userId === cohostUserId)
      ?.canManageProductTags,
  );
}

async function removeCoHost(roomId: string, cohostUserId: string) {
  await RoomRepository.removeParticipant(roomId, cohostUserId);
  showSuccessMessage(cohostUserId);
}

async function leaveAsCoHost(roomId: string) {
  await RoomRepository.leaveRoom(roomId);
  showSuccessMessage(roomId);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val roomRepository = AmityVideoClient.newRoomRepository()

roomRepository.updateCohostPermission(
    roomId = roomId,
    cohostId = userId,
    canManageProductTags = true
)
    .andThen(roomRepository.removeRoomParticipant(roomId, userId))
    .andThen(roomRepository.leaveRoom(roomId))
    .subscribe(
        { showSuccessMessage(roomId) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let roomRepository = AmityRoomRepository()

let updatedRoom = try await roomRepository.updateCohostPermissions(
    roomId: roomId,
    cohostId: userId,
    canManageProductTags: true
)
showSuccessMessage(updatedRoom.roomId)

try await roomRepository.removeParticipant(withId: roomId, userId: userId)

_ = try await roomRepository.leaveRoom(withId: roomId)
showSuccessMessage(roomId)
```


  TypeScript exposes room participant events as global room event subscribers, so filter by `event.room.roomId` when a screen only cares about one room. Android and iOS expose room-filtered co-host event streams from the room repository.

## Broadcaster Data Boundary

Accepting a co-host invitation does not connect the app to LiveKit. After a user is ready to broadcast, request broadcaster data through the room repository and connect your media stack with the returned co-host URL and token.

| Platform | Broadcaster data API |
| --- | --- |
| TypeScript | `RoomRepository.getBroadcasterData(roomId)` returns `coHostToken` and `coHostUrl` when available |
| iOS | `AmityRoomRepository().generateRoomToken(withId:)` returns room token data |
| Android | `AmityVideoClient.newRoomRepository().getBroadcasterData(roomId)` returns `AmityRoomBroadcastData.CoHosts` |
| Flutter | No public room broadcasting repository found in this audit |

See [Start Broadcasting](./start-broadcasting) for media connection guidance.

## Related Topics

    Create a co-host room and seed its initial participant list.
    Query, update, stop, delete, and observe rooms.
    Connect the accepted host or co-host to the media stack.

---

### [Recorded Room Playback](https://learn.social.plus/social-plus-sdk/video-new/broadcasting/recorded-playback)

> Observe recorded room availability and pass SDK playback URLs to your player.

Recorded playback becomes available after a room finishes broadcasting and the backend publishes recorded playback metadata. The social.plus SDK owns room status, recorded playback URLs, recorded thumbnails, and recorded resolution metadata. Your app owns the actual player, queueing, seek controls, buffering, and retry UI.

  This page covers SDK-recorded playback data. AVPlayer, ExoPlayer, HLS.js, browser autoplay handling, DRM, captions, and player UI are app-owned concerns after the SDK returns a recorded playback URL.

## Platform Surface

| Platform | Observe availability | Recorded metadata | URL refresh helper | Notes |
| --- | --- | --- | --- | --- |
| TypeScript | `RoomRepository.getRoom(roomId, callback)` | `room.recordedPlaybackInfos[]`, `room.recordedResolution` | `RoomRepository.getRecordedUrl(roomId)` | `getRecordedUrl()` returns a URL and optional expiry timestamp. |
| iOS | `AmityRoomRepository().getRoom(withId:)` | `room.recordedData[]`, `room.recordedResolution` | Re-observe or fetch the room object | Retain the returned `AmityNotificationToken` while observing. |
| Android | `AmityVideoClient.newRoomRepository().getRoom(roomId)` | `room.getRecordedPlaybackInfos()`, `room.getRecordedResolution()` | `getRecordedUrls(roomId)` | `getRecordedUrls()` returns URL strings only. |
| Flutter | No current public room recorded playback API found in this audit | Not available | Not available | The Flutter SDK source exposes older stream APIs, not the room broadcasting repository. |

## Parameters

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Observe room | `RoomRepository.getRoom(roomId, callback)` | `AmityRoomRepository().getRoom(withId:)` | `AmityVideoClient.newRoomRepository().getRoom(roomId)` |
| Recorded status | `room.status === "recorded"` | `room.status == .recorded` | `room.getStatus() == AmityRoomStatus.RECORDED` |
| Processing status | `room.status === "ended"` | `room.status == .ended` | `room.getStatus() == AmityRoomStatus.ENDED` |
| Playback URL metadata | `room.recordedPlaybackInfos[].url` | `room.recordedData[].playbackUrl` | `room.getRecordedPlaybackInfos()[].url` |
| Thumbnail metadata | `room.recordedPlaybackInfos[].thumbnailUrl` | `room.recordedData[].thumbnailUrl` | `room.getRecordedPlaybackInfos()[].thumbnailUrl` |
| Recorded resolution | `room.recordedResolution` | `room.recordedResolution` | `room.getRecordedResolution()` |
| Fresh URL helper | `RoomRepository.getRecordedUrl(roomId)` | Re-observe `AmityRoom` | `getRecordedUrls(roomId)` |

## Wait for Recorded Status

Observe the room while the playback screen is open. Treat `ended` as a processing state and only hand a recorded URL to your player after the room status becomes `recorded`.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observeRecordedAvailability(roomId: string): Amity.Unsubscriber {
  return RoomRepository.getRoom(roomId, snapshot => {
    if (snapshot.error) {
      handleError(snapshot.error);
      return;
    }

    const room = snapshot.data;

    if (room.status === "recorded" && room.recordedPlaybackInfos.length > 0) {
      showSuccessMessage(room.recordedPlaybackInfos[0].url);
      return;
    }

    if (room.status === "ended") {
      showSuccessMessage("recording-processing");
      return;
    }

    showSuccessMessage(room.status);
  });
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

val disposable = AmityVideoClient.newRoomRepository()
    .getRoom(roomId)
    .subscribe(
        { room ->
            when (room.getStatus()) {
                AmityRoomStatus.RECORDED -> {
                    val firstUrl = room.getRecordedPlaybackInfos()
                        .mapNotNull { it.url }
                        .firstOrNull()

                    showSuccessMessage(firstUrl ?: "recorded")
                }
                AmityRoomStatus.ENDED -> {
                    showSuccessMessage("recording-processing")
                }
                else -> {
                    showSuccessMessage(room.getStatus())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    guard let room = liveObject.snapshot else { return }

    switch room.status {
    case .recorded:
        showSuccessMessage(room.recordedData.first?.playbackUrl)
    case .ended:
        showSuccessMessage("recording-processing")
    default:
        showSuccessMessage(room.status.rawValue)
    }
}
```


## Read Recorded Sources

Recorded metadata can contain more than one playback item. Preserve the SDK order unless your product has a backend-defined reason to reorder segments.


```typescript TypeScript
type RecordedPlaybackSource = {
  url: string;
  thumbnailUrl: string;
};

function recordedPlaybackSources(room: Amity.Room): RecordedPlaybackSource[] {
  if (room.status !== "recorded") {
    return [];
  }

  return room.recordedPlaybackInfos.map(info => ({
    url: info.url,
    thumbnailUrl: info.thumbnailUrl,
  }));
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

data class RecordedPlaybackSource(
    val url: String,
    val thumbnailUrl: String?
)

fun recordedPlaybackSources(room: AmityRoom): List<RecordedPlaybackSource> {
    if (room.getStatus() != AmityRoomStatus.RECORDED) {
        return emptyList()
    }

    return room.getRecordedPlaybackInfos().mapNotNull { info ->
        info.url?.let { url ->
            RecordedPlaybackSource(
                url = url,
                thumbnailUrl = info.thumbnailUrl
            )
        }
    }
}
```

```swift iOS
struct RecordedPlaybackSource {
    let playbackUrl: String
    let thumbnailUrl: String
}

func recordedPlaybackSources(for room: AmityRoom) -> [RecordedPlaybackSource] {
    guard room.status == .recorded else { return [] }

    return room.recordedData
        .filter { !$0.playbackUrl.isEmpty }
        .map { data in
            RecordedPlaybackSource(
                playbackUrl: data.playbackUrl,
                thumbnailUrl: data.thumbnailUrl
            )
        }
}
```


## Refresh a Playback URL

Refresh recorded playback data before starting playback, after a long pause, or when your player reports an expired or unauthorized media URL.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

const recordedUrl = await RoomRepository.getRecordedUrl(roomId);

showSuccessMessage(recordedUrl.url);
showSuccessMessage(recordedUrl.expiresAt);
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val disposable = AmityVideoClient.newRoomRepository()
    .getRecordedUrls(roomId)
    .subscribe(
        { urls -> showSuccessMessage(urls.firstOrNull() ?: "no-recorded-url") },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var refreshToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

refreshToken = roomObject.observeOnce { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    guard let room = liveObject.snapshot,
          room.status == .recorded else {
        return
    }

    showSuccessMessage(room.recordedData.first?.playbackUrl)
}
```


## Status Handling

| Room status | Recorded playback behavior |
| --- | --- |
| `idle` | No recording exists. Show a waiting or not-started state. |
| `live` / `waitingReconnect` | Use live playback, not recorded playback. |
| `ended` | Broadcast has ended, but recording metadata may still be processing. Keep observing or offer retry. |
| `recorded` | Read recorded playback metadata and pass a URL to your player. |
| `terminated` | TypeScript room status for a terminated room. Do not assume recorded playback is available. |
| `error` | Show a recoverable error state and let the viewer retry or leave. |

  Do not treat `ended` as playable recorded content. Wait for `recorded` status or a successful platform URL refresh response before handing a recorded URL to the player.

## Segment and Player Boundary

| Area | SDK responsibility | App/player responsibility |
| --- | --- | --- |
| Availability | Room status updates and recorded metadata | Processing, empty, retry, and unavailable UI |
| Source list | Recorded URLs, thumbnails, and recorded resolution | Segment queueing, autoplay policy, seek controls, buffering, captions, and DRM |
| Freshness | TS `getRecordedUrl()`, Android `getRecordedUrls()`, iOS room re-observation | Retry timing, expired URL recovery, and player reload |
| Cleanup | Unsubscribe, invalidate tokens, or dispose Rx subscriptions | Release player instances and audio/video resources |

  Multiple recorded playback items can represent multiple files for one recording. Preserve the SDK order and let the player layer decide whether to play only the first URL or queue all URLs.

## Related Topics

    Discover room posts, observe live rooms, and choose playback sources.
    Fetch broadcaster credentials and start the host-side media session.
    Observe, query, update, stop, or delete room records.

## Video — Playback & Notifications

### [Playback Overview](https://learn.social.plus/social-plus-sdk/video-new/playback/overview)

> Understand the SDK room playback contract and hand live or recorded playback URLs to your player.

Playback in the social.plus SDK is a room-data workflow. The SDK gives your app room state, live playback URLs, recorded playback metadata, optional URL refresh helpers, and watch-session analytics. Your app owns the media player, autoplay policy, buffering UI, captions, DRM, seek controls, and platform playback SDK.

  This page covers SDK playback data for rooms. Use your own player layer, such as AVPlayer, ExoPlayer, a browser video element with HLS support, or another product-approved player, after the SDK returns a playable URL.

## Platform Surface

| Platform | Observe room state | Live source | Recorded source | Recorded refresh | Watch analytics |
| --- | --- | --- | --- | --- | --- |
| TypeScript | `RoomRepository.getRoom(roomId, callback)` | `room.livePlaybackUrl` | `room.recordedPlaybackInfos[]` | `RoomRepository.getRecordedUrl(roomId)` | `room.analytics()` |
| iOS | `AmityRoomRepository().getRoom(withId:)` | `room.livePlaybackUrl` | `room.recordedData[]` | Re-observe or fetch the room object | `room.analytics()` |
| Android | `AmityVideoClient.newRoomRepository().getRoom(roomId)` | `room.getLivePlaybackUrl()` | `room.getRecordedPlaybackInfos()` | `getRecordedUrls(roomId)` | `room.analytics()` |
| Flutter | No current public room playback API found in this audit | Not available | Not available | Not available | Not available |

## Playback Flow

    Use a room live object or room query from the platform SDK. Keep the subscription alive while the viewing screen is open.
    Use the live URL only when the room is `live` or `waitingReconnect`. Use recorded metadata only when the room is `recorded`.
    Pass the selected URL to your app-owned player. Do not call player APIs that are not part of the social.plus SDK.
    Create and update a room watch session from `room.analytics()` when your product considers the viewer actively watching.

## Parameters

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Room ID | `room.roomId` | `room.roomId` | `room.getRoomId()` |
| Room status | `room.status` | `room.status` | `room.getStatus()` |
| Live URL | `room.livePlaybackUrl` | `room.livePlaybackUrl` | `room.getLivePlaybackUrl()` |
| Recorded URL list | `room.recordedPlaybackInfos[].url` | `room.recordedData[].playbackUrl` | `room.getRecordedPlaybackInfos()[].url` |
| Recorded thumbnail list | `room.recordedPlaybackInfos[].thumbnailUrl` | `room.recordedData[].thumbnailUrl` | `room.getRecordedPlaybackInfos()[].thumbnailUrl` |
| Live resolution | `room.liveResolution` | `room.liveResolution` | `room.getLiveResolution()` |
| Recorded resolution | `room.recordedResolution` | `room.recordedResolution` | `room.getRecordedResolution()` |
| Watch analytics | `room.analytics()` | `room.analytics()` | `room.analytics()` |

## Choose a Playback Source

Select a URL from SDK room state before creating or updating your player. Return no source for statuses that are not playable.


```typescript TypeScript
function playbackSourceForRoom(room: Amity.Room): string | undefined {
  if (room.status === "live" || room.status === "waitingReconnect") {
    return room.livePlaybackUrl;
  }

  if (room.status === "recorded") {
    return room.recordedPlaybackInfos[0]?.url;
  }

  return undefined;
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

fun playbackSourceForRoom(room: AmityRoom): String? {
    return when (room.getStatus()) {
        AmityRoomStatus.LIVE,
        AmityRoomStatus.WAITING_RECONNECT -> room.getLivePlaybackUrl()
        AmityRoomStatus.RECORDED -> room.getRecordedPlaybackInfos()
            .firstOrNull()
            ?.url
        else -> null
    }
}
```

```swift iOS
func playbackSource(for room: AmityRoom) -> String? {
    switch room.status {
    case .live, .waitingReconnect:
        return room.livePlaybackUrl
    case .recorded:
        return room.recordedData.first?.playbackUrl
    default:
        return nil
    }
}
```


## Observe Playback State

Observe room state while the viewer is on a playback screen. A room can move from waiting, to live playback, to ended processing, and later to recorded playback.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

function observePlaybackState(roomId: string): Amity.Unsubscriber {
  return RoomRepository.getRoom(roomId, snapshot => {
    if (snapshot.error) {
      handleError(snapshot.error);
      return;
    }

    const room = snapshot.data;
    const source =
      room.status === "live" || room.status === "waitingReconnect"
        ? room.livePlaybackUrl
        : room.status === "recorded"
          ? room.recordedPlaybackInfos[0]?.url
          : undefined;

    if (source) {
      showSuccessMessage(source);
      return;
    }

    showSuccessMessage(room.status);
  });
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus

val disposable = AmityVideoClient.newRoomRepository()
    .getRoom(roomId)
    .subscribe(
        { room ->
            when (room.getStatus()) {
                AmityRoomStatus.LIVE,
                AmityRoomStatus.WAITING_RECONNECT -> {
                    showSuccessMessage(room.getLivePlaybackUrl() ?: "live")
                }
                AmityRoomStatus.RECORDED -> {
                    val source = room.getRecordedPlaybackInfos()
                        .firstOrNull()
                        ?.url

                    showSuccessMessage(source ?: "recorded")
                }
                else -> {
                    showSuccessMessage(room.getStatus())
                }
            }
        },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var roomObservationToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

roomObservationToken = roomObject.observe { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    guard let room = liveObject.snapshot else { return }

    switch room.status {
    case .live, .waitingReconnect:
        showSuccessMessage(room.livePlaybackUrl)
    case .recorded:
        showSuccessMessage(room.recordedData.first?.playbackUrl)
    default:
        showSuccessMessage(room.status.rawValue)
    }
}
```


## Refresh Recorded Playback

Refresh recorded playback data before starting a recorded video, after a long pause, or when your player reports an expired or unauthorized media URL.


```typescript TypeScript
import { RoomRepository } from "@amityco/ts-sdk";

async function refreshRecordedPlaybackUrl(roomId: string): Promise<string> {
  const recordedUrl = await RoomRepository.getRecordedUrl(roomId);

  showSuccessMessage(recordedUrl.expiresAt);

  return recordedUrl.url;
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.video.AmityVideoClient

val disposable = AmityVideoClient.newRoomRepository()
    .getRecordedUrls(roomId)
    .subscribe(
        { urls -> showSuccessMessage(urls.firstOrNull() ?: "no-recorded-url") },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
var refreshToken: AmityNotificationToken?
let roomObject = AmityRoomRepository().getRoom(withId: roomId)

refreshToken = roomObject.observeOnce { liveObject, error in
    if let error {
        handleGeneralError(error)
        return
    }

    guard let room = liveObject.snapshot,
          room.status == .recorded else {
        return
    }

    showSuccessMessage(room.recordedData.first?.playbackUrl)
}
```


## Status Handling

| Room status | Playback behavior |
| --- | --- |
| `idle` | Show a waiting or not-started state. Do not create a player source. |
| `live` | Use the live playback URL when present. |
| `waitingReconnect` | Keep the viewing UI available and show reconnecting state if playback stalls. |
| `ended` | Stop live playback and show processing state while recorded metadata is not ready. |
| `recorded` | Use recorded playback metadata or the platform refresh helper. |
| `terminated` | TypeScript room status for a terminated room. Do not assume playback is available. |
| `error` | Show a recoverable error state and let the viewer retry or leave. |

  Do not synthesize fallback playback URLs. If the SDK room state does not include a playable live or recorded source for the current viewer, show an unavailable, blocked, processing, or retry state based on your product rules.

## SDK and Player Boundary

| Area | social.plus SDK owns | Your app/player owns |
| --- | --- | --- |
| Discovery | Room IDs, room post data, room state, live object updates | Ranking, placement, navigation, and empty states |
| Source data | Live URLs, recorded URLs, thumbnails, and resolution metadata | Player initialization, buffering, seek controls, captions, DRM, and release lifecycle |
| Freshness | Platform refresh or re-observation helpers | Retry timing, expired URL recovery, and player reload |
| Analytics | Room watch-session APIs | Deciding which player states count as active watch time |

## Related Topics

    Observe live room state and hand the live URL to your player.
    Wait for recorded status, read recorded metadata, and refresh URLs.
    Track room watch sessions after playback starts.

---

### [Livestream Analytics](https://learn.social.plus/social-plus-sdk/video-new/analytics/overview)

> Track live and recorded room watch sessions with current SDK room analytics APIs.

Livestream analytics track a viewer's watch session for a room. The social.plus SDK owns session creation, local watch-session storage, duration updates, and pending-session sync. Your app owns deciding when a viewer is actually watching, when playback is paused or buffering, and when a viewer changes role from viewer to host or co-host.

  This page covers SDK room watch-session APIs. Product analytics dashboards, custom event names, media player state, and business reporting are app-owned concerns after you create and update watch sessions.

## Platform Surface

| Platform | Analytics entry point | Create session | Update duration | Sync pending sessions |
| --- | --- | --- | --- | --- |
| TypeScript | `room.analytics()` | `createWatchSession(startedAt)` | `updateWatchSession(sessionId, duration, endedAt)` | `syncPendingWatchSessions()` |
| iOS | `room.analytics()` | `createWatchSession(startedAt:)` | `updateWatchSession(sessionId:duration:endedAt:)` | `syncPendingWatchSessions()` |
| Android | `room.analytics()` | `createWatchSession(startedAt)` | `updateWatchSession(sessionId, duration, endedAt)` | `syncPendingWatchSessions()` |
| Flutter | No current public room analytics API found in this audit | Not available | Not available | Not available |

## Parameters

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Entry point | `room.analytics()` | `room.analytics()` | `room.analytics()` |
| Watchable statuses | `"live"`, `"recorded"` | `.live`, `.recorded` | `AmityRoomStatus.LIVE`, `AmityRoomStatus.RECORDED` |
| Start timestamp | `Date` | `Date` | `DateTime` |
| Session ID | `string` | `String` | `String` |
| Duration | `number` seconds | `Int` seconds | `Long` seconds |
| End timestamp | `Date` | `Date` | `DateTime` |
| Sync return | `void` | `Void` | `Unit` |

## Create a Watch Session

Create a watch session when the current user starts viewing a room as a viewer. The SDK accepts watch sessions only for rooms in watchable states: `live` or `recorded`.


```typescript TypeScript
async function createRoomWatchSession(
  room: Amity.Room,
): Promise<string | undefined> {
  if (room.status !== "live" && room.status !== "recorded") {
    return undefined;
  }

  const sessionId = await room.analytics().createWatchSession(new Date());
  showSuccessMessage(sessionId);

  return sessionId;
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import com.amity.socialcloud.sdk.model.video.room.AmityRoomStatus
import org.joda.time.DateTime

fun createRoomWatchSession(room: AmityRoom) {
    if (room.getStatus() != AmityRoomStatus.LIVE &&
        room.getStatus() != AmityRoomStatus.RECORDED
    ) {
        return
    }

    room.analytics()
        .createWatchSession(DateTime.now())
        .subscribe(
            { sessionId -> showSuccessMessage(sessionId) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func createRoomWatchSession(for room: AmityRoom) async throws -> String? {
    guard room.status == .live || room.status == .recorded else {
        return nil
    }

    let sessionId = try await room.analytics()
        .createWatchSession(startedAt: Date())

    showSuccessMessage(sessionId)

    return sessionId
}
```


## Update Watch Duration

Update the session with the accumulated watch duration in seconds. Count only time your player considers watchable, such as active playback, and exclude buffering, paused, or backgrounded states according to your product rules.


```typescript TypeScript
async function updateRoomWatchSession(
  room: Amity.Room,
  sessionId: string,
  watchedSeconds: number,
): Promise<void> {
  await room.analytics().updateWatchSession(
    sessionId,
    watchedSeconds,
    new Date(),
  );

  showSuccessMessage(sessionId);
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom
import org.joda.time.DateTime

fun updateRoomWatchSession(
    room: AmityRoom,
    sessionId: String,
    watchedSeconds: Long
) {
    room.analytics()
        .updateWatchSession(
            sessionId = sessionId,
            duration = watchedSeconds,
            endedAt = DateTime.now()
        )
        .subscribe(
            { showSuccessMessage(sessionId) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func updateRoomWatchSession(
    for room: AmityRoom,
    sessionId: String,
    watchedSeconds: Int
) async throws {
    try await room.analytics().updateWatchSession(
        sessionId: sessionId,
        duration: watchedSeconds,
        endedAt: Date()
    )

    showSuccessMessage(sessionId)
}
```


## Sync Pending Sessions

Call sync when the viewer leaves the playback experience or changes out of a viewer role. The SDK sync method handles pending locally stored sessions; your app decides the lifecycle event that should trigger it.


```typescript TypeScript
function syncRoomWatchSessions(room: Amity.Room): void {
  room.analytics().syncPendingWatchSessions();
  showSuccessMessage("sync-scheduled");
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.video.room.AmityRoom

fun syncRoomWatchSessions(room: AmityRoom) {
    room.analytics().syncPendingWatchSessions()
    showSuccessMessage("sync-scheduled")
}
```

```swift iOS
func syncRoomWatchSessions(for room: AmityRoom) {
    room.analytics().syncPendingWatchSessions()
    showSuccessMessage("sync-scheduled")
}
```


## Tracking Boundaries

| Area | SDK responsibility | App responsibility |
| --- | --- | --- |
| Session lifecycle | Create, update, and sync room watch sessions | Decide when the viewer starts and stops watching |
| Watchable state | Reject sessions for non-watchable room statuses | Check room status before creating a session |
| Duration | Store the latest duration value for the session | Calculate accumulated watch seconds from player state |
| Sync | Send pending sessions with SDK sync behavior | Trigger sync on page exit, role transition, or product-defined lifecycle events |
| Role changes | No automatic viewer/co-host policy | Stop viewer tracking before the user becomes host or co-host |

  Do not create watch sessions for `idle`, `ended`, `terminated`, or `error` rooms. Create sessions only after the room is `live` or `recorded`.

## Error Handling

| Situation | SDK behavior | App response |
| --- | --- | --- |
| Non-watchable room status | Create session fails or returns an error | Check status before calling and show a non-playable state |
| Missing session ID on update | Update fails because the session cannot be found | Recreate tracking only if the viewer is still watching and your product wants a new session |
| Network unavailable during sync | Pending sessions stay local until sync can complete | Retry from the next appropriate lifecycle event |

## Related Topics

    Observe live room state before creating viewer sessions.
    Track recorded room playback after recording metadata is available.
    Stop viewer tracking when a viewer becomes a co-host.

## Chat — Overviews & Message Flagging

### [Chat Module](https://learn.social.plus/social-plus-sdk/chat/overview)

> Choose the SDK surfaces for channels, members, messages, moderation, and chat engagement state.

The Chat SDK is the client surface for building channel-based messaging across TypeScript, iOS, Android, and Flutter. Use it to create and query channels, manage membership, send and read messages, apply moderation actions, and render engagement state such as previews, unread counts, read receipts, and delivery status.

  Looking for a product walkthrough? Use [Channels & Conversations](/use-cases/chat/channels-and-conversations) and [Sending Messages](/use-cases/chat/sending-messages). Use this section when you need the exact SDK objects and methods.

## SDK Area Map

| Area | Use it for | Start here |
| --- | --- | --- |
| Conversation management | Create, query, update, archive, and organize chat channels. | [Conversation Management](/social-plus-sdk/chat/conversation-management/overview) |
| Member management | Join or leave channels, query channel members, and read membership state. | [Member Management](/social-plus-sdk/chat/conversation-management/members/overview) |
| Channel governance | Add or remove members, roles, bans, and mutes. | [Channel Governance](/social-plus-sdk/chat/conversation-management/channels/governance/overview) |
| Messaging features | Create, query, edit, delete, reply to, and flag messages. | [Messaging Features](/social-plus-sdk/chat/messaging-features/overview) |
| Engagement features | Read message previews, unread counts, read status, delivery status, and receipt sync state. | [Unread Status Overview](/social-plus-sdk/chat/engagement-features/unread-status/overview) |
| Content moderation | Connect user reports, message deletion, and channel governance into a product moderation flow. | [Content Moderation](/social-plus-sdk/chat/moderation-safety/content-moderation/overview) |

## Platform Coverage

| Capability group | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Channel lifecycle | Supported | Supported | Supported | Supported |
| Member operations | Supported | Supported | Supported | Supported |
| Channel governance | Supported | Supported | Supported | Supported |
| Message creation and querying | Supported | Supported | Supported | Supported |
| Message reactions and mentions | Supported through core content APIs | Supported through core content APIs | Supported through core content APIs | Supported through core content APIs |
| Message preview and unread counts | Supported with platform-specific gaps | Supported | Supported | Supported with platform-specific gaps |
| Delivery receipt user queries | Supported | Supported | Supported | Not exposed in the current public Flutter SDK |
| Explicit receipt sync start/stop | Supported | Supported | Supported | Not exposed in the current public Flutter SDK |

  Platform gaps are documented on the specific feature pages. Do not copy a code snippet from another platform when a public SDK surface is not exposed for your target platform.

## Implementation Shape

    Create or query the channel that owns the conversation, then resolve the target `subChannelId` for message APIs.
    Use member state to decide whether the current user can read, join, send, or moderate.
    Query messages by subchannel, apply message-type filters, and handle edits or soft deletes from the message model.
    Read previews, unread counters, receipt counts, and receipt sync state from the SDK where supported.

## Product Boundaries

| Concern | SDK owns | Your app owns |
| --- | --- | --- |
| Identity | Authenticated SDK user context and channel membership state. | Login, user provisioning, and user-facing account policy. |
| Rendering | Message, channel, member, receipt, and preview models. | UI layout, empty states, moderation copy, and accessibility behavior. |
| Moderation | Message flagging, message deletion, and channel governance APIs. | Review queues, escalation policy, audit notes, appeal flows, and compliance workflows. |
| Notifications | Data fields such as unread count, mention state, and preview content. | Push-notification templates, routing, deep links, and notification preferences. |

## Related Topics

    Start a community, live, or conversation channel.
    Send text, media, custom, and reply messages.
    Let users report and unreport chat messages.

---

### [Conversation Management Overview](https://learn.social.plus/social-plus-sdk/chat/conversation-management/overview)

> Choose the SDK surfaces for chat channel lifecycle, member state, and channel governance.

Conversation management covers the SDK calls that decide where chat happens and who can participate. Start here when your integration needs to create or find a channel, resolve a message target, manage channel membership, or build moderator tools.

  If you want an end-to-end product walkthrough before choosing SDK calls, read [Channels & Conversations](/use-cases/chat/channels-and-conversations).

## Capability Map

| Capability | Use it for | SDK page |
| --- | --- | --- |
| Create channels | Create community, live, or conversation channels. | [Create Channels](./channels/create-channel) |
| Get channels | Load a known channel or a set of known channel IDs. | [Get Channels](./channels/get-channel) |
| Query channels | Build inboxes, discovery lists, event chat lists, and moderation channel lists. | [Query Channels](./channels/query-channels) |
| Update channels | Change display name, avatar, tags, metadata, or notification mode where supported. | [Update Channels](./channels/update-channel) |
| Archive channels | Archive or unarchive channels for the current user where supported. | [Archive Channels](./channels/archive-channels) |
| Member operations | Join, leave, query, search, and preview channel members. | [Member Management](./members/overview) |
| Channel governance | Add or remove channel members, roles, bans, and mutes. | [Channel Governance](./channels/governance/overview) |

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Create community channels | Supported | Supported | Supported | Supported |
| Create live channels | Supported | Supported | Supported | Supported |
| Create conversation channels | Supported | Supported | Supported | Supported |
| Query by type and membership | Supported | Supported | Supported | Supported |
| Query by keyword or display name | Supported | Not exposed on current query options | Not exposed on public query builder | Supported |
| Get multiple known channel IDs | Supported | Supported | Supported | Not exposed in the current public Flutter repository |
| Archive channels | Supported | Supported | Supported | Supported |

## Channel And Message Targets

Channel APIs operate on `channelId`. Message APIs usually operate on `subChannelId`. Resolve the target subchannel from the channel or subchannel flow before creating, querying, or syncing messages.

  The channel pages describe channel lifecycle calls. The messaging pages describe message calls after a `subChannelId` is available.

## Implementation Shape

    Use community for public or private group chat, live for event-style chat, and conversation for direct or small-group chat.
    Use type, membership, tag, deletion, and platform-specific search filters to build channel lists.
    Read membership before showing composer, join, leave, or moderation actions.
    Use role, member, ban, and mute APIs for channel-level moderation workflows.

## Related Topics

    Create, query, edit, delete, reply to, and flag messages after the channel target is known.
    Show unread counts, read status, delivery status, and receipt sync state.
    Combine message reports, deletion, and channel governance into a moderation flow.

---

### [Member Management Overview](https://learn.social.plus/social-plus-sdk/chat/conversation-management/members/overview)

> Choose the SDK surfaces for joining, leaving, querying, searching, and previewing chat channel members.

Member management is the SDK surface for deciding who is in a channel and how your app reads that membership state. Use these pages when you need join and leave flows, member lists, mention pickers, moderator lists, or membership-aware UI.

## Capability Map

| Capability | Use it for | SDK page |
| --- | --- | --- |
| Join a channel | Add the current user to a joinable channel. | [Join & Leave Channel](./join-leave-channel) |
| Leave a channel | Remove the current user from a channel where leaving is allowed. | [Join & Leave Channel](./join-leave-channel) |
| Read current membership | Hide composer controls, redirect banned users, or show join prompts. | [Join & Leave Channel](./join-leave-channel) |
| Query members | Build member lists, moderator lists, banned lists, or muted lists. | [Query Members](./query-members) |
| Search members | Build mention pickers and member directories. | [Query Members](./query-members) |
| Preview members | Show a small channel-member sample where the platform exposes preview members. | [Preview Members](./preview-members) |

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Join channel | Supported | Supported | Supported | Supported |
| Leave channel | Supported | Supported | Supported | Supported |
| Current membership state | Supported | Supported | Supported | Supported |
| Query members | Supported | Supported | Supported | Supported |
| Search members | Supported | Supported | Supported | Supported |
| Role filters | Supported | Supported | Supported | Supported |
| Preview-member field | Supported | Supported | Use member-query fallback | Use member-query fallback |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel whose membership state should be read or changed. |
| Membership filter | No | Filter member queries by state such as member, banned, muted, or all where supported. |
| `roles` | No | Filter members by channel role, such as `moderator` or another role configured for your app. |
| Search keyword | No | Search member display names where the platform exposes member search. |
| `includeDeleted` | No | Include deleted users in member query results where supported. |

## Implementation Shape

    Read membership before showing the composer, join button, leave action, or banned-state messaging.
    Query members by channel, membership state, role, search keyword, and deletion state where supported.
    Use member search for mention pickers and user-selection flows.
    Use preview members where exposed; otherwise query a small member page for fallback display.

## Related Topics

    Assign or remove channel roles for members.
    Remove channel access until a user is unbanned.
    Restrict sending while keeping channel access.

---

### [Channel Governance Overview](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/governance/overview)

> Understand the SDK surfaces for chat channel roles, member management, bans, and mutes.

Channel governance is the SDK surface for changing who can participate in a chat channel and what they can do there. Use these pages when you are building moderator tools, channel settings, admin panels, or support workflows.

## Capability Map

| Capability | Purpose | SDK page |
| --- | --- | --- |
| Member management | Add or remove channel members. | [Member Management](./member-management) |
| Role management | Add or remove channel roles for members. | [Role Management](./role-management) |
| Ban management | Block users from the channel until unbanned. | [Ban Management](./ban-management) |
| Mute management | Restrict users from sending messages while keeping channel access. | [Mute Management](./mute-management) |
| Member queries | Read current member, role, banned, and muted state. | [Query Members](/social-plus-sdk/chat/conversation-management/members/query-members) |

## Platform Coverage

| Platform | Member add/remove | Role add/remove | Ban/unban | Mute/unmute |
| --- | --- | --- | --- | --- |
| TypeScript | Supported | Supported | Supported | Supported |
| iOS | Supported | Supported | Supported | Supported |
| Android | Supported | Supported | Supported | Supported |
| Flutter | Supported | Supported | Supported | Supported |

  Governance operations are subject to channel type, membership state, and moderation permissions. If the server rejects an operation, treat that result as authoritative and show an actionable error in your product UI.

## Implementation Shape

    Use the governance pages for SDK calls that change membership, roles, bans, or mutes.
    Use member query and search APIs to render member lists, moderator lists, muted members, and banned members.
    Store reason codes, escalation rules, appeals, and audit records in your own backend if your product needs them.
    Some governance operations are only meaningful on channel types that support the target moderation behavior.

## Related Topics

    Create channels before applying governance operations.
    Read membership, role, banned, and muted state.
    Moderate individual messages separately from channel membership.

---

### [Messaging Features Overview](https://learn.social.plus/social-plus-sdk/chat/messaging-features/overview)

> SDK surfaces for creating, querying, updating, deleting, flagging, and engaging with chat messages.

Use chat message APIs to build the message composer, message list, replies, reactions, and moderation actions inside a channel or subchannel. Most message creation APIs target a `subChannelId`; use channel and member APIs when you need to discover the correct chat target first.

    Send text, image, file, video, audio, and custom message payloads where the platform SDK exposes them.
    Load channel messages, replies, filtered message lists, and paginated message collections.
    Edit supported message types, soft-delete messages, and clear failed local messages where supported.
    Let users report or unreport messages for moderation review.
    Pin one message above a livestream chat and keep it in sync through the channel live object.

## Message Creation Coverage

| Message type | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Text | `MessageRepository.createMessage` | `createTextMessage` | `createTextMessage` | `createMessage(...).text(...)` |
| Image | `MessageRepository.createMessage` | `createImageMessage` | `createImageMessage` | `createMessage(...).image(...)` |
| File | `MessageRepository.createMessage` | `createFileMessage` | `createFileMessage` | `createMessage(...).file(...)` |
| Video | `MessageRepository.createMessage` | `createVideoMessage` | `createVideoMessage` | `createMessage(...).video(...)` |
| Audio | `MessageRepository.createMessage` | `createAudioMessage` | `createAudioMessage` | No current public audio creator in the message create selector |
| Custom | `MessageRepository.createMessage` | `createCustomMessage` | `createCustomMessage` | `createCustomMessage` or `createMessage(...).custom(...)` |

Media-message inputs differ by platform. TypeScript creates media messages from uploaded file IDs. iOS accepts `AmityMessageAttachment` values such as `.localURL` or `.fileId`. Android accepts `AmityMessageAttachment` values such as `FILE_ID` or `URL`. Flutter creates image, file, and video messages from a `Uri`.

## Implementation Notes

- Resolve the `subChannelId` from your channel flow before creating messages.
- Use `parentId` when creating replies.
- Use `tags` and `metadata` only for app-owned categorization or rendering context.
- Upload or select media first when your target platform expects a file ID or attachment object.
- Keep message state handling in the UI tied to the platform model returned by the SDK.

## Related Topics

    Choose the right create API for each message type.
    Create threaded replies with `parentId`.
    Query top-level messages and reply threads.
    Add report and unreport actions for chat messages.

---

### [Message Flagging](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-flagging)

> Flag chat messages with an optional reason and detail, unflag them, and read the current user's flag state.

Use message flagging when a signed-in user reports a chat message. The SDKs expose three client-side actions: flag a message, unflag a message, and check whether the current user has already flagged a fetched message.

Flagged messages are sent to the moderation backend. Keep product policy, review workflow, and enforcement copy outside the SDK integration layer so this page stays focused on the calls your app makes.

## Platform Surface

| Platform | Flag | Unflag | Check current user's flag |
| --- | --- | --- | --- |
| Android | `messageRepository.flagMessage(messageId)` or `flagMessage(messageId, reason, detail?)` | `messageRepository.unflagMessage(messageId)` | `message.isFlaggedByMe()` on a fetched `AmityMessage` |
| iOS | `messageRepository.flagMessage(withId:)` or `flagMessage(withId:reason:detail:)` | `messageRepository.unflagMessage(withId:)` | `messageRepository.isMessageFlaggedByMe(withId:)` |
| TypeScript | `MessageRepository.flagMessage(messageId)` or `flagMessage(messageId, { reason, detail? })` | `MessageRepository.unflagMessage(messageId)` | `MessageRepository.isMessageFlaggedByMe(messageId)` |
| Flutter | `messageRepository.flagMessage(messageId:reason:)` or `message.flagWithReason(reason)` | `messageRepository.unflag(messageId)` or `message.unflag()` | `message.isFlaggedByMe` on a fetched `AmityMessage` |

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Flag | `messageId` | Yes | All | Message ID to report. |
| Flag | `reason` | No on Android, iOS, TypeScript; yes on Flutter `flagMessage` | All | One reason category. Android, iOS, and TypeScript use `AmityContentFlagReasonType` (`ContentFlagReasonEnum` before TypeScript 7.31.0), Flutter uses `AmityContentFlagReason`. See [Flag reasons](/social-plus-sdk/social/content-management/moderation/content-flagging#flag-reasons). |
| Flag | `detail` | No | Android, iOS, TypeScript | The reporter's own words, for any reason including Others. Needs a `reason`. Sent as given; omitted when not set. The server limits it to 300 characters. |
| Unflag | `messageId` | Yes | All | Message ID whose report should be removed for the current user. |
| Check flag state | `messageId` | Yes | iOS, TypeScript | Message ID to check through the repository. |
| Check flag state | Fetched message object | Yes | Android, Flutter | `isFlaggedByMe` on a fetched `AmityMessage`. |

## Flag A Message

Flag a message with a reason so your product can route it into review, and add the reporter's own words as `detail` when they give some. Use the no-reason call when your UI only offers a single "Report" action.


```kotlin Android
// Reason with the reporter's own words
messageRepository
    .flagMessage(
        messageId = messageId,
        reason = AmityContentFlagReasonType.SPAM_OR_SCAMS,
        detail = "Same promo link sent to every member",
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleFlagError(error) },
    )

// No reason
messageRepository
    .flagMessage(messageId = messageId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleFlagError(error) },
    )
```

```swift iOS
// Reason with the reporter's own words
try await messageRepository.flagMessage(
    withId: "message-id",
    reason: .spamOrScams,
    detail: "Same promo link sent to every member"
)

// Reason only: type the reason explicitly so the current call is used
try await messageRepository.flagMessage(
    withId: "message-id",
    reason: AmityContentFlagReasonType.spamOrScams
)

// No reason
try await messageRepository.flagMessage(withId: "message-id")

showSuccessMessage("Message flagged")
```

```typescript TypeScript
import { AmityContentFlagReasonType, MessageRepository } from '@amityco/ts-sdk';

// Reason with the reporter's own words
const flagged = await MessageRepository.flagMessage(messageId, {
  reason: AmityContentFlagReasonType.SpamOrScams,
  detail: 'Same promo link sent to every member',
});

renderResults(flagged);

// No reason
await MessageRepository.flagMessage(messageId);
```

```dart Flutter
final flaggedMessage = await AmityChatClient.newMessageRepository()
    .flagMessage(
      messageId: messageId,
      reason: AmityContentFlagReason.spamOrScams,
    );

final isFlaggedByMe = flaggedMessage.isFlaggedByMe;
```


## Report Child Endangerment

Flag a message that endangers a child, including suspected child sexual abuse material (CSAM), with the Child endangerment reason. Send it as its own reason, not as Others with a detail, so these reports reach moderators under their own category. A `detail` is optional.


{/* doc-as-test: skip (CHILD_ENDANGERMENT ships after the published Android SDK) */}
```kotlin Android
messageRepository
    .flagMessage(
        messageId = messageId,
        reason = AmityContentFlagReasonType.CHILD_ENDANGERMENT,
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleFlagError(error) },
    )
```

{/* doc-as-test: skip (childEndangerment ships after the published iOS SDK) */}
```swift iOS
// Type the reason explicitly so the current call is used
try await messageRepository.flagMessage(
    withId: "message-id",
    reason: AmityContentFlagReasonType.childEndangerment
)
```

```typescript TypeScript
import { AmityContentFlagReasonType, MessageRepository } from '@amityco/ts-sdk';

await MessageRepository.flagMessage(messageId, {
  reason: AmityContentFlagReasonType.ChildEndangerment,
});
```


## Report With Others

Use the Others reason when none of the categories fit. On Android, iOS, and TypeScript, put the reporter's explanation in `detail`, as for any other reason. Flutter carries the text on its Others reason.


```kotlin Android
messageRepository
    .flagMessage(
        messageId = messageId,
        reason = AmityContentFlagReasonType.OTHERS,
        detail = "Contains sensitive account information",
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleFlagError(error) },
    )
```

```swift iOS
try await messageRepository.flagMessage(
    withId: "message-id",
    reason: .others,
    detail: "Contains sensitive account information"
)
```

```typescript TypeScript
import { AmityContentFlagReasonType, MessageRepository } from '@amityco/ts-sdk';

const flagged = await MessageRepository.flagMessage(messageId, {
  reason: AmityContentFlagReasonType.Others,
  detail: 'Contains sensitive account information',
});

renderResults(flagged);
```

```dart Flutter
final flaggedMessage = await AmityChatClient.newMessageRepository()
    .flagMessage(
      messageId: messageId,
      reason: AmityContentFlagReason.others(
        'Contains sensitive account information',
      ),
    );

final flagCount = flaggedMessage.flagCount;
```


  The earlier calls that took only a reason are **deprecated** but still work on
  Android, iOS, and TypeScript: `flagMessage(messageId, reason)` with a reason
  string on TypeScript, and with `AmityContentFlagReason` on Android and iOS,
  where custom text was passed as `Others("...")` / `.others("...")`. Move custom
  text to `detail` with the Others reason. Flagging with only a message ID is
  not deprecated on these platforms. On Flutter, the repository `flag(messageId)`
  is deprecated; use `flagMessage(messageId:reason:)`.

## Unflag A Message

Remove the current user's flag from a message when the user reverses the report action.


```kotlin Android
messageRepository
    .unflagMessage(messageId = messageId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleUnflagError(error) },
    )
```

```swift iOS
try await messageRepository.unflagMessage(withId: "message-id")
showSuccessMessage("Message unflagged")
```

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

const unflagged = await MessageRepository.unflagMessage(messageId);

renderResults(unflagged);
```

```dart Flutter
final unflaggedMessage = await AmityChatClient.newMessageRepository()
    .unflag(messageId);

final isFlaggedByMe = unflaggedMessage.isFlaggedByMe;
```


## Check Flag State

TypeScript and iOS can ask the repository for the current user's flag state by message ID. Android and Flutter expose the state on fetched message objects.

Read flag state before rendering selected or disabled report controls.


```kotlin Android
messageRepository
    .getMessage(messageId = messageId)
    .subscribe(
        { fetchedMessage ->
            val isFlaggedByMe = fetchedMessage.isFlaggedByMe()
            updateMessageUI(messageId, isFlaggedByMe)
        },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let isFlaggedByMe = try await messageRepository
    .isMessageFlaggedByMe(withId: "message-id")

showSuccessMessage(isFlaggedByMe)
```

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

const isFlaggedByMe =
  await MessageRepository.isMessageFlaggedByMe(messageId);

updateUI({ isFlaggedByMe });
```

```dart Flutter
final fetchedMessage = await AmityChatClient.newMessageRepository()
    .getMessage(messageId);

final isFlaggedByMe = fetchedMessage.isFlaggedByMe;
```


## Platform Notes

- Reason with optional detail ships in TypeScript 7.29.0 and in the October 2026 iOS and Android releases.
- The Child endangerment reason ships in TypeScript 7.31.0 and in the next Android and iOS releases. Flutter's `AmityContentFlagReason` does not include it.
- On iOS, when you omit `detail`, write the reason with its type, for example `AmityContentFlagReasonType.spamOrScams`. The shorthand `.spamOrScams` on its own selects the deprecated call.
- A flag without a reason is recorded with a default reason: Others on TypeScript and Android, and Against community guidelines on iOS.
- Flutter has no separate `detail`; the reporter's text travels on `AmityContentFlagReason.others(...)`.

## Related Topics

    Refresh list state after flag or unflag actions.
    Modify or soft-delete your own messages.
    Connect message reports to your moderation operating model.

---

### [Unread Status Overview](https://learn.social.plus/social-plus-sdk/chat/engagement-features/unread-status/overview)

> Choose the correct SDK APIs for chat unread counts, read status, delivery status, and receipt sync.

Unread status is the SDK surface for showing unread counts, marking messages read or delivered, and keeping receipt state current while a chat screen is active.

## Capability Map

| Capability | Use it for | SDK page |
| --- | --- | --- |
| Channel unread count | Channel badges, total chat badge, mention indicators. | [Channel Unread Count](./channel-unread-count) |
| Message read status | Mark messages read and inspect read count fields. | [Message Read Status](./message-read-status) |
| Message delivery status | Mark messages delivered and query receipt users where supported. | [Message Delivery Status](./message-delivery-status) |
| Message receipt sync | Subscribe to receipt updates for the active subchannel. | [Message Receipt Sync](./message-receipt-sync) |

## Platform Coverage

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Per-channel unread fields | Supported | Supported | Supported | Supported |
| Total channel unread observer | Supported | Supported | Supported | Supported |
| `message.markRead()` | Supported | Supported | Supported | Supported |
| Mark delivered | Supported | Supported | Supported | Not exposed |
| Query read users | Supported | Supported | Supported | Not exposed |
| Query delivered users | Supported | Supported | Supported | Not exposed |
| Explicit receipt sync start/stop | Supported | Supported | Supported | Not exposed |

  Platform gaps are intentional documentation facts, not missing code snippets. Add a Flutter snippet for delivered users or receipt sync only after the Flutter SDK exposes a public API for that operation.

## Implementation Shape

    Use channel unread fields, total unread observers, mention flags, and message previews.
    Start receipt sync where supported, render messages, and call `message.markRead()` when messages are seen.
    Use read and delivered counts, then query receipt users where the platform exposes those APIs.
    Stop receipt sync when a screen closes or switches to a different subchannel.

## Data Ownership

| Data | Source |
| --- | --- |
| `unreadCount` / `isMentioned` | Channel or subchannel model returned by the SDK. |
| Total unread count | SDK aggregate unread observer for the current user. |
| Read and delivered counts | Message model returned by the SDK. |
| Read and delivered user lists | Receipt-user query APIs where supported. |
| Receipt sync state | Explicit subchannel receipt-sync APIs where supported. |

## Related Topics

    Show latest-message preview data beside unread state.
    Load message models before marking messages read.
    Load channel models for unread count and preview fields.

---

### [Content Moderation Overview](https://learn.social.plus/social-plus-sdk/chat/moderation-safety/content-moderation/overview)

> Connect chat message reports, message removal, and channel governance with the SDK surfaces that support moderation workflows.

Content moderation in the Chat SDK is built from specific client actions: users can flag messages, apps can render flag state from message models, messages can be edited or soft-deleted where supported, and moderators can use channel governance APIs for roles, bans, and mutes.

Keep review policy, escalation rules, audit notes, and compliance workflows in your own product or backend. The SDK supplies the client-side actions and state needed to connect those workflows to chat.

## Capability Map

| Capability | Use it for | SDK page |
| --- | --- | --- |
| Flag a message | Let a signed-in user report a message with a reason. | [Message Flagging](/social-plus-sdk/chat/messaging-features/message-flagging) |
| Unflag a message | Let the current user remove their own report. | [Message Flagging](/social-plus-sdk/chat/messaging-features/message-flagging) |
| Read flag state | Show whether the current user has already flagged a fetched message. | [Message Flagging](/social-plus-sdk/chat/messaging-features/message-flagging) |
| Edit or delete messages | Update supported message types or soft-delete messages. | [Edit & Delete Messages](/social-plus-sdk/chat/messaging-features/messages/edit-and-delete-messages) |
| Query deleted state | Include or exclude deleted messages where the platform exposes the filter. | [Query Messages](/social-plus-sdk/chat/messaging-features/messages/query-and-filter-messages) |
| Channel governance | Manage members, roles, bans, and mutes for channel-level enforcement. | [Channel Governance](/social-plus-sdk/chat/conversation-management/channels/governance/overview) |

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Flag with reason | Supported | Supported | Supported | Supported |
| Unflag | Supported | Supported | Supported | Supported |
| Check current user's flag state | Supported | Supported | Supported on fetched message | Supported on fetched message |
| Soft-delete messages | Supported | Supported | Supported | Supported |
| Query deleted messages | Supported | Supported | Supported | Supported |
| Channel bans and mutes | Supported | Supported | Supported | Supported |

## Moderation Flow

    Call the platform flag API with the message ID and reason selected in your UI.
    Re-read or observe the message when the UI needs current flag, deletion, reaction, or receipt state.
    Treat soft-deleted messages as deleted in your renderer and avoid showing original content.
    Use role, ban, mute, and member APIs when moderation affects participation rather than a single message.

## Product Boundaries

| Concern | SDK surface | Product or backend responsibility |
| --- | --- | --- |
| User report | Message flag and unflag APIs. | Report form copy, reason taxonomy, abuse policy, and user messaging. |
| Message visibility | Message delete state and deleted-message query filters. | Renderer behavior, placeholders, audit copies, and moderator review screens. |
| User enforcement | Channel role, ban, mute, and member APIs. | Appeals, staff permissions, case notes, and cross-channel policy. |
| Automation | Client-visible state after moderation actions. | Automated classifiers, review queues, escalation, and compliance exports. |

## Related Topics

    Flag, unflag, and read the current user's flag state.
    Update or soft-delete supported message types.
    Prevent users from participating in a channel until unbanned.

## Chat — Channels

### [Create Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/create-channel)

> Create community, live, and conversation chat channels with the current SDK APIs.

Use channel creation when your app needs a new chat container before sending messages. The current public SDK creation surface covers community, live, and conversation channels.

For new integrations, let the SDK and server generate channel IDs. Custom channel IDs are not exposed on the current TypeScript, iOS, or Android creation APIs, and Flutter's custom `channelId` builder is deprecated.

## Platform Surface

| Platform | Entry point | Channel types exposed here | Notes |
| --- | --- | --- | --- |
| TypeScript | `ChannelRepository.createChannel(...)` | `community`, `live`, `conversation` | Conversation creation is distinct by membership. |
| iOS | `AmityChannelRepository().createChannel(with:)` | `AmityCommunityChannelCreateOptions`, `AmityLiveChannelCreateOptions`, `AmityConversationChannelCreateOptions` | `AmityConversationChannelCreateOptions` defaults `isDistinct` to `true`. |
| Android | `AmityChatClient.newChannelRepository().createChannel(displayName)` | `.community()`, `.live()`, `.conversation(...)` | Conversation accepts one user ID or a set of user IDs. |
| Flutter | `AmityChatClient.newChannelRepository().createChannel()` | `.communityType()`, `.liveType()`, `.conversationType()` | `withChannelId(...)` exists for community/live but is deprecated. |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| Channel type | Yes | Channel kind to create: community, live, or conversation. |
| `displayName` | Depends | Human-readable channel name; required by Android's entry point and optional on some platform builders. |
| `userIds` / `userId` | Depends | Initial members or conversation target user. Conversation creation requires at least one target user. |
| `tags` | No | App-defined tags for later channel filtering. |
| `metadata` | No | App-defined JSON-style metadata stored with the channel. |
| `isPublic` | No | Community-channel visibility flag where exposed. |
| `isDistinct` | No | Conversation de-duplication flag where exposed; iOS distinct conversations default to `true`. |

## Create A Community Channel

Create a community channel when your app needs a group chat space with optional public visibility, tags, and metadata.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: channel } = await ChannelRepository.createChannel({
  type: 'community',
  displayName: 'Product support',
  userIds: ['user-id'],
  tags: ['support'],
  metadata: {
    queue: 'tier-1',
  },
  isPublic: true,
});

renderResults(channel);
```

```swift iOS
let options = AmityCommunityChannelCreateOptions()
options.setDisplayName("Product support")
options.setUserIds(["user-id"])
options.setTags(["support"])
options.setMetadata(["queue": "tier-1"])
options.setIsChannelPublic(true)

let channel = try await channelRepository.createChannel(with: options)
showSuccessMessage(channel.channelId)
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("queue", "tier-1")
}

val disposable = channelRepository
    .createChannel(displayName = "Product support")
    .community()
    .userIds(listOf(targetUserId))
    .tags(AmityTags(listOf("support")))
    .metadata(metadata)
    .isPublic(true)
    .build()
    .create()
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channel = await AmityChatClient.newChannelRepository()
    .createChannel()
    .communityType()
    .withDisplayName('Product support')
    .userIds([targetUserId])
    .tags(['support'])
    .metadata({'queue': 'tier-1'})
    .isPublic(true)
    .create();

final createdChannelId = channel.channelId;
```


## Create A Conversation Channel

Conversation channels are for one-to-one or small-group private chat. Where the SDK exposes distinct conversation behavior, the default is to return the existing conversation for the same membership instead of creating a duplicate.

Create a conversation channel with one or more target users, and let distinct conversation behavior prevent duplicates where supported.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: conversation } = await ChannelRepository.createChannel({
  type: 'conversation',
  userIds: ['user-id'],
  displayName: 'Support DM',
  tags: ['support'],
});

renderResults(conversation);
```

```swift iOS
let options = AmityConversationChannelCreateOptions()
options.setUserId("user-id")
options.setDisplayName("Support DM")
options.setTags(["support"])
options.setIsDistinct(true)

let conversation = try await channelRepository.createChannel(with: options)
showSuccessMessage(conversation.channelId)
```

```kotlin Android
val disposable = channelRepository
    .createChannel(displayName = "Support DM")
    .conversation(userId = targetUserId)
    .tags(AmityTags(listOf("support")))
    .build()
    .create()
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final conversation = await AmityChatClient.newChannelRepository()
    .createChannel()
    .conversationType()
    .withUserId(targetUserId)
    .displayName('Support DM')
    .tags(['support'])
    .create();

final channelId = conversation.channelId;
```


## Create A Live Channel

Live channels support event-style chat. The platform builders expose optional metadata, tags, and members; iOS and Android also expose live-channel linkage fields such as room or post IDs in their builders.

Create a live channel for event-style chat flows such as livestreams or scheduled events.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: liveChannel } = await ChannelRepository.createChannel({
  type: 'live',
  displayName: 'Launch Q&A',
  userIds: ['user-id'],
  tags: ['event'],
});

renderResults(liveChannel);
```

```swift iOS
let options = AmityLiveChannelCreateOptions()
options.setDisplayName("Launch Q&A")
options.setUserIds(["user-id"])
options.setTags(["event"])

let liveChannel = try await channelRepository.createChannel(with: options)
showSuccessMessage(liveChannel.channelId)
```

```kotlin Android
val disposable = channelRepository
    .createChannel(displayName = "Launch Q&A")
    .live()
    .userIds(listOf(targetUserId))
    .tags(AmityTags(listOf("event")))
    .build()
    .create()
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final liveChannel = await AmityChatClient.newChannelRepository()
    .createChannel()
    .liveType()
    .withDisplayName('Launch Q&A')
    .userIds([targetUserId])
    .tags(['event'])
    .create();

final channelId = liveChannel.channelId;
```


## Related Topics

    Retrieve a single channel or load known channel IDs.
    Build channel lists with type, membership, tag, and deletion filters.
    Change display name, avatar, tags, metadata, or notification mode where supported.
    Manage membership for channels that require explicit joining.

---

### [Get Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/get-channel)

> Retrieve a single chat channel or load known channel IDs with the current SDK APIs.

Use channel retrieval when your app already has a `channelId` and needs the current channel object for message routing, member preview, unread state, or display metadata.

Single-channel retrieval is available on all current SDKs. Batch lookup by channel IDs is exposed on TypeScript, iOS, and Android; the current public Flutter repository does not expose a batch-by-IDs method.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Get one channel | `ChannelRepository.getChannel(channelId, callback)` | `channelRepository.getChannel(channelId)` | `channelRepository.getChannel(channelId)` | `getChannel(channelId)` |
| Result style | Live object callback | `AmityObject<AmityChannel>` | `Flowable<AmityChannel>` | `Future<AmityChannel>` |
| Get channel IDs | `getChannels({ channelIds })` | `getChannels(channelIds:)` | `getChannels(channelIds)` | Not exposed in the current public repository |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Get one channel | `channelId` | Yes | Channel ID to retrieve or observe. |
| Get one channel | Callback / observer | Depends | Required by TypeScript and native live-object APIs to receive loading, error, and data updates. |
| Get one channel | Unsubscriber / token / disposable | No | Handle returned by live APIs; retain it while observing and release it when done. |
| Get known channel IDs | `channelIds` | Yes | List of channel IDs to resolve into channel objects where the platform exposes batch lookup. |

## Get One Channel

Retrieve or observe one channel when your app already has its `channelId`.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannel(
  channelId,
  ({ data: channel, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channel) {
      renderResults(channel);
    }
  },
);

unsubscribe();
```

```swift iOS
let liveChannel = channelRepository.getChannel("channel-id")

token = liveChannel.observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }
    showSuccessMessage(channel.channelId)
}
```

```kotlin Android
val disposable = channelRepository
    .getChannel(channelId = channelId)
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channel = await AmityChatClient.newChannelRepository()
    .getChannel(channelId);

final fetchedChannelId = channel.channelId;
```


## Get Known Channel IDs

Use batch lookup when your app has a small list of known channel IDs and wants the matching channel objects. The collection is not the same as a general channel search; use [Query Channels](./query-channels) when you need filters or pagination.

The current public Flutter `AmityChannelRepository` exposes `getChannel(channelId)` and query builders, but not a batch `getChannels(channelIds)` method.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannels(
  {
    channelIds: [channelId, 'channel-2'],
  },
  ({ data: channels, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channels) {
      renderResults(channels);
    }
  },
);

unsubscribe();
```

```swift iOS
let channelIds = ["channel-1", "channel-2"]
let channels = channelRepository.getChannels(channelIds: channelIds)

token = channels.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
val channelIds = listOf(channelId, "channel-2")

val disposable = channelRepository
    .getChannels(channelIds = channelIds)
    .subscribe(
        { channels -> showSuccessMessage(channels.size) },
        { error -> handleGeneralError(error) },
    )
```


## Related Topics

    Create community, live, or conversation channels.
    Build paginated channel lists from filters.
    Update channel attributes after retrieval.
    Render latest-message preview data from channel objects.

---

### [Query Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/query-channels)

> Query chat channels by type, membership, tags, deletion state, archive state, sort order, or known channel IDs.

Use channel queries to build inboxes, public channel discovery, event chat lists, and moderation views. Query support is similar across platforms, but not identical: TypeScript and Flutter expose keyword/display-name style searching, while Android's public channel query builder focuses on type, membership, tags, and deleted-state filters.

## Filter Surface

| Filter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Types | `types` | `types` | `.types(...)` or type helpers | `.types(...)` or type helpers |
| Membership | `membership` | `filter` | `.filter(...)` where the builder exposes it | `.filter(...)` |
| Tags | `tags`, `excludeTags` | `includingTags`, `excludingTags` | `.includingTags(...)`, `.excludingTags(...)` | `.includingTags(...)`, `.excludingTags(...)` |
| Deleted state | `isDeleted` | `includeDeleted` | `.includeDeleted(...)` | `.includeDeleted(...)` |
| Name or keyword | `displayName` | Not exposed on `AmityChannelQueryOptions` | Not exposed on public query builder | `.withKeyword(...)` |
| Archive exclusion | `excludeArchives` | `excludeArchives` on `AmityChannelQueryOptions` | `.excludeArchived(...)` | `.excludeArchives(...)` |
| Sort | `sortBy` | `sortBy` with `.lastActivity` or `.lastMessage` | `.sortBy(...)` with `LAST_ACTIVITY` or `LAST_MESSAGE` | `.sortBy(...)` with `LAST_ACTIVITY` |
| Known IDs | `channelIds` | `getChannels(channelIds:)` | `getChannels(channelIds)` | Not exposed in the current public repository |

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `types` | No | TypeScript, iOS, Android, Flutter | Channel types to include, such as community, live, or conversation. |
| `membership` / `filter` | No | TypeScript, iOS, Android, Flutter | Restrict results by the current user's relationship to the channel. |
| `tags` / `includingTags` | No | TypeScript, iOS, Android, Flutter | Include channels with specific app-defined tags. |
| `excludeTags` / `excludingTags` | No | TypeScript, iOS, Android, Flutter | Exclude channels with specific app-defined tags. |
| `isDeleted` / `includeDeleted` | No | TypeScript, iOS, Android, Flutter | Include or exclude deleted channels where the platform exposes the filter. |
| `displayName` / `keyword` | No | TypeScript, Flutter | Search by name or keyword where supported by the platform SDK. |
| `excludeArchives` | No | TypeScript, iOS, Android, Flutter | Exclude channels archived by the current user where supported. |
| `sortBy` | No | TypeScript, iOS, Android, Flutter | Sort channel lists where the platform exposes sort options. Choose `lastActivity` (default) or `lastMessage`; see [Sort A Channel List](#sort-a-channel-list). |
| Pagination controls | No | TypeScript, iOS, Android, Flutter | Use collection callbacks, live collections, or paging data to load additional channels. |

## Query A Channel List

Query channels with type, membership, tag, deletion, archive, search, and pagination options where each platform exposes them.


```kotlin Android
val includingTags = AmityTags().apply { add("support") }
val excludingTags = AmityTags().apply { add("hidden") }

val disposable = channelRepository
    .getChannels()
    .types(listOf(AmityChannel.Type.COMMUNITY, AmityChannel.Type.LIVE))
    .filter(AmityChannelFilter.MEMBER)
    .sortBy(AmityChannelSortBy.LAST_MESSAGE)
    .includingTags(includingTags)
    .excludingTags(excludingTags)
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let options = AmityChannelQueryOptions(
    types: Set([AmityChannelQueryType.community, AmityChannelQueryType.live]),
    filter: .userIsMember,
    includingTags: ["support"],
    excludingTags: ["hidden"],
    includeDeleted: false,
    sortBy: .lastMessage
)

let channels = channelRepository.getChannels(with: options)
token = channels.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannels(
  {
    displayName: 'support',
    membership: 'member',
    types: ['community', 'live'],
    tags: ['support'],
    excludeTags: ['hidden'],
    isDeleted: false,
    excludeArchives: true,
    sortBy: 'lastMessage',
  },
  ({ data: channels, onNextPage, hasNextPage, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channels) {
      renderResults(channels);
    }

    if (hasNextPage) onNextPage?.();
  },
);

unsubscribe();
```

```dart Flutter
final liveCollection = AmityChatClient.newChannelRepository()
    .getChannels()
    .withKeyword('support')
    .filter(AmityChannelFilter.MEMBER)
    .types([AmityChannelType.COMMUNITY, AmityChannelType.LIVE])
    .includingTags(['support'])
    .excludingTags(['hidden'])
    .includeDeleted(false)
    .excludeArchives(true)
    .sortBy(AmityChannelSortOption.LAST_ACTIVITY)
    .getLiveCollection();

liveCollection.getStreamController().stream.listen((channels) {
  final count = channels.length;
});

await liveCollection.loadNext();
```


## Sort A Channel List

Use `sortBy` to choose how a channel list is ordered. Choose `lastMessage` for an inbox that should follow the conversation, so that joining or leaving a channel does not push it to the top.

| Value | Order | What moves a channel to the top |
| --- | --- | --- |
| `lastActivity` (default) | Newest activity first | A new message, or a member being added, removed, or banned |
| `lastMessage` | Newest message first | A new message. Membership changes do not reorder the list. |

Each platform names the values in its own style:

| Platform | Option | `lastActivity` | `lastMessage` |
| --- | --- | --- | --- |
| TypeScript | `sortBy` | `'lastActivity'` | `'lastMessage'` |
| iOS | `AmityChannelQueryOptions.sortBy` (`AmityChannelSortBy`) | `.lastActivity` | `.lastMessage` |
| Android | `.sortBy(...)` (`AmityChannelSortBy`) | `LAST_ACTIVITY` | `LAST_MESSAGE` |


```kotlin Android
// Newest message first
val disposable = channelRepository
    .getChannels()
    .all()
    .filter(AmityChannelFilter.MEMBER)
    .sortBy(AmityChannelSortBy.LAST_MESSAGE)
    .build()
    .query()
    .subscribe(
        { pagingData -> submitData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
// Newest message first
let options = AmityChannelQueryOptions(
    filter: .userIsMember,
    sortBy: .lastMessage
)

let channels = channelRepository.getChannels(with: options)
token = channels.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    for channel in collection.snapshots {
        showRow(name: channel.displayName, lastMessageAt: channel.lastMessageAt)
    }
}
```

```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

// Newest message first
const unsubscribe = ChannelRepository.getChannels(
  { membership: 'member', sortBy: 'lastMessage' },
  ({ data: channels, error }) => {
    if (error) handleError(error);

    if (channels) {
      renderResults(channels);
    }
  },
);

unsubscribe();
```


- **Live order.** The collection reorders as messages arrive. When the current user sends a message, that channel moves to the top right away, before the server responds.
- **`lastMessageAt`.** The channel's `lastMessageAt` is the time of its newest message, or its creation time if it has none. Unlike `lastActivity`, membership changes and closing the channel do not change it. It is `null` (`nil` on iOS) when the backend has no value for the channel yet, and those channels are listed last, ordered by creation time. Read it as `channel.getLastMessageAt()` on Android, `channel.lastMessageAt` on iOS, and `channel.lastMessageAt` on TypeScript.
- **Backend support.** `lastMessage` needs backend support for your network. Until it is available, the query fails with HTTP status 422 and error code `500000`. The SDK does not retry and does not fall back to `lastActivity`, so handle the error in your query callback. On iOS, `error.isAmityErrorCode(.business)` identifies it, and on TypeScript the code is `Amity.ServerError.BUSINESS_ERROR`. On Android, the error arrives as `LoadState.Error` in the paging load state, not in the `subscribe` error callback. `AmityError.from(error) == AmityError.BUSINESS_ERROR` identifies it.

Flutter's `sortBy` currently accepts `LAST_ACTIVITY` only. On TypeScript, `sortBy` also accepts `lastCreated`, `firstCreated`, and `displayName`.

## Query A Specific Type

Use the type-specific helpers when the platform exposes them. Some helpers apply membership defaults: for example, Flutter's `conversationType()` and `liveType()` also set the filter to `MEMBER`.

Use type-specific channel queries when your UI needs a focused list such as conversations or live channels.


```kotlin Android
val disposable = channelRepository
    .getChannels()
    .conversationType()
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let options = AmityChannelQueryOptions(
    types: Set([AmityChannelQueryType.conversation]),
    filter: .userIsMember,
    includeDeleted: false
)

let conversations = channelRepository.getChannels(with: options)
showSuccessMessage(conversations)
```

```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannels(
  {
    types: ['conversation'],
    membership: 'member',
    isDeleted: false,
  },
  ({ data: channels }) => {
    renderResults(channels);
  },
);

unsubscribe();
```

```dart Flutter
final conversations = AmityChatClient.newChannelRepository()
    .getChannels()
    .conversationType()
    .includeDeleted(false)
    .excludeArchives(true)
    .getLiveCollection();

conversations.getStreamController().stream.listen((channels) {
  final count = channels.length;
});
```


## Known IDs

If you already have channel IDs, use [Get Channels](./get-channel) instead of a filtered query. Batch get-by-IDs is currently exposed on TypeScript, iOS, and Android.

## Related Topics

    Create a channel before it appears in query results.
    Retrieve a single channel or a known list of IDs.
    Hide or restore archived conversation channels where supported.
    Query members after selecting a channel.

---

### [Update Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/update-channel)

> Update chat channel display name, avatar, tags, metadata, and notification mode where the SDK exposes it.

Use channel updates when the app needs to change channel attributes after creation. Keep updates narrow: send only fields that actually changed, because metadata and tag updates replace the submitted values rather than merging app-side state for you.

## Update Surface

| Field | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Display name | `displayName` | `setDisplayName(...)` | `.displayName(...)` | `.displayName(...)` |
| Avatar | `avatarFileId` | `setAvatar(...)` | `.avatar(...)` | `.avatar(...)` |
| Tags | `tags` | `setTags(...)` | `.tags(...)` | `.tags(...)` |
| Metadata | `metadata` | `setMetadata(...)` | `.metadata(...)` | `.metadata(...)` |
| Notification mode | `notificationMode` | `setNotificationMode(_:)` on `AmityChannelUpdateOptions` | `.notificationMode(...)` on the edit builder | `.notificationMode(...)` |

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `channelId` | Yes | TypeScript, iOS, Android, Flutter | Channel ID to update. |
| `displayName` | No | TypeScript, iOS, Android, Flutter | Replacement channel display name. |
| `avatarFileId` / `avatar` | No | TypeScript, iOS, Android, Flutter | Replacement avatar file reference where supported. |
| `tags` | No | TypeScript, iOS, Android, Flutter | Replacement tag list for the channel. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Replacement metadata stored with the channel. |
| `notificationMode` | No | TypeScript, iOS, Android, Flutter | Per-channel notification mode: `default`, `silent`, or `subscribe`. Exposed on all four platforms. |

## Update Channel Fields

Update channel profile fields such as display name, avatar, tags, or metadata where the platform exposes those setters.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: updatedChannel } = await ChannelRepository.updateChannel(
  channelId,
  {
    displayName: 'Support desk',
    tags: ['support', 'active'],
    metadata: {
      queue: 'tier-2',
    },
  },
);

renderResults(updatedChannel);
```

```swift iOS
let options = AmityChannelUpdateOptions(channelId: "channel-id")
options.setDisplayName("Support desk")
options.setTags(["support", "active"])
options.setMetadata(["queue": "tier-2"])

let channel = try await channelRepository.editChannel(with: options)
showSuccessMessage(channel.channelId)
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("queue", "tier-2")
}

val disposable = channelRepository
    .editChannel(channelId = channelId)
    .displayName("Support desk")
    .tags(AmityTags(listOf("support", "active")))
    .metadata(metadata)
    .build()
    .apply()
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channel = await AmityChatClient.newChannelRepository()
    .updateChannel(channelId)
    .displayName('Support desk')
    .tags(['support', 'active'])
    .metadata({'queue': 'tier-2'})
    .create();

final updatedChannelId = channel.channelId;
```


## Update Notification Mode

The channel update API exposes notification mode on all four platforms. The available values are `default`, `silent`, and `subscribe`. Use the dedicated [channel notification settings](../../push-notifications/settings/channel-settings) for broader notification configuration.


```typescript TypeScript
import {
  AmityChannelNotificationModeEnum,
  ChannelRepository,
} from '@amityco/ts-sdk';

const { data: channel } = await ChannelRepository.updateChannel(
  channelId,
  {
    notificationMode: AmityChannelNotificationModeEnum.Silent,
  },
);

renderResults(channel);
```

```swift iOS
let options = AmityChannelUpdateOptions(channelId: "channel-id")
options.setNotificationMode(.silent)

let channel = try await channelRepository.editChannel(with: options)
showSuccessMessage(channel.channelId)
```

```kotlin Android
val disposable = channelRepository
    .editChannel(channelId = channelId)
    .notificationMode(AmityChannelNotificationMode.SILENT)
    .build()
    .apply()
    .subscribe(
        { channel -> showSuccessMessage(channel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channel = await AmityChatClient.newChannelRepository()
    .updateChannel(channelId)
    .notificationMode(NotificationMode.silent)
    .create();

final notificationMode = channel.notificationMode;
```


## Related Topics

    Observe the updated channel object.
    Refresh channel lists after an update.
    Configure channel notification settings.
    Manage membership separately from channel attributes.

---

### [Archive Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/archive-channels)

> Archive, unarchive, and query archived chat channels where the current SDK exposes archive APIs.

Archiving is a per-user chat-list operation. It hides a channel from the active list for the current user without deleting the channel or its messages. Archive APIs are available on TypeScript, iOS, Android, and Flutter.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Archive | `ChannelRepository.archiveChannel(channelId)` | `channelRepository.archiveChannel(channelId:)` | `channelRepository.archiveChannel(channelId)` | `archiveChannel(channelId)` |
| Unarchive | `ChannelRepository.unarchiveChannel(channelId)` | `channelRepository.unarchiveChannel(channelId:)` | `channelRepository.unarchiveChannel(channelId)` | `unarchiveChannel(channelId)` |
| Query archived channels | `ChannelRepository.getArchivedChannels(...)` | `getArchivedChannels()` or `getArchivedChannelIds()` | `getArchivedChannels()` or `getArchivedChannelIds()` | `getArchivedChannels()` |

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Archive | `channelId` | Yes | TypeScript, iOS, Android, Flutter | Channel ID to hide from the current user's active channel list. |
| Unarchive | `channelId` | Yes | TypeScript, iOS, Android, Flutter | Archived channel ID to restore to the active channel list. |
| Query archived channels | `limit` | No | TypeScript | TypeScript collection page size. |
| Query archived channels | Pagination controls | No | TypeScript, iOS, Flutter | Use TypeScript collection callbacks, `nextPage()` on the iOS `AmityCollection`, or Flutter live collection loading. Android's `getArchivedChannels()` emits the full list on each update, so there is nothing to page. |

## Archive Or Unarchive

Archive or unarchive a channel for the current user when the platform exposes archive state.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

await ChannelRepository.archiveChannel(channelId);
await ChannelRepository.unarchiveChannel(channelId);
```

```swift iOS
try await channelRepository.archiveChannel(channelId: "channel-id")
try await channelRepository.unarchiveChannel(channelId: "channel-id")
```

```kotlin Android
channelRepository.archiveChannel(channelId = channelId)
    .subscribe()

channelRepository.unarchiveChannel(channelId = channelId)
    .subscribe()
```

```dart Flutter
final repository = AmityChatClient.newChannelRepository();

await repository.archiveChannel(channelId);
await repository.unarchiveChannel(channelId);
```


## Query Archived Channels

Use the archived-channel collection for an archived inbox. The TypeScript API accepts live collection parameters such as `limit`; the Flutter API returns a live collection stream for the current user.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getArchivedChannels(
  {
    limit: 20,
  },
  ({ data: channels, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channels) {
      renderResults(channels);
    }
  },
);

unsubscribe();
```

```swift iOS
// A live collection of archived channels.
let archivedChannels = channelRepository.getArchivedChannels()
token = archivedChannels.observe { collection, error in
    renderResults(collection.snapshots)
}

// Or just the archived channel IDs.
let ids = try await channelRepository.getArchivedChannelIds()
```

```kotlin Android
// A stream of archived channels.
channelRepository.getArchivedChannels()
    .subscribe(
        { channels: List<AmityChannel> -> renderResults(channels) },
        { error -> handleGeneralError(error) },
    )

// Or just the archived channel IDs.
channelRepository.getArchivedChannelIds()
    .subscribe(
        { channelIds: List<String> -> renderResults(channelIds) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final archivedChannels = AmityChatClient.newChannelRepository()
    .getArchivedChannels();

archivedChannels.getStream().listen((event) {
  final channels = event.data;
  final isFetching = event.isFetching;
});

await archivedChannels.loadNext();
```


## Notes

| Topic | Current SDK guidance |
| --- | --- |
| Scope | Archive state belongs to the current user's archived-channel list. |
| Messages | Archiving is not message deletion. Use message delete APIs for message lifecycle changes. |
| Channel deletion | Archiving is separate from channel deletion or soft deletion. |
| Query shape | Every platform returns archived channels as a collection or stream. iOS and Android also expose an IDs-only variant, `getArchivedChannelIds()`. |

## Related Topics

    Use `excludeArchives` where the platform query supports it.
    Resolve an archived channel by ID before opening it.
    Delete messages instead of hiding a channel.
    Update channel display and metadata separately from archive state.

## Chat — Channel Governance

### [Member Management](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/governance/member-management)

> Add and remove chat channel members with the current SDK APIs.

Use member management when your app needs to add users to a channel or remove users from a channel. Channel type, membership rules, and moderator permissions can still determine whether a request is accepted by the server.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Add members | `ChannelRepository.Membership.addMembers(channelId, userIds)` | `AmityChannelMembership(channelId:).addMembers(_:)` | `membership(channelId).addMembers(userIds)` | `addMembers(channelId, userIds)` |
| Remove members | `ChannelRepository.Membership.removeMembers(channelId, userIds)` | `AmityChannelMembership(channelId:).removeMembers(_:)` | `membership(channelId).removeMembers(userIds)` | `removeMembers(channelId, userIds)` |
| Result | `Promise<boolean>` | `Void` | `Completable` | `Future` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel ID whose membership should change. |
| `userIds` | Yes | One or more user IDs to add or remove. Empty lists are rejected. |
| Membership permission | Yes | The current user must be allowed to manage members for the target channel. |

## Add Members

Add members when an existing channel should include additional users. For conversation channels, prefer the conversation creation APIs when creating the conversation membership for the first time.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didAdd = await ChannelRepository.Membership.addMembers(channelId, [
  userId,
]);

if (didAdd) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let membership = AmityChannelMembership(channelId: channelId)

try await membership.addMembers([userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .membership(channelId = channelId)
    .addMembers(userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .addMembers(channelId, [targetUserId]);
```


## Remove Members

Remove members when users should no longer participate in the channel. If the user is currently viewing the channel, update the route or composer state after removal succeeds.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didRemove = await ChannelRepository.Membership.removeMembers(channelId, [
  userId,
]);

if (didRemove) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let membership = AmityChannelMembership(channelId: channelId)

try await membership.removeMembers([userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .membership(channelId = channelId)
    .removeMembers(userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .removeMembers(channelId, [targetUserId]);
```


## Implementation Notes

    All platforms accept a list of user IDs, so use one call for a small batch instead of looping one user at a time.
    Some channel types or roles can reject member changes. Treat failures as server authority, not as local state to override.
    Use join and leave APIs when the current user is entering or exiting a channel themselves.
    Query members after add or remove operations when your UI needs confirmed membership, role, or banned-state data.

## Related Topics

    Let the current user join or leave a channel.
    Retrieve and filter channel membership.
    Assign channel roles to members.

---

### [Role Management](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/governance/role-management)

> Add and remove chat channel roles with the current SDK APIs.

Use channel roles when selected members need elevated channel permissions, such as moderator behavior. Role names are app-defined or configured for your social.plus project; the SDK applies or removes the role for the listed channel members.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Add role | `ChannelRepository.Moderation.addRole(channelId, roleId, userIds)` | `AmityChannelModeration(channelId:).addRole(_:userIds:)` | `moderation(channelId).addRole(role, userIds)` | `moderation(channelId).addRole(role, userIds)` |
| Remove role | `ChannelRepository.Moderation.removeRole(channelId, roleId, userIds)` | `AmityChannelModeration(channelId:).removeRole(_:userIds:)` | `moderation(channelId).removeRole(role, userIds)` | `moderation(channelId).removeRole(role, userIds)` |
| Result | `Promise<boolean>` | `Void` | `Completable` | `Future` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel ID where the role should be changed. |
| `role` / `roleId` | Yes | Role ID to add or remove, such as `moderator` or another role configured for your app. |
| `userIds` | Yes | One or more member user IDs. Empty lists are rejected. |
| Moderation permission | Yes | The current user must have permission to manage roles in the target channel. |

## Add A Role

Add a role when channel members should receive the permissions represented by that role.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didAddRole = await ChannelRepository.Moderation.addRole(
  channelId,
  'moderator',
  [userId],
);

if (didAddRole) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)

try await moderation.addRole("moderator", userIds: [userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .moderation(channelId = channelId)
    .addRole(role = "moderator", userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .addRole('moderator', [targetUserId]);
```


## Remove A Role

Remove a role when members should no longer have the permissions represented by that role.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didRemoveRole = await ChannelRepository.Moderation.removeRole(
  channelId,
  'moderator',
  [userId],
);

if (didRemoveRole) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)

try await moderation.removeRole("moderator", userIds: [userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .moderation(channelId = channelId)
    .removeRole(role = "moderator", userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .removeRole('moderator', [targetUserId]);
```


## Implementation Notes

    Pass the role ID string exactly as configured for your project. The SDK does not create new role definitions from this call.
    Assign roles to users who are channel members. Query the member list first when your UI needs to confirm eligibility.
    Role operations require moderation permission and can fail if the current user cannot manage the target role.
    Role moderation is meaningful on channel types that support member roles. Unsupported channel types can reject the request.

## Related Topics

    Add users before assigning channel roles.
    Filter members by role and membership state.
    Restrict access for users who should not participate.

---

### [Ban Management](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/governance/ban-management)

> Ban and unban chat channel members with the current SDK APIs.

Use channel bans when a member should lose access to a specific chat channel until a moderator restores access. The SDK operation is per-channel; ban reasons, appeal flows, and moderation audit logs are app-owned product logic.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Ban members | `ChannelRepository.Moderation.banMembers(channelId, userIds)` | `AmityChannelModeration(channelId:).banMembers(_:)` | `moderation(channelId).banMembers(userIds)` | `moderation(channelId).banMembers(userIds)` |
| Unban members | `ChannelRepository.Moderation.unbanMembers(channelId, userIds)` | `AmityChannelModeration(channelId:).unbanMembers(_:)` | `moderation(channelId).unbanMembers(userIds)` | `moderation(channelId).unbanMembers(userIds)` |
| Result | Cached channel memberships | `Void` | `Completable` | `Future` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel ID where the ban or unban should be applied. |
| `userIds` | Yes | One or more user IDs to ban or unban. Empty lists are rejected. |
| Moderation permission | Yes | The current user must have permission to moderate the target channel. |

## Ban Members

Ban removes the users from channel participation and prevents them from rejoining until they are unbanned.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const banned = await ChannelRepository.Moderation.banMembers(channelId, [
  userId,
]);

renderResults(banned.data);
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)

try await moderation.banMembers([userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .moderation(channelId = channelId)
    .banMembers(userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .banMembers([targetUserId]);
```


## Unban Members

Unban restores the users to the channel's allowed membership state. If your app shows a ban list, refresh that list after the operation succeeds.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unbanned = await ChannelRepository.Moderation.unbanMembers(channelId, [
  userId,
]);

renderResults(unbanned.data);
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)

try await moderation.unbanMembers([userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .moderation(channelId = channelId)
    .unbanMembers(userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .unbanMembers([targetUserId]);
```


## Implementation Notes

    The SDK call can fail when the current user cannot moderate the channel or the target user cannot be moderated. Handle permission and validation errors in your UI.
    A channel ban applies to the target channel. It is not a global user block and does not replace user-level block or content flag workflows.
    Store ban reasons, moderator notes, appeal state, or compliance records in your own system if your product requires them.
    Query channel members with banned-membership filters when you need to render a ban list or confirm current ban state.

## Related Topics

    Filter channel members by membership state.
    Temporarily restrict message sending.
    Add or remove channel members.

---

### [Mute Management](https://learn.social.plus/social-plus-sdk/chat/conversation-management/channels/governance/mute-management)

> Mute and unmute chat channel members with the current SDK APIs.

Use member mute when a user should keep channel access but lose the ability to send messages for a period of time. Mute duration units differ by platform, so pass the value in the unit expected by the SDK you are using.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Mute members | `ChannelRepository.Moderation.muteMembers(channelId, userIds, mutePeriod?)` | `AmityChannelModeration(channelId:).muteMembers(_:mutePeriod:)` | `moderation(channelId).muteMembers(timeout, userIds)` | `moderation(channelId).muteMembers(userIds, millis:)` |
| Unmute members | `ChannelRepository.Moderation.unmuteMembers(channelId, userIds)` | `AmityChannelModeration(channelId:).unmuteMembers(_:)` | `moderation(channelId).unmuteMembers(userIds)` | `moderation(channelId).unmuteMembers(userIds)` |
| Duration unit | Seconds; omit for indefinite mute | Seconds | `org.joda.time.Duration` | Milliseconds; defaults to 600000 |
| Result | `Promise<boolean>` | `Void` | `Completable` | `Future` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel ID where the mute or unmute should be applied. |
| `userIds` | Yes | One or more user IDs to mute or unmute. Empty lists are rejected. |
| `mutePeriod` / `timeout` / `millis` | Mute only | Duration of the mute. TypeScript and iOS take seconds, Android takes a `Duration`, and Flutter takes milliseconds. |
| Moderation permission | Yes | The current user must have permission to moderate the target channel. |

## Mute Members

Mute members when you want a temporary or indefinite send-message restriction without removing channel access. TypeScript's omitted `mutePeriod` means an indefinite mute until unmuted.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const tenMinutesInSeconds = 10 * 60;

const didMute = await ChannelRepository.Moderation.muteMembers(
  channelId,
  [userId],
  tenMinutesInSeconds,
);

if (didMute) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)
let tenMinutesInSeconds = 10 * 60

try await moderation.muteMembers([userId], mutePeriod: tenMinutesInSeconds)

showSuccessMessage(channelId)
```

```kotlin Android
val tenMinutes = org.joda.time.Duration.standardMinutes(10)

val disposable = channelRepository
    .moderation(channelId = channelId)
    .muteMembers(timeout = tenMinutes, userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
const tenMinutesInMillis = 10 * 60 * 1000;

await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .muteMembers([targetUserId], millis: tenMinutesInMillis);
```


## Unmute Members

Unmute restores the users' ability to send messages in the channel.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didUnmute = await ChannelRepository.Moderation.unmuteMembers(channelId, [
  userId,
]);

if (didUnmute) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let moderation = AmityChannelModeration(channelId: channelId)

try await moderation.unmuteMembers([userId])

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = channelRepository
    .moderation(channelId = channelId)
    .unmuteMembers(userIds = listOf(targetUserId))
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
await AmityChatClient.newChannelRepository()
    .moderation(channelId)
    .unmuteMembers([targetUserId]);
```


## Duration Notes

    Pass seconds. Omit `mutePeriod` to mute indefinitely until a later `unmuteMembers` call.
    Pass seconds through `mutePeriod`. The SDK converts the value before sending the request.
    Pass an `org.joda.time.Duration`, such as `Duration.standardMinutes(10)`.
    Pass milliseconds through `millis`. If omitted, the current public SDK default is 600000 milliseconds.

## Related Topics

    Remove channel access until a user is unbanned.
    Filter members by muted or banned membership states.
    Send messages after membership and moderation checks pass.

## Chat — Members

### [Join and Leave Channels](https://learn.social.plus/social-plus-sdk/chat/conversation-management/members/join-leave-channel)

> Add the current user to a chat channel, remove them from a channel, and observe current membership state with the current SDK APIs.

Use join and leave operations when the current user needs to enter or exit an existing channel. Joining does not create a missing channel, and conversation channels are already membership-managed by the SDK, so calling join or leave on a conversation channel can fail on platforms that enforce that restriction.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Join channel | `ChannelRepository.joinChannel(channelId)` | `channelRepository.joinChannel(channelId:)` | `joinChannel(channelId)` | `joinChannel(channelId)` |
| Leave channel | `ChannelRepository.leaveChannel(channelId)` | `channelRepository.leaveChannel(channelId:)` | `leaveChannel(channelId)` | `leaveChannel(channelId)` |
| Join result | `Promise<boolean>` | `AmityChannel` | `Single<AmityChannel>` | `Future` |
| Leave result | `Promise<boolean>` | `Void` | `Completable` | `Future` |
| Current membership | `channel.myMembership(callback)` | `channel.currentUserMembership` or `channel.myMembership()` | `membership(channelId).getMyMembership()` | `membership(channelId).getMyMembership()` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Join channel | `channelId` | Yes | Existing channel ID that the current user should join. |
| Leave channel | `channelId` | Yes | Channel ID that the current user should leave. |
| Check membership | `channelId` | Yes | Channel ID whose current-user membership should be inspected. |
| Check membership | Channel object | Depends | TypeScript and iOS can also read membership state from an observed channel object. |
| Check membership | Observer / disposable | Depends | Required by live APIs when observing channel or membership changes. |

## Join A Channel

Join adds the current user as a member of an existing channel. On iOS, joining an already joined channel returns the existing channel. On TypeScript, the API returns `true` when the returned membership is `member`.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didJoin = await ChannelRepository.joinChannel(channelId);

if (didJoin) {
  showSuccessMessage(channelId);
}
```

```swift iOS
let joinedChannel = try await channelRepository.joinChannel(channelId: channelId)

showSuccessMessage(joinedChannel.channelId)
```

```kotlin Android
val disposable = AmityChatClient.newChannelRepository()
    .joinChannel(channelId = channelId)
    .subscribe(
        { joinedChannel -> showSuccessMessage(joinedChannel.getChannelId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channelRepository = AmityChatClient.newChannelRepository();

await channelRepository.joinChannel(channelId);
```


## Leave A Channel

Leave removes the current user's membership from the channel. After leaving, stop routing the user into the channel UI and refresh any channel list or unread-count state that depends on membership.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const didLeave = await ChannelRepository.leaveChannel(channelId);

if (didLeave) {
  showSuccessMessage(channelId);
}
```

```swift iOS
try await channelRepository.leaveChannel(channelId: channelId)

showSuccessMessage(channelId)
```

```kotlin Android
val disposable = AmityChatClient.newChannelRepository()
    .leaveChannel(channelId = channelId)
    .subscribe(
        { showSuccessMessage(channelId) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final channelRepository = AmityChatClient.newChannelRepository();

await channelRepository.leaveChannel(channelId);
```


## Check Current Membership

Use current membership state to hide composer controls, redirect banned users, or distinguish a channel that is only visible from one the user has joined.


```typescript TypeScript
const unsubscribe = channel.myMembership(({ data: membership, error }) => {
  if (error) handleError(error);

  if (membership?.membership === 'banned') {
    updateUI(membership);
  }
});

unsubscribe();
```

```swift iOS
var token: AmityNotificationToken?

token = channelRepository.getChannel(channelId).observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }

    switch channel.currentUserMembership {
    case .member:
        showSuccessMessage("member")
    case .banned:
        showSuccessMessage("banned")
    case .none:
        showSuccessMessage("none")
    @unknown default:
        break
    }
}
```

```kotlin Android
val disposable = AmityChatClient.newChannelRepository()
    .membership(channelId = channelId)
    .getMyMembership()
    .subscribe(
        { membership ->
            when (membership.getMembershipType()) {
                AmityMembershipType.MEMBER -> showSuccessMessage("member")
                AmityMembershipType.BANNED -> showSuccessMessage("banned")
                AmityMembershipType.NONE -> showSuccessMessage("none")
            }
        },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final membership = await AmityChatClient.newChannelRepository()
    .membership(channelId)
    .getMyMembership();

final isBanned = membership.isBanned == true;
```


## Related Topics

    Retrieve and filter channel members.
    Render lightweight participant previews where the SDK exposes them.
    Load channel objects before routing users into a chat screen.
    Handle moderation states that affect membership.

---

### [Query Channel Members](https://learn.social.plus/social-plus-sdk/chat/conversation-management/members/query-members)

> Retrieve and search chat channel members with the current SDK filters, roles, deletion, and sorting APIs.

Use member queries for member lists, mention pickers, moderation screens, and channel participant management. All current SDKs expose channel member query and search APIs, but the filter names are not identical across platforms.

## Platform Surface

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Query members | `ChannelRepository.Membership.getMembers(params, callback)` | `AmityChannelMembership.getMembers(...)` | `membership(channelId).getMembers()` | `membership(channelId).getMembers()` |
| Search members | `searchMembers({ search })` | `searchMembers(displayName:filterBuilder:roles:)` | `searchMembers(keyword)` | `searchMembers(keyword)` |
| Status filter | `memberships` | `AmityChannelMembershipFilter` | `AmityChannelMembershipFilter` | Query: `AmityChannelMembershipFilter`; search: `AmityChannelMembership` |
| Role filter | `roles` | `roles` | `roles(...)` | `roles(...)` |
| Include deleted users | `includeDeleted` | `includeDeleted` | `includeDeleted(...)` | `includeDeleted(...)` |
| Sort | `firstCreated`, `lastCreated` | `.firstCreated`, `.lastCreated` | `FIRST_CREATED`, `LAST_CREATED` | `FIRST_CREATED`, `LAST_CREATED` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Query members | `channelId` | Yes | Channel ID whose members should be queried. |
| Query members | `memberships` / `filter` | No | Membership status filter, such as member, banned, muted, or all depending on platform. |
| Query members | `roles` | No | Channel role filters, such as `moderator`. |
| Query members | `includeDeleted` | No | Whether deleted user records should be included. |
| Query members | `sortBy` | No | Member ordering, such as first-created or last-created. |
| Query members | `limit` / page size | No | Page size for paginated member lists. |
| Search members | `search` / `displayName` / `keyword` | Yes | Search term used to find members by display name. |
| Search members | `memberships` / `membershipFilter` | No | Membership status filter for search results. |
| Search members | `roles` | No | Role filters applied to search results. |

## Query Members

Query members when you need a paginated channel member list. The default sort is newest first on platforms that define a default.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.Membership.getMembers(
  {
    channelId,
    memberships: ['member'],
    roles: ['moderator'],
    sortBy: 'lastCreated',
    includeDeleted: false,
    limit: 20,
  },
  ({ data: members, loading, error, hasNextPage, onNextPage }) => {
    if (error) handleError(error);

    if (!loading && members) {
      renderResults({ members, hasNextPage, onNextPage });
    }
  },
);

unsubscribe();
```

```swift iOS
var token: AmityNotificationToken?

let membership = AmityChannelMembership(channelId: channelId)
let members = membership.getMembers(
    filter: .all,
    sortBy: .lastCreated,
    roles: ["moderator"],
    includeDeleted: false
)

token = members.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
val disposable = AmityChatClient.newChannelRepository()
    .membership(channelId = channelId)
    .getMembers()
    .filter(filter = AmityChannelMembershipFilter.ALL)
    .roles(roles = listOf("moderator"))
    .includeDeleted(includeDeleted = false)
    .sortBy(sortOption = AmityChannelMembershipSortOption.LAST_CREATED)
    .build()
    .query()
    .subscribe(
        { members: PagingData<AmityChannelMember> -> showSuccessMessage(members) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final controller = PagingController<AmityChannelMember>(
  pageFuture: (token) => AmityChatClient.newChannelRepository()
      .membership(channelId)
      .getMembers()
      .filter(AmityChannelMembershipFilter.ALL)
      .roles(['moderator'])
      .includeDeleted(false)
      .sortBy(AmityMembershipSortOption.LAST_CREATED)
      .getPagingData(token: token, limit: 20),
  pageSize: 20,
);

controller.fetchNextPage();
```


## Search Members

Search members when the user enters a display-name keyword, such as in a mention picker. TypeScript names this parameter `search`; Android and Flutter name it `keyword`; iOS names it `displayName`.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.Membership.searchMembers(
  {
    channelId,
    search: 'alex',
    memberships: ['member'],
    roles: ['moderator'],
    includeDeleted: false,
    limit: 20,
  },
  ({ data: members, error }) => {
    if (error) handleError(error);

    if (members) {
      renderResults(members);
    }
  },
);

unsubscribe();
```

```swift iOS
var token: AmityNotificationToken?

let membership = AmityChannelMembership(channelId: channelId)
let filterBuilder = AmityChannelMembershipFilterBuilder()
filterBuilder.add(filter: .member)

let searchResults = membership.searchMembers(
    displayName: "alex",
    filterBuilder: filterBuilder,
    roles: ["moderator"],
    includeDeleted: false
)

token = searchResults.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.api.chat.member.query.AmityChannelMembership

val disposable = AmityChatClient.newChannelRepository()
    .membership(channelId = channelId)
    .searchMembers(keyword = "alex")
    .membershipFilter(channelMembership = listOf(AmityChannelMembership.MEMBER))
    .roles(roles = listOf("moderator"))
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { members: PagingData<AmityChannelMember> -> showSuccessMessage(members) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final members = await AmityChatClient.newChannelRepository()
    .membership(channelId)
    .searchMembers('alex')
    .membershipFilter([AmityChannelMembership.MEMBER])
    .roles(['moderator'])
    .includeDeleted(false)
    .sortBy(AmityMembershipSortOption.LAST_CREATED)
    .query(limit: 20);
```


## Filter Notes

    TypeScript accepts `memberships: ['member' | 'banned' | 'muted']`. Android query uses `AmityChannelMembershipFilter.ALL`, `MEMBER`, or `BANNED`; Android search uses `AmityChannelMembership`. Flutter query uses `AmityChannelMembershipFilter.ALL`, `MUTED`, or `BANNED`; Flutter search uses `AmityChannelMembership`.
    `includeDeleted: false` filters deleted users out of the result. iOS defaults this argument to `true`, so pass `false` when you want only active user records.
    Role filters match channel roles assigned to members, such as `moderator` or custom roles configured for your app.
    TypeScript live collections expose `hasNextPage` and `onNextPage`; Android returns `PagingData`; Flutter uses `PagingController` or `getPagingData`.

## Related Topics

    Manage the current user's channel membership.
    Display a lightweight set of participant avatars.
    Add or remove other users from a channel.
    Moderate channel membership state.

---

### [Preview Channel Members](https://learn.social.plus/social-plus-sdk/chat/conversation-management/members/preview-members)

> Display lightweight channel member previews where the current SDK exposes preview members.

Preview members are a small set of members attached to a channel object for compact UI surfaces such as channel rows, headers, and avatar stacks. In the current public SDKs, direct channel-level preview members are exposed by TypeScript and iOS. Android and Flutter do not expose a direct `previewMembers` channel property, so use [Query Channel Members](./query-members) and render the first few results when you need the same UI pattern.

## Platform Surface

| Platform | Direct preview member surface | Notes |
| --- | --- | --- |
| TypeScript | `channel.previewMembers` | Populated on `conversation` and `community` channels from cached channel members, up to 4 members. |
| iOS | `channel.previewMembers` | Returns up to 4 members for conversation and enabled community channel previews. |
| Android | Not exposed on `AmityChannel` | Query channel members and render the first few results. |
| Flutter | Not exposed on `AmityChannel` | Query channel members and render the first few results. |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Read preview members | `channelId` | Yes | Channel ID to fetch before reading preview members. |
| Read preview members | `previewMembers` | Read-only | Lightweight member list exposed on supported channel objects. |
| Fallback preview query | `channelId` | Yes | Channel ID whose members should be queried for preview rendering. |
| Fallback preview query | `filter` | No | Membership filter for the member query. |
| Fallback preview query | `includeDeleted` | No | Whether deleted users should be included in the fallback member query. |
| Fallback preview query | `sortBy` | No | Member ordering for the fallback preview list. |
| Fallback preview query | `limit` / page size | No | Small page size for avatar stacks or compact participant previews. |

## Read Preview Members

Fetch or observe the channel first, then read the preview members from the returned channel object.

Android and Flutter do not expose a direct channel-level `previewMembers` property. Query channel members and render a small first page when you need avatar-stack style previews.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannel(
  channelId,
  ({ data: channel, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channel) {
      renderResults(channel.previewMembers);
    }
  },
);

unsubscribe();
```

```swift iOS
var token: AmityNotificationToken?

token = channelRepository.getChannel(channelId).observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }

    let previewMembers = channel.previewMembers
    showSuccessMessage(previewMembers.count)
}
```


## Fallback Preview Query

Use this approach on Android and Flutter, or anywhere you need filtering that the channel-level preview does not provide.


```kotlin Android
val disposable = AmityChatClient.newChannelRepository()
    .membership(channelId = channelId)
    .getMembers()
    .filter(filter = AmityChannelMembershipFilter.ALL)
    .includeDeleted(includeDeleted = false)
    .sortBy(sortOption = AmityChannelMembershipSortOption.LAST_CREATED)
    .build()
    .query()
    .subscribe(
        { members: PagingData<AmityChannelMember> -> showSuccessMessage(members) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final controller = PagingController<AmityChannelMember>(
  pageFuture: (token) => AmityChatClient.newChannelRepository()
      .membership(channelId)
      .getMembers()
      .filter(AmityChannelMembershipFilter.ALL)
      .includeDeleted(false)
      .sortBy(AmityMembershipSortOption.LAST_CREATED)
      .getPagingData(token: token, limit: 4),
  pageSize: 4,
);

controller.fetchNextPage();
```


## Related Topics

    Load the channel object that carries preview members on supported platforms.
    Retrieve paginated members for full member lists and fallback previews.
    Display latest-message previews beside member preview UI.
    Build channel lists that use preview members in row layouts.

## Chat — Messaging

### [Send a Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/send-a-message)

> Choose the right SDK create-message API for each chat message type.

Use message creation APIs after your app has resolved the target `subChannelId`. Text and custom messages send structured data directly. Media messages send an uploaded file ID, attachment object, or file URI depending on platform.

    Send plain text with optional tags, metadata, mentions, and reply parent IDs.
    Send image messages with platform-specific file ID, attachment, or URI input.
    Send generic file attachments.
    Send video attachments where the platform SDK supports video message creation.
    Send audio attachments on TypeScript, iOS, and Android.
    Send app-defined JSON-style message payloads.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the message will be created. |
| Message type | Yes | SDK-specific message type selector, such as `dataType: 'text'`, `createTextMessage(...)`, or `.text(...)`. |
| Message body | Depends | Required for text and custom messages; use text strings or JSON-serializable custom payloads. |
| Media input | Depends | Required for media messages; use a TypeScript file ID, native attachment, or Flutter `Uri` depending on platform. |
| `parentId` | No | Parent message ID when creating a reply instead of a top-level message. |
| `tags` | No | App-defined tags for later filtering or grouping. |
| `metadata` | No | App-defined JSON-style metadata stored with the message. |

## Send A Text Message

Create a text message after resolving the target `subChannelId`.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'text',
  data: {
    text: 'Hello from chat',
  },
});

renderResults(message);
```

```swift iOS
let options = AmityTextMessageCreateOptions(
    subChannelId: "sub-channel-id",
    text: "Hello from chat"
)

let message = try await messageRepository.createTextMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val disposable = AmityChatClient.newMessageRepository()
    .createTextMessage(
        subChannelId = subChannelId,
        text = "Hello from chat",
    )
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .text('Hello from chat')
    .send();

final messageId = message.messageId;
```


## Return Shapes

| Platform | Create call result |
| --- | --- |
| TypeScript | Resolves to `{ data: Amity.Message, cachedAt?: number }` |
| iOS | Returns `AmityMessage` from the async repository call |
| Android | Returns a `Completable`; observe the message list for the created message |
| Flutter | Returns `Future<AmityMessage>` |

## Related Topics

    Add text, tags, metadata, mentions, and replies.
    Use `parentId` to create message replies.
    Observe sent messages in the target subchannel.
    Add report actions to sent or received messages.

---

### [Text Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/text-message)

> Send text chat messages with optional tags, metadata, mentions, and replies.

Use text messages for standard chat content. All SDKs support creating text messages by `subChannelId`; optional fields such as `tags`, `metadata`, `mentionees`, and `parentId` are available through platform-specific payloads or builders.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the text message will be created. |
| `text` | Yes | Plain text content for the message. |
| `tags` | No | App-defined tags that can be used by message queries. |
| `metadata` | No | App-defined JSON-style metadata stored with the message. |
| `mentionees` / `mentionUsers` | No | Users mentioned by the text message when the platform exposes mention builders. |
| `parentId` | No | Parent message ID when the text message is a reply. |

## Basic Text Message

Create a basic text message with a `subChannelId` and text body.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'text',
  data: {
    text: 'Welcome to the channel',
  },
});

renderResults(message);
```

```swift iOS
let options = AmityTextMessageCreateOptions(
    subChannelId: "sub-channel-id",
    text: "Welcome to the channel"
)

let message = try await messageRepository.createTextMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val disposable = AmityChatClient.newMessageRepository()
    .createTextMessage(
        subChannelId = subChannelId,
        text = "Welcome to the channel",
    )
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .text('Welcome to the channel')
    .send();

final messageId = message.messageId;
```


## Text With Context

Add tags, metadata, mentions, or reply context when the text message needs extra app-owned behavior.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'text',
  data: {
    text: 'Please review this update',
  },
  tags: ['announcement'],
  metadata: {
    source: 'composer',
  },
  mentionees: [{ type: 'user', userIds: [userId] }],
});
```

```swift iOS
let metadata: [String: Any] = [
    "source": "composer"
]

let options = AmityTextMessageCreateOptions(
    subChannelId: "sub-channel-id",
    text: "Please review this update",
    tags: ["announcement"],
    metadata: metadata
)

let message = try await messageRepository.createTextMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("source", "composer")
}

val disposable = AmityChatClient.newMessageRepository()
    .createTextMessage(
        subChannelId = subChannelId,
        text = "Please review this update",
    )
    .tags(AmityTags(listOf("announcement")))
    .metadata(metadata)
    .mentionUsers(listOf(userId))
    .build()
    .send()
    .subscribe()
```

```dart Flutter
final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .text('Please review this update')
    .tags(['announcement'])
    .metadata({'source': 'composer'})
    .mentionUsers([userId])
    .send();
```


## Related Topics

    Create a text reply with `parentId`.
    Query text messages and reply threads.

---

### [Image Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/image-message)

> Send image chat messages with platform-specific file ID, attachment, or URI inputs.

Use image messages after the user selects or uploads an image. TypeScript creates image messages with a file ID. iOS and Android use `AmityMessageAttachment`. Flutter sends image messages from a `Uri`.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the image message will be created. |
| `fileId` / `attachment` / `Uri` | Yes | Image input for the message: uploaded file ID, platform attachment, or Flutter `Uri`. |
| `caption` | No | Text caption attached to the image message where the platform exposes it. |
| `fullImage` | No | iOS option for sending the full image variant. |
| `parentId` | No | Parent message ID when sending the image as a reply. |
| `tags` | No | App-defined tags for filtering or grouping image messages. |
| `metadata` | No | App-defined metadata stored with the message. |

## Send An Image Message

Create an image message from an uploaded file ID, native attachment, or Flutter image URI.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'image',
  fileId,
});

renderResults(message);
```

```swift iOS
let imageURL = URL(fileURLWithPath: "/tmp/photo.jpg")
let options = AmityImageMessageCreateOptions(
    subChannelId: "sub-channel-id",
    attachment: .localURL(url: imageURL),
    caption: "Photo from today"
)

let message = try await messageRepository.createImageMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val attachment = AmityMessageAttachment.FILE_ID(fileId)

val disposable = AmityChatClient.newMessageRepository()
    .createImageMessage(
        subChannelId = subChannelId,
        attachment = attachment,
    )
    .caption("Photo from today")
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final imageUri = Uri.parse('file:///tmp/photo.jpg');

final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .image(imageUri)
    .caption('Photo from today')
    .send();
```


## Optional Context

Add captions, tags, metadata, or reply context when your product needs richer image-message behavior.


```swift iOS
let imageURL = URL(fileURLWithPath: "/tmp/photo.jpg")
let options = AmityImageMessageCreateOptions(
    subChannelId: "sub-channel-id",
    attachment: .localURL(url: imageURL),
    caption: "Launch photo",
    fullImage: true,
    tags: ["launch"],
    metadata: ["source": "composer"],
    parentId: "parent-message-id"
)

let reply = try await messageRepository.createImageMessage(options: options)
showSuccessMessage(reply.messageId)
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("source", "composer")
}

val disposable = AmityChatClient.newMessageRepository()
    .createImageMessage(subChannelId, AmityMessageAttachment.FILE_ID(fileId))
    .caption("Launch photo")
    .tags(AmityTags(listOf("launch")))
    .metadata(metadata)
    .parentId(messageId)
    .build()
    .send()
    .subscribe()
```


## Related Topics

    Send non-image file attachments.
    Send video attachments.

---

### [File Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/file-message)

> Send file chat messages with platform-specific file ID, attachment, or URI inputs.

Use file messages for document and generic attachment sharing. TypeScript creates file messages from an uploaded file ID. iOS and Android use `AmityMessageAttachment`. Flutter sends file messages from a `Uri`.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the file message will be created. |
| `fileId` / `attachment` / `Uri` | Yes | File input for the message: uploaded file ID, platform attachment, or Flutter `Uri`. |
| `caption` | No | Text caption attached to the file message where the platform exposes it. |
| `parentId` | No | Parent message ID when sending the file as a reply. |
| `tags` | No | App-defined tags for later filtering or grouping. |
| `metadata` | No | App-defined metadata stored with the message. |

## Send A File Message

Create a file message from an uploaded file ID, native attachment, or Flutter file URI.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'file',
  fileId,
});

renderResults(message);
```

```swift iOS
let fileURL = URL(fileURLWithPath: "/tmp/report.pdf")
let options = AmityFileMessageCreateOptions(
    subChannelId: "sub-channel-id",
    attachment: .localURL(url: fileURL),
    fileName: "report.pdf",
    caption: "Monthly report"
)

let message = try await messageRepository.createFileMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val attachment = AmityMessageAttachment.FILE_ID(fileId)

val disposable = AmityChatClient.newMessageRepository()
    .createFileMessage(
        subChannelId = subChannelId,
        attachment = attachment,
    )
    .caption("Monthly report")
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final fileUri = Uri.parse('file:///tmp/report.pdf');

final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .file(fileUri)
    .caption('Monthly report')
    .send();
```


## Replies And Metadata

Add reply context or metadata when the file message belongs to a thread or needs app-owned rendering context.


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

const { data: reply } = await MessageRepository.createMessage({
  subChannelId,
  parentId: messageId,
  dataType: 'file',
  fileId,
  tags: ['attachment'],
  metadata: {
    source: 'composer',
  },
});
```

```dart Flutter
final fileUri = Uri.parse('file:///tmp/report.pdf');

final reply = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .parentId(messageId)
    .file(fileUri)
    .caption('Adding the report here')
    .metadata({'source': 'composer'})
    .send();
```


## Related Topics

    Send image attachments.
    Send audio attachments where supported.

---

### [Audio Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/audio-message)

> Send audio chat messages on SDKs that expose audio message creation.

Use audio messages for voice notes and audio attachments. TypeScript creates audio messages from an uploaded file ID. iOS and Android use `AmityMessageAttachment`. The current Flutter public message create selector does not expose an audio creator.

Flutter supports text, image, file, video, and custom message creators in the current public `createMessage` selector. Do not use a fabricated Flutter audio creator; use another supported message type or confirm audio-message support in your SDK version first.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the audio message will be created. |
| `fileId` / `attachment` | Yes | Uploaded audio file ID on TypeScript or platform attachment on iOS and Android. |
| `fileName` | Depends | File name for iOS local URL attachments. |
| `parentId` | No | Parent message ID when sending the audio message as a reply, where supported by the platform builder. |
| `tags` | No | App-defined tags for message filtering, where supported by the platform builder. |
| `metadata` | No | App-defined metadata stored with the message, where supported by the platform builder. |

## Send An Audio Message

Create an audio message from an uploaded file ID or platform attachment, depending on the SDK.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'audio',
  fileId,
});

renderResults(message);
```

```swift iOS
let audioURL = URL(fileURLWithPath: "/tmp/voice.m4a")
let options = AmityAudioMessageCreateOptions(
    subChannelId: "sub-channel-id",
    attachment: .localURL(url: audioURL),
    fileName: "voice.m4a"
)

let message = try await messageRepository.createAudioMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val attachment = AmityMessageAttachment.FILE_ID(fileId)

val disposable = AmityChatClient.newMessageRepository()
    .createAudioMessage(
        subChannelId = subChannelId,
        attachment = attachment,
    )
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```


## Related Topics

    Send the audio file as a generic file attachment if that fits your product behavior.
    Send video attachments.

---

### [Video Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/video-message)

> Send video chat messages with platform-specific file ID, attachment, or URI inputs.

Use video messages for video attachments inside chat. TypeScript creates video messages from an uploaded file ID. iOS and Android use `AmityMessageAttachment`. Flutter sends video messages from a `Uri`.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the video message will be created. |
| `fileId` / `attachment` / `Uri` | Yes | Video input for the message: uploaded file ID, platform attachment, or Flutter `Uri`. |
| `fileName` | Depends | File name for iOS local URL attachments. |
| `parentId` | No | Parent message ID when sending the video as a reply, where supported by the platform builder. |
| `tags` | No | App-defined tags for message filtering, where supported by the platform builder. |
| `metadata` | No | App-defined metadata stored with the message, where supported by the platform builder. |

## Send A Video Message

Create a video message from an uploaded file ID, native attachment, or Flutter video URI.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'video',
  fileId,
});

renderResults(message);
```

```swift iOS
let videoURL = URL(fileURLWithPath: "/tmp/clip.mp4")
let options = AmityVideoMessageCreateOptions(
    subChannelId: "sub-channel-id",
    attachment: .localURL(url: videoURL),
    fileName: "clip.mp4"
)

let message = try await messageRepository.createVideoMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val attachment = AmityMessageAttachment.FILE_ID(fileId)

val disposable = AmityChatClient.newMessageRepository()
    .createVideoMessage(
        subChannelId = subChannelId,
        attachment = attachment,
    )
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final videoUri = Uri.parse('file:///tmp/clip.mp4');

final message = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .video(videoUri)
    .send();
```


## Related Topics

    Send generic file attachments.
    Send audio attachments where supported.

---

### [Custom Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/custom-message)

> Send app-defined custom chat message payloads.

Use custom messages when your app needs to send structured data that is not one of the built-in text or media message types. Keep the payload JSON-serializable and version your custom schema in your app code so older clients can render safely.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel where the custom message will be created. |
| `data` | Yes | JSON-serializable custom payload owned by your app. |
| `parentId` | No | Parent message ID when sending the custom message as a reply. |
| `tags` | No | App-defined tags for filtering or grouping custom messages. |
| `metadata` | No | App-defined metadata stored with the message. |

## Send A Custom Message

Create a custom message with a JSON-serializable payload that your app knows how to render.


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

const { data: message } = await MessageRepository.createMessage({
  subChannelId,
  dataType: 'custom',
  data: {
    kind: 'location',
    latitude: 13.7563,
    longitude: 100.5018,
  },
});

renderResults(message);
```

```swift iOS
let options = AmityCustomMessageCreateOptions(
    subChannelId: "sub-channel-id",
    data: [
        "kind": "location",
        "latitude": 13.7563,
        "longitude": 100.5018
    ]
)

let message = try await messageRepository.createCustomMessage(options: options)
showSuccessMessage(message.messageId)
```

```kotlin Android
val data = JsonObject().apply {
    addProperty("kind", "location")
    addProperty("latitude", 13.7563)
    addProperty("longitude", 100.5018)
}

val disposable = AmityChatClient.newMessageRepository()
    .createCustomMessage(
        subChannelId = subChannelId,
        data = data,
    )
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final message = await AmityChatClient.newMessageRepository()
    .createCustomMessage(subChannelId, {
      'kind': 'location',
      'latitude': 13.7563,
      'longitude': 100.5018,
    })
    .send();

final messageId = message.messageId;
```


## Add Tags, Metadata, Or Reply Context

Attach app-owned tags, metadata, or a `parentId` when the custom message needs filtering, rendering context, or reply threading.


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

const { data: reply } = await MessageRepository.createMessage({
  subChannelId,
  parentId: messageId,
  dataType: 'custom',
  data: {
    kind: 'system-card',
    title: 'Order received',
  },
  tags: ['system'],
  metadata: {
    source: 'checkout',
  },
});
```

```dart Flutter
final reply = await AmityChatClient.newMessageRepository()
    .createCustomMessage(subChannelId, {
      'kind': 'system-card',
      'title': 'Order received',
    })
    .parentId(messageId)
    .tags(['system'])
    .metadata({'source': 'checkout'})
    .send();
```


## Rendering Guidance

- Treat `data` as an app-owned contract.
- Include a type or version field such as `kind` so clients can choose the renderer.
- Provide a fallback renderer for unknown custom payloads.
- Keep sensitive data out of custom payloads unless your product explicitly requires it.

## Related Topics

    Send plain chat content.
    Send custom replies with `parentId`.

---

### [Reply to a Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/message-creation/reply-to-a-message)

> Create threaded chat replies by setting a parent message ID.

Use `parentId` to create a reply to an existing message. The reply still targets the same `subChannelId`; `parentId` links it to the parent message for threaded rendering and reply queries.

Replies are created with the same message-type APIs as top-level messages. Set `parentId` before sending the text, media, or custom message.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel for the reply; use the same subchannel as the parent message. |
| `parentId` | Yes | Message ID of the parent message being replied to. |
| Message type | Yes | Text, media, or custom message type selected with the platform-specific create API. |
| Message body or media input | Yes | Text/custom payload or media file input for the reply. |
| `tags` | No | App-defined tags for later filtering or grouping. |
| `metadata` | No | App-defined metadata stored with the reply. |

## Reply With Text

Create a text reply by setting `parentId` to the message being replied to.


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

const { data: reply } = await MessageRepository.createMessage({
  subChannelId,
  parentId: messageId,
  dataType: 'text',
  data: {
    text: 'Replying in thread',
  },
});

renderResults(reply);
```

```swift iOS
let options = AmityTextMessageCreateOptions(
    subChannelId: "sub-channel-id",
    text: "Replying in thread",
    parentId: "parent-message-id"
)

let reply = try await messageRepository.createTextMessage(options: options)
showSuccessMessage(reply.messageId)
```

```kotlin Android
val disposable = AmityChatClient.newMessageRepository()
    .createTextMessage(
        subChannelId = subChannelId,
        text = "Replying in thread",
    )
    .parentId(messageId)
    .build()
    .send()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final reply = await AmityChatClient.newMessageRepository()
    .createMessage(subChannelId)
    .parentId(messageId)
    .text('Replying in thread')
    .send();

final replyId = reply.messageId;
```


## Reply With Media Or Custom Data

Use the same reply pattern with media or custom payloads when the reply is not plain text.


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

const { data: imageReply } = await MessageRepository.createMessage({
  subChannelId,
  parentId: messageId,
  dataType: 'image',
  fileId,
});
```

```kotlin Android
val disposable = AmityChatClient.newMessageRepository()
    .createImageMessage(
        subChannelId = subChannelId,
        attachment = AmityMessageAttachment.FILE_ID(fileId),
    )
    .parentId(messageId)
    .build()
    .send()
    .subscribe()
```


## Query Reply Threads

After creating replies, query messages by `parentId` when you need to render a thread. See [Query & Filter Messages](../messages/query-and-filter-messages) for platform-specific query examples.

## Related Topics

    Create text messages and text replies.
    Query top-level messages and replies.

---

### [Edit and Delete Messages](https://learn.social.plus/social-plus-sdk/chat/messaging-features/messages/edit-and-delete-messages)

> Edit text or custom chat messages and soft-delete messages after creation.

Use message management APIs after your app already has the target `messageId`. The client SDKs expose text-message edits, custom-message edits, and soft deletion.

Soft deletion marks a message as deleted and lets message queries or single-message observers reflect that state. It is not a hard-delete or recovery API.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Edit text | `MessageRepository.updateMessage(messageId, patch)` | `editTextMessage(withId:_:)` | `editTextMessage(messageId).text(...).build().apply()` | `editTextMessage(messageId).text(...).update()` |
| Edit custom | `MessageRepository.updateMessage(messageId, patch)` | `editCustomMessage(withId:_:)` | `editCustomMessage(messageId).data(...).build().apply()` | `editCustomMessage(messageId, data).update()` |
| Soft delete | `MessageRepository.softDeleteMessage(messageId)` | `softDeleteMessage(withId:)` | `softDeleteMessage(messageId)` | `deleteMessage(messageId)` |

The Flutter `updateMessage(channelId, messageId)` builder is deprecated. Use `editTextMessage(messageId)` or `editCustomMessage(messageId, customData)` for new integrations.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Edit text | `messageId` | Yes | Existing text message ID to update. |
| Edit text | `text` / `data.text` | Yes | Replacement text content. |
| Edit text | `tags` | No | Replacement tags where the platform edit builder exposes tags. |
| Edit text | `metadata` | No | Replacement metadata stored with the message. |
| Edit custom | `messageId` | Yes | Existing custom message ID to update. |
| Edit custom | `data` / custom payload | Yes | Replacement JSON-serializable custom payload. |
| Soft delete | `messageId` | Yes | Message ID to soft-delete. |

## Edit A Text Message

Update the text body and optional app-owned context for an existing text message.


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

const { data: updatedMessage } = await MessageRepository.updateMessage(
  messageId,
  {
    data: { text: 'Updated text' },
    tags: ['edited'],
    metadata: { source: 'composer' },
  },
);

renderResults(updatedMessage);
```

```swift iOS
try await messageRepository.editTextMessage(
    withId: "message-id",
    "Updated text",
    metadata: ["source": "composer"]
)

showSuccessMessage("Message updated")
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("source", "composer")
}

val disposable = messageRepository
    .editTextMessage(messageId = messageId)
    .text("Updated text")
    .metadata(metadata)
    .build()
    .apply()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final updatedMessage = await AmityChatClient.newMessageRepository()
    .editTextMessage(messageId)
    .text('Updated text')
    .tags(['edited'])
    .metadata({'source': 'composer'})
    .update();

final editedAt = updatedMessage.editedAt;
```


## Edit A Custom Message

Update the JSON-serializable payload for an existing custom message.


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

const { data: updatedMessage } = await MessageRepository.updateMessage(
  messageId,
  {
    data: {
      value: { state: 'confirmed' },
    },
  },
);

renderResults(updatedMessage);
```

```swift iOS
try await messageRepository.editCustomMessage(
    withId: "message-id",
    ["state": "confirmed"]
)

showSuccessMessage("Custom message updated")
```

```kotlin Android
val customData = JsonObject().apply {
    addProperty("state", "confirmed")
}

val disposable = messageRepository
    .editCustomMessage(messageId = messageId)
    .data(customData)
    .build()
    .apply()
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final updatedMessage = await AmityChatClient.newMessageRepository()
    .editCustomMessage(messageId, {'state': 'confirmed'})
    .update();

final editedAt = updatedMessage.editedAt;
```


## Soft-Delete A Message

Soft-delete a message by ID so list and single-message observers can reflect deleted state.


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

const deletedMessage =
  await MessageRepository.softDeleteMessage(messageId);

renderResults(deletedMessage);
```

```swift iOS
try await messageRepository.softDeleteMessage(withId: "message-id")
showSuccessMessage("Message deleted")
```

```kotlin Android
val disposable = messageRepository
    .softDeleteMessage(messageId = messageId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleDeletionError(error) },
    )
```

```dart Flutter
await AmityChatClient.newMessageRepository()
    .deleteMessage(messageId);
```


## After Edit Or Delete

- Observe the message or query collection again instead of mutating app UI state by hand.
- Use `editedAt` to render edited indicators after an edit.
- Use `isDeleted` to render deleted placeholders or hide deleted messages depending on your product rule.
- Pass `includeDeleted` on query APIs only where the platform exposes that filter.

## Related Topics

    Create the message before editing or deleting it.
    Observe one message after an edit or delete.
    Refresh timelines and reply threads.

---

### [Get and View a Message](https://learn.social.plus/social-plus-sdk/chat/messaging-features/messages/get-and-view-a-message)

> Retrieve one chat message by ID and inspect its SDK fields.

Use a single-message lookup when your app needs to open a message permalink, refresh a message after an action, or observe a specific message for edits, deletion, reactions, flags, and marker updates.

The SDK returns the same message model used by message queries. Rendering is app-owned: inspect `messageType` or `dataType`, read the typed data payload, and handle `isDeleted` before displaying content.

## Platform Surface

| Platform | Retrieval shape | Update behavior |
| --- | --- | --- |
| TypeScript | `MessageRepository.getMessage(messageId, callback)` | Live object callback; returns unsubscriber |
| iOS | `messageRepository.getMessage(messageId)` | `AmityObject<AmityMessage>` observation |
| Android | `messageRepository.getMessage(messageId)` | `Flowable<AmityMessage>` |
| Flutter | `messageRepository.getMessage(messageId)` | One-shot `Future<AmityMessage>`; use `message.listen` for local live updates |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `messageId` | Yes | Message ID to retrieve or observe. |
| Callback / observer | Depends | Required by TypeScript and native live-object APIs to receive loading, error, and data updates. |
| Unsubscriber / token / disposable | No | Handle returned by live APIs; retain it while observing and release it when the UI no longer needs updates. |

## Retrieve A Message

Retrieve or observe a single message by `messageId`.


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

const unsubscribe = MessageRepository.getMessage(
  messageId,
  ({ data: fetchedMessage, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && fetchedMessage) {
      renderResults(fetchedMessage);
    }
  },
);

unsubscribe();
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    if let message = liveObject.snapshot {
        showSuccessMessage(message.messageId)
    }
}
```

```kotlin Android
val disposable = messageRepository
    .getMessage(messageId = messageId)
    .subscribe(
        { fetchedMessage ->
            showSuccessMessage(fetchedMessage.getMessageId())
        },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final fetchedMessage = await AmityChatClient.newMessageRepository()
    .getMessage(messageId);

final fetchedMessageId = fetchedMessage.messageId;
final isDeleted = fetchedMessage.isDeleted ?? false;
```


## Inspect Message Content

Read the message type and data payload before choosing the renderer for your UI.


```typescript TypeScript
if (message.dataType === 'text') {
  const text = message.data?.text;
  renderResults(text);
}

if (message.dataType === 'image') {
  const fileId = message.data?.fileId;
  renderResults(fileId);
}
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let message = liveObject.snapshot else { return }

    switch message.messageType {
    case .text:
        showSuccessMessage(message.messageId)
    case .image, .file, .video, .audio, .custom:
        showSuccessMessage(message.messageId)
    }
}
```

```kotlin Android
messageRepository
    .getMessage(messageId = messageId)
    .subscribe { fetchedMessage ->
        when (fetchedMessage.getData()) {
            is AmityMessage.Data.TEXT -> showSuccessMessage()
            is AmityMessage.Data.IMAGE -> showSuccessMessage()
            is AmityMessage.Data.FILE -> showSuccessMessage()
            is AmityMessage.Data.VIDEO -> showSuccessMessage()
            is AmityMessage.Data.AUDIO -> showSuccessMessage()
            is AmityMessage.Data.CUSTOM -> showSuccessMessage()
            else -> showSuccessMessage()
        }
    }
```

```dart Flutter
final fetchedMessage = await AmityChatClient.newMessageRepository()
    .getMessage(messageId);

switch (fetchedMessage.dataType) {
  case AmityMessageDataType.TEXT:
  case AmityMessageDataType.IMAGE:
  case AmityMessageDataType.FILE:
  case AmityMessageDataType.VIDEO:
  case AmityMessageDataType.AUDIO:
  case AmityMessageDataType.CUSTOM:
    final fetchedMessageId = fetchedMessage.messageId;
    break;
}
```


## Deletion And Edit Fields

| Field | What to use it for |
| --- | --- |
| `isDeleted` | Decide whether to hide content or render a deleted-message placeholder. |
| `editedAt` | Show an edited indicator when present. |
| `parentId` | Link a reply back to its parent message. |
| `childrenNumber` | Show reply/thread counts when available. |
| `flagCount` / `isFlaggedByMe` | Render report state and moderation affordances. |

Single-message retrieval does not replace list queries. Use `getMessages` for timelines and use `getMessage` for detail refresh, deep links, or focused observation.

## Related Topics

    Load message lists and thread replies.
    Update or soft-delete a message after sending.
    Report and unreport chat messages.

---

### [Query and Filter Messages](https://learn.social.plus/social-plus-sdk/chat/messaging-features/messages/query-and-filter-messages)

> Query chat messages by subchannel, type, tags, deleted state, parent message, or around-message context.

Use message queries to build timelines, reply threads, media views, and jump-to-message flows. All platforms start from a `subChannelId`; optional filters narrow the result set.

For chat timelines, prefer live collections or reactive streams where the platform provides them. They keep edits, deletes, reactions, and newly created messages in sync without a manual refresh loop.

## Filter Surface

| Filter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Subchannel | `subChannelId` | `subChannelId` | `getMessages(subChannelId)` | `getMessages(subChannelId)` |
| Tags | `includingTags`, `excludingTags` | `includingTags`, `excludingTags` | `includingTags()`, `excludingTags()` | `includingTags()`, `excludingTags()` |
| Type | `type` | `type` | `type()` | `type()` |
| Deleted messages | `includeDeleted` | Not exposed on query options | `includeDeleted()` | `includeDeleted()` |
| Replies | `parentId` | `messageParentFilter` | `parentId()` | `parentId()` |
| Jump context | `aroundMessageId` | `aroundMessageId` | `aroundMessageId()` | `aroundMessageId()` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Target subchannel whose messages should be queried. |
| `includingTags` / `excludingTags` | No | Include or exclude messages with specific app-defined tags. |
| `type` | No | Restrict results to one message type, such as text, image, file, video, audio, or custom. |
| `includeDeleted` | No | Include soft-deleted messages where the platform exposes the filter. |
| `parentId` / `messageParentFilter` | No | Query replies for a parent message instead of the main timeline. |
| `aroundMessageId` | No | Load messages around a target message for deep-link or jump-to-message flows. |
| `sortBy` / `stackFromEnd` | No | Control timeline ordering where the platform exposes sort options. |
| Pagination controls | No | Use callbacks, live collections, or paging data to load additional results. |

## Query A Timeline

Query the main message timeline for a subchannel with optional tag and sort filters.


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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    includingTags: ['public'],
    excludingTags: ['hidden'],
    sortBy: 'segmentDesc',
  },
  ({ data: messages, onNextPage, hasNextPage, loading, error }) => {
    if (error) handleError(error);

    if (!loading && messages) {
      renderResults(messages);
    }

    if (hasNextPage) onNextPage?.();
  },
);

unsubscribe();
```

```swift iOS
let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    includingTags: ["public"],
    excludingTags: ["hidden"],
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
token = messages.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
val includingTags = AmityTags().apply { add("public") }
val excludingTags = AmityTags().apply { add("hidden") }

val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .includingTags(includingTags)
    .excludingTags(excludingTags)
    .sortBy(AmityMessageQuerySortOption.LAST_CREATED)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final liveCollection = AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .includingTags(['public'])
    .excludingTags(['hidden'])
    .stackFromEnd(true)
    .getLiveCollection();

liveCollection.getStreamController().stream.listen((messages) {
  final count = messages.length;
});

liveCollection.loadNext();
```


## Query By Type Or Deleted State

Use message type and deleted-state filters to build focused views such as media galleries or moderation queues.


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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    type: 'image',
    includeDeleted: false,
  },
  ({ data: messages }) => {
    renderResults(messages);
  },
);

unsubscribe();
```

```swift iOS
let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    type: .image,
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
showSuccessMessage(messages)
```

```kotlin Android
val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .type(AmityMessage.DataType.IMAGE)
    .includeDeleted(includeDeleted = false)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final imageMessages = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .type(AmityMessageDataType.IMAGE)
    .includeDeleted(false)
    .query();

final count = imageMessages.length;
```


## Query Replies

Use a parent message ID to fetch replies to that message. Use the no-parent/default query for the main timeline.

Query replies with `parentId` when rendering a message thread.


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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    parentId: messageId,
    sortBy: 'segmentAsc',
  },
  ({ data: replies }) => {
    renderResults(replies);
  },
);

unsubscribe();
```

```swift iOS
let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    messageParentFilter: .parent(id: "parent-message-id"),
    sortOption: .firstCreated
)

let replies = messageRepository.getMessages(options: options)
showSuccessMessage(replies)
```

```kotlin Android
val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .parentId(parentId = messageId)
    .sortBy(AmityMessageQuerySortOption.FIRST_CREATED)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final replies = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .parentId(messageId)
    .query();

final replyCount = replies.length;
```


## Jump To A Message

Use `aroundMessageId` when your app opens a deep link or search result and needs the target message plus nearby context.

Query around a target message to load nearby context for deep links and search results.


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

const unsubscribe = MessageRepository.getMessages(
  {
    subChannelId,
    aroundMessageId: messageId,
  },
  ({ data: messages, hasPrevPage, hasNextPage }) => {
    renderResults({ messages, hasPrevPage, hasNextPage });
  },
);

unsubscribe();
```

```swift iOS
let options = AmityMessageQueryOptions(
    subChannelId: "sub-channel-id",
    aroundMessageId: "message-id",
    sortOption: .lastCreated
)

let messages = messageRepository.getMessages(options: options)
showSuccessMessage(messages)
```

```kotlin Android
val disposable = messageRepository
    .getMessages(subChannelId = subChannelId)
    .aroundMessageId(messageId = messageId)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final messagesAroundTarget = await AmityChatClient.newMessageRepository()
    .getMessages(subChannelId)
    .aroundMessageId(messageId)
    .query();

final count = messagesAroundTarget.length;
```


## Related Topics

    Create messages that appear in the queried subchannel.
    Retrieve or observe one message by ID.
    Update queried messages after creation.

---

### [Pin and Unpin Messages](https://learn.social.plus/social-plus-sdk/chat/messaging-features/messages/pin-message)

> Pin one message in a livestream chat channel, unpin it, and keep the pinned message in sync through the channel live object and realtime events.

Use pin APIs to surface one important message above a livestream chat so every viewer sees it, no matter how fast the feed scrolls. Pin state is owned by the server and exposed on the channel as `pinnedMessage`. A channel holds at most one pinned message at a time.

  Pinning is available on `live` channels only, the channel type attached to a livestream room. The server rejects pin requests on conversation, community, broadcast, standard, and private channels.

  The Flutter and React Native SDKs do not ship pin support.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Pin a message | `MessageRepository.pinMessage(messageId)` | `messageRepository.pinMessage(withId:)` | `messageRepository.pinMessage(messageId)` | Not supported |
| Unpin a message | `MessageRepository.unpinMessage(messageId)` | `messageRepository.unpinMessage(withId:)` | `messageRepository.unpinMessage(messageId)` | Not supported |
| Read the pinned message | `channel.pinnedMessage` | `channel.pinnedMessage` | `channel.getPinnedMessage()` | Not supported |
| Pin realtime events | `ChannelRepository.onChannelMessagePinned(...)`, `ChannelRepository.onChannelMessageUnpinned(...)` | Delivered through the channel live object | Delivered through the channel live object | Not supported |
| Permission constant | `'PIN_MESSAGE'` (`Amity.Permission.PinMessagePermission`) | `AmityPermission.pinMessage` | `AmityPermission.PIN_MESSAGE` | Not supported |

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Pin | `messageId` | Yes | TypeScript, iOS, Android | ID of the message to pin. Use the same `messageId` you pass to other message repository functions. |
| Unpin | `messageId` | Yes | TypeScript, iOS, Android | ID of the message that is currently pinned. Take it from `pinnedMessage.messageId`. The server rejects the call if this message is not the current pin. |
| Permission check | `channelId` | Yes | TypeScript, iOS, Android | Channel to check the current user's `PIN_MESSAGE` permission in. |

## Who Can Pin

The server authorizes pin and unpin with the `PIN_MESSAGE` channel permission. Default moderator roles carry it, so channel moderators can pin. A livestream host and co-hosts receive the channel moderator role when the room is created or when a co-host joins, so they can pin as well. Network admins with the moderate-channel admin permission can pin from the Console.

A message author cannot pin their own message by authorship alone. Only role holders can pin.

Check the permission before you show a pin control:


```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

// A network-level grant (Console) shows up on the user; a channel role shows up on the channel.
const permission = client.hasPermission('PIN_MESSAGE');
const canPin = permission.currentUser() || permission.channel(channelId);

if (canPin) {
  // Show the pin control in the message action menu.
}
```

```swift iOS
Task { @MainActor in
    let canPin = await client.hasPermission(
        .pinMessage,
        forChannel: "channel-id"
    )

    if canPin {
        // Show the pin control in the message action menu.
    }
}
```

```kotlin Android
fun checkPinPermission(channelId: String) {
    AmityCoreClient.hasPermission(AmityPermission.PIN_MESSAGE)
        .atChannel(channelId)
        .check()
        .doOnNext { canPin: Boolean ->
            if (canPin) {
                // Show the pin control in the message action menu.
            }
        }
        .subscribe()
}
```


On Android the check is a `Flowable` and re-emits when the user's channel membership changes. On iOS the check is one-shot: re-run it when the channel, room, the current user's channel membership, or the current user's own record updates, and after a `403`. Permission changes reach the client over realtime events by scope: a **channel-level** role change (moderator or co-host) over the `channel.roleAdded` / `channel.roleRemoved` events, which update the user's channel permissions; and a **network-level** change made from the Console over the `user.updated` event, which updates the user's network permissions. On iOS, `user.updated` is delivered only while the current user's events are subscribed (`AmityUser.subscribeEvent(.user)`); the pre-built livestream chat UI subscribes this automatically while it is open, and unsubscribes when it closes. Because the permission check combines the user's network and channel permissions, re-checking on either update reflects a mid-stream change with no user action, and the `403` re-check is a backstop.

  Roles are seeded when a network is created. On a network created before pin support shipped, existing roles may not include `PIN_MESSAGE` until the role backfill has run for that network. Until then the permission check returns `false` and every pin request returns `403`. Contact support if pin controls never appear on an older network.

## Pin A Message

Pin a message in its livestream channel. If another message is already pinned, the new pin replaces it in one step. You do not need to unpin first. The SDK calls `POST /api/v5/messages/{messageId}/pin`.


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

const channel = await MessageRepository.pinMessage(messageId);

renderResults(channel.pinnedMessage);
```

```swift iOS
do {
    let channel = try await messageRepository.pinMessage(withId: "message-id")
    showSuccessMessage(channel.pinnedMessage?.messageId)
} catch {
    handleError(error)
}
```

```kotlin Android
val disposable = messageRepository
    .pinMessage(messageId = messageId)
    .subscribe(
        { channel -> showSuccessMessage(channel.getPinnedMessage()?.getMessageId()) },
        { error -> handleGeneralError(error) },
    )
```


The call returns the updated channel with the pinned message set. The SDK writes the channel into its cache, so any active channel observer for that channel fires immediately, without waiting for the realtime event.

Pinning the message that is already pinned returns a `400` error. Pinning a deleted message, or a message whose author is banned from the channel or globally banned, also returns `400`. Pin state is unchanged on any error.

## Unpin A Message

Remove the current pin. Pass the `messageId` of the message that is currently pinned. The SDK calls `DELETE /api/v5/messages/{messageId}/pin`.


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

const channel = await MessageRepository.unpinMessage(messageId);

renderResults(channel.pinnedMessage); // null
```

```swift iOS
do {
    let channel = try await messageRepository.unpinMessage(withId: "message-id")
    showSuccessMessage(channel.pinnedMessage == nil)
} catch {
    handleError(error)
}
```

```kotlin Android
val disposable = messageRepository
    .unpinMessage(messageId = messageId)
    .subscribe(
        { channel -> showSuccessMessage(channel.getPinnedMessage() == null) },
        { error -> handleGeneralError(error) },
    )
```


The server rejects an unpin with `400` when `messageId` is not the current pin. This is deliberate. A stale client cannot clear a pin that someone else has since replaced. When you receive that error, re-read the channel or rely on the next `channel.messagePinned` event to get the current pin.

Unpin is allowed regardless of stream state, so a moderator can clean up after a stream ends.

## Read The Pinned Message

The pinned message lives on the channel, so observe the channel you already hold for the live chat. The field is `null` when nothing is pinned. On TypeScript it is typed optional, so a channel payload that omits it reads as `undefined`. Treat `null` and `undefined` the same way, as the `?? null` in the example does.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannel(
  channelId,
  ({ data: channel, loading, error }) => {
    if (error) handleError(error);

    if (!loading && channel) {
      renderResults(channel.pinnedMessage ?? null);
    }
  },
);

unsubscribe();
```

```swift iOS
let liveChannel = channelRepository.getChannel("channel-id")

token = liveChannel.observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }

    if let pinned = channel.pinnedMessage {
        showSuccessMessage(pinned.data?["text"] as? String)
    } else {
        // Nothing is pinned. Hide the banner.
    }
}
```

```kotlin Android
val disposable = channelRepository
    .getChannel(channelId = channelId)
    .subscribe(
        { channel ->
            val pinned: AmityPinnedMessage? = channel.getPinnedMessage()
            if (pinned != null) {
                // getData() returns AmityMessage.Data. Cast it to read the text.
                val text = (pinned.getData() as? AmityMessage.Data.TEXT)?.getText()
                showSuccessMessage(text)
            } else {
                // Nothing is pinned. Hide the banner.
            }
        },
        { error -> handleGeneralError(error) },
    )
```


### Pinned message shape

The pinned message carries a snapshot of the message body plus who pinned it and when. It is not a full message object, so use the fields below rather than message-repository helpers. Android exposes each field through the getter named in the third column.

| Field | Type | Android getter | Description |
| --- | --- | --- | --- |
| `messageId` | string | `getMessageId()` | ID of the pinned message. Pass this to the unpin call. |
| `parentId` | string \| null | `getParentId()` | Set only when the pinned message is a reply. |
| `channelId` | string | `getChannelId()` | Internal channel ID. |
| `channelPublicId` | string | `getChannelPublicId()` | Public channel ID, the value you use with the channel repository. |
| `messageFeedId` | string | `getSubChannelId()` | Subchannel the message belongs to. |
| `segment` | number | `getSegment()` | Message segment within the subchannel. |
| `dataType` | string | `getDataType()` | Message data type. Livestream chat pins text messages. On iOS it is the `AmityMessageType` enum; on Android the getter returns the `AmityMessage.DataType` enum. |
| `data` | object | `getData()` | Message data. For text messages, `{ text }`. On Android the getter returns `AmityMessage.Data`. Cast it to `AmityMessage.Data.TEXT` and call `getText()`. |
| `creatorId` | string | `getCreatorId()` | Internal ID of the message author. |
| `creatorPublicId` | string | `getCreatorPublicId()` | Public user ID of the message author. Use it to load the author profile. |
| `isDeleted` | boolean | `isDeleted()` | Always `false` in practice. The server clears the pin when the message is deleted. |
| `pinnedBy` | string | `getPinnedBy()` | Internal ID of the user who pinned the message. |
| `pinnedAt` | date-time | `getPinnedAt()` | When the message was pinned. |
| `createdAt`, `updatedAt` | date-time | `getCreatedAt()`, `getUpdatedAt()` | Message timestamps. |

The response and the pin event include the pinned message author in their `users` payload, so the author is usually already in the user cache when you render the banner.

## Listen For Pin Changes

Two realtime events arrive on the channel topic that live chat clients already subscribe to. You do not need an extra topic subscription.

| Event | When it fires | Payload |
| --- | --- | --- |
| `channel.messagePinned` | A message is pinned, including when a new pin replaces the current one | Full snapshot: `channelId`, `pinnedMessage`, `users` |
| `channel.messageUnpinned` | The pin is removed, either by a moderator or automatically | `channelId` only |

On every platform the SDK handles both events internally: it updates the cached channel and the channel live object emits. The TypeScript SDK also exposes the two events as callbacks for cases where you need a hook separate from the channel observer. On iOS and Android there is no separate callback. Observe the channel and compare the pinned message ID between emissions to tell a pin from an unpin.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribePinned = ChannelRepository.onChannelMessagePinned((channel) => {
  renderResults(channel.pinnedMessage);
});

const unsubscribeUnpinned = ChannelRepository.onChannelMessageUnpinned((channel) => {
  renderResults(channel.pinnedMessage); // null
});

unsubscribePinned();
unsubscribeUnpinned();
```

```swift iOS
var currentPinnedMessageId: String?

let liveChannel = channelRepository.getChannel("channel-id")

token = liveChannel.observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }
    let pinned = channel.pinnedMessage

    switch (currentPinnedMessageId, pinned?.messageId) {
    case (nil, let newId?):
        // channel.messagePinned: show the banner.
        showSuccessMessage("Pinned \(newId)")
    case (let oldId?, let newId?) where oldId != newId:
        // channel.messagePinned with a replacement: re-render the banner collapsed.
        showSuccessMessage("Replaced \(oldId) with \(newId)")
    case (_?, nil):
        // channel.messageUnpinned, or the pinned message was deleted: hide the banner.
        showSuccessMessage("Unpinned")
    default:
        break
    }

    currentPinnedMessageId = pinned?.messageId
}
```

```kotlin Android
var currentPinnedMessageId: String? = null

val disposable = channelRepository
    .getChannel(channelId = channelId)
    .subscribe(
        { channel ->
            val newId = channel.getPinnedMessage()?.getMessageId()
            val oldId = currentPinnedMessageId

            when {
                oldId == null && newId != null -> {
                    // channel.messagePinned: show the banner.
                    showSuccessMessage("Pinned $newId")
                }
                oldId != null && newId != null && oldId != newId -> {
                    // channel.messagePinned with a replacement: re-render the banner collapsed.
                    showSuccessMessage("Replaced $oldId with $newId")
                }
                oldId != null && newId == null -> {
                    // channel.messageUnpinned, or the pinned message was deleted: hide the banner.
                    showSuccessMessage("Unpinned")
                }
            }

            currentPinnedMessageId = newId
        },
        { error -> handleGeneralError(error) },
    )
```


Realtime delivery on iOS and Android requires the channel topic to be subscribed, which the live chat already does for the channel it renders. If you observe a channel outside a live chat screen, subscribe to its topic first as described in [Chat Realtime Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/chat-realtime-events).

Treat every `messagePinned` payload as the full current state and apply the last one you receive. Do not treat it as an increment. Replacing a pin emits one `messagePinned` event with the new message, not an unpin followed by a pin.

### Automatic unpin

The server clears the pin and emits `channel.messageUnpinned` when:

- The pinned message is deleted.
- The pinned message author is banned from the channel or globally banned. The author's messages are deleted as part of the ban.

A community ban does not affect the pin. The SDK also clears the cached pinned message when it receives a `message.deleted` event for the pinned message, so the channel stays correct even if the unpin event is missed.

  Realtime events are not replayed after a reconnect. A client that was offline while the pin changed receives nothing on reconnect. Read the channel again after reconnecting and use the channel's pinned message as the source of truth.

## Server Rules And Errors

| Condition | HTTP | `code` |
| --- | --- | --- |
| Caller lacks `PIN_MESSAGE` and is not an admin with the moderate-channel permission | `403` | `400301`. Permission changes also arrive over realtime events — `channel.roleAdded` / `channel.roleRemoved` for a channel-level role change, and `user.updated` for a network-level change made from the Console — which update the caller's permissions, so a revoked permission is usually reflected before a pin attempt. The TypeScript SDK additionally refreshes the caller's permissions on the `403` itself, as a backstop. |
| Message or channel not found | `404` | `400400` |
| Message is deleted | `400` | `400000` |
| Message is already pinned (pin) | `400` | `400000` |
| Message is not the current pin (unpin) | `400` | `400000` |
| Message author is channel-banned or globally banned (pin) | `400` | `400000` |
| Channel type is not `live` (pin) | `400` | `400000` |

Every `400` condition shares the code `400000`. Only the server `message` string tells them apart, so do not branch on the code to decide which one happened.

Pin state is never changed by a failed request, so a client does not need to roll anything back. Re-read the channel, or wait for the next event, and render what it says.


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

try {
  await MessageRepository.pinMessage(messageId);
} catch (error) {
  // The pin did not change. Hide the pin control after a 403,
  // and let the channel observer keep the banner in sync.
  handleError(error);
}
```

```swift iOS
do {
    _ = try await messageRepository.pinMessage(withId: "message-id")
} catch {
    // The pin did not change. Re-check hasPermission(.pinMessage, forChannel:)
    // after a 403, and let the channel observer keep the banner in sync.
    handleError(error)
}
```

```kotlin Android
val disposable = messageRepository
    .pinMessage(messageId = messageId)
    .subscribe(
        { /* Channel observer renders the new pin. */ },
        { error ->
            // The pin did not change. The permission Flowable re-emits after a 403,
            // and the channel observer keeps the banner in sync.
            handleGeneralError(error)
        },
    )
```


## Related Topics

    Observe the channel live object that carries the pinned message.
    Check `PIN_MESSAGE` and other channel permissions before showing controls.
    Ready-made pin action and pinned message banner in the livestream chat.

## Chat — Engagement

### [Message Preview](https://learn.social.plus/social-plus-sdk/chat/engagement-features/message-preview)

> Read the latest message preview from chat channel and subchannel SDK objects.

Use message preview when your app needs a lightweight latest-message summary for a chat list, inbox row, or notification handoff. The SDK exposes preview data on channel and subchannel models after message preview is enabled for the network.

  Message preview is configured outside these client SDK calls, typically through network settings. Client SDKs read the preview that is returned with channel or subchannel data; they do not enable the setting themselves.

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Channel preview | `channel.messagePreview` | `channel.messagePreview` | `channel.getMessagePreview()` | `channel.messagePreview` |
| Subchannel preview | `subChannel.messagePreview` | `subChannel.messagePreview` | `subChannel.getMessagePreview()` | Not exposed as a public preview object |
| Preview ID | `messagePreviewId` | `messagePreviewId` | `getMessagePreviewId()` | `messagePreviewId` |
| Preview data | `data`, `dataType` | `data`, `dataType` | `getData()`, `getDataType()` | `data`, `dataType` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes | Channel ID used to retrieve or observe the channel that contains the preview. |
| `subChannelId` | Yes for subchannel preview | Subchannel ID used to retrieve or observe a subchannel preview where the platform exposes it. |
| Preview setting | Yes | The network must have message preview enabled before new messages produce preview data. |
| `messagePreview` null handling | Yes | A channel or subchannel can return no preview when no eligible message exists, preview is disabled, or the preview has not been cached yet. |

## Read Channel Preview

Read the preview from the channel object you already use for channel lists. Treat the preview as optional and render a fallback for empty channels.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannel(
  channelId,
  ({ data: channelSnapshot, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && channelSnapshot?.messagePreview) {
      renderResults({
        id: channelSnapshot.messagePreview.messagePreviewId,
        dataType: channelSnapshot.messagePreview.dataType,
        data: channelSnapshot.messagePreview.data,
        userId: channelSnapshot.messagePreview.user?.userId,
      });
    }
  },
);

unsubscribe();
```

```swift iOS
token = channelRepository.getChannel(channelId).observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let preview = liveObject.snapshot?.messagePreview else { return }

    showSuccessMessage([
        "id": preview.messagePreviewId,
        "type": preview.dataType,
        "subChannelId": preview.subChannelId
    ])
}
```

```kotlin Android
val currentChannel = channel ?: return
val preview = currentChannel.getMessagePreview() ?: return

showSuccessMessage(
    mapOf(
        "id" to preview.getMessagePreviewId(),
        "type" to preview.getDataType(),
        "subChannelId" to preview.getSubChannelId(),
    ),
)
```

```dart Flutter
final fetchedChannel = await AmityChatClient.newChannelRepository()
    .getChannel(channelId);

final preview = fetchedChannel.messagePreview;

if (preview != null) {
  final previewId = preview.messagePreviewId;
  final previewType = preview.dataType;
  final previewData = preview.data;
}
```


## Read Subchannel Preview

Use subchannel preview when your UI lists subchannels directly. Flutter currently exposes `messagePreviewId` on `AmitySubChannel`, but not the composed `AmityMessagePreview` object.


```typescript TypeScript
import { SubChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = SubChannelRepository.getSubChannel(
  subChannelId,
  ({ data: subChannel, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && subChannel?.messagePreview) {
      renderResults(subChannel.messagePreview.messagePreviewId);
    }
  },
);

unsubscribe();
```

```swift iOS
let subChannelRepository = AmitySubChannelRepository()

token = subChannelRepository.getSubChannel(withId: "sub-channel-id").observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let preview = liveObject.snapshot?.messagePreview else { return }
    showSuccessMessage(preview.messagePreviewId)
}
```

```kotlin Android
val subChannelRepository = AmityChatClient.newSubChannelRepository()

val disposable = subChannelRepository
    .getSubChannel(subChannelId)
    .subscribe(
        { subChannel ->
            val preview = subChannel.getMessagePreview()
            showSuccessMessage(preview?.getMessagePreviewId() ?: "")
        },
        { error -> handleGeneralError(error) },
    )
```


## Preview Fields

| Field | Description |
| --- | --- |
| `messagePreviewId` | ID of the message represented by the preview. |
| `dataType` | Message data type, such as text, image, file, video, audio, or custom. |
| `data` | Preview payload for the message data type. For text messages, this contains the text payload. |
| `channelId` | Channel that owns the previewed message. |
| `subChannelId` | Subchannel that owns the previewed message. |
| `subChannelName` | Subchannel display name where the platform exposes it. |
| `isDeleted` | Whether the previewed message is deleted. Availability depends on the network preview setting. |
| `user` | User object for the previewed message creator when the SDK has the user data. |

## Related Topics

    Load channel lists that include preview data.
    Load full message timelines when preview data is not enough.
    Combine previews with unread count and mention indicators.

---

### [Channel Unread Count](https://learn.social.plus/social-plus-sdk/chat/engagement-features/unread-status/channel-unread-count)

> Read per-channel and total chat unread counts from SDK channel objects.

Use channel unread count when your app needs inbox badges, mention indicators, or total chat unread state. The SDK exposes unread state on channel models and provides an aggregate total for channels known to the current user.

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Channel count | `channel.unreadCount` | `channel.unreadCount` | `channel.getUnreadCount()` | `channel.unreadCount` |
| Channel mention | `channel.isMentioned` | `channel.isMentioned` | `channel.isMentioned()` | `channel.isMentioned` |
| Support flag | `channel.isUnreadCountSupport` | `channel.isUnreadCountSupported` | `channel.isUnreadCountSupport()` | Not exposed |
| Subchannel aggregate on channel | `channel.subChannelsUnreadCount` | `channel.subChannelsUnreadCount` | `channel.getSubChannelsUnreadCount()` | Not exposed |
| Total channel unread | `ChannelRepository.getTotalChannelsUnread(callback)` | `channelRepository.getTotalChannelsUnread()` | `channelRepository.getTotalChannelUnread()` | `getChannelTotalUnreads()` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `channelId` | Yes for single-channel reads | Channel ID used to retrieve or observe a channel model. |
| Channel object | Yes | Read `unreadCount` and `isMentioned` from the latest channel model returned by the SDK. |
| Aggregate observer | Yes for total unread | Subscribe to the total-unread API for cross-channel badge state. |
| Unsubscriber / token / disposable | Yes for live observers | Keep the returned handle while observing and release it when the UI no longer needs updates. |

## Read Channel Unread State

Read unread count and mention state from the channel object. If the platform exposes a support flag, check it before showing unread count for channel types that do not support markers.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getChannel(
  channelId,
  ({ data: channelSnapshot, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && channelSnapshot?.isUnreadCountSupport) {
      renderResults({
        unreadCount: channelSnapshot.unreadCount,
        isMentioned: channelSnapshot.isMentioned,
        subChannelsUnreadCount: channelSnapshot.subChannelsUnreadCount,
      });
    }
  },
);

unsubscribe();
```

```swift iOS
token = channelRepository.getChannel(channelId).observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    guard let channel = liveObject.snapshot else { return }

    if channel.isUnreadCountSupported {
        showSuccessMessage([
            "unreadCount": channel.unreadCount,
            "isMentioned": channel.isMentioned,
            "subChannelsUnreadCount": channel.subChannelsUnreadCount
        ])
    }
}
```

```kotlin Android
val currentChannel = channel ?: return

if (currentChannel.isUnreadCountSupport()) {
    showSuccessMessage(
        mapOf(
            "unreadCount" to currentChannel.getUnreadCount(),
            "isMentioned" to currentChannel.isMentioned(),
            "subChannelsUnreadCount" to currentChannel.getSubChannelsUnreadCount(),
        ),
    )
}
```

```dart Flutter
final fetchedChannel = await AmityChatClient.newChannelRepository()
    .getChannel(channelId);

final unreadCount = fetchedChannel.unreadCount ?? 0;
final isMentioned = fetchedChannel.isMentioned;
```


## Observe Total Channel Unread

Use total unread APIs for app-level badges or global chat navigation. The aggregate contains the unread count and whether any unread message mentions the current user.

The total unread count is calculated from the channels the SDK has already synced into its local cache. It is a live observation, not a one-time server fetch, so it starts at `0` and only reflects an accurate total after the channel list has been queried at least once. To show a total unread badge before the chat list screen appears, fetch the channel list first (for example, run a channel query in the background) so the SDK has the data to calculate from, then observe the total unread count.


```typescript TypeScript
import { ChannelRepository } from '@amityco/ts-sdk';

const unsubscribe = ChannelRepository.getTotalChannelsUnread(
  ({ data: unread, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && unread) {
      renderResults({
        unreadCount: unread.unreadCount,
        isMentioned: unread.isMentioned,
      });
    }
  },
);

unsubscribe();
```

```swift iOS
var cancellables = Set<AnyCancellable>()

channelRepository.getTotalChannelsUnread()
    .sink { unread in
        showSuccessMessage([
            "unreadCount": unread.unreadCount,
            "isMentioned": unread.isMentioned
        ])
    }
    .store(in: &cancellables)
```

```kotlin Android
val disposable = channelRepository
    .getTotalChannelUnread()
    .subscribe(
        { unread ->
            showSuccessMessage(
                mapOf(
                    "unreadCount" to unread.unreadCount,
                    "isMentioned" to unread.isMentioned,
                ),
            )
        },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
AmityChatClient.newChannelRepository()
    .getChannelTotalUnreads()
    .listen((unread) {
  final totalUnreadCount = unread.unreadCount;
  final hasMention = unread.isMentioned;
});
```


## Implementation Notes

    Per-channel values come from channel or subchannel models, so update the UI from SDK observations instead of maintaining a separate unread counter.
    Total channel unread is derived from locally synced channels. Fetch the channel list at least once before the count reflects an accurate total.
    Use `isMentioned` to visually prioritize channels where the current user has unread mentions.
    When your app uses subchannels directly, read subchannel unread fields from the subchannel model where the platform exposes them.
    Mark messages as read from the message model to update unread state.

## Related Topics

    Mark messages as read.
    Subscribe to receipt topics while a chat screen is open.
    Show latest-message previews beside unread badges.

---

### [Message Read Status](https://learn.social.plus/social-plus-sdk/chat/engagement-features/unread-status/message-read-status)

> Mark chat messages as read and inspect read-count fields from SDK message models.

Use message read status when a user views a message and your app needs unread counts to move forward. The SDK exposes `markRead()` on message models across TypeScript, iOS, Android, and Flutter.

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Mark read | `message.markRead()` | `message.markRead()` | `message.markRead()` | `message.markRead()` |
| Read count | `message.readCount` | `message.readCount` | `message.getReadCount()` | `message.readCount` |
| Delivered count | `message.deliveredCount` | `message.deliveredCount` | `message.getDeliveredCount()` | `message.deliveredCount` |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `message` | Yes | Message model returned by `getMessage` or a message query. |
| `messageId` | Yes when fetching first | Message ID used to retrieve a message before marking it read. |
| `subChannelId` | Indirect | The SDK reads this from the message model where needed. |
| `channelSegment` / segment | Indirect | The SDK reads this from the message model to sync the read position. |

## Mark Message Read

Call `markRead()` after your app decides the message has been seen, such as when the message becomes visible in an active chat screen.


```typescript TypeScript
message.markRead();

renderResults({
  messageId: message.messageId,
  readCount: message.readCount,
});
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let currentMessage = liveObject.snapshot else { return }

    currentMessage.markRead()
    showSuccessMessage(currentMessage.readCount)
}
```

```kotlin Android
val currentMessage = message ?: return

currentMessage.markRead()
showSuccessMessage(currentMessage.getReadCount())
```

```dart Flutter
final fetchedMessage = await AmityChatClient.newMessageRepository()
    .getMessage(messageId);

fetchedMessage.markRead();
final readCount = fetchedMessage.readCount ?? 0;
```


## Inspect Receipt Counts

Read-count and delivered-count fields are available on message models. Use user-list queries from [Message Delivery Status](./message-delivery-status) when you need the user identities behind the counts.


```typescript TypeScript
renderResults({
  readCount: message.readCount,
  deliveredCount: message.deliveredCount,
});
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let currentMessage = liveObject.snapshot else { return }

    showSuccessMessage([
        "readCount": currentMessage.readCount,
        "deliveredCount": currentMessage.deliveredCount
    ])
}
```

```kotlin Android
val currentMessage = message ?: return

showSuccessMessage(
    mapOf(
        "readCount" to currentMessage.getReadCount(),
        "deliveredCount" to currentMessage.getDeliveredCount(),
    ),
)
```

```dart Flutter
final fetchedMessage = await AmityChatClient.newMessageRepository()
    .getMessage(messageId);

final readCount = fetchedMessage.readCount ?? 0;
final deliveredCount = fetchedMessage.deliveredCount ?? 0;
```


## Implementation Notes

    `markRead()` is a method on the message object, so load or query messages before marking them read.
    Marking messages read is the write path that lets unread count state advance for the current user.
    Your app decides when a message is considered visible enough to mark as read.
    Use receipt-user APIs where supported when you need identities, not just count fields.

## Related Topics

    Read per-channel and total unread counts.
    Mark delivered and query receipt users where supported.
    Keep receipt state current while a chat screen is open.

---

### [Message Delivery Status](https://learn.social.plus/social-plus-sdk/chat/engagement-features/unread-status/message-delivery-status)

> Mark chat messages as delivered and query read or delivered users where the SDK supports it.

Use message delivery status when your app needs delivered receipts, read-user lists, or delivered-user lists for a message. TypeScript, iOS, and Android expose explicit delivery and receipt-user APIs. Flutter currently exposes message count fields, but not public APIs for marking a message delivered or querying receipt users.

## Platform Surface

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Mark delivered | `MessageRepository.markAsDelivered(subChannelId, messageId)` | `message.markAsDelivered()` | `message.markAsDelivered()` | Not exposed |
| Get read users | `MessageRepository.getReadUsers(query)` | `message.getReadUsers(memberships:)` | `message.getReadUsers(memberships)` | Not exposed |
| Get delivered users | `MessageRepository.getDeliveredUsers(query)` | `message.getDeliveredUsers(memberships:)` | `message.getDeliveredUsers(memberships)` | Not exposed |
| Count fields | `message.readCount`, `message.deliveredCount` | `message.readCount`, `message.deliveredCount` | `message.getReadCount()`, `message.getDeliveredCount()` | `message.readCount`, `message.deliveredCount` |

  Flutter developers can read `readCount` and `deliveredCount` from `AmityMessage`, but this SDK checkout does not expose public delivered-user or read-user query methods.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes for TypeScript delivery marking | Subchannel ID that owns the message being marked as delivered. |
| `messageId` | Yes | Message ID to mark delivered or use for receipt-user queries. |
| `message` | Yes for iOS and Android model methods | Message model returned by the SDK. |
| `memberships` | No | Filters receipt users by membership state. Supported values are member, banned, muted, non-member, and deleted. |
| Pagination controls | No | TypeScript returns a paged response; Android returns `PagingData`; iOS returns an `AmityCollection`. |

## Mark Message Delivered

Call the delivered API when a received message has reached the recipient device and your app needs to sync that delivery state.


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

const didMarkDelivered = await MessageRepository.markAsDelivered(
  subChannelId,
  messageId,
);

if (didMarkDelivered) {
  showSuccessMessage(messageId);
}
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let currentMessage = liveObject.snapshot else { return }

    Task {
        do {
            try await currentMessage.markAsDelivered()
            showSuccessMessage(currentMessage.messageId)
        } catch {
            handleError(error)
        }
    }
}
```

```kotlin Android
val currentMessage = message ?: return

val disposable = currentMessage
    .markAsDelivered()
    .subscribe(
        { showSuccessMessage(currentMessage.getMessageId()) },
        { error -> handleGeneralError(error) },
    )
```


## Query Read Users

Use read-user queries when you need to show who has read a message. Apply membership filters when your product only wants active members or needs to include muted, banned, non-member, or deleted users.


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

const { data: users, nextPage } = await MessageRepository.getReadUsers({
  messageId,
  memberships: ['member', 'muted', 'non-member'],
});

renderResults({
  users,
  nextPage,
});
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let currentMessage = liveObject.snapshot else { return }

    let memberships: Set<MessageReadMembershipFilter> = [
        .member,
        .muted,
        .nonMember
    ]
    let readUsers = currentMessage.getReadUsers(memberships: memberships)

    showSuccessMessage(readUsers)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.chat.message.MessageReadMembershipFilter

val currentMessage = message ?: return

val disposable = currentMessage
    .getReadUsers(
        memberships = listOf(
            MessageReadMembershipFilter.MEMBER,
            MessageReadMembershipFilter.MUTED,
            MessageReadMembershipFilter.NOT_MEMBER,
        ),
    )
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```


## Query Delivered Users

Use delivered-user queries when your sender UI or moderation tooling needs to know which recipients have received a message.


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

const { data: users, nextPage } = await MessageRepository.getDeliveredUsers({
  messageId,
  memberships: ['member', 'banned', 'deleted'],
});

renderResults({
  users,
  nextPage,
});
```

```swift iOS
let liveMessage = messageRepository.getMessage("message-id")

token = liveMessage.observe { liveObject, _ in
    guard let currentMessage = liveObject.snapshot else { return }

    let memberships: Set<MessageDeliveredMembershipFilter> = [
        .member,
        .banned,
        .deleted
    ]
    let deliveredUsers = currentMessage.getDeliveredUsers(memberships: memberships)

    showSuccessMessage(deliveredUsers)
}
```

```kotlin Android
import com.amity.socialcloud.sdk.model.chat.message.MessageDeliveredMembershipFilter

val currentMessage = message ?: return

val disposable = currentMessage
    .getDeliveredUsers(
        memberships = listOf(
            MessageDeliveredMembershipFilter.MEMBER,
            MessageDeliveredMembershipFilter.BANNED,
            MessageDeliveredMembershipFilter.DELETED,
        ),
    )
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) },
    )
```


## Receipt User Filters

| Logical value | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Member | `'member'` | `.member` | `MEMBER` |
| Banned | `'banned'` | `.banned` | `BANNED` |
| Muted | `'muted'` | `.muted` | `MUTED` |
| Non-member | `'non-member'` | `.nonMember` | `NOT_MEMBER` |
| Deleted | `'deleted'` | `.deleted` | `DELETED` |

## Related Topics

    Mark messages as read and inspect read count fields.
    Start receipt sync while a chat screen is active.
    Load the message models used by receipt APIs.

---

### [Message Receipt Sync](https://learn.social.plus/social-plus-sdk/chat/engagement-features/unread-status/message-receipt-sync)

> Start and stop chat message receipt synchronization for an active subchannel.

Use message receipt sync while a user is viewing a chat screen. It subscribes the SDK to receipt updates for a subchannel so read and delivery state can stay current. Stop sync when the user leaves the screen.

  This page covers the explicit public receipt-sync APIs. Flutter does not expose `startMessageReceiptSync` or `stopMessageReceiptSync` in the current public SDK surface.

## Platform Surface

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Start sync | `SubChannelRepository.startMessageReceiptSync(subChannelId)` | `AmitySubChannelRepository().startMessageReceiptSync(subChannelId:)` | `subChannelRepository.startMessageReceiptSync(subChannelId)` | Not exposed |
| Stop sync | `SubChannelRepository.stopMessageReceiptSync(subChannelId)` | `AmitySubChannelRepository().stopMessageReceiptSync(subChannelId:)` | `subChannelRepository.stopMessageReceiptSync(subChannelId)` | Not exposed |
| Result | `Promise<boolean>` / `boolean` | `Void` | `Completable` | Not exposed |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `subChannelId` | Yes | Subchannel whose message receipt topic should be synchronized. |
| Active chat lifecycle | Yes | Start sync when a user enters the message view and stop it when they leave. |
| Channel object | No | If you only have a channel, use its default subchannel ID where the platform exposes it. |
| Cleanup handle | Depends | TypeScript stop is explicit; Android and iOS use explicit stop calls; keep your own screen lifecycle ownership. |

## Start Receipt Sync

Start sync before or while rendering the active message list for a subchannel.


```typescript TypeScript
import { SubChannelRepository } from '@amityco/ts-sdk';

const didStart = await SubChannelRepository.startMessageReceiptSync(
  subChannelId,
);

if (didStart) {
  showSuccessMessage(subChannelId);
}
```

```swift iOS
let subChannelRepository = AmitySubChannelRepository()

try await subChannelRepository.startMessageReceiptSync(
    subChannelId: "sub-channel-id"
)

showSuccessMessage("sub-channel-id")
```

```kotlin Android
val subChannelRepository = AmityChatClient.newSubChannelRepository()

val disposable = subChannelRepository
    .startMessageReceiptSync(subChannelId)
    .subscribe(
        { showSuccessMessage(subChannelId) },
        { error -> handleGeneralError(error) },
    )
```


## Stop Receipt Sync

Stop sync when the active chat view closes, changes to another subchannel, or no longer needs live receipt state.


```typescript TypeScript
import { SubChannelRepository } from '@amityco/ts-sdk';

const didStop = SubChannelRepository.stopMessageReceiptSync(subChannelId);

if (didStop) {
  showSuccessMessage(subChannelId);
}
```

```swift iOS
let subChannelRepository = AmitySubChannelRepository()

try await subChannelRepository.stopMessageReceiptSync(
    subChannelId: "sub-channel-id"
)

showSuccessMessage("sub-channel-id")
```

```kotlin Android
val subChannelRepository = AmityChatClient.newSubChannelRepository()

val disposable = subChannelRepository
    .stopMessageReceiptSync(subChannelId)
    .subscribe(
        { showSuccessMessage(subChannelId) },
        { error -> handleGeneralError(error) },
    )
```


## Implementation Notes

    Tie receipt sync to the active chat screen, not to app startup.
    The public APIs take a `subChannelId`, so resolve the default subchannel from the channel when needed.
    Receipt sync keeps receipt state fresh; use `message.markRead()` to mark messages read.
    Do not add Flutter start/stop examples unless the Flutter SDK exposes public APIs for them.

## Related Topics

    Mark messages as read.
    Mark delivered and query receipt users.
    Show unread count and mention state in channel lists.

## Social — Communities

### [Social Module](https://learn.social.plus/social-plus-sdk/social/README)

> Add posts, comments, communities, reactions, notifications, and feeds to your app using the social.plus SDK Social Module.

Use the social.plus SDK Social Module to add posts, comments, communities, reactions, user relationships, notifications, stories, and feeds to your app. The SDK provides client APIs for custom UI implementations on top of social.plus managed infrastructure.

    Posts, comments, stories, and rich media content with real-time updates
    Create and manage communities with membership, roles, and moderation tools
    Reactions, notifications, feeds, search, and social interactions

## Key Capabilities

    **Posts, comments, stories, and media**
    - **Post Types**: Text, images, videos, files, polls, live stream posts, room posts, and custom post types
    - **Comments**: Create, query, edit, delete, and moderate comment threads
    - **Stories**: Create, retrieve, delete, and inspect story impressions where stories are enabled
    - **Media Handling**: Upload and display files, images, and videos through the SDK media guides
    - **Reactions & Mentions**: Add engagement and user references to supported content

    **Community structure, membership, and moderation**
    - **Community Creation**: Public or private communities with descriptions, avatars, tags, categories, and metadata
    - **Member Management**: Join, leave, add, remove, query, ban, mute, and role workflows
    - **Moderation**: Post review settings, content flagging, reporting, and permission checks
    - **Community Discovery**: Query, keyword search, category filtering, tags, trending, and recommended community collections where supported
    - **Governance**: Role-based permissions and community-level posting controls

    **Relationships and safety controls**
    - **Following**: Follow, unfollow, accept or decline follow requests, and query follower/following lists
    - **Blocking**: Block, unblock, and manage blocked users
    - **User Profile Fields**: Query and update social profile fields documented in User Management
    - **Relationship Status**: Read connection state and request state where supported

    **Feeds, search, and browsing**
    - **Feeds**: Query user, community, global, and For You (personalized) feeds
    - **Global Feed Ranking**: Use chronological ordering or configured custom post ranking where enabled
    - **Community Search**: Query communities by keyword, category, tags, membership filter, and sort order
    - **Enhanced Search**: Intelligent Search has separate setup and activation requirements in the Discovery & Engagement docs

    **Notifications and realtime-aware interactions**
    - **Notification Tray**: Query notification items and status where available
    - **Notification Events**: Work with social notification event references and settings
    - **Push Notifications**: Register devices and configure user, channel, or community settings in the Realtime Communication docs
    - **Realtime Updates**: Use live objects, live collections, and realtime events where supported by the target SDK


## Core Features

        Create content with media and moderation support
        - **Post Creation**: Text, image, video, file, poll, live stream, room, and custom post guides
        - **Content Metadata**: Multiple media types, mentions, and custom data where supported
        - **Content Management**: Edit, delete, and moderate posts
        - **Analytics**: Post impression guides where available

        Enable rich discussions with threaded conversations
        - **Threaded Discussions**: Nested comments with parent-children reply chain
        - **Real-time Updates**: Live comment feeds and notifications
        - **Mentions & Reactions**: Tag users and react to comments
        - **Moderation Tools**: Flag inappropriate content and manage discussions

        Share ephemeral content with time-limited visibility
        - **Media Stories**: Create image and video stories
        - **Engagement Tracking**: View counts, impressions, and viewer lists
        - **Global & Targeted Feeds**: Distribute to supported story targets
        - **Story Management**: Create, retrieve, inspect, and delete stories
        - **Analytics**: Story performance and audience insights

        Express emotions and drive engagement through reactions
        - **Flexible Reactions**: Custom reaction types
        - **Reaction Analytics**: Track popular reactions
        - **Bulk Operations**: Add/remove reactions efficiently
        - **Social Proof**: Display reaction counts and user lists

        Build and manage thriving social communities
        - **Community Creation**: Public, and private communities
        - **Member Management**: Roles, permissions, and member management
        - **Moderation**: Post review, reporting, ban, mute, and role workflows
        - **Community Discovery**: Query, search, trending, recommended, category, and tag-based flows where supported

        Manage follows, blocks, and social graphs
        - **Follow/Unfollow System**: Social connections with status tracking
        - **Block/Unblock Users**: Privacy controls and content filtering
        - **Relationship Management**: Connection requests and social graphs
        - **Privacy Controls**: Manage visibility and interactions

        Feed and timeline query APIs
        - **Feed Types**: Global, For You (personalized), user, and community feeds
        - **Ranking**: Chronological ordering and configured custom post ranking
        - **Content Filtering**: Hide unwanted content and filter by tags, and keywords
        - **Performance Optimization**: Efficient pagination and caching strategies

        Search and enhanced discovery options
        - **Community Search**: Search and filter community collections
        - **Post Search**: Search posts where the search feature is enabled
        - **Activation**: Intelligent Search requires network-level activation
        - **Scoring**: Relevance scores are documented on the Intelligent Search pages

        Notification docs for social engagement
        - **Notification Tray**: Centralized notification management with read/unread states
        - **Event-based Notifications**: Posts, comments, reactions, mentions, and community activities
        - **Settings**: User, channel, and community notification settings where supported

## Getting Started Workflows

    **Essential Features**: Posts + Comments + Reactions + Feed

    **Perfect for**: Social media apps, news platforms, community forums

    **Implementation Path**:
    1. **Setup Content Creation**: Implement post creation with [Posts](/social-plus-sdk/social/content-management/posts/overview)
    2. **Enable Discussions**: Add comment functionality with [Comments](/social-plus-sdk/social/content-management/comments/overview)
    3. **Add Engagement**: Implement reactions with [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)
    4. **Create Feeds**: Query user, community, global, and For You (personalized) feeds with [Feed](/social-plus-sdk/social/discovery-engagement/feed/overview)
    5. **Enable Notifications**: Setup [Notification System](/social-plus-sdk/social/discovery-engagement/notifications/overview)

    **Optional Enhancements**: Stories, user following, and search

    **Checkpoint**: Verify post, comment, reaction, feed, and notification behavior on the target SDKs you ship

    **Essential Features**: Communities + Posts + Moderation + Search

    **Perfect for**: Forums, professional networks, interest-based communities

    **Implementation Path**:
    1. **Setup Communities**: Create community structure with [Communities](/social-plus-sdk/social/communities-spaces/overview)
    2. **Enable Content Creation**: Add posts and discussions with moderation
    3. **Implement User Management**: Setup roles and permissions
    4. **Add Discovery**: Enable community search, feeds, and [Intelligent Search](/social-plus-sdk/social/discovery-engagement/search/overview) only where configured
    5. **Setup Moderation**: Configure content filtering and community management

    **Optional Enhancements**: Stories, notification settings, and analytics/moderation Console workflows

    **Checkpoint**: Verify community creation, discovery, membership, roles, and moderation permissions on the target SDKs you ship

    **Essential Features**: User profiles + Follow system + Notifications

    **Perfect for**: Professional networks, dating apps, social discovery

    **Implementation Path**:
    1. **Setup User Interactions**: Implement [Follow/Unfollow](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)
    2. **Add Privacy Controls**: Enable [Block/Unblock](/social-plus-sdk/social/user-relationship/blocking/block-unblock-user) functionality
    3. **Create Activity Feeds**: Build user-specific feeds and timelines
    4. **Enable Notifications**: Setup [Notification Tray](/social-plus-sdk/social/discovery-engagement/notifications/overview)
    5. **Add Discovery**: Add search and product-specific recommendation surfaces where needed

    **Optional Enhancements**: Messaging, notification settings, and product-specific recommendations

    **Checkpoint**: Verify follow request states, block behavior, user profile visibility, and notifications on the target SDKs you ship

    **Essential Features**: Selected social modules working together

    **Perfect for**: Products that combine feeds, communities, relationships, search, notifications, and moderation

    **Implementation Path**:
    1. **Foundation**: Implement the core features your product needs (for example Posts, Comments, and Communities)
    2. **Discovery**: Add [Search](/social-plus-sdk/social/discovery-engagement/search/overview), feeds, trending communities, and recommended communities where enabled
    3. **Feed Ranking**: Decide whether chronological or configured custom post ranking is right for the product
    4. **Analytics**: Use SDK analytics pages and Console analytics where they apply
    5. **Moderation**: Combine SDK reporting, roles, permissions, and Console moderation workflows

    **Optional Enhancements**: Live streaming, stories, notification settings, and analytics/moderation Console workflows

    **Checkpoint**: Treat this as a cross-module integration and validate each target platform separately

## Platform Support

    **iOS, Android, TypeScript, and Flutter**
    - Native iOS and Android SDKs
    - TypeScript/JavaScript SDK for web apps
    - Flutter SDK for cross-platform mobile apps
    **Use the target SDK docs**
    - Setup requirements differ by platform
    - Method names and enum availability can vary
    - Validate snippets against the SDK you ship
    **Use when your implementation crosses SDK boundaries**
    - UIKit for prebuilt UI components
    - API reference for server-side workflows
    - Console docs for moderation and analytics operations

## Related Documentation

    **Real-time messaging capabilities**

    Build chat features with channels, messages, and real-time communication

    **SDK fundamentals and architecture**

    Learn about authentication, sessions, and core SDK concepts

    **Live streaming and broadcasting**

    Add room-based broadcasting, live viewing, and playback flows

    **Pre-built UI components**

    Ready-to-use UI components for rapid development

    **Analytics and insights**

    Track engagement, user behavior, and community health

    **Content moderation tools**

    Advanced content moderation and community safety features

---

### [Overview](https://learn.social.plus/social-plus-sdk/social/communities-spaces/overview)

> Create and manage communities with configurable privacy, post moderation, membership workflows, roles, and content controls.

Use the community SDK APIs to create communities, manage membership and roles, configure posting rules, and build discovery flows. Communities support public and private access modes, discoverability settings, join approval where configured, role-based permissions, and post or story moderation settings.

**Looking for a step-by-step walkthrough?** The [Community Platform](/use-cases/social/community-platform) guide walks you through building communities with membership, governance, and moderation end-to-end.

## Core Capabilities

    Query, search, sort, and filter communities by membership, category, tags, and keyword
    Join, leave, add, remove, query, ban, mute, and role workflows
    Post settings, role-based permissions, reporting, and moderation actions
    Community categories, metadata, tags, counts, and status fields


Community objects expose fields for identity, visibility, membership, moderation settings, tags, categories, counts, and status. Start with the fields your product needs, then add governance options as your community flows become clearer.

## Community Architecture

Communities in social.plus group posts, members, roles, and moderation settings under a single community object. Use communities for forums, interest groups, private spaces, announcement areas, and other social areas that need membership and content controls.

### Core Components

    **Visual Identity**
    - Display name and description
    - Avatar and visual branding
    - Official verification status
    - Custom metadata fields

    **Discoverability**
    - Public/private visibility settings
    - Search tags and categorization
    - Query, search, trending, and recommended collections where supported
    - Category-based organization

    **Access Control**
    - Public vs private community types
    - Join approval requirements
    - Invitation workflows where configured
    - Membership state and access behavior

    **Membership Lifecycle**
    - User-initiated joining and leaving
    - Administrative member addition/removal
    - Role-based access and permissions
    - Member onboarding workflows

    **Content Management**
    - Post creation and moderation
    - Admin-only posting restrictions
    - Content approval workflows
    - Flagging and reporting systems

    **Governance Structure**
    - Role hierarchy and permissions
    - Moderation tools and enforcement
    - Community-level posting controls
    - Admin and moderator workflows

    **Community Counts**
    - Member count
    - Post count
    - Joined and deleted state
    - Flagged post/comment indicators

    **Operational Data**
    - Creation and modification timestamps
    - Deletion status
    - Official status
    - Associated channel ID

## Community Types & Access Models

social.plus supports community configurations for open discovery, controlled membership, and official community labeling:

    **Open Access**: Can be discoverable and joinable by users

    **Moderated Access**: Can require approval to join when configured

    **Content Visibility**: Build product-specific visibility behavior from community and post query results
    **Controlled Access**: Intended for restricted membership flows

    **Discovery**: Usually hidden from general discovery depending on configuration

    **Membership**: Use invitation, add member, or approval flows that match your product
    **Official Flag**: Community objects can expose official status

    **Product Display**: Use this flag for badges or filtering if your product needs it

    **Administration**: Treat official designation as an admin-controlled field

## Common Community Fields

Community objects include identity, visibility, membership, moderation, organization, and status fields. Field availability and naming can vary slightly across SDKs, so use the model exposed by your target platform SDK.

### Core Properties

| Property | Type | Description |
|----------|------|-------------|
| `communityId` | String | Unique identifier for the community |
| `channelId` | String | Associated channel identifier |
| `userId` | String | ID of the user who created the community |
| `displayName` | String | Community name for displaying |
| `description` | String | Description of the community |
| `avatar` | Object | Avatar object for community branding |

### Access & Visibility Controls

| Property | Type | Description |
|----------|------|-------------|
| `isPublic` | Boolean | Is this community public? |
| `isDiscoverable` | Boolean | Whether this community can appear in discovery/search surfaces |
| `requiresJoinApproval` | Boolean | Whether joining this community requires approval |
| `isOfficial` | Boolean | Is this community official? |

### Content & Moderation

| Property | Type | Description |
|----------|------|-------------|
| `onlyAdminCanPost` | Boolean | Only admins can post in this community |
| `postSettings` | Object | Community post settings such as review-required or admin-only posting |
| `needApprovalOnCommentCreation` (TypeScript) / `isCommentReviewEnabled` (iOS) / `isCommentReviewEnabled()` (Android) | Boolean | Whether members' comments are held for moderator review. Not exposed on Flutter. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review) |
| `hasFlaggedPost` | Boolean | Indicates whether the community has flagged posts |
| `hasFlaggedComment` | Boolean | Indicates whether the community has flagged comments |

### Organization & Discovery

| Property | Type | Description |
|----------|------|-------------|
| `categoryIds` | List | IDs of categories associated with the community |
| `tags` | List | Tags used for filtering and search |
| `metadata` | Object | Custom fields for your product. Do not store sensitive personal data here. |

### Counts & Status

| Property | Type | Description |
|----------|------|-------------|
| `postsCount` | Integer | Number of posts in the community |
| `membersCount` | Integer | Number of members in the community |
| `isJoined` | Boolean | Is this community joined? |
| `isDeleted` | Boolean | Is this community deleted? |
| `createdAt` | DateTime | Date/time when the community was created |
| `updatedAt` | DateTime | Date/time when a community is updated or deleted |

For create and update flows, review the platform-specific community builder or options object. Some fields are read-only response fields, while others can be configured when creating or editing a community.

## Best Practices

**Start Simple, Then Add Governance**: Begin with community creation, query, join/leave, and basic moderation. Add categories, roles, approval, and notification settings as the product flow requires them.

    **Planning & Purpose**
    1. **Clear Purpose**: Define community goals and target audience before creation
    2. **Appropriate Access Model**: Choose public/private settings based on community needs
    3. **Governance Planning**: Establish moderation policies and role structures early
    4. **Growth Strategy**: Plan discovery, onboarding, and member retention flows

    **Design Considerations**
    - Start with basic features and expand gradually
    - Consider your target audience's needs and behaviors
    - Keep privacy, moderation, and discovery decisions explicit
    - Design clear user journeys for joining and participating

    **Architecture & Development**
    1. **Data Modeling**: Understand the community object structure before building
    2. **Permission Architecture**: Implement proper role-based access controls from the start
    3. **User Experience**: Design intuitive flows for joining, participating, and moderating
    4. **Performance Optimization**: Plan for pagination and live collection updates

    **Development Best Practices**
    - Implement proper error handling for community operations
    - Use appropriate data validation for community properties
    - Design for mobile-first community experiences
    - Subscribe to live objects or live collections where supported by the target SDK

    **Operational Excellence**
    1. **Active Moderation**: Implement consistent content oversight and member management
    2. **Clear Guidelines**: Establish and communicate community rules and expectations
    3. **Member Engagement**: Foster participation through events, discussions, and recognition
    4. **Continuous Improvement**: Use available counts, moderation state, and your product analytics to iterate on community features

    **Management Strategies**
    - Establish clear moderation workflows and escalation paths
    - Create onboarding experiences for new community members
    - Implement feedback loops to understand member satisfaction
    - Regularly review moderation queues and community health signals

    **Sustainable Growth**
    - Focus on quality over quantity in early growth phases
    - Implement referral and invitation systems for organic growth
    - Use query, search, category, tag, trending, or recommended community flows where they fit the product
    - Create incentives for active community participation

    **Scaling Considerations**
    - Plan moderation resources as communities grow
    - Use SDK moderation actions and Console moderation workflows where appropriate
    - Consider community subdivision strategies for large groups
    - Monitor product metrics as membership increases

## Next Steps

Ready to start building? Choose your implementation path:

    Step-by-step community creation guide
    Build community search and browsing
    Configure roles, permissions, and moderation

**Need Help?** Start with the creation, query, membership, and moderation guides below, then add categories, roles, and notification settings as your use case grows.

---

### [Create Community](https://learn.social.plus/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community)

> Create a community with SDK-backed privacy, moderation, story, category, metadata, and member settings.

Use the create-community API for your platform to set up a community with a display name, description, privacy mode, category IDs, post moderation setting, story settings, metadata, and optional initial members.

Public/private visibility, discoverability, and join approval are separate settings in the SDK. Configure the combination that matches your product flow, then rely on backend permission enforcement for actual access control.

## Parameters

TypeScript exposes `CommunityRepository.createCommunity()`. iOS uses `AmityCommunityCreateOptions` with `createCommunity(with:)`. Android and Flutter start from `AmitySocialClient.newCommunityRepository().createCommunity(...)`.

| Setting | Platforms | Description |
|---------|-----------|-------------|
| `displayName` | TypeScript, iOS, Android, Flutter | Required community display name |
| `description` | TypeScript, iOS, Android, Flutter | Optional community description |
| `isPublic` | TypeScript, iOS, Android, Flutter | Public/private visibility flag |
| `avatarFileId` / `avatar` | TypeScript / iOS, Android, Flutter | Avatar file ID or uploaded SDK image object |
| `categoryIds` | TypeScript, iOS, Android, Flutter | Category IDs linked to the community |
| `postSetting` / `postSettings` | TypeScript, iOS, Android, Flutter | Post creation and review setting |
| `needApprovalOnCommentCreation` / `setNeedApprovalOnCommentCreation(_:)` / `isCommentReviewEnabled` | TypeScript / iOS / Android | Hold members' comments for moderator review. Defaults to `false`. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review) |
| `storySetting` / `storySettings` | TypeScript, iOS, Android, Flutter | Story comment setting |
| `metadata` | TypeScript, iOS, Android, Flutter | Custom metadata object |
| `userIds` | TypeScript, iOS, Android, Flutter | Initial members to add during creation |
| `tags` | TypeScript, Android, Flutter | Search/filter tags |
| `isDiscoverable` | TypeScript, iOS, Android | Whether a private community can appear in discovery surfaces |
| `requiresJoinApproval` | TypeScript, iOS, Android | Whether join requests require approval |

## Privacy Settings

| Setting | Description |
|---------|-------------|
| `isPublic` | Controls whether the community is public or private |
| `isDiscoverable` | Lets supported SDKs create discoverable private communities |
| `requiresJoinApproval` | Lets supported SDKs request approval before users join |

## Post Moderation Options

| Concept | TypeScript | iOS | Android / Flutter |
|---------|------------|-----|-------------------|
| Anyone can post | `ANYONE_CAN_POST` | `.anyoneCanPost` | `ANYONE_CAN_POST` |
| Admin review required | `ADMIN_REVIEW_POST_REQUIRED` | `.adminReviewPostRequired` | `ADMIN_REVIEW_POST_REQUIRED` |
| Admins only | `ONLY_ADMIN_CAN_POST` | `.onlyAdminCanPost` | `ADMIN_CAN_POST_ONLY` |

## Comment Review Option

Comment review is a separate community setting from post review. When it is on, comments on the community's posts are held until a reviewer approves them, unless their author can review the community's comments.

| Concept | TypeScript | iOS | Android | Flutter |
|---------|------------|-----|---------|---------|
| Set on create or update | `needApprovalOnCommentCreation: true` | `setNeedApprovalOnCommentCreation(true)` | `isCommentReviewEnabled(true)` on the builder | Not exposed |
| Read on the community | `community.needApprovalOnCommentCreation` | `community.isCommentReviewEnabled` | `community.isCommentReviewEnabled()` | Not exposed |

On Flutter, turn comment review on from the Console, another SDK, or the server API. For who is held, the review queue, and approve or decline, see [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review).

## Story Settings

Communities can be configured with story comment settings:

| Platform | Shape |
|----------|-------|
| TypeScript | `storySetting: { enableComment: true }` |
| iOS | `setStorySettings(allowComment: true)` |
| Android / Flutter | `AmityCommunityStorySettings(allowComment = true)` / `AmityCommunityStorySettings(allowComment: true)` |

## Create a Community

Use this method after your app has collected the required display name and any optional privacy, moderation, category, member, tag, or metadata settings.

```typescript TypeScript
import { CommunityPostSettings, CommunityRepository } from '@amityco/ts-sdk';

async function createCommunity(): Promise<Amity.Community> {
  const { data: community } = await CommunityRepository.createCommunity({
    displayName: 'My Community',
    description: 'Community description',
    isPublic: true,
    isDiscoverable: true,
    requiresJoinApproval: false,
    postSetting: CommunityPostSettings.ANYONE_CAN_POST,
    storySetting: { enableComment: true },
    categoryIds: ['categoryId'],
    tags: ['product'],
    metadata: { topic: 'product' },
    userIds: ['userId1', 'userId2'],
  });

  return community;
}
```

```swift iOS
let options = AmityCommunityCreateOptions()
options.setDisplayName("My Community")
options.setCommunityDescription("Community description")
options.setIsPublic(true)
options.setCategoryIds(["categoryId"])
options.setUserIds(["userId1", "userId2"])
options.setPostSettings(.anyoneCanPost)
options.setStorySettings(allowComment: true)
options.setIsDiscoverable(true)
options.setRequiresJoinApproval(false)
options.setMetadata(["topic": "product"])

let community = try await communityRepository.createCommunity(with: options)
```

```kotlin Android
fun createCommunity() {
    val metadata = JsonObject().apply {
        addProperty("topic", "product")
    }

    AmitySocialClient.newCommunityRepository()
        .createCommunity(
            displayName = "My Community",
            isDiscoverable = true,
            requiresJoinApproval = false
        )
        .description("Community description")
        .isPublic(true)
        .categoryIds(listOf("categoryId"))
        .userIds(listOf("userId1", "userId2"))
        .tags(listOf("product"))
        .metadata(metadata)
        .postSettings(AmityCommunityPostSettings.ANYONE_CAN_POST)
        .storySettings(AmityCommunityStorySettings(allowComment = true))
        .build()
        .create()
        .doOnSuccess { community: AmityCommunity ->
            // Community created.
        }
        .doOnError { error ->
            // Handle error.
        }
        .subscribe()
}
```

```dart Flutter
void createCommunity() {
  AmitySocialClient.newCommunityRepository()
      .createCommunity('My Community')
      .description('Community description')
      .categoryIds(['categoryId'])
      .userIds(['userId1', 'userId2'])
      .tags(['product'])
      .isPublic(true)
      .metadata({'topic': 'product'})
      .postSetting(AmityCommunityPostSettings.ANYONE_CAN_POST)
      .storySettings(AmityCommunityStorySettings(allowComment: true))
      .create()
      .then((AmityCommunity community) {
        // Community created.
      })
      .onError((error, stackTrace) {
        // Handle error.
      });
}
```

Community tags are shown for TypeScript, Android, and Flutter. The current iOS create/update options do not expose a public community tag setter.

## Best Practices

Start with basic settings and allow community owners to customize moderation and features after creation to avoid overwhelming the initial creation flow.

### Creation Flow Guidelines

1. Show essential settings first, advanced options later.
2. Use sensible defaults to reduce decision fatigue.
3. Allow users to preview community settings before creation.
4. Guide new community creators through setup.

### Performance Optimization

1. Compress avatar images before upload.
2. Validate metadata structure client-side.
3. Handle creation asynchronously with loading states.
4. Provide clear error messages and retry options.

## Related Topics

    Modify community settings and properties after creation
    Organize communities with category management
    Handle membership and moderation after community creation
    Make your created communities discoverable to users

---

### [Update Community](https://learn.social.plus/social-plus-sdk/social/communities-spaces/community-lifecycle/update-community)

> Update community profile, visibility, categories, moderation, story, and metadata settings with the SDK.

Use the update API for your platform to change a community's display name, description, avatar, category IDs, privacy mode, post moderation setting, comment review setting, story settings, or custom metadata. TypeScript and Flutter use `updateCommunity()`, while iOS and Android use `editCommunity`.

The backend enforces who can update a community. In your UI, expose these controls only to users who can manage community settings, such as creators, moderators, or administrators in your product model.

## Parameters

Community updates modify the community record while preserving the same `communityId`. Use them for profile changes, visibility changes, category changes, and moderation-setting changes.

| Setting | Platforms | Description |
|---------|-----------|-------------|
| `communityId` | TypeScript, iOS, Android, Flutter | Required community ID |
| `displayName` | TypeScript, iOS, Android, Flutter | Updated display name |
| `description` | TypeScript, iOS, Android, Flutter | Updated description |
| `isPublic` | TypeScript, iOS, Android, Flutter | Updated public/private visibility |
| `avatarFileId` / `avatar` | TypeScript / iOS, Android, Flutter | Updated avatar file ID or uploaded SDK image object |
| `categoryIds` | TypeScript, iOS, Android, Flutter | Updated category IDs |
| `postSetting` / `postSettings` | TypeScript, iOS, Android, Flutter | Updated post creation and review setting |
| `needApprovalOnCommentCreation` / `setNeedApprovalOnCommentCreation(_:)` / `isCommentReviewEnabled` | TypeScript / iOS / Android | Turn comment review on or off. Turning it off does not clear comments already waiting for review. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review) |
| `storySetting` / `storySettings` | TypeScript, iOS, Android, Flutter | Updated story comment setting |
| `metadata` | TypeScript, iOS, Android, Flutter | Updated custom metadata object |
| `tags` | TypeScript, Android, Flutter | Updated search/filter tags |
| `isDiscoverable` | TypeScript, iOS, Android | Updated discoverability setting |
| `requiresJoinApproval` | TypeScript, iOS, Android | Updated join approval setting |

## Permission Requirements

Do not treat client-side role checks as the source of truth. They are useful for hiding or showing controls, but the SDK call still depends on the permissions enforced by your social.plus backend configuration.

## Update a Community

Use this method for profile, visibility, category, moderation, story, tag, and metadata changes after a community has already been created.

```typescript TypeScript
import { CommunityPostSettings, CommunityRepository } from '@amityco/ts-sdk';

async function updateCommunity() {
  const updatedCommunity: Parameters<typeof CommunityRepository.updateCommunity>[1] = {
    avatarFileId: 'fileId',
    description: 'Updated community description',
    displayName: 'Updated community name',
    isPublic: true,
    categoryIds: ['news'],
    tags: ['product'],
    metadata: { topic: 'product' },
    postSetting: CommunityPostSettings.ADMIN_REVIEW_POST_REQUIRED,
    storySetting: { enableComment: true },
    isDiscoverable: true,
    requiresJoinApproval: false,
  };

  const { data: community } = await CommunityRepository.updateCommunity(
    'communityId',
    updatedCommunity,
  );

  return community;
}
```

```swift iOS
let updateOptions = AmityCommunityUpdateOptions()
updateOptions.setDisplayName("updated-name")
updateOptions.setCommunityDescription("updated-description")
updateOptions.setIsPublic(false)
updateOptions.setCategoryIds(["categoryId"])
updateOptions.setPostSettings(.adminReviewPostRequired)
updateOptions.setStorySettings(allowComment: true)
updateOptions.setIsDiscoverable(true)
updateOptions.setRequiresJoinApproval(false)
updateOptions.setMetadata(["topic": "product"])

let community = try await communityRepository.editCommunity(withId: "community-id", options: updateOptions)
```

```kotlin Android
fun editCommunity() {
    val metadata = JsonObject().apply {
        addProperty("topic", "product")
    }

    AmitySocialClient.newCommunityRepository()
        .editCommunity(
            communityId = "communityId1",
            isDiscoverable = true,
            requiresJoinApproval = false
        )
        .displayName("Updated community name")
        .isPublic(isPublic = true)
        .description(description = "Updated community description")
        .categoryIds(categoryIds = listOf("categoryId1", "categoryId2"))
        .tags(tags = listOf("product"))
        .metadata(metadata)
        .postSettings(AmityCommunityPostSettings.ADMIN_REVIEW_POST_REQUIRED)
        .storySettings(AmityCommunityStorySettings(allowComment = true))
        .build()
        .apply()
        .doOnSuccess { community: AmityCommunity ->
            // Community updated.
        }
        .doOnError { error ->
            // Handle error.
        }
        .subscribe()
}
```

```dart Flutter
void updateCommunity(String communityId, AmityImage updatingAvatar) {
  AmitySocialClient.newCommunityRepository()
      .updateCommunity(communityId)
      .avatar(updatingAvatar)
      .displayName('Updated community name')
      .description('Updated community description')
      .tags(['product'])
      .categoryIds(['categoryId1', 'categoryId2'])
      .isPublic(false)
      .postSetting(AmityCommunityPostSettings.ADMIN_REVIEW_POST_REQUIRED)
      .storySettings(AmityCommunityStorySettings(allowComment: true))
      .metadata({'topic': 'product'})
      .update()
      .then((AmityCommunity community) {
        // Community updated.
      })
      .onError((error, stackTrace) {
        // Handle error.
      });
}
```

## Privacy and Visibility Updates

### Public to Private Changes

Changing a public community to private affects how users discover and join it:

Changing visibility affects discovery and join flows. Check the resulting community state and update your UI accordingly.

### Private to Public Changes

Changing a private community to public can affect discovery and new membership flows:

Making a community public can make it available to a wider audience, depending on your discovery query and backend configuration.

## Best Practices

Notify community members about significant updates, such as privacy changes or moderation policy updates, to maintain transparency and community trust.

### Update Guidelines

1. Make small, focused updates rather than large batch changes.
2. Inform members about policy or privacy changes.
3. Preserve important metadata when updating.
4. Validate changes before applying to prevent errors.
5. Test updates in staging environments when possible.

## Related Topics

    Learn about initial community creation and setup
    Delete a community and handle client-side cleanup
    Advanced moderation features and member management
    Organize communities with category management

---

### [Delete Community](https://learn.social.plus/social-plus-sdk/social/communities-spaces/community-lifecycle/delete-community)

> Delete a community by ID with SDK permission enforcement and client-side cleanup.

The SDK exposes a delete-community API for authorized users when a community is no longer needed. Treat deletion as irreversible from the client UI, and confirm your product's data-retention and recovery policy outside the client SDK.

Deleting a community cannot be undone through the client SDK. Use explicit confirmation in your product UI before calling the SDK method.

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `communityId` | String | Yes | Unique identifier of the community to delete |

## Permission Requirements

Deletion is permission-gated by the backend. In most products, deletion controls are shown only to community creators, moderators, or administrators, but the SDK call is still validated server-side.

## Delete a Community

Call the delete-community method with a `communityId`. TypeScript, Android, and Flutter use `deleteCommunity`; iOS uses `deleteCommunity(withId:)`.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function deleteCommunity(communityId: Amity.Community['communityId']): Promise<Amity.Community> {
  const deletedCommunity = await CommunityRepository.deleteCommunity(communityId);

  return deletedCommunity;
}
```

```swift iOS
try await communityRepository.deleteCommunity(withId: "community-id")
```

```kotlin Android
fun deleteCommunity() {
    AmitySocialClient.newCommunityRepository()
        .deleteCommunity(communityId = "communityId")
        .doOnComplete {
            // Community deleted.
        }
        .doOnError { error ->
            // Handle error.
        }
        .subscribe()
}
```

```dart Flutter
void deleteCommunity(String communityId) {
  AmitySocialClient.newCommunityRepository()
      .deleteCommunity(communityId)
      .then((value) {
        // Community deleted.
      })
      .onError((error, stackTrace) {
        // Handle error.
      });
}
```

## Client Impact

After successful deletion, handle the client-side effects explicitly:

- Remove the community from any local list or cached UI state.
- Navigate away from deleted community detail screens.
- Stop showing actions that require the deleted `communityId`.
- Refresh affected discovery or membership queries when needed.

## Pre-deletion Considerations

### Product Policy

Before exposing deletion, decide how your product handles:

1. What data is retained or recoverable outside the client SDK.
2. Whether members should be notified before deletion.
3. Whether archive, privacy, or moderation actions are safer than deletion.

### Member Management

Refresh membership and discovery views after deletion so users do not see stale references to the deleted community.

## Best Practices

Implement multiple confirmation steps and consider a cooling-off period for community deletion requests to prevent impulsive decisions.

### Implementation Guidelines

1. Require multiple explicit confirmations.
2. Make users type the community name to confirm.
3. Verify user permissions before showing delete options.
4. Show clear progress during deletion operations.
5. Provide clear confirmation of successful deletion.

### User Experience Considerations

1. Emphasize the permanent nature of deletion.
2. Offer data export before deletion if your product supports it.
3. Provide tools to notify community members.
4. Handle post-deletion navigation appropriately.

## Related Topics

    Modify community settings as an alternative to deletion
    Manage communities with moderation tools instead of deletion
    Learn about community creation to understand deletion impact
    Handle member relationships before community deletion

---

### [Query Communities](https://learn.social.plus/social-plus-sdk/social/communities-spaces/discovery/query-communities)

> Query and search communities by membership, category, tags, keyword, and sort order.

Use community query APIs to browse communities by membership, category, tag filters where supported, and sort order. Use the platform's search API or keyword option when you need name-based search.

    Query communities with filtering and sorting options
    Find specific communities using keyword-based search
    Filter by user membership status and community access
    Organize discovery by community categories and topics

## Parameters

### Query Parameters

| Setting | Platforms | Description |
| --- | --- | --- |
| Membership filter | TypeScript, iOS, Android, Flutter | Filter by all, joined, or not-joined communities. |
| Sort order | TypeScript, iOS, Android, Flutter | Sort by display name, newest first, or oldest first. |
| `categoryId` | TypeScript, iOS, Android, Flutter | Filter by category ID. |
| `tags` | TypeScript, Android, Flutter | Filter by community tags. |
| `includeDeleted` | TypeScript, iOS, Android, Flutter | Include or exclude deleted communities. |
| `includeDiscoverablePrivateCommunity` | TypeScript, iOS, Android | Include discoverable private communities where supported. |

### Search Parameters

| Parameter | Platforms | Description |
| --- | --- | --- |
| Search keyword | TypeScript, iOS, Android, Flutter | Community display-name keyword. TypeScript uses `displayName`, iOS and Android use `keyword`, and Flutter uses `.withKeyword(...)`. |
| Membership filter | TypeScript, iOS, Android, Flutter | Filter by membership status. |
| Sort order | TypeScript, iOS, Android, Flutter | Sort by display name, newest first, or oldest first. |
| `categoryId` | TypeScript, iOS, Android, Flutter | Filter search results by category ID. |
| `tags` | TypeScript, Android, Flutter | Filter search results by community tags. |
| `includeDeleted` | TypeScript, iOS, Android, Flutter | Include deleted communities. |
| `includeDiscoverablePrivateCommunity` | TypeScript, iOS, Android | Include discoverable private communities where supported. |

## Filter Options

### Membership Status Filtering

Control discovery based on the current user's membership status:

| Concept | TypeScript | iOS | Android / Flutter |
|---------|------------|-----|-------------------|
| All communities | `membership: "all"` | `.all` | `ALL` |
| Joined communities | `membership: "member"` | `.userIsMember` | `MEMBER` |
| Not joined communities | `membership: "notMember"` | `.userIsNotMember` | `NOT_MEMBER` |

### Sorting Options

Organize community results to match your app's discovery flow:

| Concept | TypeScript | iOS | Android / Flutter |
|---------|------------|-----|-------------------|
| Display name ascending | `"displayName"` | `.displayName` | `DISPLAY_NAME` |
| Newest first | `"lastCreated"` | `.lastCreated` | `LAST_CREATED` |
| Oldest first | `"firstCreated"` | `.firstCreated` | `FIRST_CREATED` |

### Category Filtering

Communities can be organized by categories to help users find relevant content faster. When a `categoryId` is specified, results are filtered to only include communities belonging to that category.

### Tag Filtering

Communities can be tagged to describe their topics or purpose. TypeScript, Android, and Flutter expose a `tags` filter on the query/search builders shown below. The published iOS SDK used for this page does not expose a tag parameter on `AmityCommunityQueryOptions` or `AmityCommunitySearchOptions`.

Combine tag filtering with category and membership filters for precise discovery experiences.

## Query Communities

The query-community API returns a collection of communities that match the provided filters.
TypeScript, iOS, and Flutter expose Live Collection style APIs. Android returns `Flowable<PagingData<AmityCommunity>>`.

Android's `getCommunities().withKeyword(...)` is deprecated. Use `searchCommunities(keyword = ...)` on Android for keyword search.

```swift iOS
var queryCommunitiesToken: AmityNotificationToken?

func queryCommunities() {
    let queryOptions = AmityCommunityQueryOptions(
        filter: .all,
        sortBy: .lastCreated,
        categoryId: "categoryId",
        includeDeleted: false,
        includeDiscoverablePrivateCommunity: true
    )

    let liveCollection = communityRepository.getCommunities(with: queryOptions)
    queryCommunitiesToken = liveCollection.observe { collection, error in
        if let error = error {
            print("Error querying communities: \(error)")
            return
        }

        for community in collection.snapshots {
            // Handle each community in the results
            print("Community: \(community.displayName)")
        }
    }
}

```

```kotlin Android
fun queryCommunities() {
    AmitySocialClient.newCommunityRepository()
        .getCommunities(includeDiscoverablePrivateCommunity = true)
        .sortBy(sortBy = AmityCommunitySortOption.LAST_CREATED)
        .filter(filter = AmityCommunityFilter.ALL)
        .categoryId(categoryId = "categoryId")
        .tags(tags = listOf("gaming", "tech"))
        .includeDeleted(includeDeleted = false)
        .build()
        .query()
        .doOnNext { pagingData: PagingData<AmityCommunity> ->
            // Handle community results
        }
        .doOnError { error ->
            // Handle error
        }
        .subscribe()
}

```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

let nextPageFn: (() => void) | undefined;
let hasMore: boolean | undefined;

const unsubscribeCommunities = CommunityRepository.getCommunities(
  {
    membership: 'all',
    sortBy: 'lastCreated',
    categoryId: 'category-id',
    includeDeleted: false,
    includeDiscoverablePrivateCommunity: true,
    tags: ['gaming', 'tech'],
    limit: 20,
  },
  ({ data: communities, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render communities.
    }
    hasMore = hasNextPage;
    nextPageFn = onNextPage;
  },
);

function loadMore() {
  if (hasMore) {
    nextPageFn?.();
  }
}
```

```dart Flutter
void queryCommunities() {
  final liveCollection = AmitySocialClient.newCommunityRepository()
      .getCommunities()
      .filter(AmityCommunityFilter.ALL)
      .sortBy(AmityCommunitySortOption.LAST_CREATED)
      .categoryId('categoryId')
      .tags(['gaming', 'tech'])
      .includeDeleted(false)
      .getLiveCollection(pageSize: 20);

  liveCollection.getStreamController().stream.listen((communities) {
    // Render communities.
  }, onError: (error) {
    // Handle error.
  });

  liveCollection.loadNext();
}
```

## Search Communities

Use search for name-based discovery. The parameter name differs by platform: TypeScript uses `displayName`, iOS uses `keyword`, Android passes `keyword` into `searchCommunities(...)`, and Flutter uses `.withKeyword(...)` on the query builder.

```swift iOS
var searchCommunitiesToken: AmityNotificationToken?

func searchCommunitiesExample() {
    let searchOptions = AmityCommunitySearchOptions(
        keyword: "gaming",
        filter: .all,
        sortBy: .displayName,
        categoryId: nil,
        includeDeleted: false,
        includeDiscoverablePrivateCommunity: true
    )
    let liveCollection = communityRepository.searchCommunities(with: searchOptions)
    searchCommunitiesToken = liveCollection.observe { collection, error in
        for community in collection.snapshots {
            // For example, to handle each community in the list.
        }
    }
}
```

```kotlin Android
fun searchCommunities() {
    AmitySocialClient.newCommunityRepository()
        .searchCommunities(
            keyword = "gaming",
            includeDiscoverablePrivateCommunity = true
        )
        .sortBy(sortBy = AmityCommunitySortOption.DISPLAY_NAME)
        .filter(filter = AmityCommunityFilter.ALL)
        .categoryId(categoryId = "categoryId")
        .tags(tags = listOf("gaming"))
        .includeDeleted(includeDeleted = false)
        .build()
        .query()
        .doOnNext { communities: PagingData<AmityCommunity> ->
            // PagingData<AmityCommunity>
        }
        .doOnError {
            // Exception
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscribeSearch = CommunityRepository.searchCommunities(
  {
    displayName: 'gaming',
    membership: 'notMember',
    sortBy: 'displayName',
    categoryId: 'category-id',
    includeDeleted: false,
    includeDiscoverablePrivateCommunity: true,
    tags: ['gaming'],
    limit: 20,
  },
  ({ data: communities, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render search results.
    }
  },
);
```

```dart Flutter
void searchCommunities() {
  final liveCollection = AmitySocialClient.newCommunityRepository()
      .getCommunities()
      .withKeyword('gaming')
      .filter(AmityCommunityFilter.NOT_MEMBER)
      .sortBy(AmityCommunitySortOption.DISPLAY_NAME)
      .tags(['gaming'])
      .includeDeleted(false)
      .getLiveCollection(pageSize: 20);

  liveCollection.getStreamController().stream.listen((communities) {
    // Render search results.
  }, onError: (error) {
    // Handle error.
  });

  liveCollection.loadNext();
}
```


## Related Topics

    Retrieve detailed information about specific communities
    Discover popular and recommended communities
    Learn about organizing communities with categories
    Help users join discovered communities

---

### [Get Community](https://learn.social.plus/social-plus-sdk/social/communities-spaces/discovery/get-community)

> Retrieve a community by ID and observe community updates with the SDK.

Call the get-community API with a `communityId` to retrieve a community's profile fields, counts, membership status, and settings. TypeScript and iOS expose Live Object style APIs, Android exposes an Rx stream, and Flutter exposes both a deprecated one-shot future and a live stream.

    Access name, description, avatar, and basic community information
    View member counts, join status, and community accessibility
    Real-time synchronization of community changes and member activity
    Retrieve community data without joining

Use the live/observable form for detail screens so the UI can react when the community changes.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Get community by ID | `communityId` | Yes | Unique identifier of the community to retrieve. |

## Get Community by ID

The get-community API retrieves a community by ID. Use it for detail screens, join previews, and any workflow that needs the current community record before taking an action.

```swift iOS
var token: AmityNotificationToken?

func observeCommunity(communityId: String) {
    token = communityRepository.getCommunity(withId: communityId).observe { liveObject, error in
        if let error = error {
            print("Error retrieving community: \(error)")
            return
        }

        guard let community = liveObject.snapshot else {
            print("Community not found")
            return
        }

        print("Community ID: \(community.communityId)")
        print("Name: \(community.displayName)")
    }
}
```

```kotlin Android
fun observeCommunity() {
    AmitySocialClient.newCommunityRepository()
        .getCommunity(communityId = "communityId")
        .doOnNext { community: AmityCommunity ->
            println("Community ID: ${community.getCommunityId()}")
            println("Name: ${community.getDisplayName()}")
        }
        .doOnError { error ->
            println("Error retrieving community: ${error.message}")
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getCommunity(
  'communityId',
  ({ data: community, loading, error }) => {
    if (error) {
      // Handle any errors that occur during retrieving data
    }
    if (loading) {
      // Handle the loading state, e.g., show a loading spinner
    }
    if (community) {
      // Process the data
    }
  },
);
```

```dart Flutter
void observeCommunity(String communityId) {
  AmitySocialClient.newCommunityRepository()
      .live
      .getCommunity(communityId)
      .listen((AmityCommunity community) {
        // Render community.
      }, onError: (error) {
        // Handle error.
      });
}
```

## Related Topics

    Discover communities through search and filtering
    Learn how to implement community membership actions
    Understand community organization and categorization
    Implement community recommendation features

---

### [Trending & Recommended Communities](https://learn.social.plus/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities)

> Fetch trending and recommended communities with the SDK discovery APIs.

Use the SDK discovery APIs to fetch trending and recommended community lists. These methods call the social.plus backend discovery endpoints and return community collections or lists, depending on platform.

    Fetch communities from the trending endpoint
    Fetch communities from the recommended endpoint

The ranking logic is owned by the backend service. The client SDK exposes methods to request and render the returned communities.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Trending communities | `includeDiscoverablePrivateCommunity` | No | TypeScript, iOS, Android | Include discoverable private communities where supported. |
| Trending communities | `limit` | No | TypeScript | Limit the returned collection size. |
| Recommended communities | `includeDiscoverablePrivateCommunity` | No | TypeScript, iOS, Android | Include discoverable private communities where supported. |
| Recommended communities | `limit` | No | TypeScript | Limit the returned collection size. |

## Trending Communities

The `getTrendingCommunities()` method fetches communities from the trending endpoint. TypeScript exposes a Live Collection with pagination options, iOS exposes a Live Collection, Android returns a `Flowable<List<AmityCommunity>>`, and Flutter returns a `Future<List<AmityCommunity>>`.

```swift iOS
var token: AmityNotificationToken?

func observeTrendingCommunities() {
    token = communityRepository.getTrendingCommunities(
        includeDiscoverablePrivateCommunity: true
    ).observe { collection, error in
        for community in collection.snapshots {
            // For example, to handle each community in the list.
        }
    }
}
```

```kotlin Android
fun queryTrendingCommunities() {
    AmitySocialClient.newCommunityRepository()
        .getTrendingCommunities(includeDiscoverablePrivateCommunity = true)
        .doOnNext { communities: List<AmityCommunity> ->
            // Render trending communities.
        }
        .doOnError { error ->
            // Handle error.
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getTrendingCommunities(
  { limit: 5, includeDiscoverablePrivateCommunity: true },
  ({ data: communities, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render trending communities.
    }
  },
);
```

```dart Flutter
void getTrendingCommunities() {
  AmitySocialClient.newCommunityRepository()
      .getTrendingCommunities()
      .then((List<AmityCommunity> communities) {
        // Render trending communities.
      })
      .onError((error, stackTrace) {
        // Handle error.
      });
}
```

## Recommended Communities

The `getRecommendedCommunities()` method fetches communities from the recommended endpoint. Use it when your discovery UI needs a backend-curated list instead of a filter-based query.

```swift iOS
var token: AmityNotificationToken?

func observeRecommendedCommunities() {
    token = communityRepository.getRecommendedCommunities(
        includeDiscoverablePrivateCommunity: true
    ).observe { collection, error in
        for community in collection.snapshots {
            // For example, to handle each community in the list.
        }
    }
}
```

```kotlin Android
fun queryRecommendedCommunities() {
    AmitySocialClient.newCommunityRepository()
        .getRecommendedCommunities(includeDiscoverablePrivateCommunity = true)
        .doOnNext { communities: List<AmityCommunity> ->
            // Render recommended communities.
        }
        .doOnError { error ->
            // Handle error.
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getRecommendedCommunities(
  { limit: 5, includeDiscoverablePrivateCommunity: true },
  ({ data: communities, loading, error }) => {
    if (error) {
      // Handle error.
    }
    if (loading) {
      // Show loading state.
    }
    if (communities) {
      // Render recommended communities.
    }
  },
);
```

```dart Flutter
void getRecommendedCommunities() {
  AmitySocialClient.newCommunityRepository()
      .getRecommendedCommunities()
      .then((List<AmityCommunity> communities) {
        // Render recommended communities.
      })
      .onError((error, stackTrace) {
        // Handle error.
      });
}
```

## Best Practices

**Recommendation Refresh**: Refresh trending and recommended communities intentionally, such as when the user opens the discovery surface or pulls to refresh.

### User Experience Guidelines

1. **Loading States**: Show skeleton screens during discovery data fetching
2. **Empty States**: Provide fallback content when no recommendations are available
3. **Action Feedback**: Give immediate feedback when users join discovered communities

### Performance Optimization

1. **Pagination**: Use TypeScript pagination options when building longer discovery feeds
2. **Image Optimization**: Preload community avatars for smooth scrolling
3. **Background Updates**: Refresh discovery data in the background

## Related Topics

    Advanced community search and filtering capabilities
    Implement community membership actions from discovery
    Learn about community organization for better recommendations
    Display detailed community information before joining

---

### [Community Categories](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/community-categories)

> Query community categories and use them to filter community discovery

Community categories are read through the SDK and managed in the social.plus Console. Client apps can query category lists, include or exclude deleted categories, and use category IDs when querying communities.

Categories can only be created and updated from the social.plus Console. SDK access is limited to reading existing categories.

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `sortBy` | No | Sort order for categories. |
| `includeDeleted` | No | Include deleted categories in the result. |
| `limit` / pagination token | No | Page-size and pagination controls where supported by the platform. |

## Sort Options

| Platform | Sort values |
|----------|-------------|
| TypeScript | `"name"`, `"firstCreated"`, `"lastCreated"` |
| iOS | `.displayName`, `.firstCreated`, `.lastCreated` |
| Android | `AmityCommunityCategorySortOption.NAME`, `FIRST_CREATED`, `LAST_CREATED` |
| Flutter | `AmityCommunityCategorySortOption.NAME`, `FIRST_CREATED`, `LAST_CREATED` |

## Query Categories

Use `getCategories()` to retrieve community categories. The SDK returns paginated/live collection results depending on the platform.

```swift iOS
let liveCollection = communityRepository.getCategories(
    sortBy: .displayName,
    includeDeleted: false
)

token = liveCollection.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let categories = collection.snapshots
    // Render categories
}
```

```kotlin Android
fun queryCategories(communityRepository: AmityCommunityRepository) {
    communityRepository
        .getCategories()
        .sortBy(sortOption = AmityCommunityCategorySortOption.NAME)
        .includeDeleted(includeDeleted = false)
        .build()
        .query()
        .doOnNext { categories: PagingData<AmityCommunityCategory> ->
            // Render categories
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { CategoryRepository } from '@amityco/ts-sdk';

let nextPageFn: (() => void) | undefined;
let hasMore = false;

const unsubscriber = CategoryRepository.getCategories(
  {
    sortBy: 'name',
    includeDeleted: false,
    limit: 20,
  },
  ({ data: categories, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      // Handle error
      return;
    }

    if (!loading && categories) {
      // Render categories
    }

    hasMore = hasNextPage;
    nextPageFn = onNextPage;
  },
);

function loadMoreCategories() {
  if (hasMore) nextPageFn?.();
}
```

```dart Flutter
final categories = <AmityCommunityCategory>[];
late PagingController<AmityCommunityCategory> categoryController;

void queryCommunityCategories() {
  categoryController = PagingController(
    pageFuture: (token) => AmitySocialClient.newCommunityRepository()
        .getCategories()
        .sortBy(AmityCommunityCategorySortOption.NAME)
        .includeDeleted(false)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(() {
      if (categoryController.error == null) {
        categories
          ..clear()
          ..addAll(categoryController.loadedItems);
      } else {
        // Handle pagination error
      }
    });

  categoryController.fetchNextPage();
}
```

## Using Categories with Community Queries

After retrieving categories, pass a category ID into community query APIs to filter community discovery.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getCommunities(
  {
    categoryId: 'category-id',
    sortBy: 'lastCreated',
  },
  ({ data: communities }) => {
    // Render communities in this category
  },
);
```

```kotlin Android
fun queryCommunitiesByCategory(categoryId: String) {
    AmitySocialClient.newCommunityRepository()
        .getCommunities()
        .categoryId(categoryId = categoryId)
        .build()
        .query()
        .subscribe { communities: PagingData<AmityCommunity> ->
            // Render communities in this category
        }
}
```

```dart Flutter
void queryCommunitiesByCategory(String categoryId) {
  AmitySocialClient.newCommunityRepository()
      .getCommunities()
      .categoryId(categoryId)
      .getLiveCollection(pageSize: 20)
      .getStreamController()
      .stream
      .listen((communities) {
        // Render communities in this category
      });
}
```

## Related Topics

    Filter communities by category, membership, keyword, and sort order
    Assign categories when creating a community

---

### [Community Invitation Management](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/community-invitation)

> Read, send, accept, and reject community invitations

Community invitations let moderators invite users to join a community. Depending on network settings, invited users may become members automatically or may need to accept the invitation.

## Parameters

| Operation | Platforms | Parameter | Required | Description |
| --- | --- | --- | --- | --- |
| Get membership acceptance setting | iOS, Android, TypeScript | None | No | Reads social settings to determine whether invited users join automatically or must accept. |
| Get my community invitations | iOS, Android, TypeScript | `limit` / page size | No | Page size for the signed-in user's invitation list where the platform exposes pagination. |
| Check a community invitation | iOS, Android, TypeScript | Community object | Yes | Fetched community object used to read the current user's invitation state. |
| Accept or reject an invitation | iOS, Android, TypeScript | Invitation object | Yes | Invitation object returned from a community or invitation query. |
| Create invitations | iOS, Android, TypeScript | Community object | Yes | Fetched community object used to create invitations. |
| Create invitations | iOS, Android, TypeScript | `userIds` | Yes | User IDs to invite to the community. |
| Get member invitations | iOS, Android, TypeScript | Community object | Yes | Fetched community object used to query invitations sent for that community. |
| Get member invitations | iOS, Android, TypeScript | `statuses` / `limit` | No | Optional invitation status filters and page size where exposed. |

## Membership Acceptance Setting

Use social settings to check whether the network uses automatic membership or invitation acceptance.

```swift iOS
let socialSettings = client.getSocialSettings()

switch socialSettings?.membershipAcceptance {
case .automatic:
    // Invitations add users automatically
    break
case .invitation:
    // Invited users must accept
    break
case .none:
    // Settings are not available locally yet
    break
@unknown default:
    break
}
```

```kotlin Android
fun observeMembershipAcceptance() {
    AmitySocialClient.getSettings()
        .doOnNext { socialSettings ->
            when (socialSettings.getMembershipAcceptanceType()) {
                AmityMembershipAcceptanceType.AUTOMATIC -> {
                    // Invitations add users automatically
                }
                AmityMembershipAcceptanceType.INVITATION -> {
                    // Invited users must accept
                }
                AmityMembershipAcceptanceType.UNKNOWN -> {
                    // Setting is unknown
                }
            }
        }
        .subscribe()
}
```

```typescript TypeScript
import { MembershipAcceptanceTypeEnum } from '@amityco/ts-sdk';

async function getMembershipAcceptance() {
  const settings = await client.getSocialSettings();

  if (settings.membershipAcceptance === MembershipAcceptanceTypeEnum.Invitation) {
    // Invited users must accept
  }

  return settings.membershipAcceptance;
}
```

## Get My Community Invitations

Use this flow for the current user to list pending community invitations.

```swift iOS
let invitationRepository = AmityInvitationRepository()
let liveCollection = invitationRepository.getMyCommunityInvitations()

token = liveCollection.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let invitations = collection.snapshots
    // Render pending invitations
}
```

```kotlin Android
fun getMyCommunityInvitations() {
    AmityCoreClient.newInvitationRepository()
        .getMyCommunityInvitations()
        .doOnNext { invitations: PagingData<AmityInvitation> ->
            // Render pending invitations
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { InvitationRepository } from '@amityco/ts-sdk';

function getMyCommunityInvitations() {
  return InvitationRepository.getMyCommunityInvitations(
    { limit: 20 },
    ({ data: invitations, loading, error }) => {
      if (error) {
        // Handle error
        return;
      }

      if (!loading && invitations) {
        // Render pending invitations
      }
    },
  );
}
```

## Check a Community Invitation

Use `community.getInvitation()` when the user needs to know whether they have a pending invitation for a specific community.

```swift iOS
var community: AmityCommunity! // Fetched community

if let invitation = await community.getInvitation() {
    switch invitation.status {
    case .pending:
        // Can accept or reject
        break
    case .approved, .rejected, .canceled:
        // Invitation already resolved
        break
    @unknown default:
        break
    }
}
```

```kotlin Android
fun getInvitation(community: AmityCommunity) {
    community.getInvitation()
        .doOnSuccess { invitations: List<AmityInvitation> ->
            invitations.forEach { invitation ->
                val status = invitation.getStatus()
                // Render status
            }
        }
        .subscribe()
}
```

```typescript TypeScript
import { InvitationStatusEnum } from '@amityco/ts-sdk';

async function getInvitation(community: Amity.Community) {
  const invitation = await community.getInvitation();

  if (invitation?.status === InvitationStatusEnum.Pending) {
    // Can accept or reject
  }

  return invitation;
}
```

## Accept or Reject an Invitation

Invitation linked objects expose `accept()` and `reject()` across TypeScript, iOS, and Android.

```swift iOS
var community: AmityCommunity! // Fetched community

if let invitation = await community.getInvitation() {
    do {
        try await invitation.accept()
    } catch let error {
        handleError(error)
    }
}
```

```kotlin Android
fun acceptInvitation(invitation: AmityInvitation) {
    invitation.accept()
        .doOnComplete {
            // Invitation accepted
        }
        .subscribe()
}
```

```typescript TypeScript
async function acceptInvitation(invitation: Amity.Invitation) {
  await invitation.accept();
}
```

```swift iOS
var community: AmityCommunity! // Fetched community

if let invitation = await community.getInvitation() {
    do {
        try await invitation.reject()
    } catch let error {
        handleError(error)
    }
}
```

```kotlin Android
fun rejectInvitation(invitation: AmityInvitation) {
    invitation.reject()
        .doOnComplete {
            // Invitation rejected
        }
        .subscribe()
}
```

```typescript TypeScript
async function rejectInvitation(invitation: Amity.Invitation) {
  await invitation.reject();
}
```

## Create Invitations

Use `createInvitations()` on a fetched community object to invite users.

```swift iOS
var community: AmityCommunity! // Fetched community

do {
    try await community.createInvitations(["user1", "user2"])
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun createInvitations(community: AmityCommunity) {
    community.createInvitations(userIds = listOf("user1", "user2"))
        .doOnComplete {
            // Invitations created
        }
        .subscribe()
}
```

```typescript TypeScript
async function createInvitations(
  community: Amity.Community,
  userIds: Amity.User['userId'][],
) {
  await community.createInvitations(userIds);
}
```

## Get Member Invitations

Moderators can observe invitations sent for a community.

```swift iOS
var community: AmityCommunity! // Fetched community

let liveCollection = community.getMemberInvitations()

token = liveCollection.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let invitations = collection.snapshots
    // Render community invitations
}
```

```kotlin Android
fun getMemberInvitations(community: AmityCommunity) {
    community.getMemberInvitations()
        .doOnNext { invitations: PagingData<AmityInvitation> ->
            // Render community invitations
        }
        .subscribe()
}
```

```typescript TypeScript
import { InvitationStatusEnum } from '@amityco/ts-sdk';

function getMemberInvitations(community: Amity.Community) {
  return community.getMemberInvitations(
    {
      statuses: [InvitationStatusEnum.Pending],
      limit: 20,
    },
    ({ data: invitations, loading, error }) => {
      if (error) {
        // Handle error
        return;
      }

      if (!loading && invitations) {
        // Render community invitations
      }
    },
  );
}
```

## Related Topics

    Manage user-initiated joining and leaving
    Query and search community members
    Add and remove community members directly
    Discover and filter communities

---

### [Community Moderation](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/community-moderation)

> Assign roles, ban or unban members, and check community permissions

Use community moderation APIs for role assignment, ban management, and permission checks. Role IDs must already exist in your network; these APIs assign or remove roles from users, but they do not create roles.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Add roles | `communityId` | Yes | Community ID where roles should be assigned. |
| Add roles | `roleIds` / `roles` | Yes | Existing role IDs to assign. Flutter accepts one role ID per call. |
| Add roles | `userIds` | Yes | User IDs that should receive the roles. |
| Remove roles | `communityId` | Yes | Community ID where roles should be removed. |
| Remove roles | `roleIds` / `roles` | Yes | Existing role IDs to remove. Flutter accepts one role ID per call. |
| Remove roles | `userIds` | Yes | User IDs whose roles should be updated. |
| Ban or unban members | `communityId` | Yes | Community ID whose ban list should change. |
| Ban or unban members | `userIds` | Yes | User IDs to ban or unban. |
| Check permissions | `permission` | Yes | Permission value to check, such as ban-community-user. |
| Check permissions | `communityId` | Yes | Community where the permission should be evaluated. |

## Role Management

TypeScript, iOS, and Android accept a list of role IDs. Flutter exposes `addRole()` and `removeRole()` for one role ID per call.

### Add Roles

Add role IDs to one or more users after the roles already exist in your network.


```swift iOS
let communityModeration = AmityCommunityModeration(communityId: communityId)

do {
    try await communityModeration.addRoles(
        ["community-moderator"],
        userIds: ["user1", "user2"]
    )
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun addRoles(communityRepository: AmityCommunityRepository) {
    communityRepository
        .moderation(communityId = "communityId")
        .addRoles(
            roles = listOf("community-moderator"),
            userIds = listOf("user1", "user2")
        )
        .doOnComplete {
            // Roles added
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function addRoles(
  communityId: Amity.Community['communityId'],
  roleIds: Amity.Role['roleId'][],
  userIds: Amity.User['userId'][],
): Promise<boolean> {
  return CommunityRepository.Moderation.addRoles(communityId, roleIds, userIds);
}
```

```dart Flutter
Future<void> addRole(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .moderation(communityId)
      .addRole('community-moderator', userIds);
}
```


### Remove Roles

Remove role IDs from one or more users when they should no longer have that community role.


```swift iOS
let communityModeration = AmityCommunityModeration(communityId: communityId)

do {
    try await communityModeration.removeRoles(
        ["community-moderator"],
        userIds: ["user1", "user2"]
    )
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun removeRoles(communityRepository: AmityCommunityRepository) {
    communityRepository
        .moderation(communityId = "communityId")
        .removeRoles(
            roles = listOf("community-moderator"),
            userIds = listOf("user1", "user2")
        )
        .doOnComplete {
            // Roles removed
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function removeRoles(
  communityId: Amity.Community['communityId'],
  roleIds: Amity.Role['roleId'][],
  userIds: Amity.User['userId'][],
): Promise<boolean> {
  return CommunityRepository.Moderation.removeRoles(communityId, roleIds, userIds);
}
```

```dart Flutter
Future<void> removeRole(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .moderation(communityId)
      .removeRole('community-moderator', userIds);
}
```


## Ban Members

Use `banMembers()` / `banMember()` to ban users from a community.


```swift iOS
let communityModeration = AmityCommunityModeration(communityId: communityId)

do {
    try await communityModeration.banMembers(["user1", "user2"])
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun banMembers(communityRepository: AmityCommunityRepository) {
    communityRepository
        .moderation(communityId = "communityId")
        .banMembers(userIds = listOf("user1", "user2"))
        .doOnComplete {
            // Members banned
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function banMembers(
  communityId: Amity.Community['communityId'],
  userIds: Amity.User['userId'][],
) {
  const { data: bannedMembers } =
    await CommunityRepository.Moderation.banMembers(communityId, userIds);

  return bannedMembers;
}
```

```dart Flutter
Future<void> banMembers(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .moderation(communityId)
      .banMember(userIds);
}
```


## Unban Members

Use `unbanMembers()` / `unbanMember()` to remove community bans.


```swift iOS
let communityModeration = AmityCommunityModeration(communityId: communityId)

do {
    try await communityModeration.unbanMembers(["user1", "user2"])
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun unbanMembers(communityRepository: AmityCommunityRepository) {
    communityRepository
        .moderation(communityId = "communityId")
        .unbanMembers(userIds = listOf("user1", "user2"))
        .doOnComplete {
            // Members unbanned
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function unbanMembers(
  communityId: Amity.Community['communityId'],
  userIds: Amity.User['userId'][],
) {
  const { data: unbannedMembers } =
    await CommunityRepository.Moderation.unbanMembers(communityId, userIds);

  return unbannedMembers;
}
```

```dart Flutter
Future<void> unbanMembers(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .moderation(communityId)
      .unbanMember(userIds);
}
```


## Check Permissions

Permission checks use the current user's cached permission state. Query the relevant community/member state before relying on the result for UI decisions.


```swift iOS
let canBan = await client.hasPermission(
    .banCommunityUser,
    forCommunity: communityId
)
```

```kotlin Android
fun checkCommunityPermission() {
    AmityCoreClient
        .hasPermission(permission = AmityPermission.BAN_COMMUNITY_USER)
        .atCommunity(communityId = "communityId")
        .check()
        .doOnNext { hasPermission: Boolean ->
            // Render permission-aware UI
        }
        .subscribe()
}
```

```typescript TypeScript
function checkCommunityPermission(communityId: Amity.Community['communityId']) {
  return client
    .hasPermission(Amity.Permission.BanChannelCommunityPermission)
    .community(communityId);
}
```

```dart Flutter
void checkCommunityPermission(String communityId) {
  final hasPermission = AmityCoreClient
      .hasPermission(AmityPermission.BAN_COMMUNITY_USER)
      .atCommunity(communityId)
      .check();
}
```


## Related Topics

    Add and remove community members
    User-initiated joining, leaving, and approval workflows
    Search and filter community member lists
    Invitation-based member onboarding workflows

---

### [Join/Leave Community](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/join-leave-community)

> Join or leave communities, handle join requests, and manage approval flows

Use community membership APIs to let the active user join or leave a community. Communities that require approval return a pending join request instead of immediate membership.

iOS, Android, and TypeScript support object-based `community.join()` flows that return a success or pending result. Flutter currently exposes repository-level `joinCommunity()` and `leaveCommunity()` methods.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Join community | Community object | Platform-dependent | iOS, Android, and TypeScript call `join()` on a fetched community object. |
| Join community | `communityId` | Platform-dependent | Flutter joins by community ID. |
| Check my join request | Community object | Yes | Fetched community object used to read the active user's pending request. |
| Observe pending join requests | Community object | Yes | Fetched community object used by moderators to list join requests. |
| Observe pending join requests | `status` / `limit` | No | Optional request status and page-size controls where exposed. |
| Cancel, approve, or reject | Join request object | Yes | Join request object returned from a join-request query. |
| Leave community | `communityId` | Yes | Community ID the active user should leave. |

## Join Community

For approval-aware flows, fetch a community object first and call `join()` where the platform supports it. The result tells you whether membership was granted immediately or a join request is pending.


```swift iOS
var community: AmityCommunity! // Fetched community

Task { @MainActor in
    do {
        let result = try await community.join()

        switch result {
        case .success:
            // Joined immediately
            break
        case .pending(let joinRequest):
            let status = joinRequest.status
            // Show pending state
        }
    } catch let error {
        handleError(error)
    }
}
```

```kotlin Android
fun joinCommunity(community: AmityCommunity) {
    community.join()
        .doOnSuccess { result ->
            when (result) {
                is AmityJoinResult.Success -> {
                    // Joined immediately
                }
                is AmityJoinResult.Pending -> {
                    val joinRequest = result.request
                    // Show pending state
                }
            }
        }
        .doOnError { throwable ->
            when (AmityError.from(throwable)) {
                AmityError.ITEM_NOT_FOUND -> {
                    // Community does not exist
                }
                AmityError.USER_IS_BANNED -> {
                    // Current user is banned
                }
                else -> {
                    // Handle other errors
                }
            }
        }
        .subscribe()
}
```

```typescript TypeScript
async function joinCommunity(community: Amity.Community): Promise<Amity.JoinResult> {
  const result = await community.join();

  if (result.status === 'pending') {
    const joinRequest = result.request;
    // Show pending state
  }

  return result;
}
```

```dart Flutter
Future<void> joinCommunity(String communityId) async {
  await AmitySocialClient.newCommunityRepository()
      .joinCommunity(communityId);
}
```


## Join Requests

When a community requires approval, the SDK exposes the active user's request and moderator review flows.

### Check My Join Request

Fetch the active user's join request when an approval-required community returns a pending state.


```swift iOS
var community: AmityCommunity! // Fetched community

Task { @MainActor in
    do {
        let joinRequest = try await community.getMyJoinRequest()
        let status = joinRequest.status
        // Render status
    } catch let error {
        handleError(error)
    }
}
```

```kotlin Android
fun getMyJoinRequest(community: AmityCommunity) {
    community.getMyJoinRequest()
        .doOnSuccess { joinRequest ->
            val status = joinRequest.getStatus()
            // Render status
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
async function getMyJoinRequest(community: Amity.Community) {
  const joinRequest = await community.getMyJoinRequest();

  if (joinRequest?.status === 'pending') {
    // Render pending state
  }

  return joinRequest;
}
```


### Observe Pending Join Requests

Moderators can observe join requests for a community and approve or reject individual requests.


```swift iOS
var community: AmityCommunity! // Fetched community

token = community.getJoinRequests(status: .pending).observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let joinRequests = collection.snapshots
    // Render pending requests
}
```

```kotlin Android
fun observePendingJoinRequests(community: AmityCommunity) {
    community.getJoinRequests(status = AmityJoinRequestStatus.PENDING)
        .doOnNext { joinRequests: PagingData<AmityJoinRequest> ->
            // Render pending requests
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { JoinRequestStatusEnum } from '@amityco/ts-sdk';

function observePendingJoinRequests(community: Amity.Community) {
  return community.getJoinRequests(
    {
      communityId: community.communityId,
      type: 'communityJoinRequest',
      targetType: 'community',
      status: JoinRequestStatusEnum.Pending,
      options: { limit: 20 },
    },
    ({ data: joinRequests, loading, error }) => {
      if (error) {
        // Handle error
        return;
      }

      if (!loading && joinRequests) {
        // Render pending requests
      }
    },
  );
}
```


### Cancel, Approve, or Reject

Cancel your own request or approve and reject pending requests from a moderator flow.


```swift iOS
func cancelJoinRequest(_ joinRequest: AmityJoinRequest) {
    Task { @MainActor in
        do {
            try await joinRequest.cancel()
        } catch let error {
            handleError(error)
        }
    }
}

func approveJoinRequest(_ joinRequest: AmityJoinRequest) {
    Task { @MainActor in
        do {
            try await joinRequest.approve()
        } catch let error {
            handleError(error)
        }
    }
}

func rejectJoinRequest(_ joinRequest: AmityJoinRequest) {
    Task { @MainActor in
        do {
            try await joinRequest.reject()
        } catch let error {
            handleError(error)
        }
    }
}
```

```kotlin Android
fun cancelJoinRequest(joinRequest: AmityJoinRequest) {
    joinRequest.cancel()
        .doOnComplete {
            // Cancelled
        }
        .subscribe()
}

fun approveJoinRequest(joinRequest: AmityJoinRequest) {
    joinRequest.approve()
        .doOnComplete {
            // Approved
        }
        .subscribe()
}

fun rejectJoinRequest(joinRequest: AmityJoinRequest) {
    joinRequest.reject()
        .doOnComplete {
            // Rejected
        }
        .subscribe()
}
```

```typescript TypeScript
async function cancelJoinRequest(joinRequest: Amity.JoinRequest) {
  await joinRequest.cancel();
}

async function approveJoinRequest(joinRequest: Amity.JoinRequest) {
  await joinRequest.approve();
}

async function rejectJoinRequest(joinRequest: Amity.JoinRequest) {
  await joinRequest.reject();
}
```


## Leave Community

Use `leaveCommunity()` to remove the active user from a community.

Leaving removes the current user's community membership. If the community requires approval, the user may need to request access again before rejoining.


```swift iOS
do {
    try await communityRepository.leaveCommunity(withId: communityId)
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun leaveCommunity(communityRepository: AmityCommunityRepository, communityId: String) {
    communityRepository
        .leaveCommunity(communityId = communityId)
        .doOnComplete {
            // Left community
        }
        .doOnError { throwable ->
            when (AmityError.from(throwable)) {
                AmityError.ITEM_NOT_FOUND -> {
                    // Community does not exist
                }
                AmityError.PERMISSION_DENIED -> {
                    // Permission denied
                }
                else -> {
                    // Handle other errors
                }
            }
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function leaveCommunity(communityId: Amity.Community['communityId']) {
  const hasLeft = await CommunityRepository.leaveCommunity(communityId);
  return hasLeft;
}
```

```dart Flutter
Future<void> leaveCommunity(String communityId) async {
  await AmitySocialClient.newCommunityRepository()
      .leaveCommunity(communityId);
}
```


## Related Topics

    View and search community member lists.
    Add and remove community members.
    Manage roles, bans, and permissions.
    Invitation-based member onboarding workflows.

---

### [Member Management](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/member-management)

> Add and remove community members with the community membership APIs

Use member management APIs when a moderator or admin needs to add users to a community or remove existing members. These APIs are separate from user-initiated join and leave flows.

Member management APIs require the current user to have the relevant community permissions. The SDK methods perform the operation; your app should query member lists afterward if the UI needs an updated collection.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Add members | `communityId` | Yes | Community ID whose membership should change. |
| Add members | `userIds` | Yes | User IDs to add to the community. |
| Remove members | `communityId` | Yes | Community ID whose membership should change. |
| Remove members | `userIds` | Yes | User IDs to remove from the community. |

## Add Members

Use `addMembers()` to add one or more users to a community.

```swift iOS
let communityMembership = AmityCommunityMembership(communityId: communityId)

do {
    try await communityMembership.addMembers(["user1", "user2"])
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun addMembers(communityRepository: AmityCommunityRepository) {
    communityRepository
        .membership(communityId = "communityId")
        .addMembers(userIds = listOf("user1", "user2"))
        .doOnComplete {
            // Members added
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function addMembers(
  communityId: Amity.Community['communityId'],
  userIds: Amity.User['userId'][],
): Promise<boolean> {
  return CommunityRepository.Membership.addMembers(communityId, userIds);
}
```

```dart Flutter
Future<void> addMembers(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .membership(communityId)
      .addMembers(userIds);
}
```

## Remove Members

Use `removeMembers()` to remove one or more users from a community.

Removing members changes their community membership immediately. If the community requires approval, removed users may need to request access again before rejoining.

```swift iOS
let communityMembership = AmityCommunityMembership(communityId: communityId)

do {
    try await communityMembership.removeMembers(["user1", "user2"])
} catch let error {
    handleError(error)
}
```

```kotlin Android
fun removeMembers(communityRepository: AmityCommunityRepository) {
    communityRepository
        .membership(communityId = "communityId")
        .removeMembers(userIds = listOf("user1", "user2"))
        .doOnComplete {
            // Members removed
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

async function removeMembers(
  communityId: Amity.Community['communityId'],
  userIds: Amity.User['userId'][],
): Promise<boolean> {
  return CommunityRepository.Membership.removeMembers(communityId, userIds);
}
```

```dart Flutter
Future<void> removeMembers(String communityId, List<String> userIds) async {
  await AmitySocialClient.newCommunityRepository()
      .membership(communityId)
      .removeMembers(userIds);
}
```

## Related Topics

    Assign roles and ban or unban community members
    User-initiated membership workflows and approval requests
    Search and filter community member lists
    Invitation-based member onboarding workflows

---

### [Query Community Members](https://learn.social.plus/social-plus-sdk/social/communities-spaces/organization/query-community-members)

> Query and search community members by membership status, roles, keyword, and sort order

Use member query APIs to list community members and member search APIs to find members by keyword. The available filters and sort values differ by SDK, so use the platform-specific values below.

Member query APIs return paginated or live collection results depending on the platform. Use pagination controls for large communities.

## Parameters

### Common Parameters

| Parameter | Platforms | Description |
|-----------|-----------|-------------|
| `communityId` | All | Community to query. |
| `roles` | All | Optional role IDs to include, such as `community-moderator`. |
| `includeDeleted` | All | Include deleted users. |
| `excludingRoles` | TypeScript, iOS, Android | Exclude members holding any role in the list. Applies to both query and search. |
| `limit` / pagination token | TypeScript, Flutter | Explicit page size. iOS and Android paginate through the live collection and `PagingData` instead. |

### Query Filters

| Platform | Values |
|----------|--------|
| TypeScript | `memberships: ["member"]`, `["banned"]`, or omit `memberships` for all results |
| iOS | `AmityCommunityMembership.QueryFilter.member`, `.banned`, `.all` |
| Android | `AmityCommunityMembershipFilter.MEMBER`, `BANNED`, `ALL` |
| Flutter | `AmityCommunityMembershipFilter.MEMBER`, `BANNED`, `ALL` |

### Query Sort Options

| Platform | Values |
|----------|--------|
| TypeScript | `"firstCreated"`, `"lastCreated"` |
| iOS | `.displayName`, `.firstCreated`, `.lastCreated`, `.lastJoin` |
| Android | `DISPLAY_NAME`, `FIRST_CREATED`, `LAST_CREATED`, `LAST_JOIN` |
| Flutter | `FIRST_CREATED`, `LAST_CREATED` |

Query members when you need a paginated member list with membership, role, deletion, and sort filters.


```swift iOS
let communityMembership = AmityCommunityMembership(communityId: communityId)

let liveCollection = communityMembership.getMembers(
    filter: .member,
    roles: ["community-moderator"],
    sortBy: .firstCreated,
    includeDeleted: false,
    excludingRoles: ["channel-moderator"]
)

token = liveCollection.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let members = collection.snapshots
    // Render members
}
```

```kotlin Android
fun queryCommunityMembers(communityRepository: AmityCommunityRepository) {
    communityRepository
        .membership(communityId = "communityId")
        .getMembers()
        .filter(filter = AmityCommunityMembershipFilter.MEMBER)
        .roles(roles = listOf("community-moderator"))
        .excludingRoles(excludingRoles = listOf("channel-moderator"))
        .includeDeleted(includeDeleted = false)
        .sortBy(sortBy = AmityCommunityMembershipSortOption.FIRST_CREATED)
        .build()
        .query()
        .doOnNext { members: PagingData<AmityCommunityMember> ->
            // Render members
        }
        .doOnError { throwable ->
            // Handle error
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

let nextPageFn: (() => void) | undefined;
let hasMore = false;

const unsubscriber = CommunityRepository.Membership.getMembers(
  {
    communityId,
    memberships: ['member'],
    roles: ['community-moderator'],
    excludingRoles: ['channel-moderator'],
    sortBy: 'firstCreated',
    includeDeleted: false,
    limit: 20,
  },
  ({ data: members, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      // Handle error
      return;
    }

    if (!loading && members) {
      // Render members
    }

    hasMore = hasNextPage;
    nextPageFn = onNextPage;
  },
);

function loadMoreMembers() {
  if (hasMore) nextPageFn?.();
}
```

```dart Flutter
final members = <AmityCommunityMember>[];
late PagingController<AmityCommunityMember> membersController;

void queryCommunityMembers(String communityId) {
  membersController = PagingController(
    pageFuture: (token) => AmitySocialClient.newCommunityRepository()
        .membership(communityId)
        .getMembers()
        .filter(AmityCommunityMembershipFilter.MEMBER)
        .roles(['community-moderator'])
        .includeDeleted(false)
        .sortBy(AmityCommunityMembershipSortOption.FIRST_CREATED)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(() {
      if (membersController.error == null) {
        members
          ..clear()
          ..addAll(membersController.loadedItems);
      } else {
        // Handle pagination error
      }
    });
}
```


## Search Community Members

Search APIs use the same community and role controls, plus a keyword/display-name search input.

### Search Filters

| Platform | Values |
|----------|--------|
| TypeScript | `memberships: ["member"]`, `["banned"]`, or omit `memberships` |
| iOS | `AmityCommunityMembership.SearchFilter.member`, `.banned` |
| Android | `AmityCommunityMembership.MEMBER`, `BANNED` |
| Flutter | `AmityCommunityMembershipFilter.MEMBER`, `BANNED`, `ALL` |

### Search Sort Options

| Platform | Values |
|----------|--------|
| TypeScript | `"displayName"`, `"firstCreated"`, `"lastCreated"` |
| iOS | `.displayName`, `.firstCreated`, `.lastCreated`, `.lastJoin` |
| Android | `DISPLAY_NAME`, `FIRST_CREATED`, `LAST_CREATED`, `LAST_JOIN` |
| Flutter | `FIRST_CREATED`, `LAST_CREATED` |


```swift iOS
let communityMembership = AmityCommunityMembership(communityId: communityId)

let liveCollection = communityMembership.searchMembers(
    keyword: "alex",
    filter: [.member],
    roles: ["community-moderator"],
    sortBy: .displayName,
    includeDeleted: false,
    excludingRoles: ["channel-moderator"]
)

token = liveCollection.observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    let members = collection.snapshots
    // Render matching members
}
```

```kotlin Android
fun searchCommunityMembers(
    communityRepository: AmityCommunityRepository,
    keyword: String
) {
    communityRepository
        .membership(communityId = "communityId")
        .searchMembers(keyword = keyword)
        .roles(roles = listOf("community-moderator"))
        .membershipFilter(
            communityMembership = listOf(AmityCommunityMembership.MEMBER)
        )
        .excludingRoles(excludingRoles = listOf("channel-moderator"))
        .includeDeleted(includeDeleted = false)
        .sortBy(AmityCommunityMembershipSortOption.DISPLAY_NAME)
        .build()
        .query()
        .doOnNext { members: PagingData<AmityCommunityMember> ->
            // Render matching members
        }
        .subscribe()
}
```

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

function searchCommunityMembers(keyword: string) {
  return CommunityRepository.Membership.searchMembers(
    {
      communityId,
      search: keyword,
      memberships: ['member'],
      roles: ['community-moderator'],
      excludingRoles: ['channel-moderator'],
      sortBy: 'displayName',
      includeDeleted: false,
      limit: 20,
    },
    ({ data: members, loading, error }) => {
      if (error) {
        // Handle error
        return;
      }

      if (!loading && members) {
        // Render matching members
      }
    },
  );
}
```

```dart Flutter
final searchResults = <AmityCommunityMember>[];
late PagingController<AmityCommunityMember> searchController;

void searchCommunityMembers(String communityId, String keyword) {
  searchController = PagingController(
    pageFuture: (token) => AmitySocialClient.newCommunityRepository()
        .membership(communityId)
        .searchMembers(keyword)
        .filter(AmityCommunityMembershipFilter.MEMBER)
        .roles(['community-moderator'])
        .includeDeleted(false)
        .sortBy(AmityCommunityMembershipSortOption.FIRST_CREATED)
        .getPagingData(token: token, limit: 20),
    pageSize: 20,
  )..addListener(() {
      if (searchController.error == null) {
        searchResults
          ..clear()
          ..addAll(searchController.loadedItems);
      } else {
        // Handle pagination error
      }
    });
}
```


## Excluding Roles

Use `excludingRoles` when you need a member list that removes users with any role in the exclusion list. It is available in TypeScript, iOS, and Android, on both the member query and the member search APIs. Flutter exposes `excludingRoles` on neither builder.

How it resolves:

- A member is removed if they hold **any** role in the list — not only if they hold all of them.
- An **empty list applies no exclusion**, so you can pass one unconditionally and let the caller decide. iOS and Android default the parameter to an empty list; in TypeScript it is optional.
- `roles` and `excludingRoles` combine as an intersection: a member is returned only if they match `roles` and hold none of the roles in `excludingRoles`. Listing the same role in both therefore yields no members.


```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.Membership.getMembers(
  {
    communityId,
    excludingRoles: ['community-moderator', 'channel-moderator'],
    limit: 20,
  },
  ({ data: members }) => {
    // Members do not include users with excluded roles
  },
);
```

```swift iOS
let communityMembership = AmityCommunityMembership(communityId: communityId)

let liveCollection = communityMembership.getMembers(
    filter: .member,
    roles: [],
    sortBy: .firstCreated,
    includeDeleted: false,
    excludingRoles: ["community-moderator", "channel-moderator"]
)

token = liveCollection.observe { collection, error in
    let members = collection.snapshots
    // Members do not include users with excluded roles
}
```

```kotlin Android
fun queryMembersExcludingRoles(communityRepository: AmityCommunityRepository) {
    communityRepository
        .membership(communityId = "communityId")
        .getMembers()
        .filter(filter = AmityCommunityMembershipFilter.MEMBER)
        .excludingRoles(
            excludingRoles = listOf("community-moderator", "channel-moderator")
        )
        .build()
        .query()
        .doOnNext { members: PagingData<AmityCommunityMember> ->
            // Members do not include users with excluded roles
        }
        .subscribe()
}
```


## Related Topics

    Manage joining and leaving communities.
    Add and remove community members.
    Manage roles, bans, and permissions.
    Understand role-based access control.

---

### [User Relationship](https://learn.social.plus/social-plus-sdk/social/user-relationship/overview)

> SDK overview for follow, unfollow, follow requests, follower lists, and blocking.

User relationship APIs let a signed-in user build and manage their social graph. Use them for follow/unfollow actions, incoming follow requests, follower and following lists, follow counts, and blocked-user management.

For an end-to-end product walkthrough, see [User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph). This section focuses on SDK calls and return shapes.

## Relationship Systems

| System | What it manages | Main SDK surface |
| --- | --- | --- |
| Following | Follow requests, accepted follows, pending requests, follower/following lists, and follow counts | `UserRepository.Relationship` on TypeScript, `relationship()` on Android and Flutter, `AmityUserRelationship` on iOS |
| Blocking | Block/unblock actions, the current user's blocked-user list, and — in the reverse direction — the users who have blocked the current user | Relationship block APIs plus `getBlockedUsers()` / `getBlockingUsers()` on the user repository |

Follow status values are platform-specific enum or string values, but the shared meanings are:

| Status | Meaning |
| --- | --- |
| `none` | No active follow relationship |
| `pending` | A follow request exists and is waiting for action |
| `accepted` | The follow relationship is active |
| `blocked` | The relationship is blocked |

Whether a follow becomes `accepted` immediately or starts as `pending` is determined by your network's follow configuration. The same SDK follow call is used in both cases.

## Platform Coverage

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Follow and unfollow | Yes | Yes | Yes | Yes |
| Accept and decline incoming follow requests | Yes | Yes | Yes | Yes |
| Get current user's follow counts | Yes | Yes | Yes | Yes |
| Get another user's follow counts and status | Yes | Yes | Yes | Yes |
| Query followers and following | Yes | Yes | Yes | Yes |
| Block and unblock users | Yes | Yes | Yes | Yes |
| Query paginated blocked users | Yes | Yes | Yes | Yes |
| Get all blocked users as a one-shot list | Yes | Yes | Yes | Not available in the Flutter public repository |
| Query users who blocked the current user (reverse direction) | Yes | Yes | Yes | Not available in the current Flutter SDK |

## Use The Right Read API

Use the live or paginated APIs for user-facing screens:

- Follow info: profile headers, follow buttons, counters, and relationship badges.
- Follower/following lists: people lists with pagination and refresh behavior.
- Blocked users: a settings screen where users can review and unblock accounts.

Use `getAllBlockedUsers()` only when you need a one-shot block list for local decisions. It returns up to 100 blocked users on TypeScript, iOS, and Android, and the SDK caches the result briefly.

Do not rely on this overview for feed visibility, search visibility, comment permissions, or other product policy details. Those behaviors can depend on backend configuration and feature area. Handle SDK errors from the affected feature API and keep the UI state in sync with relationship status.

## Related Guides

    Create or remove a follow relationship.
    Approve or reject incoming follow requests.
    Read follow status and follow counts.
    Query paginated relationship lists.
    Block or unblock another user.
    Query the current user's blocked-user list.
    Query the reverse direction — users who blocked you.

## Social — Content Management Overview

### [Overview](https://learn.social.plus/social-plus-sdk/social/content-management/overview)

> Create, retrieve, moderate, and measure posts, comments, stories, and share links with the social.plus SDKs

Content Management is the SDK surface for user-generated social content. Use it to build feeds, post creation flows, comment threads, story experiences, content reporting, review queues, and shareable links.

The exact method names and supported content types vary by platform, so the pages in this section show platform-specific snippets instead of treating every SDK as identical.

    Create text, media, poll, live, room, mixed, and custom posts where supported by each SDK.
    Add, query, edit, and delete comments and replies on posts or other supported targets.
    Publish and retrieve short-lived story content for users and communities.
    Fetch network-level shareable-link configuration for supported content types.
    Let users flag content and let moderators review or manage posts where the SDK exposes review APIs.
    Mark posts and stories as viewed and read engagement counters exposed by the SDK.

## Platform Coverage

| Area | Current SDK coverage |
| --- | --- |
| Posts | TypeScript, iOS, Android, and Flutter. Supported post types differ by SDK; see [Posts Overview](./posts/overview). |
| Comments | TypeScript, iOS, Android, and Flutter. |
| Stories | TypeScript, iOS, Android, and Flutter. |
| Shareable links | TypeScript, iOS, and Android expose shareable-link configuration. A Flutter public API was not found in the current Flutter SDK source. |
| Post `structureType` | TypeScript, iOS, and Android expose this field. Flutter's current public post model exposes `type` but not `structureType`. |
| Post `localCommentCount` | TypeScript, iOS, and Android expose a locally computed live comment count. Flutter's current public post model does not expose this field. Deprecated with comment approval (iOS/TS) — use `getLocalCommentCount(includePending:)`. |

  This section documents SDK behavior only. Console configuration, API-only workflows, and UIKit behavior can differ and are covered elsewhere.

## Integration Path

    Decide whether the content belongs to a user feed, a community feed, or another target supported by the page you are implementing.
    Image, video, file, audio, and clip posts reference uploaded files. Use the content-handling upload pages before calling the post creation APIs.
    Use the post, comment, or story repository for the content type. Prefer the platform-specific page for exact method names and return types.
    Use live objects or live collections for feeds, detail views, and comment threads that should update while the user is looking at them.
    Add flagging, review, delete, pin, and impression tracking only where your product workflow and platform SDK support those actions.

## Related Topics

    Start with text posts, then add media or custom post types.
    Load feeds and filter by target, type, status, or mixed media structure.
    Subscribe to social topics when the UI needs remote updates.

---

### [Content Sharing](https://learn.social.plus/social-plus-sdk/social/content-management/content-sharing)

> Fetch shareable-link configuration and build links for supported social content

Shareable links are configured at the network level. The SDKs fetch the configured domain and URL patterns so your app can build links to social.plus content using your own routing scheme.

The current SDKs expose this configuration differently:

| Platform | SDK surface |
| --- | --- |
| TypeScript | `Client.getShareableLinkConfiguration()` returns helper methods such as `generateLink`, `getPattern`, and `isEnabled`. |
| iOS | `client.getShareableLinkConfiguration()` returns `domain` and `patterns`. |
| Android | `AmityCoreClient.getShareableLinkConfiguration().getShareableLink()` returns `domain` and `patterns`. |
| Flutter | No public shareable-link configuration API was found in the current Flutter SDK source. |

  The SDK reads the configured patterns. It does not create the destination screens in your app. Your app still needs routes that can open the generated URLs.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Fetch configuration | None | No | Reads the network-level shareable-link configuration. |
| Generate a post link | `postId` | Yes | Post ID used to replace `{postId}` in the configured URL pattern. |
| Generate a post link | `posts` pattern | Yes | Pattern returned by the backend configuration for post links. |
| Generate a post link | `domain` | Yes | Configured shareable-link domain returned by the SDK. |

## Supported Pattern Keys

TypeScript maps content types to these pattern keys:

| Content type | Pattern key | Placeholder |
| --- | --- | --- |
| Post | `posts` | `{postId}` |
| Community | `communities` | `{communityId}` |
| User | `users` | `{userId}` |
| Livestream | `livestream` | `{livestream}` |
| Event | `events` | `{eventId}` |

iOS and Android return the backend `patterns` map directly. Check that the key you need exists before generating a link.

## Generate a Post Link

Fetch the shareable-link configuration before generating a post link, then fall back gracefully if the needed pattern is missing.


```typescript TypeScript
import { AmitySharableContentType, Client } from "@amityco/ts-sdk";

async function getPostShareLink(postId: string) {
  const config = await Client.getShareableLinkConfiguration();

  return config.generateLink(AmitySharableContentType.POST, postId);
}
```

```swift iOS
let postId = "post-id"
let config = try await client.getShareableLinkConfiguration()

if let pattern = config.patterns["posts"] {
    let link = config.domain + pattern.replacingOccurrences(
        of: "{postId}",
        with: postId
    )
    showInfo(link)
}
```

```kotlin Android
AmityCoreClient.getShareableLinkConfiguration()
    .getShareableLink()
    .subscribe({ config ->
        val pattern = config.getPatterns()["posts"]
        val link = pattern?.let {
            config.getDomain() + it.replace("{postId}", postId)
        }
    }, { error ->
        handleGeneralError(error)
    })
```


## Generate an Event Link

Event links are the primary use case for shareable links: an app can copy or share a direct link to an event detail screen. Gate the share UI on `isEnabled` first, then generate the link — `generateLink` returns `null` when the event pattern is not configured.


```typescript TypeScript
import { AmitySharableContentType, Client } from "@amityco/ts-sdk";

async function getEventShareLink(eventId: string) {
  const config = await Client.getShareableLinkConfiguration();

  // Feature gate — hide the share action when event links aren't configured
  if (!config.isEnabled(AmitySharableContentType.EVENT)) return null;

  return config.generateLink(AmitySharableContentType.EVENT, eventId);
  // → "https://app.example.com/events/abc123" or null
}
```

```swift iOS
let eventId = "event-id"
let config = try await client.getShareableLinkConfiguration()

// Feature gate — hide the share action when event links aren't configured
guard config.isEnabled(.event) else { return }

if let link = config.generateLink(.event, referenceId: eventId) {
    showInfo(link)
}
```

```kotlin Android
AmityCoreClient.getShareableLinkConfiguration()
    .subscribe({ config ->
        // Feature gate — hide the share action when event links aren't configured
        if (config.isEnabled(AmitySharableContentType.EVENT)) {
            val link = config.generateLink(AmitySharableContentType.EVENT, eventId)
            // ... copy or share `link`
        }
    }, { error ->
        handleGeneralError(error)
    })
```


Shareable links are available on TypeScript, iOS, and Android. Flutter has no public shareable-link configuration API in the current SDK source.

## Best Practices

- Treat missing patterns as a disabled share target for that content type.
- Generate links only after the content exists and you have the final content ID.
- Keep app route handling separate from link generation so deleted or restricted content can show a useful fallback screen.
- Cache the configuration during a session if your sharing UI needs it often.

## Related Topics

    Learn how posts are modeled and created.
    Share community destinations after configuring community URL patterns.
    Share user profile destinations after configuring user URL patterns.
    Share event links after configuring the event URL pattern.

---

### [Content Moderation Overview](https://learn.social.plus/social-plus-sdk/social/content-management/moderation/overview)

> SDK moderation surfaces for flagging, review, deletion, community governance, and user safety.

Use social.plus moderation APIs to collect user reports, review posts before publication, remove content, and enforce community rules. This overview maps the SDK surfaces; Console review workflows and policy decisions live outside the SDK.

    Let users flag or unflag posts and comments, then check flag status in the UI.
    Query reviewing posts and approve or decline them where post review is enabled.
    Remove posts or comments after a user action or moderation decision.
    Assign roles, ban members, unban members, and check community permissions.

## Choose the Right API

| Goal | Start here |
| --- | --- |
| Users report a post or comment | [Content Flagging](./content-flagging) |
| Moderators approve or decline posts in review | [Post Review](../posts/moderation/post-review) |
| Moderators remove posts | [Delete Post](../posts/moderation/delete-post) |
| Moderators remove comments | [Delete Comment](../comments/actions/delete-comment) |
| Community owners manage member permissions | [Community Moderation](../../communities-spaces/organization/community-moderation) |
| Users block abusive accounts | [Block & Unblock User](../../user-relationship/blocking/block-unblock-user) |

The SDK exposes the actions and status checks listed above. It does not define your community policy, escalation rules, moderator assignment process, or user appeal flow.

## Implementation Notes

- Keep moderation UI state local until the SDK call succeeds.
- Refresh the affected live object or collection after approving, declining, deleting, flagging, or unflagging content.
- Use permission checks before showing moderator-only actions.
- Keep user-facing labels for flag reasons aligned with your community guidelines.

## Related Topics

    Add report and unreport actions for posts and comments.
    Work with review queues and post approval state.

---

### [Content Flagging](https://learn.social.plus/social-plus-sdk/social/content-management/moderation/content-flagging)

> Flag posts and comments with an optional reason and detail, unflag them, and check flag status.

Use content flagging APIs when users need to report posts or comments for review. A report can say _why_ with a reason, and add the reporter's own words as an optional detail, so moderators see the context without a follow-up. The SDK supports flagging, unflagging, and checking whether the current user has flagged a loaded item.

  TypeScript, iOS, and Android flag posts and comments with no reason, or with a
  reason and an optional detail. Flutter flags posts and comments without a
  reason; its public post and comment flag builders do not accept a reason yet.

## SDK surfaces

    Flag and unflag posts through the post repository or post model extension, depending on platform.
    Flag and unflag comments through the comment repository or comment model extension.
    Pick one predefined reason and optionally add the reporter's own words as detail, for any reason including Others.
    Check whether the current user has flagged a loaded post or comment before rendering an unflag action.

## Flag reasons

A reason is one fixed category. On Android, iOS, and TypeScript it never carries text: the reporter's own words always go in `detail`. Flutter uses these reasons for messages only, and its Others reason carries the text.

| Reason | Android `AmityContentFlagReasonType` | iOS `AmityContentFlagReasonType` | TypeScript `AmityContentFlagReasonType` | Flutter `AmityContentFlagReason` (messages only) |
| --- | --- | --- | --- | --- |
| Against community guidelines | `COMMUNITY_GUIDELINES` | `.communityGuidelines` | `CommunityGuidelines` | `communityGuidelines` |
| Child endangerment | `CHILD_ENDANGERMENT` | `.childEndangerment` | `ChildEndangerment` | Not available |
| Harassment or bullying | `HARASSMENT_OR_BULLYING` | `.harassmentOrBullying` | `HarassmentOrBullying` | `harassmentOrBullying` |
| Self-harm or suicide | `SELF_HARM_OR_SUICIDE` | `.selfHarmOrSuicide` | `SelfHarmOrSuicide` | `selfHarmOrSuicide` |
| Violence or threatening content | `VIOLENCE_OR_THREATENING_CONTENT` | `.violenceOrThreateningContent` | `ViolenceOrThreateningContent` | `violenceOrThreateningContent` |
| Selling and promoting restricted items | `SELLING_RESTRICTED_ITEMS` | `.sellingRestrictedItems` | `SellingRestrictedItems` | `sellingRestrictedItems` |
| Sexual content or nudity | `SEXUAL_CONTENT_OR_NUDITY` | `.sexualContentOrNudity` | `SexualContentOrNudity` | `sexualContentOrNudity` |
| Spam or scams | `SPAM_OR_SCAMS` | `.spamOrScams` | `SpamOrScams` | `spamOrScams` |
| False information or misinformation | `FALSE_INFORMATION` | `.falseInformation` | `FalseInformation` | `falseInformation` |
| Others | `OTHERS` | `.others` | `Others` | `others('...')` |

Use **Child endangerment** for content that endangers a child, including suspected child sexual abuse material (CSAM). Send it as its own reason, not as Others with a detail, so these reports reach moderators under their own category. The reason is sent as the exact text `Child endangerment`.

On TypeScript, `AmityContentFlagReasonType` is the same enum as `ContentFlagReasonEnum`, exported under the name Android and iOS use. Both names work. Before TypeScript 7.31.0, only `ContentFlagReasonEnum` is exported.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Flag a post or comment | `postId` / `commentId` | Yes | All | ID of the content to report. |
| Flag a post or comment | `reason` | No | Android, iOS, TypeScript | One reason from the table above. Omit it to flag without a reason. |
| Flag a post or comment | `detail` | No | Android, iOS, TypeScript | The reporter's own words, for any reason including Others. Needs a `reason`. Sent as given; omitted when not set. The server limits it to 300 characters. |
| Unflag content | `postId` / `commentId` | Yes | All | Content ID whose current-user report should be removed. |
| Check flag status | `postId` / `commentId` or loaded model | Yes | All | Checks whether the current user has flagged the item. |

  A `detail` without a `reason` is not possible: every call that takes `detail`
  also requires `reason`. On TypeScript, a malformed options object is rejected
  before any request is sent.

## Flag a post

Flag a post when a member reports it. Pass a reason when your report menu offers one, and pass the reporter's text as `detail` when they add some. Use the no-reason call when your UI only offers a single "Report" action.


```kotlin Android
val postRepository = AmitySocialClient.newPostRepository()

// Reason with the reporter's own words
postRepository
    .flagPost(
        postId = postId,
        reason = AmityContentFlagReasonType.SPAM_OR_SCAMS,
        detail = "Repeated promotional links",
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )

// Reason only
postRepository
    .flagPost(postId, AmityContentFlagReasonType.HARASSMENT_OR_BULLYING)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )

// No reason
postRepository
    .flagPost(postId = postId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let repository = AmityPostRepository()

// Reason with the reporter's own words
try await repository.flagPost(
    withId: "post-id",
    reason: .spamOrScams,
    detail: "Repeated promotional links"
)

// Reason only: type the reason explicitly so the current call is used
try await repository.flagPost(
    withId: "post-id",
    reason: AmityContentFlagReasonType.harassmentOrBullying
)

// No reason
try await repository.flagPost(withId: "post-id")
```

```typescript TypeScript
import { AmityContentFlagReasonType, PostRepository } from '@amityco/ts-sdk';

// Reason with the reporter's own words
const didFlag = await PostRepository.flagPost(postId, {
  reason: AmityContentFlagReasonType.SpamOrScams,
  detail: 'Repeated promotional links',
});

if (didFlag) {
  showSuccessMessage('Post flagged');
}

// Reason only
await PostRepository.flagPost(postId, { reason: AmityContentFlagReasonType.HarassmentOrBullying });

// No reason
await PostRepository.flagPost(postId);
```

```dart Flutter
// Flutter flags posts without a reason
final didFlag = await post.report().flag();

if (didFlag) {
  // Show flagged state.
}
```


## Flag a comment

Flag a comment the same way: no reason, or a reason with an optional `detail`.


```kotlin Android
val commentRepository = AmitySocialClient.newCommentRepository()

// Reason with the reporter's own words
commentRepository
    .flagComment(
        commentId = commentId,
        reason = AmityContentFlagReasonType.HARASSMENT_OR_BULLYING,
        detail = "Insults another member in every reply",
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )

// No reason
commentRepository
    .flagComment(commentId = commentId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let repository = AmityCommentRepository()

// Reason with the reporter's own words
try await repository.flagComment(
    withId: "comment-id",
    reason: .harassmentOrBullying,
    detail: "Insults another member in every reply"
)

// No reason; returns a Bool
let didFlag = try await repository.flagComment(withId: "comment-id")
```

```typescript TypeScript
import { AmityContentFlagReasonType, CommentRepository } from '@amityco/ts-sdk';

// Reason with the reporter's own words
const didFlag = await CommentRepository.flagComment(commentId, {
  reason: AmityContentFlagReasonType.HarassmentOrBullying,
  detail: 'Insults another member in every reply',
});

if (didFlag) {
  showSuccessMessage('Comment flagged');
}

// No reason
await CommentRepository.flagComment(commentId);
```

```dart Flutter
// Flutter flags comments without a reason
final didFlag = await comment.report().flag();

if (didFlag) {
  // Show flagged state.
}
```


## Report child endangerment

Flag content that endangers a child with the Child endangerment reason. A `detail` is optional, as for any reason. The same reason works for comments and messages, and for user behavior reports.


{/* doc-as-test: skip (CHILD_ENDANGERMENT ships after the published Android SDK) */}
```kotlin Android
AmitySocialClient.newPostRepository()
    .flagPost(postId, AmityContentFlagReasonType.CHILD_ENDANGERMENT)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

{/* doc-as-test: skip (childEndangerment ships after the published iOS SDK) */}
```swift iOS
// Type the reason explicitly so the current call is used
try await AmityPostRepository().flagPost(
    withId: "post-id",
    reason: AmityContentFlagReasonType.childEndangerment
)
```

```typescript TypeScript
import { AmityContentFlagReasonType, PostRepository } from '@amityco/ts-sdk';

await PostRepository.flagPost(postId, {
  reason: AmityContentFlagReasonType.ChildEndangerment,
});
```


## Build a report-reason picker

On TypeScript and iOS, build your report menu from the SDK's reason list instead of a hardcoded copy. A reason added in a later SDK release then appears in your menu without a code change.

| | TypeScript | iOS |
| --- | --- | --- |
| Reasons in display order, Others last | `getContentFlagReasons()` (a new array on each call) | `AmityContentFlagReasonType.allCases` |
| Stable key, such as `child_endangerment` | `getContentFlagReasonKey(reason)` | `reason.key` |
| English label | the enum value | `reason.defaultLabel` |

The key is snake_case, the same on every platform, and never renamed. Use it to look up your translated label, and show the English label when you have no translation for the key.

Never send the key or the label to the server. Pass the enum value as `reason`.


```typescript TypeScript
import {
  AmityContentFlagReasonType,
  getContentFlagReasonKey,
  getContentFlagReasons,
} from '@amityco/ts-sdk';

// Your app's translated strings, keyed by your own prefix plus the SDK key
declare const translations: Record<string, string | undefined>;

const reasonRows = getContentFlagReasons()
  // Offer Others separately, with a free-text field for detail
  .filter((reason) => reason !== AmityContentFlagReasonType.Others)
  .map((reason) => ({
    reason,
    label: translations[`report_reason_${getContentFlagReasonKey(reason)}`] ?? reason,
  }));
```

{/* doc-as-test: skip (key and defaultLabel ship after the published iOS SDK) */}
```swift iOS
// Your app's translated strings, keyed by your own prefix plus the SDK key
let translations: [String: String] = [:]

let reasonRows = AmityContentFlagReasonType.allCases
    // Offer Others separately, with a free-text field for detail
    .filter { $0 != .others }
    .map { reason in
        (reason: reason, label: translations["report_reason_\(reason.key)"] ?? reason.defaultLabel)
    }
```


  Android has no key or label helpers yet. To list the reasons there, iterate
  `AmityContentFlagReasonType.entries` (or `values()` on Kotlin earlier than 1.9)
  and supply your own label for each value.

## Report with Others

Use the Others reason when none of the categories fit. Put the reporter's explanation in `detail`, exactly as for any other reason.


```kotlin Android
AmitySocialClient.newPostRepository()
    .flagPost(
        postId = postId,
        reason = AmityContentFlagReasonType.OTHERS,
        detail = "Shares a member's home address",
    )
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
try await AmityPostRepository().flagPost(
    withId: "post-id",
    reason: .others,
    detail: "Shares a member's home address"
)
```

```typescript TypeScript
import { AmityContentFlagReasonType, PostRepository } from '@amityco/ts-sdk';

await PostRepository.flagPost(postId, {
  reason: AmityContentFlagReasonType.Others,
  detail: "Shares a member's home address",
});
```


  The earlier calls that took only a reason are **deprecated** but still work:
  `flagPost(postId, reason)` and `flagComment(commentId, reason)` with a reason
  string on TypeScript, and with `AmityContentFlagReason` on Android and iOS,
  where custom text was passed as `Others("...")` / `.others("...")`. Move custom
  text to `detail` with the Others reason. Flagging with only an ID is not
  deprecated.

## Unflag content

Unflag content when the current user removes their own report from a post or comment.


```kotlin Android
AmitySocialClient.newPostRepository()
    .unflagPost(postId = postId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )

AmitySocialClient.newCommentRepository()
    .unflagComment(commentId = commentId)
    .subscribe(
        { showSuccessMessage() },
        { error -> handleGeneralError(error) },
    )
```

```swift iOS
let postRepository = AmityPostRepository()
let commentRepository = AmityCommentRepository()

try await postRepository.unflagPost(withId: "post-id")
try await commentRepository.unflagComment(withId: "comment-id")
```

```typescript TypeScript
import { CommentRepository, PostRepository } from '@amityco/ts-sdk';

const didUnflagPost = await PostRepository.unflagPost(postId);
const didUnflagComment = await CommentRepository.unflagComment(commentId);
```

```dart Flutter
final didUnflagPost = await post.report().unflag();
final didUnflagComment = await comment.report().unflag();
```


## Check flag status

Check flag status before rendering a flag or unflag action for the loaded item.


```kotlin Android
val loadedPost = post ?: return
val loadedComment = comment ?: return

val isPostFlagged = loadedPost.isFlaggedByMe()
val isCommentFlagged = loadedComment.isFlaggedByMe()
```

```swift iOS
let postRepository = AmityPostRepository()
let commentRepository = AmityCommentRepository()

let isPostFlagged = try await postRepository.isFlaggedByMe(withId: "post-id")
let isCommentFlagged = try await commentRepository.isCommentFlaggedByMe(withId: "comment-id")
```

```typescript TypeScript
import { CommentRepository, PostRepository } from '@amityco/ts-sdk';

const isPostFlagged = await PostRepository.isPostFlaggedByMe(postId);
const isCommentFlagged = await CommentRepository.isCommentFlaggedByMe(commentId);
```

```dart Flutter
final isPostFlagged = post.isFlaggedByMe;
final isCommentFlagged = comment.isFlaggedByMe;
```


Flagging creates report state; it does not delete, hide, approve, or decline content by itself. For review workflows, use the moderation tools available in Console and the SDK APIs for the content type you are moderating.

## Platform notes

- Reason with optional detail ships in TypeScript 7.29.0 and in the October 2026 iOS and Android releases.
- The Child endangerment reason ships in TypeScript 7.31.0, which also adds `getContentFlagReasons()`, `getContentFlagReasonKey()`, and the `AmityContentFlagReasonType` export. Android and iOS add the reason in their next releases; the iOS release also adds `key` and `defaultLabel` to `AmityContentFlagReasonType`. Flutter does not offer it.
- On iOS, when you omit `detail`, write the reason with its type, for example `AmityContentFlagReasonType.spamOrScams`. The shorthand `.spamOrScams` on its own selects the deprecated call.
- A flag without a reason is recorded with a default reason: Others on TypeScript and Android, and Against community guidelines on iOS.
- Flutter flags posts and comments without a reason.

## Related topics

    Approve or decline posts in review workflows.
    Remove posts after a moderation decision.
    Remove comments after a moderation decision.
    Manage community roles, bans, and permissions.
    Flag chat messages with the same reasons and detail.

## Social — Posts

### [Posts Overview](https://learn.social.plus/social-plus-sdk/social/content-management/posts/overview)

> Understand post targets, content types, structure types, live comment counts, and the platform-specific post APIs

Posts are the primary content objects in social.plus. A post belongs to a target, such as a user feed or community feed, and can contain text, uploaded media, poll data, live or room references, or custom data depending on the SDK.

  Looking for a product walkthrough? The [Rich Content Creation](/use-cases/social/rich-content-creation) guide covers an end-to-end content flow. This page focuses on SDK surfaces and data behavior.

## Post Types

| Type | Current SDK notes |
| --- | --- |
| Text | Supported by TypeScript, iOS, Android, and Flutter. |
| Image | Supported by TypeScript, iOS, Android, and Flutter after image upload. |
| Video | Supported by TypeScript, iOS, Android, and Flutter after video upload. |
| File | Supported by TypeScript, iOS, Android, and Flutter after file upload. |
| Poll | Supported by TypeScript, iOS, Android, and Flutter when a poll exists. |
| Live stream or room | TypeScript and Android expose both live stream and room data types. iOS exposes room creation and deprecated live-stream creation. Flutter exposes live-stream post creation in the current source. |
| Audio | Supported by TypeScript, iOS, and Android after audio upload. A Flutter audio post creator was not found in the current source. |
| Clip | Supported by TypeScript, iOS, and Android after clip upload. A Flutter clip post creator was not found in the current source. |
| Mixed media | TypeScript, iOS, and Android expose mixed attachment/media flows. A Flutter mixed-media post creator was not found in the current source. |
| Event | Supported by TypeScript, iOS, and Android. References an existing event via `data.eventId`. Reads must go through `GET /api/v5/posts` — event posts are excluded from unfiltered `v3` and `v4` results. See [Event Posts](./creation/event-post). |
| Custom | Supported by TypeScript, iOS, Android, and Flutter for app-specific data. |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Create a text post | `targetType` | Yes | Feed target type, commonly `community` or `user`. |
| Create a text post | `targetId` | Yes | Target feed ID, such as a community ID or user ID. |
| Create a text post | `data.text` | Yes | Text body for the post. |
| Query posts with mixed structure | `dataTypes` | Yes | Content type filter, such as `image`. |
| Query posts with mixed structure | `includeMixedStructure` | No | Include mixed-structure posts alongside the requested media type. |
| Subscribe to post/comment events | Community or post object | Yes | Object used to build the realtime topic for the scope being observed. |
| Subscribe to post/comment events | Subscription level | Yes | Realtime level, such as post-and-comment or comment-only. |

## Create a Text Post

Use the text post creation page for full platform coverage; this TypeScript example shows the minimum shape for a community text post.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: createdPost } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Hello community",
  },
});
```


## Post Structure

Media posts use a parent-child structure. The parent post carries the target, text, metadata, counters, and other feed-level fields. Uploaded image, video, file, audio, or clip attachments are represented as child posts.

```mermaid
graph TD
    A["Parent post"] --> B["Text and metadata"]
    A --> C["Child post: image"]
    A --> D["Child post: video"]
    A --> E["Child post: file"]
    A --> F["Comments"]
    A --> G["Reactions"]
```

Common post fields include:

| Field | Notes |
| --- | --- |
| `postId` | Unique post ID. |
| `parentPostId` | Parent ID for a child post; empty or null for parent posts depending on platform. |
| `targetId` / `targetID` | Feed target ID, such as a community ID or user ID. TypeScript and iOS use `targetId`; some platform models expose differently cased names. |
| `targetType` | Target type, commonly `community` or `user`. |
| `dataType` / `type` | Content type such as `text`, `image`, `video`, `file`, `poll`, or custom type. Flutter exposes this as `type`. |
| `structureType` | Composition type exposed by TypeScript, iOS, and Android. Flutter's current public post model does not expose this field. |
| `data` | Type-specific post data. |
| `metadata` | App-defined metadata. |
| `commentsCount` | Server comment count at fetch time. |
| `localCommentCount` | Locally computed live count exposed by TypeScript, iOS, and Android. |
| `childrenPosts` / `children` | Child posts for media attachments. Field name varies by SDK. |
| `isDeleted` | Soft-delete state. |

## Structure Type

`structureType` classifies a post by its attachment composition.

| Platform | Current behavior |
| --- | --- |
| TypeScript | Typed values are `text`, `image`, `video`, `file`, `audio`, `event`, and `mixed`. |
| iOS | Exposes `structureType` as a string on `AmityPost`. |
| Android | Exposes `getStructureType()` with values including `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `FILE`, `LIVESTREAM`, `POLL`, `CLIP`, `ROOM`, `EVENT`, `MIXED`, and `UNKNOWN`. |
| Flutter | No public `structureType` field was found in the current public `AmityPost` model. |

Use `includeMixedStructure` when querying a single media type and you also want posts whose `structureType` is `mixed`.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const stopObserving = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    dataTypes: ["image"],
    includeMixedStructure: true,
  },
  ({ data }) => {
    renderResults(data);
  }
);
```


## Live Comment Count

`localCommentCount` is a client-side count that starts from the server `commentsCount` value and then updates as the SDK observes comment create/delete events. It is exposed by TypeScript, iOS, and Android in the current SDKs.

Use it for active feed or detail screens where a live counter matters. Use `commentsCount` when you only need the server value returned with the fetched post.

To receive remote updates, the app must both observe the post or feed and subscribe to an appropriate realtime topic.

  **Deprecated with comment approval.** In the comment-approval SDKs (iOS and
  TypeScript), `localCommentCount` is deprecated in favor of
  `getLocalCommentCount(includePending:)`. The old property equals
  `getLocalCommentCount(includePending: true)` — it includes the author's own
  pending comment; pass `includePending: false` for the shared, approved-only
  count. Move new code to `getLocalCommentCount(includePending:)` and choose the
  flag explicitly. See [Comment
  Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review#related-sdk-functions)
  for how the two counts behave under review.


```typescript TypeScript
import { getCommunityTopic, getPostTopic, SubscriptionLevels } from "@amityco/ts-sdk";

const communityTopic = getCommunityTopic(
  community,
  SubscriptionLevels.POST_AND_COMMENT
);

const postCommentTopic = getPostTopic(post, SubscriptionLevels.COMMENT);
```


  Global feed queries do not provide a single global post/comment realtime topic. Subscribe at a community, user, or post scope when the UI needs remote events.

## Related Topics

    Start with the simplest post creation path.
    Publish an event as a post so it renders as a card in feeds.
    Load feeds and filter by type, target, review status, or mixed structure.
    Track post views and meaningful views where supported.

---

### [Text Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/text-post)

> Create text posts with the current social.plus SDKs, including optional structured links where supported.

Text posts publish written content to a user feed, a community feed, or the current user's own feed. Use them for plain updates, status messages, and posts that attach structured link metadata.

  The text is the parent post content. The SDK creation fields below describe the SDK API; UIKit's product-tag UI is a separate surface and may support fewer post types. See [UIKit Product Tagging](/uikit/components/social/product-tagging) for the UI-specific coverage.

    Publish to user feeds, community feeds, or the current user's feed depending on the SDK target API.
    TypeScript, Android, and iOS can attach structured links during text post creation.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `text` | Yes | TypeScript, iOS, Android, Flutter | Text content for the post body. |
| `targetType` | Yes for explicit feed targets | TypeScript, iOS, Android, Flutter | Feed target, usually `community` or `user`. |
| `targetId` | Yes for explicit feed targets | TypeScript, iOS, Android, Flutter | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android, Flutter | User mention payload where supported by the platform builder. |
| `links` | No | TypeScript, Android, iOS | Structured link metadata supported by TypeScript, Android, and iOS. |
| `productTags` | No | TypeScript, Android, iOS | Products tagged in the post text. Text product tag types: `Amity.TextProductTag`, `AmityTextProductTag`, `AmityProductTag.Text`. |

**Product tags (SDK API).** `productTags` tags products mentioned in the post **text**. Each tag names a product and the character range it covers in that text. Media product tags do not apply to a text-only post. When a post also has media, the text remains on the parent and the media is a child; use the media page's `attachmentProductTags` for that child. See [Image Post](./image-post) or [Video Post](./video-post) for those fields. Flutter does not expose product tags on any post builder. For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create a Text Post

The examples below create a text post in a community. Use the equivalent user target method or target type when posting to a user feed.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityTextPostBuilder()
builder.setText("Hello community")

let post = try await postRepository.createTextPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil
)
```

```kotlin Android
postRepository.createTextPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    text = "Hello community"
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Hello community",
  },
});
```

```dart Flutter
final post = await AmitySocialClient.newPostRepository()
    .createPost()
    .targetCommunity(communityId)
    .text('Hello community')
    .createTextPost();
```


## Add Structured Links

TypeScript, Android, and iOS expose a `links` field when creating a text post. Fetch preview metadata first if the post should render a preview card.

Flutter's current public post creation builder supports text, metadata, and user mentions, but it does not expose a structured `links` payload on the text post builder.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityTextPostBuilder()
builder.setText("Check this out https://www.amity.co")

let preview = try await client.getLinkPreviewMetadata(url: "https://www.amity.co")
let links = [
    AmityLink(
        url: "https://www.amity.co",
        renderPreview: true,
        domain: preview.domain,
        title: preview.title,
        imageUrl: preview.imageUrl
    )
]

let post = try await postRepository.createTextPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil,
    links: links
)
```

```kotlin Android
AmityCoreClient.getLinkPreviewMetadata("https://www.amity.co")
    .flatMap { preview ->
        val links = listOf(
            AmityLink(
                index = null,
                length = null,
                url = "https://www.amity.co",
                renderPreview = true,
                domain = preview.getDomain(),
                title = preview.getTitle(),
                imageUrl = preview.getImageUrl()
            )
        )

        postRepository.createTextPost(
            targetType = AmityPost.TargetType.COMMUNITY,
            targetId = communityId,
            text = "Check this out https://www.amity.co",
            links = links
        )
    }
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { Client, PostRepository } from "@amityco/ts-sdk";

const preview = await Client.getLinkPreviewMetadata("https://www.amity.co");

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Check this out https://www.amity.co",
  },
  links: [
    {
      url: "https://www.amity.co",
      renderPreview: true,
      domain: preview.domain ?? undefined,
      title: preview.title ?? undefined,
      imageUrl: preview.imageUrl ?? undefined,
    },
  ],
});
```


## Tag Products in the Text

TypeScript, Android, and iOS accept a `productTags` array when creating a text post. Each tag names a product and the character range it covers in the post text, so UIKit can render that range as a tappable product mention.

Set `index` and `length` against the same string you pass as `text`. In the examples below, `featured product` starts at index 12 and is 16 characters long. iOS stores only the range. TypeScript and Android also carry the matched `text`.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityTextPostBuilder()
builder.setText("Loving this featured product for my morning runs!")

let post = try await postRepository.createTextPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil,
    productTags: [
        AmityTextProductTag(productId: "prod_001", index: 12, length: 12)
    ]
)
```

```kotlin Android
postRepository.createTextPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    text = "Loving this featured product for my morning runs!",
    productTags = listOf(
        AmityProductTag.Text(
            productId = "prod_001",
            text = "featured product",
            index = 12,
            length = 16
        )
    )
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Loving this featured product for my morning runs!",
  },
  productTags: [
    { productId: "prod_001", text: "featured product", index: 12, length: 16 },
  ],
});
```


## Query Text Posts

Post query APIs are SDK-specific. For TypeScript, `PostRepository.getPosts` returns a live collection through a callback instead of a promise, so do not call it with `await`.

For structure type values and filtering behavior, see [Posts Overview](../overview) and [Mixed Media Posts](./mixed-media-post).

## Related Topics

    Review post concepts, retrieval, and moderation flows.
    Load text posts back into feed and detail screens.
    Add user mention payloads where the platform exposes them.

---

### [Image Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/image-post)

> Create image posts with uploaded image files using the current social.plus SDKs.

Image posts combine one or more uploaded images with an optional text caption. Upload the images first, then pass the uploaded image objects or file IDs to the post creation API.

This page focuses on the SDK call that creates the post. See [Image Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/image-handling) for upload steps, supported file inputs, and upload constraints.

    Create posts from image objects or file IDs returned by the file upload flow.
    Add text, metadata, mentions, or other SDK-supported post fields alongside the images.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `images`, `uploadedImages`, or `fileId` | Yes | TypeScript, iOS, Android, Flutter | Uploaded image objects or image file IDs, depending on SDK. |
| `text` | No | TypeScript, iOS, Android, Flutter | Caption text shown with the image post. |
| `targetType` | Yes | TypeScript, iOS, Android, Flutter | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android, Flutter | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android, Flutter | User mention payload where supported by the platform builder. |
| `productTags` | No | TypeScript, Android, iOS | Products tagged in the post text. Text product tag types: `Amity.TextProductTag`, `AmityTextProductTag`, `AmityProductTag.Text`. |
| `attachmentProductTags` | No | TypeScript, Android, iOS | Products tagged on individual image attachments. An `AmityAttachmentProductTags` container, keyed by each attachment's `fileId`. |

**Product tags (SDK API).** An image post has a text parent and an image child. `productTags` tags products mentioned in the parent **text**. `attachmentProductTags` tags products on the child **media attachment**, and is not an array: it is an `AmityAttachmentProductTags` container that maps each attachment's `fileId` to that attachment's media tags. Flutter does not expose product tags on any post builder. See [Tag Products](#tag-products) below for both. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging). For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create an Image Post

The examples below create an image post in a community. Replace the target with the SDK's user-feed target when posting to a user.


```swift iOS
func createImagePost(
    uploadedImages: [AmityImageData],
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityImagePostBuilder()
    builder.setImages(uploadedImages)
    builder.setText("Photos from today")

    return try await postRepository.createImagePost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```

```kotlin Android
fun createImagePost(
    uploadedImages: Set<AmityImage>,
    communityId: String
) {
    postRepository.createImagePost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        images = uploadedImages,
        text = "Photos from today"
    )
        .subscribe({ post ->
            showSuccessMessage(post.getPostId())
        }, { error ->
            handleGeneralError(error)
        })
}
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Photos from today",
  },
  attachments: [
    {
      type: "image",
      fileId,
    },
  ],
});
```

```dart Flutter
Future<AmityPost> createImagePost(List<AmityImage> uploadedImages) {
  return AmitySocialClient.newPostRepository()
      .createPost()
      .targetCommunity(communityId)
      .image(uploadedImages)
      .text('Photos from today')
      .post();
}
```


## Tag Products

TypeScript, Android, and iOS accept two separate product inputs when creating an image post. The text tag is applied to the parent; the attachment tag is applied to the image child.

| Input | Tags what | Shape |
| --- | --- | --- |
| `productTags` | Products named in the post text | An array of text product tags, each with a character range |
| `attachmentProductTags` | Products shown in one image | An `AmityAttachmentProductTags` container, keyed by `fileId` |

Build `attachmentProductTags` by setting the tags for each uploaded image's `fileId`. Images you do not set tags for stay untagged.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityImagePostBuilder()
builder.setImages(uploadedImages)
builder.setText("Wearing the featured product today")

let attachmentTags = AmityAttachmentProductTags()
attachmentTags.set(
    fileId: uploadedImages[0].fileId,
    tags: [AmityMediaProductTag(productId: "prod_001")]
)

let post = try await postRepository.createImagePost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil,
    productTags: [
        AmityTextProductTag(productId: "prod_001", index: 12, length: 12)
    ],
    attachmentProductTags: attachmentTags
)
```

```kotlin Android
val attachmentTags = AmityAttachmentProductTags.Builder()
attachmentTags.set(
    uploadedImages.first().getFileId(),
    listOf(AmityProductTag.Media(productId = "prod_001"))
)

postRepository.createImagePost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    images = uploadedImages,
    text = "Wearing the featured product today",
    productTags = listOf(
        AmityProductTag.Text(
            productId = "prod_001",
            text = "featured product",
            index = 12,
            length = 16
        )
    ),
    attachmentProductTags = attachmentTags.build()
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { AmityAttachmentProductTags, PostRepository } from "@amityco/ts-sdk";

const attachmentTags = new AmityAttachmentProductTags();
attachmentTags.set(fileId, [{ productId: "prod_001" }]);

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Wearing the featured product today",
  },
  attachments: [{ type: "image", fileId }],
  productTags: [
    { productId: "prod_001", text: "featured product", index: 12, length: 16 },
  ],
  attachmentProductTags: attachmentTags,
});
```


## Notes

- TypeScript accepts image attachments as `{ type: "image", fileId }`.
- Android accepts a `Set<AmityImage>`.
- iOS accepts `[AmityImageData]`.
- Flutter accepts `List<AmityImage>`.

For mixed attachment types, use [Mixed Media Posts](./mixed-media-post).

## Related Topics

    Upload images before creating image posts.
    Combine images with other supported media attachments.
    Review post concepts, retrieval, and moderation flows.

---

### [Video Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/video-post)

> Create video posts with uploaded video files using the current social.plus SDKs.

Video posts combine uploaded videos with an optional text caption. Upload the videos first, then pass the uploaded video objects or file IDs to the post creation API.

This page focuses on the SDK call that creates the post. See [Video Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/video-handling) for upload steps, supported file inputs, processing behavior, and upload constraints.

    Create posts from video objects or file IDs returned by the file upload flow.
    Add text, metadata, mentions, or other SDK-supported post fields alongside the videos.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `videos`, `uploadedVideos`, or `fileId` | Yes | TypeScript, iOS, Android, Flutter | Uploaded video objects or video file IDs, depending on SDK. |
| `text` | No | TypeScript, iOS, Android, Flutter | Caption text shown with the video post. |
| `targetType` | Yes | TypeScript, iOS, Android, Flutter | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android, Flutter | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android, Flutter | User mention payload where supported by the platform builder. |
| `productTags` | No | TypeScript, Android, iOS | Products tagged in the post text. Text product tag types: `Amity.TextProductTag`, `AmityTextProductTag`, `AmityProductTag.Text`. |
| `attachmentProductTags` | No | TypeScript, Android, iOS | Products tagged on individual video attachments. An `AmityAttachmentProductTags` container, keyed by each attachment's `fileId`. |

**Product tags (SDK API).** A video post has a text parent and a video child. `productTags` tags products mentioned in the parent **text**. `attachmentProductTags` tags products on the child **media attachment**, and is not an array: it is an `AmityAttachmentProductTags` container that maps each attachment's `fileId` to that attachment's media tags. Flutter does not expose product tags on any post builder. See [Tag Products](#tag-products) below for both. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging). For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create a Video Post

The examples below create a video post in a community. Replace the target with the SDK's user-feed target when posting to a user.


```swift iOS
func createVideoPost(
    uploadedVideos: [AmityVideoData],
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityVideoPostBuilder()
    builder.setVideos(uploadedVideos)
    builder.setText("Video from today")

    return try await postRepository.createVideoPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```

```kotlin Android
fun createVideoPost(
    uploadedVideos: Set<AmityVideo>,
    communityId: String
) {
    postRepository.createVideoPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        videos = uploadedVideos,
        text = "Video from today"
    )
        .subscribe({ post ->
            showSuccessMessage(post.getPostId())
        }, { error ->
            handleGeneralError(error)
        })
}
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Video from today",
  },
  attachments: [
    {
      type: "video",
      fileId,
    },
  ],
});
```

```dart Flutter
Future<AmityPost> createVideoPost(List<AmityVideo> uploadedVideos) {
  return AmitySocialClient.newPostRepository()
      .createPost()
      .targetCommunity(communityId)
      .video(uploadedVideos)
      .text('Video from today')
      .post();
}
```


## Tag Products

TypeScript, Android, and iOS accept two separate product inputs when creating a video post. The text tag is applied to the parent; the attachment tag is applied to the video child.

| Input | Tags what | Shape |
| --- | --- | --- |
| `productTags` | Products named in the post text | An array of text product tags, each with a character range |
| `attachmentProductTags` | Products shown in one video | An `AmityAttachmentProductTags` container, keyed by `fileId` |

Build `attachmentProductTags` by setting the tags for each uploaded video's `fileId`. Videos you do not set tags for stay untagged.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityVideoPostBuilder()
builder.setVideos(uploadedVideos)
builder.setText("Wearing the featured product today")

let attachmentTags = AmityAttachmentProductTags()
attachmentTags.set(
    fileId: uploadedVideos[0].fileId,
    tags: [AmityMediaProductTag(productId: "prod_001")]
)

let post = try await postRepository.createVideoPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil,
    productTags: [
        AmityTextProductTag(productId: "prod_001", index: 12, length: 12)
    ],
    attachmentProductTags: attachmentTags
)
```

```kotlin Android
val attachmentTags = AmityAttachmentProductTags.Builder()
attachmentTags.set(
    uploadedVideos.first().getFileId(),
    listOf(AmityProductTag.Media(productId = "prod_001"))
)

postRepository.createVideoPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    videos = uploadedVideos,
    text = "Wearing the featured product today",
    productTags = listOf(
        AmityProductTag.Text(
            productId = "prod_001",
            text = "featured product",
            index = 12,
            length = 16
        )
    ),
    attachmentProductTags = attachmentTags.build()
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { AmityAttachmentProductTags, PostRepository } from "@amityco/ts-sdk";

const attachmentTags = new AmityAttachmentProductTags();
attachmentTags.set(fileId, [{ productId: "prod_001" }]);

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Wearing the featured product today",
  },
  attachments: [{ type: "video", fileId }],
  productTags: [
    { productId: "prod_001", text: "featured product", index: 12, length: 16 },
  ],
  attachmentProductTags: attachmentTags,
});
```


## Notes

- TypeScript accepts video attachments as `{ type: "video", fileId }`.
- Android accepts a `Set<AmityVideo>`.
- iOS accepts `[AmityVideoData]`.
- Flutter accepts `List<AmityVideo>`.

For mixed attachment types, use [Mixed Media Posts](./mixed-media-post).

## Related Topics

    Upload videos before creating video posts.
    Create short-form clip posts where supported.
    Combine videos with other supported media attachments.

---

### [Audio Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/audio-post)

> Create audio posts where the SDK exposes audio post creation.

Audio posts attach uploaded audio files to a post. Upload the audio first, then pass the uploaded audio objects or file IDs to the post creation API.

TypeScript, Android, and iOS expose audio post creation APIs. Flutter can upload audio files, but the current public Flutter post creation builder does not expose an audio post creation method.

    Create posts from audio objects or file IDs returned by the audio upload flow.
    Use audio post creation only on SDKs that expose it in the public post builder.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `audios`, `uploadedAudios`, or `fileId` | Yes | TypeScript, iOS, Android | Uploaded audio objects or audio file IDs, depending on SDK. |
| `text` | No | TypeScript, iOS, Android | Caption text shown with the audio post. |
| `targetType` | Yes | TypeScript, iOS, Android | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android | User mention payload where supported by the platform builder. |
| `productTags` | No | iOS | Products named in the parent post text. |
| `attachmentProductTags` | No | TypeScript, iOS | Products shown on the child audio attachment. An `AmityAttachmentProductTags` container keyed by `fileId`. |

**Product tags (SDK API).** An audio post has a text parent and an audio child. iOS accepts both inputs on `createAudioPost`; TypeScript accepts `attachmentProductTags` for the child only. The public Android and Flutter audio creators expose neither field, so this page does not promise a post-creation workaround. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging). For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create an Audio Post

The examples below create an audio post in a community on SDKs that support audio post creation.


```swift iOS
func createAudioPost(
    uploadedAudios: [AmityAudioData],
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityAudioPostBuilder()
    builder.setAudios(uploadedAudios)
    builder.setText("Listen to this")

    return try await postRepository.createAudioPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```

```kotlin Android
fun createAudioPost(
    uploadedAudios: Set<AmityAudio>,
    communityId: String
) {
    postRepository.createAudioPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        audios = uploadedAudios,
        text = "Listen to this"
    )
        .subscribe({ post ->
            showSuccessMessage(post.getPostId())
        }, { error ->
            handleGeneralError(error)
        })
}
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createAudioPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Listen to this",
  },
  attachments: [
    {
      type: "audio",
      fileId,
    },
  ],
});
```


## Flutter Support

Flutter's public file repository supports audio upload, but the public post creation builder currently exposes text, image, video, file, poll, live stream, and custom post creation paths. It does not expose `.audio(...)` or a dedicated audio post creator.

Use a supported Flutter post type, or create audio posts from a platform/backend layer that exposes audio post creation.

## Notes

- TypeScript accepts audio attachments as `{ type: "audio", fileId }`.
- Android accepts a `Set<AmityAudio>`.
- iOS accepts `[AmityAudioData]`.
- Do not set `structureType` manually; the service derives post structure from the created post data.

## Related Topics

    Upload files before creating attachment-based posts.
    Combine multiple supported media attachment types.
    Review post concepts, retrieval, and moderation flows.

---

### [File Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/file-post)

> Create file posts with uploaded files using the current social.plus SDKs.

File posts attach uploaded files to a post. Upload files first, then pass the uploaded file objects or file IDs to the post creation API.

This page focuses on the SDK call that creates the post. See [File Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/file) for upload steps, supported file inputs, and upload constraints.

    Create posts from file objects or file IDs returned by the file upload flow.
    Add text, metadata, mentions, or other SDK-supported post fields alongside the file attachments.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `files`, `uploadedFiles`, or `fileId` | Yes | TypeScript, iOS, Android, Flutter | Uploaded file objects or file IDs, depending on SDK. |
| `text` | No | TypeScript, iOS, Android, Flutter | Caption text shown with the file post. |
| `targetType` | Yes | TypeScript, iOS, Android, Flutter | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android, Flutter | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android, Flutter | User mention payload where supported by the platform builder. |
| `productTags` | No | TypeScript, iOS | Products named in the parent post text. |
| `attachmentProductTags` | No | TypeScript, iOS | Products shown on child file attachments. An `AmityAttachmentProductTags` container keyed by `fileId`. |

## Create a File Post

The examples below create a file post in a community. Replace the target with the SDK's user-feed target when posting to a user.


```swift iOS
func createFilePost(
    uploadedFiles: [AmityFileData],
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityFilePostBuilder()
    builder.setFiles(uploadedFiles)
    builder.setText("Featured product resources")

    let attachmentTags = AmityAttachmentProductTags()
    attachmentTags.set(
        fileId: uploadedFiles[0].fileId,
        tags: [AmityMediaProductTag(productId: "prod_001")]
    )

    return try await postRepository.createFilePost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil,
        productTags: [
            AmityTextProductTag(productId: "prod_001", index: 0, length: 12)
        ],
        attachmentProductTags: attachmentTags
    )
}
```

```kotlin Android
fun createFilePost(
    uploadedFiles: Set<AmityFile>,
    communityId: String
) {
    postRepository.createFilePost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        files = uploadedFiles,
        text = "Resources for the team"
    )
        .subscribe({ post ->
            showSuccessMessage(post.getPostId())
        }, { error ->
            handleGeneralError(error)
        })
}
```

```typescript TypeScript
import { AmityAttachmentProductTags, PostRepository } from "@amityco/ts-sdk";

const attachmentTags = new AmityAttachmentProductTags();
attachmentTags.set(fileId, [{ productId: "prod_001" }]);

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Featured product resources",
  },
  attachments: [
    {
      type: "file",
      fileId,
    },
  ],
  productTags: [
    { productId: "prod_001", text: "Featured product", index: 0, length: 16 },
  ],
  attachmentProductTags: attachmentTags,
});
```

```dart Flutter
Future<AmityPost> createFilePost(List<AmityFile> uploadedFiles) {
  return AmitySocialClient.newPostRepository()
      .createPost()
      .targetCommunity(communityId)
      .file(uploadedFiles)
      .text('Resources for the team')
      .post();
}
```


**Product tags (SDK API).** A file post has a text parent and one child per file attachment. TypeScript's generic `createPost` and iOS `createFilePost` expose both text `productTags` for the parent and `attachmentProductTags` for the file children. The public Android and Flutter file creators expose neither field. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging).

## Notes

- TypeScript accepts file attachments as `{ type: "file", fileId }`.
- Android accepts a `Set<AmityFile>`.
- iOS accepts `[AmityFileData]`.
- Flutter accepts `List<AmityFile>`.

For mixed attachment types, use [Mixed Media Posts](./mixed-media-post).

## Related Topics

    Upload files before creating file posts.
    Combine files with other supported media attachments.
    Review post concepts, retrieval, and moderation flows.

---

### [Custom Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/custom-post)

> Create custom post types with application-defined structured data.

Custom posts let your app publish structured content that it renders itself, such as product cards, event cards, listings, or other domain-specific content.

Use a stable, application-owned data type such as `post.product` or `event.session`. Avoid built-in post data types such as `text`, `image`, `video`, `file`, `poll`, and `liveStream`.

    Store an application-defined JSON payload in the post data.
    Render custom post types with your own UI in feeds and detail screens.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `dataType` or `customDataType` | Yes | Stable application-owned type string that identifies how your app should render the post. |
| `data` | Yes | JSON-style payload for the custom post. Keep this schema owned by your application. |
| `targetType` | Yes | Feed target, usually `community` or `user`. |
| `targetId` | Yes | Community ID or user ID for the target feed. |
| `metadata` | No | Auxiliary custom metadata that should not define the post type. |
| `mentionees` | No | User mention payload where supported by the platform builder. |

## Create a Custom Post

The examples below create a custom product-style post in a community. Replace the data type and payload with your app's schema.


```swift iOS
let postRepository = AmityPostRepository()
let builder = AmityCustomPostBuilder()
builder.setDataType("post.product")
builder.setData([
    "title": "Wireless headphones",
    "price": 149.99,
    "currency": "USD"
])

let post = try await postRepository.createCustomPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil
)
```

```kotlin Android
val data = JsonObject().apply {
    addProperty("title", "Wireless headphones")
    addProperty("price", 149.99)
    addProperty("currency", "USD")
}

postRepository.createCustomPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    customDataType = "post.product",
    data = data
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  dataType: "post.product",
  data: {
    title: "Wireless headphones",
    price: 149.99,
    currency: "USD",
  },
});
```

```dart Flutter
final post = await AmitySocialClient.newPostRepository()
    .createPost()
    .targetCommunity(communityId)
    .custom('post.product', {
      'title': 'Wireless headphones',
      'price': 149.99,
      'currency': 'USD',
    })
    .post();
```


## Notes

- The SDK stores the custom payload; your application owns validation and rendering for the custom schema.
- Use one stable data type per custom schema so feeds can route rendering predictably.
- Keep custom post data focused on renderable content. Use `metadata` for auxiliary app data that should not define the post type.

## Related Topics

    Review post concepts, retrieval, and moderation flows.
    Load custom posts back into feed and detail screens.
    Update supported post fields after creation.

---

### [Poll Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/poll-post)

> Create poll posts that reference an existing social.plus poll.

Poll posts share an existing poll in a user or community feed. Create the poll first with the Poll Repository, then create a post that references the returned `pollId`.

Create the poll before creating the post. See [Poll Creation Guidelines](/social-plus-sdk/core-concepts/content-handling/poll#create-a-poll) for poll creation examples.

    A poll post points to a `pollId` returned by the poll creation flow.
    Publish the poll into a user feed or community feed with optional text.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `pollId` | Yes | TypeScript, iOS, Android, Flutter | ID of an existing poll created before post creation. |
| `text` | No | TypeScript, iOS, Android, Flutter | Feed caption or prompt shown with the poll post. |
| `targetType` | Yes | TypeScript, iOS, Android, Flutter | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android, Flutter | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android, Flutter | User mention payload where supported by the platform builder. |
| `productTags` | No | TypeScript, iOS | Products named in the parent post text. Poll choices are not product-tag targets. |

## Create a Poll Post

The examples below create a poll post in a community from an existing `pollId`.


```swift iOS
func createPollPost(
    pollId: String,
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityPollPostBuilder()
    builder.setPollId(pollId)
    builder.setText("Vote for featured product")

    return try await postRepository.createPollPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil,
        productTags: [
            AmityTextProductTag(productId: "prod_001", index: 9, length: 12)
        ]
    )
}
```

```kotlin Android
postRepository.createPollPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    pollId = pollId,
    text = "Vote in this poll"
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  dataType: "poll",
  data: {
    text: "Vote for featured product",
    pollId,
  },
  productTags: [
    { productId: "prod_001", text: "featured product", index: 9, length: 16 },
  ],
});
```

```dart Flutter
final post = await AmitySocialClient.newPostRepository()
    .createPost()
    .targetCommunity(communityId)
    .poll(pollId)
    .text('Vote in this poll')
    .post();
```


**Product tags (SDK API).** A poll post has a text parent and a poll child. TypeScript's generic `createPost({ dataType: "poll", ... })` and iOS `createPollPost` expose text `productTags` for the parent caption. The public Android and Flutter poll creators expose no product-tag field, and a poll child has no attachment-tag input. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging).

## Notes

- The post creation call does not create the poll. It only attaches an existing poll by ID.
- Keep the poll question, answers, answer type, and close time in the poll creation flow.
- Use the post text for feed context or a short prompt; the poll object remains the source of truth for answer options and voting behavior.

## Related Topics

    Create the poll object before publishing a poll post.
    Create a simple feed post without a poll attachment.
    Review post concepts, retrieval, and moderation flows.

---

### [Live Stream Posts (Deprecated)](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/live-stream-post)

> Create legacy live stream posts from an existing stream ID. For new live and co-host experiences, use room posts.

Live stream posts are the legacy feed representation for an existing live stream. The stream itself must be created through the Video SDK first, then its `streamId` can be attached to a post.

  For new live and co-host room experiences, create a room and publish a room post instead. The iOS live stream post API is deprecated in favor of `createRoomPost`.

## When to Use

| Use case | Recommended post type |
| --- | --- |
| Existing legacy live stream integration | Live stream post |
| New live broadcast or co-host room experience | Room post |
| Uploaded video playback | Video post or clip post |

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `streamId` | Yes | ID of the live stream created before post creation |
| `text` | No | Caption text shown with the post |
| `targetType` | Yes | Feed target, usually `community` or `user` |
| `targetId` | Yes | Community ID or user ID for the target feed |
| `metadata` | No | Custom metadata stored with the post where supported |

## Create a Live Stream Post

Create a legacy live stream post only when your product still has an existing stream ID from the older live-stream flow.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  dataType: "liveStream",
  data: {
    streamId,
    text: "Watch this live session",
  },
});
```

```kotlin Android
fun createLegacyLiveStreamPost(streamId: String, communityId: String) {
    postRepository.createLiveStreamPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        streamId = streamId,
        text = "Watch this live session"
    )
        .subscribe(
            { post -> showSuccessMessage(post.getPostId()) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func createLegacyLiveStreamPost(
    streamId: String,
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityLiveStreamPostBuilder(
        streamId: streamId,
        text: "Watch this live session"
    )

    return try await postRepository.createLiveStreamPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```

```dart Flutter
Future<AmityPost> createLegacyLiveStreamPost(
  String streamId,
  String communityId,
) {
  return AmitySocialClient.newPostRepository()
      .createPost()
      .targetCommunity(communityId)
      .liveStream(streamId)
      .text('Watch this live session')
      .post();
}
```


## Platform Notes

- TypeScript creates a legacy live stream post through `PostRepository.createPost()` with `dataType: "liveStream"`.
- Android exposes `AmityPostRepository.createLiveStreamPost()`.
- iOS exposes `AmityPostRepository.createLiveStreamPost()`, but the method is deprecated in favor of `createRoomPost()`.
- Flutter exposes `.liveStream(streamId)` on the public post creation builder.

## Related Topics

    Use room posts for new live and co-host experiences.
    Create posts from uploaded video files.
    Create and manage live streams before posting.

---

### [Clip Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/clip-post)

> Create short-form video posts from an uploaded clip.

Clip posts publish an uploaded clip into a user or community feed. Upload the clip first, then pass the uploaded file ID or clip data into the post creation API.

  Use clip posts for short-form video experiences that need the `clip` post type. Use video posts when you only need the standard uploaded-video post flow.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `clip` or `fileId` | Yes | TypeScript, iOS, Android | Uploaded clip data or clip file ID, depending on SDK |
| `text` | No | TypeScript, iOS, Android | Caption text shown with the post |
| `displayMode` | No | TypeScript, iOS, Android | Clip display mode where supported, such as `fill` or `fit` |
| `isMuted` | No | TypeScript, iOS, Android | Whether playback should start muted where supported |
| `targetType` | Yes | TypeScript, iOS, Android | Feed target, usually `community` or `user` |
| `targetId` | Yes | TypeScript, iOS, Android | Community ID or user ID for the target feed |
| `productTags` | No | iOS | Products named in the parent post text. |
| `attachmentProductTags` | No | TypeScript, iOS | Products shown on the child clip attachment. An `AmityAttachmentProductTags` container keyed by `fileId`. |

**Product tags (SDK API).** A clip post has a text parent and a clip child. iOS accepts both inputs on `createClipPost`; TypeScript accepts `attachmentProductTags` for the child only. The public Android and Flutter clip creators expose neither field, so this page does not promise a post-creation workaround. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging). For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create a Clip Post

Create a clip post from an uploaded clip file or clip data, and include optional display settings where supported.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createClipPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Watch this clip",
  },
  attachments: [
    {
      type: "clip",
      fileId,
      displayMode: "fill",
      isMuted: false,
    },
  ],
});
```

```kotlin Android
fun createClipPost(uploadedClip: AmityClip, communityId: String) {
    postRepository.createClipPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        clip = uploadedClip,
        text = "Watch this clip",
        displayMode = AmityClip.DisplayMode.FILL,
        isMuted = false
    )
        .subscribe(
            { post -> showSuccessMessage(post.getPostId()) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func createClipPost(
    uploadedClip: AmityClipData,
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityClipPostBuilder()
    builder.setClip(uploadedClip)
    builder.setText("Watch this clip")
    builder.setDisplayMode(.fill)
    builder.setIsMuted(false)

    return try await postRepository.createClipPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```


  The current Flutter public post creation builder does not expose a clip post creator. It supports text, image, video, file, poll, live stream, and custom post creation.

## Platform Notes

- TypeScript exposes `PostRepository.createClipPost()` with `attachments: [{ type: "clip", fileId }]`.
- Android exposes `AmityPostRepository.createClipPost()` with an uploaded `AmityClip`.
- iOS exposes `AmityPostRepository.createClipPost()` with `AmityClipPostBuilder` and uploaded `AmityClipData`.
- Flutter does not currently expose a public clip post creation method.

## Related Topics

    Upload video files before creating video-based posts.
    Create standard uploaded-video posts.
    Combine multiple supported media attachments in one post.

---

### [Mixed Media Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/mixed-media-post)

> Create posts that combine multiple uploaded media attachment types where the SDK exposes mixed media creation.

Mixed media posts combine two or more uploaded attachment types in one post, such as images with videos or files with audio. Upload each media item first, then pass the uploaded media objects or file IDs to the mixed media creation API.

TypeScript, Android, and iOS expose mixed media post creation APIs. The current public Flutter post creation builder exposes single attachment-type creators for image, video, and file posts, but it does not expose a mixed media post creator.

    Keep related uploaded media in one post instead of splitting it into separate posts.
    The service derives the post structure from the attachment types; do not set it manually.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `attachments`, uploaded media sets, or file IDs | Yes | TypeScript, iOS, Android | Uploaded media items to combine in one post. Supported attachment types depend on SDK. |
| `text` | No | TypeScript, iOS, Android | Caption text shown with the mixed media post. |
| `targetType` | Yes | TypeScript, iOS, Android | Feed target, usually `community` or `user`. |
| `targetId` | Yes | TypeScript, iOS, Android | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android | Custom metadata stored with the post where supported. |
| `mentionees` | No | TypeScript, iOS, Android | User mention payload where supported by the platform builder. |
| `productTags` | No | iOS | Products named in the parent post text. Text product tags. |
| `attachmentProductTags` | Yes on TypeScript | TypeScript, iOS | Products shown on child attachments. An `AmityAttachmentProductTags` container keyed by `fileId`. |

**Product tags (SDK API).** A mixed-media post has a text parent and one child per attachment. iOS accepts both inputs on `createMixedMediaPost`, both optional. TypeScript accepts `attachmentProductTags` for the children only, and its type declares the field as required: pass an empty `new AmityAttachmentProductTags()` when the post has no product tags. The public Android and Flutter mixed-media creators expose neither field, so this page does not promise a post-creation workaround. UIKit's product-tag UI is a separate surface and may support fewer post types; see [UIKit Product Tagging](/uikit/components/social/product-tagging). For tagging limits and tap-through behavior, see [Product Tagging](/uikit/components/social/posts#product-tagging).

## Create a Mixed Media Post

The examples below combine image and video attachments in a community post. Add audio or file attachments on SDKs that expose those uploaded media object types.


```swift iOS
func createMixedMediaPost(
    uploadedImages: [AmityImageData],
    uploadedVideos: [AmityVideoData],
    communityId: String
) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityMixedMediaPostBuilder()
    builder.setText("Photos and video from today")
    builder.setImages(uploadedImages)
    builder.setVideos(uploadedVideos)

    return try await postRepository.createMixedMediaPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil
    )
}
```

```kotlin Android
fun createMixedMediaPost(
    uploadedImages: Set<AmityImage>,
    uploadedVideos: Set<AmityVideo>,
    communityId: String
) {
    val attachments = mutableSetOf<AmityAttachment>()
    attachments.addAll(uploadedImages)
    attachments.addAll(uploadedVideos)

    postRepository.createMixedAttachmentPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        attachments = attachments,
        text = "Photos and video from today"
    )
        .subscribe({ post ->
            showSuccessMessage(post.getPostId())
        }, { error ->
            handleGeneralError(error)
        })
}
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  data: {
    text: "Photos and video from today",
  },
  attachments: [
    {
      type: "image",
      fileId: imageFileId,
    },
    {
      type: "video",
      fileId: videoFileId,
    },
  ],
});
```


## Flutter Support

Flutter's current public post creation builder exposes `.image(...)`, `.video(...)`, and `.file(...)` for single attachment-type posts. It does not expose a public mixed media builder that accepts multiple attachment types in one post creation call.

Create a single supported post type from Flutter, or create mixed media posts from a platform/backend layer that exposes mixed attachment creation.

Mixed-structure posts can still be **read** from Flutter: pass `includeMixedStructure: true` to [`semanticSearchPosts()`](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-post). The limitation is on creation only.

## Notes

- TypeScript accepts mixed attachments in `PostRepository.createPost`.
- Android accepts a `Set<AmityAttachment>` through `createMixedAttachmentPost`.
- iOS accepts uploaded media through `AmityMixedMediaPostBuilder`.
- Do not pass `structureType` in the create request. The service derives it from the attachment composition.

## Related Topics

    Create image-only posts from uploaded images.
    Create video-only posts from uploaded videos.
    Create file-only posts from uploaded files.

---

### [Room Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/room-post)

> Create feed posts that reference an existing live room.

Room posts publish an existing room into a user or community feed. Create the room first through the room or video APIs, then pass its `roomId` to the post creation API. A room post has a text parent and a child room post; product tagging is attached to that post child, not to the room entity itself.

  Room posts are the current path for new live and co-host room experiences. This page focuses only on creating the feed post from an existing `roomId`.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `roomId` | Yes | TypeScript, iOS, Android | ID of the room to attach to the post |
| `text` | No | TypeScript, iOS, Android | Caption text shown on the parent post |
| `title` | No | TypeScript, iOS, Android | Optional title stored in the room child post data |
| `targetType` | Yes | TypeScript, iOS, Android | Feed target, usually `community` or `user` |
| `targetId` | Yes | TypeScript, iOS, Android | Community ID or user ID for the target feed |
| `metadata` | No | TypeScript, iOS, Android | Custom metadata stored with the post where supported |
| `productTags` | No | TypeScript, iOS, Android | Media products available on the child room post; each tag carries `productId` only |
| `pinnedProductId` | No | TypeScript, iOS, Android | Product featured on the child at creation. Must also appear in `productTags` |

**Product tags (SDK API).** Room posts take **media** product tags, which carry a `productId` and nothing else. The positional fields `text`, `index`, and `length` belong to text product tags and do not apply here. `createRoomPost` returns the parent post; pinning, unpinning, and later tag updates target its **child** room post. These are SDK capabilities; UIKit's product-tag UI is a separate surface and may support fewer post types. See [UIKit Product Tagging](/uikit/components/social/product-tagging) for UI coverage and [Livestream Product Tagging](/social-plus-sdk/video-new/broadcasting/product-tagging) for the lifecycle operations.

## Create a Room Post

Create a room post after the room already exists, then use the returned post in the target user or community feed.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createRoomPost({
  targetType: "community",
  targetId: communityId,
  data: {
    roomId,
    text: "Join this live room",
    title: "Live room",
  },
  productTags: [{ productId: "prod_001" }],
  pinnedProductId: "prod_001",
});
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.producttag.AmityProductTag

fun createRoomPost(roomId: String, communityId: String) {
    postRepository.createRoomPost(
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        roomId = roomId,
        text = "Join this live room",
        title = "Live room",
        productTags = listOf(AmityProductTag.Media(productId = "prod_001")),
        pinnedProductId = "prod_001"
    )
        .subscribe(
            { post -> showSuccessMessage(post.getPostId()) },
            { error -> handleGeneralError(error) }
        )
}
```

```swift iOS
func createRoomPost(roomId: String, communityId: String) async throws -> AmityPost {
    let postRepository = AmityPostRepository()
    let builder = AmityRoomPostBuilder(
        roomId: roomId,
        text: "Join this live room"
    )
    builder.setTitle("Live room")

    return try await postRepository.createRoomPost(
        builder,
        targetId: communityId,
        targetType: .community,
        metadata: nil,
        mentionees: nil,
        productTags: [AmityMediaProductTag(productId: "prod_001")],
        pinnedProductId: "prod_001"
    )
}
```


  The current Flutter public post creation builder does not expose a room post creator. Use another supported SDK or backend flow when your product needs to publish room posts from Flutter.

## Platform Notes

- TypeScript exposes `PostRepository.createRoomPost()`.
- Android exposes `AmityPostRepository.createRoomPost()`.
- iOS exposes `AmityPostRepository.createRoomPost()` with `AmityRoomPostBuilder`.
- Flutter does not currently expose a public room post creation method.

## Related Topics

    Review the deprecated legacy live stream post path.
    Create posts from uploaded video files.
    Review posts, comments, reactions, and sharing concepts.

---

### [Event Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/creation/event-post)

> Publish a scheduled event as a post so it renders as an event card in feeds and community timelines.

An event post attaches an existing event to a post. The post carries the author's text; the event supplies the card that renders inside the feed. Tapping the card opens the event detail page instead of the post detail page, so the event stays the primary surface.

Create the event first with the Event Repository. See [Create Event](/social-plus-sdk/social/events/create-event). The event post references the returned `eventId`.

    An event post points to an `eventId` returned by event creation. The reference is immutable — a post can never be repointed at a different event.
    Publish to a user feed or a community feed. Private-community events are locked to their own community server-side.

## Data Type

Event posts use a dedicated content type:

| Field | Value |
| --- | --- |
| `dataType` | `"event"` |
| `structureType` | `"event"` |
| `data.eventId` | Required — the event this post is about |
| `data.title` | Optional — prefilled from the event's `title`, editable |
| `data.text` | Optional — prefilled from the event's `description`, editable |

Publishing an event post with both `title` and `text` blank is valid — the event card is the payload.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `eventId` | Yes | TypeScript, iOS, Android | ID of an existing event. The post cannot be created without it. |
| `title` | No | TypeScript, iOS, Android | Post title. Prefilled from `event.title` in composer, but any string (including empty) is accepted. Android: `String?`, dropped from the payload when blank. |
| `text` | No | TypeScript, iOS, Android | Post body. Prefilled from `event.description` in composer, but any string (including empty) is accepted. Android: `String`, defaults to `""`. |
| `targetType` | Yes | TypeScript, iOS, Android | Feed target, `community` or `user`. Constrained by the event's origin — see [Target Rules](#target-rules). |
| `targetId` | Yes | TypeScript, iOS, Android | Community ID or user ID for the target feed. |
| `metadata` | No | TypeScript, iOS, Android | Custom metadata stored with the post where supported. |
| `mentionees` | No | iOS, TypeScript | User mention payload where supported by the platform builder. |
| `mentionUserIds` | No | Android | `Set<String>` of user IDs to mention. |
| `hashtags` | No | Android | Hashtags stored with the post. |
| `tags` | No | Android | Post tags. |

The event-post SDK surface is available in TypeScript, iOS, and Android. Flutter and React Native do not expose these event-post APIs.

## Create an Event Post

Creating an event post publishes the post and returns the created post once the server has accepted it. `eventId` is required; `title` and `text` are the author's own copy and may both be empty.


```swift iOS
let postRepository = AmityPostRepository()
// `eventId` (required, immutable) and `text` are init parameters; only `title` has a setter.
let builder = AmityEventPostBuilder(eventId: eventId, text: "Come say hi")
builder.setTitle("Summer Meetup")

let post = try await postRepository.createEventPost(
    builder,
    targetId: communityId,
    targetType: .community,
    metadata: nil,
    mentionees: nil
)
```

```kotlin Android
postRepository.createEventPost(
    targetType = AmityPost.TargetType.COMMUNITY,
    targetId = communityId,
    eventId = eventId,
    title = "Summer Meetup",
    text = "Come say hi"
)
    .subscribe({ post ->
        showSuccessMessage(post.getPostId())
    }, { error ->
        handleGeneralError(error)
    })
```

```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: post } = await PostRepository.createPost({
  targetType: "community",
  targetId: communityId,
  dataType: "event",
  data: {
    eventId,
    title: "Summer Meetup",
    text: "Come say hi",
  },
});
```


## Target Rules

The target is constrained by the event's origin:

| Event origin | Allowed targets | Enforcement |
| --- | --- | --- |
| Public community | The event's own community, any community the user can post in, or the user's own feed | Client picks; server accepts any valid target |
| Private community | The event's own community only | Server-enforced — a `400` is returned for any other target |
| User-hosted (`originType: "user"`) | Any community the user can post in, or the user's own feed | Client picks; server accepts any valid target |

The private-community lock is a **server-side** rule. If your app builds a custom target picker, honour the same rule client-side to avoid surprising `400` errors after the user has already drafted a post.

## Rejected Combinations

The backend rejects the following with `400`:

| Case | Reason |
| --- | --- |
| Missing `data.eventId` | Required for `dataType: "event"`. |
| Disallowed target | Private-community event posted anywhere other than that community. |
| Media attachment | Image, video, file, audio, or clip children are not permitted — the event card is the visual. |
| Product tags | `productTags` or `attachmentProductTags` are not permitted on event posts. |
| Changing `data.eventId` | The event reference is immutable. Delete the post and create a new one to point at a different event. |

## Editing an Event Post

Editing updates `data.title` and `data.text` only. The event itself is never changed by a post edit, and sibling posts referencing the same event are unaffected.


```swift iOS
// `eventId` is required by the builder's init but is never sent on update (immutable).
let builder = AmityEventPostBuilder(eventId: eventId, text: "Updated body")
builder.setTitle("Updated title")

try await postRepository.editPost(withId: postId, builder: builder)
```

```kotlin Android
postRepository.editPost(postId)
    .title("Updated title")
    .text("Updated body")
    .build()
    .apply()
    .subscribe()
```

```typescript TypeScript
await PostRepository.editPost(postId, {
  data: { title: "Updated title", text: "Updated body" },
});
```


Do not send `data.eventId` on edit. It is immutable — any request that changes it is rejected with `400`.

## Resolve the Event from a Post

There are two ways to resolve the event — pick one: a **snapshot** (`post.getEvent()`) that returns the event cached with the post, or a **live observer** (`EventRepository.getEvent`) that keeps the card in sync with changes.

| Accessor | Role | Availability |
| --- | --- | --- |
| `post.getEvent()` | Synchronous snapshot from the sibling `events[]` collection cached with the post response. No network call, no subscription. Not a live observable. | ✅ **Shipped on iOS.** 🚧 Planned on other platforms. Android will surface it via the sealed `AmityPost.Data.EVENT` variant rather than a top-level method. |
| `EventRepository.getEvent(eventId)` | Live observer. Subscribe while the card is on screen; unsubscribe on scroll-off or unmount. | ✅ Shipped on iOS, TypeScript, and Android. |

On **iOS**, `post.getEvent()` is the recommended path — it's shipped, and the SDK links the event to the post during serialization, so it returns the event directly, with no repository call and without inspecting child posts yourself (this is what AmityUIKit does).

On **Android**, resolve the event through the repository instead: read the `eventId` from the **child** post — the parent post's data is `TEXT` and the `EVENT` data sits on the child — then observe it with `EventRepository.getEvent(eventId)`.


```swift iOS
// Shipped on iOS — the event is linked to the post during serialization.
if let event = post.getEvent() {
    render(event)
}
```

```kotlin Android
// The event reference lives on the child post, not the parent.
val eventData = post.getChildren()
    .firstOrNull { it.getData() is AmityPost.Data.EVENT }
    ?.getData() as? AmityPost.Data.EVENT

eventData?.let { data ->
    AmitySocialClient.newEventRepository()
        .getEvent(data.getEventId())
        .subscribeOn(Schedulers.io())
        .observeOn(AndroidSchedulers.mainThread())
        .subscribe(
            { event -> render(event) },
            { /* event deleted or unavailable — render the unavailable card */ }
        )
}
```

```typescript TypeScript
import { EventRepository } from "@amityco/ts-sdk";

if (post.eventId) {
  const stopObserving = EventRepository.getEvent(post.eventId, ({ data: event }) => {
    if (event) render(event);
  });

  // Call stopObserving when the event card leaves the screen.
}
```


On iOS, `post.getEvent()` returns `nil` when the post is not an event post, or when the event entry is not in the payload (for example, the event was deleted).

On Android, `getEvent(eventId)` is a live stream that emits again whenever the event changes. A deleted or unavailable event surfaces as an **error on the `Flowable`**, not a null emission — handle it in the error callback. A **cancelled** event still resolves normally and must be treated as deleted by the consumer; the SDK does not normalise it.

## Query Event Posts

Event posts are **excluded from the default results** of `v3` and `v4` post queries so that older clients never receive a `dataType` they cannot render. Reads for event-aware clients must use **`GET /api/v5/posts`**.

| Platform | Reading event posts |
| --- | --- |
| Android | `getPosts()` already targets `GET /api/v5/posts`, so event posts are returned without any extra filter. There is no `dataTypes` parameter to set. |
| TypeScript | Pass `dataTypes: ["event"]` when reading through a `v3` / `v4` path. |

To include event posts on any version, filter explicitly:


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const stopObserving = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    dataTypes: ["event"],
  },
  ({ data }) => {
    renderResults(data);
  }
);
```


An unfiltered `v4` feed query will not return an event post you just created — the exclusion gate hides it. Either upgrade the read to `v5` or add `dataTypes=event` to the query.

## Related Topics

    Create the event that an event post will reference.
    Event model, statuses, and RSVP APIs.
    Post targets, structure types, and platform APIs.

---

### [Get Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/retrieval/get-post)

> Retrieve one post as a live object, or fetch a known set of post IDs where the SDK supports batch lookup.

Use post retrieval when your app already knows the post ID. Single-post retrieval returns a live object or stream on every SDK. Batch lookup is available on TypeScript, iOS, and Android.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Single post | `postId` | Yes | Unique post ID to observe or fetch. |
| Multiple posts by ID | `postIds` | Yes | List or set of post IDs to fetch on TypeScript, iOS, and Android. |

## Single Post

Observe a single post when a detail screen should update as post data, counters, or moderation state changes.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getPost(
  postId,
  ({ data: post, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (post) {
      renderResults(post);
    }
  },
);
```

```kotlin Android
postRepository.getPost(postId)
    .subscribe(
        { post -> showSuccessMessage(post.getPostId()) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let postRepository = AmityPostRepository()
var token: AmityNotificationToken?

token = postRepository.getPost(withId: "post-id").observe { liveObject, error in
    guard let post = liveObject.snapshot else { return }
    showSuccessMessage(post.postId)
}
```

```dart Flutter
final subscription = AmitySocialClient.newPostRepository()
    .live
    .getPost(postId)
    .listen((AmityPost post) {
      final id = post.postId;
    });

await subscription.cancel();
```


## Multiple Posts by ID

Fetch a known set of post IDs when your app already has exact IDs and does not need a paged feed query.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: posts } = await PostRepository.getPostByIds([
  postId,
  "another-post-id",
]);
```

```kotlin Android
postRepository.getPostByIds(setOf(postId, "another-post-id"))
    .subscribe(
        { posts -> showSuccessMessage(posts.size) },
        { error -> handleGeneralError(error) }
    )
```

```swift iOS
let postRepository = AmityPostRepository()
var token: AmityNotificationToken?

token = postRepository.getPosts(postIds: ["post-id", "another-post-id"]).observe { collection, error in
    showSuccessMessage(collection.snapshots.count)
}
```


  The current Flutter public post repository exposes single-post retrieval through `live.getPost(postId)` and the deprecated `getPost(postId)` future, but it does not expose a public batch get-by-IDs method.

## Notes

- Keep the unsubscriber or notification token so you can dispose the live object when the screen is destroyed.
- Use query APIs when you need a feed, pagination, filtering, or real-time collection updates.
- Batch lookup skips invalid IDs on iOS collection results; handle an empty collection as a valid outcome.

## Related Topics

    Query posts by feed target, post type, review status, or tags.
    Render post data and child media safely.
    Review post structure and post data types.

---

### [Query Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/retrieval/query-posts)

> Query live post collections by target, data type, review status, deletion state, tags, and pagination options.

Use post queries to build user feeds, community feeds, review queues, and media galleries. Query results are paginated live collections on the client SDKs.

## Parameters

| Operation | Parameter | Platforms | Required | Description |
| --- | --- | --- | --- | --- |
| Query posts | Target filter | TypeScript, iOS, Android, Flutter | Context-dependent | Target type and target ID for user or community feeds. |
| Query posts | Data type filter | TypeScript, iOS, Android, Flutter | No | Post content types to include, such as image, video, file, poll, or custom. |
| Query posts | Deleted-state filter | TypeScript, iOS, Android, Flutter | No | Include or exclude deleted posts where supported. |
| Query posts | Review/feed status | TypeScript, iOS, Android, Flutter | No | Published, reviewing, or declined state filters where exposed by the SDK. |
| Query posts | `tags` | TypeScript, iOS, Android, Flutter | No | Tags to match when building tag-filtered feeds. |
| Query posts | `includeMixedStructure` | TypeScript, iOS, Android; Flutter semantic search only | No | Include mixed-structure posts alongside media-type filters where supported. |
| Query posts | `untilAt` | TypeScript, iOS, Android | No | Time boundary for pagination where supported. |
| Android cache invalidation | `invalidateCache` | Android | No | Android-only option to skip stale paging cache for a query. |

## Common Filters

| Filter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Target | `targetType`, `targetId` | `targetType`, `targetId` | `.targetUser()`, `.targetCommunity()` | `.targetUser()`, `.targetCommunity()` |
| Data type | `dataTypes` | `dataTypes` | `.dataTypes()` | `.types()` |
| Include deleted | `includeDeleted` | `deletedOption` | `.includeDeleted()` | `.includeDeleted()` |
| Review/feed status | `feedType` with published or reviewing | `feedType` | `.reviewStatus()` | `.feedType()` |
| Tags | `tags` | `tags` | `.tags()` | `.tags()` |
| Mixed media matching | `includeMixedStructure` | `includeMixedStructure` | `.includeMixedStructure()` | Not exposed on `getPosts()`; available on [`semanticSearchPosts()`](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-post) |
| Time boundary | `untilAt` | `untilAt` | `.untilAt()` | Not exposed in the current public builder |
| Invalidate cache | Not exposed | Not exposed | `.invalidateCache()` | Not exposed |

## Data Type Filters

| Platform | Query data type values |
| --- | --- |
| TypeScript | Non-text post data types through `dataTypes`, including image, video, file, poll, live stream, audio, clip, room, and custom strings |
| iOS | String `dataTypes`; deprecated `filterPostTypes` exists but new docs should use `dataTypes` |
| Android | `AmityPost.DataType`, including text, image, video, file, poll, live stream, audio, clip, room, and custom |
| Flutter | `AmityDataType.TEXT`, `IMAGE`, `VIDEO`, `FILE`, `LIVESTREAM`, `POLL`, and `CUSTOM`; no public audio, clip, or room enum values |

## Query a Community Feed

Query a community feed with the filters your UI needs, then keep the returned live collection or stream subscription while the feed is visible.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

let loadNextPage: (() => void) | undefined;
let canLoadMore = false;

const unsubscribe = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    dataTypes: ["image", "video", "poll"],
    includeDeleted: false,
    feedType: "published",
    sortBy: "lastCreated",
    tags: ["product", "promotion"],
    includeMixedStructure: true,
  },
  ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);
    loadNextPage = onNextPage;
    canLoadMore = hasNextPage;
  },
);

function loadMorePosts() {
  if (canLoadMore) {
    loadNextPage?.();
  }
}
```

```swift iOS
let postRepository = AmityPostRepository()
var token: AmityNotificationToken?

let options = AmityPostQueryOptions(
    targetType: .community,
    targetId: communityId,
    sortBy: .lastCreated,
    deletedOption: .notDeleted,
    dataTypes: Set(["image", "video", "poll"]),
    feedType: .published,
    tags: ["product", "promotion"],
    includeMixedStructure: true
)

token = postRepository.getPosts(options).observe { collection, error in
    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
postRepository
    .getPosts()
    .targetCommunity(communityId = communityId)
    .dataTypes(
        dataTypes = listOf(
            AmityPost.DataType.IMAGE,
            AmityPost.DataType.VIDEO,
            AmityPost.DataType.POLL
        )
    )
    .includeDeleted(includeDeleted = false)
    .reviewStatus(AmityReviewStatus.PUBLISHED)
    .tags(tags = listOf("product", "promotion"))
    .includeMixedStructure(includeMixedStructure = true)
    .sortBy(sortOption = AmityCommunityFeedSortOption.LAST_CREATED)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final postLiveCollection = AmitySocialClient.newPostRepository()
    .getPosts()
    .targetCommunity(communityId)
    .types([
      AmityDataType.IMAGE,
      AmityDataType.VIDEO,
      AmityDataType.POLL,
    ])
    .includeDeleted(false)
    .feedType(AmityFeedType.PUBLISHED)
    .tags(['product', 'promotion'])
    .getLiveCollection(pageSize: 20);

postLiveCollection.getStreamController().stream.listen((posts) {
  final count = posts.length;
});

await postLiveCollection.loadNext();

if (postLiveCollection.hasNextPage()) {
  await postLiveCollection.loadNext();
}
```


## Android Cache Invalidation

Android exposes `invalidateCache(true)` on post query builders. Use it when a screen should skip stale paging cache on entry, such as after pull-to-refresh.


```kotlin Android
postRepository
    .getPosts()
    .targetCommunity(communityId = communityId)
    .includeDeleted(includeDeleted = false)
    .invalidateCache(invalidateCache = true)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```


## Time Boundaries

`untilAt` is available on TypeScript, iOS, and Android query surfaces. It is a time boundary for pagination. For newest-first sorting, older posts beyond the boundary are excluded; for oldest-first sorting, newer posts beyond the boundary are excluded.


```kotlin Android
val oneWeekAgo = DateTime.now().minusDays(7)

postRepository
    .getPosts()
    .targetCommunity(communityId = communityId)
    .untilAt(oneWeekAgo)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```


## Notes

- For media galleries, set a data type filter and enable mixed media matching where the SDK supports it.
- For moderation review queues, use review/feed status filters and apply your app's permission checks before showing restricted states.
- Always dispose live collection subscriptions, notification tokens, or stream subscriptions when the screen is destroyed.

## Related Topics

    Retrieve one known post or a known set of post IDs.
    Render returned post content by type.
    Review approval and declined-post flows.

---

### [Viewing Post Content](https://learn.social.plus/social-plus-sdk/social/content-management/posts/retrieval/viewing-content)

> Render post text, child media, polls, live stream data, room data, and local counts from returned SDK post objects.

Posts can contain text directly and can also reference child posts for media attachments. Query and get APIs return composed post objects where each SDK exposes helpers for reading the post data.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Inspect post content | Post object | Yes | TypeScript, iOS, Android, Flutter | Post returned from a get or query API. Use SDK helper methods or typed data accessors on that object. |

## Parent and Child Posts

Media posts commonly use a parent-child shape:

- The parent post carries the main feed item and text.
- Child posts carry individual media attachments such as images, videos, and files.
- SDK helpers expose composed children where the platform supports them.


```typescript TypeScript
function inspectPostContent(post: Amity.Post) {
  const childCount = post.childrenPosts.length;
  const localCommentCount = post.localCommentCount;

  const image = post.getImageInfo();
  const video = post.getVideoInfo();
  const videoThumbnail = post.getVideoThumbnailInfo();
  const file = post.getFileInfo();
  const poll = post.getPollInfo();
  const audio = post.getAudioInfo();
  const clip = post.getClipInfo();
  const room = post.getRoomInfo();

  renderResults({
    childCount,
    localCommentCount,
    image,
    video,
    videoThumbnail,
    file,
    poll,
    audio,
    clip,
    room,
  });
}
```

```swift iOS
func inspectPostContent(_ post: AmityPost) {
    let childCount = post.childrenPosts.count
    let localCommentCount = post.localCommentCount

    let image = post.getImageInfo()
    let video = post.getVideoInfo()
    let videoThumbnail = post.getVideoThumbnailInfo()
    let file = post.getFileInfo()
    let poll = post.getPollInfo()
    let audio = post.getAudioInfo()
    let clip = post.getClipInfo()
    let room = post.getRoomInfo()

    showSuccessMessage([
        childCount,
        localCommentCount,
        image?.fileId,
        video?.fileId,
        videoThumbnail?.fileId,
        file?.fileId,
        poll?.pollId,
        audio?.fileId,
        clip?.fileId,
        room?.roomId
    ])
}
```

```kotlin Android
fun inspectPostContent(post: AmityPost) {
    val children = post.getChildren()
    val localCommentCount = post.getLocalCommentCount()

    when (val data = post.getData()) {
        is AmityPost.Data.TEXT -> showSuccessMessage(data.getText())
        is AmityPost.Data.IMAGE -> showSuccessMessage(data.getImage() ?: "")
        is AmityPost.Data.FILE -> showSuccessMessage(data.getFile() ?: "")
        is AmityPost.Data.AUDIO -> showSuccessMessage(data.getAudio() ?: "")
        is AmityPost.Data.VIDEO -> showSuccessMessage(data.getThumbnailImage() ?: "")
        is AmityPost.Data.CLIP -> showSuccessMessage(data.getThumbnailImage() ?: "")
        is AmityPost.Data.LIVE_STREAM -> showSuccessMessage(data.getPostId())
        is AmityPost.Data.ROOM -> showSuccessMessage(data.getRoom() ?: "")
        is AmityPost.Data.POLL -> showSuccessMessage(data.getPollId())
        is AmityPost.Data.CUSTOM -> showSuccessMessage(data.getDataType())
    }

    showSuccessMessage(children.size + localCommentCount)
}
```

```dart Flutter
void inspectPostContent(AmityPost post) {
  final children = post.children ?? <AmityPost>[];
  final commentCount = post.commentCount ?? 0;
  final data = post.data;

  if (data is TextData) {
    final text = data.text;
  } else if (data is ImageData) {
    final imageUrl = data.getUrl(AmityImageSize.MEDIUM);
  } else if (data is FileData) {
    final file = data.file;
  } else if (data is VideoData) {
    final thumbnail = data.thumbnail;
  } else if (data is LiveStreamData) {
    final streamId = data.streamId;
  } else if (data is PollData) {
    final pollId = data.pollId;
  } else if (data is CustomData) {
    final rawData = data.rawData;
  }

  final childCount = children.length;
  final total = childCount + commentCount;
}
```


## Platform Notes

| Platform | Content helpers |
| --- | --- |
| TypeScript | Linked post helpers include `childrenPosts`, `getImageInfo()`, `getVideoInfo()`, `getVideoThumbnailInfo()`, `getFileInfo()`, `getPollInfo()`, `getAudioInfo()`, `getClipInfo()`, and `getRoomInfo()` |
| iOS | `AmityPost` exposes `childrenPosts` plus helper methods for image, video, thumbnail, file, poll, audio, clip, and room data |
| Android | `AmityPost.getData()` returns a sealed data type; inspect it with `when` and use data-specific methods |
| Flutter | Current public model exposes text, image, video, file, live stream, poll, and custom data classes; audio, clip, and room post data classes are not exposed in the current public model |

## Rendering Guidance

- Prefer SDK helper methods over reading raw data maps when helpers exist.
- Handle unknown or custom data types gracefully; custom post types are application-defined.
- For video and clip playback, read the media object first and choose a URL or resolution your UI can render.
- For room posts, check room status before presenting live or recorded playback UI.
- Use `localCommentCount` where exposed when your UI should include replies in the visible comment count. With comment approval (iOS/TS), this is deprecated in favor of `getLocalCommentCount(includePending:)` — it equals `getLocalCommentCount(includePending: true)`; pass `includePending: false` for the shared, approved-only count.

## Related Topics

    Query live post collections before rendering
    Create posts with multiple media attachment types
    Create room posts for live room experiences

---

### [Edit Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/moderation/edit-post)

> Update existing posts with the public SDK edit APIs and platform-specific editor surfaces.

Use post editing when your app needs to update content that already exists. The SDKs update the post by ID; permission checks are enforced by the backend for post owners, moderators, and admins according to your app configuration.

## Platform Support

| Platform | Public edit surface | Notes |
| --- | --- | --- |
| TypeScript | `PostRepository.editPost(postId, patch)` | Patch can include `data`, `metadata`, `tags`, `mentionees`, `hashtags`, `attachments`, `links`, `productTags`, and `attachmentProductTags` |
| iOS | `postRepository.editPost(withId:builder:...)` | Use the builder type that matches the original post content type |
| Android | `postRepository.editPost(postId).build().apply()` | Builder supports text, title, attachments, metadata, mentions, hashtags, tags, links, product tags, and tagged attachment products |
| Flutter | `post.edit().build().update()` | Editor is available on an `AmityPost`; it supports text, image, file, video, custom data, metadata, and mentioned users |

  The current Flutter public editor does not expose link preview replacement or product-tag editing. Keep those updates on platforms that expose the fields.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Update a post | `postId` | Yes | Post ID to update. Flutter updates through a loaded `AmityPost` object. |
| Update a post | Text/data patch | Usually | Updated text or post data supported by the original post type. |
| Update a post | Attachments/media | No | Complete attachment set to keep where the SDK exposes attachment editing. |
| Update a post | `metadata`, `tags`, mentions, links | No | Optional fields exposed by the target SDK edit surface. |

## Update a Post

Load or know the post ID, then apply the platform-specific editor or patch API for the fields your product allows users to change.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: updatedPost } = await PostRepository.editPost(postId, {
  data: {
    text: "Updated caption with https://www.amity.co",
  },
  attachments: [
    {
      type: "image",
      fileId: imageFileId,
    },
  ],
  metadata: {
    editedFrom: "profile",
  },
  tags: ["release-note"],
  links: [
    {
      url: "https://www.amity.co",
      index: 21,
      length: 20,
      renderPreview: true,
      domain: "www.amity.co",
    },
  ],
});

renderResults(updatedPost);
```

```swift iOS
let builder = AmityTextPostBuilder()
builder.setText("Updated caption")

let updatedPost = try await postRepository.editPost(
    withId: "post-id",
    builder: builder,
    metadata: ["editedFrom": "profile"],
    mentionees: nil,
    hashtags: nil,
    links: nil,
    productTags: nil,
    attachmentProductTags: nil
)

showSuccessMessage(updatedPost.postId)
```

```kotlin Android
val metadata = JsonObject().apply {
    addProperty("editedFrom", "profile")
}

postRepository.editPost(postId = postId)
    .text(text = "Updated caption")
    .metadata(metadata)
    .tags(listOf("release-note"))
    .build()
    .apply()
    .subscribe(
        { showSuccessMessage(postId) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final post = await AmitySocialClient.newPostRepository().getPost(postId);

await post
    .edit()
    .text('Updated caption')
    .metadata({'editedFrom': 'profile'})
    .build()
    .update();
```


## Editing Media

On platforms with attachment editing, send the complete attachment set you want the post to keep. If you omit an existing image, file, or video from the update payload, that attachment should be treated as removed from the edited post.

| Platform | Media edit pattern |
| --- | --- |
| TypeScript | Send `attachments` with `{ type, fileId }` entries |
| iOS | Rebuild the post with the matching media builder, such as `AmityImagePostBuilder`, `AmityFilePostBuilder`, or `AmityVideoPostBuilder` |
| Android | Pass media objects through `.attachments(...)` on the edit builder |
| Flutter | Use `.image(...)`, `.file(...)`, or `.video(...)` on the loaded post editor |

## Notes

- Keep the edit operation tied to the content type that was originally created.
- Preserve existing attachments by reading the current post first and including the items that should remain.
- After a successful edit, use the returned or live-updated post to refresh UI state such as edited timestamps, tags, metadata, and attachment lists.

## Related Topics

    Load the current post before editing.
    Remove posts through soft or hard deletion.
    Render the updated post content.

---

### [Delete Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/moderation/delete-post)

> Delete posts through the public SDK soft-delete and hard-delete surfaces.

Use post deletion when a user or moderator needs to remove a post by ID. Deletion permissions are enforced by the backend according to the actor, target community, and your app settings.

## Platform Support

| Platform | Soft delete | Hard delete | Public SDK method |
| --- | --- | --- | --- |
| TypeScript | Yes | Yes | `PostRepository.softDeletePost(postId)` and `PostRepository.hardDeletePost(postId)` |
| iOS | Yes | Yes | `softDeletePost(withId:parentId:)` and `hardDeletePost(withId:parentId:)` |
| Android | Yes | Yes | `softDeletePost(postId)` and `hardDeletePost(postId)` |
| Flutter | Yes | No verified hard-delete flag | `deletePost(postId:)` or `post.delete()` |

  Do not rely on Flutter's `hardDelete` argument for hard deletion in the current public SDK. The public delete path does not pass a hard-delete flag to the request.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Delete a post | `postId` | Yes | Post ID to soft delete or hard delete. |
| Delete a post | Delete type | Yes | Choose soft delete or hard delete where the target SDK exposes both behaviors. |
| Delete a post | `parentId` | No | Optional iOS parent post ID for child-post deletion state updates. |

## Delete a Post

Delete by post ID, choosing soft delete or hard delete only on SDKs that expose the desired behavior.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const softDeletedPost = await PostRepository.softDeletePost(postId);
const hardDeletedPost = await PostRepository.hardDeletePost(postId);

renderResults([softDeletedPost, hardDeletedPost]);
```

```swift iOS
try await postRepository.softDeletePost(withId: "post-id", parentId: nil)
try await postRepository.hardDeletePost(withId: "post-id", parentId: nil)

showSuccessMessage()
```

```kotlin Android
postRepository.softDeletePost(postId = postId)
    .subscribe(
        { showSuccessMessage(postId) },
        { error -> handleGeneralError(error) }
    )

postRepository.hardDeletePost(postId = postId)
    .subscribe(
        { showSuccessMessage(postId) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
await AmitySocialClient.newPostRepository().deletePost(postId: postId);
```


## Parent Post IDs

iOS delete methods accept an optional `parentId`. Pass `nil` for top-level posts. If you are deleting a child post and your app already has its parent post ID, pass that parent ID so local post state can be updated correctly.

## Notes

- Use soft delete when your app needs the deleted state to remain observable.
- Use hard delete only when your app intentionally wants the object invalidated or permanently removed on SDKs that expose the hard-delete path.
- Refresh or remove local UI items after deletion; live collections usually update, but optimistic UI should still handle delete failures.

## Related Topics

    Update existing post content.
    Approve or decline posts in review queues.
    Query posts with deleted-state filters.

---

### [Pinned Posts](https://learn.social.plus/social-plus-sdk/social/content-management/posts/moderation/pin-post)

> Read community and global pinned posts through the public SDK live collection APIs.

Use pinned-post queries to display posts that were already pinned outside the client SDK. The SDK surfaces in this page are read-only retrieval APIs.

## Platform Support

| Platform | Community pinned posts | Global pinned posts | Placement values |
| --- | --- | --- | --- |
| TypeScript | `PostRepository.getPinnedPosts(...)` | `PostRepository.getGlobalPinnedPosts(...)` | String placement such as `default` or `announcement`; `null` fetches all community placements |
| iOS | `postRepository.getPinnedPosts(...)` | `postRepository.getGlobalPinnedPosts(...)` | `AmityPinPlacement.default.rawValue` or `AmityPinPlacement.announcement.rawValue` |
| Android | `postRepository.getPinnedPosts(...)` | `postRepository.getGlobalPinnedPosts(...)` | `AmityPinnedPost.PinPlacement.DEFAULT.value` or `ANNOUNCEMENT.value` |
| Flutter | `AmitySocialClient.newPostRepository().getPinnedPosts(...)` | `getGlobalPinnedPosts()` | String placement, or `PinPlacement.DEFAULT.value` / `ANNOUNCEMENT.value` |

  Current client SDKs retrieve pinned posts. Pinning and unpinning are not exposed as public client SDK operations in this surface.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Community pinned posts | `communityId` | Yes | All | Community whose pinned posts should be retrieved. |
| Community pinned posts | `placement` | No | All | Placement such as default or announcement. |
| Community pinned posts | `sortBy` | No | TypeScript, iOS | Sort order. Not accepted by the current Android call. Flutter exposes `sortByOptions`, but the request builder does not forward it — do not depend on it. |
| Community pinned posts | `includeMixedStructure` | No | TypeScript, iOS, Android | Include mixed-structure posts. Not exposed on the current Flutter public method. |
| Global pinned posts | `includeMixedStructure` | No | TypeScript, iOS, Android | Include mixed-structure posts in global pinned results. Not exposed on the current Flutter public method. |

## Community Pinned Posts

Query community pinned posts for a specific community and optional placement such as an announcement area.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getPinnedPosts(
  {
    communityId,
    placement: "announcement",
    sortBy: "lastPinned",
    includeMixedStructure: true,
  },
  ({ data: pinnedPosts, loading, error, onNextPage, hasNextPage }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(pinnedPosts);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);
```

```swift iOS
token = postRepository
    .getPinnedPosts(
        communityId: communityId,
        placement: AmityPinPlacement.announcement.rawValue,
        sortBy: .lastPinned,
        includeMixedStructure: true
    )
    .observe { collection, error in
        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
postRepository.getPinnedPosts(
    communityId = communityId,
    placement = AmityPinnedPost.PinPlacement.ANNOUNCEMENT.value,
    includeMixedStructure = true
)
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final pinnedPosts = AmitySocialClient.newPostRepository().getPinnedPosts(
  communityId: communityId,
  placement: 'announcement',
);

pinnedPosts.getStreamController().stream.listen((items) {
  final count = items.length;
});

await pinnedPosts.loadNext();
```


## Global Pinned Posts

Query global pinned posts when the product needs an app-wide featured-content surface.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getGlobalPinnedPosts(
  {
    includeMixedStructure: true,
  },
  ({ data: pinnedPosts, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(pinnedPosts);
  },
);
```

```swift iOS
token = postRepository
    .getGlobalPinnedPosts(includeMixedStructure: true)
    .observe { collection, error in
        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
postRepository.getGlobalPinnedPosts(includeMixedStructure = true)
    .subscribe(
        { pinnedPosts -> showSuccessMessage(pinnedPosts.size) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final globalPinnedPosts =
    AmitySocialClient.newPostRepository().getGlobalPinnedPosts();

globalPinnedPosts.getStreamController().stream.listen((items) {
  final count = items.length;
});

await globalPinnedPosts.loadNext();
```


## Notes

- Use community pinned posts for a single community feed or announcement area.
- Use global pinned posts for app-wide featured content.
- TypeScript, iOS, and Android expose `includeMixedStructure`; the current Flutter public pinned-post methods do not expose that option.
- Flutter exposes a `sortByOptions` parameter on `getPinnedPosts`, but the current public request builder does not pass it into the request. Do not depend on custom sorting there.

## Pin / Feature Controls

Pinning, unpinning, featuring, and unfeaturing are performed from the **social.plus Console**, not from the client SDK. The client SDKs surface pinned and featured state as read-only.

- **Event posts** in the UIKit follow the same rule and go a step further — the pinned / featured badge renders but there is no in-app pin control in any role, including hosts and moderators. See [Event Posts](../creation/event-post) and the [Event UIKit doc](/uikit/components/social/event) for how the badge renders.
- **User-feed posts** can never be pinned regardless of role or Console state.
- **Global featuring** requires a public community — a post in a private community cannot be featured globally.

## Related Topics

    Query regular feed posts.
    Render the pinned post object.
    Approve or decline posts.

---

### [Post Review](https://learn.social.plus/social-plus-sdk/social/content-management/posts/moderation/post-review)

> Approve, decline, and query posts in community review states with the public SDKs.

Use post review when a community requires posts to be approved before they appear in the published feed. The SDKs expose approval actions by post ID, plus query filters for building a review queue.

## Platform Support

| Platform | Approve | Decline | Query review queue |
| --- | --- | --- | --- |
| TypeScript | `PostRepository.approvePost(postId)` | `PostRepository.declinePost(postId)` | `PostRepository.getPosts({ feedType: "reviewing" })` |
| iOS | `postRepository.approvePost(withId:)` | `postRepository.declinePost(withId:)` | `AmityPostQueryOptions(feedType: .reviewing)` |
| Android | `postRepository.approvePost(postId)` | `postRepository.declinePost(postId)` | `.reviewStatus(AmityReviewStatus.UNDER_REVIEW)` |
| Flutter | `reviewPost(postId:).approve()` | `reviewPost(postId:).decline()` | `.feedType(AmityFeedType.REVIEWING)` |

  TypeScript's current post query type exposes `published` and `reviewing` as live collection feed filters. Android, iOS, and Flutter expose published, reviewing, and declined states in their review/feed status models.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Check review status | Post object | Yes | Loaded post object whose feed/review status should be read. |
| Approve or decline | `postId` | Yes | Post ID to approve or decline. |
| Query a review queue | `communityId` | Yes | Community whose reviewing posts should be listed. |
| Query a review queue | Review/feed status | Yes | Reviewing/under-review filter for the target SDK. |
| Query a review queue | Sort and pagination controls | No | Optional collection controls exposed by the platform. |

## Check Review Status

Read review status from a loaded post before deciding which moderation actions or labels to show.


```typescript TypeScript
const isPublished = post.feedType === "published";
const isUnderReview = post.feedType === "reviewing";

renderResults({ isPublished, isUnderReview });
```

```swift iOS
if let currentPost = postRepository.getPost(withId: "post-id").snapshot {
    switch currentPost.getFeedType() {
    case .published:
        showSuccessMessage("published")
    case .reviewing:
        showSuccessMessage("reviewing")
    case .declined:
        showSuccessMessage("declined")
    @unknown default:
        showSuccessMessage("unknown")
    }
}
```

```kotlin Android
when (post?.getReviewStatus()) {
    AmityReviewStatus.PUBLISHED -> showSuccessMessage("published")
    AmityReviewStatus.UNDER_REVIEW -> showSuccessMessage("reviewing")
    AmityReviewStatus.DECLINED -> showSuccessMessage("declined")
    null -> showSuccessMessage("unknown")
}
```

```dart Flutter
final post = await AmitySocialClient.newPostRepository().getPost(postId);

switch (post.feedType) {
  case AmityFeedType.PUBLISHED:
    final status = 'published';
    break;
  case AmityFeedType.REVIEWING:
    final status = 'reviewing';
    break;
  case AmityFeedType.DECLINED:
    final status = 'declined';
    break;
  default:
    final status = 'unknown';
}
```


## Approve or Decline

Approve or decline by post ID after your product confirms the current user should moderate that community.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const { data: approvedPost } = await PostRepository.approvePost(postId);
const { data: declinedPost } = await PostRepository.declinePost(postId);

renderResults([approvedPost, declinedPost]);
```

```swift iOS
try await postRepository.approvePost(withId: "post-id")
try await postRepository.declinePost(withId: "post-id")

showSuccessMessage()
```

```kotlin Android
postRepository.approvePost(postId = postId)
    .subscribe(
        { showSuccessMessage(postId) },
        { error -> handleGeneralError(error) }
    )

postRepository.declinePost(postId = postId)
    .subscribe(
        { showSuccessMessage(postId) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
await AmitySocialClient.newPostRepository()
    .reviewPost(postId: postId)
    .approve();

await AmitySocialClient.newPostRepository()
    .reviewPost(postId: postId)
    .decline();
```


## Query a Review Queue

Query reviewing posts for a community when building a moderation queue.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getPosts(
  {
    targetType: "community",
    targetId: communityId,
    feedType: "reviewing",
    sortBy: "lastCreated",
  },
  ({ data: posts, loading, error, onNextPage, hasNextPage }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);
```

```swift iOS
let options = AmityPostQueryOptions(
    targetType: .community,
    targetId: communityId,
    sortBy: .lastCreated,
    deletedOption: .notDeleted,
    dataTypes: nil,
    feedType: .reviewing
)

token = postRepository.getPosts(options).observe { collection, error in
    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
postRepository
    .getPosts()
    .targetCommunity(communityId = communityId)
    .reviewStatus(reviewStatus = AmityReviewStatus.UNDER_REVIEW)
    .build()
    .query()
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final reviewQueue = AmitySocialClient.newPostRepository()
    .getPosts()
    .targetCommunity(communityId)
    .feedType(AmityFeedType.REVIEWING)
    .getLiveCollection(pageSize: 20);

reviewQueue.getStreamController().stream.listen((posts) {
  final count = posts.length;
});

await reviewQueue.loadNext();
```


## Notes

- Show approve and decline actions only to users who should moderate the community.
- Approval and decline calls operate by post ID and rely on backend permission checks.
- Remove reviewed posts from local review queues after successful action, or wait for the live collection to update.

## Related Topics

    Query community feeds by review status.
    Remove posts during moderation.
    Display pinned posts.

---

### [Post Impressions](https://learn.social.plus/social-plus-sdk/social/content-management/posts/analytics/post-impressions)

> Record post view analytics, read impression and reach counts, and query users who viewed a post.

Post impression analytics has three SDK-facing pieces:

- Mark a post as viewed when your app decides it was visible enough to count.
- Read `impression` and `reach` from the post model returned by retrieval or query APIs.
- Query reached users when you need the list of unique viewers for a post.

  The SDK exposes impression and reach counters, but it does not expose a ready-made view-rate metric. Calculate product-specific ratios in your app from the counters and audience size that matter to your experience.

## Metrics

| Metric | TypeScript / iOS / Flutter | Android | Meaning |
| --- | --- | --- | --- |
| Impression | `post.impression` | `post.getImpression()` | Total view events recorded for the post |
| Reach | `post.reach` | `post.getReach()` | Unique users who viewed the post |

## Platform APIs

| Operation | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Mark viewed | `post.analytics.markAsViewed()` | `post.analytics.markAsViewed()` | `post.analytics().markAsViewed()` | `post.analytics().markPostAsViewed()` |
| Query reached users | `UserRepository.getReachedUsers({ viewId, viewedType: "post" }, callback)` | `userRepository.getReachedUsers(viewedType: .post, viewedId: postId)` | `userRepository.getReachedUsers(AmityViewedType.POST, postId)` | `userRepository.getViewedUsers(viewedType: AmityViewedType.POST, viewedId: postId)` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Mark a post as viewed | Post object | Yes | Loaded post object whose analytics helper records the view. |
| Query reached users | `viewId` / `viewedId` | Yes | Post ID used to query users reached by the post. |
| Query reached users | `viewedType` | Yes | Viewed type value for posts. |
| Query reached users | `limit` | No | TypeScript page size for reached-user results. |

## Mark a Post as Viewed

Call the analytics method from your own visibility logic, such as a post detail screen opening or a feed cell crossing your viewability threshold. Do not call it from every render or rebuild.


```typescript TypeScript
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getPost(
  postId,
  ({ data: post, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!post) return;

    post.analytics.markAsViewed();

    renderResults({
      impression: post.impression,
      reach: post.reach,
    });
  },
);
```

```swift iOS
let postRepository = AmityPostRepository()
var token: AmityNotificationToken?

token = postRepository.getPost(withId: "post-id").observe { liveObject, error in
    guard let post = liveObject.snapshot else { return }

    post.analytics.markAsViewed()

    let impression = post.impression
    let reach = post.reach
    showSuccessMessage("Impressions: \(impression), reach: \(reach)")
}
```

```kotlin Android
postRepository.getPost(postId)
    .subscribe(
        { post ->
            post.analytics().markAsViewed()

            val impression = post.getImpression()
            val reach = post.getReach()
            showSuccessMessage("Impressions: $impression, reach: $reach")
        },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final subscription = AmitySocialClient.newPostRepository()
    .live
    .getPost(postId)
    .listen((AmityPost post) {
      post.analytics().markPostAsViewed();

      final impression = post.impression ?? 0;
      final reach = post.reach ?? 0;
    });

await subscription.cancel();
```


## Query Reached Users

Use reached-user queries when you need the user list behind the reach count. TypeScript names the ID parameter `viewId`; iOS, Android, and Flutter name it `viewedId`.


```typescript TypeScript
import { UserRepository } from "@amityco/ts-sdk";

const unsubscribe = UserRepository.getReachedUsers(
  {
    viewId: postId,
    viewedType: "post",
    limit: 10,
  },
  ({ data: users, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(users);
  },
);
```

```swift iOS
let userRepository = AmityUserRepository()
var token: AmityNotificationToken?

token = userRepository
    .getReachedUsers(viewedType: .post, viewedId: "post-id")
    .observe { collection, error in
        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.model.core.analytics.AmityViewedType

AmityCoreClient.newUserRepository()
    .getReachedUsers(viewedType = AmityViewedType.POST, viewedId = postId)
    .subscribe(
        { users: PagingData<AmityUser> -> showSuccessMessage(users) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final users = await AmityCoreClient.newUserRepository()
    .getViewedUsers(viewedType: AmityViewedType.POST, viewedId: postId)
    .query();

final reachedUserCount = users.length;
```


## Notes

- Keep the unsubscriber, notification token, or stream subscription so you can dispose it when the screen is destroyed.
- Refresh or re-query the post if your UI needs updated `impression` and `reach` values after marking a view.
- Treat analytics failures as non-blocking; viewing a post should not depend on the analytics event being accepted.
- Apply your own viewability threshold and debounce rules before calling the SDK method.

## Related Topics

    Query posts by feed target, post type, review status, or tags
    Render post data and child media safely
    Track story views and query reached users for stories

## Social — Comments

### [Comments Overview](https://learn.social.plus/social-plus-sdk/social/content-management/comments/overview)

> Create, query, update, delete, and react to comments on posts, stories, and custom content.

Use the comment repository when you need discussions on posts, stories, or custom content. Comment creation supports text, optional image attachments, metadata, user mentions, and replies through `parentId`.

  A reply is a normal comment with `parentId` set to another comment ID. There is no separate reply API in the SDK.

  Each comment also carries `rootId`, the ID of the top-level comment that starts the thread. `parentId` is the comment being replied to directly, while `rootId` stays the same for every comment in the thread — use it to group or navigate a whole thread without walking the parent chain.

## Comment Targets

| Reference type | Use it for | SDK value |
| --- | --- | --- |
| Post | Comments on Social posts | `post` / `.post` / `POST` |
| Story | Comments on story content | `story` / `.story` / `STORY` |
| Content | Comments on your own external content IDs | `content` / `.content` / `CONTENT` |

## Comment Shape

The exact property names vary by platform, but the SDK model centers on the same fields.

| Concept | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Comment ID | `comment.commentId` | `comment.commentId` | `comment.getCommentId()` | `comment.commentId` |
| Parent comment | `comment.parentId` | `comment.parentId` | `comment.getParentId()` | `comment.parentId` |
| Root comment | `comment.rootId` | `comment.rootId` | `comment.getRootId()` | `comment.rootId` |
| Reference | `referenceId`, `referenceType` | `referenceId`, `referenceType` | `comment.getReference()` | `referenceId`, `referenceType` |
| Text data | `comment.data.text` | `comment.data` text value | `comment.getData()` | `comment.data` |
| Image attachments | `comment.attachments` | `comment.attachments` | `comment.getAttachments()` | `comment.attachments` |
| Reply count | `childrenNumber` | `childrenNumber` | `getChildCount()` | `childrenNumber` |
| Reactions | `reactions`, `myReactions` | reaction properties on comment | `getReactionCount()`, `getMyReactions()` | `reactionCount`, `myReactions` |
| Moderation | `isDeleted`, flags | `isDeleted`, flags | `isDeleted()`, flags | `isDeleted`, flags |
| Approval status | `comment.approvalStatus` | `comment.approvalStatus` | `comment.getApprovalStatus()` | Not exposed |

## Creation APIs

| Platform | Repository entry point | Text comment | Image comment |
| --- | --- | --- | --- |
| TypeScript | `CommentRepository.createComment(...)` | `data: { text }` | `attachments: [{ type: "image", fileId }]` |
| iOS | `AmityCommentRepository().createComment(with:)` | `AmityCommentCreateOptions(text:)` | `attachments: [.image(fileId:)]` |
| Android | `commentRepository.createComment()` | `.with().text(...).build().send()` | `.with().attachments(...).build().send()` |
| Flutter | `AmitySocialClient.newCommentRepository().createComment()` | `.create().text(...).send()` | `.create().attachments(...).send()` |

  Upload image files first, then pass the uploaded image file IDs to the comment creation API. Comment creation does not upload local files by itself.

  A community can require a moderator to approve comments before anyone else sees them. In such a community, a created or edited comment comes back `pending` and stays out of public comment lists and counts until it is approved. See [Approval Lifecycle](./moderation/comment-review#approval-lifecycle).

## Related Topics

    Create top-level comments and replies with text
    Create comments with uploaded image attachments
    Query top-level comments and reply threads
    Edit, delete, flag, and manage comments

---

### [Create Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/creation/create-comment)

> Choose the right comment creation API for text comments, replies, and image comments.

Use comment creation APIs to add comments to posts, stories, or your own custom content IDs. A reply is a normal comment with `parentId` set to the comment being replied to.

    Create top-level comments and replies with text, metadata, mentions, and supported link payloads.
    Create comments with uploaded image file IDs.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `referenceId` | Yes | TypeScript, iOS, Android, Flutter | Target content ID for the comment, such as a post ID. |
| `referenceType` | Yes | TypeScript, iOS, Android, Flutter | Target content type, such as `post`. |
| `text` | Yes | TypeScript, iOS, Android, Flutter | Text body for the comment or reply shown in these examples. |
| `parentId` | No | TypeScript, iOS, Android, Flutter | Parent comment ID when creating a reply. |
| `metadata` | No | TypeScript, iOS, Android, Flutter | App-defined metadata stored with the comment. Set through each platform's comment builder. |
| `mentionees` / mention builders | No | TypeScript, iOS, Android, Flutter | Mention targets for text comments. Set through each platform's comment builder. |

  In a community that requires comment review, the created comment comes back with a `pending` approval status: only its author and the community's reviewers can see it, and it does not move the post's comment count for anyone else until it is approved. See [Approval Lifecycle](../moderation/comment-review#approval-lifecycle) for when a comment is held and who is exempt. In a community that requires review, create with optimistic creation turned off so the returned comment already carries its approval status — see [Read Approval Status on a Comment](../moderation/comment-review#read-approval-status-on-a-comment).

## Basic Text Comment

Create a top-level text comment by passing the reference target and text body to the comment repository.


```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

const { data: comment } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: 'post',
  data: {
    text: 'Hello world!',
  },
});

renderResults(comment);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Hello world!"
)

let comment = try await commentRepository.createComment(with: options)
showSuccessMessage(comment.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .with()
    .text(text = "Hello world!")
    .build()
    .send()
    .subscribe(
        { comment -> showSuccessMessage(comment.getCommentId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final comment = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .create()
    .text('Hello world!')
    .send();

final commentId = comment.commentId;
```


## Reply to a Comment

Create a reply with the same reference target and the `parentId` of the comment being replied to.


```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

const { data: reply } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: 'post',
  parentId: commentId,
  data: {
    text: 'Replying to this comment',
  },
});

renderResults(reply);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Replying to this comment",
    parentId: "parent-comment-id"
)

let reply = try await commentRepository.createComment(with: options)
showSuccessMessage(reply.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .parentId(parentId = commentId)
    .with()
    .text(text = "Replying to this comment")
    .build()
    .send()
    .subscribe(
        { reply -> showSuccessMessage(reply.getCommentId()) },
        { error -> handleGeneralError(error) },
    )
```

```dart Flutter
final reply = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .parentId(commentId)
    .create()
    .text('Replying to this comment')
    .send();

final replyId = reply.commentId;
```


## Related Topics

    See full text-comment parameters and notes.
    Create comments with uploaded image attachments.
    Query top-level comments and reply threads.
    Remove comments after user or moderation actions.

---

### [Text Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/creation/text-comment)

> Create text comments and replies on posts, stories, or custom content.

Create a text comment by passing a reference target and text body to the comment repository. To create a reply, pass the parent comment ID with the same reference target.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `referenceId` | Yes | All | ID of the post, story, or custom content item being commented on |
| `referenceType` | Yes | All | Use `post`, `story`, or `content` |
| `text` | Yes | All | Text body of the comment |
| `parentId` | No | All | Existing comment ID when creating a reply |
| `metadata` | No | All | Custom metadata attached to the comment |
| `mentionees` / mention builder | No | All | User mention payloads |
| `links` | No | TypeScript, iOS, Android | Link metadata; not exposed on the Flutter comment builder |

  The current Flutter public comment creation builder exposes `metadata(...)` and `mentionUsers(...)`, but it does not expose a `links(...)` method.

## Create a Text Comment

Create a top-level text comment with the reference target and text body.

  Comment creation is local-first on TypeScript, iOS, Android, and React Native: the SDK persists a local comment before the server confirms it. See [Local-First Comment Creation](#local-first-comment-creation) for the per-platform sync states and failure handling.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: comment } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: "post",
  data: {
    text: "Hello world!",
  },
});

renderResults(comment);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Hello world!"
)

let comment = try await commentRepository.createComment(with: options)
showSuccessMessage(comment.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .with()
    .text(text = "Hello world!")
    .build()
    .send()
    .subscribe(
        { comment -> showSuccessMessage(comment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final comment = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .create()
    .text('Hello world!')
    .send();

final commentId = comment.commentId;
```


## Reply to a Comment

Replies use the same creation API with `parentId` set to the comment being replied to.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: reply } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: "post",
  parentId: commentId,
  data: {
    text: "Replying to this comment",
  },
});

renderResults(reply);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Replying to this comment",
    parentId: "parent-comment-id"
)

let reply = try await commentRepository.createComment(with: options)
showSuccessMessage(reply.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .parentId(parentId = commentId)
    .with()
    .text(text = "Replying to this comment")
    .build()
    .send()
    .subscribe(
        { reply -> showSuccessMessage(reply.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final reply = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .parentId(commentId)
    .create()
    .text('Replying to this comment')
    .send();

final replyId = reply.commentId;
```


## Add Structured Links

TypeScript, iOS, and Android accept a `links` payload when creating a comment, which stores the links found in the comment text alongside the comment.

Comments highlight link text; they do not render link preview cards. Build each link with `renderPreview: false` and leave the preview metadata fields unset — a comment never needs a preview metadata lookup.

Each link carries:

| Field | Required | Description |
| --- | --- | --- |
| `url` | Yes | The link target. |
| `renderPreview` | Yes | Set `false` for comments. Comments never render preview cards, so this value does not affect how a comment link displays. |
| `index`, `length` | No | Position and length of the link text within the comment text. Include both whenever you send a `links` payload. |
| `domain`, `title`, `imageUrl` | No | Preview card metadata. Leave unset for comments. |

  Sending `links` is optional. Clients detect URLs in the comment text and highlight them on their own, so a comment created without a `links` payload still renders highlighted links. When you do send the payload, include `index` and `length` for every link. On Android, `AmityLink` has no default arguments — pass `null` for every field you are not setting.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: comment } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: "post",
  data: {
    text: "Check this out https://www.amity.co",
  },
  links: [
    {
      index: 15,
      length: 20,
      url: "https://www.amity.co",
      renderPreview: false,
    },
  ],
});

renderResults(comment);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Check this out https://www.amity.co",
    links: [
        AmityLink(
            url: "https://www.amity.co",
            index: 15,
            length: 20,
            renderPreview: false
        )
    ]
)

let comment = try await commentRepository.createComment(with: options)
showSuccessMessage(comment.commentId)
```

```kotlin Android
val links = listOf(
    AmityLink(
        index = 15,
        length = 20,
        url = "https://www.amity.co",
        renderPreview = false,
        domain = null,
        title = null,
        imageUrl = null
    )
)

AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .with()
    .text(text = "Check this out https://www.amity.co")
    .links(links = links)
    .build()
    .send()
    .subscribe(
        { comment -> showSuccessMessage(comment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```


When editing a comment on iOS, `links` follows update semantics: pass `nil` to leave the existing links unchanged, or `[]` to remove them all. See [Edit Comment](../actions/edit-comment).

## Local-First Comment Creation

On TypeScript, iOS, Android, and React Native, the SDK writes the comment to its local store and starts the server request immediately, so an active comment collection can render it before the round trip completes. Flutter waits for the server response instead.

The state is observable on every local-first platform, but the names and failure behavior differ:

| Platform | State and failure behavior |
| --- | --- |
| TypeScript | Read `comment.syncState`: `syncing` while the request is in flight, `synced` after server confirmation, or `error` when creation fails. The optimistic item remains in the collection on failure and carries a temporary local comment ID. |
| iOS | Observe `AmityComment.syncState`: `.syncing` becomes `.synced` after confirmation. A failed local comment becomes `.error` and is removed from its parent relationship, so it no longer appears among its parent's children. |
| Android | Read `comment.getState()`: `SYNCING` becomes `SYNCED` after confirmation. A failed local comment is marked `FAILED` in the local store. |
| Flutter | The current public comment-creation path waits for the server response before persisting the comment; it does not create the same local-first temporary comment. |
| React Native | Uses `@amityco/ts-sdk-react-native`, which shares the TypeScript implementation and behaves identically. |

Render local-first comments in a pending style, and handle each platform's failure state so a failed comment is not mistaken for a server-created one.

  On TypeScript and React Native, local-first creation requires the client cache. When the cache is disabled no local comment is created, and the call behaves like a plain server request.

The creation call also rejects when the server request fails; it does not only set the failure state. Catch the error from the creation call and watch sync state through the live collection or observable query. Handling only one of the two leaves either an unhandled rejection or a pending comment that never resolves.

## Notes

- Keep the same `referenceId` and `referenceType` as the thread you are replying in.
- Use query APIs or live collections to display creation and sync state in the UI.
- Validate your product's text limits and moderation rules before calling the SDK.
- Build mention payloads from the user IDs your mention picker returns.

## Related Topics

    Create comments with uploaded image attachments.
    Query top-level comments and reply threads.

---

### [Image Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/creation/image-comment)

> Create comments with uploaded image attachments.

Image comments are comments with image attachment file IDs. Upload each image first, then pass the uploaded file ID to the comment creation API. You can also include text with the image attachment.

  Comment creation accepts uploaded image file IDs. Use the file or image upload APIs before creating the comment.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Create an image comment | `referenceId` | Yes | Target content ID for the comment, such as a post ID. |
| Create an image comment | `referenceType` | Yes | Target content type, such as `post`. |
| Create an image comment | Uploaded image file ID | Yes | File ID returned by the image upload API. |
| Create an image comment | `text` | No | Optional text body included with the image attachment. |
| Reply with an image | `parentId` | Yes | Parent comment ID when creating an image reply. |

## Create an Image Comment

Create an image comment from an uploaded image file ID, with optional text where supported.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: comment } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: "post",
  data: {
    text: "Photo response",
  },
  attachments: [
    {
      type: "image",
      fileId: imageFileId,
    },
  ],
});

renderResults(comment);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Photo response",
    attachments: [
        .image(fileId: "uploaded-image-id")
    ]
)

let comment = try await commentRepository.createComment(with: options)
showSuccessMessage(comment.commentId)
```

```kotlin Android
val imageAttachment = AmityComment.Attachment.IMAGE(
    fileId = fileId,
    image = null
)

AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .with()
    .attachments(imageAttachment)
    .text(text = "Photo response")
    .build()
    .send()
    .subscribe(
        { comment -> showSuccessMessage(comment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final comment = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .create()
    .attachments([
      CommentImageAttachment(fileId: fileId),
    ])
    .text('Photo response')
    .send();

final commentId = comment.commentId;
```


## Reply with an Image

Set `parentId` before the platform-specific create step.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: reply } = await CommentRepository.createComment({
  referenceId: postId,
  referenceType: "post",
  parentId: commentId,
  attachments: [
    {
      type: "image",
      fileId: imageFileId,
    },
  ],
});

renderResults(reply);
```

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "",
    attachments: [
        .image(fileId: "uploaded-image-id")
    ],
    parentId: "parent-comment-id"
)

let reply = try await commentRepository.createComment(with: options)
showSuccessMessage(reply.commentId)
```

```kotlin Android
val imageAttachment = AmityComment.Attachment.IMAGE(
    fileId = fileId,
    image = null
)

AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .parentId(parentId = commentId)
    .with()
    .attachments(imageAttachment)
    .build()
    .send()
    .subscribe(
        { reply -> showSuccessMessage(reply.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final reply = await AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId)
    .parentId(commentId)
    .create()
    .attachments([
      CommentImageAttachment(fileId: fileId),
    ])
    .send();

final replyId = reply.commentId;
```


## Notes

- Reuse the uploaded image file ID returned by the upload API; do not pass a local file path to comment creation.
- If your product needs image moderation or file-size limits, apply those rules before upload.
- Query the resulting comment if you need composed file metadata such as rendered image information.

## Related Topics

    Create text comments and replies.
    Upload image files before attaching them to comments.

---

### [Get Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/retrieval/get-comment)

> Retrieve a comment by ID and observe updates where the SDK exposes live objects or streams.

Use a comment ID when your app needs to open a thread, refresh a detail view, or inspect a comment after creation. TypeScript, iOS, Android, and Flutter all expose single-comment retrieval; the live update shape differs by platform.

## Comment Fields

The comment model names vary by SDK, but these are the fields most apps read after retrieval.

| Concept | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Comment ID | `commentId` | `commentId` | `getCommentId()` | `commentId` |
| Parent comment | `parentId` | `parentId` | `getParentId()` | `parentId` |
| Reference | `referenceId`, `referenceType` | `referenceId`, `referenceType` | `getReference()` | `referenceId`, `referenceType` |
| Data | `data` | `data` | `getData()` | `data` |
| Image attachments | `attachments` | `attachments` | `getAttachments()` | `attachments` |
| Reply count | `childrenNumber` | `childrenNumber` | `getChildCount()` | `childrenNumber` |
| Reactions | `reactionCount`, `myReactions` | `reactionsCount`, `myReactions` | `getReactionCount()`, `getMyReactions()` | `reactionCount`, `myReactions` |
| Deleted state | `isDeleted` | `isDeleted` | `isDeleted()` | `isDeleted` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Observe a comment | `commentId` | Yes | Comment ID to observe as a live object or stream. |
| Fetch one comment | `commentId` | Yes | Comment ID to fetch once on Flutter. |
| Fetch multiple comments by ID | `commentIds` | Yes | Comment IDs to fetch on TypeScript and Android. |

## Observe a Comment

Observe a single comment when a detail view or thread preview should stay current after edits, deletes, or reactions.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComment(
  commentId,
  ({ data: comment, loading, error }) => {
    if (loading) return;

    if (error) {
      handleError(error);
      return;
    }

    if (comment) {
      renderResults(comment);
    }
  },
);
```

```swift iOS
var token: AmityNotificationToken?

token = commentRepository
    .getComment(withId: "comment-id")
    .observe { liveObject, error in
        if let error {
            handleError(error)
            return
        }

        guard let comment = liveObject.snapshot else { return }
        showSuccessMessage(comment.commentId)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.api.core.ExperimentalAmityApi

@OptIn(ExperimentalAmityApi::class)
fun observeComment(commentId: String) {
    AmitySocialClient.newCommentRepository()
        .getComment(commentId = commentId)
        .subscribe(
            { comment -> showSuccessMessage(comment.getCommentId()) },
            { error -> handleGeneralError(error) }
        )
}

observeComment(commentId)
```

```dart Flutter
final commentStream = AmitySocialClient.newCommentRepository()
    .live
    .getComment(commentId);

final subscription = commentStream.listen((comment) {
  final fetchedCommentId = comment.commentId;
}, onError: (error) {
  showError(error);
});

await subscription.cancel();
```


## Fetch One Comment

Flutter also exposes a direct one-shot fetch for comment detail screens.


```dart Flutter
final comment = await AmitySocialClient.newCommentRepository()
    .getComment(commentId: commentId);

final fetchedCommentId = comment.commentId;
```


## Fetch Multiple Comments by ID

Batch lookup is available in TypeScript and Android. Use query APIs when you need a paged collection for a post, story, or custom content item.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: comments } = await CommentRepository.getCommentByIds([
  commentId,
  "another-comment-id",
]);

renderResults(comments);
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .getCommentByIds(commentIds = setOf(commentId, "another-comment-id"))
    .subscribe(
        { comments -> showSuccessMessage(comments.size) },
        { error -> handleGeneralError(error) }
    )
```


## Notes

- Dispose of live observers or stream subscriptions when the screen is no longer active.
- Android `getComment(...)` is annotated with `ExperimentalAmityApi`; opt in at the call site or enclosing scope.
- If the user needs a list of comments under a reference, use [Query Comments](/social-plus-sdk/social/content-management/comments/retrieval/query-comments) instead of repeated single-comment calls.

## Related Topics

    Query top-level comments and reply threads.
    Fetch or derive the newest comment for a reference.

---

### [Get Latest Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/retrieval/get-latest-comment)

> Fetch the newest comment for a post or content item, with platform-specific helper availability.

Use the latest-comment pattern when you need a compact preview, such as showing the newest comment below a post card. iOS and Android expose dedicated latest-comment helpers. TypeScript and Flutter use the normal comment query API sorted newest-first with a page size of one.

## Platform Availability

| Platform | Dedicated latest helper | Reference targets |
| --- | --- | --- |
| iOS | `getLatestComment(withReferenceId:referenceType:includeReplies:)` | `post`, `content`, `story` |
| Android | `getLatestComment().post(...)` / `.content(...)` | `post`, `content` |
| TypeScript | Use `getComments(...)` with `sortBy: "lastCreated"` and `pageSize: 1` | `post`, `content`, `story` |
| Flutter | Use `getComments().post(...)`, `.content(...)`, or `.story(...)` with newest-first sort and limit `1` | `post`, `content`, `story` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Dedicated helpers | `referenceId` | Yes | Target content ID whose latest comment should be fetched. |
| Dedicated helpers | `referenceType` | Yes | Target content type, such as `post`. |
| Dedicated helpers | `includeReplies` | No | Whether replies can be returned as the latest comment on iOS and Android. |
| Query the latest comment | `sortBy` | Yes | Newest-first sort order, such as `lastCreated`. |
| Query the latest comment | `pageSize` / `limit` | Yes | Set to `1` to retrieve only the newest comment. |

## Dedicated Helpers

Use the dedicated iOS and Android helpers when you want the latest comment without building a manual one-item query.


```swift iOS
let latestComment = try await commentRepository.getLatestComment(
    withReferenceId: "post-id",
    referenceType: .post,
    includeReplies: true
)

showSuccessMessage(latestComment.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .getLatestComment()
    .post(postId = postId)
    .includeReplies(includeReplies = true)
    .build()
    .query()
    .subscribe(
        { comment -> showSuccessMessage(comment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```


## Query the Latest Comment

Use this pattern on TypeScript and Flutter, or when you want the same query-based behavior across platforms.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComments(
  {
    referenceType: "post",
    referenceId: postId,
    sortBy: "lastCreated",
    pageSize: 1,
  },
  ({ data: comments, loading, error }) => {
    if (loading) return;

    if (error) {
      handleError(error);
      return;
    }

    const latestComment = comments?.[0];
    if (latestComment) {
      renderResults(latestComment);
    }
  },
);
```

```dart Flutter
final comments = await AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId)
    .sortBy(AmityCommentSortOption.LAST_CREATED)
    .includeDeleted(false)
    .query(limit: 1);

final latestComment = comments.isNotEmpty ? comments.first : null;
```


## Include Replies

For iOS and Android dedicated helpers, `includeReplies` controls whether replies can be returned as the latest comment.

| Value | Result |
| --- | --- |
| `true` | The newest comment at any level can be returned |
| `false` | Only top-level comments are considered |

For query-based implementations, use the `parentId` filter:

- Omit `parentId` to query comments from all levels where the SDK supports it.
- Set `parentId` to `null` / `nil` to query only top-level comments.
- Set `parentId` to a comment ID to query replies to that comment.

## Notes

- The dedicated iOS and Android latest-comment helpers return one comment, not a live object or live collection.
- Use [Query Comments](/social-plus-sdk/social/content-management/comments/retrieval/query-comments) when you need pagination, filtering, or a full thread.
- Handle the empty state in query-based implementations because a reference may not have comments yet.

## Related Topics

    Query comments with parent filters, deleted-state filters, and pagination.
    Retrieve a specific comment by ID.

---

### [Query Comments](https://learn.social.plus/social-plus-sdk/social/content-management/comments/retrieval/query-comments)

> Query comments for posts, stories, or custom content with pagination, parent filtering, deleted-state filtering, and sort order.

Use comment queries when your app needs a paged list for a post, story, or custom content item. Query top-level comments for the main thread, then query replies with `parentId` when a user expands a comment.

  Query APIs return paged/live collection results on TypeScript, iOS, Android, and Flutter. For a single known comment ID, use [Get Comment](/social-plus-sdk/social/content-management/comments/retrieval/get-comment).

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Query comments | `referenceId` | Yes | ID of the post, story, or custom content item. |
| Query comments | `referenceType` | Yes | Target content type, such as `post`, `story`, or `content`. |
| Query comments | `parentId` | No | `null` / `nil` for top-level comments, a comment ID for replies, or omitted where supported. |
| Query comments | `includeDeleted` | No | Include soft-deleted comments for moderation or audit views. |
| Query comments | `dataTypes` | No | Filter comments by content type, such as text or image. |
| Query comments | `sortBy` / `orderBy` | No | Newest-first or oldest-first comment order. |
| Query comments | `pageSize` / `limit` | No | Number of comments to load per page. |

## Query Options

| Option | Description |
| --- | --- |
| `referenceId` | ID of the post, story, or custom content item |
| `referenceType` | `post`, `story`, or `content` |
| `parentId` | `null` / `nil` for top-level comments; a comment ID for replies; omit the parent filter to include all levels where supported |
| `includeDeleted` | Include soft-deleted comments when building moderation or audit views |
| `dataTypes` | Filter comments by content type, such as text or image |
| `sortBy` / `orderBy` | Newest-first or oldest-first comment order |
| `pageSize` / `limit` | Number of comments to load per page |

## Query Top-Level Comments

Set the parent filter to `null` / `nil` when you only want root comments.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComments(
  {
    referenceType: "post",
    referenceId: postId,
    parentId: null,
    sortBy: "lastCreated",
    pageSize: 10,
  },
  ({ data: comments, loading, error }) => {
    if (loading) return;

    if (error) {
      handleError(error);
      return;
    }

    renderResults(comments);
  },
);
```

```swift iOS
let queryOptions = AmityCommentQueryOptions(
    referenceId: "post-id",
    referenceType: .post,
    filterByParentId: true,
    parentId: nil,
    orderBy: .descending,
    includeDeleted: false,
    pageSize: 20
)

token = commentRepository
    .getComments(with: queryOptions)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.api.social.comment.query.AmityCommentSortOption

AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId = postId)
    .parentId(parentId = null)
    .sortBy(AmityCommentSortOption.LAST_CREATED)
    .includeDeleted(includeDeleted = false)
    .pageSize(pageSize = 15)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final liveCollection = AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId)
    .parentId(null)
    .sortBy(AmityCommentSortOption.LAST_CREATED)
    .includeDeleted(false)
    .getLiveCollection(pageSize: 20);

final subscription = liveCollection.getStreamController().stream.listen(
  (comments) {
    final visibleCommentCount = comments.length;
  },
  onError: (error) {
    showError(error);
  },
);

liveCollection.loadNext();
await subscription.cancel();
```


## Query Replies

Set `parentId` to an existing comment ID to load replies for that comment.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComments(
  {
    referenceType: "post",
    referenceId: postId,
    parentId: commentId,
    sortBy: "firstCreated",
    pageSize: 5,
  },
  ({ data: replies, loading, error }) => {
    if (loading) return;

    if (error) {
      handleError(error);
      return;
    }

    renderResults(replies);
  },
);
```

```swift iOS
let replyQueryOptions = AmityCommentQueryOptions(
    referenceId: "post-id",
    referenceType: .post,
    filterByParentId: true,
    parentId: "parent-comment-id",
    orderBy: .ascending,
    includeDeleted: false,
    pageSize: 5
)

token = commentRepository
    .getComments(with: replyQueryOptions)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.api.social.comment.query.AmityCommentSortOption

AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId = postId)
    .parentId(parentId = commentId)
    .sortBy(AmityCommentSortOption.FIRST_CREATED)
    .includeDeleted(includeDeleted = false)
    .pageSize(pageSize = 5)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final replies = await AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId)
    .parentId(commentId)
    .sortBy(AmityCommentSortOption.FIRST_CREATED)
    .includeDeleted(false)
    .query(limit: 5);

final replyCount = replies.length;
```


## Filter by Data Type

Use data type filters when your UI needs a specific type of comment, such as image-only comments.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComments(
  {
    referenceType: "post",
    referenceId: postId,
    dataTypes: {
      values: ["image"],
      matchType: "exact",
    },
    pageSize: 10,
  },
  ({ data: imageComments, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    renderResults(imageComments);
  },
);
```

```swift iOS
let imageOnlyOptions = AmityCommentQueryOptions(
    referenceId: "post-id",
    referenceType: .post,
    filterByParentId: false,
    dataTypes: .exact([.image]),
    orderBy: .descending,
    includeDeleted: false,
    pageSize: 20
)

token = commentRepository
    .getComments(with: imageOnlyOptions)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.api.social.comment.query.AmityCommentDataTypeFilter
import com.amity.socialcloud.sdk.api.social.comment.query.AmityCommentSortOption

AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId = postId)
    .dataTypes(
        AmityCommentDataTypeFilter.Exact(
            dataTypes = listOf(AmityComment.DataType.IMAGE)
        )
    )
    .sortBy(AmityCommentSortOption.LAST_CREATED)
    .includeDeleted(includeDeleted = false)
    .pageSize(pageSize = 10)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final imageComments = await AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId)
    .dataTypes(
      AmityCommentDataTypeFilter.exact(dataTypes: [AmityDataType.IMAGE]),
    )
    .sortBy(AmityCommentSortOption.LAST_CREATED)
    .includeDeleted(false)
    .query(limit: 10);

final imageCommentCount = imageComments.length;
```


## Reference Targets

| Target | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Post | `referenceType: "post"` | `.post` | `.post(postId = ...)` | `.post(postId)` |
| Story | `referenceType: "story"` | `.story` | `.story(storyId = ...)` | `.story(storyId)` |
| Content | `referenceType: "content"` | `.content` | `.content(contentId = ...)` | `.content(contentId)` |

## Notes

- Keep `referenceId` and `referenceType` consistent between the parent comment and its replies.
- Use smaller page sizes for reply threads than for top-level comments.
- `includeDeleted: true` is mainly for moderation, audit, or admin-style views; most end-user views should exclude deleted comments.
- Dispose of observers, subscriptions, or live collections when the screen is no longer active.

## Related Topics

    Retrieve a specific comment by ID
    Create top-level comments and replies

---

### [Edit Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/actions/edit-comment)

> Update comment text, metadata, mentions, links, and image attachments with the comment update APIs.

Use comment update APIs when a user edits a comment or replaces its image attachments. The SDK sends the update to the server; permission, ownership, and moderation rules are enforced by the backend and surfaced as SDK errors.

## Update Fields

| Field | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Text | `data: { text }` | `AmityCommentUpdateOptions(text:)` | `.text(...)` | `.text(...)` |
| Metadata | `metadata` | `metadata` | `.metadata(...)` | `.metadata(...)` |
| Mentions | `mentionees` | `mentioneesBuilder` | `.mentionUsers(...)` | `.mentionUsers(...)` |
| Links | `links` | `links` | `.links(...)` | Not exposed on the public update builder |
| Image attachments | `attachments` payload | `attachments` | `.attachments(...)` | `.attachments(...)` |

  Upload image files first, then pass the uploaded file IDs to the update API. Passing local file paths to comment update is not supported.

  In a community that requires comment review, an edit that actually changes the comment, made by anyone who cannot review the community's comments, sends it back to `pending`: it leaves public comment lists and the post's comment count until a reviewer approves it again. An edit that changes nothing leaves the comment approved. Read `approvalStatus` on the returned comment instead of assuming the edit is live — see [How the Status Changes](../moderation/comment-review#how-the-status-changes) for which edits count and who is exempt.

  On a network where `isAllowEditCommentWhenReviewingEnabled` is `false`, editing a comment that is already pending fails with `403` / `400300`.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Update text | `commentId` | Yes | TypeScript, iOS, Android, Flutter | Comment ID to update. |
| Update text | `text` | Yes | TypeScript, iOS, Android, Flutter | Replacement text body for the comment. |
| Update image attachments | `commentId` | Yes | TypeScript, iOS, Android, Flutter | Comment ID to update. |
| Update image attachments | Uploaded image file ID | Yes | TypeScript, iOS, Android, Flutter | Uploaded image file ID to keep on the comment. |
| Update optional fields | `metadata`, mentions | No | TypeScript, iOS, Android, Flutter | Optional editable fields. See [Update Fields](#update-fields) for each platform's builder method. |
| Update optional fields | `links` | No | TypeScript, iOS, Android | Link attachments. Not exposed on the Flutter public update builder. |

## Update Text

Update text and other editable fields by loading the comment ID and applying the platform-specific update call.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: updatedComment } = await CommentRepository.updateComment(
  commentId,
  {
    data: {
      text: "Updated comment text",
    },
  },
);

renderResults(updatedComment);
```

```swift iOS
let options = AmityCommentUpdateOptions(
    text: "Updated comment text"
)

let updatedComment = try await commentRepository.editComment(
    withId: "comment-id",
    options: options
)

showSuccessMessage(updatedComment.commentId)
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .editComment(commentId = commentId)
    .text(text = "Updated comment text")
    .build()
    .apply()
    .subscribe(
        { updatedComment -> showSuccessMessage(updatedComment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
await AmitySocialClient.newCommentRepository()
    .updateComment(commentId: commentId)
    .text('Updated comment text')
    .build()
    .update();
```


## Update Image Attachments

Set the attachment list to the full list you want the comment to keep. To preserve an existing image, include its uploaded file ID in the update payload.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const patch: Parameters<typeof CommentRepository.createComment>[0] = {
  referenceId: postId,
  referenceType: "post",
  data: {
    text: "Updated with an image",
  },
  attachments: [
    {
      type: "image",
      fileId: imageFileId,
    },
  ],
};

const { data: updatedComment } = await CommentRepository.updateComment(
  commentId,
  patch,
);

renderResults(updatedComment);
```

```swift iOS
let options = AmityCommentUpdateOptions(
    text: "Updated with an image",
    attachments: [
        .image(fileId: "uploaded-image-id")
    ]
)

let updatedComment = try await commentRepository.editComment(
    withId: "comment-id",
    options: options
)

showSuccessMessage(updatedComment.commentId)
```

```kotlin Android
val imageAttachment = AmityComment.Attachment.IMAGE(
    fileId = fileId,
    image = null
)

AmitySocialClient.newCommentRepository()
    .editComment(commentId = commentId)
    .text(text = "Updated with an image")
    .attachments(imageAttachment)
    .build()
    .apply()
    .subscribe(
        { updatedComment -> showSuccessMessage(updatedComment.getCommentId()) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
await AmitySocialClient.newCommentRepository()
    .updateComment(commentId: commentId)
    .text('Updated with an image')
    .attachments([
      CommentImageAttachment(fileId: fileId),
    ])
    .build()
    .update();
```


## Clear Optional Fields

Different SDKs distinguish between "leave this field unchanged" and "replace this field with an empty value."

| Change | Pattern |
| --- | --- |
| Leave text unchanged | Do not set the text field in the update options |
| Remove text from a media comment | Set text to an empty string |
| Leave attachments unchanged | Do not set the attachments field |
| Remove all attachments | Set attachments to an empty list where the platform exposes that update shape |
| Remove metadata | Set metadata to an empty object/dictionary |
| Remove links | Set links to an empty list where the platform exposes link updates |

## Notes

- For TypeScript image attachment updates, build the attachment payload using the same uploaded-file shape as comment creation.
- For iOS, Android, and Flutter, `nil` / unset attachment fields leave existing attachments unchanged; an explicit empty list removes attachments.
- Rebuild mention and link payloads from the edited text before updating a comment.
- Handle permission, not-found, and moderation errors from the SDK call rather than relying only on client-side checks.

## Related Topics

    Soft delete or permanently delete comments where supported.
    Query comments and include deleted comments when needed.
    Upload images before attaching them to comments.
    Create top-level comments and replies.
    Approve or decline comments held for moderator review.

---

### [Delete Comment](https://learn.social.plus/social-plus-sdk/social/content-management/comments/actions/delete-comment)

> Delete comments with the platform-supported soft delete and hard delete APIs.

Use comment deletion when a user removes their own comment or a moderation flow removes a comment. Soft delete marks the comment as deleted while preserving enough state for collections and audit-style views. Hard delete permanently removes the comment where the SDK exposes that operation.

## Platform Support

| Platform | Soft delete | Hard delete |
| --- | --- | --- |
| TypeScript | `CommentRepository.softDeleteComment(commentId)` or `deleteComment(commentId)` | `CommentRepository.hardDeleteComment(commentId)` or `deleteComment(commentId, true)` |
| iOS | `softDeleteComment(withId:)` | `hardDeleteComment(withId:)` |
| Android | `softDeleteComment(commentId)` | `hardDeleteComment(commentId)` |
| Flutter | `comment.delete()` | Not exposed as a verified separate public delete path |

  Hard delete is permanent. Confirm the action in your UI before calling a hard-delete API.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Soft delete | `commentId` | Yes | Comment ID to soft delete. |
| Hard delete | `commentId` | Yes | Comment ID to hard delete where supported. |
| Query deleted comments | `referenceId` | Yes | Target content ID whose comments should be queried. |
| Query deleted comments | `referenceType` | Yes | Target content type, such as `post`. |
| Query deleted comments | `includeDeleted` | Yes | Include soft-deleted comments in query results. |

## Soft Delete

Soft delete a comment when the UI should preserve deleted-state semantics in comment collections.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const deletedComment = await CommentRepository.softDeleteComment(commentId);

renderResults(deletedComment);
```

```swift iOS
try await commentRepository.softDeleteComment(withId: "comment-id")
showSuccessMessage("Comment deleted")
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .softDeleteComment(commentId = commentId)
    .subscribe(
        { showSuccessMessage(commentId) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final comment = await AmitySocialClient.newCommentRepository()
    .getComment(commentId: commentId);

await comment.delete();
```


## Hard Delete

Hard delete is available in TypeScript, iOS, and Android.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const deletedComment = await CommentRepository.hardDeleteComment(commentId);

renderResults(deletedComment);
```

```swift iOS
try await commentRepository.hardDeleteComment(withId: "comment-id")
showSuccessMessage("Comment permanently deleted")
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .hardDeleteComment(commentId = commentId)
    .subscribe(
        { showSuccessMessage(commentId) },
        { error -> handleGeneralError(error) }
    )
```


## Query Deleted Comments

Use the query API with deleted comments included when you need moderation or audit views.


```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getComments(
  {
    referenceType: "post",
    referenceId: postId,
    includeDeleted: true,
    pageSize: 10,
  },
  ({ data: comments, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    renderResults(comments);
  },
);
```

```swift iOS
let options = AmityCommentQueryOptions(
    referenceId: "post-id",
    referenceType: .post,
    filterByParentId: false,
    orderBy: .descending,
    includeDeleted: true,
    pageSize: 20
)

token = commentRepository
    .getComments(with: options)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId = postId)
    .includeDeleted(includeDeleted = true)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final comments = await AmitySocialClient.newCommentRepository()
    .getComments()
    .post(postId)
    .includeDeleted(true)
    .query(limit: 10);

final resultCount = comments.length;
```


## Notes

- Handle not-found, permission, and moderation errors from the SDK call.
- Query live collections after deletion if the UI needs to reflect deleted-state changes.
- Use soft delete for reversible moderation workflows; reserve hard delete for cases where permanent removal is intended and supported on that platform.
- The Flutter public comment extension exposes `delete()` for the comment instance; do not rely on a separate Flutter hard-delete path unless your SDK version documents one.

## Related Topics

    Update text, metadata, mentions, links, and image attachments.
    Query comments with deleted-state filtering.
    Retrieve a specific comment by ID.
    Understand comment targets and model fields.

---

### [Comment Review](https://learn.social.plus/social-plus-sdk/social/content-management/comments/moderation/comment-review)

> Hold new and edited comments for moderator review, then query the review queue and approve or decline them.

Turn on comment review when a community should read a comment before anyone else does. A held comment still belongs to its author, who can keep editing it, but it stays out of comment lists and public comment counts until a reviewer approves it. Reviewers work from a community-wide queue and approve or decline by comment ID.

## Platform Support

| Platform   | Read approval status          | Query review queue                                          | Approve                                       | Decline                                                |
| ---------- | ----------------------------- | ----------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |
| TypeScript | `comment.approvalStatus`      | `CommentRepository.getCommentReviewQueue(params, callback)` | `CommentRepository.approveComment(commentId)` | `CommentRepository.declineComment(commentId, reason?)` |
| iOS        | `comment.approvalStatus`      | `commentRepository.getCommentReviewQueue(with:)`            | `commentRepository.approveComment(withId:)`   | `commentRepository.declineComment(withId:reason:)`     |
| Android    | `comment.getApprovalStatus()` | `commentRepository.getCommentReviewQueue(communityId)`      | `commentRepository.approveComment(commentId)` | `commentRepository.declineComment(commentId, reason)`  |

## Approval Lifecycle

Every comment carries an `approvalStatus`. This section is the single reference for when a comment is held, how its status moves, and what each move changes on the comment and its post. The method sections below show the calls.

### When Review Applies

A comment is held for review only when all three of these are true:

1. It is written on a post that belongs to a community. This includes replies: a reply on such a post is held under the same rule as a top-level comment.
2. That community has `needApprovalOnCommentCreation` turned on. See [Require Review for Community Comments](#require-review-for-community-comments).
3. Its author cannot review that community's comments. The community's creator, and anyone who holds `REVIEW_COMMUNITY_COMMENT` on the community, publish immediately. Community moderators hold that permission by default.

Every other comment is approved when it is written.

| Comment on | Held for review |
| --- | --- |
| A post in a community with review on, written by a member who cannot review | Yes |
| A post in a community with review on, written by the community's creator or a holder of `REVIEW_COMMUNITY_COMMENT` | No |
| A post in a community with review off | No |
| A post that is itself awaiting post review | Follows the same rule as any other post in its community |
| A post on a user's own feed | No. There is no community to carry the setting. |
| A story | No, even when the story's community has review on |
| Your own content IDs (`referenceType: "content"`) | No |

Changing the setting affects future transitions, not existing comments:

- **Turning review on** changes no existing comment. A comment written before the switch enters review only if someone who cannot review later makes an effective edit to it. See [How the Status Changes](#how-the-status-changes).
- **Turning review off** does not drain the queue. Comments already pending stay pending, stay in the review queue, and can still be approved or declined.

### Statuses

| Status   | TypeScript   | iOS         | Android    | What it means |
| -------- | ------------ | ----------- | ---------- | ------------- |
| Pending  | `"pending"`  | `.pending`  | `PENDING`  | Held for review. Its author, the community's reviewers, and network admins can fetch it by ID; everyone else gets `404`. It appears in no comment query on TypeScript, iOS, or Android, not even its author's; reviewers find it in the [review queue](#query-the-review-queue). It accepts no replies, reactions, or flags. |
| Approved | `"approved"` | `.approved` | `APPROVED` | Visible to everyone. Not terminal: an effective edit can send it back to pending. |
| Rejected | `"rejected"` | `.rejected` | `REJECTED` | Declined by a reviewer. Terminal, and the comment is deleted at the same time. |

  The server omits `approvalStatus` on a comment that has never been through
  review, which includes every comment written before this feature. Every SDK
  reads an absent value as **approved**. Read the value from the SDK model, not
  the field's presence on the raw payload, and do not write your own defaulting.

### Comment Queries Show Approved Comments Only

The TypeScript, iOS, and Android SDKs filter comment queries to approved comments, for every viewer, including the author of a pending comment. The same applies to a post's latest-comment previews and to reply lists. You do not need to filter pending comments out yourself, and you cannot get one back through a comment query.

To show an author their own pending comment, keep the comment that create or edit returns and render it outside the list, for example with an "Awaiting review" label. Reviewers read pending comments through the [review queue](#query-the-review-queue).

### How the Status Changes

```mermaid
stateDiagram-v2
    direction LR
    [*] --> Approved: Review does not apply
    [*] --> Pending: Review applies
    Pending --> Approved: Approve
    Pending --> Rejected: Decline
    Pending --> Pending: Author edits
    Approved --> Pending: Effective edit
    Rejected --> [*]
```

| From | Trigger | Result |
| --- | --- | --- |
| New comment | Written where [review applies](#when-review-applies) | `pending` |
| New comment | Written anywhere else, or by someone who can review | `approved` |
| `pending` | A reviewer approves | `approved` |
| `pending` | A reviewer declines | `rejected`, and the comment is deleted |
| `pending` | The author edits | Stays `pending` and keeps its place in the queue. Refused with `403` / `400300` when the network's `isAllowEditCommentWhenReviewingEnabled` is `false`. |
| `pending` | The author or a moderator deletes it | Deleted, and removed from the review queue |
| `approved` | An effective edit by someone who cannot review, while the community has review on | `pending`. The comment leaves public comment lists and returns to the top of the review queue. |
| `approved` | An edit that changes nothing, or an edit by someone who can review | Stays `approved` |
| `approved` or `rejected` | Approve or decline again | Refused with `403` / `400300` |
| `rejected` | Anything | Nothing. A rejected comment cannot be approved, edited, or restored. |

  An edit is **effective** when it changes the comment's text, or when it sends
  attachments, links, or metadata at all, even the same values as before. An
  edit that sends only unchanged text leaves the status as it is.

### What Approving or Declining Changes

Only `approvalStatus` records the outcome on the comment. The other changes land on visibility, counts, and events.

| What changes | Approve (`pending` → `approved`) | Decline (`pending` → `rejected`) | Re-review (`approved` → `pending`) |
| --- | --- | --- | --- |
| `approvalStatus` | `approved` | `rejected` | `pending` |
| Who sees it | Everyone | No one: the comment is deleted | Author, reviewers, and network admins by ID only; it leaves every comment query |
| `isDeleted` | Unchanged (`false`) | `true`, and its attachments are removed | Unchanged (`false`) |
| Position in the thread | Where it was written, because `createdAt` does not change | Not shown | Keeps its `createdAt` |
| `post.commentsCount` and the parent's reply count | Increase by one for everyone | Unchanged; a pending comment was never counted | Decrease by one until it is approved again |
| Realtime event | `comment.approved` | A comment deletion. There is no `comment.declined` event. | A comment update carrying the `pending` status |
| Notifications | Sent now, on the first approval only; none are sent while a comment is pending | None | None |

The reviewer who decided, the time of the decision, and the decline `reason` are kept for the moderation record only. No SDK returns them.

## Permission

Reading the queue and deciding on a comment both require the `REVIEW_COMMUNITY_COMMENT` permission on the target community. A client-side check is for hiding controls only; the server enforces the permission on every call, and a reviewer can never review their own comment.


{/* doc-as-test: skip (comment review ships after the currently pinned Android SDK) */}

```kotlin Android
import com.amity.socialcloud.sdk.model.core.permission.AmityPermission

AmityCoreClient
    .hasPermission(permission = AmityPermission.REVIEW_COMMUNITY_COMMENT)
    .atCommunity(communityId = communityId)
    .check()
    .doOnNext { canReview: Boolean ->
        showSuccessMessage(canReview)
    }
    .subscribe()
```

{/* doc-as-test: skip (comment review ships after the currently pinned iOS SDK) */}

```swift iOS
let canReview = await client.hasPermission(
    .reviewCommunityComment,
    forCommunity: "community-id"
)

showSuccessMessage(canReview)
```

```typescript TypeScript
const canReview = client
  .hasPermission(Amity.Permission.ReviewCommunityCommentPermission)
  .community(communityId);

renderResults(canReview);
```


## Require Review for Community Comments

Set `needApprovalOnCommentCreation` when you create or update the community. After it is on, new comments and effective edits in that community enter the queue, unless their author can review the community's comments. See [Approval Lifecycle](#approval-lifecycle) for the full rule.


{/* doc-as-test: skip (comment review ships after the currently pinned Android SDK) */}

```kotlin Android
AmitySocialClient.newCommunityRepository()
    .editCommunity(communityId = "community-id")
    .isCommentReviewEnabled(isCommentReviewEnabled = true)
    .build()
    .apply()
    .doOnSuccess { community: AmityCommunity ->
        renderResults(community.isCommentReviewEnabled())
    }
    .subscribe()
```

{/* doc-as-test: skip (comment review ships after the currently pinned iOS SDK) */}

```swift iOS
let updateOptions = AmityCommunityUpdateOptions()
updateOptions.setNeedApprovalOnCommentCreation(true)

let community = try await communityRepository.editCommunity(
    withId: "community-id",
    options: updateOptions
)

renderResults(community.isCommentReviewEnabled)
```

```typescript TypeScript
import { CommunityRepository } from "@amityco/ts-sdk";

const { data: community } = await CommunityRepository.updateCommunity(
  communityId,
  {
    needApprovalOnCommentCreation: true,
  },
);

renderResults(community.needApprovalOnCommentCreation);
```


  Turning the setting off does not drain the queue. Comments already waiting
  stay waiting, and the review queue keeps serving them until each one is
  decided.

## Read Approval Status on a Comment

Read the status on any comment you hold — including the one returned by create and edit — before you show it as published. In a community that requires review, a create or an effective edit comes back pending.

In a community that requires review, create comments with optimistic creation turned off. An optimistic create writes a local comment before the server answers, and the SDK cannot determine that comment's approval status yet; the correct status is reflected once the server responds. With optimistic creation off, nothing is written locally until the server confirms the comment, so the comment you receive already carries its approval status.

| Platform | Turn optimistic creation off |
| --- | --- |
| Android | Call `.isOptimistic(false)` on the comment creator builder |
| iOS | Pass `isOptimistic: false` to `AmityCommentCreateOptions` |
| TypeScript | Pass `false` as the second argument: `createComment(bundle, false)` |


{/* doc-as-test: skip (comment review ships after the currently pinned Android SDK) */}

```kotlin Android
import com.amity.socialcloud.sdk.api.social.comment.review.AmityCommentApprovalStatus

AmitySocialClient.newCommentRepository()
    .createComment()
    .post(postId = postId)
    .with()
    .text(text = "Hello world!")
    .isOptimistic(isOptimistic = false) // wait for the server's approval status
    .build()
    .send()
    .subscribe(
        { comment ->
            when (comment.getApprovalStatus()) {
                AmityCommentApprovalStatus.PENDING ->
                    showSuccessMessage("Awaiting review — only you can see this comment")
                AmityCommentApprovalStatus.APPROVED -> showSuccessMessage(comment.getCommentId())
                AmityCommentApprovalStatus.REJECTED -> showSuccessMessage("declined")
            }
        },
        { error -> handleGeneralError(error) },
    )
```

{/* doc-as-test: skip (comment review ships after the currently pinned iOS SDK) */}

```swift iOS
let options = AmityCommentCreateOptions(
    referenceId: "post-id",
    referenceType: .post,
    text: "Hello world!",
    isOptimistic: false // wait for the server's approval status
)

let comment = try await commentRepository.createComment(with: options)

switch comment.approvalStatus {
case .pending:
    showSuccessMessage("Awaiting review — only you can see this comment")
case .approved:
    showSuccessMessage(comment.commentId)
case .rejected:
    showSuccessMessage("declined")
}
```

```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: comment } = await CommentRepository.createComment(
  {
    referenceId: postId,
    referenceType: "post",
    data: { text: "Hello world!" },
  },
  false, // isOptimistic: wait for the server's approval status
);

if (comment.approvalStatus === "pending") {
  renderResults("Awaiting review — only you can see this comment");
} else {
  renderResults(comment);
}
```


## Query the Review Queue

List a community's pending comments, newest first by when each entered the queue. A comment sent back for re-review returns to the top.

| Input | Required | Description |
| --- | --- | --- |
| `communityId` | Yes | Community whose pending comments to list. |
| `postId` | No | Narrows the queue to one post. A post from another community returns an empty list, not an error. |
| `startDate` / `endDate` | No | Filter on when the comment was **written**, not when it entered the queue. `endDate` includes the whole calendar day. |
| `timeZone` | No | IANA time-zone name the date filters are read in. Defaults to `UTC`. |
| Page size | No | Defaults to **10** on this route, not the SDK-wide 20, and is capped at 100. | The queue is community-wide unless you narrow it to one post, and it stays readable after the community's review setting is turned off.


{/* doc-as-test: skip (comment review ships after the currently pinned Android SDK) */}

```kotlin Android
import org.joda.time.DateTime

AmitySocialClient.newCommentRepository()
    .getCommentReviewQueue(communityId = communityId)
    .startDate(startDate = DateTime.parse("2026-09-01"))
    .endDate(endDate = DateTime.parse("2026-09-30"))
    .timeZone(timeZone = "Asia/Bangkok")
    .pageSize(pageSize = 10)
    .build()
    .query()
    .subscribe(
        { pagingData -> getPagingData(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

{/* doc-as-test: skip (comment review ships after the currently pinned iOS SDK) */}

```swift iOS
let options = AmityCommentReviewQueueQueryOptions(
    communityId: "community-id",
    postId: nil,
    startDate: nil,
    endDate: nil,
    timeZone: "Asia/Bangkok",
    pageSize: 10
)

token = commentRepository.getCommentReviewQueue(with: options).observe { collection, error in
    if let error = error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const unsubscribe = CommentRepository.getCommentReviewQueue(
  {
    communityId,
    startDate: "2026-09-01",
    endDate: "2026-09-30",
    timeZone: "Asia/Bangkok",
    limit: 10,
  },
  ({ data: comments, loading, error, onNextPage, hasNextPage }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(comments);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);
```


## Approve or Decline a Comment

Approve to reveal the comment to everyone and move the post's comment count by one. Decline to reject it — a declined comment is deleted at the same time. [What Approving or Declining Changes](#what-approving-or-declining-changes) lists every effect of both.

Both calls take the comment ID. Decline also takes an optional `reason`, at most 250 characters, kept for the moderation record only.

Neither call is idempotent. A second decision on a comment that was already decided is refused, so two reviewers acting at once cannot both record an outcome.


{/* doc-as-test: skip (comment review ships after the currently pinned Android SDK) */}

```kotlin Android
AmitySocialClient.newCommentRepository()
    .approveComment(commentId = commentId)
    .subscribe(
        { showSuccessMessage(commentId) },
        { error -> handleGeneralError(error) }
    )

AmitySocialClient.newCommentRepository()
    .declineComment(commentId = commentId, reason = "Off-topic")
    .subscribe(
        { showSuccessMessage(commentId) },
        { error -> handleGeneralError(error) }
    )
```

{/* doc-as-test: skip (comment review ships after the currently pinned iOS SDK) */}

```swift iOS
try await commentRepository.approveComment(withId: "comment-id")
try await commentRepository.declineComment(withId: "comment-id", reason: "Off-topic")

showSuccessMessage()
```

```typescript TypeScript
import { CommentRepository } from "@amityco/ts-sdk";

const { data: approvedComment } =
  await CommentRepository.approveComment(commentId);

const { data: declinedComment } = await CommentRepository.declineComment(
  commentId,
  "Off-topic",
);

renderResults([approvedComment, declinedComment]);
```


## Related SDK Functions

Comment review changes how several other comment, post, and community APIs behave. The reference for each is on its own page; this table says only how review affects it.

| Function | How comment review affects it | Reference |
| --- | --- | --- |
| Query comments (`getComments`) | Returns approved comments only, for every viewer including the author, on TypeScript, iOS, and Android. You do not filter pending comments out yourself. Show an author their own pending comment from the object create or edit returns. | [Query Comments](/social-plus-sdk/social/content-management/comments/retrieval/query-comments) |
| Get a comment by ID | Its author, the community's reviewers, and network admins get a pending comment; everyone else gets `404`, which does not mean the comment was deleted. | [Get Comment](/social-plus-sdk/social/content-management/comments/retrieval/get-comment) |
| Create a comment or reply | Comes back `pending` where review applies. In a community that requires review, create with optimistic creation off: an optimistic create cannot determine the comment's approval status until the server responds. A reply to a pending comment is refused. | [Create Comment](/social-plus-sdk/social/content-management/comments/creation/create-comment) · [Read Approval Status on a Comment](#read-approval-status-on-a-comment) |
| Edit a comment | An effective edit sends an approved comment back to `pending`. Editing a pending comment fails when the network's `isAllowEditCommentWhenReviewingEnabled` social setting is `false`. | [Edit Comment](/social-plus-sdk/social/content-management/comments/actions/edit-comment) |
| Delete a comment | The author or a moderator can delete a pending comment; it leaves the review queue. A decline also arrives as a deletion. | [Delete Comment](/social-plus-sdk/social/content-management/comments/actions/delete-comment) |
| Add a reaction | Refused on a pending comment: `400` for its author, `404` for everyone else. | [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions) |
| Flag a comment | Refused on a pending comment. | [Flag a Comment](/social-plus-sdk/social/content-management/moderation/content-flagging#flag-a-comment) |
| Post comment counts (`commentsCount`, `getLocalCommentCount`) | `post.commentsCount` counts approved comments only, for everyone. `getLocalCommentCount(includePending: true)` adds the current user's own pending comments. | [Live Comment Count](/social-plus-sdk/social/content-management/posts/overview#live-comment-count) |
| Create or update a community | Carries the comment review setting: `needApprovalOnCommentCreation` on TypeScript, `setNeedApprovalOnCommentCreation(_:)` on iOS, and `isCommentReviewEnabled(_:)` on Android. | [Update Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/update-community) · [Require Review](#require-review-for-community-comments) |
| Check a permission (`hasPermission`) | `REVIEW_COMMUNITY_COMMENT` decides who can read the queue and decide, and whose own comments skip review. | [Roles and Permissions](/social-plus-sdk/core-concepts/user-management/roles-permissions) · [Permission](#permission) |
| Subscribe to a realtime topic | Without a community or post comment subscription, approvals and declines do not reach the client. | [Social Realtime Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events) |

## Related Topics

    title="Post Review"
    href="/social-plus-sdk/social/content-management/posts/moderation/post-review"
    icon="gavel"
  >
    Approve, decline, and query posts held for community review.
    title="Edit Comment"
    href="/social-plus-sdk/social/content-management/comments/actions/edit-comment"
    icon="pen"
  >
    Update comment text and attachments, and see when an edit needs review
    again.
    title="Query Comments"
    href="/social-plus-sdk/social/content-management/comments/retrieval/query-comments"
    icon="filter"
  >
    List comments and replies on a post, story, or custom content ID.
    title="Social Realtime Events"
    href="/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events"
    icon="bolt"
  >
    Subscribe to community and post topics so comment events reach the client.

## Social — Stories

### [Stories Overview](https://learn.social.plus/social-plus-sdk/social/content-management/stories/overview)

> Create, retrieve, analyze, and delete time-limited image and video stories with the social.plus SDKs.

Stories are time-limited media items attached to a story target. The SDKs support image and video stories, optional metadata, optional hyperlink story items, live retrieval, view/link analytics, and soft or hard deletion.

The examples in this section use community targets, which are the common target shape across the SDKs covered here.

For a product-level walkthrough, see [Stories & Ephemeral Content](/use-cases/social/stories-and-ephemeral-content). The pages in this SDK section stay focused on exact SDK methods and data shapes.

    Publish image or video stories with optional metadata and hyperlink items.
    Observe individual stories, active story collections, story targets, and global story targets.
    Mark stories as seen, mark hyperlink clicks, and query reached users where supported.

## Story Model

The exact accessor style differs by platform, but story objects expose the same main concepts:

| Field | Description |
|-------|-------------|
| `storyId` | Unique story identifier. |
| `targetType` / `targetId` | Target that owns the story. The SDK examples use `community`. |
| `dataType` | Story content type, such as image or video. |
| `data` | Media-specific story data, including image/video file references where available. |
| `items` / `storyItems` | Interactive story items such as hyperlinks. |
| `metadata` | Custom metadata provided during creation. |
| `syncState` / `state` | Local creation state such as syncing, synced, or failed. |
| `isDeleted` | Whether the story is deleted. |
| `isSeen` | Whether the current user has seen the story. |
| `impression` | Total view count exposed on the story model. |
| `reach` | Unique reached-user count exposed on the story model. |
| `expiresAt`, `createdAt`, `updatedAt` | Story lifecycle timestamps. |

## Story Target Model

Story targets represent story availability for a target such as a community.

| Field | Description |
|-------|-------------|
| `targetType` / `targetId` | Target identity. |
| `hasUnseen` | Whether the current user has unseen stories for this target. |
| `syncingStoriesCount` | Local stories still syncing for this target. |
| `failedStoriesCount` | Local stories that failed to sync for this target. |
| `updatedAt` | Last target update timestamp. |

## SDK Surface

| Workflow | TypeScript | iOS | Android | Flutter |
|----------|------------|-----|---------|---------|
| Create image | `createImageStory()` | `createImageStory(options:)` | `createImageStory()` | `createImageStory()` |
| Create video | `createVideoStory()` | `createVideoStory(options:)` | `createVideoStory()` | `createVideoStory()` |
| Single story | `getStoryByStoryId()` | `getStory(storyId:)` | `getStory()` | `live.getStory()` |
| Active stories | `getActiveStoriesByTarget()` | `getActiveStoriesByTarget(...)` | `getActiveStories(...)` | `getActiveStories(...).build()` |
| Stories by targets | `getStoriesByTargetIds()` | `getStoriesByTargets(...)` | `getStoriesByTargets(...)` | `getStoriesByTargets(...).build()` |
| Story target | `getTargetById()` | `getStoryTarget(...)` | `getStoryTarget(...)` | `live.getStoryTaregt(...)` |
| Story targets | `getTargetsByTargetIds()` | `getStoryTargets(...)` | `getStoryTargets(...)` | `getStoryTargets(...).build()` |
| Global targets | `getGlobalStoryTargets()` | `getGlobalStoryTargets(option:)` | `getGlobalStoryTargets(...)` | `GlobalStoryTargetLiveCollection` |
| Analytics | `story.analytics.*` | `story.analytics.*` | `storyRepository.analytics(story).*` | `storyRepository.analytics(story).*` |

Flutter's single story-target helper is currently named `getStoryTaregt` in the shipped SDK. The spelling above is intentional.

## Accuracy Notes

- The SDK creation APIs accept image or video files and pass upload/processing errors through their platform-specific async pattern.
- File size, duration, and moderation limits are enforced by backend or network configuration. This SDK reference does not hardcode those values.
- Story analytics methods should be called on synced story objects. Native and Flutter SDKs explicitly no-op for unsynced stories.
- `SMART`, `UNSEEN`, `SEEN`, and `ALL` query options apply to global story target retrieval.

## Related Topics

    Publish image and video stories.
    Retrieve story live objects and collections.
    Retrieve target-level story availability and unseen status.
    Record story views, link clicks, and reached users.

---

### [Create Story](https://learn.social.plus/social-plus-sdk/social/content-management/stories/creation/create-story)

> Create image and video stories with StoryRepository creation APIs.

Use the story repository to create image or video stories for a target. The examples below use community targets, optional metadata, and an optional hyperlink story item.

Story creation is optimistic on the SDKs that maintain local story state. Watch the returned story or active story collection for sync state changes such as syncing, synced, or failed.

## Parameters

| Concept | TypeScript | iOS | Android | Flutter |
|---------|------------|-----|---------|---------|
| Target type | `'community'` | `.community` | `AmityStory.TargetType.COMMUNITY` | `AmityStoryTargetType.COMMUNITY` |
| Target ID | `string` | `String` | `String` | `String` |
| Image input | `FormData` with `files` | `imageFileURL` | `imageUri` | `imageFile` |
| Video input | `FormData` with `files` | `videoFileURL` | `videoUri` | `videoFile` |
| Metadata | Object | `[String: Any]?` | `JsonObject?` | `Map<String, dynamic>?` |
| Hyperlinks | `Amity.StoryItemType.Hyperlink` | `AmityHyperLinkItem` | `AmityStoryItem.HYPERLINK` | `HyperLink` |

For TypeScript, append the file under the `files` key. The SDK throws if the `FormData` object has no `files` entry.

## Create image story

Create an image story from a local image file, target, and optional metadata or hyperlink items.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const formData = new FormData();
formData.append('files', imageFile);

const result = await StoryRepository.createImageStory(
  'community',
  communityId,
  formData,
  { campaignId: 'launch' },
  'fit',
  [
    {
      type: Amity.StoryItemType.Hyperlink,
      data: {
        url: 'https://example.com',
        customText: 'Learn more',
      },
    },
  ],
);

renderResults(result.data);
```

```swift iOS
let items: [AmityStoryItem] = [
    AmityHyperLinkItem(url: "https://example.com", customText: "Learn more")
]

let imageURL = URL(fileURLWithPath: "/path/to/image.jpg")
let options = AmityImageStoryCreateOptions(
    targetType: .community,
    targetId: communityId,
    imageFileURL: imageURL,
    metadata: ["campaignId": "launch"],
    items: items,
    imageDisplayMode: .fit
)

let story = try await storyRepository.createImageStory(options: options)
showSuccessMessage(story.storyId)
```

```kotlin Android
fun createImageStory(
    storyRepository: AmityStoryRepository,
    targetId: String,
    imageUri: Uri
) {
    storyRepository.createImageStory(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        imageUri = imageUri,
        storyItems = listOf(
            AmityStoryItem.HYPERLINK(
                url = "https://example.com",
                customText = "Learn more"
            )
        ),
        imageDisplayMode = AmityStoryImageDisplayMode.FIT,
        metadata = JsonObject().apply {
            addProperty("campaignId", "launch")
        }
    )
        .doOnComplete { showSuccessMessage("Story created") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
import 'dart:io';

Future<void> createImageStory(String communityId) async {
  final storyRepository = AmitySocialClient.newStoryRepository();

  await storyRepository.createImageStory(
    targetType: AmityStoryTargetType.COMMUNITY,
    targetId: communityId,
    imageFile: File('/path/to/image.jpg'),
    imageDisplayMode: AmityStoryImageDisplayMode.FIT,
    metadata: {'campaignId': 'launch'},
    storyItems: [
      HyperLink(
        url: 'https://example.com',
        customText: 'Learn more',
      ),
    ],
  );
}
```


## Create video story

Create a video story from a local video file, target, and optional metadata or hyperlink items.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const formData = new FormData();
formData.append('files', videoFile);

const result = await StoryRepository.createVideoStory(
  'community',
  communityId,
  formData,
  { campaignId: 'launch' },
  [
    {
      type: Amity.StoryItemType.Hyperlink,
      data: {
        url: 'https://example.com',
        customText: 'Watch more',
      },
    },
  ],
);

renderResults(result.data);
```

```swift iOS
let items: [AmityStoryItem] = [
    AmityHyperLinkItem(url: "https://example.com", customText: "Watch more")
]

let videoURL = URL(fileURLWithPath: "/path/to/video.mp4")
let options = AmityVideoStoryCreateOptions(
    targetType: .community,
    targetId: communityId,
    videoFileURL: videoURL,
    metadata: ["campaignId": "launch"],
    items: items
)

let story = try await storyRepository.createVideoStory(options: options)
showSuccessMessage(story.storyId)
```

```kotlin Android
fun createVideoStory(
    storyRepository: AmityStoryRepository,
    targetId: String,
    videoUri: Uri
) {
    storyRepository.createVideoStory(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        videoUri = videoUri,
        storyItems = listOf(
            AmityStoryItem.HYPERLINK(
                url = "https://example.com",
                customText = "Watch more"
            )
        ),
        metadata = JsonObject().apply {
            addProperty("campaignId", "launch")
        }
    )
        .doOnComplete { showSuccessMessage("Story created") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
import 'dart:io';

Future<void> createVideoStory(String communityId) async {
  final storyRepository = AmitySocialClient.newStoryRepository();

  await storyRepository.createVideoStory(
    targetType: AmityStoryTargetType.COMMUNITY,
    targetId: communityId,
    videoFile: File('/path/to/video.mp4'),
    metadata: {'campaignId': 'launch'},
    storyItems: [
      HyperLink(
        url: 'https://example.com',
        customText: 'Watch more',
      ),
    ],
  );
}
```


## Hyperlink items

Story hyperlink items contain:

| Field | Description |
|-------|-------------|
| `url` | Destination URL. |
| `customText` | Optional text shown for the link. |

## Related topics

    Observe created stories and sync state.
    Mark synced stories as seen and track link clicks.

---

### [Get Stories](https://learn.social.plus/social-plus-sdk/social/content-management/stories/retrieval/get-stories)

> Retrieve individual stories, active stories for one target, or stories across multiple targets.

Story retrieval APIs return live objects or live collections. Use a single-story API when you already have a `storyId`, active-story APIs for a target's current stories, and multi-target APIs when building a story tray across communities.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Single story | `storyId` | Yes | Story ID to observe as a live object or stream. |
| Active stories for a target | `targetType` | Yes | Story target type, such as community. |
| Active stories for a target | `targetId` | Yes | Target ID whose active stories should be retrieved. |
| Active stories for a target | Sort/order option | No | Sort order for returned active stories where exposed. |
| Stories across targets | `targets` | Yes | Target type and target ID pairs to retrieve in one request. |
| Stories across targets | Sort/order option | No | Sort order for returned stories where exposed. |

## Single Story

Observe a single story when your UI already has a `storyId` and needs live story state.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoryByStoryId(storyId, ({ data, loading, error }) => {
  if (error) {
    handleError(error);
    return;
  }

  if (!loading && data) {
    updateUI(data);
  }
});

unsubscribe();
```

```swift iOS
token = storyRepository.getStory(storyId: "story-id").observe { object, error in
    if let error {
        handleError(error)
        return
    }

    if let story = object.snapshot {
        showSuccessMessage(story.storyId)
    }
}
```

```kotlin Android
fun observeStory(
    storyRepository: AmityStoryRepository,
    storyId: String
) {
    storyRepository.getStory(storyId = storyId)
        .doOnNext { story: AmityStory ->
            showSuccessMessage(story.getStoryId())
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeStory(String storyId) {
  final stream = AmitySocialClient.newStoryRepository().live.getStory(storyId);

  stream.listen((story) {
    final currentStoryId = story.storyId;
    showError(currentStoryId ?? '');
  });
}
```


## Active Stories for a Target

Active-story APIs retrieve non-expired stories for one target. They are the usual choice for rendering a viewer after the user opens a story ring.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getActiveStoriesByTarget(
  {
    targetType: 'community',
    targetId: communityId,
    options: {
      sortBy: 'createdAt',
      orderBy: 'desc',
    },
  },
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }
  },
);

unsubscribe();
```

```swift iOS
token = storyRepository
    .getActiveStoriesByTarget(
        targetType: .community,
        targetId: communityId,
        sortOption: .lastCreated
    )
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
fun observeActiveStories(
    storyRepository: AmityStoryRepository,
    targetId: String
) {
    storyRepository.getActiveStories(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId,
        sortOption = AmityStorySortOption.LAST_CREATED
    )
        .doOnNext { stories: PagingData<AmityStory> ->
            getPagingData(stories)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeActiveStories(String communityId) {
  final collection = StoryLiveCollection(
    request: () => AmitySocialClient.newStoryRepository()
        .getActiveStories(
          targetId: communityId,
          targetType: AmityStoryTargetType.COMMUNITY,
          orderBy: AmityStorySortingOrder.LAST_CREATED,
        )
        .build(),
  );

  collection.getStreamController().stream.listen((stories) {
    final visibleCount = stories.length;
    showError(visibleCount);
  });

  collection.getData();
}
```


## Stories Across Targets

Use the multi-target APIs when you need stories from multiple targets in one live collection.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoriesByTargetIds(
  {
    targets: [
      { targetType: 'community', targetId: communityId },
      { targetType: 'community', targetId: 'community-id-2' },
    ],
    options: {
      sortBy: 'createdAt',
      orderBy: 'desc',
    },
  },
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }
  },
);

unsubscribe();
```

```swift iOS
let targets = [
    AmityStoryTargetSearchInfo(targetType: .community, targetId: communityId),
    AmityStoryTargetSearchInfo(targetType: .community, targetId: "community-id-2")
]

token = storyRepository
    .getStoriesByTargets(targets: targets, sortOption: .lastCreated)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
fun observeStoriesByTargets(storyRepository: AmityStoryRepository) {
    val targets = listOf(
        AmityStory.TargetType.COMMUNITY to "community-id-1",
        AmityStory.TargetType.COMMUNITY to "community-id-2"
    )

    storyRepository.getStoriesByTargets(
        targets = targets,
        sortOption = AmityStorySortOption.LAST_CREATED
    )
        .doOnNext { stories: List<AmityStory> ->
            showSuccessMessage(stories.size)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeStoriesByTargets() {
  final targets = [
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-1',
    ),
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-2',
    ),
  ];

  final collection = StoryLiveCollection(
    request: () => AmitySocialClient.newStoryRepository()
        .getStoriesByTargets(
          targets: targets,
          orderBy: AmityStorySortingOrder.LAST_CREATED,
        )
        .build(),
  );

  collection.getStreamController().stream.listen((stories) {
    final visibleCount = stories.length;
    showError(visibleCount);
  });

  collection.getData();
}
```


## Notes

- Active-story APIs include local optimistic stories where the platform SDK supports optimistic creation.
- Multi-target APIs return synced stories across the requested targets.
- Use story target APIs when you only need ring state such as `hasUnseen`.

## Related Topics

    Retrieve target-level story availability and unseen state.
    Track views and reached users for stories.

---

### [Get Story Targets](https://learn.social.plus/social-plus-sdk/social/content-management/stories/retrieval/get-story-targets)

> Retrieve story target state, including unseen status and local sync counts.

Story target APIs let you render story rings without fetching every story. A story target tells you whether a target has unseen stories and, where supported, how many local stories are syncing or failed.

The examples below use community targets.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Single story target | `targetType` | Yes | Story target type, such as community. |
| Single story target | `targetId` | Yes | Target ID whose story state should be observed. |
| Multiple story targets | `targets` | Yes | Target type and target ID pairs to observe together. |

## Single Story Target

Observe one story target when rendering a story ring for a known community or user target.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getTargetById(
  {
    targetType: 'community',
    targetId: communityId,
  },
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && data) {
      updateUI(data.hasUnseen);
    }
  },
);

unsubscribe();
```

```swift iOS
token = storyRepository
    .getStoryTarget(targetType: .community, targetId: communityId)
    .observe { object, error in
        if let error {
            handleError(error)
            return
        }

        if let storyTarget = object.snapshot {
            showSuccessMessage(storyTarget.hasUnseen)
        }
    }
```

```kotlin Android
fun observeStoryTarget(
    storyRepository: AmityStoryRepository,
    targetId: String
) {
    storyRepository.getStoryTarget(
        targetType = AmityStory.TargetType.COMMUNITY,
        targetId = targetId
    )
        .doOnNext { storyTarget: AmityStoryTarget ->
            showSuccessMessage(storyTarget.hasUnseen())
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeStoryTarget(String communityId) {
  final stream = AmitySocialClient.newStoryRepository().live.getStoryTaregt(
    targetType: AmityStoryTargetType.COMMUNITY,
    targetId: communityId,
  );

  stream.listen((storyTarget) {
    final hasUnseen = storyTarget.hasUnseen;
    showError(hasUnseen);
  });
}
```


Flutter's single-target live helper is spelled `getStoryTaregt` in the current SDK.

## Multiple Story Targets

Observe multiple story targets when building a tray that shows state for several targets at once.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getTargetsByTargetIds(
  [
    { targetType: 'community', targetId: communityId },
    { targetType: 'community', targetId: 'community-id-2' },
  ],
  ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }
  },
);

unsubscribe();
```

```swift iOS
let targets = [
    AmityStoryTargetSearchInfo(targetType: .community, targetId: communityId),
    AmityStoryTargetSearchInfo(targetType: .community, targetId: "community-id-2")
]

token = storyRepository.getStoryTargets(targets: targets).observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
fun observeStoryTargets(storyRepository: AmityStoryRepository) {
    val targets = listOf(
        AmityStory.TargetType.COMMUNITY to "community-id-1",
        AmityStory.TargetType.COMMUNITY to "community-id-2"
    )

    storyRepository.getStoryTargets(targets = targets)
        .doOnNext { storyTargets: List<AmityStoryTarget> ->
            showSuccessMessage(storyTargets.size)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeStoryTargets() {
  final targets = [
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-1',
    ),
    StoryTargetSearchInfo(
      targetType: AmityStoryTargetType.COMMUNITY,
      targetId: 'community-id-2',
    ),
  ];

  final collection = StoryTargetLiveCollection(
    request: () => AmitySocialClient.newStoryRepository()
        .getStoryTargets(targets: targets),
  );

  collection.getStreamController().stream.listen((storyTargets) {
    final targetCount = storyTargets.length;
    showError(targetCount);
  });

  collection.getData();
}
```


## When to Use Story Targets

- Use story targets for story tray rings, unseen indicators, and sync/error badges.
- Use [Get Stories](./get-stories) when you need the actual story media and items.
- Use [Get Global Story Targets](./get-global-story-targets) when you need a global discovery feed of active story targets.

## Related Topics

    Retrieve story objects and collections.
    Query story targets across the app.

---

### [Get Global Story Targets](https://learn.social.plus/social-plus-sdk/social/content-management/stories/retrieval/get-global-story-targets)

> Retrieve active story targets across the app using global story target query options.

Global story target APIs return story targets across the app. Use them for discovery experiences such as a global story tray.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Query global story targets | Seen-state query option | Yes | Option such as smart, unseen, seen, or all. |
| Query global story targets | `limit` | No | TypeScript page size for global target results. |

## Query Options

| Option | Description |
|--------|-------------|
| `SMART` | Combines unseen targets first, then seen targets. |
| `UNSEEN` | Returns targets with unseen stories. |
| `SEEN` | Returns targets without unseen stories. |
| `ALL` | Returns all active story targets. |

Option casing follows each platform: TypeScript uses `Amity.StorySeenQuery.SMART`, iOS uses `.smart`, Android and Flutter use `AmityGlobalStoryTargetsQueryOption.SMART`.

## Query Global Story Targets

Query global story targets for a tray or discovery surface, using the seen-state option that matches your product sort order.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getGlobalStoryTargets(
  {
    seenState: Amity.StorySeenQuery.SMART,
    limit: 20,
  },
  ({ data, loading, error, hasNextPage, onNextPage }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);

unsubscribe();
```

```swift iOS
token = storyRepository.getGlobalStoryTargets(option: .smart).observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
fun observeGlobalStoryTargets(storyRepository: AmityStoryRepository) {
    storyRepository.getGlobalStoryTargets(
        queryOption = AmityGlobalStoryTargetsQueryOption.SMART
    )
        .doOnNext { targets: PagingData<AmityStoryTarget> ->
            getPagingData(targets)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
void observeGlobalStoryTargets() {
  final collection = GlobalStoryTargetLiveCollection(
    queryOption: AmityGlobalStoryTargetsQueryOption.SMART,
  );

  collection.getStreamController().stream.listen((storyTargets) {
    final targetCount = storyTargets.length;
    showError(targetCount);
  });

  collection.getData();
}
```


## Notes

- `SMART` is the right default for a consumer-facing global tray because it prioritizes unseen targets.
- Use `UNSEEN` for a strict "new stories only" surface.
- Use `SEEN` when you need a replay or archive-style surface of already seen active targets.
- Use `ALL` when your UI needs all active targets regardless of current user's seen state.

## Related Topics

    Retrieve specific story target state.
    Retrieve the actual story objects for one or more targets.

---

### [Delete Story](https://learn.social.plus/social-plus-sdk/social/content-management/stories/actions/delete-story)

> Soft delete or hard delete stories with StoryRepository deletion APIs.

Story repositories expose soft delete and hard delete operations. Soft delete marks a story as deleted and removes it from normal story collections. Hard delete passes the permanent-delete flag to the backend.

Treat hard delete as irreversible from the client perspective. Do not offer it in user-facing flows without confirmation.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Soft delete | `storyId` | Yes | Story ID to soft delete. |
| Hard delete | `storyId` | Yes | Story ID to hard delete after confirmation. |

## Soft Delete

Soft delete a story when the item should disappear from normal story surfaces while preserving deleted-state semantics.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const deleted = await StoryRepository.softDeleteStory(storyId);
showSuccessMessage(deleted);
```

```swift iOS
try await storyRepository.softDeleteStory(storyId: "story-id")
showSuccessMessage("Story soft deleted")
```

```kotlin Android
fun softDeleteStory(
    storyRepository: AmityStoryRepository,
    storyId: String
) {
    storyRepository.softDeleteStory(storyId = storyId)
        .doOnComplete { showSuccessMessage("Story soft deleted") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
Future<void> softDeleteStory(String storyId) async {
  await AmitySocialClient.newStoryRepository().softDeleteStory(
    storyId: storyId,
  );
}
```


## Hard Delete

Hard delete a story only after the product confirms permanent removal is intended.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const deleted = await StoryRepository.hardDeleteStory(storyId);
showSuccessMessage(deleted);
```

```swift iOS
try await storyRepository.hardDeleteStory(storyId: "story-id")
showSuccessMessage("Story hard deleted")
```

```kotlin Android
fun hardDeleteStory(
    storyRepository: AmityStoryRepository,
    storyId: String
) {
    storyRepository.hardDeleteStory(storyId = storyId)
        .doOnComplete { showSuccessMessage("Story hard deleted") }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
Future<void> hardDeleteStory(String storyId) async {
  await AmitySocialClient.newStoryRepository().hardDeleteStory(
    storyId: storyId,
  );
}
```


## Choosing a Delete Type

| Delete type | Use when |
|-------------|----------|
| Soft delete | You want the story removed from normal story surfaces while preserving delete semantics in SDK state. |
| Hard delete | You need a permanent deletion request and have confirmed the action with the user or moderator. |

## Related Topics

    Observe collections after delete operations.
    Create new story content.

---

### [Story Impressions](https://learn.social.plus/social-plus-sdk/social/content-management/stories/analytics/story-impressions)

> Mark synced stories as seen, mark story link clicks, and query reached users.

Story objects expose `impression`, `reach`, and `isSeen` state. Analytics helpers let you mark a synced story as seen and mark a story hyperlink as clicked.

Call story analytics methods on synced story objects. Native and Flutter SDKs explicitly ignore unsynced stories for these analytics calls.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Mark story as seen | Synced story object | Yes | Story object whose analytics helper records the seen event. |
| Mark story link as clicked | Synced story object | Yes | Story object whose analytics helper records the link-click event. |
| Query reached users | `viewId` / `viewedId` | Yes | Story ID used to query reached users. |
| Query reached users | `viewedType` | Yes | Viewed type value for stories. |
| Query reached users | `limit` | No | TypeScript page size for reached-user results. |

## Mark Story as Seen

Mark a synced story as seen after your UI decides the current user has viewed it.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoryByStoryId(storyId, ({ data, error }) => {
  if (error) {
    handleError(error);
    return;
  }

  data?.analytics.markAsSeen();
});

unsubscribe();
```

```swift iOS
token = storyRepository.getStory(storyId: "story-id").observe { object, error in
    if let error {
        handleError(error)
        return
    }

    object.snapshot?.analytics.markAsSeen()
}
```

```kotlin Android
fun markStoryAsSeen(
    storyRepository: AmityStoryRepository,
    story: AmityStory
) {
    storyRepository.analytics(story).markAsSeen()
}
```

```dart Flutter
void markStoryAsSeen(AmityStory story) {
  AmitySocialClient.newStoryRepository().analytics(story).markAsSeen();
}
```


## Mark Story Link as Clicked

Mark a story link as clicked when the user opens the hyperlink item from the story UI.


```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoryByStoryId(storyId, ({ data, error }) => {
  if (error) {
    handleError(error);
    return;
  }

  data?.analytics.markLinkAsClicked();
});

unsubscribe();
```

```swift iOS
token = storyRepository.getStory(storyId: "story-id").observe { object, error in
    if let error {
        handleError(error)
        return
    }

    object.snapshot?.analytics.markLinkAsClicked()
}
```

```kotlin Android
fun markStoryLinkAsClicked(
    storyRepository: AmityStoryRepository,
    story: AmityStory
) {
    storyRepository.analytics(story).markLinkAsClicked()
}
```

```dart Flutter
void markStoryLinkAsClicked(AmityStory story) {
  AmitySocialClient.newStoryRepository().analytics(story).markLinkAsClicked();
}
```


## Query Reached Users

Use reached-user APIs to retrieve users who viewed a story.


```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getReachedUsers(
  {
    viewId: storyId,
    viewedType: 'story',
    limit: 20,
  },
  ({ data, loading, error, hasNextPage, onNextPage }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading) {
      renderResults(data);
    }

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);

unsubscribe();
```

```swift iOS
token = userRepository
    .getReachedUsers(viewedType: .story, viewedId: "story-id")
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
fun queryStoryReachedUsers(
    userRepository: AmityUserRepository,
    storyId: String
) {
    userRepository.getReachedUsers(
        viewedType = AmityViewedType.STORY,
        viewedId = storyId
    )
        .doOnNext { users: PagingData<AmityUser> ->
            getPagingData(users)
        }
        .doOnError { error -> showErrorMessage(error = error) }
        .subscribe()
}
```

```dart Flutter
Future<void> queryStoryReachedUsers(String storyId) async {
  final users = await AmityCoreClient.newUserRepository()
      .getViewedUsers(
        viewedType: AmityViewedType.STORY,
        viewedId: storyId,
      )
      .query();

  showError(users.length);
}
```


## Related Topics

    Retrieve stories before recording analytics events.
    Create stories with hyperlink items.

## Social — Discovery & Feed

### [Discovery & Engagement Overview](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/overview)

> SDK surfaces for feeds, search, notification tray, and discovery-driven engagement.

Discovery and engagement APIs help users find content, communities, and activity updates. Use this overview to choose between feed retrieval, intelligent search, and notification tray APIs.

    Personalized For You feed, chronological global feed, custom-ranking global feed, and per-owner feeds.
    Search posts and communities through SDK-supported semantic search surfaces.
    Retrieve tray items, item status, tray seen status, and notification event metadata.
    Add engagement affordances on posts, comments, stories, and other supported content.

## Choose The Right Surface

| Goal | Use |
| --- | --- |
| Give each user a personalized discovery tab | [For You Feed](./feed/for-you-feed) |
| Build a real-time, newest-first feed | [Global Feed](./feed/global-feed) |
| Surface globally what people engage with | [Custom-Ranking Global Feed](./feed/custom-ranking) |
| Search communities by meaning or keyword | [Intelligent Search Community](./search/intelligent-search-community) |
| Search posts or hashtags | [Intelligent Search Post](./search/intelligent-search-post) |
| Show notifications in-app | [Notification Items](./notifications/notification-items) |
| Track tray seen/unseen state | [Notification Tray Status](./notifications/notification-tray-status) |

Platform coverage varies by surface. Each linked page includes the platform-specific SDK availability and code examples for that feature.

## Related Topics

    Compare the For You, global, and custom-ranking feeds.
    Compare post and community search options.
    Build notification tray experiences.
    Share content into feeds and engagement flows.

---

### [Feeds & Timelines](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/feed/overview)

> Choose between the personalized For You feed, the chronological global feed, and the custom-ranking global feed.

Use `AmityFeedRepository` to read feed-style post collections. Each feed is a separate SDK entry point over the same content — what changes is who the posts are selected for, and how they are ordered.

    **Personalized per user.** Surfaces the posts each member is most likely to care about — from their communities, follows, public content, and live streams — so the home feed stays relevant instead of showing everything at once. Requires the network setting.
    **Chronological.** The most recent posts come first. Use it for a real-time content stream.
    **Score-sorted.** The same global content, ordered by engagement, recency, and updates rather than by time alone.
    **Scoped to one owner.** Query posts for a single user or community, with richer filters.

## Choosing a feed

| If you need | Use | Ordering |
| --- | --- | --- |
| A discovery tab tailored to each user | [For You feed](/social-plus-sdk/social/discovery-engagement/feed/for-you-feed) | Backend-personalized and ranked |
| A live stream of everything happening now | [Global feed](/social-plus-sdk/social/discovery-engagement/feed/global-feed) | Newest first |
| A global feed that surfaces what people engage with | [Custom-ranking global feed](/social-plus-sdk/social/discovery-engagement/feed/custom-ranking) | Engagement score |
| One user's or one community's posts | [Query posts](/social-plus-sdk/social/content-management/posts/retrieval/query-posts) | Newest first, with filters |

For You feed is a network-level feature and must be enabled for your network before it returns content. The global and custom-ranking feeds are available to every network.

## Feed APIs

| Feed | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| For You feed | `FeedRepository.getForYouFeed()` | Supported | Supported | Not available |
| Global feed | `FeedRepository.getGlobalFeed()` | `AmityFeedRepository().getGlobalFeed()` | `AmitySocialClient.newFeedRepository().getGlobalFeed()` | `AmitySocialClient.newFeedRepository().getGlobalFeed()` |
| Custom-ranking global feed | `FeedRepository.getCustomRankingGlobalFeed()` | `AmityFeedRepository().getCustomRankingGlobalFeed()` | `AmitySocialClient.newFeedRepository().getCustomRankingGlobalFeed()` | `AmitySocialClient.newFeedRepository().getCustomRankingGlobalFeed()` |
| User feed | `FeedRepository.getUserFeed()` | `AmityFeedRepository().getUserFeed()` | `AmitySocialClient.newFeedRepository().getUserFeed()` | `AmitySocialClient.newFeedRepository().getUserFeed()` |
| Community feed | `FeedRepository.getCommunityFeed()` | `AmityFeedRepository().getCommunityFeed()` | `AmitySocialClient.newFeedRepository().getCommunityFeed()` | `AmitySocialClient.newFeedRepository().getCommunityFeed()` |

TypeScript still exports `queryGlobalFeed()`, but the SDK source marks it deprecated. Use the live collection APIs for new integrations.

## Notes

- Use post query APIs when you need a specific user or community feed with richer filters such as tags, review status, or deletion state.
- Dispose live collection subscriptions, notification tokens, and stream subscriptions when the screen is destroyed.
- Ranking is backend-owned on every feed that has it. Do not hardcode ranking assumptions in client UI logic.

## Related Topics

    Prebuilt newsfeed, global feed, and For You components.
    Search posts semantically or by hashtag.

---

### [Topic-based Content Discovery](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/feed/curated-content)

> Help users discover relevant community conversations through configured topics, using the SDK or the Discovery Widget.

Topic-based content discovery helps brands and community teams bring relevant conversations to the pages people already visit. Instead of relying on users to search for a community, surface posts about a topic on your homepage, category pages, or other browsing surfaces. Post previews help people understand what your community offers and decide which conversations to explore.

Your team configures a topic in the social.plus Console. The SDK uses its topic ID to fetch an ordered selection of community posts, called a **pool**. Build your own presentation with these posts, or use the UIKit's [Discovery Widget](/uikit/components/social/discovery-widget) for a ready-made carousel.

The SDK supports topic-based content discovery on **TypeScript**, **iOS**, and **Android**. Flutter and React Native are not supported.

## How recommendations are selected

Recommendations use three main signals:

- **Topic relevance:** how closely a post matches the configured topic. This is the main signal.
- **Engagement:** activity on a post, such as reactions and comments, helps identify relevant conversations people are participating in.
- **Freshness:** newer posts help keep the selection timely.

Selection is based on the configured topic rather than a reader's personal interests or engagement history. Topic configuration and eligibility rules determine which posts can appear. Viewer-specific restrictions, such as blocked authors, can further affect the returned selection.

The SDK returns posts in recommendation order. Preserve that order when presenting the recommended selection.

## Before you start

Configure a topic in the social.plus Console and obtain its topic ID. Initialize the SDK and establish a [user session](/social-plus-sdk/getting-started/authentication) or a [visitor session](/social-plus-sdk/getting-started/visitor-mode) before fetching posts.

Topic configuration is managed in the Console. This page covers reading its recommendations and reporting interactions from your app.

## Parameters

| Parameter | Type | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| `topicId` | `string` | Yes | TypeScript, iOS, Android | The topic ID configured in the Console. |
| `limit` | integer | No | TypeScript, iOS, Android | Maximum number of posts to return, from 1 to 100. Omit to use the server default. |

## Fetch recommended posts

`getPool` returns the topic and its ordered posts in a single request. It is not a live collection and does not support pagination. Call it again when your app needs a new selection.


```typescript TypeScript
import { CuratedContentRepository } from '@amityco/ts-sdk';

const pool = await CuratedContentRepository.getPool('your-topic-id', 10);
const topicName = pool.topic.topicName;
const posts = pool.posts;
```

```swift iOS
let repository = AmityCuratedContentRepository()
let pool = try await repository.getPool(topicId: "your-topic-id", limit: 10)

let topicName = pool.topic.topicName
let posts = pool.posts
```

```kotlin Android
val repository = AmityCoreClient.newCuratedContentRepository()

repository.getPool(topicId = "your-topic-id", limit = 10)
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ pool ->
        val topicName = pool.topic.topicName
        val posts = pool.posts
    }, { error ->
        // Handle the failed request in your app.
    })
```


The returned posts are standard post objects that you can render in your own UI. Results may contain fewer posts than requested, including an empty list. An empty list is a successful response; omit the discovery surface when there is no content to display.

## Report interactions

When building your own discovery surface, use the topic's analytics handle to measure what readers see and open. Report views when the surface or card becomes visible, rather than when an off-screen element is mounted.

| Method | Report when |
| --- | --- |
| `markAsViewed()` | The discovery surface becomes visible. |
| `markPostAsViewed(postId)` | A post card becomes visible. |
| `markPostClick(postId)` | The reader selects a post card. |


```typescript TypeScript
pool.topic.analytics.markAsViewed();
pool.topic.analytics.markPostAsViewed(post.postId);
pool.topic.analytics.markPostClick(post.postId);
```

```swift iOS
pool.topic.analytics.markAsViewed()
pool.topic.analytics.markPostAsViewed(postId: post.postId)
pool.topic.analytics.markPostClick(postId: post.postId)
```

```kotlin Android
val topic = pool.topic
topic.analytics().markAsViewed()
topic.analytics().markPostAsViewed(post.getPostId())
topic.analytics().markPostClick(post.getPostId())
```


Report the surface impression and each post impression once per page load. Report a click when the reader selects a card, and let navigation proceed without waiting for analytics.

The Discovery Widget reports these interactions automatically, so you do not need to report them again for that component.

## Related topics

    Embed a ready-made carousel of topic-based recommendations.
    Establish a session for readers who have not signed in.

---

### [Overview](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/search/overview)

> Use SDK search APIs for semantic post search, hashtag post search, and semantic community search.

The SDK search pages in this section cover the client-side APIs for finding posts and communities. Keep the mental model simple: search is requested through SDK repository methods, filters narrow the search scope, and the backend returns ranked results.

Semantic search availability depends on your network configuration. Confirm that the feature is enabled for your network before building UI that depends on semantic search results.

For Flutter, semantic post and community search are available from `amity_sdk` 7.8.7.

## Search Surfaces

| Surface | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Semantic community search | `CommunityRepository.semanticSearchCommunities()` | `AmityCommunityRepository().semanticSearchCommunities(options:)` | `AmitySocialClient.newCommunityRepository().semanticSearchCommunities()` | `AmitySocialClient.newCommunityRepository().semanticSearchCommunities()` |
| Semantic post search | `PostRepository.semanticSearchPosts()` | `AmityPostRepository().semanticSearchPosts(options:)` | `AmitySocialClient.newPostRepository().semanticSearchPosts()` | `AmitySocialClient.newPostRepository().semanticSearchPosts()` |
| Hashtag post search | `PostRepository.searchPostsByHashtag()` | `AmityPostRepository().searchPostsByHashtag(options:)` | `AmitySocialClient.newPostRepository().searchPostsByHashtag()` | Not available |

## Filters

| Filter | Community search | Post search |
| --- | --- | --- |
| Search text | `query` | `query` for semantic search, `hashtags` for hashtag search |
| Category IDs | Supported for community semantic search | Not applicable |
| Tags | Supported for community semantic search | Use post query APIs for tag filters; hashtag search uses `hashtags` |
| Membership status | Supported by TypeScript, iOS, Android, and Flutter community semantic search | Not applicable |
| Target scope | Not applicable | Semantic post search can scope to a user or community target on TypeScript, iOS, Android, and Flutter |
| Post data types | Not applicable | Supported for semantic post search on all platforms; hashtag search support differs by platform |
| Mixed structure | Not applicable | Supported by semantic post search on TypeScript, iOS, Android, and Flutter; not exposed on Flutter's regular `getPosts()` builder |

## Implementation Guides

    Find communities by semantic query, category, tag, and membership status
    Search posts by semantic query or by hashtag

## Notes

- Do not assume a fixed client-visible scoring formula. The SDK APIs return ranked collections, but ranking details are owned by the backend service.
- Debounce user-entered queries before starting a new search request.
- Keep empty, loading, and error states separate in your UI because search results may legitimately be empty.
- Dispose live collection subscriptions and notification tokens when the screen is destroyed.
- The SDK exposes semantic search for both posts and communities. Current Android, iOS, and Flutter UIKit global-search screens use semantic search for posts, while their community tabs use keyword search; use the SDK community repository when you need semantic community discovery in UIKit.

---

### [Posts](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/search/intelligent-search-post)

> Search posts semantically or by hashtag with the SDK post repository APIs.

Use post search when users need to find content across accessible post targets. The SDK exposes semantic post search for natural-language queries on TypeScript, iOS, Android, and Flutter, and hashtag post search for explicit hashtag matching on TypeScript, iOS, and Android.

The current public Flutter SDK source does not expose hashtag post search. Semantic post search is available on Flutter.

Flutter semantic post search requires `amity_sdk` 7.8.7 or later.

## Parameters

| Parameter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Query | `query` | `query` | `query` | `query` |
| Target | `targetType`, `targetId` | `targetType`, `targetId` | `targetType`, `targetId` | `targetType`, `targetId` |
| Data types | `dataTypes` | `dataTypes` | `postTypes` | `postTypes` |
| Parent-only matching | `matchingOnlyParentPost` | `matchingOnlyParentPost` | `matchingOnlyParentPosts` | `matchingOnlyParentPosts` |
| Mixed structure | `includeMixedStructure` | `includeMixedStructure` | `includeMixedStructure` | `includeMixedStructure` |

## Semantic Search Posts

Use semantic search when a natural-language query should match accessible posts for the requested target and data types.


```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

let loadNextPage: (() => void) | undefined;
let canLoadMore = false;

const unsubscribe = PostRepository.semanticSearchPosts(
  {
    query: 'healthy breakfast ideas',
    targetType: 'community',
    targetId: communityId,
    dataTypes: ['text', 'image'],
    matchingOnlyParentPost: true,
    includeMixedStructure: false,
    limit: 20,
  },
  ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);
    loadNextPage = onNextPage;
    canLoadMore = hasNextPage;
  },
);

function loadMorePosts() {
  if (canLoadMore) {
    loadNextPage?.();
  }
}

unsubscribe();
```

```swift iOS
let options = AmityPostSemanticSearchOptions(
    query: "healthy breakfast ideas",
    targetId: communityId,
    targetType: .community,
    dataTypes: ["text", "image"],
    matchingOnlyParentPost: true,
    includeMixedStructure: false
)

token = postRepository
    .semanticSearchPosts(options: options)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
AmitySocialClient.newPostRepository()
    .semanticSearchPosts(
        query = "healthy breakfast ideas",
        targetType = AmityPost.TargetType.COMMUNITY,
        targetId = communityId,
        postTypes = listOf(AmityPost.DataType.TEXT, AmityPost.DataType.IMAGE),
        matchingOnlyParentPosts = true,
        includeMixedStructure = false
    )
    .subscribe(
        { pagingData: PagingData<AmityPost> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final liveCollection = AmitySocialClient.newPostRepository()
    .semanticSearchPosts(
      query: 'healthy breakfast ideas',
      targetType: AmityPostTargetType.COMMUNITY,
      targetId: communityId,
      postTypes: const [AmityDataType.TEXT, AmityDataType.IMAGE],
      matchingOnlyParentPosts: true,
      includeMixedStructure: false,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((posts) {
  // Render posts in your UI.
});

await liveCollection.loadNext();
```


## Hashtag Search Filters

| Parameter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Hashtags | `hashtags` | `hashtags` | `hashtags` | Not available |
| Target | `targetType` | Not exposed | Not exposed | Not available |
| Data types | `dataTypes` | `dataTypes` | `dataTypes` | Not available |
| Parent-only matching | `matchingOnlyParentPost` | `matchingOnlyParentPost` | Not exposed in the snippet surface | Not available |
| Mixed structure | `includeMixedStructure` | `includeMixedStructure` | `includeMixedStructure` | Not available |

## Hashtag Search Posts

Hashtag search finds posts that contain one or more hashtags. Pass hashtag names without the `#` prefix.


```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

let loadNextHashtagPage: (() => void) | undefined;
let canLoadMoreHashtagPosts = false;

const unsubscribe = PostRepository.searchPostsByHashtag(
  {
    targetType: 'community',
    hashtags: ['recipe'],
    dataTypes: ['image'],
    matchingOnlyParentPost: true,
    includeMixedStructure: false,
    limit: 20,
  },
  ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);
    loadNextHashtagPage = onNextPage;
    canLoadMoreHashtagPosts = hasNextPage;
  },
);

function loadMoreHashtagPosts() {
  if (canLoadMoreHashtagPosts) {
    loadNextHashtagPage?.();
  }
}

unsubscribe();
```

```swift iOS
let options = AmityPostHashtagSearchOptions(
    hashtags: ["recipe"],
    dataTypes: ["image"],
    matchingOnlyParentPost: true,
    includeMixedStructure: false
)

token = postRepository
    .searchPostsByHashtag(options: options)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
AmitySocialClient.newPostRepository()
    .searchPostsByHashtag(
        hashtags = listOf("recipe"),
        dataTypes = listOf(AmityPost.DataType.IMAGE),
        includeMixedStructure = false
    )
    .subscribe(
        { pagingData: PagingData<AmityPost> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```


## Notes

- For semantic post search, provide `targetType` and `targetId` together when scoping search to one user or community target.
- Use parent-only matching when the UI should show top-level posts instead of child posts from mixed or threaded structures.
- For hashtag search, TypeScript requires a `targetType`; iOS and Android expose hashtag search without a target type parameter. Hashtag search is not available in the Flutter SDK.
- On Flutter, `getLiveCollection()` returns results in server relevance order; call `loadNext()` to page and `dispose()` when the screen is torn down. `getPagingData(token:, limit:)` is available for a one-shot query.
- Search results are permission-aware from the backend response, but your UI should still handle empty results and authorization errors.

## Related Topics

    Query live post collections by target, type, review state, tags, and pagination options.
    Query feed-style post collections for global, custom-ranking, user, and community feeds.
    Review SDK search surfaces for community and post discovery.

---

### [Communities](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/search/intelligent-search-community)

> Search communities semantically with category, tag, membership, and discoverable private community filters.

Use community semantic search when a discovery experience should match a user's intent instead of only exact community names. The client SDK sends a query and optional filters, then observes or receives a paginated set of `AmityCommunity` results.

Flutter semantic community search requires `amity_sdk` 7.8.7 or later.

## Parameters

| Parameter | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Query | `query` | `query` | `query` | `query` |
| Category IDs | `categoryIds` | `categoryIds` | `categoryIds` | `categoryIds` |
| Tags | `tags` | `tags` | `AmityTags` | `tags` |
| Membership status | `communityMembershipStatus` | `communityMembershipStatus` | `filter` | `filter` |
| Discoverable private communities | `includeDiscoverablePrivateCommunity` | `includeDiscoverablePrivateCommunity` | `includeDiscoverablePrivateCommunity` | `includeDiscoverablePrivateCommunity` |

## Search Communities

Search communities with a semantic query and optional category, tag, membership, or discoverable-private filters.


```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

let loadNextPage: (() => void) | undefined;
let canLoadMore = false;

const unsubscribe = CommunityRepository.semanticSearchCommunities(
  {
    query: 'trail running',
    categoryIds: ['category-id'],
    tags: ['outdoors'],
    includeDiscoverablePrivateCommunity: true,
    limit: 20,
  },
  ({ data: communities, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(communities);
    loadNextPage = onNextPage;
    canLoadMore = hasNextPage;
  },
);

function loadMoreCommunities() {
  if (canLoadMore) {
    loadNextPage?.();
  }
}

unsubscribe();
```

```swift iOS
let options = AmityCommunitySemanticSearchOptions(
    query: "trail running",
    categoryIds: ["category-id"],
    tags: ["outdoors"],
    communityMembershipStatus: .all,
    includeDiscoverablePrivateCommunity: true
)

token = communityRepository
    .semanticSearchCommunities(options: options)
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
import com.amity.socialcloud.sdk.model.social.community.AmityCommunityMembershipStatusFilter

AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
        query = "trail running",
        filter = AmityCommunityMembershipStatusFilter.ALL,
        tags = AmityTags(listOf("outdoors")),
        categoryIds = listOf("category-id"),
        includeDiscoverablePrivateCommunity = true
    )
    .subscribe(
        { pagingData: PagingData<AmityCommunity> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter
final liveCollection = AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
      query: 'trail running',
      filter: AmityCommunityFilter.ALL,
      tags: const ['outdoors'],
      categoryIds: const ['category-id'],
      includeDiscoverablePrivateCommunity: true,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((communities) {
  // Render communities in your UI.
});

await liveCollection.loadNext();
```


## Membership Status

| Intent | iOS | Android | TypeScript | Flutter |
| --- | --- | --- | --- | --- |
| Search all visible communities | `.all` | `AmityCommunityMembershipStatusFilter.ALL` | Omit `communityMembershipStatus` for the default all-status search | `AmityCommunityFilter.ALL` (default) |
| Search joined communities | `.member` | `AmityCommunityMembershipStatusFilter.MEMBER` | Use the SDK's typed membership-status value in app code | `AmityCommunityFilter.MEMBER` |
| Search communities the user has not joined | `.notMember` | `AmityCommunityMembershipStatusFilter.NOT_MEMBER` | Use the SDK's typed membership-status value in app code | `AmityCommunityFilter.NOT_MEMBER` |

## Notes

- Use category and tag filters when your discovery UI already knows the user's topic area.
- Use `includeDiscoverablePrivateCommunity` only when your product intentionally exposes discoverable private communities in search results.
- Flutter defaults `includeDiscoverablePrivateCommunity` to `false`; set it to `true` to include discoverable private communities.
- Search results are returned as live or paginated collections depending on platform, so keep pagination and disposal logic close to the screen that owns the search.
- On Flutter, `includeDiscoverablePrivateCommunity` is available on `semanticSearchCommunities()` only. `getCommunities()` does not expose it.

## Related Topics

    Query and search communities by membership, category, tags, keyword, and sort order.
    Retrieve categories used to organize community discovery.
    Review SDK search surfaces for community and post discovery.

## Social — Notifications

### [Notification Tray Overview](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/notifications/overview)

> Read notification tray items, tray seen status, and item seen status with the SDK notification tray APIs.

The notification tray SDK APIs expose in-app notification tray data for the signed-in user. Use them to render notification items, show a tray-level unread indicator, mark the tray as seen, and mark individual tray items as seen.

The current public Flutter SDK source reviewed for this page exposes push-notification registration and notification-settings APIs, but not notification tray item/status APIs.

## SDK Surfaces

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Query tray items | `notificationTray.getNotificationTrayItems()` | `client.notificationTray.getNotificationTrayItems()` | `AmityCoreClient.notificationTray().getNotificationTrayItems()` | Not exposed in the current public Flutter SDK source reviewed for this page |
| Observe tray seen status | `notificationTray.getNotificationTraySeen()` | `client.notificationTray.getNotificationTraySeen()` | `AmityCoreClient.notificationTray().getNotificationTraySeen()` | Not exposed in the current public Flutter SDK source reviewed for this page |
| Mark tray seen | `notificationTray.markTraySeen(lastSeenAt)` | `client.notificationTray.markSeen()` | `AmityCoreClient.notificationTray().markTraySeen()` | Not exposed in the current public Flutter SDK source reviewed for this page |
| Mark item seen | `notificationTray.markItemsSeen([{ id, lastSeenAt }])` | `AmityNotificationTrayItem.markSeen()` | `AmityNotificationTrayItem.markSeen()` | Not exposed in the current public Flutter SDK source reviewed for this page |

## Data Model

Notification tray items are returned with actor, target, reference, action, text, and seen-state data. Property names differ slightly by platform.

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Item ID | `_id` | `notificationId` | `getId()` |
| Last occurred | `lastOccurredAt` | `lastOccurredAt` | `getLastOccurredAt()` |
| Last seen | `lastSeenAt` | `lastSeenAt` | `getLastSeenAt()` |
| Action type | `actionType` | `actionType` | `getActionType()` |
| Category | `trayItemCategory` | `trayItemCategory` | `getTrayItemCategory()` |
| Target | `targetId`, `targetType` | `targetId`, `targetType` | `getTargetId()`, `getTargetType()` |
| Text | `text`, `templatedText` | `text`, `templatedText` | `getText()`, `getTemplatedText()` |
| Linked users | `users` | `users` | `getUsers()` |
| Item seen state | `isSeen` | `isSeen` | `isSeen()` |
| Recent-state helper | `isRecent` | `isRecent` | `isRecent()` |

Tray seen status is a separate object with the latest tray occurrence timestamp, latest tray seen timestamp, and a derived `isSeen` value.

## Typical Flow

1. Observe tray seen status to decide whether to show a notification indicator.
2. Query tray items when the user opens the notification tray.
3. Mark the tray as seen after the user views the tray.
4. Mark individual items as seen when the user views or opens a specific item.
5. Dispose observers or subscriptions when the owning screen is destroyed.

## Related Topics

    Query tray items and mark individual items as seen
    Observe and update tray-level seen status
    Reference action and category values returned on tray items

---

### [Notification Tray Items](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/notifications/notification-items)

> Query notification tray items and mark individual items as seen.

Notification tray items are paginated notification records for the signed-in user. Use this API to render an in-app notification tray and then mark individual items as seen when the user opens or views them.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Query items | `limit` / pagination handle | No | TypeScript, iOS, Android | Page-size and pagination controls where supported by the platform. |
| Mark item seen | Item ID | Yes | TypeScript | Notification item ID to pass into `markItemsSeen`. |
| Mark item seen | `lastSeenAt` | Yes | TypeScript | ISO timestamp for when the item was seen. |
| Mark item seen | Notification tray item object | Yes | iOS, Android | Item returned by the tray item query; call `markSeen()` on the object. |

## Query Items

Query notification tray items for the signed-in user, keeping the pagination handle while the tray screen is active.


```typescript TypeScript
import { notificationTray } from '@amityco/ts-sdk';

let loadNextPage: (() => void) | undefined;
let canLoadMore = false;

const unsubscribe = notificationTray.getNotificationTrayItems(
  { limit: 20 },
  ({ data: items, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(items);
    loadNextPage = onNextPage;
    canLoadMore = hasNextPage;
  },
);

function loadMoreNotificationItems() {
  if (canLoadMore) {
    loadNextPage?.();
  }
}

unsubscribe();
```

```swift iOS
token = client.notificationTray
    .getNotificationTrayItems()
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android
AmityCoreClient.notificationTray()
    .getNotificationTrayItems()
    .subscribe(
        { pagingData: PagingData<AmityNotificationTrayItem> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```


## Mark an Item Seen

Mark an individual notification item seen after the user opens or views that item.


```typescript TypeScript
import { notificationTray } from '@amityco/ts-sdk';

async function markNotificationItemSeen(notificationId: string) {
  await notificationTray.markItemsSeen([
    {
      id: notificationId,
      lastSeenAt: new Date().toISOString(),
    },
  ]);
}
```

```swift iOS
token = client.notificationTray
    .getNotificationTrayItems()
    .observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        guard let firstItem = collection.snapshots.first else { return }

        Task { @MainActor in
            do {
                try await firstItem.markSeen()
            } catch {
                handleError(error)
            }
        }
    }
```

```kotlin Android
fun markNotificationItemSeen(item: AmityNotificationTrayItem) {
    item.markSeen()
        .subscribe(
            { showSuccessMessage("seen") },
            { error -> handleGeneralError(error) }
        )
}
```


## Data Freshness

**The notification tray is not real-time.** Tray items are served from a short-lived server-side cache. A newly triggered notification is **not** guaranteed to appear the moment it happens — it becomes visible only after the server's cache refreshes. Until then, a query returns the previously cached result. Treat the tray as **eventually consistent**, not live, and do not rely on a new item (or an updated count) reflecting immediately after the triggering action.

## Notes

- TypeScript marks one or more items by ID through `markItemsSeen`.
- iOS and Android expose `markSeen()` on the `AmityNotificationTrayItem` model returned by the tray item query.
- Use the platform-specific item ID field when routing from a tray item to a target screen: TypeScript `_id`, iOS `notificationId`, and Android `getId()`.
- Dispose live collection subscriptions or notification tokens when the notification tray screen is destroyed.

## Related Topics

    Manage overall notification tray seen status.
    Reference action and category values returned on tray items.

---

### [Notification Tray Status](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/notifications/notification-tray-status)

> Observe and update notification tray seen status for unread indicators.

Notification tray status tracks whether the signed-in user's tray has been seen since the latest tray item occurred. Use it for tray badges, unread indicators, and "new notifications" affordances.

## Status Fields

| Concept | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Tray is seen | `isSeen` | `isSeen` | `isSeen()` |
| Last tray occurrence | `lastTrayOccurredAt` | `lastTrayOccurredAt` | `getLastOccurredAt()` |
| Last tray seen timestamp | `lastTraySeenAt` | `lastTraySeenAt` | `getLastSeenAt()` |

The current public Flutter SDK source reviewed for this page does not expose notification tray seen-status APIs.

## Parameters

| Operation | Input | Required | Platforms | Description |
| --- | --- | --- | --- | --- |
| Observe tray seen status | Signed-in user session | Yes | TypeScript, iOS, Android | The SDK returns status for the current user; no explicit user ID is passed. |
| Mark tray seen | Seen timestamp | Platform-dependent | TypeScript | Timestamp to store as the tray seen time. |
| Mark tray seen | Current tray context | Yes | iOS, Android | Marks the signed-in user's tray seen without an explicit timestamp parameter. |

## Observe Tray Seen Status

Observe tray seen status when your app needs a badge or "new notifications" indicator to stay current.


```typescript TypeScript
import { notificationTray } from '@amityco/ts-sdk';

const unsubscribe = notificationTray.getNotificationTraySeen(
  ({ data: status, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    updateUI(status);
  },
);

unsubscribe();
```

```swift iOS
token = client.notificationTray
    .getNotificationTraySeen()
    .observe { object, error in
        if let error {
            handleError(error)
            return
        }

        if let status = object.snapshot {
            showSuccessMessage(status.isSeen)
        }
    }
```

```kotlin Android
AmityCoreClient.notificationTray()
    .getNotificationTraySeen()
    .subscribe(
        { status: AmityNotificationTraySeen -> showSuccessMessage(status.isSeen() == true) },
        { error -> handleGeneralError(error) }
    )
```


## Mark Tray Seen

Mark the tray seen after the user actually views the notification tray.


```typescript TypeScript
import { notificationTray } from '@amityco/ts-sdk';

async function markNotificationTraySeen() {
  await notificationTray.markTraySeen(new Date().toISOString());
}
```

```swift iOS
Task { @MainActor in
    do {
        try await client.notificationTray.markSeen()
    } catch {
        handleError(error)
    }
}
```

```kotlin Android
AmityCoreClient.notificationTray()
    .markTraySeen()
    .subscribe(
        { showSuccessMessage("seen") },
        { error -> handleGeneralError(error) }
    )
```


## Notes

- Mark the tray as seen when the user actually views the tray, not merely when a badge is rendered.
- Keep tray-level status separate from item-level status. Marking the tray seen does not replace item-level interaction tracking in your UI.
- Re-observe or refresh tray status when the app returns to the foreground if your badge must reflect cross-device activity.

**Not real-time.** Seen status is derived from the same server-cached tray data as [notification items](./notification-items#data-freshness), so it does not update the instant a new notification is triggered. Expect a short delay before `isSeen` / `lastTrayOccurredAt` reflect a new occurrence — an unread indicator built on this status is eventually consistent, not live.

## Related Topics

    Query notification items and mark individual items as seen.
    Understand the notification tray SDK surface.

---

### [Notification Event Fields](https://learn.social.plus/social-plus-sdk/social/discovery-engagement/notifications/notification-events-reference)

> Reference action and category values returned on notification tray items.

Notification tray items include string fields that identify what happened and what kind of tray item was produced. Use these fields for routing, icons, grouping, and display decisions in your app.

Do not hardcode notification message-template behavior from this page. The SDK returns `text` and `templatedText` on each tray item. Render those fields or map action/category values only for UI behavior you own, such as icons and routing.

## Core Fields

| Field | TypeScript | iOS | Android | Purpose |
| --- | --- | --- | --- | --- |
| Action type | `actionType` | `actionType` | `getActionType()` | Broad action family |
| Tray item category | `trayItemCategory` | `trayItemCategory` | `getTrayItemCategory()` | More specific category for mentions, reactions, follows, events, and related actions |
| Target | `targetId`, `targetType` | `targetId`, `targetType` | `getTargetId()`, `getTargetType()` | Object the notification points at |
| Reference | `referenceId`, `referenceType` | `referenceId`, `referenceType` | `getReferenceId()`, `getReferenceType()` | Related object, when present |
| Parent | `parentId` | `parentId` | `getParentId()` | Parent object, when present |
| Rendered text | `text`, `templatedText` | `text`, `templatedText` | `getText()`, `getTemplatedText()` | Text returned by the backend for display |

## Action Types

The TypeScript SDK type surface defines these action values. iOS and Android expose action type as a string on each returned tray item.

| Value | Meaning |
| --- | --- |
| `post` | Post-related notification |
| `poll` | Poll-related notification |
| `comment` | Comment-related notification |
| `reaction` | Reaction-related notification |
| `mention` | Mention-related notification |
| `reply` | Reply-related notification |
| `join_request` | Join-request-related notification |
| `user` | User-related notification |
| `event` | Event-related notification (routes to the event detail page) |

## Tray Item Categories

The TypeScript SDK type surface defines these category values. iOS and Android expose the category as a string on each returned tray item.

| Value | Meaning |
| --- | --- |
| `mention_in_post` | Mention in a post |
| `mention_in_comment` | Mention in a comment |
| `mention_in_reply` | Mention in a reply |
| `mention_in_poll` | Mention in a poll |
| `reaction_on_post` | Reaction on a post |
| `reaction_on_comment` | Reaction on a comment |
| `reaction_on_reply` | Reaction on a reply |
| `respond_on_join_request` | Response to a join request |
| `follow` | Follow notification |
| `event_reminder` | Event reminder |
| `event_started` | Event started notification |
| `event_created` | Event created notification |
| `room_cohost_invite` | Room co-host invitation |
| `user_profile_reset` | User profile reset notification |

## Routing Guidance

- Use `targetType` and `targetId` for the primary destination.
- Use `referenceType` and `referenceId` when your UI needs to highlight a related post, comment, event, or other referenced object.
- Use `rootId` and `latestCommentId` when they are present and your comment UI needs to open a thread context.
- For `actionType == "event"` items, resolve the event id from `actionReferenceId` and route to the event detail page. When `trayItemCategory == "event_created"`, the hydrated `event` object (including `event.targetCommunity`) is available on the item for rendering the community avatar, event-type chip (`In-person` / `Virtual` from `event.type`), and event start date/time (from `event.startTime`).
- Prefer the returned `text` or `templatedText` for display copy instead of rebuilding notification copy in the client.

## Related Documentation

    Query tray items and inspect returned fields
    Observe and update tray-level seen status

## Social — Events

### [Events Overview](https://learn.social.plus/social-plus-sdk/social/events/overview)

> Create, query, update, delete, and RSVP to scheduled events using the SDK event APIs.

Events are scheduled social objects with a title, description, type, start and end time, origin, optional location or external URL, optional cover image, tags, metadata, and RSVP counts.

The SDK event surface is currently exposed in TypeScript, iOS, and Android. The public Flutter SDK source reviewed for this page does not expose scheduled event creation, query, management, or RSVP APIs.

## Platform Coverage

| Capability | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Create event | `EventRepository.createEvent(options)` | `AmityEventRepository().createEvent(options:)` | `AmitySocialClient.newEventRepository().createEvent()...build().create()` | Not exposed in the current public Flutter SDK source reviewed for this page |
| Get event | `EventRepository.getEvent(eventId, callback)` | `AmityEventRepository().getEvent(id:)` | `AmitySocialClient.newEventRepository().getEvent(eventId)` | Not exposed |
| Query events | `EventRepository.getEvents(params, callback)` | `AmityEventRepository().getEvents(options:)` | `AmitySocialClient.newEventRepository().getEvents()...build().query()` | Not exposed |
| Query my RSVP events | `EventRepository.getMyEvents({ status }, callback)` | Use `AmityEventQueryOptions(userId:onlyAttendee:)` | Use `getEvents().userId(...).onlyAttendee(true)` | Not exposed |
| Update event | `EventRepository.updateEvent(eventId, options)` | `AmityEventRepository().updateEvent(id:options:)` | `AmitySocialClient.newEventRepository().updateEvent(eventId)...build().apply()` | Not exposed |
| Delete event | `EventRepository.deleteEvent(eventId)` | `AmityEventRepository().deleteEvent(id:)` | `AmitySocialClient.newEventRepository().deleteEvent(eventId)` | Not exposed |
| RSVP | `event.createRSVP(...)`, `event.updateRSVP(...)`, `event.getMyRSVP()`, `event.getRSVPs(...)` | Same methods on `AmityEvent` | Same methods on `AmityEvent` | Not exposed |
| Share event link | `Client.getShareableLinkConfiguration()` + `AmitySharableContentType.EVENT` | Supported | Supported | Not available |

## Event Fields

Core fields returned by the SDK include:

| Field | Notes |
| --- | --- |
| `eventId` | Stable event identifier. Android exposes it as `getEventId()`. |
| `title`, `description` | Event copy supplied at creation time. |
| `type` | `virtual` or `in_person`. |
| `status` | TypeScript and iOS expose `scheduled`, `live`, `ended`, and `cancelled`. Android also exposes `DRAFT` and `UNKNOWN` enum values for server compatibility. |
| `startTime`, `endTime` | Required when creating events. TypeScript accepts ISO strings; iOS uses `Date`; Android uses Joda `DateTime`. |
| `originType`, `originId` | The event origin: `community` or `user`, plus the corresponding ID. |
| `isOriginPublic` | For a community-origin event, whether the origin community is public. User-origin events have no origin community; use `originType` when applying the event-post target rules — see [Target Rules](../content-management/posts/creation/event-post#target-rules). Android exposes it as `isOriginPublic()`. |
| `location`, `externalUrl`, `coverImageFileId` | Optional display and media fields. |
| `tags`, `metadata` | Optional structured fields. Timezone can be stored in `metadata.timezone` on TypeScript/iOS and via `timezone(...)` on Android. |
| `rsvpCount`, `interestedCount` | Count fields returned with the event. |
| `creator`, `targetCommunity`, `coverImage`, `post`, `room` | Linked objects are present when returned by the SDK payload/cache. Availability depends on platform and response payload. |

## RSVP Statuses

| Status | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Going | `AmityEventResponseStatus.Going` | `.going` | `AmityEventResponseStatus.GOING` |
| Interested | Not exposed by the current TypeScript enum reviewed for this page | `.interested` | `AmityEventResponseStatus.INTERESTED` |
| Not going | `AmityEventResponseStatus.NotGoing` | `.notGoing` | `AmityEventResponseStatus.NOT_GOING` |

## Common Flow

1. Create an event with a title, description, type, start time, end time, origin type, and origin ID.
2. Query events by origin, status, type, user ID, attendee filter, sort option, and order option.
3. Observe a single event if the detail screen needs live updates.
4. Let users RSVP through the methods on the returned `AmityEvent`.
5. Update or delete events through the event repository when the current user has permission.

This page documents SDK method names and data surfaces only. Product policy such as who can create, edit, RSVP, or view an event is enforced by backend permissions and should be handled by your app UI and error handling.

## Event Guides

    Create scheduled virtual or in-person events.
    Get, query, update, and delete event objects.
    Create, update, read, and query RSVP responses.
    Attach an event to a post so it renders as an event card in feeds.
    Generate a shareable deep link to an event.

---

### [Create Event](https://learn.social.plus/social-plus-sdk/social/events/create-event)

> Create scheduled virtual or in-person events with the SDK event repository.

Create events through the event repository on TypeScript, iOS, and Android. A create request needs a title, description, event type, start time, end time, origin type, and origin ID. Optional fields include location, external URL, cover image file ID, tags, and metadata.

Flutter does not currently expose a public scheduled-event creation API in the SDK source reviewed for this page.

## Parameters

| Parameter | Required | Platforms | Description |
| --- | --- | --- | --- |
| `title` | Yes | TypeScript, iOS, Android | Event title shown to users. |
| `description` | Yes | TypeScript, iOS, Android | Event description or summary. |
| `type` | Yes | TypeScript, iOS, Android | Virtual or in-person event type. |
| `startTime`, `endTime` | Yes | TypeScript, iOS, Android | Start and end time. TypeScript accepts ISO strings, iOS uses `Date`, and Android uses Joda `DateTime`. |
| `originType`, `originId` | Yes | TypeScript, iOS, Android | Event owner scope, usually a community origin and community ID. |
| `location` | No | TypeScript, iOS, Android | Physical location for in-person events. |
| `externalUrl` | No | TypeScript, iOS, Android | Link for a virtual event or external event details. |
| `coverImageFileId` | No | TypeScript, iOS, Android | Uploaded file ID for the event cover image. |
| `tags` | No | TypeScript, iOS, Android | Tags used for app-owned grouping or filtering. |
| `metadata` / `timezone` | No | TypeScript, iOS, Android | Custom metadata. Android exposes timezone through `.timezone(...)`. |

## Create an Event

Use the create method when your app has collected the required event fields and knows the target origin. The examples below create a virtual community event and return the created event object.


```typescript TypeScript
import {
  AmityEventOriginType,
  AmityEventType,
  EventRepository,
} from '@amityco/ts-sdk';

const { data: event } = await EventRepository.createEvent({
  title: 'Community Workshop',
  description: 'A live workshop for community members.',
  type: AmityEventType.Virtual,
  startTime: '2026-08-01T09:00:00.000Z',
  endTime: '2026-08-01T10:00:00.000Z',
  originType: AmityEventOriginType.Community,
  originId: communityId,
  externalUrl: 'https://example.com/live',
  tags: ['workshop'],
  metadata: { timezone: 'UTC' },
});

showSuccessMessage(event.eventId);
```

```swift iOS
let repository = AmityEventRepository()

let options = AmityEventCreateOptions(
    title: "Community Workshop",
    description: "A live workshop for community members.",
    type: .virtual,
    startTime: Date(),
    endTime: Date().addingTimeInterval(3600),
    originType: .community,
    originId: communityId,
    externalUrl: "https://example.com/live",
    tags: ["workshop"],
    metadata: ["timezone": "UTC"]
)

let event = try await repository.createEvent(options: options)
showSuccessMessage(event.eventId)
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .createEvent()
    .title("Community Workshop")
    .description("A live workshop for community members.")
    .type(AmityEventType.VIRTUAL)
    .startTime(DateTime.now().plusDays(7))
    .endTime(DateTime.now().plusDays(7).plusHours(1))
    .originType(AmityEventOriginType.COMMUNITY)
    .originId(communityId)
    .externalUrl("https://example.com/live")
    .timezone("UTC")
    .tags(listOf("workshop"))
    .build()
    .create()
    .subscribe(
        { event: AmityEvent -> showSuccessMessage(event.getEventId()) },
        { error -> handleGeneralError(error) }
    )
```

## Platform Notes

- TypeScript uses `AmityEventType.Virtual` and `AmityEventType.InPerson`.
- iOS uses `.virtual` and `.inPerson`.
- Android uses `AmityEventType.VIRTUAL` and `AmityEventType.IN_PERSON`.
- Android requires `endTime(...)` before calling `build()`.

## Related Topics

    Get, query, update, and delete events.
    Create, update, read, and query RSVP responses.
    Review event fields, coverage, and common flows.

---

### [Manage Events](https://learn.social.plus/social-plus-sdk/social/events/manage-events)

> Get, query, update, and delete events with SDK event repository APIs.

Use event repository APIs to observe a single event, query event collections, update event fields, and delete events.

Flutter does not currently expose public scheduled-event management APIs in the SDK source reviewed for this page.

## Parameters

| Input | Methods | Platforms | Description |
| --- | --- | --- | --- |
| `eventId` | Get, update, delete | TypeScript, iOS, Android | Stable ID of the event to read or mutate. |
| `originType`, `originId` | Query | TypeScript, iOS, Android | Scope events to a community or user origin. |
| `userId`, `onlyAttendee` | Query my RSVP events | TypeScript, iOS, Android | Filter events by attendee or user context. |
| `status` | Query | TypeScript, iOS, Android | Filter by scheduled, live, ended, or cancelled status. |
| `type` | Query | TypeScript, iOS, Android | Filter by virtual or in-person event type. |
| `sortBy`, `orderBy` | Query | TypeScript, iOS, Android | Sort event lists by start time or creation time. |
| `excludeOwnEvents` | Query | TypeScript, Android | Exclude events created by the current user — useful for discovery feeds. Defaults to `false`. |
| Event fields | Update | TypeScript, iOS, Android | Mutable fields such as title, external URL, description, location, tags, and metadata. |

## Get an Event

Use this method for event detail screens or any flow that needs the latest state of one event. TypeScript and iOS expose observable objects; Android returns the requested event through the repository.

```typescript TypeScript
import { EventRepository } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent(
  'event-123',
  ({ data: event, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!event) return;

    showSuccessMessage(event.title);
  },
);

unsubscribe();
```

```swift iOS
let repository = AmityEventRepository()

token = repository.getEvent(id: "event-123").observe { eventObject, error in
    if let error {
        handleError(error)
        return
    }
    guard let event = eventObject.snapshot else { return }

    showSuccessMessage(event.title)
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvent("event-123")
    .subscribe(
        { event: AmityEvent -> showSuccessMessage(event.getTitle()) },
        { error -> handleGeneralError(error) }
    )
```

## Query Events

Use event queries to build calendar lists, community event lists, and upcoming-event surfaces. Pass origin, status, type, sort, and order filters that match the list your UI needs. For discovery surfaces such as an **Explore** or **Happening now** feed, set `excludeOwnEvents: true` (TypeScript) or `.excludeOwnEvents(true)` (Android) to omit events created by the current user; it is a no-op when no authenticated user is resolved.

```typescript TypeScript
import {
  AmityEventOrderOption,
  AmityEventOriginType,
  AmityEventSortOption,
  AmityEventStatus,
  EventRepository,
} from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvents(
  {
    originType: AmityEventOriginType.Community,
    originId: communityId,
    status: AmityEventStatus.Scheduled,
    sortBy: AmityEventSortOption.StartTime,
    orderBy: AmityEventOrderOption.Ascending,
    excludeOwnEvents: true, // Exclude the current user's own events from the Explore, Happening, and Recommended surfaces
  },
  ({ data: events, loading, error, hasNextPage, onNextPage }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(events);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);

unsubscribe();
```

```swift iOS
let repository = AmityEventRepository()
let options = AmityEventQueryOptions(
    originType: .community,
    originId: communityId,
    status: .scheduled,
    sortBy: .startTime,
    orderBy: .ascending
)

token = repository.getEvents(options: options).observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.map(\.title))
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvents()
    .originType(AmityEventOriginType.COMMUNITY)
    .originId(communityId)
    .status(AmityEventStatus.SCHEDULED)
    .sortBy(AmityEventSortOption.START_TIME)
    .orderBy(AmityEventOrderOption.ASCENDING)
    .excludeOwnEvents(true) // For showing on happening event and recommended event
    .build()
    .query()
    .subscribe(
        { pagingData: PagingData<AmityEvent> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

## Query My RSVP Events

Use this flow when the current screen should show events connected to a user's RSVP or attendance state. The SDKs expose this through event query filters rather than a separate event object method.

```typescript TypeScript
import { AmityEventResponseStatus, EventRepository } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getMyEvents(
  { status: AmityEventResponseStatus.Going },
  ({ data: events, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(events);
  },
);

unsubscribe();
```

```swift iOS
let options = AmityEventQueryOptions(
    userId: "user-123",
    onlyAttendee: true,
    sortBy: .startTime,
    orderBy: .ascending
)

token = AmityEventRepository().getEvents(options: options).observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    showSuccessMessage(collection.snapshots.count)
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvents()
    .userId(userId)
    .onlyAttendee(true)
    .sortBy(AmityEventSortOption.START_TIME)
    .orderBy(AmityEventOrderOption.ASCENDING)
    .build()
    .query()
    .subscribe(
        { pagingData: PagingData<AmityEvent> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

## Update an Event

Use update when the current user can edit the event and your app has collected the changed fields. The examples update the title and virtual-event URL.

```typescript TypeScript
import { EventRepository } from '@amityco/ts-sdk';

const { data: event } = await EventRepository.updateEvent('event-123', {
  title: 'Updated Community Workshop',
  externalUrl: 'https://example.com/updated-live',
});

showSuccessMessage(event.title);
```

```swift iOS
let repository = AmityEventRepository()
let options = AmityEventUpdateOptions(
    title: "Updated Community Workshop",
    externalUrl: "https://example.com/updated-live"
)

let event = try await repository.updateEvent(id: "event-123", options: options)
showSuccessMessage(event.title)
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .updateEvent("event-123")
    .title("Updated Community Workshop")
    .externalUrl("https://example.com/updated-live")
    .build()
    .apply()
    .subscribe(
        { event: AmityEvent -> showSuccessMessage(event.getTitle()) },
        { error -> handleGeneralError(error) }
    )
```

## Delete an Event

Use delete for event owner or moderator flows where removing the event is allowed by backend permissions. Handle errors in your UI because permission and lifecycle rules are enforced server-side.

```typescript TypeScript
import { EventRepository } from '@amityco/ts-sdk';

await EventRepository.deleteEvent('event-123');
showSuccessMessage('Event deleted');
```

```swift iOS
try await AmityEventRepository().deleteEvent(id: "event-123")
showSuccessMessage("Event deleted")
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .deleteEvent("event-123")
    .subscribe(
        { showSuccessMessage("Event deleted") },
        { error -> handleGeneralError(error) }
    )
```

## Query Filters

| Filter | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Origin | `originType`, `originId` | `originType`, `originId` | `.originType(...)`, `.originId(...)` |
| Creator or attendee user | `userId`, `onlyAttendee` | `userId`, `onlyAttendee` | `.userId(...)`, `.onlyAttendee(...)` |
| Status | `AmityEventStatus.Scheduled`, `Live`, `Ended`, `Cancelled` | `.scheduled`, `.live`, `.ended`, `.cancelled` | `AmityEventStatus.SCHEDULED`, `LIVE`, `ENDED`, `CANCELLED` |
| Type | `AmityEventType.Virtual`, `InPerson` | `.virtual`, `.inPerson` | `AmityEventType.VIRTUAL`, `IN_PERSON` |
| Sort | `AmityEventSortOption.StartTime`, `CreatedAt` | `.startTime`, `.createdAt` | `AmityEventSortOption.START_TIME`, `CREATED_AT` |
| Order | `AmityEventOrderOption.Ascending`, `Descending` | `.ascending`, `.descending` | `AmityEventOrderOption.ASCENDING`, `DESCENDING` |
| Exclude own events | `excludeOwnEvents` | — | `.excludeOwnEvents(...)` |

TypeScript `deleteEvent` returns `void`. Android returns a `Completable`; iOS returns from an async throwing function when deletion completes.

## Related Topics

    Create scheduled virtual or in-person events.
    Work with RSVP responses on event objects.
    Review event fields, coverage, and common flows.

---

### [Event RSVP](https://learn.social.plus/social-plus-sdk/social/events/event-rsvp)

> Create, update, read, and query event RSVP responses from SDK event objects.

RSVP methods are exposed on the `AmityEvent` object returned by the event repository. Use them after you have loaded or created an event.

Flutter does not currently expose public scheduled-event RSVP APIs in the SDK source reviewed for this page.

## Status Values

| Meaning | TypeScript | iOS | Android |
| --- | --- | --- | --- |
| Going | `AmityEventResponseStatus.Going` | `.going` | `AmityEventResponseStatus.GOING` |
| Interested | Not exposed by the current TypeScript enum reviewed for this page | `.interested` | `AmityEventResponseStatus.INTERESTED` |
| Not going | `AmityEventResponseStatus.NotGoing` | `.notGoing` | `AmityEventResponseStatus.NOT_GOING` |

## Parameters

| Parameter | Methods | Platforms | Description |
| --- | --- | --- | --- |
| `event` | All RSVP methods | TypeScript, iOS, Android | Loaded `AmityEvent` object that exposes RSVP methods. |
| `status` | Create, update, query | TypeScript, iOS, Android | RSVP status to create, update, or filter. |
| `eventId` | Load before RSVP | TypeScript, iOS, Android | Event ID used to retrieve the event object first. |
| Pagination callback or collection | Query RSVPs | TypeScript, iOS, Android | Returned RSVP list or live collection for rendering attendees. |

## Create RSVP

Create an RSVP when a user responds to an event for the first time. The examples load the event first, then call `createRSVP` on the returned event object.

```typescript TypeScript
import { AmityEventResponseStatus, EventRepository } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent(
  'event-123',
  async ({ data: event, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!event) return;

    const rsvp = await event.createRSVP(AmityEventResponseStatus.Going);
    showSuccessMessage(rsvp?.status);
  },
);

unsubscribe();
```

```swift iOS
token = AmityEventRepository().getEvent(id: "event-123").observe { eventObject, error in
    if let error {
        handleError(error)
        return
    }
    guard let event = eventObject.snapshot else { return }

    Task {
        do {
            let rsvp = try await event.createRSVP(status: .going)
            showSuccessMessage(rsvp.status.rawValue)
        } catch {
            handleError(error)
        }
    }
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvent("event-123")
    .firstOrError()
    .flatMap { event: AmityEvent ->
        event.createRSVP(AmityEventResponseStatus.GOING)
    }
    .subscribe(
        { rsvp: AmityEventResponse -> showSuccessMessage(rsvp.getStatus()) },
        { error -> handleGeneralError(error) }
    )
```

## Update RSVP

Update an RSVP when a user changes their response. Use the same event object flow, but pass the new status to `updateRSVP`.

```typescript TypeScript
import { AmityEventResponseStatus, EventRepository } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent(
  'event-123',
  async ({ data: event, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!event) return;

    const rsvp = await event.updateRSVP(AmityEventResponseStatus.NotGoing);
    showSuccessMessage(rsvp?.status);
  },
);

unsubscribe();
```

```swift iOS
token = AmityEventRepository().getEvent(id: "event-123").observe { eventObject, error in
    if let error {
        handleError(error)
        return
    }
    guard let event = eventObject.snapshot else { return }

    Task {
        do {
            let rsvp = try await event.updateRSVP(status: .notGoing)
            showSuccessMessage(rsvp.status.rawValue)
        } catch {
            handleError(error)
        }
    }
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvent("event-123")
    .firstOrError()
    .flatMap { event: AmityEvent ->
        event.updateRSVP(AmityEventResponseStatus.NOT_GOING)
    }
    .subscribe(
        { rsvp: AmityEventResponse -> showSuccessMessage(rsvp.getStatus()) },
        { error -> handleGeneralError(error) }
    )
```

## Get My RSVP

Get the active user's RSVP for an event when the UI needs to show the current response before offering update actions.

```typescript TypeScript
import { EventRepository } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent(
  'event-123',
  async ({ data: event, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!event) return;

    const rsvp = await event.getMyRSVP();
    showSuccessMessage(rsvp?.status);
  },
);

unsubscribe();
```

```swift iOS
token = AmityEventRepository().getEvent(id: "event-123").observe { eventObject, error in
    if let error {
        handleError(error)
        return
    }
    guard let event = eventObject.snapshot else { return }

    Task {
        do {
            let rsvp = try await event.getMyRSVP()
            showSuccessMessage(rsvp.status.rawValue)
        } catch {
            handleError(error)
        }
    }
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvent("event-123")
    .firstOrError()
    .flatMap { event: AmityEvent ->
        event.getMyRSVP()
    }
    .subscribe(
        { rsvp: AmityEventResponse -> showSuccessMessage(rsvp.getStatus()) },
        { error -> handleGeneralError(error) }
    )
```

## Query RSVPs

Query RSVP responses when you need to render attendee lists, counts by status, or moderation views. Filter by status when the screen only needs one response group.

```typescript TypeScript
import { AmityEventResponseStatus, EventRepository } from '@amityco/ts-sdk';

let rsvpUnsubscribe: Amity.Unsubscriber | undefined;

const unsubscribe = EventRepository.getEvent(
  'event-123',
  ({ data: event, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }
    if (!event) return;

    rsvpUnsubscribe = event.getRSVPs(
      { status: AmityEventResponseStatus.Going },
      ({ data: responses, loading, error }) => {
        if (loading) return;
        if (error) {
          handleError(error);
          return;
        }

        renderResults(responses);
      },
    );
  },
);

rsvpUnsubscribe?.();
unsubscribe();
```

```swift iOS
token = AmityEventRepository().getEvent(id: "event-123").observe { eventObject, error in
    if let error {
        handleError(error)
        return
    }
    guard let event = eventObject.snapshot else { return }

    token = event.getRSVPs(status: .going).observe { collection, error in
        if let error {
            handleError(error)
            return
        }

        showSuccessMessage(collection.snapshots.count)
    }
}
```

```kotlin Android
AmitySocialClient.newEventRepository()
    .getEvent("event-123")
    .firstOrError()
    .flatMapPublisher { event: AmityEvent ->
        event.getRSVPs(AmityEventResponseStatus.GOING)
    }
    .subscribe(
        { pagingData: PagingData<AmityEventResponse> -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

## Response Fields

`AmityEventResponse` includes the event ID, user ID, status, linked user when available, creation time, update time, and the time the user responded. Android also exposes an RSVP ID through `getRsvpId()`.

## Related Topics

    Create the event before collecting RSVP responses.
    Get and query event objects before calling RSVP methods.
    Review event coverage, fields, and status values.

## Social — Follow & User Relationships

### [Follow/Unfollow User](https://learn.social.plus/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)

> Follow or unfollow another user with the social.plus SDKs.

Use the follow API to create a relationship from the current user to another user. The SDK returns the resulting follow status where the platform exposes one. Depending on network configuration, the status can become `accepted` immediately or remain `pending` until the target user accepts the request.

Use the unfollow API to cancel a pending request or remove an accepted follow relationship.

If the relationship is blocked, follow and unfollow calls can fail or return a blocked status. Read the connection status before rendering a follow button when the UI needs to distinguish blocked users.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Follow user | `userId` / `targetUserId` | Yes | ID of the user the current user wants to follow. |
| Unfollow user | `userId` / `targetUserId` | Yes | ID of the user the current user wants to unfollow or whose pending request should be canceled. |

## Follow User

Follow a user when the current user starts a relationship that may become accepted immediately or remain pending.


```swift iOS
let relationship = AmityUserRelationship()
let response = try await relationship.follow(withUserId: "target-user-id")
_ = response
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .follow(userId = targetUserId)
    .subscribe(
        { status: AmityFollowStatus ->
            showSuccessMessage(status.apiKey)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const { data: followStatus } = await UserRepository.Relationship.follow(userId);

if (followStatus.status === 'accepted') {
  showSuccessMessage('Following');
}
```

```dart Flutter
final status = await AmityCoreClient.newUserRepository()
    .relationship()
    .follow(targetUserId);

final statusValue = status.value;
```


## Unfollow User

Unfollow a user to remove an accepted relationship or cancel a pending follow request.


```swift iOS
let relationship = AmityUserRelationship()
let response = try await relationship.unfollow(withUserId: "target-user-id")
_ = response
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .unfollow(userId = targetUserId)
    .subscribe(
        {
            showSuccessMessage()
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const didUnfollow = await UserRepository.Relationship.unfollow(userId);

if (didUnfollow) {
  showSuccessMessage('Unfollowed');
}
```

```dart Flutter
final status = await AmityCoreClient.newUserRepository()
    .relationship()
    .unfollow(targetUserId);

final statusValue = status.value;
```


## Related Topics

    Handle incoming follow requests.
    Read status and counters.
    Query followers and following.

---

### [Accept/Decline Follow Request](https://learn.social.plus/social-plus-sdk/social/user-relationship/following/accept-decline-follow-request)

> Accept or decline incoming follow requests with the social.plus SDKs.

When follow approval is enabled, a follow call creates a pending request. The target user can accept the request to make the relationship active, or decline it to remove the request.

Accept and decline methods operate on requests received by the current user. If the request has already been withdrawn, accepted, or declined, handle the SDK error and refresh the request list or follow info.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Accept follow request | `userId` / `targetUserId` | Yes | ID of the requester whose incoming follow request should be accepted. |
| Decline follow request | `userId` / `targetUserId` | Yes | ID of the requester whose incoming follow request should be declined. |

## Accept Follow Request

Accept an incoming follow request when the current user approves the requester.


```swift iOS
let relationship = AmityUserRelationship()
let response = try await relationship.acceptMyFollower(withUserId: "requester-user-id")
_ = response
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .acceptMyFollower(userId = targetUserId)
    .subscribe(
        {
            showSuccessMessage()
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const didAccept = await UserRepository.Relationship.acceptMyFollower(userId);

if (didAccept) {
  showSuccessMessage('Follow request accepted');
}
```

```dart Flutter
final status = await AmityCoreClient.newUserRepository()
    .relationship()
    .acceptMyFollower(targetUserId);

final statusValue = status.value;
```


## Decline Follow Request

Decline an incoming follow request when the current user does not want to approve the requester.


```swift iOS
let relationship = AmityUserRelationship()
let response = try await relationship.declineMyFollower(withUserId: "requester-user-id")
_ = response
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .declineMyFollower(userId = targetUserId)
    .subscribe(
        {
            showSuccessMessage()
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const didDecline = await UserRepository.Relationship.declineMyFollower(userId);

if (didDecline) {
  showSuccessMessage('Follow request declined');
}
```

```dart Flutter
final status = await AmityCoreClient.newUserRepository()
    .relationship()
    .declineMyFollower(targetUserId);

final statusValue = status.value;
```


## Related Topics

    Create or remove follow relationships.
    Read status and counters.
    Query pending or accepted followers.

---

### [Get Follower/Following List](https://learn.social.plus/social-plus-sdk/social/user-relationship/following/get-follower-following-list)

> Query paginated follower and following lists with the social.plus SDKs.

Use follower and following list APIs when you need to show people lists, pending requests, or accepted relationships. Results are paginated or live depending on the platform.

| List | Description |
| --- | --- |
| Followers | Users who follow the target user |
| Following | Users the target user follows |

Status filters use `accepted`, `pending`, or `all` where the platform exposes them. TypeScript and Flutter support status filters on target-user follower/following builders. iOS and Android support status filters on the current user's follower/following builders; use their target-user builders when you need another user's accepted social graph without a status filter.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Get followers | `userId` / `targetUserId` | Platform-dependent | Target user whose followers should be queried. iOS and Android status-filter snippets use current-user builders. |
| Get following | `userId` / `targetUserId` | Platform-dependent | Target user whose following list should be queried. iOS status-filter snippet uses the current-user builder. |
| Both lists | `status` / status filter | No | Relationship status filter such as accepted, pending, or all where exposed. |
| Both lists | `limit` / page size | No | Page size for paginated follower or following lists. |

## Get Followers

Query followers when your UI needs a paginated people list for a user. The iOS and Android snippets use the current-user builders because those SDKs expose status filters there.


```swift iOS
let relationship = AmityUserRelationship()
let followers = relationship.getMyFollowers(with: .accepted)

_ = followers.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    let relationships = collection.snapshots
    _ = relationships.first?.sourceUser
}

followers.nextPage()
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .getMyFollowers()
    .status(AmityFollowStatusFilter.ACCEPTED)
    .build()
    .query()
    .subscribe(
        { pagingData: PagingData<AmityFollowRelationship> ->
            showSuccessMessage(pagingData)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

let loadMoreFollowers: (() => void) | undefined;

const unsubscribe = UserRepository.Relationship.getFollowers(
  { userId, status: 'accepted' },
  ({ data: followers, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && followers) {
      renderResults(followers);
    }

    loadMoreFollowers = hasNextPage ? onNextPage : undefined;
  },
);
```

```dart Flutter
final page = await AmityCoreClient.newUserRepository()
    .relationship()
    .getFollowers(targetUserId)
    .status(AmityFollowStatusFilter.ACCEPTED)
    .getPagingData(limit: 20);

final relationships = page.data;
```


## Get Following

Query following relationships when your UI needs the users a profile follows. The iOS snippet uses the current-user builder to show status filtering; the Android snippet uses the target-user builder for another user's following list.


```swift iOS
let relationship = AmityUserRelationship()
let followings = relationship.getMyFollowings(with: .accepted)

_ = followings.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    let relationships = collection.snapshots
    _ = relationships.first?.targetUser
}

followings.nextPage()
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .getFollowings(userId = targetUserId)
    .build()
    .query()
    .subscribe(
        { pagingData: PagingData<AmityFollowRelationship> ->
            showSuccessMessage(pagingData)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

let loadMoreFollowings: (() => void) | undefined;

const unsubscribe = UserRepository.Relationship.getFollowings(
  { userId, status: 'accepted' },
  ({ data: followings, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && followings) {
      renderResults(followings);
    }

    loadMoreFollowings = hasNextPage ? onNextPage : undefined;
  },
);
```

```dart Flutter
final page = await AmityCoreClient.newUserRepository()
    .relationship()
    .getFollowings(targetUserId)
    .status(AmityFollowStatusFilter.ACCEPTED)
    .getPagingData(limit: 20);

final relationships = page.data;
```


## Follow Relationship Fields

| Platform | Common fields |
| --- | --- |
| TypeScript | `from`, `to`, `status`, `createdAt`, `updatedAt` |
| iOS | `sourceUserId`, `targetUserId`, `sourceUser`, `targetUser`, `status` |
| Android | `getSourceUser()`, `getTargetUser()`, `getStatus()` |
| Flutter | `sourceUserId`, `targetUserId`, `sourceUser`, `targetUser`, `status`, `createdAt` |

## Related Topics

    Change a relationship.
    Read counts and status.
    Process pending followers.

---

### [Get Connection Status](https://learn.social.plus/social-plus-sdk/social/user-relationship/following/get-connection-status)

> Read follow status and follow counts for the current user or another user.

Use follow info APIs to render profile headers, follow buttons, follower counts, following counts, and pending-request badges.

The current user's follow info returns counts only. Another user's follow info returns counts plus the current user's relationship status toward that user.

| Field | TypeScript | iOS | Android | Flutter |
| --- | --- | --- | --- | --- |
| Follower count | `followerCount` | `followersCount` | `getFollowerCount()` | `followerCount` |
| Following count | `followingCount` | `followingCount` | `getFollowingCount()` | `followingCount` |
| Pending count for current user | `pendingCount` | `pendingCount` | `getPendingRequestCount()` | `pendingRequestCount` |
| Status for another user | `status` | `status` | `getStatus()` | `status` |

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Get my follow info | None | No | Reads the current user's follow counts and pending-request count. |
| Get another user's follow info | `userId` / `targetUserId` | Yes | ID of the user whose counts and relationship status should be read. |
| Live observation | Callback / observer / subscription | Platform-dependent | TypeScript, iOS, and Android examples observe live data. Retain and dispose the returned handle where applicable. |

## Get My Follow Info

Read the current user's follow counts and pending-request count for profile or account surfaces.


```swift iOS
let relationship = AmityUserRelationship()

_ = relationship.getMyFollowInfo().observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    if let info = liveObject.snapshot {
        _ = info.followersCount
        _ = info.followingCount
        _ = info.pendingCount
    }
}
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .getMyFollowInfo()
    .subscribe(
        { info: AmityMyFollowInfo ->
            showSuccessMessage(info.getFollowerCount())
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.Relationship.getMyFollowInfo(
  ({ data: followInfo, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && followInfo) {
      updateUI({
        followers: followInfo.followerCount,
        following: followInfo.followingCount,
        pending: followInfo.pendingCount,
      });
    }
  },
);
```

```dart Flutter
final info = await AmityCoreClient.newUserRepository()
    .relationship()
    .getMyFollowInfo();

final followerCount = info.followerCount;
final followingCount = info.followingCount;
final pendingCount = info.pendingRequestCount;
```


## Get Another User's Follow Info

Read another user's follow info when rendering a profile header or follow button state.


```swift iOS
let relationship = AmityUserRelationship()

_ = relationship.getFollowInfo(withUserId: "target-user-id").observe { liveObject, error in
    if let error {
        handleError(error)
        return
    }

    if let info = liveObject.snapshot {
        _ = info.status
        _ = info.followersCount
        _ = info.followingCount
    }
}
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .getFollowInfo(userId = targetUserId)
    .subscribe(
        { info: AmityUserFollowInfo ->
            showSuccessMessage(info.getStatus().apiKey)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.Relationship.getFollowInfo(
  userId,
  ({ data: followInfo, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && followInfo) {
      updateUI({
        status: followInfo.status,
        followers: followInfo.followerCount,
        following: followInfo.followingCount,
      });
    }
  },
);
```

```dart Flutter
final info = await AmityCoreClient.newUserRepository()
    .relationship()
    .getFollowInfo(targetUserId);

final status = info.status;
final followerCount = info.followerCount;
final followingCount = info.followingCount;
```


## Related Topics

    Change the relationship state.
    Process pending requests.
    Query follower and following lists.

---

### [Block & Unblock User](https://learn.social.plus/social-plus-sdk/social/user-relationship/blocking/block-unblock-user)

> Block or unblock another user with the social.plus SDKs.

Use the block API when the current user wants to block another user. Use the unblock API to remove that block.

The SDK updates relationship data after block and unblock calls. TypeScript returns the updated blocked payload (`follows` and `followCounts`). iOS, Android, and Flutter expose these actions as async or completable operations.

Blocking affects relationship state, but downstream visibility and interaction behavior can vary by feature area and backend configuration. Keep feed, comment, search, and profile screens resilient by handling errors from those feature APIs and refreshing relationship status after block or unblock actions.

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Block user | `userId` / `targetUserId` | Yes | ID of the user the current user wants to block. |
| Unblock user | `userId` / `targetUserId` | Yes | ID of the user the current user wants to unblock. |

## Block User

Block a user when the current user wants to prevent or limit relationship-based interactions with that account.


```swift iOS
let relationship = AmityUserRelationship()
try await relationship.blockUser(userId: "target-user-id")
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .blockUser(userId = targetUserId)
    .subscribe(
        {
            showSuccessMessage()
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const result = await UserRepository.Relationship.blockUser(userId);

const followStatus = result.follows[0]?.status;
const followCount = result.followCounts[0];
```

```dart Flutter
await AmityCoreClient.newUserRepository()
    .relationship()
    .blockUser(targetUserId);
```


### Handle the blocked-user limit

A network caps how many users one account can block. When the current user is already at that cap, the block call fails with a "maximum blocked users reached" error instead of succeeding. On TypeScript this surfaces as the server error code `Amity.ServerError.MAX_BLOCKED_USERS_REACHED` (`400324`). Catch it and prompt the user to unblock someone before blocking another account.


```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

try {
  await UserRepository.Relationship.blockUser(userId);
} catch (error) {
  if (error?.code === Amity.ServerError.MAX_BLOCKED_USERS_REACHED) {
    showBlockedUserLimitReached();
    return;
  }
  handleError(error);
}
```

```swift iOS
let relationship = AmityUserRelationship()
do {
    try await relationship.blockUser(userId: "target-user-id")
    showSuccessMessage()
} catch {
    if error.isAmityErrorCode(.maxBlockedUsersReached) {
        // Already at the per-network block cap — prompt the user to unblock someone first.
        showBlockedUserLimitReached()
    } else {
        handleError(error)
    }
}
```

```kotlin Android
AmityCoreClient.newUserRepository()
    .relationship()
    .blockUser(userId = targetUserId)
    .doOnComplete {
        showSuccessMessage()
    }
    .doOnError { error ->
        if (AmityError.from(error) == AmityError.MAX_BLOCKED_USERS_REACHED) {
            // Already at the per-network block cap — prompt the user to unblock someone first.
            showBlockedUserLimitReached()
        } else {
            handleGeneralError(error)
        }
    }
    .subscribe()
```


## Unblock User

Unblock a user when the current user removes a previously created block.


```swift iOS
let relationship = AmityUserRelationship()
try await relationship.unblockUser(userId: "target-user-id")
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .relationship()
    .unblockUser(userId = targetUserId)
    .subscribe(
        {
            showSuccessMessage()
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const result = await UserRepository.Relationship.unBlockUser(userId);

const followStatus = result.follows[0]?.status;
const followCount = result.followCounts[0];
```

```dart Flutter
await AmityCoreClient.newUserRepository()
    .relationship()
    .unblockUser(targetUserId);
```


## After Block Or Unblock

After a successful block or unblock action:

- Refresh follow info if the current screen shows relationship status or counters.
- Refresh follower/following lists if the current screen displays social graph data.
- Refresh blocked-user lists if the current screen lets users manage blocked accounts.
- Handle errors from other feature APIs instead of assuming all product surfaces update in the same way.

## Related Topics

    Query the blocked-user list.
    Query the reverse direction.
    Change follow relationships.

---

### [Manage Blocked Users](https://learn.social.plus/social-plus-sdk/social/user-relationship/blocking/manage-blocked-users)

> Query the current user's blocked-user list with the social.plus SDKs.

Use blocked-user list APIs to build a settings screen where users can review accounts they have blocked and unblock them when needed.

There are two read patterns:

| API | Best for | Platforms |
| --- | --- | --- |
| `getBlockedUsers()` | A paginated management screen | TypeScript, iOS, Android, Flutter |
| `getAllBlockedUsers()` | A one-shot list for local decisions | TypeScript, iOS, Android |

These APIs return users the current user has **blocked**. To read the reverse direction — users who have **blocked the current user** — see [Users Who Blocked You](./manage-blocking-users).

## Parameters

| Operation | Parameter | Required | Description |
| --- | --- | --- | --- |
| Get blocked users | `limit` / page size | No | Page size for the paginated blocked-user list where the platform exposes it. |
| Get blocked users | Pagination handle | No | Use each platform's live collection, paging, or callback pagination to load more blocked users. |
| Get all blocked users | None | No | Returns a one-shot list on TypeScript, iOS, and Android. Not exposed in the current public Flutter repository. |

## Get Blocked Users

Query blocked users for a paginated account-management screen.


```swift iOS
let repository = AmityUserRepository()
let blockedUsers = repository.getBlockedUsers()

_ = blockedUsers.observe { collection, error in
    if let error {
        handleError(error)
        return
    }

    let users = collection.snapshots
    _ = users.first?.userId
}

blockedUsers.nextPage()
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .getBlockedUsers()
    .subscribe(
        { pagingData: PagingData<AmityUser> ->
            showSuccessMessage(pagingData)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

let loadMoreBlockedUsers: (() => void) | undefined;

const unsubscribe = UserRepository.getBlockedUsers(
  { limit: 25 },
  ({ data: users, onNextPage, hasNextPage, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && users) {
      renderResults(users);
    }

    loadMoreBlockedUsers = hasNextPage ? onNextPage : undefined;
  },
);
```

```dart Flutter
final page = await AmityCoreClient.newUserRepository()
    .getBlockedUsers()
    .getPagingData(limit: 20);

final blockedUsers = page.data;
```


## Get All Blocked Users

Use `getAllBlockedUsers()` when your app needs a one-shot list instead of a paginated collection. TypeScript, iOS, and Android return up to 100 blocked users and use a short SDK-side cache. Call the method again when you need a fresh snapshot.


```swift iOS
let repository = AmityUserRepository()
let blockedUsers = try await repository.getAllBlockedUsers()

let blockedUserIds = Set(blockedUsers.map { $0.userId })
```

```kotlin Android
val disposable = AmityCoreClient.newUserRepository()
    .getAllBlockedUsers()
    .subscribe(
        { users: List<AmityUser> ->
            val blockedUserIds = users.map { it.getUserId() }.toSet()
            showSuccessMessage(blockedUserIds)
        },
        { error ->
            handleGeneralError(error)
        },
    )
```

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const blockedUsers = await UserRepository.getAllBlockedUsers();
const blockedUserIds = new Set(blockedUsers.map((user) => user.userId));
```


The one-shot API is not available in the Flutter public repository. For Flutter, use `getBlockedUsers().getPagingData(...)` and page through the result.

## Related Topics

    Query the reverse direction.
    Change blocked status.
    Query social graph lists.

## UIKit — Overview & Getting Started

### [social.plus UIKit](https://learn.social.plus/uikit/overview)

> Build beautiful social applications with pre-built UI components. Cross-platform support for iOS, Android, Web, React Native, and Flutter.

![UI Kit Dark Pn](/images/UIKit-Dark.png)

# Build Social Apps 10x Faster

social.plus UIKit is the **most comprehensive collection of pre-built social UI components** designed to help you create engaging social applications in days, not months. With cross-platform support and extensive customization options, UIKit provides everything you need to build modern social experiences.

<div className="not-prose">
  Get Started Free

  Browse Components

</div>

<div className="not-prose">
  <iframe
    id="demo-iframe"
    src="https://uikiss.social.plus/"
    width="100%"
    height="800"
    style={{ border: "1px solid #e5e7eb", borderRadius: "8px", zoom: "0.75" }}
  />
</div>

<p style={{ fontSize: "13px", color: "#6b7280", marginTop: "12px", marginBottom: "24px" }}>
  This showcases the UIKit's features and design. Note: some functionality is simulated and write actions are disabled/broken for demo purposes.
</p>

## Why 1000\+ Developers Choose UIKit

    Skip months of UI development with **50\+ pre-built components**. Go from idea to launch in weeks.
    Reduce development costs by **80%** with ready-to-use components instead of building from scratch.
    Multiple platform support: iOS, Android, Web, React Native, and Flutter support.

## Choose Your Approach

Before diving into UIKit, **choose the right approach** based on your customization needs:

    **Use Dynamic UI Out-of-the-Box**

    - Colors, text, and basic styling
    - No code changes required
    - Perfect for brand consistency
    - Real-time updates without app releases
    title="Moderate Customization"
    icon="paintbrush"
    href="/uikit/customization/component-styling"
  >
    **Leverage Component Styling**

    - Custom json configuration and styling overrides
    - More advanced theming options
    - Component-level modifications
    - Still within UIKit framework
    **Fork and Extend from GitHub Repository**

    - Complete control over components
    - Custom layouts and workflows
    - Jumpstart for your project
    - Maintain your own version
    **Use SDK or API Directly**

    - Build completely custom interfaces
    - Full design freedom
    - Maximum flexibility
    - Custom user experiences

  **Need help deciding?** Start with Dynamic UI for quick wins, then consider forking if you need deeper customization, or use the SDK for completely custom experiences.

## Component Categories

### Chat & Messaging

Real-time communication components for building chat experiences:

    Real-time live chat for streaming and events
    One-on-one and group messaging interfaces
    Chat list and channel management

### Social Components

Build comprehensive social experiences:

    Dynamic content feeds with infinite scroll
    Rich post creation and comment systems
    Like, love, and custom reaction systems

    Community creation and management
    User profiles and social connections
    Built-in moderation and safety tools

### Story Components

Create engaging ephemeral content experiences:

    Creation & viewing with media, text, and effects

## Platform Support

social.plus UIKit provides comprehensive cross-platform support with a mobile-first approach:

    **iOS & Android**

    - Native performance and platform integration
    - Platform-specific design guidelines
    - Optimized for mobile user experience
    - Full access to device capabilities
    **React Native & Flutter**

    - Single codebase, multiple platforms
    - Native performance with cross-platform efficiency
    - Consistent UI across iOS and Android
    - Reduced development time and maintenance

    **React Web**

    - Mobile-responsive design
    - Desktop view support for optimal web experience
    - Progressive Web App (PWA) compatibility
    - Modern web technologies and best practices

## Why Choose social.plus UIKit?

    - **Pre-built Components**: Skip months of UI development
    - **Plug-and-Play**: Components work out of the box
    - **Comprehensive**: Everything needed for social applications
    - **Battle-tested**: Used by thousands of production apps
    - **Modern Interface**: Contemporary design following latest trends
    - **Mobile-first**: Optimized for mobile user experience
    - **Desktop Support**: NEW responsive design for web applications
    - **Consistent**: Uniform experience across all platforms
    - **Theme System**: Comprehensive theming with light/dark modes
    - **Dynamic UI**: Real-time customization without app updates
    - **Brand Alignment**: Match your exact brand guidelines
    - **Component Control**: Granular control over individual components
    - **Scalable**: Built to handle millions of users
    - **Secure**: Industry-standard security practices
    - **Reliable**: 99.9% uptime SLA
    - **Support**: Dedicated enterprise support team

## Release Notes

Stay up-to-date with the latest UIKit features, improvements, and bug fixes:

    Latest updates and releases for iOS UIKit
    Latest updates and releases for Android UIKit
    Latest updates and releases for Web UIKit
    Latest updates and releases for React Native UIKit
    Latest updates and releases for Flutter UIKit


## What's Next

UIKit 4 is just the beginning. We're continuously evolving the platform with:

- **New Components**: Expanding our library with more social and business components
- **Enhanced Customization**: More granular control over component behavior
- **Performance Optimizations**: Faster rendering and better memory management
- **Advanced Features**: AI-powered moderation, analytics, and personalization

---

    Connect with other developers, share experiences, and get help from our community
    Access our support resources, submit tickets, and get expert assistance

  **Ready to Build Something Amazing?**

  social.plus UIKit provides everything you need to create engaging social applications. From rapid prototyping to production deployment, we've got the tools and components to bring your vision to life.

  [Get Started Now →](/uikit/getting-started/overview)

---

### [Quick Start](https://learn.social.plus/uikit/getting-started/overview)

> Your complete guide to building social apps with social.plus UIKit - from installation to your first component

Welcome to social.plus UIKit! This guide will get you from zero to a working social app in **under 15 minutes**. Follow these steps to add complete social features to your app.

## Quick Start Guide

    Select the UIKit that matches your development environment and install:

        - [Native Mobile UIKit: iOS, Android](/uikit/getting-started/installation)
        - [Web UIKit: React](/uikit/getting-started/installation)
        - [Cross-Platform UIKit: Flutter, React Native](/uikit/getting-started/installation)

    **Installation Options**: Choose **package installation** for quick setup or **GitHub forking** for complete customization. React Native and Flutter are only available through GitHub forking.

    1. Visit the Admin Console
    2. Navigate to **Applications** → **Your App** → **Settings**
    3. Copy your API key and note your region (US, EU, or SG)

    Keep your API key secure. For production apps, implement proper server-side authentication.

    Install UIKit and set up with your API credentials (for more details, see the [authentication guide](/uikit/getting-started/authentication)):

```swift iOS
// Add to your AppDelegate or SceneDelegate
import AmityUIKit

AmityUIKitManager.setup(
    apiKey: "your-api-key",
    region: .US  // .US, .EU, or .SG
)

// Register user when the user accesses the feature
AmityUIKitManager.registerDevice(
  withUserId: "USER_ID",
  displayName: "Ali Connors",
  authToken: "AUTH_TOKEN"
)
```

```kotlin Android
// In your Application class
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        AmityUIKit4Manager.setup(
            apiKey = "your-api-key",
            endpoint = AmityEndpoint.US
        )
    }
}

// Register user when the user accesses the feature
fun login(userId: String, authToken: String) {
  AmityCoreClient.login(
    userId = userId,
    sessionHandler = object : SessionHandler {
        override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
            renewal.renew()
            }
          }
      ).authToken(authToken)
    .build()
    .submit()
    .subscribeOn(Schedulers.io())
    .doOnError {
        // Exception
    }
    .subscribe()
  }
```

```typescript React
import { AmityUIKitProvider } from '@amityco/ui-kit';
import '@amityco/ui-kit/dist/index.css';

const isGoogleBotOrInspectionTool: boolean = false // can add condition to check if user agent is google bot will be true

function App() {
  return (
    <AmityUiKitProvider
      key={userId}
      apiKey={apiKey}
      userId={userId}
      apiRegion={apiRegion} //eu, us, or sg
      getAuthToken={getAuthToken} //for secure mode authentication
      onRouteChange={(page) => {
          console.log("Route changed to:", page); // integrate with your analytics service
      }}
      seoOptimizationEnabled={isGoogleBotOrInspectionTool} // default value is false, if pass true MQTT will be disabled.
    >
      <div
        style={{
          position: "absolute",
          left: 0,
          top: 0,
          width: "100vw",
          height: "100dvh",
        }}
      >
        <AmityUiKitSocial />
      </div>
    </AmityUiKitProvider>
  );
}
```

```jsx React Native
import {
  AmityUiKitProvider,
  AmityUiKitSocial,
} from '@amityco/react-native-social-uikit';

export default function App() {
  return (
    <AmityUiKitProvider
      apiKey="your-api-key"
      apiRegion="us"
      userId="user123"
      displayName="John Doe"
    >
      {/* Render <AmityUiKitChat /> instead to mount chat (v4.3.0+) */}
      <AmityUiKitSocial />
    </AmityUiKitProvider>
  );
}
```

```dart Flutter
import 'package:flutter/material.dart';
import 'package:amity_uikit_beta_service/amity_uikit.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize the SDK before showing any UIKit screen.
  await AmityUIKit().setup(
    apikey: 'YOUR_API_KEY',
    region: AmityEndpointRegion.sg, // .us, .eu, or .sg
  );

  runApp(const MyApp());
}

// 2. Register (log in) the user. registerDevice needs a BuildContext that
// sits BELOW AmityUIKitProvider — see the next step for how AuthGate calls it.
void login(BuildContext context) {
  AmityUIKit().registerDevice(
    context: context,
    userId: 'USER_ID',
    displayName: 'DISPLAY_NAME', // optional
    // authToken: 'AUTH_TOKEN',  // only when secure mode is enabled
    callback: (isSuccess, error) {
      if (!isSuccess) {
        debugPrint('Login failed: $error');
      }
    },
  );
}
```

    Start with a social feed or any component that fits your app:

```swift iOS
let socialHomePage = AmitySocialHomePage()
let navigationViewController = AmitySwiftUIHostingNavigationController(rootView: socialHomePage)
```

```kotlin Android
@Composable
fun composeSocialHomePage() {
AmitySocialHomePage()
}

fun startAnActivity(context: Context) {
  val intent = Intent(
    context,
    AmitySocialHomePageActivity::class.java
    )
    context.startActivity(intent)
}
```

```jsx React
import React from 'react';
import { AmityUiKitProvider, AmitySocialHomePage } from '@amityco/ui-kit';
const SampleAmitySocialHomePage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config} //put your customized config json object
    >
      <AmitySocialHomePage />
    </AmityUiKitProvider>
  );
};

export default SampleAmitySocialHomePage;
```

```jsx React Native
import {
  AmitySocialHomePage,
  AmityUiKitProvider,
  } from '@amityco/react-native-social-uikit';
  import React from 'react';
  import config from '../../uikit.config.json';
  <AmityUiKitProvider
    configs={config} //put your customized config json object
    apiKey="API_KEY"
    apiRegion="API_REGION"
    userId="userId"
    displayName="displayName"
    apiEndpoint="https://api.{API_REGION}.amity.co"
  />
  behaviour={{
AmitySocialHomePageBehaviour: { onChooseTab: (tab) => console.log(tab) },
  }}
>
  <AmitySocialHomePage />
</AmityUiKitProvider>;
```

```dart Flutter
import 'package:flutter/material.dart';
import 'package:amity_uikit_beta_service/amity_uikit.dart';
import 'package:amity_uikit_beta_service/v4/utils/config_provider_widget.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize UIKit
  await AmityUIKit().setup(
    apikey: 'YOUR_API_KEY',
    region: AmityEndpointRegion.eu, // .us, .eu, or .sg
  );

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AmityUIKitProvider(
      child: LoginGate(),
    );
  }
}

class LoginGate extends StatefulWidget {
  @override
  State<LoginGate> createState() => _LoginGateState();
}

class _LoginGateState extends State<LoginGate> {
  bool _loggedIn = false;
  String? _error;

  @override
  void initState() {
    super.initState();
    AmityUIKit().registerDevice(
      context: context,
      userId: 'userId1',
      callback: (isSuccess, error) {
        if (!mounted) return;
        setState(() {
          _loggedIn = isSuccess;
          _error = error;
        });
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    if (_loggedIn) {
      return SocialHomePageConfigProviderWidget();
    }
    if (_error != null) {
      return Scaffold(body: Center(child: Text('Login failed: $_error')));
    }
    return const Scaffold(body: Center(child: CircularProgressIndicator()));
  }
}
```

## Development Paths

UIKit offers four progressive customization levels. Start at the lowest level that solves today’s need—move up only when you hit a limitation. Each level layers on the previous one; no throwaway work.

    Remote + conditional configuration & layout: role‑based visibility, experiments, feature flags, runtime theme adjustments.
    <br/><br/>
    Use when you need server‑driven variations without redeploys.

    Targeted page / component / element overrides: icons, button styles, layout spacing, per‑feature navigation behavior.
    <br/><br/>
    Use when a few components need deeper tweaks beyond tokens.

    Full source fork for new UX paradigms, custom data flows, or deep platform integrations.
    <br/><br/>
    Use only when earlier layers cannot achieve your required behavior.

Decision shortcut:
- Role/experiment/change colors on-the-fly → <a href="/uikit/customization/dynamic-ui">Level 1: Dynamic UI</a>
- Specific component/layout tweaks → <a href="/uikit/customization/component-styling">Level 2: Component Styling</a>
- Net‑new interaction model → <a href="/uikit/customization/advanced-customization">Level 3: Fork & Extend</a>

You can safely prototype at Level 1 and graduate upward without rewriting work—higher levels augment, not replace, earlier configuration.

## Installation Methods

UIKit offers two installation approaches to match your development needs:

    **Quick Setup (Recommended)**

    ✅ **Platforms**: iOS, Android, Web
    ❌ **Not available**: Flutter, React Native

    - Managed dependencies and updates
    - Minimal configuration required
    - Perfect for most use cases
    - Easy version management
    **Complete Customization**

    ✅ **All Platforms**: iOS, Android,Web, Flutter, React Native

    - Full source code access
    - Custom modifications possible
    - Advanced integrations
    - Maximum flexibility

**React Native Special Case**: React Native UIKit is only available through GitHub forking, giving you complete control over the implementation.

## Use Case Examples

Choose your starting point based on what you want to build:

    **Perfect for**: Instagram-like apps, social networks, content sharing platforms

    **Start with these components:**
    1. Social Feed - Display user posts and content
    2. User Profiles - User information and social connections
    3. Post Creation - Rich content creation tools
    4. Comments & Reactions - User engagement features

    **Timeline**: 1-2 weeks for MVP

    **Perfect for**: Forums, interest groups, professional networks

    **Start with these components:**
    1. Communities - Group creation and management
    2. Community Feed - Group-specific content
    3. Member Management - Roles and permissions
    4. Moderation Tools - Content safety features

    **Timeline**: 2-3 weeks for MVP

    **Perfect for**: Influencer apps, creator tools, content platforms

    **Start with these components:**
    1. Story Creation - Rich multimedia stories
    2. Story Viewing - Immersive story experience
    3. Social Feed - Creator content distribution
    4. User Profiles - Creator showcase pages

    **Timeline**: 2-3 weeks for MVP

## Ready to Start?

Choose your next step based on your current status:

    **Start with Installation**

    Set up UIKit for your platform and get your development environment ready.
    **Configure Authentication**

    Set up your API credentials and user authentication system.
    **Customize UIKit**

    Customize UIkit to match your app's branding and user experience.

**Quick Win**: If you just want to see UIKit in action, follow our [5-minute setup guide](/uikit/getting-started/installation) and add a social feed to your app!

---

### [Installation](https://learn.social.plus/uikit/getting-started/installation)

> Install social.plus UIKit across all platforms with package managers or GitHub source code

Choose your platform and installation method to get started with social.plus UIKit. We support both **package installation** for quick setup and **GitHub forking** for complete customization.

  **Two Installation Approaches**: Use package installation for quick
  integration, or fork from GitHub for complete control and customization.

## Installation Methods

    **Quick Setup (Recommended)**

    - Managed dependencies
    - Easy updates
    - Minimal configuration
    - Perfect for most use cases

    **Complete Customization**

    - Full source code access
    - Custom modifications
    - Advanced integrations
    - Maximum flexibility


---

## Package Installation

Install UIKit through package managers for quick integration:

    ### Prerequisites

    - iOS 15.0 or later
    - Xcode 26.0 or later
    - Swift 6.0 or later

    ### Installation Steps

        **Add Package Dependency in Xcode:**

        1. Open your project in Xcode
        2. Go to **File → Add Package Dependencies**
        3. Enter the repository URL:

```
https://github.com/AmityCo/Amity-Social-Cloud-UIKit-iOS-SwiftPM
```

        4. Select dependency rule (Up to Next Major for stable releases)

          \*\*Please specify the required version of the UIKit using `Exact Version` Dependency Rule as shown in the image below.

          For Example: `Exact Version` `4.6.0`
        5. Choose the latest version and add to your target

        **Import in your code:**

```swift
import AmityUIKit
```
    ### Initialize UIKit

```swift
// In your AppDelegate or SceneDelegate
import AmityUIKit

AmityUIKitManager.setup(
    apiKey: "YOUR_API_KEY",
    endpoint: .US  // .US, .EU, or .SG
)

// Register user and present social home
AmityUIKitManager.registerDevice(
    withUserId: "user123",
    displayName: "John Doe"
) { success, error in
    if success {
        AmityUIKitManager.presentSocialHome()
    }
}
```

    ### Required Permissions (Info.plist)

```xml
<key>NSCameraUsageDescription</key>
<string>Access camera to take photos and videos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Access photo library to select images</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access microphone for video recording</string>
```

    ### Prerequisites

    - Android 5.0 (API Level 21) or higher
    - Kotlin support enabled
    - Data binding enabled

    ### Gradle Configuration

    **Project-level build.gradle:**

```gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
```

    **App-level build.gradle:**

```gradle
android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        targetSdk 34
    }

    buildFeatures {
        dataBinding = true
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }

    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}

dependencies {
    implementation 'com.github.AmityCo.Amity-Social-Cloud-UIKit-Android:amity-uikit:x.y.z'
}
```

    ### Initialize UIKit

```kotlin
// In your Application class
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

    AmityUIKit4Manager.setup(
            apiKey = "YOUR_API_KEY",
            endpoint =  AmityEndpoint.EU
        )
    }
}
```

    ### Prerequisites

    - React 18 or later (hooks support required)
    - Node.js 16 or later
    - TypeScript support (recommended)
    - Modern browser with ES6+ support

    ### Installation

```bash
pnpm i @amityco/ui-kit
```

    ### Setup AmityUIKitProvider

```typescript
import React from 'react';
import { AmityUIKitProvider } from '@amityco/ui-kit-react';
import '@amityco/ui-kit-react/dist/index.css';

function App() {
  return (
    <AmityUIKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"  // "us", "eu", or "sg"
      userId="user123"
      displayName="John Doe"
    >
      <YourAppComponents />
    </AmityUIKitProvider>
  );
}

export default App;
```

    Our UIKit includes user interfaces to enable fast integration of standard Social features into new or existing applications. The React Native UIKit supports integration with **React Native CLI**, providing you with a flexible experience to seamlessly integrate social features into your existing React Native application.

      React Native UIKit v4 is **generally available** and published on npm as [`@amityco/react-native-social-uikit`](https://www.npmjs.com/package/@amityco/react-native-social-uikit).

      **Important**: If you'd like to use React Native Expo, please visit the [Expo repository](https://github.com/AmityCo/Amity-Social-UIKit-React-Native-OpenSource) instead.

    ### Minimum Requirements

    | Requirement | Version |
    | --- | --- |
    | React | 19 |
    | React Native | 0.82.1 |
    | Node.js | ≥ 20 |
    | Yarn | ≥ 1.22.15 |
    | JDK | ≥ 17.0.10 |
    | Kotlin | 2.1.20 |
    | iOS deployment target | 15.1 |
    | Android | `minSdkVersion` 24, `compileSdkVersion` 36, `targetSdkVersion` 36, `buildToolsVersion` 36.0.0 |

    React Native CLI is required (not Expo).

    ### Install the UIKit

```bash
# Install the UIKit
yarn add @amityco/react-native-social-uikit

# Install required peer dependencies
yarn add @amityco/ts-sdk-react-native@^7.28.0 react-native-fs@2.20.0 react-native-reanimated@~4.3.4 react-native-worklets@~0.8.3 @livekit/react-native @livekit/react-native-webrtc livekit-client @react-native-firebase/app @react-native-firebase/messaging @react-native-async-storage/async-storage @react-native-camera-roll/camera-roll @react-native-clipboard/clipboard @react-native-community/datetimepicker "@react-native-community/netinfo@>=11.5.0" @react-navigation/native @react-navigation/native-stack @react-navigation/stack react-native-compressor react-native-gesture-handler react-native-get-random-values react-native-haptic-feedback react-native-image-picker react-native-linear-gradient react-native-safe-area-context react-native-screens react-native-svg react-native-video react-native-video-controls react-native-vision-camera @babel/plugin-transform-export-namespace-from

# Build-time only
yarn add -D @react-native/babel-preset @react-native/metro-config
```

      `react-native-fs` is pinned to `2.20.0`, and `react-native-reanimated` (`~4.3.4`) and `react-native-worklets` (`~0.8.3`) are pinned to a patch range. Installing versions outside these is unsupported. `@amityco/ts-sdk-react-native` must be `7.28.0` or later.

      **Upgrading from 4.2.x:** v4.3.0 adds `react-native-reanimated`, `react-native-worklets`, and `@react-native-camera-roll/camera-roll` as peer dependencies, and raises `@react-native-community/netinfo` to `>=11.5.0`. The `react-native-netinfo` package is no longer required — remove it if your app only installed it for the UIKit. Then complete the Babel and [save-to-gallery permission](#required-permissions) steps below.

    ### Configure Babel

    Register both Babel plugins in your app's `babel.config.js`, or the build fails. `react-native-worklets/plugin` must be the **last** entry in `plugins`:

```js babel.config.js
module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    '@babel/plugin-transform-export-namespace-from',
    // Must be the last plugin in the list.
    'react-native-worklets/plugin',
  ],
};
```

      `metro-react-native-babel-preset` is obsolete. If your app still uses it, replace it with `module:@react-native/babel-preset`.

      To customize the UIKit source, see the React Native tab under [GitHub Fork Installation](#github-fork-installation).

    ### Platform Configuration

    **iOS Configuration (ios/Podfile):**

```ruby
platform :ios, '15.1'  # Minimum iOS 15.1

target 'YourApp' do
 config = use_native_modules!

  # Required for UIKit functionality
  pod 'SPTPersistentCache', :modular_headers => true
  pod 'DVAssetLoaderDelegate', :modular_headers => true
  $RNVideoUseVideoCaching = true

  # Your other dependencies...
end
```

    **iOS Deployment Target:**

    - In Xcode, set **Minimum Deployments** to at least **iOS 15.1**

    **Install iOS dependencies:**

```bash
npx pod-install
```

    **Android Configuration (android/build.gradle):**

```gradle
buildscript {
    ext {
        kotlinVersion = "2.1.20"
        minSdkVersion = 24
        compileSdkVersion = 36
        targetSdkVersion = 36
        buildToolsVersion = "36.0.0"
        // ... other configurations
    }
}
```

    ### Required Permissions

    **iOS Permissions (ios/YourApp/Info.plist):**

```xml
<key>NSCameraUsageDescription</key>
<string>App needs access to the camera to take photos</string>
<key>NSMicrophoneUsageDescription</key>
<string>App needs access to the microphone to record audio</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>App needs access to the gallery to select photos</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>App needs access to save photos and videos to your gallery</string>
```

    **Android Permissions (android/app/src/main/AndroidManifest.xml):**

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission
  android:name="android.permission.WRITE_EXTERNAL_STORAGE"
  android:maxSdkVersion="28" />
```

      **Required from v4.3.0.** Chat lets users save photos and videos to the device gallery.
      - **iOS:** without `NSPhotoLibraryAddUsageDescription`, iOS terminates the app the first time a user saves media.
      - **Android:** Android 9 (API 28) and below need `WRITE_EXTERNAL_STORAGE` to save to the gallery. Without it, saving always fails with a permission error. Keep `android:maxSdkVersion="28"`: Android 10 and above don't need the permission.

    ### Basic Usage

    **Simple Integration:**

    `AmityUiKitSocial` mounts the full social experience. To mount chat instead, render `AmityUiKitChat` — see [Add Chat](#add-chat) below.

```jsx
import React from 'react';
import {
  AmityUiKitSocial,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';

export default function App() {
  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"  // "us", "eu", or "sg"
      userId="user123"
      displayName="John Doe"
      apiEndpoint="https://api.us.amity.co"  // Optional if using default endpoints
    >
      <AmityUiKitSocial />
    </AmityUiKitProvider>
  );
}
```

    ### Add Chat

    From v4.3.0, the same package includes Chat UIKit. Render `AmityUiKitChat` inside `AmityUiKitProvider` to mount the chat experience, starting at the chat list. It needs no extra package and uses the same provider props as `AmityUiKitSocial`.

    From v4.3.1, each chat page can also be rendered on its own inside `AmityPageRenderer` — see [Chat Components](/uikit/components/chat/overview#quick-start-example).

```jsx
import React from 'react';
import {
  AmityUiKitChat,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';

export default function ChatScreen() {
  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"
      userId="user123"
      displayName="John Doe"
    >
      <AmityUiKitChat />
    </AmityUiKitProvider>
  );
}
```

    ### Individual Screen Components

    Instead of mounting the whole UIKit, you can render a single page or component inside `AmityPageRenderer`, which sets up the navigation the UIKit screens need.

```jsx
import React from 'react';
import {
  AmityUiKitProvider,
  AmityPageRenderer,  // Required for individual screens
  CommunityProfilePage,
} from '@amityco/react-native-social-uikit';

export default function App() {
  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us"
      userId="user123"
      displayName="John Doe"
    >
      <AmityPageRenderer>
        <CommunityProfilePage defaultCommunityId="community123" />
      </AmityPageRenderer>
    </AmityUiKitProvider>
  );
}
```

    For the pages and components you can render this way, see the React Native examples in [Social Components](/uikit/components/social/overview) and, from v4.3.1, [Chat Components](/uikit/components/chat/overview).

      **Note**: `AmityPageRenderer` is only required when using individual screen components. It's not needed for `AmityUiKitSocial` or `AmityUiKitChat`.
    ### React Navigation v7 Migration

    If you're upgrading to React Navigation v7, follow these steps:

    **1. Upgrade Dependencies:** Update these packages to match UIKit's exact versions in `package.json`:

    - `@react-navigation/native`
    - `@react-navigation/native-stack`
    - `@react-navigation/stack`
    - `react-native-screens`

    **`2. Replace independent={true} with NavigationIndependentTree:`**

    **Before:**

```jsx
<NavigationContainer independent={true}>
  {/* Your navigators */}
</NavigationContainer>
```

    **After:**

```jsx
import { NavigationIndependentTree } from '@react-navigation/native';

<NavigationIndependentTree>
  <NavigationContainer>
    {/* Your navigators */}
  </NavigationContainer>
</NavigationIndependentTree>
```


---

## GitHub Fork Installation

For complete customization and control over the UIKit source code:

  **Note**: The Flutter UIKit is only available through GitHub forking, not
  package installation. React Native is available both ways: install from npm
  under [Package Installation](#package-installation), or fork it here to
  customize the source.

    ### Fork Repository

    1. Fork the [iOS UIKit repository](https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource)
    2. Clone your forked repository:

```bash
git clone https://github.com/YOUR_USERNAME/ASC-UIKit-iOS-OpenSource.git
```

    ### Open-source Installation

    With open-source, developers have more flexibility and greater customization options, allowing you to have complete control over the visual style. Open sourcing allows for more transparency and visibility and enables contributions from a greater developer community in terms of good design, implementation, code improvement, and fixes, translating into a better product and typical development.

    ### Migration from Existing Project

    #### Remove Existing Dependencies (If Applicable)

    If you've never used UI Kit, you may skip this step and proceed to the next step. If you're integrating the UI Kit with an existing project, you'll need to remove and unlink the managed UIKit from your project before proceeding with the integration.

    ### Migrate to iOS UIKit Open Source

    There are several ways for you to migrate the open-source iOS UIKit into your projects, depending on your workflow. One way that we recommend is via Git Submodule. This instruction assumes that the app project is already set up with a Git repository.

    **1. Add the git submodule of social.plus UIKit open source into your git repository:**

```bash
git submodule add https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource
```

    **2. Create an Xcode Workspace, and then add both MyApp.xcodeproj and AmityUIKit.xcodeproj together under the same workspace.**

    ![iOS Open Source Project Directory Structure](/images/ios-opensource-directory.png)

    <div align="center">
    ![Xcode Workspace Project Structure](/images/ios-opensource-xcode-workspace-project-structure.png)

    </div>

    **3. AmityUIKit links with other dependencies such as AmitySDK through SharedFrameworks which is a Swift Package.**

    - **3.1 Reset the Package Cache of your Application Target i.e YourApp.xcodeproj. [If you are installing AmityUIKit for the first time, you can skip this step]**

      Select App Target In Xcode Project → Select File Menu for Xcode→ Packages → Reset Package Cache
    - **3.2 Link SharedFrameworks & AmityUIKit.framework to YourApp.xcodeproj target as shown below.**

      ![Link SharedFrameworks to iOS Project](/images/ios-opensource-link-framework.png)

      ![Link AmityUIKit Framework to iOS Project](/images/ios-opensource-link-framework-2.png)

    **4. On MyApp.xcodeproj, let's try importing social.plus UIKit / social.plus SDK and call some APIs. You should be able to compile and run the app.**

    ![iOS Integration Example](/images/ios-opensource-integration-example.png)

    ### Modify iOS Open Source UIKit

    You can modify the iOS open-source UIKit to customize behaviors to fit your needs. To modify the code, simply copy and paste it into your local machine.

    We recommend that you first fork the repository before starting any customization work so that it will be easier to merge the code with the next version update that we provide from the main repository.

    References on forking: https://docs.github.com/en/get-started/quickstart/fork-a-repo

    ### Get Latest iOS Open Source UIKit Updates

    To update to the latest version of the UIKit, you can pull the latest commit of the git submodule.

```bash
cd https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource
git pull origin master
git checkout tags/4.0.0-beta01
cd ..
git add .
git commit -m "Update ios uikit opensource submodule"
git push origin master
```

    ### Required Setup

    **Info.plist Permissions:**

```xml
<key>NSCameraUsageDescription</key>
<string>Access camera to take photos and videos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Access photo library to select images</string>
<key>NSMicrophoneUsageDescription</key>
<string>Access microphone for video recording</string>
```

    **Initialize in AppDelegate:**

```swift
import AmityUIKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AmityUIKitManager.setup(
        apiKey: "YOUR_API_KEY",
        endpoint: .US  // .US, .EU, or .SG
    )
    return true
}
```

    ### Customization Benefits

    - **Complete UI Control**: Modify view controllers, storyboards, XIB files, and Swift UI components
    - **Custom Theming**: Change colors, fonts, images, and styling throughout the app
    - **Business Logic**: Add custom validation, analytics, user flows, and integrations
    - **Advanced Features**: Implement custom post types, moderation rules, and push notifications
    - **Native Performance**: Direct access to native iOS optimizations and latest features
    - **Version Control**: Track changes and manage updates through your own repository

    ### Fork Repository

    1. Fork the [Android UIKit repository](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android-OpenSource)
    2. Clone your forked repository:

```bash
git clone https://github.com/YOUR_USERNAME/Amity-Social-Cloud-UIKit-Android-OpenSource.git
```

    ### Integration Methods

        **Step 1: Download/Clone Source Code**

        - Clone or download the source code from the [open-source GitHub repository](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android-OpenSource)
        - Extract the downloaded ZIP file if applicable

        **Step 2: Import Module in Android Studio**

        1. Navigate to your current application in Android Studio
        2. In the top navigation bar, go to **File → New → Import Module...**
        3. Choose the source directory where you downloaded/cloned the UIKit source code
        4. Select the modules to import

        **Step 3: Select Required Modules** Import these essential modules:

        - `:chat` - Chat functionality
        - `:common` - Common utilities and components
        - `:social` - Social features
        - `:amity-uikit` - Main UIKit module

          **Optional**: The `:sample` module contains examples of UIKit Fragments and Activities for reference but is not required for your implementation.
        **Step 4: Configure settings.gradle** Navigate to your root project's `settings.gradle` file and verify the module paths:

```gradle
include ':amity-uikit'
include ':chat'
include ':common'
include ':social'

// Verify paths are correct (Android Studio may auto-generate these)
project(':amity-uikit').projectDir = new File('../Amity-Social-Cloud-UIKit-Android-OpenSource/amity-uikit')
project(':chat').projectDir = new File('../Amity-Social-Cloud-UIKit-Android-OpenSource/chat')
project(':common').projectDir = new File('../Amity-Social-Cloud-UIKit-Android-OpenSource/common')
project(':social').projectDir = new File('../Amity-Social-Cloud-UIKit-Android-OpenSource/social')
```

        **Step 5: Configure Repository in settings.gradle** Add the JitPack repository to `dependencyResolutionManagement`:

```gradle
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url 'https://sdk.amity.co/artifactory/amity-release' }
    }
}
```

        **Step 6: Add Dependencies to App Module** In your app-level `build.gradle`, add the UIKit dependency:

```gradle
dependencies {
    implementation project(path: ':amity-uikit')

    // Required dependencies will be included automatically
    // through the UIKit module's dependencies
}
```

        **Step 7: Configure Packaging Options** Add packaging exclusions in your app-level `build.gradle`:

```gradle
android {
    // ... other configurations

    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}
```

        **Step 8: Apply Dependencies Configuration** In your project-level `build.gradle`, apply the dependencies configuration:

```gradle
apply from: "../Amity-Social-Cloud-UIKit-Android-OpenSource/buildsystem/dependencies.gradle"
```

        **Step 9: Configure gradle.properties** Ensure this setting is in your `gradle.properties` file:

```properties
android.nonTransitiveRClass=false
```
    ### Required Configuration

    **Project-level build.gradle:**

```gradle
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url 'https://sdk.amity.co/artifactory/amity-release' }
    }
}
```

    **App-level build.gradle configuration:**

```gradle
android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        targetSdk 34
        multiDexEnabled true
    }

    buildFeatures {
        dataBinding = true
        viewBinding = true
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }

    packagingOptions {
        exclude 'META-INF/INDEX.LIST'
        exclude 'META-INF/io.netty.versions.properties'
    }
}
```

    **Initialize in Application class:**

```kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        AmityUIKit4Manager.setup(
             apiKey = "YOUR_API_KEY",
             endpoint =  AmityEndpoint.EU
            )
    }
}
```

    ### Permissions (AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

    ### Troubleshooting

    **Common Issues:**

    1. **Module paths not found**: Double-check the paths in `settings.gradle` match your actual directory structure
    2. **Build errors**: Ensure all required modules (`:chat`, `:common`, `:social`, `:amity-uikit`) are imported
    3. **Dependency conflicts**: Make sure `android.nonTransitiveRClass=false` is set in `gradle.properties`
    4. **Repository access**: Verify JitPack and Amity repositories are correctly configured

    **Clean and Rebuild:**

```bash
./gradlew clean
./gradlew build
```

    ### Customization Benefits

    - **Complete Layout Control**: Modify XML layouts, fragments, activities, and view components
    - **Custom Styling**: Change themes, colors, typography, and dimensions using Android resources
    - **Data Binding**: Implement custom data binding adapters, view models, and observers
    - **Navigation Control**: Customize fragment transactions, navigation flows, and deep linking
    - **Build Configurations**: Control ProGuard rules, build variants, flavors, and dependencies
    - **Resource Management**: Override drawables, strings, colors, and other resources
    - **Architecture Integration**: Integrate with MVVM, MVP, or other architectural patterns

    ### Fork Repository

    1. Fork the [Web UIKit repository](https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource)
    2. Clone your forked repository:

```bash
git clone https://github.com/YOUR_USERNAME/Amity-Social-Cloud-UIKit-Web-OpenSource.git
```

    ### Prerequisites

    **Install PNPM (Optional but Recommended):**

```bash
corepack enable pnpm
```

    [_Reference: PNPM Installation Guide_](https://pnpm.io/installation#using-corepack)

    ### Setup Methods

        **Running Storybook for Component Development:**

        Storybook allows you to view and develop UI components in isolation, which is helpful for customization and testing.

        **Step 1: Clone Repository**

```bash
git clone https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource.git
cd Amity-Social-Cloud-UIKit-Web-OpenSource
```

        **Step 2: Install Dependencies**

```bash
pnpm install
```

        **Step 3: Configure Environment** Create a `.env` file at the root of the project:

```bash
STORYBOOK_API_REGION=<API_REGION>
STORYBOOK_API_KEY=<API_KEY>
```

        Replace `<API_REGION>` (us/eu/sg) and `<API_KEY>` with your actual credentials.

        **Step 4: Run Storybook**

```bash
pnpm run storybook
```

        **Step 5: View Components** Open your browser and navigate to `http://localhost:6006` to view the Storybook interface.
        **Installing UIKit with Your Application:**

        **Step 1: Clone Repository**

```bash
git clone https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource.git
cd Amity-Social-Cloud-UIKit-Web-OpenSource
```

        **Step 2: Install Dependencies**

```bash
pnpm install
```

        **Step 3: Build the Project**

```bash
pnpm run build
```

        **Step 4: Navigate to Your Application**

```bash
cd <path-to-your-app>
```

        **Step 5: Link UIKit to Your Application** Choose your preferred package manager:

        **NPM:**

```bash
npm link file:<path-to-amity-ui-kit-repository> --save
```

        **Yarn (Classic):**

```bash
yarn add file:<path-to-amity-ui-kit-repository>
```

        **PNPM:**

```bash
pnpm i file:<path-to-amity-ui-kit-repository>
```

        **Alternative: Git Dependency** Add to your `package.json`:

```json
{
  "dependencies": {
    "@amityco/ui-kit-react": "git+https://github.com/YOUR_USERNAME/Amity-Social-Cloud-UIKit-Web-OpenSource.git#main"
  }
}
```
        **Copy Source Files Method:**

        For maximum customization, copy the source files directly into your project:

        **Step 1: Copy Source Files**

```bash
# Copy the src folder to your project
cp -r Amity-Social-Cloud-UIKit-Web-OpenSource/src YourProject/src/amity-uikit
```

        **Step 2: Install Peer Dependencies**

```bash
npm install react react-dom typescript
npm install @types/react @types/react-dom
```

        **Step 3: Configure Build Tools** Update your TypeScript, Webpack, or Vite configuration to handle the new source files.

        **Step 4: Import Components**

```jsx
import { AmityUIKitProvider } from './amity-uikit/components';
```
    ### Required Dependencies

    Ensure these peer dependencies are installed in your project:

```json
{
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "typescript": "^4.9.0"
  }
}
```

    ### Updating to Latest Version

    **For Forked Repository:**

```bash
# Sync your fork with upstream
git remote add upstream https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource.git
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

# Rebuild after updates
pnpm install
pnpm run build
```

    **For Local Development:**

```bash
cd Amity-Social-Cloud-UIKit-Web-OpenSource
git pull origin main
pnpm install
pnpm run build

# Re-link to your project if needed
cd YourProject
pnpm i file:<path-to-amity-ui-kit-repository>
```

    ### Troubleshooting

    **Common Issues:**

    1. **Build errors**: Ensure all peer dependencies are correctly installed
    2. **Module resolution**: Check your bundler configuration and alias settings
    3. **TypeScript errors**: Verify TypeScript configuration includes UIKit source paths
    4. **Style conflicts**: Import UIKit styles after your application styles

    **Reset and Clean Installation:**

```bash
# In UIKit directory
rm -rf node_modules package-lock.json
pnpm install
pnpm run build

# In your project
rm -rf node_modules package-lock.json
npm install
```

    ### Customization Benefits

    - **Complete Component Control**: Edit React components, hooks, and utilities directly
    - **Advanced Styling**: Customize CSS-in-JS, SCSS, CSS modules, and theme configurations
    - **State Management**: Implement custom Redux, Zustand, or Context patterns
    - **Routing Integration**: Customize React Router or Next.js routing flows
    - **Bundle Optimization**: Control webpack/Vite configuration, code splitting, and tree shaking
    - **Development Experience**: Use Storybook for isolated component development and testing
    - **API Integration**: Modify API calls, data fetching, and caching strategies

    ### Fork Repository

    1. Fork the [Flutter UIKit repository](https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource)
    2. Clone your forked repository:

```bash
git clone https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource.git
```

    ### Integration Methods

        **Add to pubspec.yaml:**

```yaml
dependencies:
  amity_uikit_beta_service:
    path: ./Amity-Social-UIKit-Flutter-Opensource
```

        **Project structure:**

```
YourFlutterProject/
├── lib/
├── pubspec.yaml
└── Amity-Social-UIKit-Flutter-Opensource/
    ├── lib/
    └── pubspec.yaml
```
        **Add to pubspec.yaml:**

```yaml
dependencies:
  amity_uikit_beta_service:
    git:
      url: https://github.com/YOUR_USERNAME/Amity-Social-UIKit-Flutter-Opensource.git
      ref: main  # or specific branch/tag
```
        **Add as submodule:**

```bash
cd YourFlutterProject
git submodule add https://github.com/YOUR_USERNAME/Amity-Social-UIKit-Flutter-Opensource.git packages/amity_uikit
git submodule update --init --recursive
```

        **Update pubspec.yaml:**

```yaml
dependencies:
  amity_uikit_beta_service:
    path: packages/amity_uikit
```

    ### Initialization

```dart
import 'package:flutter/material.dart';
import 'package:amity_uikit_beta_service/amity_uikit.dart';
import 'package:amity_uikit_beta_service/v4/utils/config_provider_widget.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize UIKit
  await AmityUIKit().setup(
    apikey: 'YOUR_API_KEY',
    region: AmityEndpointRegion.eu,
  );

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AmityUIKitProvider(
      child: SocialHomePageConfigProviderWidget(),
    );
  }
}
```

    ### Customization Benefits

    - **Widget Modification**: Edit Flutter widgets, screens, and navigation flows
    - **Theme Customization**: Modify Material/Cupertino themes and custom styling
    - **State Management**: Implement custom Provider, Bloc, or Riverpod patterns
    - **Platform Channels**: Add custom platform-specific functionality
    - **Build Configuration**: Control pubspec dependencies and build settings

    Fork the React Native UIKit when you need to change the UIKit itself, such as its components, screens, or navigation flows. If you only need the published UIKit, use the React Native tab under [Package Installation](#package-installation) instead.

    ### Fork Repository

    1. Fork the [React Native UIKit repository](https://github.com/AmityCo/Amity-Social-UIKit-React-Native-CLI-OpenSource).
    2. Clone your fork:

```bash
git clone https://github.com/YOUR_USERNAME/Amity-Social-UIKit-React-Native-CLI-OpenSource.git
```

    ### Build and Install a Local Package

    Build a package from your fork and install it into your app in place of the npm package:

```bash
cd Amity-Social-UIKit-React-Native-CLI-OpenSource
yarn install
npm pack        # builds the UIKit and produces amityco-react-native-social-uikit-x.x.x.tgz

# from your app
yarn add ../path/to/amityco-react-native-social-uikit-x.x.x.tgz
```

    Imports stay the same (`@amityco/react-native-social-uikit`). Rebuild and reinstall the package each time you change the UIKit source.

    ### Complete the App Setup

    A local build needs the same app setup as the npm package. Follow these steps in the React Native tab under [Package Installation](#package-installation):

    - Install the peer dependencies (skip `yarn add @amityco/react-native-social-uikit`)
    - Configure Babel
    - Platform configuration
    - Required permissions

    ### Try Sample App

    The repository includes a built-in sample app for testing:

    **1. Setup Sample App:**

```bash
cd example
yarn install
```

    **2. Configure Firebase (for push notifications):**

    - Set up Firebase project at https://console.firebase.google.com/
    - Download `google-services.json` and `GoogleService-Info.plist`
    - Copy to `/example/android/app/` and `/example/ios/` respectively

    **3. Configure App Settings:** Edit `/example/src/App.tsx` with your credentials:

    - `apiKey`
    - `apiRegion`
    - `apiEndpoint`
    - `userId`
    - `displayName`
    - `fcmToken`

    **4. Run Sample App:**

```bash
# From root directory
yarn install

# Run iOS
yarn example ios

# Run Android
yarn example android
```

    ### Customization Benefits

    - **Complete Component Control**: Modify React Native components, screens, and navigation flows
    - **Advanced Styling**: Override StyleSheet styles and implement custom theme configurations
    - **Individual Screen Usage**: Import and use specific screens for granular control
    - **Native Module Integration**: Add custom native modules and third-party libraries
    - **Navigation Flexibility**: Customize React Navigation flows and screen transitions
    - **State Management**: Implement custom Redux/Context state management patterns
    - **Push Notifications**: Full control over Firebase configuration and notification handling

---

## Next Steps

After installation, continue with:

    title="Authentication Setup"
    icon="key"
    href="/uikit/getting-started/authentication"
  >
    Configure user authentication and API credentials
    title="First Component"
    icon="puzzle-piece"
    href="/uikit/getting-started/first-steps"
  >
    Add your first UIKit component to your app
    title="Customization"
    icon="palette"
    href="/uikit/customization/overview"
  >
    Customize themes, colors, and styling

  **Installation Complete?** Head to [Authentication
  Setup](/uikit/getting-started/authentication) to configure your API
  credentials and start building!

---

### [Authentication & Setup](https://learn.social.plus/uikit/getting-started/authentication)

> Configure user authentication and initialize social.plus UIKit in your application

This guide covers user authentication and device registration for social.plus UIKit. Authentication is essential for personalizing the user experience and enabling social features.

  **New to social.plus Authentication?** For comprehensive authentication concepts, security patterns, and backend implementation, see the [SDK Authentication Guide](/social-plus-sdk/getting-started/authentication). This guide focuses specifically on UIKit implementation.

## Prerequisites

Before setting up authentication, ensure you have:

    Your API key and region from social.plus Console
    social.plus UIKit installed in your project

  **Coming from First Steps?** If you followed the [First Steps guide](/uikit/getting-started/first-steps), you've already completed basic authentication. This guide provides comprehensive details and production-ready patterns.

---

## Get Your API Credentials

### Access social.plus Console

    Go to [social.plus Console](https://console.socialplus.com) and sign in to your account.

    In the left sidebar, click **Settings** → **Security**.

    Find your **API Key** and note your **Region**. You'll need both for authentication.

### Regional Configuration

social.plus operates in multiple regions for optimal performance and compliance:

```typescript
apiRegion: "us"
endpoint: "api.us.amity.co"
```
```typescript
apiRegion: "eu"
endpoint: "api.eu.amity.co"
```
```typescript
apiRegion: "sg"
endpoint: "api.sg.amity.co"
```

  **Region Consistency**: Your API region must match the region where your social.plus application was created. Mismatched regions will cause authentication failures.

---

## Authentication Modes

social.plus UIKit supports two authentication modes depending on your security requirements:

    **Quick Setup (API Key Only)**

    Perfect for development, testing, and proof-of-concept applications:

```typescript
// Development authentication - API key only
<AmityUiKitProvider
  apiKey="YOUR_API_KEY"
  apiRegion="us"
  userId="user-123"
  displayName="John Doe"
>
  {/* Your app */}
</AmityUiKitProvider>
```

      Development mode is great for getting started quickly, but should not be used in production applications.

    **Secure Setup (API Key + Auth Token)**

    Required for production applications with proper backend verification:

```typescript
// Production authentication - with auth token
const getAuthToken = async () => {
  // Get auth token from your secure backend
  const response = await fetch('/api/auth/social-plus-token');
  const { authToken } = await response.json();
  return authToken;
};

<AmityUiKitProvider
  apiKey="YOUR_API_KEY"
  apiRegion="us"
  userId="user-123"
  displayName="John Doe"
  getAuthToken={getAuthToken}
>
  {/* Your app */}
</AmityUiKitProvider>
```

      **Auth Token Security**: Auth tokens must be generated by your backend server after verifying the user. Never generate auth tokens on the client side.

  Understanding auth tokens, server-to-server verification, and backend implementation patterns

---

## Device Registration

### Understanding Device Binding

  **Important**: Once registered, a device is permanently tied to a `userId` until explicitly unregistered or inactive for 90+ days. Plan your authentication flow carefully.

When you authenticate a user with social.plus UIKit, you're registering the current device with that user's ID. This device will receive all messages and notifications belonging to that user.

### Platform Implementation

Choose your platform for device registration:

```swift
import AmityUIKit

// 1. Register device with user (basic)
AmityUIKitManager.registerDevice(
    withUserId: "user-123",
    displayName: "John Doe"
)

// 2. Register device with auth token (production)
AmityUIKitManager.registerDevice(
    withUserId: "user-123",
    displayName: "John Doe",
    authToken: "auth-token-from-backend"
)

// 3. Register for push notifications (optional)
UIKitManager.registerDeviceForPushNotification("device-token") { isSuccess, error in
    if isSuccess {
        print("Push notifications registered")
    } else {
        print("Push registration failed: \(error?.localizedDescription ?? "")")
    }
}
```

      **Push Notifications**: social.plus UIKit doesn't manage push permission requests or token creation. Your app must handle these and pass the device token.

```kotlin
import com.amity.socialcloud.sdk.AmityCoreClient

// Production login with auth token
fun login(userId: String, authToken: String) {
    AmityCoreClient.login(
        userId = userId,
        sessionHandler = object : SessionHandler {
            override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
                renewal.renew()
            }
        }
    ).authToken(authToken)
        .displayName("John Doe")
        .build()
        .submit()
        .subscribeOn(Schedulers.io())
        .doOnComplete {
            // Device registered successfully
            Log.d("Auth", "User logged in successfully")
        }
        .doOnError { error ->
            Log.e("Auth", "Login failed", error)
        }
        .subscribe()
}
```

```typescript
import React from 'react';
import { AmityUiKitProvider, AmityUiKitSocial } from '@amityco/ui-kit-open-source';
import '@amityco/ui-kit-open-source/dist/index.css';

export default function App() {
  // Function to get auth token from your backend
  const getAuthToken = async () => {
    const authToken = await getAuthTokenFromApi();
    return authToken;
  };

  return (
    <AmityUiKitProvider
      key="user-123" // Important: key should match userId
      apiKey="YOUR_API_KEY"
      userId="user-123"
      displayName="John Doe"
      apiRegion="us" // eu, us, or sg
      getAuthToken={getAuthToken} // For secure mode authentication
    >
      <div
        style={{
          position: "absolute",
          left: 0,
          top: 0,
          width: "100vw",
          height: "100dvh",
        }}
      >
        <AmityUiKitSocial />
      </div>
    </AmityUiKitProvider>
  );
}
```

      **Provider Placement**: `AmityUiKitProvider` should be placed only once at the top of your application. Multiple providers will create connection problems.

```typescript
import React from 'react';
import {
  AmityUiKitSocial,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';

export default function App() {
  const getAuthToken = async () => {
    // Get auth token from your backend
    const response = await fetch('https://yourapi.com/auth/token');
    const { authToken } = await response.json();
    return authToken;
  };

  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="us" // eu, us, or sg
      userId="user-123"
      displayName="John Doe"
      getAuthToken={getAuthToken}
      apiEndpoint="https://api.us.amity.co"
    >
      <AmityUiKitSocial />
    </AmityUiKitProvider>
  );
}
```

```dart
import 'package:amity_uikit_beta_service/amity_uikit_beta_service.dart';

void login() async {
  try {
    await AmityCoreClient.login(
      'user-123',
      sessionHandler: (AccessTokenRenewal renewal) {
        renewal.renew();
      },
    )
        .displayName('John Doe')
        .authToken('auth-token-from-backend')
        .submit();

    print('Login successful');
  } catch (error) {
    print('Login failed: $error');
  }
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return AmityUIKitProvider(
      child: SocialHomePageConfigProviderWidget(),
    );
  }
}
```

---

## User Management

### User ID Guidelines

Your user identification strategy is crucial for a smooth user experience:

    **Best Practices:**
    - Use your internal user ID or UUID
    - Ensure IDs are unique across your entire user base
    - Keep IDs consistent across all platforms

    **Avoid:**
    - Email addresses (users might change emails)
    - Phone numbers (users might change numbers)
    - Display names (not unique)

    **Valid Characters:**
    - Alphanumeric characters (a-z, A-Z, 0-9)
    - Underscores (_) and hyphens (-)
    - Maximum length: 255 characters

    **Invalid Characters:**
    - Spaces or special characters (@, #, $, etc.)
    - Emojis or unicode characters

    **Security:**
    - Don't expose sensitive information in user IDs
    - Consider hashing user IDs if needed
    - Implement server-side validation

    **Scalability:**
    - Use a consistent ID format
    - Plan for user merging scenarios
    - Consider ID migration strategies

### Session Management

    When a user logs into your app, register them with social.plus. The device will be tied to this user.

    The SDK automatically maintains sessions across app launches. No additional action needed.

    When users log out, properly unregister the device to prevent unauthorized access:

```swift
// Unregister device on logout
AmityUIKitManager.unregisterDevice()
```

          Unregistering a device is synchronous. Once called, the SDK disconnects from the server and wipes the user session.
```kotlin
AmityCoreClient.logout()
    .submit()
    .subscribe({
        // Successfully logged out
        navigateToLogin()
    }, { error ->
        Log.e("Logout", "Failed", error)
    })
```
```typescript
// For web applications, remove the provider or navigate away
const handleLogout = () => {
  // Clear user state and navigate to login
  setCurrentUser(null);
  navigate('/login');
};
```

    To switch users, unregister the current user first, then register the new user:

```typescript
// 1. Unregister current user
await amitySDK.unregisterDevice();

// 2. Register new user
await amitySDK.registerDevice(newUserId, newDisplayName);
```

---

## Advanced Configuration

### Environment Management

Organize your configuration for different environments:

```typescript
const config = {
  apiKey: "dev_b24c28bc...",
  apiRegion: "us",
  debug: true,
  // No auth token needed for development
};
```

```typescript
const config = {
  apiKey: process.env.REACT_APP_AMITY_API_KEY,
  apiRegion: process.env.REACT_APP_AMITY_REGION,
  debug: false,
  // Auth token required for production
  getAuthToken: async () => {
    const response = await fetch('/api/auth/social-plus-token');
    const { authToken } = await response.json();
    return authToken;
  }
};
```

### Error Handling

Implement comprehensive error handling for authentication:

```typescript
const AuthenticationService = {
  async authenticateUser(userId: string, displayName: string, authToken?: string) {
    try {
      if (authToken) {
        // Production mode with auth token
        await amitySDK.registerDevice(userId, displayName, authToken);
      } else {
        // Development mode
        await amitySDK.registerDevice(userId, displayName);
      }

      console.log('Authentication successful');
      return { success: true };
    } catch (error) {
      console.error('Authentication failed:', error);

      // Handle specific error types
      if (error.code === 'INVALID_API_KEY') {
        return { success: false, error: 'Invalid API credentials' };
      } else if (error.code === 'INVALID_AUTH_TOKEN') {
        return { success: false, error: 'Invalid or expired auth token' };
      } else if (error.code === 'NETWORK_ERROR') {
        return { success: false, error: 'Network connection failed' };
      }

      return { success: false, error: 'Authentication failed' };
    }
  },

  async logoutUser() {
    try {
      await amitySDK.unregisterDevice();
      return { success: true };
    } catch (error) {
      console.error('Logout failed:', error);
      return { success: false, error: 'Logout failed' };
    }
  }
};
```

---

## Backend Integration

For production applications, you'll need to implement auth token generation on your backend:

  Learn how to implement secure auth token generation, token validation, and server-to-server communication with social.plus

### Quick Backend Example

Here's a simplified example of auth token generation:

```javascript
// Example Node.js backend endpoint
app.post('/api/auth/social-plus-token', authenticateUser, async (req, res) => {
  try {
    // User is already authenticated by your middleware
    const { userId } = req.user;

    // Generate auth token for social.plus
    const authToken = await generateSocialPlusAuthToken(userId);

    res.json({ authToken });
  } catch (error) {
    res.status(500).json({ error: 'Failed to generate auth token' });
  }
});
```

  **Security Note**: Never generate auth tokens on the client side. They must be created by your secure backend after verifying the user's identity.

---

## Troubleshooting

    **Invalid API Key (401 Error):**
    - Verify API key is correct and not truncated
    - Check that the API key matches your console account
    - Ensure no extra spaces or characters

    **Invalid Auth Token (403 Error):**
    - Verify auth token is properly generated by your backend
    - Check token hasn't expired
    - Ensure token format matches social.plus requirements

    **Region Mismatch:**
    - Verify region matches your console setup
    - Check endpoint URLs are correct
    - Confirm region code format (us/eu/sg)

    **Device Already Registered:**
    - Unregister existing user first
    - Wait for previous session to properly close
    - Clear app data if needed (development only)

    **Invalid User ID Format:**
    - Remove special characters and spaces
    - Check user ID length (max 255 characters)
    - Use only alphanumeric characters and underscores

    **Session Conflicts:**
    - Ensure proper logout before switching users
    - Check for multiple provider instances (Web/React)
    - Verify device registration cleanup

    **iOS:**
    - Ensure registration is called on main thread
    - Check for proper app lifecycle handling
    - Verify push notification setup if using

    **Android:**
    - Implement proper Activity/Fragment lifecycle
    - Check for ProGuard/R8 obfuscation issues
    - Verify session handler implementation

    **Web/React:**
    - Ensure single provider instance at app root
    - Import CSS styles for proper component rendering
    - Check for CORS issues in development

    **React Native:**
    - Verify native module linking
    - Check platform-specific permissions
    - Test on physical devices for push notifications

    **Flutter:**
    - Check session handler implementation
    - Verify platform permissions are configured
    - Ensure proper async/await usage

---

## Next Steps

Now that authentication is configured, you can explore social.plus UIKit features:

    Browse available UI components and features
    Learn how to customize themes and styling

    Platform-specific configuration and optimization
    Complete authentication concepts and backend implementation

### User ID Guidelines

Your user identification strategy is crucial for a smooth user experience:

    **Best Practices:**
    - Use your internal user ID or UUID
    - Ensure IDs are unique across your entire user base
    - Keep IDs consistent across all platforms

    **Avoid:**
    - Email addresses (users might change emails)
    - Phone numbers (users might change numbers)
    - Display names (not unique)

    **Valid Characters:**
    - Alphanumeric characters (a-z, A-Z, 0-9)
    - Underscores (_) and hyphens (-)
    - Maximum length: 255 characters

    **Invalid Characters:**
    - Spaces or special characters (@, #, $, etc.)
    - Emojis or unicode characters

    **Security:**
    - Don't expose sensitive information in user IDs
    - Consider hashing user IDs if needed
    - Implement server-side validation

    **Scalability:**
    - Use a consistent ID format
    - Plan for user merging scenarios
    - Consider ID migration strategies

### Session Management

  **Device Binding**: Once registered, a device is permanently tied to a user ID until explicitly unregistered or inactive for 90+ days. Plan your authentication flow carefully.

    When a user logs into your app, register them with social.plus:

```typescript
// Register the current device with the user
await amitySDK.register(userId, displayName);
```

    The SDK automatically maintains sessions across app launches. No additional action needed.

    When users log out, properly unregister the device:

```swift
AmitySDK.unregisterDevice { success, error in
    if success {
        // Device unregistered successfully
        self.returnToLoginScreen()
    } else {
        // Handle error
        print("Logout failed: \(error?.localizedDescription ?? "")")
    }
}
```
```kotlin
AmityCoreClient.logout()
    .submit()
    .subscribe({
        // Successfully logged out
        navigateToLogin()
    }, { error ->
        Log.e("Logout", "Failed", error)
    })
```
```typescript
// For web applications, simply remove the provider
// or navigate away from UIKit components
const handleLogout = () => {
  // Clear user state
  setCurrentUser(null);
  // Navigate to login
  navigate('/login');
};
```

    To switch users, unregister the current user first, then register the new user:

```typescript
// 1. Unregister current user
await amitySDK.unregisterDevice();

// 2. Register new user
await amitySDK.register(newUserId, newDisplayName);
```

---

## Advanced Configuration

### Environment Management

Organize your configuration for different environments:

```typescript
const config = {
  apiKey: "dev_b24c28bc...",
  apiRegion: "us",
  debug: true,
  enableLogging: true,
  // Optional: Use test endpoints
  apiEndpoint: "https://api.staging.amity.co"
};
```

```typescript
const config = {
  apiKey: process.env.REACT_APP_AMITY_API_KEY,
  apiRegion: process.env.REACT_APP_AMITY_REGION,
  debug: false,
  enableLogging: false,
  // Use production endpoints
  apiEndpoint: `https://api.${process.env.REACT_APP_AMITY_REGION}.amity.co`
};
```

```typescript
// For enterprise customers with custom domains
const config = {
  apiKey: "your_enterprise_api_key",
  apiEndpoint: "https://api.your-company.com",
  // Additional enterprise features
  enableCustomBranding: true,
  enableAdvancedModeration: true
};
```

### Error Handling

Implement comprehensive error handling for authentication:

```typescript
const AuthenticationService = {
  async authenticateUser(userId: string, displayName: string) {
    try {
      await amitySDK.register(userId, displayName);
      console.log('Authentication successful');
      return { success: true };
    } catch (error) {
      console.error('Authentication failed:', error);

      // Handle specific error types
      if (error.code === 'INVALID_API_KEY') {
        return { success: false, error: 'Invalid API credentials' };
      } else if (error.code === 'NETWORK_ERROR') {
        return { success: false, error: 'Network connection failed' };
      } else if (error.code === 'INVALID_USER_ID') {
        return { success: false, error: 'Invalid user ID format' };
      }

      return { success: false, error: 'Authentication failed' };
    }
  },

  async logoutUser() {
    try {
      await amitySDK.unregisterDevice();
      return { success: true };
    } catch (error) {
      console.error('Logout failed:', error);
      return { success: false, error: 'Logout failed' };
    }
  }
};
```

### Security Best Practices

    **Client-Side Applications:**
    - Store API keys in environment variables
    - Never commit API keys to version control
    - Use different keys for development and production

    **Server-Side Authentication (Recommended):**
    - Implement server-side token generation
    - Use short-lived authentication tokens
    - Validate users on your backend before issuing tokens

    **Input Validation:**
    - Validate user IDs before registration
    - Sanitize display names
    - Implement rate limiting for authentication attempts

    **Session Security:**
    - Monitor for unusual authentication patterns
    - Implement proper logout flows
    - Consider implementing session timeouts

---

## Troubleshooting

    **Invalid API Key (401 Error):**
    - Verify API key is correct and not truncated
    - Check that the API key matches your console account
    - Ensure no extra spaces or characters

    **Region Mismatch (403 Error):**
    - Verify region matches your console setup
    - Check endpoint URLs are correct
    - Confirm region code format (us/eu/sg)

    **Network Issues:**
    - Test internet connectivity
    - Check firewall/proxy settings
    - Verify DNS resolution for amity.co domains

    **Invalid User ID Format:**
    - Remove special characters and spaces
    - Check user ID length (max 255 characters)
    - Use only alphanumeric characters and underscores

    **Device Already Registered:**
    - Unregister existing user first
    - Wait for previous session to properly close
    - Clear app data if needed (development only)

    **Display Name Issues:**
    - Ensure display name is not empty
    - Check for special character restrictions
    - Verify UTF-8 encoding for international names

    **iOS:**
    - Ensure setup is called on main thread
    - Check for proper delegate implementations
    - Verify bundle identifier permissions

    **Android:**
    - Implement proper Activity/Fragment lifecycle
    - Check for ProGuard/R8 obfuscation issues
    - Verify network permissions in manifest

    **Web/React:**
    - Ensure provider wraps all UIKit components
    - Check for CORS issues in development
    - Verify React version compatibility

    **React Native:**
    - Check platform-specific permissions
    - Verify native module linking
    - Test on physical devices, not just simulators

    **Flutter:**
    - Check pubspec.yaml dependencies
    - Verify platform permissions are configured
    - Test hot reload vs full restart

---

## Next Steps

Now that authentication is configured, you can explore social.plus UIKit features:

    Browse available UI components and features
    Learn how to customize themes and styling

    Platform-specific configuration and optimization
    See real-world implementation examples

    Initialize the SDK in your `Application` class or main activity:

```kotlin
import com.amity.socialcloud.sdk.AmityCoreClient
import com.amity.socialcloud.uikit.AmityUIKit

// In Application class or MainActivity
AmityCoreClient.setup(
    apiKey = "YOUR_API_KEY",
    region = AmityRegionalEndpoint.US // or EU, SG
)
```

    Register and authenticate the user:

```kotlin
AmityCoreClient.login("unique_user_id")
    .displayName("User Display Name")
    .build()
    .submit()
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe({ user ->
        // User registered successfully
        Log.d("Auth", "User registered: ${user.displayName}")
    }, { error ->
        // Handle registration error
        Log.e("Auth", "Registration failed", error)
    })
```

    Start social.plus UIKit activities:

```kotlin
import com.amity.socialcloud.uikit.AmityUIKit

// Launch social features
AmityUIKit.openSocialHome(this)

// Or launch specific features
AmityUIKit.openChatHome(this)
```

### Web/React Setup

    Set up the `AmityUiKitProvider` in your React app:

```typescript
import React from 'react';
import { AmityUiKitProvider } from '@amityco/ui-kit';

function App() {
  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="US" // or "EU", "SG"
      userId="unique_user_id"
      displayName="User Display Name"
    >
      {/* Your app content */}
    </AmityUiKitProvider>
  );
}
```

    Import and use social.plus components:

```typescript
import { AmityUiKitSocial } from '@amityco/ui-kit';

function SocialPage() {
  return (
    <div className="social-container">
      <AmityUiKitSocial />
    </div>
  );
}
```

### React Native Setup

    Wrap your app with the provider:

```typescript
import React from 'react';
import {
  AmityUiKitProvider,
  AmityUiKitSocial,
} from '@amityco/react-native-social-uikit';

export default function App() {
  return (
    <AmityUiKitProvider
      apiKey="YOUR_API_KEY"
      apiRegion="US" // or "EU", "SG"
      userId="unique_user_id"
      displayName="User Display Name"
    >
      <AmityUiKitSocial />
    </AmityUiKitProvider>
  );
}
```

### Flutter Setup

    Set up the `AmityApp` widget:

```dart
import 'package:amity_uikit_beta_service/amity_uikit_beta_service.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: AmityApp(
        apiKey: 'YOUR_API_KEY',
        apiRegion: 'US', // or 'EU', 'SG'
        userId: 'unique_user_id',
        displayName: 'User Display Name',
        child: AmitySocialHomePage(),
      ),
    );
  }
}
```

---

## Authentication Best Practices

### User ID Guidelines

    - Use a unique, persistent identifier for each user
    - Avoid using email addresses or phone numbers directly
    - Consider using UUIDs or your system's internal user IDs

    - Maintain the same user ID across app sessions
    - Ensure user IDs remain consistent across different platforms
    - Don't change user IDs after initial registration

    - Never expose sensitive user information in user IDs
    - Use a hash or encoded value if needed
    - Implement proper server-side validation

### Session Management

  **Device Binding**: A device registered with a specific `userId` will be permanently tied to that user until you deliberately unregister the device, or until the device has been inactive for more than 90 days.

    Register the device with the user ID when the user logs in to your app.

    The SDK automatically maintains the session across app launches.

    Properly unregister the device when the user logs out:

```swift
AmitySDK.unregisterDevice { success, error in
    if success {
        print("Device unregistered successfully")
    }
}
```
```kotlin
AmityCoreClient.logout()
    .submit()
    .subscribe({
        // Device unregistered successfully
    }, { error ->
        // Handle logout error
    })
```

---

## Configuration Options

### Optional Parameters

    For enterprise customers with custom endpoints:

```typescript
// Web/React
<AmityUiKitProvider
  apiKey="YOUR_API_KEY"
  apiEndpoint="https://api.custom-domain.com"
  // ... other props
/>
```

    For server-side authentication (recommended for production):

```typescript
// Use secure token instead of API key
<AmityUiKitProvider
  authToken="secure_server_generated_token"
  // ... other props
/>
```

### Environment Configuration

```typescript
const config = {
  apiKey: "dev_api_key",
  apiRegion: "US",
  debug: true,
  logging: true
};
```
```typescript
const config = {
  apiKey: process.env.REACT_APP_AMITY_API_KEY,
  apiRegion: process.env.REACT_APP_AMITY_REGION,
  debug: false,
  logging: false
};
```

---

## Troubleshooting

    **Invalid API Key**: Verify your API key is correct and matches your console account.

    **Wrong Region**: Ensure the region matches where your social.plus application was created.

    **Network Issues**: Check internet connectivity and firewall settings.

    **Duplicate User**: User IDs must be unique within your application.

    **Invalid Characters**: User IDs should only contain alphanumeric characters and underscores.

    **Session Conflicts**: Ensure proper logout before registering a different user.

    **iOS**: Check that you're calling setup methods on the main thread.

    **Android**: Ensure proper lifecycle management in activities/fragments.

    **Web**: Verify the provider wraps all components that need social.plus context.

---

## Next Steps

    Browse available UI components and features
    Learn how to customize themes and styling

    See real-world implementation examples
    Explore the complete API documentation

---

### [First Steps](https://learn.social.plus/uikit/getting-started/first-steps)


## UIKit — Components Overview

### [UIKit Components](https://learn.social.plus/uikit/components/overview)

> 50+ pre-built components to build social apps 10x faster. Copy-paste ready code examples.

social.plus UIKit ships production‑ready building blocks covering social feeds, communities, chat, realtime engagement, moderation, and media workflows. This page orients you to the component families, helps you choose the right starting layer, and links to deeper implementation docs.

If you are still validating product fit, start with out‑of‑the‑box components first. Defer heavy styling or forking until core UX assumptions are proven.

## When to Use Pre‑built Components

Use UIKit components when you need to:

	<li>Ship core social & chat functionality in days not months</li>
	<li>Reduce maintenance of real‑time, media, and moderation edge cases</li>
	<li>Inherit accessibility, performance & localization defaults</li>
	<li>Progressively customize (themes → styling → dynamic UI → fork)</li>
	<li>Keep API surface stable while iterating on product UX</li>

Consider building custom (or moving to <a href="/uikit/customization/advanced-customization">Fork & Extend</a>) when you:

- Need radical UX divergence not achievable via theming/styling/dynamic config
- Must embed experimental interaction paradigms (novel canvas, 3D, AR)
- Have compliance constraints requiring full source review & diff control

## Quick Navigation


### Media & Ephemeral


### Chat Components


For advanced dynamic layout adaptation, combine components with <a href="/uikit/customization/dynamic-ui">Dynamic UI</a> to conditionally show/hide or rearrange modules without forking.

## Customization Path (Decision Snapshot)

| Goal | Start Here | Escalate To | When to Escalate |
| ---- | ---------- | ----------- | ---------------- |
| Brand colors & typography | <a href="/uikit/customization/overview">Cutomization</a> | Component Styling | Need granular token overrides beyond palette |
| Adjust spacing / hide elements | Component Styling | Dynamic UI | Multiple layouts per context (role, A/B test) |
| Conditional layouts & feature gating | Dynamic UI | Fork & Extend | Need structural changes not expressible in config |
| Experimental UX / deep logic changes | Fork & Extend | — | Full control & long‑term ownership required |


## Troubleshooting

		Confirm authentication & client initialization completed; check feature flag / dynamic UI rules not excluding component; inspect console / logs for API permission errors.
		Verify selector specificity (see Component Styling precedence); ensure dynamic theme not overwriting at runtime; clear build / metro cache.
		Check network / WebSocket connectivity; verify subscription scope; ensure app not in background restricted mode; inspect rate limiting headers.
		Check file size limits & compression settings; fall back to resumable upload APIs; ensure correct MIME type negotiation.
		If change is purely visual (layout minor, spacing, colors) stay in styling; structural render tree changes or new data flows → evaluate fork per advanced customization matrix.

## Next Steps


Keep feedback flowing: note gaps or advanced scenarios and feed them back before committing to a fork—often a lighter abstraction exists.

## UIKit — Chat Components

### [Overview](https://learn.social.plus/uikit/components/chat)

> Complete guide to social.plus UIKit chat components for conversations, groups, live streaming, and real-time messaging

**Key Benefit**: Build comprehensive chat experiences with pre-built components covering one-on-one conversations, group chats, live streaming interactions, and complete channel management - all optimized for real-time communication.

## Feature Overview

social.plus Chat UIKit provides a complete suite of messaging components designed to handle every aspect of modern chat applications. From intimate one-on-one conversations to high-volume live streaming chats, our components are built to scale with your needs while maintaining exceptional user experience.

**Light & dark themes.** Chat components support both light and dark themes. Dark mode is currently verified for **chat** components; other UIKit features adopt the expanded color set in a later release — see [Component styling](/uikit/customization/component-styling).

    **Complete Messaging Foundation**
    - One-on-one and group conversations
    - Real-time message delivery and sync
    - Rich media support (images and videos)
    - Message editing, deletion, and reactions
    **High-Volume Live Events**
    - Live chat for streaming platforms
    - Real-time reactions and engagement
    - User mentions and role management
    - Performance optimized for live events

    **Multi-User Collaboration**
    - Group creation and management
    - Role-based permissions system
    - Member administration tools
    - Moderation and safety controls
    **Chat Discovery & Management**
    - Recent chats and channel lists
    - Archive and organization tools
    - Search and discovery features
    - Network connectivity handling

## Chat Component Categories

    **Essential messaging components for standard chat experiences**

    ### Conversation Chat
    Complete messaging interface for one-on-one and basic group conversations.

    **Key Features:**
    - Real-time messaging with text and media support
    - Message reactions, replies, and rich content
    - Message editing, deletion, and interaction controls
    - Network awareness and offline handling

    **Platform Support:** iOS, Android, React, Flutter

      📱 Conversation Chat Guide

    ### Recent Chats (Chat List)
    Central hub for managing and navigating between all chat conversations.

    **Key Features:**
    - Chat list with previews and unread indicators
    - Real-time activity sorting and updates
    - Swipe-to-archive functionality
    - Create new conversations and access archived chats

    **Platform Support:** iOS, Android, React, Flutter

      📋 Recent Chats Guide

    **Advanced multi-user conversation features**

    ### Group Chat
    Comprehensive group conversation solution with advanced member management.

    **Key Features:**
    - Group creation with privacy controls
    - Role-based permissions (moderators vs members)
    - Member management (add, remove, ban users)
    - Group settings and profile customization
    - Message reporting and moderation tools

    **Platform Support:** iOS, Android, React, Flutter

    **Components Included:**
    - AmityGroupChatPage - Main group interface
    - AmityCreateGroupChatPage - Group creation flow
    - AmityGroupSettingPage - Group administration
    - AmityGroupMemberListPage - Member management
    - AmityBannedGroupMemberListPage - Moderation tools

      👥 Group Chat Guide

    **Real-time chat for live events and streaming**

    ### Live Chat
    High-performance chat interface designed for live streaming and events.

    **Key Features:**
    - Real-time messaging optimized for high volume
    - Message reactions with customizable emojis
    - User mentions (@username and @all)
    - User profiles and role badges
    - Performance optimized for live events

    **Platform Support:** iOS, Android, React

    **Components Included:**
    - AmityLiveChatPage - Complete live chat interface
    - AmityLiveChatHeader - Channel information display
    - AmityLiveChatMessageList - Real-time message display
    - AmityLiveChatMessageComposeBar - Message creation with mentions
    - AmityReactionList - Reaction management

      📺 Live Chat Guide

## Implementation Strategies

    **Designing your chat system structure**

    Plan your chat implementation based on your use case: start with basic conversations for simple messaging apps, add group features for collaboration platforms, or implement live chat for streaming applications. Consider user flows between different chat types and how users will discover and manage conversations.

    **Choosing the right components for your platforms**

    Flutter components provide the most comprehensive chat features, while iOS/Android/React live chat components are optimized for streaming use cases. Plan your cross-platform strategy based on feature requirements and choose components that align with your development approach.

    **Building for growth and high usage**

    Chat components are built on the SDK foundation that handles caching, real-time updates, and performance optimization. Focus on UI/UX design, user flow optimization, and component configuration rather than low-level performance concerns.

## Best Practices

    **Creating intuitive chat interfaces**

    Design clear navigation between different chat types, provide visual hierarchy for message importance, and ensure consistent interaction patterns across all chat components. Consider how users will transition between recent chats, individual conversations, and group management.

    **Implementing effective content management**

    Leverage built-in reporting mechanisms, configure appropriate moderation workflows, and provide clear user controls for blocking and muting. Plan role-based permissions for group chats and establish guidelines for live chat moderation.

    **Aligning chat interfaces with your brand**

    Customize themes, colors, and component behavior to match your application's design system. Consider different chat contexts (private conversations vs live events) and adjust styling accordingly while maintaining usability and accessibility.

## Quick Start Guide

    **Identify your primary use case:**

    - **Simple Messaging**: Start with Conversation Chat and Recent Chats
    - **Community Platform**: Add Group Chat for collaborative features
    - **Live Streaming**: Implement Live Chat for real-time events
    - **Complete Platform**: Combine all components for full chat functionality

    **Begin with essential functionality:**

    1. Implement conversation management (Recent Chats)
    2. Add individual messaging (Conversation Chat)
    3. Extend with group features if needed
    4. Integrate live chat for streaming use cases

    **Tailor to your application:**

    - Apply your brand theming and styling
    - Configure component behavior and limits
    - Set up moderation and safety features
    - Test user flows and interaction patterns

    **Launch and optimize:**

    - Deploy with appropriate user testing
    - Monitor chat usage and performance
    - Gather user feedback for improvements
    - Iterate on features and user experience

## Component Comparison

| Feature | Conversation Chat | Group Chat | Live Chat |
|---------|------------------|------------|-----------|
| **Flutter Support** | ✅ Full Support | ✅ Full Support | ❌ Not Available |
| **iOS Support** | ✅ Full Support | ✅ Full Support | ✅ Full Support |
| **Android Support** | ✅ Full Support | ✅ Full Support | ✅ Full Support |
| **React Support** | ✅ Full Support | ✅ Full Support | ✅ Full Support |
| **React Native Support** | ✅ Full Support (v4.3.0+) | ✅ Full Support (v4.3.0+) | ❌ Not Available |
| **Use Case** | 1-on-1 messaging | Multi-user collaboration | Live streaming events |
| **Member Limit** | 2 users | Multiple users | High volume viewers |
| **Moderation** | Basic reporting | Advanced admin tools | Live event moderation |
| **Performance** | Standard messaging | Group-optimized | High-volume optimized |

## Use Cases

    **Instagram-style messaging**

    Use Conversation Chat for direct messages and Recent Chats for message management. Add Group Chat for story collaborations or close friends features.
    **Discord-like experience**

    Implement Group Chat for team channels, Live Chat for tournament streams, and Recent Chats for server navigation.
    **Slack-style workplace chat**

    Use Group Chat for team channels, Conversation Chat for direct messages, and Recent Chats for workspace organization.
    **Twitch-style live interaction**

    Focus on Live Chat for viewer engagement, with Conversation Chat for creator-fan direct communication.

## Related Features

    **User Profiles & Social**
    User profiles and social interactions
    **Content Safety**
    Advanced moderation and reporting
    **Theme & Styling**
    Customize chat component appearance

**Getting Started**: Begin with Recent Chats and Conversation Chat for basic messaging functionality, then expand to Group Chat or Live Chat based on your specific use case and user needs.

---

### [Chat Components Overview](https://learn.social.plus/uikit/components/chat/overview)

> Complete guide to social.plus UIKit chat components for building messaging experiences

social.plus UIKit provides a comprehensive set of chat components for building modern messaging experiences. These components are designed to work seamlessly across all platforms with consistent functionality and customizable styling.

    Powerful search across channels and messages
    Chat list and channel management
    One-on-one and group messaging interface
    Real-time chat for live events and streaming

## Key Features

    - Instant message delivery and receipt
    - Read and unread message state
    - Message synchronization across devices

    - Text messages with formatting
    - Image and video sharing

    - Message reactions and replies
    - Mentions in messages
    - Message editing and deletion
    - Message search and filtering
    - Archive and unarchive chats
    - Push notifications

    - Message reporting
    - User blocking and muting
    - Profanity filtering
    - Admin moderation controls

## Platform Support

All chat components are available across platforms with platform-specific optimizations:

    **iOS & Android**
    - Native performance and animations
    - Platform-specific UI patterns
    - Keyboard handling and input optimization
    - Push notification integration
    **React Web & React Native**
    - Embeds as React components via `AmityUiKitProvider`
    - Responsive design for all screen sizes

**React Native** ships Chat UIKit from v4.3.0 of `@amityco/react-native-social-uikit`, covering the chat list, conversation and group chat, and chat search. Live chat is not included.

## Getting Started

### Basic Implementation

    Set up the chat client with your social.plus credentials
    Select the chat components that fit your use case
    Apply your brand colors and styling
    Enable or disable specific chat features

### Quick Start Example

```swift iOS
import AmityUIKit4

// AmityChatPage is a SwiftUI view. Wrap it to present it from a UIKit stack.
let chatPage = AmityChatPage(channelId: "your_channel_id")
let hostingController = AmitySwiftUIHostingController(rootView: chatPage)

navigationController?.pushViewController(hostingController, animated: true)
```

```kotlin Android
import com.amity.socialcloud.uikit.chat.compose.conversation.AmityChatPageActivity

// The chat page is an Activity. Launch it with its Intent factory.
startActivity(
    AmityChatPageActivity.newIntent(context, channelId = "your_channel_id")
)
```

```tsx React
import { AmityUiKitProvider, AmityUiKitChatV4 } from '@amityco/ui-kit';
import config from './uikit.config.json';

function MyChatApp() {
  return (
    <AmityUiKitProvider
      configs={config}
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      apiEndpoint="https://api.{API_REGION}.amity.co"
    >
      <AmityUiKitChatV4 />
    </AmityUiKitProvider>
  );
}
```

```jsx React Native
import { AmityUiKitProvider, AmityUiKitChat } from '@amityco/react-native-social-uikit';

// Requires @amityco/react-native-social-uikit v4.3.0 or later.
function MyChatApp() {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
    >
      <AmityUiKitChat />
    </AmityUiKitProvider>
  );
}
```

**React Native**: `AmityUiKitChat` opens at the chat list, and every other chat screen is reached from there. From v4.3.1, every chat page is also exported on its own under the same names as the Web UIKit. To open a specific conversation directly — for example from a push notification — render `<AmityChatPage channelId="..." />` inside `AmityPageRenderer`; each component page shows its React Native example. Pages that take props export a `<PageName>Props` type, such as `AmityChatPageProps`. The page you render is the first screen in its stack, so its back button has nothing to go back to — close it from your app's own navigation. See [Installation](/uikit/getting-started/installation#add-chat) for the peer dependencies and save-to-gallery permissions chat requires.

## Component Architecture

### Chat System Overview

```mermaid
graph TD
    A[Chat Client] --> B[Recent Chats List]
    A --> C[Conversation View]
    A --> D[Live Chat Room]

    B --> E[Channel Preview]
    B --> F[User Status]

    C --> G[Message List]
    C --> H[Message Input]
    C --> I[Media Picker]

    D --> J[Live Messages]
    D --> K[Participant List]
    D --> L[Moderator Tools]
```

### Data Flow

    User authenticates with social.plus credentials
    Connect to specific chat channels or rooms
    Establish WebSocket connection for live updates
    Send, receive, and display messages in real-time

## Customization Options

Chat pages follow the UIKit page / component / element ID system. Set a network-wide theme in the top-level `theme`, then override a specific chat surface by its ID under `customizations` in your `uikit.config.json` — the same pattern used across every UIKit page.

**Light & dark themes.** Chat components support both light and dark themes. Dark mode is currently verified for **chat** components; other UIKit features adopt the expanded color set in a later release — see [Component styling](/uikit/customization/component-styling).

```json uikit.config.json
{
  "preferred_theme": "default",
  "theme": {
    "light": { "primary_color": "#1054DE", "background_color": "#FFFFFF" }
  },
  "excludes": [],
  "customizations": {
    "chat_home_page/*/*": {
      "theme": {
        "light": { "primary_color": "#1054DE" }
      }
    },
    "live_chat/*/*": {
      "theme": {
        "light": { "primary_color": "#1054DE" }
      }
    }
  }
}
```

Chat page IDs include `chat_home_page`, `chat_page`, `group_chat_page`, and `live_chat`. For the full theming and localization model, see [Component styling](/uikit/customization/component-styling) and [Localization](/uikit/customization/localization).

## Performance Considerations

    Efficiently load message history with pagination
    Automatic image compression and caching
    Queue messages when offline, sync when online
    Optimize memory usage for long conversations

### Best Practices

    - Implement pagination for message history
    - Use virtual scrolling for large conversations
    - Cache recent messages locally
    - Preload critical attachments

    - Use WebSocket connections efficiently
    - Implement proper reconnection logic
    - Handle connection state changes gracefully
    - Optimize update frequency

    - Show loading states and progress indicators
    - Implement smooth animations and transitions
    - Handle errors gracefully with user feedback
    - Support keyboard shortcuts and accessibility

## Security Features

All chat components include built-in security features to protect user communications and prevent abuse.

    Messages are encrypted in transit (TLS)
    AI-powered profanity and content filtering
    Block, mute, and report functionality
    Comprehensive moderation and management tools

## Integration Examples

### Simple Chat Integration

For basic one-on-one or group messaging:

1. **Recent Chats List** - Show user's active conversations
2. **Conversation Chat** - Full messaging interface
3. **Basic customization** - Apply brand colors and styling

### Live Event Chat

For live streaming or event chat:

1. **Live Chat Room** - Real-time community messaging
2. **Moderation tools** - Admin controls for large audiences
3. **Custom reactions** - Event-specific reactions and features

### Customer Support Chat

For customer service integration:

1. **Conversation Chat** - Agent-customer messaging
2. **Media sharing** - Image and video support
3. **Admin features** - Supervisor tools and analytics

## Next Steps

    Add powerful search capabilities to your chat
    Create a comprehensive chat list interface
    Implement one-on-one and group messaging
    Build real-time community chat features

---

### [Recent Chats (Chat List)](https://learn.social.plus/uikit/components/chat/recent-chats)

> Chat list and channel management interface for organizing conversations with real-time updates and archive functionality

**Key Benefit**: Provide users with a centralized hub to manage all their chat conversations, featuring real-time updates, unread indicators, and intuitive navigation between active and archived chats.

## Feature Overview

The UIKit provides users with an overview of all their active chat channels. It offers a quick glance at the latest conversations and helps users easily stay on top of ongoing discussions.

    **Conversation Organization**
    - Channel preview with latest messages
    - Real-time activity sorting
    - Unread message indicators
    - Swipe-to-archive functionality
    **Intuitive Chat Access**
    - Tap to enter conversations
    - Create new conversations
    - Access archived chats
    - Network connectivity indicators

**Platform Support**: Recent Chats components are available on **iOS, Android, React, React Native, and Flutter**. On **React Native**, these screens ship from v4.3.0 as part of `AmityUiKitChat`, and from v4.3.1 each page can also be rendered on its own inside `AmityPageRenderer` — see [Quick Start](/uikit/components/chat/overview#quick-start-example). Only pages are exported on React Native; the building-block components shown here (list, bubble, composer, action sheets) aren't.

## Implementation Guide

    **Main entry point for chat functionality**

    The AmityChatHomePage serves as the central hub for managing and navigating between conversations.

    ### Features

    | Feature                        | Description                                                          |
    | ------------------------------ | -------------------------------------------------------------------- |
    | Chat List Display              | Displays a list of available chats for the user                     |
    | Network Connectivity Indicator | Shows "Waiting for network..." message when device is offline       |
    | Create New Conversation        | Allows users to create new chat conversations via popup menu        |
    | Access Archived Chats          | Provides access to archived chats through menu option               |

    ### Code Examples

```dart Flutter
Widget chatHomePage() {
  return AmityChatHomePage();
}
```

```jsx React Native
<AmityPageRenderer>
  <AmityChatHomePage />
</AmityPageRenderer>
```

    **Automatic Management**: The chat home page automatically handles real-time updates, sorting, and network connectivity through the underlying SDK.

    **React Native** (v4.3.0+): The chat home page is where `AmityUiKitChat` opens. It shows unread and mention badges on each chat and lets users swipe a chat to archive it. When push notifications are disabled for the user's account or for the chat module (for example, by an admin), the list shows a "Push notifications have been disabled by admin" banner.

    **Core chat conversation list**

    The ChatListComponent provides a list of chat conversations for the user with real-time updates and navigation capabilities.

    ### Features

    | Feature                    | Description                                                            |
    | -------------------------- | ---------------------------------------------------------------------- |
    | Display Chat Conversations | Shows a list of chat conversations for the user                       |
    | Real-Time Updates          | Automatically updates the chat list with new conversations or changes |

    ### Code Examples

```dart Flutter
Widget chatListComponent() {
  return ChatListComponent();
}
```

    **Real-Time Integration**: The chat list automatically syncs with the SDK to provide live updates for new messages, conversation changes, and user activity.

    **Organized archive functionality**

    Components for managing archived conversations separately from active chats.

    ### Archived Chat List

    The ArchivedChatListComponent provides a dedicated interface for viewing and managing archived conversations.

    ### Features

    | Feature                   | Description                                                             |
    | ------------------------- | ----------------------------------------------------------------------- |
    | Display Archived Chats    | Shows a list of archived chat conversations for the user               |
    | Organized Chat Management | Helps users manage archived chats separately from active conversations |
    | Customizable Behavior     | Extends the base chat list component for flexibility and customization |

    ### Code Examples

```dart Flutter
Widget archivedChatListComponent() {
  return ArchivedChatListComponent();
}
```

```jsx React Native - Archived Chat Page
// React Native exports the full archived chats page, not the list component.
<AmityPageRenderer>
  <AmityArchivedChatPage />
</AmityPageRenderer>
```

    **New conversation interface**

    User interface for searching users and initiating new chat conversations.

    ### Features

    | Feature                  | Description                                                             |
    | ------------------------ | ----------------------------------------------------------------------- |
    | Search Users             | Allows users to search for other users by display name by typing at least 3 characters |
    | User List Display        | Displays a list of users matching the search query                     |
    | Real-Time Search Updates | Updates the user list dynamically as the search query changes          |
    | Start New Conversation   | Enables users to select a user and start a new chat conversation       |
    | Error Handling           | Displays appropriate messages for no results or invalid search queries |

    ### Code Examples

```dart Flutter
Widget createConversationPage() {
  return AmityChannelCreateConversationPage();
}
```

```jsx React Native
<AmityPageRenderer>
  <AmityChannelCreateConversationPage />
</AmityPageRenderer>
```

    **Search Optimization**: The search functionality includes built-in debouncing and result optimization handled by the SDK layer.

## Sort Order

By default the chat list shows the most recently active chat first. You can sort by the newest message instead, so that joining or leaving a chat does not push it to the top. This option is available on **iOS, Android, and Web**.

Set `channel_list_sort_by` under `feature_flags.chat` in your UIKit config:

```json
{
  "feature_flags": {
    "chat": {
      "channel_list_sort_by": "lastMessage"
    }
  }
}
```

| Value | Order |
| --- | --- |
| `lastActivity` (default) | Newest activity first: a new message, or a member added, removed, or banned |
| `lastMessage` | Newest message first. Membership changes do not reorder the list. |

- **Default.** A missing key, or any value other than `lastMessage`, keeps `lastActivity`. All three tabs (All, Direct, Groups) use the same value.
- **When it applies.** The chat home page reads the value when it builds its channel queries. On iOS and Android a change takes effect the next time the page opens. On Web the chat home stays mounted for the life of the UIKit, so a change takes effect the next time the UIKit is loaded with the new config.
- **Row time.** With `lastMessage`, each row shows the time of its newest message (or the chat's creation time if it has none), so a membership change neither moves a row nor changes its time. With `lastActivity`, rows keep showing the last activity time.
- **Live order.** The list reorders as messages arrive. When the current user sends a message, that chat moves to the top right away.
- **Backend support.** `lastMessage` needs backend support for your network. If it is not available, the page shows the error state ("Couldn't load chats") in place of the list, with no call to action. The UIKit does not fall back to `lastActivity`. Set the value back to `lastActivity` until it is available.

To sort a channel list in your own UI, see [Query Channels](/social-plus-sdk/chat/conversation-management/channels/query-channels#sort-a-channel-list).

## Component Management Strategies

    **Organizing chat navigation**

    Plan the user flow between recent chats, individual conversations, and archived chats. Consider how users will discover and access different chat functionalities while maintaining a clear navigation hierarchy.

    **Optimizing chat list presentation**

    Design clear visual indicators for unread messages, archived conversations, and different conversation types. Use consistent styling patterns to help users quickly identify and navigate to their desired conversations.

    **Implementing intuitive interactions**

    Configure swipe actions, tap behaviors, and menu options to provide users with quick access to common chat management actions while maintaining a clean and uncluttered interface.

## Best Practices

    **Tailoring the chat list experience**

    Customize the appearance of chat previews, timestamps, and unread indicators to match your app's design system. Focus on readability and clear visual hierarchy to enhance user experience.

    **Streamlining chat discovery**

    Design clear pathways for users to find existing conversations, create new ones, and manage their chat organization. Consider user habits and common usage patterns when planning the interface.

    **Ensuring cross-device compatibility**

    Optimize the chat list interface for different screen sizes and orientations. Ensure touch targets are appropriately sized and that the interface remains usable across various device configurations.

## Related Features

    **Individual Chats**
    Navigate to conversation interfaces
    **Multi-user Chats**
    Roles & member tools
    **Streaming Events**
    High-volume interaction

**Implementation Strategy**: Start with AmityChatHomePage as your main chat interface, then add ArchivedChatListComponent and AmityChannelCreateConversationPage as needed to provide complete chat management functionality.

---

### [Conversation Chat](https://learn.social.plus/uikit/components/chat/conversation-chat)

> Complete messaging interface for one-on-one and group conversations with rich media support and real-time interactions

**Key Benefit**: Seamlessly integrate complete chat functionality into your application with pre-built components that handle messaging, media sharing, reactions, and replies out of the box.

## Feature Overview

This UIKit is designed to seamlessly integrate messaging functionalities into your application, enabling rich conversations between users. Whether you're building a social network, a community platform, or a customer support system, our Conversation Chat UIKit equips you with everything you need to create engaging messaging experiences.

    **Complete Chat Experience**
    - Send and receive text messages
    - Rich media support (images and videos)
    - Message editing and deletion
    - Real-time message delivery
    **Enhanced Engagement**
    - Message reactions with emojis
    - Message replies and quoted context
    - User action controls
    - Conversation management

**Platform Support**: Conversation Chat components are available on **iOS, Android, React, React Native, and Flutter**. On **React Native**, these screens ship from v4.3.0 as part of `AmityUiKitChat`, and from v4.3.1 each page can also be rendered on its own inside `AmityPageRenderer` — see [Quick Start](/uikit/components/chat/overview#quick-start-example). Only pages are exported on React Native; the building-block components shown here (list, bubble, composer, action sheets) aren't.

## Implementation Guide

    **Complete chat conversation interface**

    The AmityChatPage serves as the main component for displaying and interacting with individual chat conversations in your application.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `channelId` | String | Unique identifier for the chat channel |
    | `userId` | String | Current user's unique identifier |
    | `userDisplayName` | String | Display name for the current user |
    | `avatarUrl` | String | URL for the user's avatar image |

    ### Features

    | Feature              | Description                                                     |
    | -------------------- | --------------------------------------------------------------- |
    | Conversation View    | Complete chat interface with message history and input controls |
    | Channel Management   | Mute/unmute toggle and conversation settings                    |
    | Network Awareness    | Offline mode indication and automatic reconnection              |
    | Message Organization | Chronological display with date separators                      |
    | Link Preview         | Automatic rich preview for shared URLs                          |

    ### Code Examples

```swift iOS
let page = AmityChatPage(channelId: "channelId")
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun chatPage() {
    AmityChatPage(channelId = "channelId")
}
```

```tsx React
import { AmityChatPage } from '@amityco/ui-kit';

<AmityChatPage channelId="channelId" />;
```

```dart Flutter
Widget chatPage() {
  return AmityChatPage(
    channelId: 'channelId',
    userId: 'userId',
    userDisplayName: 'displayName',
    avatarUrl: 'avatarUrl',
  );
}
```

```jsx React Native
// channelId is required; userDisplayName and jumpToMessageId are optional.
<AmityPageRenderer>
  <AmityChatPage channelId="channelId" />
</AmityPageRenderer>
```

    **Important Note**: The AmityChatPage automatically handles message loading, real-time updates, link previews, and user interactions.

    ### Chat Page Behavior

    Customize navigation and interaction behavior for the chat page.

```swift iOS
class CustomChatPageBehavior: AmityChatPageBehavior {
    override func onAvatarTap(context: AmityChatPageBehavior.Context) {
        // Route the header-avatar tap to your own screen.
    }
}

// Register once, e.g. at app start.
AmityUIKit4Manager.behaviour.chatPageBehavior = CustomChatPageBehavior()
```

```kotlin Android
class CustomChatPageBehavior : AmityChatPageBehavior() {
    override fun onAvatarTap(context: Context, userId: String, avatarUrl: String?) {
        // Route the header-avatar tap to your own screen.
    }
}

// Register once, e.g. at app start.
AmityChatBehaviorHelper.chatPageBehavior = CustomChatPageBehavior()
```

```dart Flutter
class CustomChatPageBehavior extends AmityChatPageBehavior {
  @override
  void onAvatarTap(
    BuildContext context,
    String? avatarUrl,
    String? userId,
  ) {
    // Route the header-avatar tap to your own screen.
  }
}

// Register once, e.g. at app start.
AmityUIKit4Manager.behavior.chatPageBehavior = CustomChatPageBehavior();
```

```jsx React Native
// Pass handlers through the behaviour prop of AmityUiKitProvider.
<AmityUiKitProvider
  /* ...credentials */
  behaviour={{
    AmityChatPageBehavior: {
      onAvatarTap: ({ userId, avatarUrl }) => {
        // Route the header-avatar tap to your own screen.
      },
    },
  }}
>
  <AmityUiKitChat />
</AmityUiKitProvider>
```

    **Individual message rendering and composition**

    Components for displaying and creating messages within the chat interface.

    ### Message Bubble Rendering

    The AmityMessageBubble renders individual chat messages as bubbles in the conversation view.

    ### Features

    | Feature              | Description                                    |
    | -------------------- | ---------------------------------------------- |
    | Content Rendering    | Support for text, images, videos               |
    | Interaction Handlers | Tap, long-press actions for message operations |
    | Rich Content         | URL detection, media previews, and thumbnails  |
    | Error Handling       | Retry options for failed messages              |

    ### Message Composition

    The AmityMessageComposer provides functionality for composing and sending messages within chat conversations.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `subChannelId` | String | Sub-channel identifier for the conversation |
    | `avatarUrl` | String | URL for the user's avatar image |
    | `action` | MessageComposerAction | Callback actions for message events |

    ### Optional Parameters

    | Parameter | Type | Default | Platforms | Description |
    |-----------|------|---------|-----------|-------------|
    | `mediaAttachmentLimit` | int | `10` | Flutter, from UIKit 4.20.18 | Maximum number of media files a user can select in one picker session |

    ### Code Examples

```swift iOS - Message List & Compose Bar
// Both components share one chat room view model.
let viewModel = AmityChatRoomViewModel(channelId: "channelId")

AmityChatMessageListComponent(viewModel: viewModel)
AmityChatMessageComposeBar(viewModel: viewModel)
```

```kotlin Android - Message List & Compose Bar
@Composable
fun conversationMessages() {
    // Both composables share one page view model.
    val viewModel = remember { AmityChatPageViewModel(channelId = "channelId") }

    AmityChatMessageList(viewModel = viewModel)
    AmityMessageComposer(viewModel = viewModel)
}
```

```tsx React - Message List & Compose Bar
import { AmityChatPage } from '@amityco/ui-kit';

// React does not expose the message list or compose bar separately for
// conversation and group chat — they are rendered by the page component.
// (AmityLiveChatMessageList and AmityLiveChatMessageComposeBar belong to Live Chat.)
<AmityChatPage channelId="channelId" />;
```

```dart Flutter - Message List & Compose Bar
// Flutter renders each message with AmityMessageBubble rather than
// exposing a list component.
Widget messageBubbleView(AmityMessage message) {
  return AmityMessageBubble(
    message: message,
  );
}

Widget messageComposer() {
  return AmityMessageComposer(
    subChannelId: 'channelId',
    avatarUrl: 'avatarUrl',
    // Optional: cap how many media files the picker allows.
    mediaAttachmentLimit: 10,
    action: MessageComposerAction(
      onMessageCreated: () {
        // Handle message created callback
        print('Message created');
      },
      onDissmiss: () {
        // Handle dismiss callback
        print('Composer dismissed');
      },
    ),
  );
}
```

    ### Message Bubble Behavior

    Override `AmityMessageBubbleBehavior` to route taps on a sender's **avatar** and on a **mentioned user** to your own screens. The mention-user tap override is available on iOS (UIKit 4.28.0), Android (UIKit 4.26.0), and React Native (UIKit 4.3.0).

    The two taps start from different defaults:

    | Override | Default behavior | Effect of overriding |
    | --- | --- | --- |
    | `onAvatarTap` | Opens the full-screen avatar viewer. Does nothing if the user has no avatar. | Replaces the viewer — it no longer opens unless you open it yourself. |
    | `onMentionUserTap` | Does nothing. | Adds behavior where there was none. |

```swift iOS
class CustomMessageBubbleBehavior: AmityMessageBubbleBehavior {
    override func onAvatarTap(context: AmityMessageBubbleBehavior.Context) {
        // Route the sender-avatar tap to your own screen.
    }

    override func onMentionUserTap(context: AmityMessageBubbleBehavior.Context) {
        // Route a tap on a mentioned user to your own screen.
    }
}

// Register once, e.g. at app start.
AmityUIKit4Manager.behaviour.messageBubbleBehavior = CustomMessageBubbleBehavior()
```

```kotlin Android
class CustomMessageBubbleBehavior : AmityMessageBubbleBehavior() {
    override fun onAvatarTap(context: Context, userId: String, avatarUrl: String?) {
        // Route the sender-avatar tap to your own screen.
    }

    override fun onMentionUserTap(context: Context, userId: String) {
        // Route a tap on a mentioned user to your own screen.
    }
}

// Register once, e.g. at app start.
AmityChatBehaviorHelper.messageBubbleBehavior = CustomMessageBubbleBehavior()
```

```dart Flutter
class CustomMessageBubbleBehavior extends AmityMessageBubbleBehavior {
  @override
  void onAvatarTap(
    BuildContext context,
    String? avatarUrl,
    String? userId,
  ) {
    // Route the sender-avatar tap to your own screen.
  }
}
```

```jsx React Native
// Pass handlers through the behaviour prop of AmityUiKitProvider.
// Handlers receive { userId, avatarUrl? } and { userId } respectively.
<AmityUiKitProvider
  /* ...credentials */
  behaviour={{
    AmityMessageBubbleBehavior: {
      onAvatarTap: ({ userId, avatarUrl }) => {
        // Route the sender-avatar tap to your own screen.
      },
      onMentionUserTap: ({ userId }) => {
        // Route a tap on a mentioned user to your own screen.
      },
    },
  }}
>
  <AmityUiKitChat />
</AmityUiKitProvider>
```

    **The header avatar is a separate hook.** `AmityMessageBubbleBehavior.onAvatarTap` covers only the sender avatar on a message bubble. The peer avatar in the conversation header is served by `AmityChatPageBehavior.onAvatarTap`, which takes the same arguments and also opens the avatar viewer by default. Override that one to redirect the header tap.

    **User interaction and management features**

    Bottom sheet component for performing actions on users within conversations.

    ### Features

    | Feature           | Description                                         |
    | ----------------- | --------------------------------------------------- |
    | Notification Control | Mute/unmute notifications for the conversation   |
    | User Management   | Report/unreport and block/unblock user options     |
    | Action Sheet UI   | Clean bottom sheet interface for user actions      |

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `user` | AmityUser | User object for the target user |
    | `isMute` | Boolean | Current mute status of the conversation |
    | `isUserBlocked` | Boolean | Current block status of the user |

    ### Code Examples

```dart Flutter
Widget conversationChatUserActionComponent() {
  // Create a user for this example
  final AmityUser user = AmityUser();

  return AmityConversationChatUserActionComponent(
    user: user,
    isMute: false,
    isUserBlocked: false,
  );
}
```

    **User Actions**: This component provides a comprehensive set of user management actions while maintaining a clean and intuitive interface.

    ### User Actions Configuration

    Control which user actions are available in conversation chats through JSON configuration.

    #### Configuration Overview

    Configure which actions appear in the user action menu by enabling or disabling specific options in your AmityUIKitConfig.json file. Set `"enabled": false` for any action you want to hide from the user action menu.

    #### Available Actions

    | Action | Description | Default |
    |--------|-------------|---------|
    | `mute` | Mute/unmute notifications for the conversation | Enabled |
    | `report` | Report the user for inappropriate behavior | Enabled |
    | `block` | Block/unblock the user | Enabled |

    #### Configuration Examples

```json Default Configuration
{
  "conversation_chat_user_actions": [
    {
      "name": "mute",
      "enabled": true
    },
    {
      "name": "report",
      "enabled": true
    },
    {
      "name": "block",
      "enabled": true
    }
  ]
}
```

```json Hide Report Action
{
  "conversation_chat_user_actions": [
    {
      "name": "mute",
      "enabled": true
    },
    {
      "name": "report",
      "enabled": false
    },
    {
      "name": "block",
      "enabled": true
    }
  ]
}
```

```json Only Mute Action
{
  "conversation_chat_user_actions": [
    {
      "name": "mute",
      "enabled": true
    },
    {
      "name": "report",
      "enabled": false
    },
    {
      "name": "block",
      "enabled": false
    }
  ]
}
```

```json All Actions Disabled
{
  "conversation_chat_user_actions": [
    {
      "name": "mute",
      "enabled": false
    },
    {
      "name": "report",
      "enabled": false
    },
    {
      "name": "block",
      "enabled": false
    }
  ]
}
```

    **Global Configuration**: These user action configurations are set at the global level in AmityUIKitConfig.json and apply to all conversation chat components automatically.

    **React Native**: v4.3.0 doesn't read `conversation_chat_user_actions`. All three actions — notification toggle, report, and block — are always shown.

    #### Configuration Benefits

    | Benefit | Description |
    |---------|-------------|
    | **Flexibility** | Enable only the actions that make sense for your app's use case |
    | **User Safety** | Control moderation and safety features available to users |
    | **Simplified UI** | Reduce clutter by hiding unnecessary options |
    | **Consistent Experience** | Global configuration ensures consistency across all conversations |

    #### Best Practices

        **Choosing appropriate user actions**

        Consider your app's moderation strategy when configuring user actions. If you have a separate reporting system, you might disable the built-in report action. For community-focused apps, keep all safety features enabled to empower users.

        **Maintaining safe conversation environments**

        While you can disable actions, consider the impact on user safety. Block and report features are important safety tools. Only disable them if you have alternative mechanisms in place.

        **Validating action configurations**

        Test your configuration changes thoroughly across different user scenarios. Ensure that disabling actions doesn't negatively impact user experience or safety features in your application.

## Component Management Strategies

    **Integrating chat components into your app**

    The UIKit components are designed to work seamlessly together. Use AmityChatPage as your main interface, and leverage individual components like AmityMessageBubble and MessageComposer when you need granular control over specific parts of the chat experience.

    **Tailoring the chat interface**

    Customize the appearance and behavior of chat components to match your app's design. The UIKit provides theming options and component configuration to align with your brand while maintaining core functionality.

    **Designing intuitive chat experiences**

    Plan your navigation flow between chat components and other parts of your app. Consider how users will access conversations, manage settings, and interact with message features for the best user experience.

## Best Practices

    **Optimizing UIKit setup**

    Configure the UIKit components properly for your use case. Ensure proper parameter passing between components and handle callback functions appropriately. The underlying SDK handles all performance optimization automatically.

    **Creating engaging chat interfaces**

    Focus on clear visual hierarchy, intuitive interaction patterns, and responsive design. The UIKit provides pre-built interactions while allowing you to customize the presentation layer to match your app's experience.

    **Managing user interactions gracefully**

    Implement proper error handling for user actions and provide clear feedback for loading states, connection issues, and user interactions. The SDK manages network reliability while the UIKit handles user interface feedback.

## Related Features

    **All Chat Components**
    Summary & architecture
    **Multi-user Features**
    Roles & member tools
    **Streaming Chat**
    High-volume events

**Implementation Strategy**: Start with the AmityChatPage component for a complete chat experience, then customize individual components like AmityMessageBubble and MessageComposer as needed for your specific use case.

---

### [Group Chat](https://learn.social.plus/uikit/components/chat/group-chat)

> Complete group conversation solution with member management, moderation tools, and rich messaging for multi-user interactions

**Key Benefit**: Build feature-rich group conversations with complete member management, role-based permissions, moderation tools, and interactive messaging capabilities all in pre-built components.

## Feature Overview

The Group Chat UIKit is designed to provide a complete solution for multi-user conversations within your application. It offers rich functionality for group creation, member management, and interactive messaging experiences. This component is ideal for building community spaces, team channels, or any feature requiring conversations among multiple participants.

    **Complete Group Control**
    - Create and customize group chats
    - Edit group profiles and settings
    - Privacy controls (public/private)
    - Avatar and name management
    **Advanced Member Controls**
    - Add, remove, and ban members
    - Role-based permissions system
    - Moderator privilege management
    - Member action controls

    **Interactive Communication**
    - Text, images, and videos
    - Message reactions and replies
    - Edit and delete capabilities for your own messages
    - Real-time message delivery
    **Safety & Control**
    - Message reporting system
    - User banning and management
    - Content moderation tools
    - Notification preferences

**Message-level moderation**: Moderator deletion of another member's message is separate from member-level actions such as banning, muting, removing, or changing roles. It is available from iOS UIKit **4.23.0**, Android UIKit **4.23.0**, Web (React) UIKit **4.20.0**, and React Native UIKit **4.3.0**.

**Platform Support**: Group Chat components are available on **iOS, Android, React, React Native, and Flutter**. On **React Native**, these screens ship from v4.3.0 as part of `AmityUiKitChat`, and from v4.3.1 each page can also be rendered on its own inside `AmityPageRenderer` — see [Quick Start](/uikit/components/chat/overview#quick-start-example). Only pages are exported on React Native; the building-block components shown here (list, bubble, composer, action sheets) aren't.

## Implementation Guide

    **Main group conversation interface**

    The primary components for group chat functionality and conversation management.

    ### Group Chat Page

    The AmityGroupChatPage serves as the main interface for group conversations with real-time messaging capabilities.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `channelId` | String | Unique identifier for the group chat channel |

    ### Features

    | Feature                | Description                                    |
    | ---------------------- | ---------------------------------------------- |
    | Real-time Display      | Live message updates and conversation flow     |
    | Message Composition    | Text, images, and videos                       |
    | Message Actions        | Reply, edit, delete, and reaction capabilities |
    | Member Interaction     | User profiles and member-specific actions     |
    | Link Preview           | Automatic rich preview for shared URLs        |
    | User Mention           | Tag and notify members using @ mentions       |

    ### Code Examples

```swift iOS
let page = AmityGroupChatPage(channelId: "your-channel-id")
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun groupChatPage() {
    AmityGroupChatPage(channelId = "your-channel-id")
}
```

```tsx React
import { AmityGroupChatPage } from '@amityco/ui-kit';

<AmityGroupChatPage channelId="your-channel-id" />;
```

```dart Flutter
Widget groupChatPage() {
  return AmityGroupChatPage(
    channelId: 'your-channel-id',
  );
}
```

```jsx React Native
<AmityPageRenderer>
  <AmityGroupChatPage channelId="your-channel-id" />
</AmityPageRenderer>
```

    **Automatic Features**: The group chat page automatically handles real-time updates, message synchronization, link previews, user mentions, and user interactions through the underlying SDK.

    **Creating and configuring new groups**

    Components for setting up new group chats and managing initial configuration.

    ### Group Creation Flow

    Create new group chats with member selection, naming, and privacy settings.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `selectedUsers` | List&lt;AmityUser&gt; | Initial members for the group chat |

    ### Features

    | Feature              | Description                                   |
    | -------------------- | --------------------------------------------- |
    | Group Naming         | Set optional group name and description      |
    | Avatar Upload        | Choose or upload group avatar image          |
    | Privacy Settings     | Configure public or private group access     |
    | Member Management    | View and manage selected members             |

    ### Member Selection

    Select users when creating groups or adding members to existing groups.

    ### Code Examples

```swift iOS - Create Group
let page = AmityCreateGroupChatPage(selectedUsers: selectedUsers)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android - Create Group
@Composable
fun createGroupChatPage(selectedUsers: List<AmityUser>) {
    AmityCreateGroupChatPage(selectedUsers = selectedUsers)
}
```

```tsx React - Create Group
import { AmityCreateGroupChatPage } from '@amityco/ui-kit';

<AmityCreateGroupChatPage selectedUsers={selectedUsers} />;
```

```dart Flutter - Create Group
Widget createGroupChatPage() {
  // Create a list of users for this example
  final List<AmityUser> selectedUsers = [];

  return AmityCreateGroupChatPage(
    selectedUsers: selectedUsers,
  );
}
```

```jsx React Native - Create Group
// selectedUsers: Amity.User[] (the members picked for the new group)
<AmityPageRenderer>
  <AmityCreateGroupChatPage selectedUsers={selectedUsers} />
</AmityPageRenderer>
```

```dart Flutter - Select Members
Widget selectGroupMemberPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityAddGroupMemberPage(
    channel: channel,
  );
}
```

```jsx React Native - Select Members
// selectedGroupMember is optional: users to show as already selected
<AmityPageRenderer>
  <AmitySelectGroupMemberPage />
</AmityPageRenderer>
```

    **Group management and configuration**

    Comprehensive settings and administrative controls for group management.

    ### Group Settings Page

    Central hub for all group configuration and management options.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `channel` | AmityChannel | Group channel object |
    | `isModerator` | Boolean | Current user's moderator status |

    ### Administrative Features

    | Feature                    | Description                                      |
    | -------------------------- | ------------------------------------------------ |
    | Profile Management         | Edit group name, avatar, and description        |
    | Member Permissions         | Configure who can post and manage content       |
    | Notification Settings      | Group-wide and personal notification controls   |
    | Member Management          | View, add, remove, and ban members             |
    | Moderation Tools           | Access banned users and reporting features      |

    **React Native** (v4.3.0+): Moderators choose the group's notification mode: **Default** (members get notifications and can turn them off), **Silent** (no notifications for anyone), or **Subscribe** (off by default, and members can opt in). Members turn notifications for the group on or off, unless a moderator has disabled them, in which case a banner explains this.

    ### Code Examples

```swift iOS - Group Settings
let page = AmityGroupSettingPage(channelId: "your-channel-id", isModerator: false)
let viewController = AmitySwiftUIHostingController(rootView: page)

// Related pages
AmityEditGroupProfilePage(channelId: "your-channel-id", displayName: "Team", avatarURL: nil)
AmityGroupNotificationPreferencePage(channelId: "your-channel-id", isSilentByModerator: false)
AmityEditGroupMemberPermissionsPage(channelId: "your-channel-id", isMuted: false)
```

```kotlin Android - Group Settings
@Composable
fun groupSettingPage() {
    AmityGroupSettingPage(channelId = "your-channel-id")
}

// Related pages
// AmityEditGroupProfilePage(channelId = "your-channel-id")
// AmityGroupNotificationPreferencePage(channelId = "your-channel-id")
// AmityEditGroupMemberPermissionsPage(channelId = "your-channel-id")
```

```tsx React - Group Settings
import {
  AmityGroupSettingPage,
  AmityEditGroupProfilePage,
  AmityGroupNotificationPreferencePage,
  AmityEditGroupMemberPermissionsPage,
} from '@amityco/ui-kit';

<AmityGroupSettingPage channelId="your-channel-id" />;
```

```dart Flutter - Group Settings
Widget groupSettingPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityGroupSettingPage(
    channel: channel,
    isModerator: false,
  );
}
```

```jsx React Native - Group Settings
<AmityPageRenderer>
  <AmityGroupSettingPage channelId="your-channel-id" />
</AmityPageRenderer>
```

```dart Flutter - Edit Profile
Widget editGroupProfilePage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityEditGroupProfilePage(
    channel: channel,
  );
}
```

```jsx React Native - Edit Profile
<AmityPageRenderer>
  <AmityEditGroupProfilePage channelId="your-channel-id" />
</AmityPageRenderer>
```

```dart Flutter - Notification Settings
Widget groupNotificationPreferencePage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityGroupNotificationPreferencePage(
    channel: channel,
  );
}
```

```jsx React Native - Notification Settings
<AmityPageRenderer>
  <AmityGroupNotificationPreferencePage channelId="your-channel-id" />
</AmityPageRenderer>
```

```dart Flutter - Member Permissions
Widget editGroupMemberPermissionsPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityEditGroupMemberPermissionsPage(
    channel: channel,
  );
}
```

```jsx React Native - Member Permissions
<AmityPageRenderer>
  <AmityEditGroupMemberPermissionsPage channelId="your-channel-id" />
</AmityPageRenderer>
```

    **User administration and moderation**

    Tools for managing group members, permissions, and moderation actions.

    ### Member List Management

    View and manage all group members with role-based controls.

    ### Features

    | Feature                | Description                                     |
    | ---------------------- | ----------------------------------------------- |
    | Member Directory       | List of all members and moderators            |
    | Member Actions         | Report, remove, ban, mute, and promote options |
    | Add Members           | Search users by display name and add them to the group |
    | Banned User Management | View and manage banned members                 |
    | Mute Members           | Moderators can mute members from posting      |

    ### Member Action Controls

    Bottom sheet component for performing actions on individual group members.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `user` | AmityUser | Target user for actions |
    | `isCurrentUserModerator` | Boolean | Current user's moderator status |
    | `isSelectedUserModerator` | Boolean | Target user's moderator status |

    ### Code Examples

```swift iOS - Member List
let page = AmityGroupMemberListPage(channelId: "your-channel-id", isModerator: false)
let viewController = AmitySwiftUIHostingController(rootView: page)

// Related pages
AmityAddGroupMemberPage(channelId: "your-channel-id")
AmityBannedGroupMemberListPage(channelId: "your-channel-id", isModerator: false)
```

```kotlin Android - Member List
@Composable
fun groupMemberListPage() {
    AmityGroupMemberListPage(channelId = "your-channel-id")
}

// Related pages
// AmityAddGroupMemberPage(channelId = "your-channel-id")
// AmityBannedGroupMemberListPage(channelId = "your-channel-id")
```

```tsx React - Member List
import {
  AmityGroupMemberListPage,
  AmityAddGroupMemberPage,
  AmityBannedGroupMemberListPage,
} from '@amityco/ui-kit';

<AmityGroupMemberListPage channelId="your-channel-id" />;
```

```dart Flutter - Member List
Widget groupMemberListPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityGroupMemberListPage(
    channel: channel,
  );
}
```

```jsx React Native - Member List
<AmityPageRenderer>
  <AmityGroupMemberListPage channelId="your-channel-id" />
</AmityPageRenderer>
```

```dart Flutter - Member Actions
Widget groupMemberActionComponent() {
  // Create a user for this example
  final AmityUser user = AmityUser();

  return AmityGroupMemberActionComponent(
    user: user,
    isCurrentUserModerator: true,
    isSelectedUserModerator: false,
  );
}
```

```dart Flutter - Add Members
Widget addGroupMemberPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityAddGroupMemberPage(
    channel: channel,
  );
}
```

```jsx React Native - Add Members
<AmityPageRenderer>
  <AmityAddGroupMemberPage channelId="your-channel-id" />
</AmityPageRenderer>
```

```dart Flutter - Banned Members
Widget bannedGroupMemberListPage() {
  // Create a channel for this example
  final AmityChannel channel = AmityChannel();
  channel.channelId = 'your-channel-id';

  return AmityBannedGroupMemberListPage(
    channel: channel,
  );
}
```

```jsx React Native - Banned Members
<AmityPageRenderer>
  <AmityBannedGroupMemberListPage channelId="your-channel-id" />
</AmityPageRenderer>
```

    **Safety and content management tools**

    Components for maintaining safe and appropriate group conversations.

    ### Message Reporting

    Allow users to report inappropriate messages with predefined or custom reasons.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `message` | AmityMessage | Message object to report |

    ### Features

    | Feature                | Description                                  |
    | ---------------------- | -------------------------------------------- |
    | Predefined Reasons     | Quick selection of common report categories  |
    | Custom Reporting       | Option to provide detailed custom reasons   |
    | Automated Processing   | Integration with moderation workflows       |

    **React Native** (v4.3.0+): Moderators can delete any member's message, not only their own. Members can report and unreport messages and other members. A moderator badge appears on moderators' avatars.

    ### Code Examples

```kotlin Android - Message Reporting
@Composable
fun messageReportPage() {
    AmityMessageReportPage(messageId = "your-message-id")
}
```

```dart Flutter - Message Reporting
Widget messageReportComponent() {
  // Create a message for this example
  final AmityMessage message = AmityMessage();

  // Report component
  final reportComponent = AmityMessageReportComponent(
    message: message,
  );

  // Return the report component for the example
  return reportComponent;
}
```

    **Moderation Integration**: Report submissions are automatically processed through the SDK's moderation system and can trigger configured moderation workflows.

    ### Moderator Message Deletion

    Group moderators can delete messages authored by other members from iOS UIKit **4.23.0**, Android UIKit **4.23.0**, and Web (React) UIKit **4.20.0**. This is a message-level moderation action, separate from the member-level ban, mute, removal, and role-management actions covered under Member Management.

    ### Behavior

    | Aspect | Detail |
    | ------ | ------ |
    | Who can delete | Members holding the channel moderator role |
    | What can be deleted | Any member's message in the group chat |
    | Where it appears | The message action menu in the group chat message list |
    | Integration required | None — the delete action appears automatically once the current user has the moderator role |

    **Scope**: The delete action is gated on the channel moderator role, so in practice it applies to group chat, where that role is assigned. Members without the role can still delete only their own messages.

    **Individual message rendering and composition**

    Components for displaying and creating messages within the chat interface.

    ### Message Bubble Rendering

    The AmityMessageBubble renders individual chat messages as bubbles in the conversation view.

    ### Features

    | Feature              | Description                                    |
    | -------------------- | ---------------------------------------------- |
    | Content Rendering    | Support for text, images, videos               |
    | Interaction Handlers | Tap, long-press actions for message operations |
    | Rich Content         | URL detection, media previews, and thumbnails  |
    | Error Handling       | Retry options for failed messages              |

    ### Message Composition

    The AmityMessageComposer provides functionality for composing and sending messages within chat conversations.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `subChannelId` | String | Sub-channel identifier for the conversation |
    | `avatarUrl` | String | URL for the user's avatar image |
    | `action` | MessageComposerAction | Callback actions for message events |

    ### Optional Parameters

    | Parameter | Type | Default | Platforms | Description |
    |-----------|------|---------|-----------|-------------|
    | `mediaAttachmentLimit` | int | `10` | Flutter, from UIKit 4.20.18 | Maximum number of media files a user can select in one picker session |

    ### Code Examples

```swift iOS - Message List & Compose Bar
// Both components share one chat room view model.
let viewModel = AmityChatRoomViewModel(channelId: "your-channel-id")

AmityChatMessageListComponent(viewModel: viewModel, pageId: .groupChatPage)
AmityChatMessageComposeBar(viewModel: viewModel, isGroupChat: true)
```

```kotlin Android - Message List & Compose Bar
@Composable
fun groupMessages() {
    // Both composables share one page view model.
    val viewModel = remember { AmityGroupChatPageViewModel(channelId = "your-channel-id") }

    AmityGroupChatMessageList(viewModel = viewModel)
    AmityGroupChatMessageComposer(viewModel = viewModel)
}
```

```tsx React - Message List & Compose Bar
import { AmityGroupChatPage } from '@amityco/ui-kit';

// React does not expose the message list or compose bar separately for
// conversation and group chat — they are rendered by the page component.
// (AmityLiveChatMessageList and AmityLiveChatMessageComposeBar belong to Live Chat.)
<AmityGroupChatPage channelId="your-channel-id" />;
```

```dart Flutter - Message List & Compose Bar
// Flutter renders each message with AmityMessageBubble rather than
// exposing a list component.
Widget messageBubbleView(AmityMessage message) {
  return AmityMessageBubble(
    message: message,
  );
}

Widget messageComposer() {
  return AmityMessageComposer(
    subChannelId: 'channelId',
    avatarUrl: 'avatarUrl',
    // Optional: cap how many media files the picker allows.
    mediaAttachmentLimit: 10,
    action: MessageComposerAction(
      onMessageCreated: () {
        // Handle message created callback
        print('Message created');
      },
      onDissmiss: () {
        // Handle dismiss callback
        print('Composer dismissed');
      },
    ),
  );
}
```

    ### Message Bubble Behavior

    Override `AmityMessageBubbleBehavior` to route taps on a sender's **avatar** and on a **mentioned user** to your own screens. The mention-user tap override is available on iOS (UIKit 4.28.0) and Android (UIKit 4.26.0).

    The two taps start from different defaults:

    | Override | Default behavior | Effect of overriding |
    | --- | --- | --- |
    | `onAvatarTap` | Opens the full-screen avatar viewer. Does nothing if the user has no avatar. | Replaces the viewer — it no longer opens unless you open it yourself. |
    | `onMentionUserTap` | Does nothing. | Adds behavior where there was none. |

```swift iOS
class CustomMessageBubbleBehavior: AmityMessageBubbleBehavior {
    override func onAvatarTap(context: AmityMessageBubbleBehavior.Context) {
        // Route the sender-avatar tap to your own screen.
    }

    override func onMentionUserTap(context: AmityMessageBubbleBehavior.Context) {
        // Route a tap on a mentioned user to your own screen.
    }
}

// Register once, e.g. at app start.
AmityUIKit4Manager.behaviour.messageBubbleBehavior = CustomMessageBubbleBehavior()
```

```kotlin Android
class CustomMessageBubbleBehavior : AmityMessageBubbleBehavior() {
    override fun onAvatarTap(context: Context, userId: String, avatarUrl: String?) {
        // Route the sender-avatar tap to your own screen.
    }

    override fun onMentionUserTap(context: Context, userId: String) {
        // Route a tap on a mentioned user to your own screen.
    }
}

// Register once, e.g. at app start.
AmityChatBehaviorHelper.messageBubbleBehavior = CustomMessageBubbleBehavior()
```

```dart Flutter
class CustomMessageBubbleBehavior extends AmityMessageBubbleBehavior {
  @override
  void onAvatarTap(
    BuildContext context,
    String? avatarUrl,
    String? userId,
  ) {
    // Route the sender-avatar tap to your own screen.
  }
}
```

## Component Management Strategies

    **Planning group creation to deletion workflow**

    Design clear user flows for creating groups, managing settings, adding members, and handling group lifecycle events. Consider how users will discover groups, join conversations, and manage their participation.

    **Implementing role-based access control**

    Plan your group permission structure carefully, considering moderator privileges, member capabilities, and administrative controls. Use the built-in role system to maintain appropriate access levels.

    **Building effective content management**

    Configure reporting workflows, automated moderation responses, and escalation procedures. Plan how moderators will handle reported content and member management tasks.

## Best Practices

    **Creating intuitive group interactions**

    Design clear navigation between group functions, provide helpful onboarding for group creation, and ensure member management tools are easily accessible to appropriate users.

    **Planning for group growth**

    Consider how your groups will scale with member count, message volume, and administrative complexity. Plan appropriate limits and management tools for large groups.

    **Maintaining secure group environments**

    Implement appropriate privacy controls for different group types, ensure reporting mechanisms are easily accessible, and provide clear moderation capabilities for group administrators.

## Related Features

    **Find Content Fast**
    Search channels and messages
    **Individual Messaging**
    One-on-one conversation features
    **Chat Management**
    Organize and navigate conversations

**Implementation Strategy**: Start with AmityGroupChatPage for basic group messaging, then add AmityCreateGroupChatPage for group creation, and finally integrate the settings and moderation components as needed for your use case.

---

### [Live Chat](https://learn.social.plus/uikit/components/chat/live-chat)

> Real-time chat interface designed for live streaming and events with reactions, mentions, and interactive messaging

**Key Benefit**: Enhance live streaming experiences with real-time chat functionality including messaging, reactions, mentions, and user interactions designed specifically for high-volume live events.

## Feature Overview

This powerful UIKit is designed to seamlessly integrate live chat functionalities into your in-app livestreams, enhancing viewer engagement and interaction. Whether you're hosting gaming streams, sports events, or live Q&A sessions, our UIKit equips you with everything you need to create an immersive chat experience.

    **Real-Time Communication**
    - Send and receive text messages instantly
    - Edit or delete own messages
    - Flag inappropriate content for moderation
    - High-volume message handling
    **Enhanced Engagement**
    - Message reactions with customizable emojis
    - User mentions (@username or @all)
    - User profiles and role badges
    - Moderator identification

    **Brand-Aligned Design**
    - Customizable messaging components
    - Theme configuration options
    - Configurable message limits
    - Custom placeholder text
    **Stream-Ready Features**
    - Channel information display
    - Member count tracking
    - Real-time message flow
    - Performance optimized for live events

## Implementation Guide

    **Full-featured live chat interface**

    The AmityLiveChatPage provides a complete live chat experience by integrating header, message list, and compose bar components.

    ### Required Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `channelId` | String | Unique identifier for the live chat channel |

    ### Features

    | Feature                   | Description                                |
    | ------------------------- | ------------------------------------------ |
    | Live Chat Functionalities | A complete page with full live chat features |
    | Real-Time Updates         | Instant message delivery and display       |
    | Integrated Components     | Header, message list, and compose bar     |

    ### Customization Options

    | Config ID | Config Key | Type | Description |
    |-----------|------------|------|-------------|
    | `live_chat/*/*` | `theme` | Page | Customize page theme |

    ### Code Examples

```swift iOS
let page = AmityLiveChatPage(channelId: "live-channel-id")

// To use this page from UIKit framework, you can also wrap it in AmitySwiftUIHostingController.
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeLiveChatPage(
    channelId: String
) {
    AmityLiveChatPage(
        channelId = channelId
    )
}
```

```typescript React
import React from 'react';
import { AmityLiveChatPage } from '@amityco/ui-kit';

interface SampleLiveChatPageProps {
  channelId: Amity.Channel['channelId']
}

const SampleLiveChatPage = ({ channelId }: SampleLiveChatPageProps) => {
  // Passing channelId to the component
  return <AmityLiveChatPage channelId={channelId} />
}

export default SampleLiveChatPage;
```

    **Complete Integration**: The live chat page automatically handles real-time messaging, user interactions, and component coordination through the underlying SDK.

    **Channel information display**

    The AmityLiveChatHeader component provides a visual representation of channel profile information.

    ### Features

    | Feature              | Description                                              |
    | -------------------- | -------------------------------------------------------- |
    | Display Channel Info | Display channel's display name, avatar, and member count |
    | Live Updates         | Real-time member count and channel status updates       |

    ### Customization Options

    | Config ID | Config Key | Type | Description |
    |-----------|------------|------|-------------|
    | `live_chat/chat_header/*` | `theme` | Component | Customize component theme |

    ### Code Examples

```swift iOS
let viewModel = AmityLiveChatPageViewModel(channelId: "live-channel-id")
let header = AmityLiveChatHeader(viewModel: viewModel)
```

```kotlin Android
@Composable
fun composeLiveChatHeader(
    viewModel: AmityLiveChatPageViewModel
) {
    AmityLiveChatHeader(
        viewModel = viewModel
    )
}
```

```typescript React
import React from 'react';
import { AmityLiveChatHeader } from '@amityco/ui-kit';

interface SampleLiveChatHeaderProps {
  channel: Amity.Channel
}

const SampleLiveChatHeader = ({ channel }: SampleLiveChatHeaderProps) => {
  // Passing channel model
  return <AmityLiveChatHeader channel={channel} />
}

export default SampleLiveChatHeader;
```

    **Message display and interaction**

    Components for viewing messages and handling reactions in real-time.

    ### Message List Component

    The AmityLiveChatMessageList enables users to view and interact with messages in real-time.

    ### Message List Features

    | Feature                | Description                                                               |
    | ---------------------- | ------------------------------------------------------------------------- |
    | View Messages          | View past and real-time messages in the channel                          |
    | Interact with Messages | Trigger possible actions on each message such as copy, reply, and delete |
    | Real-Time Updates      | Instant message appearance and status updates                            |

    ### Message List Code Examples

```swift iOS
let viewModel = AmityLiveChatPageViewModel(channelId: "live-channel-id")
let messageList = AmityLiveChatMessageList(viewModel: viewModel)
```

```kotlin Android
@Composable
fun composeLiveChatMessageList(
    viewModel: AmityLiveChatPageViewModel
) {
    AmityLiveChatMessageList(
        viewModel = viewModel
    )
}
```

```typescript React
import React, { useState } from 'react';
import { AmityLiveChatMessageList } from '@amityco/ui-kit';

interface SampleLiveChatMessageListProps {
  channel: Amity.Channel
}

const SampleLiveChatMessageList = ({ channel }: SampleLiveChatMessageListProps) => {
  // Passing channel model
  const [replyMessage, setReplyMessage] = useState<Amity.Message | undefined>(undefined);
  return (
    <AmityLiveChatMessageList
      channel={channel}                 // channel model
      replyMessage={setReplyMessage}    // function to set reply message
    />
  );
}

export default SampleLiveChatMessageList;
```

    ### Reaction List Component

    The AmityReactionList allows users to view and manage reactions on messages.

    ### Reaction List Features

    | Feature              | Description                                                 |
    | -------------------- | ----------------------------------------------------------- |
    | Reaction List        | Users can view the list of users who reacted on the message |
    | Add/Remove Reactions | Interactive reaction management                             |
    | User Profiles        | Display user information for each reaction                  |

    ### Reaction List Code Examples

```swift iOS
// Create reaction list component
let reactionListView = AmityReactionList(referenceId: "message-id", referenceType: .message)
let viewController = AmitySwiftUIHostingController(rootView: reactionListView)
```

```kotlin Android
@Composable
fun ReactionListSample(
    referenceType: AmityReactionReferenceType,
    referenceId: String
) {
    AmityReactionList(
        referenceType = referenceType,
        referenceId = referenceId
    )
}
```

```typescript React
import { AmityReactionList } from '@amityco/ui-kit';
import React from 'react';

interface SampleAmityReactionListProps {
  referenceId: string;
  referenceType: Amity.ReactableType;
}

const SampleAmityReactionList = ({ referenceId, referenceType }: SampleAmityReactionListProps) => {
  return <AmityReactionList referenceId={referenceId} referenceType={referenceType} />;
};

export default SampleAmityReactionList;
```

    ### Customization Options

    | Config ID | Config Key | Type | Description |
    |-----------|------------|------|-------------|
    | `live_chat/message_list/*` | `theme` | Component | Customize component theme |

    **Message creation and interaction**

    The AmityLiveChatMessageComposeBar provides full message creation functionality with mentions and reply capabilities.

    ### Features

    | Feature                      | Description                                                        |
    | ---------------------------- | ------------------------------------------------------------------ |
    | Create Message               | Enable message creation with text input                           |
    | Mention Other Members        | Enable '@' character to trigger user selection for mentions       |
    | Reply Functionality          | Reply to specific messages in the conversation                    |
    | Character Limits             | Configurable message length restrictions                          |

    ### Customization Options

    | Config ID | Config Key | Type | Description |
    |-----------|------------|------|-------------|
    | `live_chat/message_compose_bar/*` | `theme` | Component | Customize component theme |
    | `live_chat/message_compose_bar/*` | `message_limit` | Component | Define maximum character count |
    | `live_chat/message_compose_bar/*` | `placeholder_text` | Component | Define placeholder text on the compose bar |

    ### Code Examples

```swift iOS
let viewModel = AmityLiveChatPageViewModel(channelId: "live-channel-id")
let messageComposeBar = AmityLiveChatMessageComposeBar(viewModel: viewModel)
```

```kotlin Android
@Composable
fun composeLiveChatMessageComposeBar(
    viewModel: AmityLiveChatPageViewModel
) {
    AmityLiveChatMessageComposeBar(
        viewModel = viewModel
    )
}
```

```typescript React
import React, { useRef, useState } from 'react';
import { AmityLiveChatMessageComposeBar } from '@amityco/ui-kit';

interface SampleLiveChatMessageComposeBarProps {
  channel: Amity.Channel,
}

const SampleLiveChatPage = ({ channel }: SampleLiveChatMessageComposeBarProps) => {
  const mentionSuggestionRef = useRef<HTMLDivElement>(null);
  const [replyMessage, setReplyMessage] = useState<Amity.Message | undefined>();
  const [mentionMessage, setMentionMessage] = useState<Amity.Message | undefined>();

  return (
    <>
      <div ref={mentionSuggestionRef}>
        {/* User suggestion panel will render here */}
      </div>

      <AmityLiveChatMessageComposeBar
        channel={channel}
        suggestionRef={mentionSuggestionRef}
        composeAction={{
          replyMessage,
          mentionMessage,
          clearReplyMessage: () => setReplyMessage(undefined),
          clearMention: () => setMentionMessage(undefined),
        }}
      />
    </>
  )
}

export default SampleLiveChatPage;
```

    **Advanced Features**: The compose bar includes built-in user mention suggestions, reply management, and configurable message limits for optimal live chat performance.

## Component Management Strategies

    **Optimizing for high-volume live streams**

    Plan your live chat implementation to handle high message volumes during popular streams. Consider message rate limiting, user role management, and moderation workflows to maintain a positive chat environment.

    **Maximizing viewer interaction**

    Design clear visual hierarchies for user roles, implement intuitive reaction systems, and provide easy access to mentions and replies to encourage active participation in live events.

    **Maintaining safe live environments**

    Implement effective moderation tools, user reporting systems, and automated content filtering to ensure live chat remains engaging and appropriate for your audience.

## Best Practices

    **Ensuring smooth live chat experience**

    Configure appropriate message limits, implement efficient scrolling behaviors, and optimize component rendering for smooth performance during high-activity live events.

    **Creating engaging live interactions**

    Design clear visual indicators for user roles, provide intuitive interaction patterns for reactions and mentions, and ensure the chat interface doesn't interfere with the main live content.

    **Aligning with your brand and content**

    Customize themes, message limits, and placeholder text to match your streaming platform's design and tone. Consider your audience and content type when configuring interaction features.

## Related Features

    **Multi-User Conversations**
    Advanced group messaging features
    **Standard Messaging**
    Regular chat conversation components
    **Content Safety**
    Content moderation and user management

**Implementation Strategy**: Start with AmityLiveChatPage for a complete live chat experience, then customize individual components (header, message list, compose bar) as needed to match your streaming platform's specific requirements and branding.

---

### [Search chats & messages](https://learn.social.plus/uikit/components/chat/search-chat)

> Powerful search capabilities across channels and messages for efficient chat navigation and content discovery

**Key Benefit**: Dramatically improve user experience by allowing users to instantly find past conversations, locate important messages, and navigate large chat histories with powerful dual-mode search capabilities.

## Feature Overview

The Chat Search UIKit provides comprehensive search functionality that enables users to quickly find conversations and locate specific message content. It offers two distinct search modes optimized for different use cases - searching for channels by name and searching for specific message content across all conversations.

    **Find Conversations Fast**
    - Search by channel name and participants
    - Real-time result updates
    - Covers both conversation and community channels
    - Archive status visibility
    **Locate Specific Content**
    - Full-text search across messages
    - Context preview with highlights
    - Jump to message in conversation
    - Sender information display

    **Optimized Experience**
    - Efficient server-side indexing
    - Instant search results
    - Real-time updates
    - Minimal resource usage
    **Complete Coverage**
    - Search archived channels
    - Clear archive indicators
    - Access archived content
    - Seamless navigation

**Platform Support**: Chat Search is available on **Flutter** (standalone `AmitySearchChannelPage`), **React Web**, and **React Native** v4.3.0+ (reached from the chat home page, or rendered standalone as `AmitySearchChannelPage` from v4.3.1 — see the notes below). Refer to the platform UIKit for iOS and Android availability.

## Implementation Guide

    **Find channels and conversations**

    Search across conversation and community channels to quickly locate chats by name or participants.

    ### Search Page

    The AmitySearchChannelPage provides a unified search interface with tab-based navigation between Chat and Message search modes.

    ### Features

    | Feature                | Description                                    |
    | ---------------------- | ---------------------------------------------- |
    | Channel Name Search    | Search by display name of channels            |
    | Real-time Results      | Results update instantly as you type          |
    | Channel Type Support   | Includes conversations and community chats    |
    | Last Message Preview   | Shows preview of most recent message          |
    | Archive Indicator      | Displays archive status for each channel      |
    | Quick Navigation       | Tap result to open channel immediately        |

    ### Code Examples

```dart Flutter - Search Page
Widget searchPage() {
  return AmitySearchChannelPage();
}
```

```jsx React Native - Search Page
<AmityPageRenderer>
  <AmitySearchChannelPage />
</AmityPageRenderer>
```

    **Search Scope**: Chat Search mode searches across both active and archived channels, with clear indicators showing which channels are archived.

    **React Web**: Search is not a standalone exported page on React Web. It is reached from `AmityChatHomePage` via the header search entry, which opens the search view with the Chat / Message tabs. The Chat tab is backed by the SDK's `ChannelRepository.searchChannels` (member channels of type `conversation` and `community`, sorted by last activity), and archived channels are indicated inline. No extra wiring is required — enable the chat home page and search is available.

    **React Native** (v4.3.0+): Search opens from the search button on the chat home page, with **Chats** and **Messages** tabs. From v4.3.1 you can also render `AmitySearchChannelPage` on its own inside `AmityPageRenderer`. Results appear once the query is at least 3 characters. Archived channels show an archived badge; swipe a result row to archive or unarchive it. Tapping a result in the **Messages** tab opens the chat scrolled to that message. One-to-one chats with users the viewer has blocked are hidden from both tabs.

    **Search within message content**

    Perform full-text search across all messages to find specific content, discussions, or shared information.

    ### Features

    | Feature                | Description                                      |
    | ---------------------- | ------------------------------------------------ |
    | Full-Text Search       | Search across all message text content          |
    | Context Preview        | View message snippets with highlighted terms    |
    | Jump to Message        | Navigate directly to message in conversation    |
    | Sender Information     | See who sent each matching message              |
    | Timestamp Display      | View when messages were sent                    |
    | Multi-Channel Search   | Search across all accessible channels           |

    ### Code Examples

```dart Flutter - Message Search
Widget searchPage() {
  // Same component provides both search modes
  // Users switch between Chat and Message tabs
  return AmitySearchChannelPage();
}
```

    **Automatic Features**: The search page automatically handles real-time updates, result filtering, and navigation through the underlying SDK.


## Search Management Strategies

    **Creating intuitive search flows**

    Design clear entry points to search functionality from your chat interface. Consider placing search prominently in navigation, providing keyboard shortcuts for power users, and ensuring smooth transitions between search results and conversations.

    **Handling large conversation volumes**

    The search component automatically handles performance optimization through server-side indexing and efficient result delivery. Real-time updates ensure users always see the most current results without manual refresh.

    **Maintaining access control**

    Search results automatically respect user permissions and channel access. Private channels only appear for members, and deleted messages are excluded from results. Archive status reflects each user's individual settings.

## Best Practices

    **Designing effective search interactions**

    Make search easily discoverable in your chat interface, provide clear visual feedback during search operations, and ensure smooth navigation from search results to conversations. Consider adding search to your main navigation for quick access.

    **Displaying relevant information**

    The search component automatically provides context through message previews, timestamps, and sender information. Ensure your UI design gives adequate space for these details to help users identify the correct results.

    **Managing archived content**

    Search includes both active and archived channels with clear indicators. Plan how users will interact with archived results and ensure they understand archive status before accessing content.

## Related Features

    **Chat Management**
    Organize and navigate conversations
    **Multi-user Conversations**
    Create and manage group chats
    **Individual Messaging**
    One-on-one conversation features

**Implementation Strategy**: Start with AmitySearchChannelPage to provide immediate search capabilities across your chat application. The component integrates seamlessly with other chat features and requires minimal setup.

## UIKit — Social Components

### [Overview](https://learn.social.plus/uikit/components/social/overview)

> Complete guide to social.plus UIKit social components for building community experiences

social.plus UIKit provides a comprehensive suite of social components for building modern community experiences. These components are designed to work seamlessly across all platforms with rich content creation, social discovery, and community management functionality.

    Ephemeral content with 24-hour expiration
    TikTok-style short-form video content
    Real-time video broadcasting and viewing
    Dynamic content discovery and feeds
    Community creation and management
    Content safety and moderation tools

## Key Features

    - Rich multimedia posts with media attachments
    - Ephemeral stories with 24-hour expiration
    - Short-form video clips with editing tools
    - Live streaming with real-time broadcasting
    - Poll creation and interactive content

    - Personalized social feeds with engagement
    - TikTok-style vertical video feeds
    - Story rings and ephemeral content discovery
    - Advanced search and content categorization
    - Trending content and algorithmic recommendations

    - Community creation and management
    - Role-based permissions and moderation
    - Member engagement and relationship management
    - User profiles and follow systems
    - Community-specific content targeting

    - Structured content reporting with categories
    - Administrative moderation dashboard
    - Real-time content filtering and safety controls
    - Community guidelines enforcement
    - User blocking and privacy controls

## Platform Support

All social components are available across platforms with platform-specific optimizations:

    **iOS & Android**
    - Native performance and camera integration
    - Platform-specific UI patterns and gestures
    - Real-time streaming and media optimization
    - Push notification and background sync
    **React Web & Cross-Platform**
    - Progressive Web App support
    - Responsive design for all screen sizes
    - WebRTC integration for streaming
    - Service worker for offline content

## Getting Started

### Basic Implementation

    Set up the social client with your social.plus credentials
    Select the social components that fit your community needs
    Apply your brand colors and styling preferences
    Enable or disable specific social features and moderation


## Performance Optimizations

    Efficiently load social feeds with infinite scroll
    Automatic compression for stories and clips
    Optimized live updates for feeds and streams
    Smart caching for offline content access

### Best Practices

    - Implement pagination for social feeds
    - Use lazy loading for media content
    - Cache frequently accessed content locally
    - Preload next content for smooth scrolling

    - Use WebSocket connections efficiently for live features
    - Implement proper reconnection logic for streams
    - Handle connection state changes gracefully
    - Optimize live chat and reaction updates

    - Show loading states and progress indicators
    - Implement smooth animations and transitions
    - Handle errors gracefully with user feedback
    - Support accessibility and keyboard navigation

## Security Features

All social components include built-in security features to protect user content and prevent abuse.

    AI-powered content filtering and reporting
    Granular privacy settings and user controls
    Comprehensive moderation and safety tools
    Secure content storage and transmission

## Integration Examples

### Social Media App

For consumer social applications:

1. **Story Creation** - Rich multimedia story sharing
2. **Social Feeds** - Personalized content discovery
3. **Community Features** - Interest-based communities

### Community Platform

For brand or interest communities:

1. **Community Management** - Branded community spaces
2. **Content Moderation** - Safety and guidelines enforcement
3. **Live Events** - Streaming and real-time engagement

### Creator Platform

For content creator applications:

1. **Clip Creation** - Short-form video tools
2. **Live Streaming** - Real-time broadcasting
3. **Audience Engagement** - Direct creator-fan interaction

## Next Steps

    Implement ephemeral content sharing
    Build short-form video experiences

    Add real-time video broadcasting
    Create community management features

---

### [Social Feeds & Content Discovery](https://learn.social.plus/uikit/components/social/feeds)

> Complete social home page experience with feeds, content creation, community discovery, and user engagement components

**Key Benefit**: Build comprehensive social experiences with pre-built components for content feeds, community discovery, post creation, and user engagement - all designed to work seamlessly together in a social home page.

## Components on this page

| Component | What it shows | Platforms |
| --- | --- | --- |
| [For You Feed](#for-you-feed) | Posts the backend personalized for the current user | React Web, iOS, Android |
| [Social Home Page](#social-home-page) | The container that hosts the feed tabs, creation menu, and discovery | All |
| [Newsfeed](#newsfeed-component) | Stories plus the global post list | All |
| [Global Feed](#global-feed-component) | Aggregated community posts, newest first (chronological only) | All |
| [Empty Newsfeed](#empty-newsfeed-component) | The first-run state, with prompts to post or join a community | All |
| [Create Post Menu](#create-post-menu-component) | The entry point for posts, stories, polls, and live streams | All |
| [Community Discovery](#community-discovery) | Categories, recommended, and trending communities | All |

## For You Feed

As a community grows, the posts worth a member's attention get buried by volume. The **For You** tab surfaces the posts each member is most likely to care about, so the home experience stays relevant and worth returning to — without you building any ranking logic yourself.

For You is a backend-personalized feed that appears as a tab on the social home page. It is a **network-level setting** — the tab only shows when the network has For You feed enabled and the current user is not a visitor or bot. When the setting is off (or the feed reports that it is disabled), the UIKit hides the tab and falls back to the newsfeed automatically.

**Platform Support**: For You feed is available on the **React Web, iOS, and Android** UIKit. It is not available on Flutter or React Native.

### What the For You feed includes

The backend assembles For You from these content sources, then ranks them for the current user:

| Source | What it contributes |
| --- | --- |
| Joined communities | Posts from communities the user is a member of |
| Public communities | Posts from public communities the user has **not** joined |
| Followed users | Posts from the user feeds the user follows |
| Public user feeds | Posts from user feeds that are public |
| Exploration | A small amount of random posts, for controlled discovery |
| Livestreams | Ongoing livestreams, injected while they are live |

Ranking, and the mix between these sources, is owned by the backend. There are no client-side knobs in the UIKit or SDK to weight or filter them. For network-level tuning, contact [social.plus Support](https://ekoapp.atlassian.net/servicedesk/customer/portal/3).

### How ranking works

The backend ranks each post for the current user by blending four signals — **relevance** (what the user has engaged with before), **affinity** (authors and communities they're connected to), **popularity** (engagement across the network), and **freshness** (how recently it was posted) — then spaces out repetitive authors, communities, and topics so the feed stays varied. New users start with a popularity- and freshness-led feed that personalizes as they engage. The UIKit renders the ranked result as-is; the exact scoring model is backend-owned and not exposed. See [How ranking works](/social-plus-sdk/social/discovery-engagement/feed/for-you-feed#how-ranking-works) for the full behavior.

The UIKit also reports post views for you, so the feed automatically skips posts the member has already seen — on any surface — without extra wiring.

**Transparency.** For You is a personalized recommender. Where recommender-system transparency rules apply (such as the EU Digital Services Act), disclose the four signals above to your users in plain language and offer the non-personalized **Newsfeed** as the alternative they can switch to at any time — the tab switch is that control.

### How the tab is gated

The social home page reads the network setting and the feed collection, then derives whether to show the For You tab:

1. `useForYouFeedSetting()` reads `forYouFeed.enabled` for the network (skipped for visitors/bots).
2. `useForYouFeedCollection()` observes the personalized posts once the setting is enabled.
3. The tab is shown only when the setting is enabled **and** the collection did not fail with a feed-disabled error. If the feed becomes unavailable while the tab is active, the page switches back to the newsfeed.

### Render the feed

`AmitySocialHomePage` wires the For You tab for you — enable For You feed on your network and it appears automatically. To embed the feed on its own, render the `ForYouFeed` component with a `pageId`:

```tsx React
import { ForYouFeed } from '@amityco/ui-kit';

function ForYouTab() {
  return <ForYouFeed pageId="social_home_page" />;
}
```

```swift iOS
AmityForYouFeedComponent()
```

```kotlin Android
@Composable
fun composeForYouFeedComponent() {
    AmityForYouFeedComponent()
}
```

### Hooks

| Hook | Returns | Use for |
| --- | --- | --- |
| `useForYouFeedSetting({ shouldCall })` | `{ forYouFeedSetting, isPending, error }` | Decide whether to render a For You entry point. Pass `shouldCall: !isVisitorOrBot`. |
| `useForYouFeedCollection({ shouldCall })` | `{ posts, isLoading, hasMore, loadMore, error, refresh, isLoadingFirstPage }` | Render the personalized post list and paginate it. Gate `shouldCall` on the enabled setting. |

Both hooks and the `ForYouFeed` component are backed by the SDK's `FeedRepository.getForYouFeed()` and `Client.getForYouFeedSetting()`. See [For You Feed](/social-plus-sdk/social/discovery-engagement/feed/for-you-feed) for the SDK-level behavior.

## Social Home Page

**Complete social home experience**

The AmitySocialHomePage serves as the central hub integrating multiple social components for a comprehensive user experience.

### Features

| Feature                | Description                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Global Feed Navigation | Navigate through different segments like newsfeed, explore, my communities                                              |
| Newsfeed Viewing       | Displays recent posts, updates, and activities from connections and followed communities                                 |
| Community Access       | Quick access to user communities with options to join more                                                              |
| Engagement Options     | Like, comment, and interact with posts directly from the page                                                           |

### Customization Options

| Config ID | Type | Description |
|-----------|------|-------------|
| `social_home_page/*/*` | Page | Customize page theme |
| `social_home_page/*/newsfeed_button` | Element | Customize text |
| `social_home_page/*/explore_button` | Element | Customize text |
| `social_home_page/*/my_communities_button` | Element | Customize text |

### Code Examples

```swift iOS
let socialHomePage = AmitySocialHomePage()
let viewController = AmitySwiftUIHostingController(rootView: socialHomePage)
```

```kotlin Android
@Composable
fun composeSocialHomePage() {
    AmitySocialHomePage()
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmitySocialHomePage } from '@amityco/ui-kit';

const SampleSocialHomePage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmitySocialHomePage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmitySocialHomePage, AmityUiKitProvider } from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmitySocialHomePage />
</AmityUiKitProvider>
```

```dart Flutter
Widget socialHomePage() {
  return AmitySocialHomePage();
}
```

**Navigation Customization**: Custom navigation behavior can be implemented to enhance interaction flow, including overriding default actions for global search or community search.

### Navigation Behavior

Custom navigation behavior can be implemented to enhance or modify the interaction flow on the AmitySocialHomePage.

```swift iOS
class CustomAmitySocialHomePageBehavior: AmitySocialHomePageBehavior {
    override init() {
        super.init()
    }

    override func goToGlobalSearch(context: AmitySocialHomePageBehavior.Context) {
        // Custom implementation for navigating to Global Search
    }

    override func goToCommunitySearch(context: AmitySocialHomePageBehavior.Context) {
        // Custom implementation for navigating to Community Search
    }
}

// Call this function to setup custom behaviour class in UIKit
func setSocialHomePageBehaviour() {
    let customBehavior = CustomAmitySocialHomePageBehavior()
    AmityUIKit4Manager.behaviour.socialHomePageBehavior = customBehavior
}
```

```kotlin Android
class CustomSocialHomePageBehavior : AmitySocialHomePageBehavior() {
    override fun goToGlobalSearch(context: Context) {
        // custom implementation for navigating to Global Search
    }

    override fun goToCommunitySearch(context: Context) {
        // custom implementation for navigating to Community Search
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehavior = CustomSocialHomePageBehavior()
    AmityUIKit4Manager.behavior.socialHomePageBehavior = customBehavior
}
```

```typescript React
import { AmityUIKitProvider, AmitySocialHomePage } from '@amityco/ui-kit';

const SampleSocialHomePage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmitySocialHomePageBehavior: {
          goToGlobalSearch: () => {
            // Navigate to global search page
          },
          goToCommunitySearch: () => {
            // Navigate to community search page
          },
        },
      }}
    >
      <AmitySocialHomePage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmitySocialHomePage, AmityUiKitProvider } from '@amityco/react-native-social-uikit';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmitySocialHomePageBehavior: {
      goToGlobalSearch: () => {
        // Navigate to global search page
      },
      goToCommunitySearch: () => {
        // Navigate to community search page
      },
    },
  }}
>
  <AmitySocialHomePage />
</AmityUiKitProvider>
```

## Feed Components

**Newsfeed and content display**

Components for displaying and managing social content feeds with stories and posts.

### Newsfeed Component

Integrates story display and global feed for a complete social feed experience.

| Feature            | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| Story Display      | Highlights user stories at the top, making them immediately accessible                   |
| Post List          | Displays recent posts, updates, and activities from connections and communities          |
| Engagement Options | Users can like, comment, and interact with posts directly                               |

```swift iOS
let newsfeedComponent = AmityNewsFeedComponent()
let viewController = AmitySwiftUIHostingController(rootView: newsfeedComponent)
```

```kotlin Android
@Composable
fun composeNewsFeedComponent() {
    AmityNewsFeedComponent()
}
```

```dart Flutter
Widget newsFeedComponent() {
  return AmityNewsFeedComponent();
}
```

### Global Feed Component

Central component for aggregating and displaying diverse community posts, newest first.

The component renders the SDK's chronological global feed, which shows at most the 20 most recent posts per user or community. See [Global Feed](/social-plus-sdk/social/discovery-engagement/feed/global-feed) for the SDK-level behavior and query parameters.

**Custom ranking is not available in the UIKit** on any platform, only in the SDK — see the [Feature Matrix](/feature-matrix). `AmityGlobalFeedComponent` always renders the chronological feed. To ship an engagement-ranked feed, query [`getCustomRankingGlobalFeed()`](/social-plus-sdk/social/discovery-engagement/feed/custom-ranking) directly and render the results with your own list.

```swift iOS
let globalFeedComponent = AmityGlobalFeedComponent()
let viewController = AmitySwiftUIHostingController(rootView: globalFeedComponent)
```

```kotlin Android
@Composable
fun composeGlobalFeedComponent() {
    AmityGlobalFeedComponent()
}
```

```typescript React
import { AmityUIKitProvider, AmityGlobalFeedComponent } from '@amityco/ui-kit';

const SampleGlobalFeed = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityGlobalFeedComponentBehavior: {
          goToPostDetailPage: ({ postId }) => {
            console.log('goToPostDetailPage', postId);
          },
          goToViewStoryPage: () => {},
        },
      }}
    >
      <AmityGlobalFeedComponent
        isLoading={false}
        items={[]}
        onFeedReachBottom={() => {}}
        onPostDeleted={() => {}}
      />
    </AmityUIKitProvider>
  );
};
```

```dart Flutter
Widget globalFeedComponent() {
  return AmityGlobalFeedComponent();
}
```

### Empty Newsfeed Component

Handles empty states with engaging placeholders and call-to-action buttons.

```swift iOS
let emptyNewsFeedComponent = AmityEmptyNewsFeedComponent()
let viewController = AmitySwiftUIHostingController(rootView: emptyNewsFeedComponent)
```

```kotlin Android
@Composable
fun composeEmptyNewsFeedComponent() {
    AmityEmptyNewsFeedComponent()
}
```

```typescript React
import { AmityUIKitProvider, AmityEmptyNewsFeedComponent } from '@amityco/ui-kit';

const SampleEmptyNewsFeed = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityEmptyNewsFeedComponent />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmityEmptyNewsFeedComponent, AmityUiKitProvider } from '@amityco/react-native-social-uikit';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityEmptyNewsFeedComponent />
</AmityUiKitProvider>
```

```dart Flutter
Widget emptyNewsfeedComponent() {
  return AmityEmptyNewsFeedComponent();
}
```

### Navigation Behavior

The behavior of the AmityGlobalFeedComponent can be customized to handle navigation to the post detail page differently.

```swift iOS
class CustomAmityGlobalFeedComponentBehavior: AmityGlobalFeedComponentBehavior {
    override init() {
        super.init()
    }

    override func goToPostDetailPage(context: AmityGlobalFeedComponentBehavior.Context) {
        // Custom implementation for navigating to Post Detail Page
    }
}

// Call this function to setup custom behaviour class in UIKit
func setGlobalFeedComponentBehaviour() {
    let customBehavior = CustomAmityGlobalFeedComponentBehavior()
    AmityUIKit4Manager.behaviour.globalFeedComponentBehavior = customBehavior
}
```

```kotlin Android
class CustomGlobalFeedComponentBehavior : AmityGlobalFeedComponentBehavior() {
    override fun goToPostDetailPage(context: Context, id: String, category: AmityPostCategory) {
        // custom implementation for navigating to Post Detail Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehavior = CustomGlobalFeedComponentBehavior()
    AmityUIKit4Manager.behavior.globalFeedComponentBehavior = customBehavior
}
```

```typescript React
import { AmityUIKitProvider, AmityGlobalFeedComponent } from '@amityco/ui-kit';

const SampleGlobalFeed = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityGlobalFeedComponentBehavior: {
          goToPostDetailPage: ({ postId }) => {
            console.log('goToPostDetailPage', postId);
          },
          goToViewStoryPage: () => {},
        },
      }}
    >
      <AmityGlobalFeedComponent
        isLoading={false}
        items={[]}
        onFeedReachBottom={() => {}}
        onPostDeleted={() => {}}
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmityGlobalFeedComponent, AmityUiKitProvider } from '@amityco/react-native-social-uikit';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmityGlobalFeedComponentBehavior: {
      goToPostDetailPage: (postId: string) => {
        console.log(postId);
      },
    },
  }}
>
  <AmityGlobalFeedComponent />
</AmityUiKitProvider>
```

## Content Creation

**Post and story creation tools**

Components for enabling users to create posts, stories, and other content types.

### Create Post Menu Component

Provides users with options to create various types of content.

### Features

| Feature      | Description                                                                                                                |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Create Post  | Navigate to post creation with target selection                                                                           |
| Create Story | Direct users to story target selection for audience customization                                                         |
| Create Poll  | Enable poll creation functionality                                                                                         |
| Create Livestream | Support for livestream content creation                                                                                   |

### Customization Options

| Config ID | Type | Description |
|-----------|------|-------------|
| `social_home_page/create_post_menu/*` | Component | Customize component theme |
| `social_home_page/create_post_menu/create_post_button` | Element | Customize text and image |
| `social_home_page/create_post_menu/create_story_button` | Element | Customize text and image |
| `social_home_page/create_post_menu/create_poll_button` | Element | Customize text and image |
| `social_home_page/create_post_menu/create_livestream_button` | Element | Customize text and image |

### Code Examples

```swift iOS
let createPostMenuComponent = AmityCreatePostMenuComponent()
let viewController = AmitySwiftUIHostingController(rootView: createPostMenuComponent)
```

```kotlin Android
@Composable
fun composeCreatePostMenuComponent() {
    AmityCreatePostMenuComponent()
}
```

```typescript React
import { AmityUIKitProvider, AmityCreatePostMenuComponent } from '@amityco/ui-kit';

const SampleCreatePostMenu = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityCreatePostMenuComponentBehavior: {
          goToSelectPostTargetPage: () => {},
          goToStoryTargetSelectionPage: () => {},
        },
      }}
    >
      <AmityCreatePostMenuComponent />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmityCreatePostMenuComponent, AmityUiKitProvider } from '@amityco/react-native-social-uikit';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmityCreatePostMenuComponentBehavior: {
      goToSelectStoryTargetPage: () => {},
      goToSelectPostTargetPage: ({ postType }) => console.log(postType),
    },
  }}
>
  <AmityCreatePostMenuComponent />
</AmityUiKitProvider>
```

**Navigation Behavior**: The component behavior can be customized to manage navigation flow for post and story creation aligned with your application's user experience.

### Navigation Behavior

The behavior of the AmityCreatePostMenuComponent can be customized to manage how the application navigates upon user actions related to post and story creation.

```swift iOS
class CustomAmityCreatePostMenuComponentBehavior: AmityCreatePostMenuComponentBehavior {
    override init() {
        super.init()
    }

    override func goToSelectPostTargetPage(context: AmityCreatePostMenuComponentBehavior.Context) {
        // Custom implementation for navigating to Select Post Target Page
    }

    override func goToSelectStoryTargetPage(context: AmityCreatePostMenuComponentBehavior.Context) {
        // Custom implementation for navigating to Select Story Target Page
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCreatePostMenuComponentBehaviour() {
    let customBehavior = CustomAmityCreatePostMenuComponentBehavior()
    AmityUIKit4Manager.behaviour.createPostMenuComponentBehavior = customBehavior
}
```

```kotlin Android
class CustomCreatePostMenuComponentBehavior : AmityCreatePostMenuComponentBehavior() {
    override fun goToSelectPostTargetPage(
        context: Context,
        type: AmityPostTargetSelectionPageType
    ) {
        // custom implementation for navigating to Post Target Selection Page
    }

    override fun goToSelectStoryTargetPage(context: Context) {
        // custom implementation for navigating to Story Target Selection Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCreatePostMenuComponentBehavior()
    AmityUIKit4Manager.behavior.createPostMenuComponentBehavior = customBehaviour
}
```

```typescript React
import { AmityUIKitProvider, AmityCreatePostMenuComponent } from '@amityco/ui-kit';

const SampleCreatePostMenu = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityCreatePostMenuComponentBehavior: {
          goToSelectPostTargetPage: () => {
            // Navigate to post target selection
          },
          goToStoryTargetSelectionPage: () => {
            // Navigate to story target selection
          },
        },
      }}
    >
      <AmityCreatePostMenuComponent />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import { AmityCreatePostMenuComponent, AmityUiKitProvider } from '@amityco/react-native-social-uikit';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmityCreatePostMenuComponentBehavior: {
      goToSelectStoryTargetPage: () => {
        // Navigate to story target selection
      },
      goToSelectPostTargetPage: ({ postType }) => {
        console.log(postType);
        // Navigate to post target selection
      },
    },
  }}
>
  <AmityCreatePostMenuComponent />
</AmityUiKitProvider>
```

## Community Discovery

**Explore and discover communities**

Components for helping users find and engage with communities through categories and recommendations.

### Community Categories Component

Displays five categories in a horizontally scrollable view with explore options.

| Feature      | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| Categories   | Highlights 5 categories making them immediately accessible |
| See More Tab | Allows users to view all categories in a separate page     |

```swift iOS
let categoriesComponent = AmityCommunityCategoriesComponent()
let viewController = AmitySwiftUIHostingController(rootView: categoriesComponent)
```

```kotlin Android
@Composable
fun composeCommunityCategoriesComponent() {
    AmityCommunityCategoriesComponent()
}
```

### Recommended Communities Component

Shows top four recommended communities for users to join.

```swift iOS
let recommendedComponent = AmityRecommendedCommunitiesComponent()
let viewController = AmitySwiftUIHostingController(rootView: recommendedComponent)
```

```kotlin Android
@Composable
fun composeRecommendedCommunitiesComponent() {
    AmityRecommendedCommunitiesComponent()
}
```

### Trending Communities Component

Showcases the top five trending communities for user interaction.

```swift iOS
let trendingComponent = AmityTrendingCommunitiesComponent()
let viewController = AmitySwiftUIHostingController(rootView: trendingComponent)
```

```kotlin Android
@Composable
fun composeTrendingCommunitiesComponent() {
    AmityTrendingCommunitiesComponent()
}
```

### Customization Options

| Component | Config ID | Type | Description |
|-----------|-----------|------|-------------|
| Categories | `social_home_page/community_categories/*` | Component | Customize component theme |
| Recommended | `social_home_page/recommended_communities/*` | Component | Customize component theme |
| Trending | `social_home_page/trending_communities/*` | Component | Customize component theme |

## Best practices

    Plan the layout by combining feed components, content creation tools, and community discovery. Consider the user flow from content consumption to creation and community engagement, and where the For You tab sits relative to the newsfeed.

    Position the create post menu so it encourages user-generated content without competing with content discovery. Community categories, recommendations, and trending displays give users several routes into communities.

    Keep a clear visual hierarchy between content types, smooth transitions between components, and consistent navigation across social features. Design mobile-first.

    The SDK handles data fetching and pagination, so focus on UI responsiveness: efficient list rendering, optimized media display, and stable scroll positions when new pages load.

    Match themes, colors, and component behavior to your design system. Adjust styling per context — creation surfaces and consumption surfaces deserve different emphasis.

## Related Features

    **Search & Discovery**
    Global search, categories, and notification components
    **Content Creation**
    Post creation and management components
    **Community Features**
    Community creation and administration tools

**Implementation Strategy**: Start with AmitySocialHomePage for a complete experience, then customize individual components (newsfeed, create post menu, community discovery) based on your specific user engagement goals and brand requirements.

---

### [Post Components](https://learn.social.plus/uikit/components/social/posts)

> Comprehensive post creation, editing, and content management components for rich social interactions

**Key Benefit**: Enable rich content creation and engagement with comprehensive post components supporting text, media, polls, mentions, link previews, and advanced accessibility features across all platforms.

## Feature Overview

The Post Components UIKit provides a complete suite of tools for post creation, editing, and content management. From rich media posts and interactive polls to advanced features like @mentions, link previews, and accessibility support, these components create the foundation for engaging social content experiences.

    Create rich content with text, images, and videos. Support for **optional titles**, **mentions**, **hashtags**, and multiple attachments.

    Engage users with text or **image-based polls**. Users can **change/remove votes** with customizable duration and multiple selections.

    Real-time **livestreaming** with interactive chat and reactions, available in Livestreaming post in a community.

    **Inline comments**, reactions, @mentions, and real-time interaction tracking for active discussions.

    **Shareable deep links**, link previews, hashtags, and **gallery-to-post linking** for better content discovery.

    Post editing, content moderation tools, and comprehensive management for all post types.

## Platform Support

| Feature | iOS | Android | React | React Native | Flutter |
| --- | --- | --- | --- | --- | --- |
| Create Text, Image, Video Post | ✅ | ✅ | ✅ | ✅ | ✅ |
| Edit Text, Image, Video Post | ✅ | ✅ | ✅ | ✅ | ✅ |
| Media Carousel (multiple images/videos) | ✅ | ✅ | ✅ | ✅ | ❌ |
| Create Livestream Post | ✅ | ✅ | ❌ | ✅ | ❌ |
| Community Livestream with chat and reaction | ✅ | ✅ | ✅ | ❌ | ❌ |
| Create Poll Post | ✅ | ✅ | ✅ | ❌ | ✅ |
| Create Image Poll Post | ✅ | ✅ | ✅ | ❌ | ❌ |
| Update Poll Answer | ✅ | ✅ | ✅ | ❌ | ❌ |
| Report Post | ✅ | ✅ | ✅ | ✅ | ✅ |
| Comments & Reactions | ✅ | ✅ | ✅ | ✅ | ✅ |
| Recent Comment preview | ✅ | ✅ | ✅ | ❌ | ❌ |
| Mention | ✅ | ✅ | ✅ | ✅ | ✅ |
| Link Preview | ✅ | ✅ | ✅ | ✅ | ✅ |
| Brand User Post | ✅ | ✅ | ✅ | ❌ | ✅ |
| (Optional) Post title | ✅ | ✅ | ✅ | ❌ | ❌ |
| Hashtag | ✅ | ✅ | ✅ | ❌ | ❌ |
| Sharable Links | ✅ | ✅ | ✅ | ❌ | ❌ |
| Ads | ✅ | ✅ | ✅ | ✅ | ❌ |
| Alt text for Image Post | ✅ | ✅ | ✅ | ❌ | ❌ |
| Url Preview Removal | ✅ | ✅ | ✅ | ❌ | ❌ |
| Product Mentions in Text | ✅ | ✅ | ✅ | ❌ | ❌ |
| Product Tags on Media | ✅ | ✅ | ✅ | ❌ | ❌ |
| Product Carousel Display | ✅ | ✅ | ✅ | ❌ | ❌ |
| Edit Product Tags | ✅ | ✅ | ✅ | ❌ | ❌ |

**Legend**: ✅ Full Support | ❌ Not Available

## Post Types & Features

    **Supported Content Types**

    - **Text Posts**: Rich text content with optional post titles and free-form hashtags for better discoverability
    - **Rich Media Posts**: Images and videos with enhanced display, alt text support, and a swipeable carousel for posts with multiple attachments
    - **Livestream Posts**: Livestreaming with interactive chat and reactions
    - **Poll Posts**: Interactive polls with voting and real-time results
      - Text-only polls with multiple choice options
      - Image polls with visual voting options (supported on iOS, Android, React)
      - Vote management - users can change or remove their poll votes

    **User Interaction Capabilities**

    - **Reactions**: Multiple sentiment expressions
    - **Inline Comments**: Threaded conversations displayed directly under posts on feeds for improved engagement
    - **Mentions**: @username functionality with notifications and user discovery
    - **Sharing**: Content distribution with shareable deep links for posts
    - **Poll Voting**: Interactive voting with the ability to change or remove votes before poll closes

    **Enhanced Functionality**

    - **Post Titles**: Optional titles for better post organization and context
    - **Free-form Hashtags**: Add hashtags anywhere in post content for improved content discovery and categorization
    - **Shareable Deep Links**: Generate and share direct links to specific posts for seamless navigation
    - **Link Preview**: Automatic metadata extraction and display for URLs shared in posts
    - **Link Highlighting**: Detect links using `AmityLink.index` and `AmityLink.length`, highlight matching text, and open `link.url` on tap
    - **Gallery-to-Post Linking**: Community gallery media is linked to original posts, providing full context when viewing images
    - **Brand User**: Professional/admin posting capabilities with enhanced visibility
    - **Accessibility**: Comprehensive alt text support for images ensuring inclusive content
    - **Moderation**: Content reporting and management for community safety

    **Commerce Integration & Product Discovery**

    - **Text Product Mentions**: Tag products in post captions using `@` trigger with product suggestion overlay for easy discovery
    - **Media Product Tags**: Tag products directly on images and videos with coordinate-based positioning to highlight specific items
    - **Product Search**: Real-time product search for quick product discovery
    - **Multi-select Support**: Select multiple products per post (maximum 20 products combined across text and media)
    - **Product Carousel Display**: View all tagged products in a scrollable carousel below post content
    - **Product Links**: Tap products to open in in-app browser without interrupting social experience
    - **Edit Product Tags**: Add, remove, or modify product tags on existing posts while maintaining engagement metrics
    - **Per-Media Limits**: Support per-media tagging with individual product limits (max 5 products per media item)
    - **Product Tag Indicator**: Visual indicator on media thumbnails showing count of tagged products
    - **Context-Aware Headers**: Different labels for product display based on content type (post vs image/video)

## Implementation Guide

    **Complete post viewing experience**

    The Post Detail Page displays comprehensive post information, including content, engagements, and comments.

    ### Features

    | Feature | Description |
    | --- | --- |
    | Engagement Options | Users can like, comment, and interact with posts directly from this page |
    | Content Display | Full post content with media, polls, and interactive elements |
    | Comment Integration | Integrated comment tray for discussions |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `post_detail_page/*/*` | Theme | You can customize page theme |
    | `post_detail_page/*/back_button` | Element | You can update back button icon |
    | `post_detail_page/*/menu_button` | Element | You can update menu button icon |

    ### Code Examples


```swift iOS
let postDetailPage = AmityPostDetailPage(id: "<post-id>")
let viewController = AmitySwiftUIHostingController(rootView: postDetailPage)
```

```kotlin Android
@Composable
fun composePostDetailPage(postId: String) {
    AmityPostDetailPage(
        id = postId,
        style = AmityPostContentComponentStyle.DETAIL,
        hideTarget = false,
    )
}

fun startAnActivity(context: Context, postId: String) {
    val intent = AmityPostDetailPageActivity.newIntent(
        context = context,
        id = postId,
    )
    context.startActivity(intent)
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPostDetailPage } from '@amityco/ui-kit';

const SampleAmityPostDetailPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityPostDetailPage
        id="post-id"
        hideTarget={false}
        category="post"
        commentId="comment-id"
        parentId="parent-id"
      />
    </AmityUiKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostDetailPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityPostDetailPage postId="7297262927392" />
</AmityUiKitProvider>
```

```dart Flutter
Widget postDetailPageWidget() {
  return AmityPostDetailPage(
    postId: 'post-id',
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomAmityPostDetailPageBehavior: AmityPostDetailPageBehavior {
    override init() {
        super.init()
    }
}

// Call this function to setup custom behaviour class in UIKit
func setPostDetailPageBehaviour() {
    let customBehavior = CustomAmityPostDetailPageBehavior()
    AmityUIKit4Manager.behaviour.postDetailPageBehavior = customBehavior
}
```

```kotlin Android
class CustomPostDetailPageBehaviour : AmityPostDetailPageBehavior() {

}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomPostDetailPageBehaviour()
    AmityUIKit4Manager.behavior.postDetailPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostDetailPage } from '@amityco/ui-kit';

const SampleAmityPostDetailPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityPostDetailPage id="post-id" />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostDetailPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityPostDetailPage postId="7297262927392" />
</AmityUiKitProvider>
```

    **Flexible post display component**

    The Post Content Component displays post information including content and engagements in a reusable format.

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `*/post_content/*` | Theme | You can customize component theme |
    | `*/post_content/moderator_badge` | Element | You can change icon and wording of Moderator Badge |
    | `*/post_content/timestamp` | Element | You can hide timestamp |
    | `*/post_content/menu_button` | Element | You can change icon of menu button |
    | `*/post_content/reaction_button` | Element | You can change reaction button icon and wording |
    | `*/post_content/comment_button` | Element | You can change comment button icon and wording |
    | `*/post_content/share_button` | Element | You can change share button icon and wording |

    ### Code Examples


```swift iOS
let postContentComponent = AmityPostContentComponent(
    post: post,
    style: .feed,
    hideMenuButton: false,
    onTapAction: { _ in
        // Action called when Post Content area is tapped
    }
)
let viewController = AmitySwiftUIHostingController(rootView: postContentComponent)
```

```kotlin Android
@Composable
fun composePostContentComponent(
    post: AmityPost,
    style: AmityPostContentComponentStyle,
    hideMenuButton: Boolean,
) {
    AmityPostContentComponent(
        post = post,
        style = style,
        hideMenuButton = hideMenuButton,
        onTapAction = {}
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostContentComponent } from '@amityco/ui-kit';

const SampleAmityPostContentComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityGlobalFeedComponentBehavior: {
          goToPostDetailPage: ({ postId }) => {
            console.log('goToPostDetailPage', postId);
          },
          goToViewStoryPage: () => {},
        },
      }}
    >
      <AmityPostContentComponent
        post={post}
        type="feed"
        onClick={() => {}}
        onPostDeleted={() => {}}
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostContentComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityPostContentComponent post={{} as Amity.Post} />
</AmityUiKitProvider>
```

```dart Flutter
Widget postContentComponentWidget() {
  return AmityPostContentComponent(
    post: post,
    style: AmityPostContentComponentStyle.feed,
  );
}
```


    ### Link Preview Behavior

        If multiple links have `renderPreview = true`, UIKit shows the preview card for the link with the lowest `index` value.

        If the post has no `links` field but a URL is still detected in the text, UIKit can fall back to `getLinkPreviewMetadata` and render a preview from the extracted metadata.

        Preview cards display the title at the top and the domain at the bottom. If `title` is missing, UIKit uses `domain` as the title. If `imageUrl` is missing, the image section is hidden.

        Tapping either highlighted link text or the preview card opens `link.url`.

    ### Navigation Behavior


```swift iOS
class CustomAmityPostContentComponentBehavior: AmityPostContentComponentBehavior {
    override init() {
        super.init()
    }

    override func goToUserProfilePage(context: AmityPostContentComponentBehavior.Context) {
        // Custom implementation for navigatin to User Profile Page
    }

    override func goToCommunityProfilePage(context: AmityPostContentComponentBehavior.Context) {
        // Custom implementation for navigatin to Community Profile Page
    }
}

// Call this function to setup custom behaviour class in UIKit
func setPostContentComponentBehaviour() {
    let customBehavior = CustomAmityPostContentComponentBehavior()
    AmityUIKit4Manager.behaviour.postContentComponentBehavior = customBehavior
}
```

```kotlin Android
class CustomPostContentComponentBehaviour : AmityPostContentComponentBehavior() {
    override fun goToCommunityProfilePage(context: Context, community: AmityCommunity) {
        // custom implementation for navigating to Community Profile Page
    }

    override fun goToUserProfilePage(context: Context, userId: String) {
        // custom implementation for navigating to User Profile Page
    }

    override fun goToPostComposerPage(context: Context, post: AmityPost) {
        // custom implementation for navigating to Post Composer Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomPostContentComponentBehaviour()
    AmityUIKit4Manager.behavior.postContentComponentBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostContentComponent } from '@amityco/ui-kit';

const SampleAmityPostContentComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityGlobalFeedComponentBehavior: {
          goToPostDetailPage: ({ postId }) => {
            console.log('goToPostDetailPage', postId);
          },
          goToViewStoryPage: () => {},
        },
      }}
    >
      <AmityPostContentComponent
        post={post}
        type="feed"
        onClick={() => {}}
        onPostDeleted={() => {}}
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
class CustomPostContentComponentBehaviour : AmityPostContentComponentBehavior() {
    override fun goToCommunityProfilePage(context: Context, community: AmityCommunity) {
        // custom implementation for navigating to Community Profile Page
    }

    override fun goToUserProfilePage(context: Context, userId: String) {
        // custom implementation for navigating to User Profile Page
    }

    override fun goToPostComposerPage(context: Context, post: AmityPost) {
        // custom implementation for navigating to Post Composer Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomPostContentComponentBehaviour()
    AmityUIKit4Manager.behavior.postContentComponentBehavior = customBehaviour
}
```

    **Create and edit posts**

    The Post Composer Page enables users to create and edit posts with text content, media attachments, and rich features.

    ### Features

    | Feature | Description |
    | --- | --- |
    | Post Composition | Create posts with text content, images, videos and files |
    | Post Editing | Edit existing posts using edit mode |
    | Media Integration | Uses AmityMediaAttachmentComponent and AmityDetailedMediaAttachmentComponent |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `post_composer_page/*/*` | Theme | You can customize page theme |
    | `post_composer_page/*/close_button` | Element | You can update close button icon |
    | `post_composer_page/*/community_display_name` | Element | You can hide community name on navigation bar |
    | `post_composer_page/*/create_new_post_button` | Element | You can change wording of post button on navigation bar |
    | `post_composer_page/*/edit_post_button` | Element | You can change wording of save button on navigation bar if this page is used as edit mode |
    | `post_composer_page/*/edit_post_title` | Element | You can change navigation title appeared in the edit mode |

    ### Code Examples


```swift iOS
// Create Option to use AmityPostComposerPage to create post
let createOption = AmityPostComposerOptions.createOptions(
    mode: .create,
    targetId: "<target-id>",
    targetType: .community,
    community: community
)
// Edit Option to use AmityPostComposerPage to edit existing post
let editOption = AmityPostComposerOptions.editOptions(mode: .edit, post: post)

let postComposerPage = AmityPostComposerPage(options: createOption)
let viewController = AmitySwiftUIHostingController(rootView: postComposerPage)
```

```kotlin Android
@Composable
fun composePostComposerPage(
    options: AmityPostComposerOptions
) {
    AmityPostComposerPage(
        options = options,
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostComposerPage } from '@amityco/ui-kit';

const SampleAmityPostComposerPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityPostComposerPageBehavior: {
          goToSocialHomePage: () => {},
        },
      }}
    >
      <AmityPostComposerPage
        mode="create"
        community={{} as Amity.Community}
        targetId="your-targetId"
        targetType="community"
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostComposerPage,
  AmityUiKitProvider,
  AmityPostComposerMode,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityPostComposerPage
    mode={AmityPostComposerMode.CREATE}
    community={{} as Amity.Community}
    targetId="9263297329"
    targetType="Community"
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget postComposerPageWidget() {
  // Create post composer options
  AmityPostComposerOptions createOptions =
      AmityPostComposerOptions.createOptions(
          targetType: AmityPostTargetType.COMMUNITY,
          targetId: 'targetId',
          community: community);

  // Edit post composer options
  AmityPostComposerOptions editOptions = AmityPostComposerOptions.editOptions(
    post: post,
  );

  return AmityPostComposerPage(options: createOptions);
}
```


    ### Navigation Behavior


```swift iOS
class CustomAmityPostComposerPageBehavior: AmityPostComposerPageBehavior {
    override init() {
        super.init()
    }
}

// Call this function to setup custom behaviour class in UIKit
func setPostComposerPageBehaviour() {
    let customBehavior = CustomAmityPostComposerPageBehavior()
    AmityUIKit4Manager.behaviour.postComposerPageBehavior = customBehavior
}
```

```kotlin Android
class CustomPostComposerPageBehavior : AmityPostComposerPageBehavior() {

}

fun setCustomBehavior() {
    val customBehaviour = CustomPostComposerPageBehavior()
    AmityUIKit4Manager.behavior.postComposerPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostComposerPage } from '@amityco/ui-kit';

const SampleAmityPostComposerPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityPostComposerPageBehavior: {
          goToSocialHomePage: () => {},
        },
      }}
    >
      <AmityPostComposerPage
        mode="create"
        community={{} as Amity.Community}
        targetId="your-targetId"
        targetType="community"
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostComposerPage,
  AmityUiKitProvider,
  AmityPostComposerMode,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityPostComposerPage
    mode={AmityPostComposerMode.CREATE}
    community={{} as Amity.Community}
    targetId="9263297329"
    targetType="Community"
  />
</AmityUiKitProvider>
```

    **Media upload and management**

    Components for adding media and files to posts during creation or editing.

    ### Media Attachment Component

    Compact media attachment interface for quick media addition.

    | Feature | Description |
    | --- | --- |
    | Attach media and files | Add images, videos, and files to posts |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `post_composer_page/media_attachment/*` | Theme | You can change component theme |
    | `post_composer_page/media_attachment/camera_button` | Element | You can change camera button icon |
    | `post_composer_page/media_attachment/image_button` | Element | You can change photo button icon |
    | `post_composer_page/media_attachment/video_button` | Element | You can change video button icon |
    | `post_composer_page/media_attachment/file_button` | Element | You can change attachment button icon |


```swift iOS
let viewModel = AmityMediaAttachmentViewModel()
let mediaAttachmentComponent = AmityMediaAttachmentComponent(viewModel: viewModel)
let viewController = AmitySwiftUIHostingController(rootView: mediaAttachmentComponent)
```

```kotlin Android
@Composable
fun composeMediaAttachmentComponent(
    viewModel: AmityMediaAttachmentViewModel,
) {
    AmityMediaAttachmentComponent(
        viewModel = viewModel
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityMediaAttachmentComponent } from '@amityco/ui-kit';

const SampleAmityMediaAttachmentComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityMediaAttachmentComponent
        uploadLoading={false}
        onChangeImages={() => {}}
        onChangeThumbnail={() => {}}
        videoThumbnail=""
        onChangeVideos={() => {}}
        isVisibleCamera={true}
        isVisibleImage={true}
        isVisibleVideo={true}
        totalMedia={0}
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityMediaAttachmentComponent,
  AmityUiKitProvider,
  mediaAttachment,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityMediaAttachmentComponent
    onPressCamera={() => {}}
    onPressImage={() => {}}
    onPressVideo={() => {}}
    chosenMediaType={mediaAttachment.image}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget mediaAttachmentComponentWidget() {
  return AmityMediaAttachmentComponent(
    onCameraTap: () {
      // Handle camera action
    },
    onImageTap: () {
      // Handle image action
    },
    onVideoTap: () {
      // Handle video action
    },
  );
}
```


    ### Detailed Media Attachment Component

    Enhanced media attachment interface with detailed options.

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `post_composer_page/detailed_media_attachment/*` | Theme | You can change component theme |
    | `post_composer_page/detailed_media_attachment/camera_button` | Element | You can change camera button icon and wording |
    | `post_composer_page/detailed_media_attachment/image_button` | Element | You can change photo button icon and wording |
    | `post_composer_page/detailed_media_attachment/video_button` | Element | You can change video button icon and wording |
    | `post_composer_page/detailed_media_attachment/file_button` | Element | You can change attachment button icon and wording |


```swift iOS
let viewModel = AmityMediaAttachmentViewModel()
let detailMediaAttachmentComponent = AmityDetailedMediaAttachmentComponent(viewModel: viewModel)
let viewController = AmitySwiftUIHostingController(rootView: detailMediaAttachmentComponent)
```

```kotlin Android
@Composable
fun composeDetailedMediaAttachmentComponent(
    viewModel: AmityMediaAttachmentViewModel,
) {
    AmityDetailedMediaAttachmentComponent(
        viewModel = viewModel
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityDetailedMediaAttachmentComponent } from '@amityco/ui-kit';

const SampleAmityDetailedMediaAttachmentComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityDetailedMediaAttachmentComponent
        uploadLoading={false}
        onChangeImages={() => {}}
        onChangeThumbnail={() => {}}
        videoThumbnail=""
        onChangeVideos={() => {}}
        isVisibleCamera={true}
        isVisibleImage={true}
        isVisibleVideo={true}
        totalMedia={0}
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityDetailedMediaAttachmentComponent,
  AmityUiKitProvider,
  mediaAttachment,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityDetailedMediaAttachmentComponent
    onPressCamera={() => {}}
    onPressImage={() => {}}
    onPressVideo={() => {}}
    chosenMediaType={mediaAttachment.image}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget detailedMediaAttachmentComponentWidget() {
  return AmityDetailedMediaAttachmentComponent(
    onCameraTap: () {
      // Handle camera action
    },
    onImageTap: () {
      // Handle image action
    },
    onVideoTap: () {
      // Handle video action
    },
  );
}
```

    **Interactive polling features**

    Components for creating and managing interactive polls with target audience selection.

    ### Poll Target Selection Page

    Streamlines the process of selecting target audience for polls.

    | Feature | Description |
    | --- | --- |
    | Post creation | Select a community or my timeline to create a poll post with the selected target |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `select_poll_target_page/*/*` | Page | You can customize page theme |
    | `select_poll_target_page/*/close_button` | Element | You can customize image |
    | `select_poll_target_page/*/title` | Element | You can customize text |
    | `select_poll_target_page/*/my_timeline_text` | Element | You can customize text |


```swift iOS
let postTargetSelectionPage = AmityPostTargetSelectionPage()
let viewController = AmitySwiftUIHostingController(rootView: postTargetSelectionPage)
```

```kotlin Android
@Composable
fun composePostTargetSelectionPage(
    type: AmityPostTargetSelectionPageType
) {
    AmityPostTargetSelectionPage(
        type = type,
    )
}

fun startAnActivity(context: Context) {
    val intent = AmityPostTargetSelectionPageActivity.newIntent(
        context = context,
        type = AmityPostTargetSelectionPageType.POST
    )
    context.startActivity(intent)
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostTargetSelectionPage } from '@amityco/ui-kit';

const SampleAmityPostTargetSelectionPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityPostTargetSelectionPage: {
          goToPostComposerPage: () => {},
        },
      }}
    >
      <AmityPostTargetSelectionPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostTargetSelectionPage,
  AmityUiKitProvider,
  AmityPostTargetSelectionPageType,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmityPostTargetSelectionPageBehavior: {
      goToPostComposerPage: () => {},
      goToLivestreamComposerPage: () => {},
      goToPollComposerPage: () => {},
    },
  }}
>
  <AmityPostTargetSelectionPage
    postType={AmityPostTargetSelectionPageType.post}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget postTargetSelctionPageWidget() {
  return AmityPostTargetSelectionPage();
}
```


    ### Poll Post Composer Page

    Enables users to create interactive polls with questions and multiple answer options. Supports both text-only polls and image polls with visual voting options.

    | Feature | Description |
    | --- | --- |
    | Post Composition | Create poll posts with text questions and text options |
    | Image Poll Support | Create image polls with visual voting options (iOS, Android, React) |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `poll_post_composer_page/*/*` | Theme | You can customize page theme |
    | `poll_post_composer_page/*/poll_question_tile` | Element | You can change wording of poll question title |
    | `poll_post_composer_page/*/poll_options_title` | Element | You can change wording of poll question title |
    | `poll_post_composer_page/*/poll_options_desc` | Element | You can change wording of poll options description |
    | `poll_post_composer_page/*/poll_add_option_button` | Element | You can change wording of add option button and its corresponding icon |
    | `poll_post_composer_page/*/poll_duration_title` | Element | You can change wording of poll duration title |
    | `poll_post_composer_page/*/poll_duration_desc` | Element | You can change wording of poll duration description |
    | `poll_post_composer_page/*/poll_multiple_selection_title` | Element | You can change wording of poll multiple selection title |
    | `poll_post_composer_page/*/poll_multiple_selection_desc` | Element | You can change wording of poll multiple selection description |


```swift iOS
let pollComposer = AmityPollPostComposerPage(
    targetId: "user-id|community-id",
    targetType: .community
)
```

```kotlin Android
@Composable
fun pollPostComposerPage(
    targetId: String,
    targetType: AmityPost.TargetType,
) {
    AmityPollPostComposerPage(
        targetId = targetId,
        targetType = targetType,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPollPostComposerPage } from '@amityco/ui-kit';

const SampleAmityPollPostComposerPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPollPostComposerPage
        targetId="targetId"
        targetType="community"
        // Use pollType="text" for text polls or pollType="image" for image polls
        pollType="text"
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget pollComposerPageWidget() {
  return AmityPollPostComposerPage(
      targetType: AmityPostTargetType.COMMUNITY,
      targetId: 'targetId',
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomAmityPostTargetSelectionPageBehavior: AmityPostTargetSelectionPageBehavior {
    override init() {
        super.init()
    }

    override func goToPostComposerPage(context: AmityPostTargetSelectionPageBehavior.Context) {
        // Custom implementation for navigating to Post Composer Page
    }
}

// Call this function to setup custom behaviour class in UIKit
func setPostTargetSelectionPageBehaviour() {
    let customBehavior = CustomAmityPostTargetSelectionPageBehavior()
    AmityUIKit4Manager.behaviour.postTargetSelectionPageBehavior = customBehavior
}
```

```kotlin Android
class CustomPostTargetSelectionPageBehaviour : AmityPostTargetSelectionPageBehavior() {
    override fun goToPostComposerPage(
        context: Context,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String?,
        targetType: AmityPostTargetType,
        community: AmityCommunity?
    ) {
        // custom implementation for navigating to Post Composer Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomPostTargetSelectionPageBehaviour()
    AmityUIKit4Manager.behavior.postTargetSelectionPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityPostTargetSelectionPage } from '@amityco/ui-kit';

const SampleAmityPostTargetSelectionPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityPostTargetSelectionPage: {
          goToPostComposerPage: () => {},
        },
      }}
    >
      <AmityPostTargetSelectionPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityPostTargetSelectionPage,
  AmityUiKitProvider,
  AmityPostTargetSelectionPageType,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
  behaviour={{
    AmityPostTargetSelectionPageBehavior: {
      goToPostComposerPage: () => {},
      goToLivestreamComposerPage: () => {},
      goToPollComposerPage: () => {},
    },
  }}
>
  <AmityPostTargetSelectionPage
    postType={AmityPostTargetSelectionPageType.post}
  />
</AmityUiKitProvider>
```


## Media Carousel

Posts with **two or more** images or videos are displayed as a horizontally **swipeable carousel** — one full-width frame per attachment, shown in the order they were added. A post with a single attachment is shown as one full-width frame.

  <img
    src="/images/post-media-carousel.png"
    alt="Media carousel — a post with multiple images shown as full-width swipeable frames with a pagination indicator and an n/total counter"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

  Every attachment is reachable by swiping, so nothing is hidden or truncated. The media carousel is available on iOS, Android, React, and React Native.

### How It Works

    Each image or video gets its own full-width frame, with no wrap-around at the first or last frame. On mobile, members **swipe** one frame at a time. On desktop, swipe is disabled and members use the **arrow buttons** on the frame — the left arrow is hidden on the first frame and the right arrow on the last.

    The frame shape is classified from the **first** attachment and locked for the whole carousel, so the post height never jumps between frames.

    A pagination indicator and an `n/total` counter show the current frame and update as members move through the carousel. Desktop shows an indicator strip alongside the arrow buttons.

    Tapping a frame opens the full-screen viewer at that frame in its original aspect ratio; closing returns to the same frame. In the viewer, videos autoplay and keep their mute state across swipes.

### Frame Ratio

The carousel picks **one** frame shape from the **first** attachment — landscape (16:9), square (1:1), or portrait (4:5) — and locks it for every frame, so the post height never shifts as members move through the carousel. Each frame is cropped to fill the locked shape, while the full-screen viewer shows each item at its original aspect ratio. Portrait videos keep their orientation. In the composer, if the first attachment is removed, the shape re-derives from the new first attachment.

### Composer Preview

When creating or editing a post, the composer previews attachments in the same carousel format before publishing. Each frame carries its own controls:

- **Remove** — delete that attachment from the post
- **Alt text** — add descriptive text (images only)
- **Product tag** — open the product picker for that frame

### Limits & Constraints

| Limit | Value |
| --- | --- |
| Attachments per post | 2–10 render as a carousel (a single attachment renders as one frame) |
| Media types per post | Images **or** videos — a single post cannot mix images and videos |
| Duplicate selection | Duplicate files are silently excluded before upload |

## Product Tagging

Product tagging enables commerce integration within posts, allowing users to tag products in text and media, and viewers to discover and open tagged products directly from a post.

  <img
    src="/images/post-product-tagging.png"
    alt="Post product tagging — tagged products displayed as a carousel below post content"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

  Product tagging requires the Product Catalog to be configured and enabled for your network in the console. The feature is available on iOS, Android, and Web only.

### How It Works

    Type `@` in the post caption to trigger a suggestion overlay with a **Products** tab. Selecting a product inserts it as a single token — backspace removes the entire mention.

    Each image or video in a post has its own tag entry point. Tap the tag button on a media item to open the product picker for that item.

    All tagged products are displayed in a scrollable list below the post content — in both the feed and post detail view.

    Tapping a product opens its link in an in-app browser on iOS and Android, and in a new tab on Web. Override this to route the tap yourself — see below.

### Customize the Product Tap

Opening the product link is the default. Override `onPostProductTagClick` on `AmityGlobalBehavior` to send the tap to your own product screen or commerce flow instead.

The handler receives the tapped product on the context. Read it to decide where to go.

| Context field | Type | Available on |
| --- | --- | --- |
| `product` | `AmityProduct` | iOS, Android, Web |
| `pageContext` | `android.content.Context` | Android |

`AmityProduct` carries `productId`, `productName`, `productUrl`, `price`, `currency`, and `thumbnailUrl`. Use `productId` to look the item up in your own catalogue, or `productUrl` to open it yourself.

```swift iOS
class MyGlobalBehavior: AmityGlobalBehavior {
    override func onPostProductTagClick(context: AmityGlobalBehavior.Context) {
        guard let product = context.product else { return }

        if let item = MyCatalogue.find(id: product.productId) {
            MyNavigator.showProduct(item)
        } else {
            // Fall back to the UIKit in-app browser.
            super.onPostProductTagClick(context: context)
        }
    }
}

AmityUIKit4Manager.behaviour.globalBehavior = MyGlobalBehavior()
```

```kotlin Android
AmityUIKit4Manager.behavior.globalBehavior = object : AmityGlobalBehavior() {
    override fun onPostProductTagClick(context: AmityGlobalBehavior.Context): Boolean {
        val product = context.product ?: return false

        val intent = Intent(context.pageContext, ProductActivity::class.java)
        intent.putExtra("productId", product.getProductId())
        context.pageContext.startActivity(intent)

        // Return true to claim the tap, so the in-app browser is skipped.
        return true
    }
}
```

```typescript Web
<AmityUIKitProvider
  pageBehavior={{
    AmityGlobalBehavior: {
      onPostProductTagClick: ({ product }) => {
        router.push(`/products/${product.productId}`);
      },
    },
  }}
>
```

**The platforms differ in how you fall back to the default.**

- **Android** — the handler returns a `Boolean`. Return `true` when your app handled the tap, or `false` to get the built-in product web view.
- **iOS** — the handler returns no value, so an override always replaces the default. Call `super.onPostProductTagClick(context:)` where you want the in-app browser instead.
- **Web** — the handler returns no value and behaves like iOS. There is no `super` to call: open `product.productUrl` yourself if you want the default behavior for some products.

### Limits & Constraints

| Limit | Value |
| --- | --- |
| Max products per post | 20 (combined across text mentions and media tags) |
| Max products per media item | 5 |
| Platforms supported | iOS, Android, Web |

### Components Used in Posts

Product tagging in posts uses two shared UIKit components. See [Product Tagging Components](/uikit/components/social/product-tagging) for full parameter reference and code examples.

| Component | Used for |
| --- | --- |
| `ProductTagSelectionComponent` | Searching and selecting products (via `create` or `edit` mode) |
| `ProductTagListComponent` | Displaying tagged products below post content (via `post`, `image`, or `video` render mode) |

The `ProductTagSelectionComponent` is opened from the Post Composer Page — either from the `@` mention flow in the text editor, or from the tag button on a media attachment. The `ProductTagListComponent` is rendered automatically within Post Detail and feed views when a post has tagged products.

## Pinned & Featured Posts

When a post is pinned or featured, the UIKit renders a **read-only badge** on it in the feed. This applies to any post, not just events.

Pinning and featuring are **managed in the Console** — there is no in-app control in the UIKit to change that state; the component only reflects it. See the [pin/feature note](/social-plus-sdk/social/content-management/posts/moderation/pin-post) for how the state is set.

A post published to a user's own feed can never be pinned. Global featuring requires a public community.

## Related Features

    **Content Display** Feed components for displaying and organizing posts

    **Engagement Features** User interaction and engagement components

    **Community Features** Community management and participation tools

    **Commerce Integration** Shared UIKit components for product selection and display

---

### [Communities](https://learn.social.plus/uikit/components/social/communities)

> Core community features including setup, profiles, and content feeds

**UIKit Component**: Community components are built on top of the social.plus
  SDK, providing ready-to-use community management UI with full data management
  handled automatically.

## Feature Overview

Core Community UIKit components provide comprehensive tools for building and managing community experiences. From creating and configuring communities to displaying rich content feeds, these components handle the complete community lifecycle while maintaining seamless integration with the social.plus SDK.

### Key Features

    **Community creation and configuration** - Create new communities with
    avatars, names, descriptions - Category assignment (up to 10 categories) -
    Privacy settings (public/private/hidden) - Member invitation workflows
    **Community profile and header display** - Cover photo and community
    information display - Member and post count tracking - Community
    verification badges - Join/request management
    **Community feed components** - General community post feeds - Pinned posts
    display - Image-only content feeds - Video-only content feeds
    **Basic member addition workflows** - Category selection for communities -
    Member search and invitation - Privacy-based member management - Community
    discovery features

## Implementation Guide

    **Community creation, setup, and basic configuration**

    The Community Setup components provide comprehensive tools for creating new communities and configuring existing ones, including category assignment and member invitation workflows.

    ### Community Setup Page

    The Community Setup Page can be used to create a brand new community or update existing community information including avatar, name, description, categories, and privacy settings.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Creating a community | Fill in information needed to create the community like avatar, name, description and categories. Public or private community selection available. |
    | Updating existing community | Community avatar, name, description, and categories can be updated. Privacy settings can be changed from public to private and vice versa. |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_setup_page/*/*` | Page | You can customize page theme |
    | `community_setup_page/*/close_button` | Element | You can customize image |
    | `community_setup_page/*/title` | Element | You can customize text |
    | `community_setup_page/*/community_edit_title` | Element | You can customize text |
    | `community_setup_page/*/community_name_title` | Element | You can customize text |
    | `community_setup_page/*/community_about_title` | Element | You can customize text |
    | `community_setup_page/*/community_category_title` | Element | You can customize text |
    | `community_setup_page/*/community_privacy_title` | Element | You can customize text |
    | `community_setup_page/*/community_create_button` | Element | You can customize text and image |
    | `community_setup_page/*/community_edit_button` | Element | You can customize text and image |

    #### Code Examples

```swift iOS
// AmityCommunitySetupPage can be used in 2 modes:
// Creation mode - .create
// Editing mode - .edit(AmityCommunity)
let page = AmityCommunitySetupPage(mode: .create)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunitySetupPage(community: AmityCommunity) {
    AmityCommunitySetupPage(
        mode = AmityCommunitySetupPageMode.Create,
    )

    AmityCommunitySetupPage(
        mode = AmityCommunitySetupPageMode.Edit(community),
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunitySetupPage,
  AmityCommunitySetupPageMode,
} from '@amityco/ui-kit';

const SampleCommunitySetup = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityCommunitySetupPageBehavior: {
          goToAddCategoryPage: (context) => {},
          goToAddMemberPage: (context) => {},
        },
      }}
    >
      <AmityCommunitySetupPage
        mode={AmityCommunitySetupPageMode.EDIT}
        community={community}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communitySetupPage() {
  // This page can be used to create a new community or edit an existing community.
  // CreateMode() is used to create a new community.
  // EditMode(AmityCommunity community) is used to edit an existing community.
  return AmityCommunitySetupPage(mode: const CreateMode());
}
```

    ### Add Category Page

    The Add Category Page allows users to search for categories to attach to a community. A community can have up to 10 categories.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Add category | Up to 10 categories can be selected to attach to a community |

    #### Code Examples

```swift iOS
let categoryPage = AmityCommunityAddCategoryPage(categories: [], onAddedAction: { categories in
    // Handle selected categories
})
let categoryVC = AmitySwiftUIHostingController(rootView: categoryPage)
```

```kotlin Android
@Composable
fun composeCommunityAddCategoryPage(
    categories: List<AmityCommunityCategory>,
) {
    AmityCommunityAddCategoryPage(
        categories = categories,
        onAddedAction = { /* Handle categories */ }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityAddCategoryPage } from '@amityco/ui-kit';

const SampleAmityCommunityAddCategoryPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityAddCategoryPage category={category} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget addCategoryPage() {
  return AmityCommunityAddCategoryPage(
    categories: const [],
    onAddedAction: (categories) {}
  );
}
```

    ### Invite Member Page

    The Invite Member Page allows users to search for specific users by display name to invite to a community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Invite User | Users can be searched by display name to invite them to a community |

    #### Code Examples

```swift iOS
let invitePage = AmityCommunityInviteMemberPage(users: [], onInvitedAction: { users in
    // Handle invited users
})
let inviteVC = AmitySwiftUIHostingController(rootView: invitePage)
```

```kotlin Android
@Composable
fun composeCommunityInvitedMemberPage(users: List<AmityUser>) {
    AmityCommunityInviteMemberPage(
        users = users,
        onInvitedAction = { users: List<AmityUser> ->
            // Handle the invited users list
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityInviteMemberPage } from '@amityco/ui-kit';

const SampleAmityCommunityInviteMemberPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityInviteMemberPage communityId="communityId" onSubmit={(userIds) => {}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Flutter code not provided in original content
// Please refer to platform-specific documentation
```

    ### Navigation Behavior

    The Community Setup Page will navigate to the user listing page to add users to the community if it is created as private, and to the category listing page to attach categories to the community.

```swift iOS
class CustomAmityCommunitySetupPageBehavior: AmityCommunitySetupPageBehavior {
    override init() {
        super.init()
    }

    override func goToAddMemberPage(_ context: AmityCommunitySetupPageBehavior.Context) {
        // override behavior
    }

    override func goToAddCategoryPage(_ context: AmityCommunitySetupPageBehavior.Context) {
        // override behavior
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommunitySetupPageBehaviour() {
    let customBehavior = CustomAmityCommunitySetupPageBehavior()
    AmityUIKit4Manager.behaviour.communitySetupPageBehavior = customBehavior
}
```

```kotlin Android
class CustomCommunitySetupPageBehavior : AmityCommunitySetupPageBehavior() {
    // Override navigation methods as needed
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCommunitySetupPageBehavior()
    AmityUIKit4Manager.behavior.communitySetupPageBehavior = customBehaviour
}
```

```typescript React
const SampleCommunitySetupWithBehavior = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityCommunitySetupPageBehavior: {
          goToAddCategoryPage: (context) => {
            // Custom category page navigation
          },
          goToAddMemberPage: (context) => {
            // Custom member page navigation
          },
        },
      }}
    >
      <AmityCommunitySetupPage
        mode={AmityCommunitySetupPageMode.CREATE}
      />
    </AmityUiKitProvider>
  );
};
```


    **Community profile page and header components**

    The Community Profile components provide the main interface for displaying community information and content, serving as the central hub for community interaction.

    ### Community Profile Page

    The Community Profile Page is the main page of a community where all announcement posts, pinned posts, regular posts, and stories created within the community are stored. This page also allows users with necessary permissions to create posts and stories in the community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Community Post Feed | All posts created within the community can be seen in the feed |
    | Pinned Posts | Pin tab displays all pinned posts |
    | Announcement Posts | Announcement posts displayed on top of community post feed at the first tab |
    | Image Feed | Image tab consolidates all images posted in the community |
    | Video Feed | Video tab contains all videos posted in the community |
    | Pending Posts | Users with moderator permission can review all pending posts in the community |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/*/*` | Page | You can customize page theme |
    | `community_profile_page/*/back_button` | Element | You can customize image |
    | `community_profile_page/*/menu_button` | Element | You can customize image |
    | `community_profile_page/community_pin/community_create_post_button` | Element | You can customize image |

    #### Code Examples

```swift iOS
// Community Profile Page
let page = AmityCommunityProfilePage(communityId: "<community-id>")
let vc = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityProfilePage(communityId: String) {
    AmityCommunityProfilePage(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityProfilePage
} from '@amityco/ui-kit';

const SampleCommunityProfile = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityCommunityProfilePageBehavior: {
          goToPostComposerPage: (context) => {},
          goToPostDetailPage: (context) => {},
          goToStoryCreationPage: (context) => {},
          goToCommunitySettingPage: (context) => {},
          goToEditCommunityPage: (context) => {},
          goToPendingPostPage: (context) => {},
          goToMembershipPage: (context) => {},
          goToPollPostComposerPage: (context) => {},
        },
      }}
    >
      <AmityCommunityProfilePage communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

    ### Community Header Component

    The Community Header Component displays the cover photo, display name, description and categories, and other information about the community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Community Information | Display cover photo, display name, description and categories, members and posts count, stories, pending posts |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/community_header/*` | Component | You can customize component theme |
    | `community_profile_page/community_header/community_verify_badge` | Element | You can customize image |
    | `community_profile_page/community_header/community_join_button` | Element | You can customize image |
    | `community_profile_page/community_header/community_pending_post` | Element | You can customize image |

    #### Code Examples

```swift iOS
// Community Header Component
let component = AmityCommunityHeaderComponent(community: community)
let viewController = AmitySwiftUIHostingController(rootView: component)
```

```kotlin Android
@Composable
fun composeCommunityHeader(community: AmityCommunity) {
    AmityCommunityHeaderComponent(
        community = community
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityHeaderComponent
} from '@amityco/ui-kit';

const SampleCommunityHeader = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityHeaderComponent community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityHeaderComponent(AmityCommunity? community) {
  return AmityCommunityHeaderComponent(community: community);
}
```

    ### Navigation Behavior

    The Community Profile Page will navigate to the post composer page, story creation page, pending post page, community membership page, community setting page, and post detail page.

```swift iOS
class CustomAmityCommunityProfilePageBehavior: AmityCommunityProfilePageBehavior {
    override init() {
        super.init()
    }

    override func goToPendingPostPage(context: AmityCommunityProfilePageBehavior.Context) {
        // override behavior
    }

    override func goToCommunitySettingPage(context: AmityCommunityProfilePageBehavior.Context) {
        // override behavior
    }

    override func goToPostComposerPage(context: AmityCommunityProfilePageBehavior.Context, community: AmityCommunityModel? = nil) {
        // override behavior
    }

    override func goToCreateStoryPage(context: AmityCommunityProfilePageBehavior.Context, community: AmityCommunityModel?) {
        // override behavior
    }

    override func goToPostDetailPage(context: AmityCommunityProfilePageBehavior.Context, post: AmityPostModel?, category: AmityPostCategory = .general) {
        // override behavior
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommunityProfilePageBehavior() {
    let customBehavior = CustomAmityCommunityProfilePageBehavior()
    AmityUIKit4Manager.behaviour.communityProfilePageBehavior = customBehavior
}
```

```kotlin Android
class AmityCustomCommunityProfilePageBehavior : AmityCommunityProfilePageBehavior() {
    override fun goToCommunitySettingPage(context: Context) {
        // custom implementation for navigating to Community Setting Page
    }

    override fun goToPendingPostPage(context: Context) {
        // custom implementation for navigating to Post Review Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehavior = AmityCustomCommunityProfilePageBehavior()
    AmityUIKit4Manager.behavior.communityProfilePageBehavior = customBehavior
}
```

```typescript React
const SampleCommunityProfileWithBehavior = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityCommunityProfilePageBehavior: {
          goToPostComposerPage: (context) => {
            // Custom post composer navigation
          },
          goToPostDetailPage: (context) => {
            // Custom post detail navigation
          },
          goToStoryCreationPage: (context) => {
            // Custom story creation navigation
          },
          goToCommunitySettingPage: (context) => {
            // Custom community settings navigation
          },
        },
      }}
    >
      <AmityCommunityProfilePage communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```


    **Community content feeds and media displays**

    The Community Feed components provide specialized views for different types of content within communities, offering users organized access to posts, media, and pinned content.

    ### Community Feed Component

    The Community Feed Component displays a list of posts created in the community, serving as the main content stream for community members.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Post Feed | Display a list of posts created within the community |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/community_feed/*` | Component | You can customize component theme |

    #### Code Examples

```swift iOS
// Community Feed Component
let component = AmityCommunityFeedComponent(communityId: "<community-id>")
let viewController = AmitySwiftUIHostingController(rootView: component)
```

```kotlin Android
@Composable
fun composeCommunityFeed(communityId: String) {
    AmityCommunityFeedComponent(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityFeedComponent
} from '@amityco/ui-kit';

const SampleCommunityFeed = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Community feed components are not available in Flutter platform
// Please use the Community Profile Page which includes all feed functionality
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

    ### Community Pin Feed Component

    The Community Pin Feed Component displays a list of pinned posts created in the community, highlighting important or featured content.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Pin Post Feed | Display a list of pinned posts |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/community_pin/*` | Component | You can customize component theme |

    #### Code Examples

```swift iOS
// Community Pin Feed Component
let pinnedComponent = AmityCommunityPinnedPostComponent(communityId: "<community-id>")
let pinnedVC = AmitySwiftUIHostingController(rootView: pinnedComponent)
```

```kotlin Android
@Composable
fun composeCommunityPinnedPosts(communityId: String) {
    AmityCommunityPinnedPostComponent(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityPinnedPostComponent
} from '@amityco/ui-kit';

const SampleCommunityPinnedPosts = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityPinnedPostComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Community pin feed components are not available in Flutter platform
// Please use the Community Profile Page which includes all feed functionality
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

    ### Community Image Feed Component

    The Community Image Feed Component displays a list of image posts created in the community, providing a visual gallery experience with navigation to original posts.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Image Feed | Display a list of image posts in gallery format |
    | Original Post Navigation | Tap on gallery images to navigate to their original posts |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/community_image_feed/*` | Component | You can customize component theme |

    #### Navigation Callbacks

    The Image Feed Component supports navigation callbacks to handle taps on gallery items, allowing users to view the complete original post.

    #### Code Examples

```swift iOS
// Community Image Feed Component
let imageComponent = AmityCommunityImageFeedComponent(communityId: "<community-id>")
let imageVC = AmitySwiftUIHostingController(rootView: imageComponent)
```

```kotlin Android
@Composable
fun composeCommunityImageFeed(communityId: String) {
    AmityCommunityImageFeedComponent(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityImageFeedComponent
} from '@amityco/ui-kit';

const SampleCommunityImageFeed = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityImageFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Community image feed components are not available in Flutter platform
// Please use the Community Profile Page which includes all feed functionality
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

    ### Community Video Feed Component

    The Community Video Feed Component displays a list of video posts created in the community, offering a dedicated video content experience with navigation to original posts.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Video Feed | Display a list of video posts in gallery format |
    | Original Post Navigation | Tap on gallery videos to navigate to their original posts |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/community_video_feed/*` | Component | You can customize component theme |

    #### Navigation Callbacks

    The Video Feed Component supports navigation callbacks to handle taps on gallery items, allowing users to view the complete original post with video playback context.

    #### Code Examples

```swift iOS
// Community Video Feed Component with Original Post Navigation
let videoComponent = AmityCommunityVideoFeedComponent(communityId: "<community-id>")
let videoVC = AmitySwiftUIHostingController(rootView: videoComponent)
```

```kotlin Android
@Composable
fun composeCommunityVideoFeed(communityId: String) {
    AmityCommunityVideoFeedComponent(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityVideoFeedComponent
} from '@amityco/ui-kit';

const SampleCommunityVideoFeed = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityVideoFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Community video feed components are not available in Flutter platform
// Please use the Community Profile Page which includes all feed functionality
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

    ### Navigation Behavior

    Community feed components integrate with the main community profile navigation behavior, allowing seamless interaction with posts and content.

```swift iOS
// Feed components inherit navigation behavior from Community Profile Page
// Use the Community Profile Page behavior customization for navigation control
class CustomAmityCommunityProfilePageBehavior: AmityCommunityProfilePageBehavior {
    override func goToPostDetailPage(context: AmityCommunityProfilePageBehavior.Context, post: AmityPostModel?, category: AmityPostCategory = .general) {
        // Custom post detail navigation from feed components
    }
}
```

```kotlin Android
// Feed components work within the Community Profile Page context
// Navigation behavior is handled through the Community Profile Page behavior
class AmityCustomCommunityProfilePageBehavior : AmityCommunityProfilePageBehavior() {
    override fun goToPostDetailPage(context: Context, postId: String) {
        // Custom post detail navigation from feed components
    }
}
```

```typescript React
// Feed components integrate with Community Profile Page navigation
const SampleFeedsWithNavigation = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunityProfilePageBehavior: {
          goToPostDetailPage: (context) => {
            // Custom navigation for posts in feed components
          },
        },
      }}
    >
      <AmityCommunityFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

      ### Community Event Feed Component

      The Community Event Feed Component displays a list of event posts created in the community, providing a dedicated view for event-related content and activities.

      #### Features

      | Feature | Description |
      |---------|-------------|
      | Event Feed | Display a list of event posts in the community |
      | Original Event Navigation | Tap on event items to navigate to their detailed view |

      #### Customization Options

      | Config ID | Type | Description |
      |-----------|------|-------------|
      | `community_profile_page/community_event_feed/*` | Component | You can customize component theme |

      #### Navigation Callbacks

      The Event Feed Component supports navigation callbacks to handle taps on event items, allowing users to view the complete event details.

      #### Code Examples

```swift iOS
// Community Event Feed Component
let eventComponent = AmityCommunityEventFeedComponent(communityId: "<community-id>")
let eventVC = AmitySwiftUIHostingController(rootView: eventComponent)
```

```kotlin Android
@Composable
fun composeCommunityEventFeed(communityId: String) {
    AmityCommunityEventFeedComponent(
        communityId = communityId
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityCommunityEventFeedComponent
} from '@amityco/ui-kit';

const SampleCommunityEventFeed = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityEventFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// Community event feed components are not available in Flutter platform
// Please use the Community Profile Page which includes all feed functionality
Widget communityProfilePage(String communityId) {
  return AmityCommunityProfilePage(communityId: communityId);
}
```

      ### Navigation Behavior

      Community event feed components integrate with the main community profile navigation behavior, allowing seamless interaction with event posts and details.

```swift iOS
// Event feed components inherit navigation behavior from Community Profile Page
// Use the Community Profile Page behavior customization for navigation control
class CustomAmityCommunityProfilePageBehavior: AmityCommunityProfilePageBehavior {
    override func goToEventDetailPage(context: AmityCommunityProfilePageBehavior.Context, event: AmityEventModel?) {
        // Custom event detail navigation from event feed components
    }
}
```

```kotlin Android
// Event feed components work within the Community Profile Page context
// Navigation behavior is handled through the Community Profile Page behavior
class AmityCustomCommunityProfilePageBehavior : AmityCommunityProfilePageBehavior() {
    override fun goToEventDetailPage(context: Context, eventId: String) {
        // Custom event detail navigation from event feed components
    }
}
```

```typescript React
// Event feed components integrate with Community Profile Page navigation
const SampleEventFeedsWithNavigation = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunityProfilePageBehavior: {
          goToEventDetailPage: (context) => {
            // Custom navigation for events in event feed components
          },
        },
      }}
    >
      <AmityCommunityEventFeedComponent communityId="communityId" />
    </AmityUiKitProvider>
  );
};
```


## Related Components

    title="Community Management"
    href="/uikit/components/social/community-management"
    icon="gears"
  >
    **Settings & Administration** Community settings, permissions, and
    moderation tools
    title="Community Membership"
    href="/uikit/components/social/community-membership"
    icon="users"
  >
    **Member Management** Member administration, invitations, and join requests
    title="Social Feeds"
    href="/uikit/components/social/feeds"
    icon="newspaper"
  >
    **Feed Components** General social feed components and integration
    title="Posts & Media"
    href="/uikit/components/social/posts"
    icon="photo-film"
  >
    **Post Components** Community post creation and management
    title="Content Discovery"
    href="/uikit/components/social/content-discovery"
    icon="magnifying-glass"
  >
    **Search & Discovery** Community and content discovery features
    title="Users & Profiles"
    href="/uikit/components/social/users"
    icon="user"
  >
    **User Management** User profiles and social interactions

  **Implementation Strategy**: Start with the AmityCommunitySetupPage for
  creating new communities, then integrate AmityCommunityProfilePage as the main
  community hub. Use specialized feed components (Pin, Image, Video) to provide
  organized content views. Configure navigation behaviors early to ensure smooth
  user flows between community creation, content viewing, and management
  features.

---

### [Community Management](https://learn.social.plus/uikit/components/social/community-management)

> Community settings, permissions, moderation tools, and administrative features

**UIKit Component**: Community management components are built on top of the social.plus SDK, providing ready-to-use administrative and moderation UI with full data management handled automatically.

## Feature Overview

Community Management UIKit components provide comprehensive administrative tools for community oversight, settings management, and content moderation. These components enable moderators and administrators to configure community settings, manage notifications, review pending content, and control permissions—all through ready-to-use interfaces built on top of the social.plus SDK.

### Key Features

    **Comprehensive community configuration**
    - Community profile editing and management
    - Member management and role assignment
    - Privacy and visibility controls
    - Community closure and leave functionality
    **Fine-grained notification controls**
    - Community-wide notification settings
    - Post, comment, and story notification preferences
    - Individual notification type management
    - User notification preference controls
    **Pending posts and content oversight**
    - Pending post review and approval
    - Community post moderation tools
    - Join request management
    - Content acceptance and decline workflows
    **Post and story permission management**
    - Post creation permission settings
    - Story comment permission controls
    - Role-based access management
    - Community-specific permission configurations

## Implementation Guide

    **Core community settings and configuration**

    Community Settings components provide comprehensive administrative controls for community management, including profile editing, member management, and core community configuration options.

    ### Community Setting Page

    The Community Settings Page is the gateway for changing various settings within the community and updating its profile information. Users can leave the community or close the entire community from this page.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Editing Profile | Community profile can be updated through this setting |
    | Updating Members | Adding new members or removing existing members can be done from this setting. It also has the functionality to change role of users within the community |
    | Notification Setting | All notification settings related to a community can be changed here |
    | Post Permissions | Post related permissions can be changed here |
    | Story Comments | Story comment permissions can be changed here |
    | Leave Community | User can leave the community |
    | Close Community | Moderator user can close the entire community |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_setting_page/*/*` | Page | You can customize page theme |
    | `community_setting_page/*/edit_profile` | Element | You can customize text |
    | `community_setting_page/*/members` | Element | You can customize text |
    | `community_setting_page/*/notifications` | Element | You can customize text |
    | `community_setting_page/*/post_permission` | Element | You can customize text |
    | `community_setting_page/*/story_setting` | Element | You can customize text |
    | `community_setting_page/*/leave_community` | Element | You can customize text |
    | `community_setting_page/*/close_community` | Element | You can customize text |
    | `community_setting_page/*/close_community_description` | Element | You can customize text |

    #### Code Examples

```swift iOS
let page = AmityCommunitySettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunitySettingPage(community: AmityCommunity) {
    AmityCommunitySettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunitySettingPage } from '@amityco/ui-kit';

const SampleAmityCommunitySettingPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityCommunitySettingPageBehavior: {
          goToEditCommunityPage: (context) => {},
          goToMembershipPage: (context) => {},
          goToPostPermissionPage: (context) => {},
          goToStorySettingPage: (context) => {},
          goToSocialHomePage: () => {},
        },
      }}
    >
      <AmityCommunitySettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communitySettingPage(AmityCommunity community) {
  return AmityCommunitySettingPage(community: community);
}
```

    ### Community Story Setting Page

    The Community Story Setting Page is the page where users can update the setting whether new comments will be allowed in the story in a community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Allow Comments | This setting will allow users to create new comments in the community stories |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_story_setting_page/*/*` | Page | You can customize page theme |

    #### Code Examples

```swift iOS
let page = AmityCommunityStorySettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeStorySettingPage(community: AmityCommunity) {
    AmityCommunityStorySettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityStorySettingPage } from '@amityco/ui-kit';

const SampleAmityCommunityStorySettingPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityStorySettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityStorySettingPage(AmityCommunity community) {
  return AmityCommunityStorySettingPage(community: community);
}
```

    ### Navigation Behavior

    The Community Settings Page will navigate to each page related to the setting. You can override these behaviors to navigate to your own pages.

```swift iOS
class CustomAmityCommunitySettingPageBehavior: AmityCommunitySettingPageBehavior {
    override init() {
        super.init()
    }

    override func goToEditCommunityPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // override behavior
    }

    override func goToMembershipPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // override behavior
    }

    override func goToNotificationPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // override behavior
    }

    override func goToPostPermissionPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // override behavior
    }

    override func goToStorySettingPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // override behavior
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommunitySettingPageBehavior() {
    let customBehavior = CustomAmityCommunitySettingPageBehavior()
    AmityUIKit4Manager.behaviour.communitySettingPageBehavior = customBehavior
}
```

```kotlin Android
class CustomCommunitySettingPageBehavior : AmityCommunitySettingPageBehavior() {
    // Override navigation methods as needed
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCommunitySettingPageBehavior()
    AmityUIKit4Manager.behavior.communitySettingPageBehavior = customBehaviour
}
```

```typescript React
const SampleCommunitySettingWithBehavior = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunitySettingPageBehavior: {
          goToEditCommunityPage: (context) => {
            // Custom edit community page navigation
          },
          goToMembershipPage: (context) => {
            // Custom membership page navigation
          },
          goToPostPermissionPage: (context) => {
            // Custom post permission page navigation
          },
        },
      }}
    >
      <AmityCommunitySettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

    **Community notification configuration and management**

    Notification Settings components provide granular control over community notifications, allowing users to customize their notification preferences for posts, comments, stories, and other community activities.

    ### Community Notification Setting Page

    The Community Notification Setting Page is the main page to change the notification settings within the community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Allow Notification | User can turn the community notification on and off |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_notification_page/*/*` | Page | You can customize page theme |

    #### Code Examples

```swift iOS
let page = AmityCommunityNotificationSettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityNotificationSettingPage(community: AmityCommunity) {
    AmityCommunityNotificationSettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityNotificationSettingPage } from '@amityco/ui-kit';

const SampleNotificationSettings = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityNotificationSettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityNotificationSettingPage(AmityCommunity community) {
  return AmityCommunityNotificationSettingPage(community: community);
}
```

    ### Community Posts Notification Page

    The Community Posts Notification Page is the page to change post-related notification settings in a community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | React Posts | Update notification setting of post reactions |
    | New Posts | Update notification setting of post creation |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_posts_notification_page/*/*` | Page | You can customize page theme |

    #### Code Examples

```swift iOS
let page = AmityCommunityPostsNotificationSettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityPostsNotificationSettingPage(community: AmityCommunity) {
    AmityCommunityPostsNotificationSettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityPostsNotificationSettingPage } from '@amityco/ui-kit';

const SamplePostsNotificationSettings = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityPostsNotificationSettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityPostsNotificationSettingPage(AmityCommunity community) {
  return AmityCommunityPostsNotificationSettingPage(community: community);
}
```

    ### Community Comments Notification Page

    The Community Comments Notification Page is the page to change comment-related notification settings in a community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | React Comments | Update notification setting of comment reactions |
    | New Comments | Update notification setting of comment creations |
    | Replies | Update notification setting of reply comment creations |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_comments_notification_page/*/*` | Page | You can customize page theme |

    #### Code Examples

```swift iOS
let page = AmityCommunityCommentsNotificationSettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityCommentsNotificationSettingPage(community: AmityCommunity) {
    AmityCommunityCommentsNotificationSettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityCommentsNotificationSettingPage } from '@amityco/ui-kit';

const SampleCommentsNotificationSettings = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityCommentsNotificationSettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityCommentsNotificationSettingPage(AmityCommunity community) {
  return AmityCommunityCommentsNotificationSettingPage(community: community);
}
```

    ### Community Stories Notification Page

    The Community Stories Notification Page is the page to change story-related notification settings in a community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | New Stories | Update notification setting of story creations |
    | Story Reactions | Update notification setting of story reactions |
    | Story Comments | Update notification setting of story comment creations |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_stories_notification_page/*/*` | Page | You can customize page theme |

    #### Code Examples

```swift iOS
let page = AmityCommunityStoriesNotificationSettingPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityStoriesNotificationSettingPage(community: AmityCommunity) {
    AmityCommunityStoriesNotificationSettingPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityStoriesNotificationSettingPage } from '@amityco/ui-kit';

const SampleStoriesNotificationSettings = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityStoriesNotificationSettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityStoriesNotificationSettingPage(AmityCommunity community) {
  return AmityCommunityStoriesNotificationSettingPage(community: community);
}
```

    ### Navigation Behavior

    This page will navigate to dedicated notification setting pages of posts, comments, and stories. You can override the behaviors to navigate to your own pages.

```swift iOS
class CustomAmityCommunityNotificationSettingPageBehavior: AmityCommunityNotificationSettingPageBehavior {
    override init() {
        super.init()
    }

    override func goToPostsNotificationSettingPage(_ context: AmityCommunityNotificationSettingPageBehavior.Context) {
        // override behavior
    }

    override func goToCommentsNotificationSettingPage(_ context: AmityCommunityNotificationSettingPageBehavior.Context) {
        // override behavior
    }

    override func goToStoriesNotificationSettingPage(_ context: AmityCommunityNotificationSettingPageBehavior.Context) {
        // override behavior
    }
}

// Call this function to setup custom behaviour class in UIKit
func setNotificationSettingPageBehaviour() {
    let customBehavior = CustomAmityCommunityNotificationSettingPageBehavior()
    AmityUIKit4Manager.behaviour.communityNotificationSettingPageBehavior = customBehavior
}
```

```kotlin Android
class CustomCommunityNotificationSettingPageBehavior :
    AmityCommunityNotificationSettingPageBehavior() {
    // Override navigation methods as needed
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCommunityNotificationSettingPageBehavior()
    AmityUIKit4Manager.behavior.communityNotificationSettingPageBehavior = customBehaviour
}
```

```typescript React
const SampleNotificationWithBehavior = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunityNotificationSettingPageBehavior: {
          goToPostsNotificationSettingPage: (context) => {
            // Custom posts notification navigation
          },
          goToCommentsNotificationSettingPage: (context) => {
            // Custom comments notification navigation
          },
          goToStoriesNotificationSettingPage: (context) => {
            // Custom stories notification navigation
          },
        },
      }}
    >
      <AmityCommunityNotificationSettingPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

    **Pending posts and content moderation tools**

    Content Moderation components provide comprehensive tools for reviewing and managing pending content, including posts and join requests that require moderator approval.

    ### Pending Request Page

    The pending request page is a unified interface that handles two types of moderation: **Pending Posts** (content moderation) and **Join Requests** (membership management). This page provides a centralized location for moderators to review both content and membership requests.

    **Content vs Membership**: While this page handles both types of pending items, the **Join Request** functionality is primarily a membership management feature. For detailed join request workflows and implementation, see [Community Membership - Join Request Management](/uikit/components/social/community-membership#join-request-management).

    Only moderators can approve or decline posts or join requests in a community. Normal users will only see their own posts that are pending approval from moderators.

    #### Features

    | Feature | Type | Description |
    |---------|------|-------------|
    | Pending Posts | **Content Moderation** | Moderator can review pending posts to accept or decline. Non-moderators see only their own pending posts |
    | Join Requests | **Membership Management** | Moderator can review requests from users wanting to join the community. See [Community Membership](/uikit/components/social/community-membership) for detailed implementation |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `pending_request_page/*/*` | Page | Customize overall page theme and layout |
    | `pending_request_page/*/back_button` | Element | Customize back button appearance |
    | `pending_request_page/*/title` | Element | Customize page title text |
    | `pending_request_page/*/pending_posts_section` | Component | Customize pending posts section styling |
    | `pending_request_page/*/join_requests_section` | Component | Customize join requests section styling |

    #### Code Examples

```swift iOS
let page = AmityPendingRequestPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composePendingRequestPage(community: AmityCommunity) {
    AmityPendingRequestPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPendingRequestPage } from '@amityco/ui-kit';

const ModerationPendingRequestPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPendingRequestPage
        community={{}}
        // This page handles both pending posts (content moderation)
        // and join requests (membership management)
        onPostAction={(action, post) => {
          // Handle post moderation actions
        }}
        onJoinRequestAction={(action, request) => {
          // Handle join request actions
          // For detailed implementation, see Community Membership docs
        }}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget pendingRequestPage(AmityCommunity community) {
  return AmityPendingRequestPage(community: community);
}
```

    ### Pending Post Content Component

    The pending post content component will display a post needed to be reviewed. Moderator of the community can review the pending post and can accept or decline.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Pending Posts | Moderator can review the pending post to accept or decline. If the user is not a moderator, the list will be the user's own posts needed to be reviewed |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `pending_posts_page/pending_post_content/*` | Component | You can customize component theme |
    | `pending_posts_page/pending_post_content/post_accept_button` | Element | You can customize text |
    | `pending_posts_page/pending_post_content/post_decline_button` | Element | You can customize text |

    #### Code Examples

```swift iOS
let component = AmityPendingPostContentComponent(post: post)
let viewController = AmitySwiftUIHostingController(rootView: component)
```

```kotlin Android
@Composable
fun composePendingPostComponent(post: AmityPost) {
    AmityPendingPostContentComponent(
        post = post,
        onAcceptAction = {
            // Handle accept action
        },
        onDeclineAction = {
            // Handle decline action
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPendingPostContentComponent } from '@amityco/ui-kit';

const SampleAmityPendingPostContentComponent = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPendingPostContentComponent
        post={{}}
        refresh={() => {}}
        canReviewCommunityPosts={true}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget pendingPostContentComponent(AmityPost post) {
  return AmityPendingPostContentComponent(post: post);
}
```

    ### Pending Post List Component

    The pending post list component will have the list of posts needed to be reviewed. Moderator of the community can review the pending posts.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Pending Posts | Moderator can review the pending posts to accept or decline. If the user is not a moderator, the list will be the user's own posts needed to be reviewed |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `pending_request_page/pending_post_list/*` | Component | You can customize component theme |
    | `pending_request_page/pending_post_list/post_accept_button` | Element | You can customize text |
    | `pending_request_page/pending_post_list/post_decline_button` | Element | You can customize text |

    #### Code Examples

```swift iOS
let page = AmityPendingPostListComponent(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composePendingPostListComponent(post: AmityPost) {
    AmityPendingPostContentComponent(
        post = post,
        onAcceptAction = {
            // Handle accept action
        },
        onDeclineAction = {
            // Handle decline action
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPendingPostListComponent } from '@amityco/ui-kit';

const SampleAmityPendingPostListComponent = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPendingPostListComponent
        pageId={'*'}
        reviewingPosts={[]}
        canReviewCommunityPosts={false}
        refresh={() => {}}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget pendingPostListComponent(AmityCommunity community) {
  return AmityPendingPostListComponent(
    community: community,
    pageId: 'pendingRequestPage',
  );
}
```

    **Join Request Management**: Join request approval and management functionality is documented in the [Community Membership](/uikit/components/social/community-membership) section, as it focuses on member management workflows rather than content moderation.

    ### Navigation Behavior

    Content moderation components integrate with the main community management navigation behavior for seamless moderation workflows.

```swift iOS
// Moderation components inherit navigation behavior from Community Profile Page
// Use the Community Profile Page behavior customization for navigation control
class CustomAmityCommunityProfilePageBehavior: AmityCommunityProfilePageBehavior {
    override func goToPendingPostPage(context: AmityCommunityProfilePageBehavior.Context) {
        // Custom pending post page navigation
    }
}
```

```kotlin Android
// Moderation components work within the Community Profile Page context
// Navigation behavior is handled through the Community Profile Page behavior
class AmityCustomCommunityProfilePageBehavior : AmityCommunityProfilePageBehavior() {
    override fun goToPendingPostPage(context: Context) {
        // Custom pending post page navigation
    }
}
```

```typescript React
// Moderation components integrate with Community Profile Page navigation
const SampleModerationWithNavigation = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunityProfilePageBehavior: {
          goToPendingPostPage: (context) => {
            // Custom navigation for pending posts
          },
        },
      }}
    >
      <AmityPendingRequestPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

    **Post and content permission controls**

    Permission Management components provide administrative controls for managing community permissions, including post creation permissions and content-related access controls.

    ### Community Post Permissions Page

    The Community Post Permissions Page allows administrators to configure who can create posts and manage post-related permissions within the community.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Post Creation Permissions | Configure which community members can create posts |
    | Content Access Control | Manage permissions for different types of content creation |
    | Role-Based Permissions | Set permissions based on user roles within the community |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_post_permission_page/*/*` | Page | You can customize page theme |
    | `community_post_permission_page/*/permission_settings` | Element | You can customize permission setting elements |

    #### Code Examples

```swift iOS
let page = AmityCommunityPostPermissionPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunityPostPermissionPage(community: AmityCommunity) {
    AmityCommunityPostPermissionPage(
        community = community,
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityPostPermissionPage } from '@amityco/ui-kit';

const SamplePostPermissionPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunityPostPermissionPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communityPostPermissionPage(AmityCommunity community) {
  return AmityCommunityPostPermissionPage(community: community);
}
```

    ### Navigation Behavior

    Permission management components integrate with the community settings navigation flow for seamless administrative control.

```swift iOS
// Permission management is typically accessed through Community Settings Page
class CustomAmityCommunitySettingPageBehavior: AmityCommunitySettingPageBehavior {
    override func goToPostPermissionPage(_ context: AmityCommunitySettingPageBehavior.Context) {
        // Custom post permission page navigation
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommunitySettingPageBehavior() {
    let customBehavior = CustomAmityCommunitySettingPageBehavior()
    AmityUIKit4Manager.behaviour.communitySettingPageBehavior = customBehavior
}
```

```kotlin Android
// Permission management navigation through Community Settings
class CustomCommunitySettingPageBehavior : AmityCommunitySettingPageBehavior() {
    override fun goToPostPermissionPage(context: Context) {
        // Custom post permission page navigation
    }
}

fun setCustomBehavior() {
    val customBehaviour = CustomCommunitySettingPageBehavior()
    AmityUIKit4Manager.behavior.communitySettingPageBehavior = customBehaviour
}
```

```typescript React
const SamplePermissionWithNavigation = () => {
  return (
    <AmityUiKitProvider
      pageBehavior={{
        AmityCommunitySettingPageBehavior: {
          goToPostPermissionPage: (context) => {
            // Custom post permission navigation
          },
        },
      }}
    >
      <AmityCommunityPostPermissionPage community={{}} />
    </AmityUiKitProvider>
  );
};
```

## Related Components

    **Core Community Features**
    Community setup, profiles, and content feeds
    **Member Management**
    Member administration, invitations, and join requests
    **General Moderation**
    Platform-wide content moderation tools
    **Post Components**
    Post creation and management features
    **User Management**
    User profiles and administrative controls
    **Feed Components**
    Social feed display and management

**Implementation Strategy**: Start with the AmityCommunitySettingPage as the central administrative hub, then integrate specialized pages for notifications, content moderation, and permissions based on your community's needs. Use AmityPendingRequestPage primarily for pending post moderation workflows, and leverage the [Community Membership](/uikit/components/social/community-membership) components for join request management. Configure notification settings to match your engagement strategy and implement custom navigation behaviors early to ensure smooth administrative workflows between different management interfaces.

---

### [Community Membership](https://learn.social.plus/uikit/components/social/community-membership)

> Member management, invitations, join requests, and membership administration

**UIKit Component**: Community membership components are built on top of the social.plus SDK, providing ready-to-use member management UI with full data management handled automatically.

## Feature Overview

Community Membership UIKit components provide comprehensive tools for managing community members, handling join requests, processing invitations, and tracking membership analytics. These components enable community administrators to effectively manage their member base through intuitive interfaces that handle invitations, approval workflows, member roles, and membership insights—all built on top of the social.plus SDK.

### Key Features

    **Comprehensive member management**
    - Member list display and management
    - Role assignment and permission control
    - Member profile access and interactions
    - Member removal and ban functionality
    **Member invitation workflows**
    - Send invitations to new members
    - Track invitation status and responses
    - Manage pending invitation lists
    - Configure invitation permissions and limits
    **Join request handling and approval**
    - Review and approve join requests
    - Decline inappropriate requests
    - Automated approval workflow options
    - Join request notification management
    **Membership insights and tracking**
    - Member growth and activity metrics
    - Invitation success rate tracking
    - Join request approval statistics
    - Member engagement analytics

## Implementation Guide

    **Core member management and administration**

    Member Administration components provide comprehensive tools for managing community members, including member lists, role assignments, and member profile management. These components enable administrators to effectively oversee their community membership.

    ### Member Management Page

    The member management page provides a comprehensive view of all community members with tools for administration and role management.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Member List Display | View all community members with profiles and roles |
    | Role Assignment | Assign and modify member roles and permissions |
    | Member Search | Search and filter members by various criteria |
    | Member Actions | Remove, ban, or promote members |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `community` | `AmityCommunity` | The community object for member management |
    | `currentUser` | `AmityUser` | The current user for permission validation |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `member_management_page/*/*` | Page | Customize overall page theme and layout |
    | `member_management_page/*/member_list_item` | Component | Member list item styling |
    | `member_management_page/*/role_badge` | Element | Member role badge appearance |
    | `member_management_page/*/action_buttons` | Element | Member action button styling |
    | `member_management_page/*/search_bar` | Element | Member search interface styling |
    | `member_management_page/*/member_avatar` | Element | Member profile picture display |

    #### Code Examples

```swift iOS
let memberPage = AmityMemberManagementPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: memberPage)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeMemberManagementPage(community: AmityCommunity) {
    AmityMemberManagementPage(
        community = community,
        onMemberSelected = { member ->
            // Handle member profile navigation
        },
        onMemberAction = { action, member ->
            // Handle member actions (promote, remove, etc.)
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityMemberManagementPage } from '@amityco/ui-kit';

const MemberManagement = ({ community }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
    >
      <AmityMemberManagementPage
        community={community}
        onMemberAction={(action, member) => {
          // Handle member actions
        }}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget memberManagementPage(AmityCommunity community) {
  return AmityCommunityMembershipPage(
    community: community,
  );
}
```

    ### Navigation Behavior

```swift iOS
// Navigate to member profile
func navigateToMemberProfile(member: AmityUser) {
    let profilePage = AmityUserProfilePage(user: member)
    let viewController = AmitySwiftUIHostingController(rootView: profilePage)
    navigationController?.pushViewController(viewController, animated: true)
}

// Handle member actions
func handleMemberAction(action: MemberAction, member: AmityUser) {
    switch action {
    case .promote:
        // Promote member to moderator
        break
    case .remove:
        // Remove member from community
        break
    case .ban:
        // Ban member from community
        break
    }
}
```

```kotlin Android
// Navigate to member profile
fun navigateToMemberProfile(member: AmityUser) {
    val profilePage = AmityUserProfilePage(user = member)
    // Navigate to profile page
}

// Handle member actions
fun handleMemberAction(action: MemberAction, member: AmityUser) {
    when (action) {
        MemberAction.PROMOTE -> {
            // Promote member to moderator
        }
        MemberAction.REMOVE -> {
            // Remove member from community
        }
        MemberAction.BAN -> {
            // Ban member from community
        }
    }
}
```

```typescript React
// Handle member navigation
const handleMemberNavigation = (member) => {
    // Navigate to member profile
    navigate(`/profile/${member.userId}`);
};

// Handle member actions
const handleMemberAction = (action, member) => {
    switch (action) {
        case 'promote':
            // Promote member to moderator
            break;
        case 'remove':
            // Remove member from community
            break;
        case 'ban':
            // Ban member from community
            break;
    }
};
```

```dart Flutter
// Navigate to member profile
void navigateToMemberProfile(AmityUser member) {
    Navigator.push(
        context,
        MaterialPageRoute(
            builder: (context) => AmityUserProfilePage(userId: member.userId!),
        ),
    );
}

// Handle member actions
void handleMemberAction(MemberAction action, AmityUser member) {
    switch (action) {
        case MemberAction.promote:
            // Promote member to moderator
            break;
        case MemberAction.remove:
            // Remove member from community
            break;
        case MemberAction.ban:
            // Ban member from community
            break;
    }
}
```

    **Member invitation workflows and invitation tracking**

    Invitation Management components provide tools for inviting new members to communities, tracking invitation status, and managing invitation permissions.

    ### Community Invitation Page

    The community invitation page enables administrators to send invitations to new members and track invitation responses.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Send Invitations | Invite users by username, email, or user ID |
    | Invitation Status | Track sent, pending, and accepted invitations |
    | Bulk Invitations | Send multiple invitations simultaneously |
    | Invitation Limits | Respect community invitation limits and quotas |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `community` | `AmityCommunity` | The community object for invitation management |
    | `invitationLimit` | `Int` | Maximum number of invitations allowed |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `invitation_page/*/*` | Page | Invitation page theme and layout |
    | `invitation_page/*/send_button` | Element | Invitation send button styling |
    | `invitation_page/*/user_search` | Component | User search interface customization |
    | `invitation_page/*/invitation_status` | Component | Invitation status display styling |
    | `invitation_page/*/bulk_invite_section` | Component | Bulk invitation interface styling |
    | `invitation_page/*/invitation_limit_display` | Element | Invitation quota display styling |

    #### Code Examples

```swift iOS
let invitationPage = AmityCommunityInvitationPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: invitationPage)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeInvitationPage(community: AmityCommunity) {
    AmityCommunityInvitationPage(
        community = community,
        onInvitationSent = { users ->
            // Handle successful invitations
        },
        onInvitationError = { error ->
            // Handle invitation errors
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunityInvitationPage } from '@amityco/ui-kit';

const InvitationManagement = ({ community }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
    >
      <AmityCommunityInvitationPage
        community={community}
        onInvitationSent={(users) => {
          // Handle successful invitations
        }}
        onInvitationError={(error) => {
          // Handle invitation errors
        }}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// The Flutter UIKit exposes member addition through AmityCommunityAddMemberPage.
Widget addMemberPage(List<AmityUser> selectedUsers) {
  return AmityCommunityAddMemberPage(
    users: selectedUsers,
    onAddedAction: (users) {
      // Handle the selected users to add to the community
    },
  );
}
```

    ### Navigation Behavior

```swift iOS
// Handle invitation success
func handleInvitationSuccess(users: [AmityUser]) {
    // Show success message
    let alert = UIAlertController(
        title: "Invitations Sent",
        message: "Successfully invited \(users.count) users",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    present(alert, animated: true)
}

// Navigate to invitation status
func showInvitationStatus() {
    let statusPage = AmityInvitationStatusPage(community: community)
    let viewController = AmitySwiftUIHostingController(rootView: statusPage)
    navigationController?.pushViewController(viewController, animated: true)
}
```

```kotlin Android
// Handle invitation success
fun handleInvitationSuccess(users: List<AmityUser>) {
    // Show success message
    Toast.makeText(
        context,
        "Successfully invited ${users.size} users",
        Toast.LENGTH_SHORT
    ).show()
}

// Navigate to invitation status
fun showInvitationStatus() {
    val statusPage = AmityInvitationStatusPage(community = community)
    // Navigate to status page
}
```

```typescript React
// Handle invitation workflows
const handleInvitationWorkflow = {
    onSuccess: (users) => {
        // Show success notification
        showNotification(`Successfully invited ${users.length} users`);
    },
    onError: (error) => {
        // Handle invitation error
        showError(`Failed to send invitations: ${error.message}`);
    },
    showStatus: () => {
        // Navigate to invitation status page
        navigate('/community/invitations/status');
    }
};
```

```dart Flutter
// Handle invitation success
void handleInvitationSuccess(List<AmityUser> users) {
    ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
            content: Text('Successfully invited ${users.length} users'),
        ),
    );
}

// Navigate to the community membership page to review members
void showMembership(AmityCommunity community) {
    Navigator.push(
        context,
        MaterialPageRoute(
            builder: (context) => AmityCommunityMembershipPage(community: community),
        ),
    );
}
```

    **Join request handling, approval, and rejection workflows**

    Join Request Management components provide tools for reviewing and processing requests from users who want to join private or restricted communities.

    ### Pending Request Page (Join Requests)

    The pending request page handles join requests from users wanting to join the community. This is part of a larger component that also handles pending posts (documented in [Community Management](/uikit/components/social/community-management)).

    The Pending Request Page contains both **Join Requests** (membership-related) and **Pending Posts** (moderation-related). This section focuses on the join request functionality. For pending post moderation, see [Community Management](/uikit/components/social/community-management).

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Join Request List | View all pending requests to join the community |
    | Request Approval | Approve legitimate join requests |
    | Request Rejection | Decline inappropriate or spam requests |
    | User Profile Access | View requesting user profiles for review |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `community` | `AmityCommunity` | The community object for join request management |
    | `moderatorPermissions` | `Boolean` | Whether current user has moderator permissions |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `pending_request_page/*/*` | Page | Customize overall page theme and layout |
    | `pending_request_page/*/back_button` | Element | Customize back button appearance |
    | `pending_request_page/*/title` | Element | Customize page title text |
    | `pending_request_page/*/join_requests_section` | Component | Customize join requests section styling |
    | `pending_request_page/*/request_list` | Component | Join request list display styling |

    #### Code Examples

```swift iOS
// Focus on join request functionality of pending request page
let page = AmityPendingRequestPage(community: community)
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeJoinRequestManagement(community: AmityCommunity) {
    AmityPendingRequestPage(
        community = community,
        onJoinRequestAction = { action, request ->
            // Handle join request approval/rejection
            when (action) {
                is JoinRequestAction.Approve -> {
                    // Approve join request
                }
                is JoinRequestAction.Reject -> {
                    // Reject join request
                }
            }
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityPendingRequestPage } from '@amityco/ui-kit';

const JoinRequestManagement = ({ community }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
    >
      <AmityPendingRequestPage
        community={community}
        onJoinRequestAction={(action, request) => {
          // Handle join request actions
          if (action === 'approve') {
            // Approve join request
          } else if (action === 'reject') {
            // Reject join request
          }
        }}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget joinRequestManagement(AmityCommunity community) {
  return AmityPendingRequestPage(
    community: community,
  );
}
```

    ### Join Request Content Component

    The join request content component displays individual join requests with user information and approval controls.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | User Information | Display requesting user profile and details |
    | Request Actions | Approve or decline join requests |
    | Request History | View previous requests from the same user |
    | Bulk Actions | Process multiple requests simultaneously |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `pending_request_page/join_request_content/*` | Component | Customize component theme |
    | `pending_request_page/join_request_content/join_accept_button` | Element | Customize accept button text |
    | `pending_request_page/join_request_content/join_decline_button` | Element | Customize decline button text |

    #### Code Examples

```swift iOS
let component = AmityJoinRequestContentComponent(community: community)
let viewController = AmitySwiftUIHostingController(rootView: component)
```

```kotlin Android
@Composable
fun composeJoinRequestComponent(joinRequest: AmityJoinRequest) {
    AmityJoinRequestContentComponent(
        joinRequest = joinRequest,
        onAcceptAction = {
            // Handle accept action
        },
        onDeclineAction = {
            // Handle decline action
        }
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityJoinRequestContentComponent } from '@amityco/ui-kit';

const JoinRequestComponent = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}} // put your customized config json object
    >
      <AmityJoinRequestContentComponent
        pageId={'*'} // optional, default is '*'
        joinRequests={null} // join requests array, can be null
        isLoading={false} // loading state, default is false
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// The Flutter UIKit does not expose a standalone join request content widget.
// Join request content is rendered inside AmityPendingRequestPage.
Widget joinRequestComponent(AmityCommunity community) {
  return AmityPendingRequestPage(
    community: community,
  );
}
```

    ### Navigation Behavior

```swift iOS
// Handle join request approval
func approveJoinRequest(request: AmityJoinRequest) {
    // Approve the request
    request.approve { [weak self] result in
        DispatchQueue.main.async {
            switch result {
            case .success:
                // Show success message
                self?.showSuccessAlert("Join request approved")
            case .failure(let error):
                // Handle error
                self?.showErrorAlert("Failed to approve request: \(error.localizedDescription)")
            }
        }
    }
}

// Navigate to user profile
func showRequestingUserProfile(user: AmityUser) {
    let profilePage = AmityUserProfilePage(user: user)
    let viewController = AmitySwiftUIHostingController(rootView: profilePage)
    navigationController?.pushViewController(viewController, animated: true)
}
```

```kotlin Android
// Handle join request actions
fun handleJoinRequestAction(action: JoinRequestAction, request: AmityJoinRequest) {
    when (action) {
        is JoinRequestAction.Approve -> {
            // Approve join request
            request.approve()
                .subscribe(
                    {
                        // Show success message
                        showSuccessToast("Join request approved")
                    },
                    { error ->
                        // Handle error
                        showErrorToast("Failed to approve request: ${error.message}")
                    }
                )
        }
        is JoinRequestAction.Reject -> {
            // Reject join request
            request.reject()
        }
    }
}

// Navigate to user profile
fun showRequestingUserProfile(user: AmityUser) {
    val profilePage = AmityUserProfilePage(user = user)
    // Navigate to profile page
}
```

```typescript React
// Handle join request workflows
const handleJoinRequestWorkflow = {
    approve: async (request) => {
        try {
            await request.approve();
            showNotification('Join request approved successfully');
            // Refresh the request list
            refreshRequests();
        } catch (error) {
            showError(`Failed to approve request: ${error.message}`);
        }
    },
    reject: async (request) => {
        try {
            await request.reject();
            showNotification('Join request rejected');
            refreshRequests();
        } catch (error) {
            showError(`Failed to reject request: ${error.message}`);
        }
    },
    viewProfile: (user) => {
        // Navigate to user profile
        navigate(`/profile/${user.userId}`);
    }
};
```

```dart Flutter
// Handle join request approval
Future<void> approveJoinRequest(AmityJoinRequest request) async {
    try {
        await request.approve();
        ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Join request approved')),
        );
        // Refresh the request list
        refreshRequests();
    } catch (error) {
        ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Failed to approve request: $error')),
        );
    }
}

// Navigate to user profile
void showRequestingUserProfile(AmityUser user) {
    Navigator.push(
        context,
        MaterialPageRoute(
            builder: (context) => AmityUserProfilePage(userId: user.userId!),
        ),
    );
}
```

## Related Components

    **Core Community Features**
    Community setup, profiles, and content feeds
    **Settings & Administration**
    Community settings, permissions, and moderation tools
    **User Management**
    User profiles and social interactions
    **Moderation Tools**
    Content and user moderation features
    **Feed Components**
    Community content display and interaction
    **Post Components**
    Community post creation and management

**Implementation Strategy**: Start with the Member Management Page as your central hub for community administration, then implement invitation workflows to grow your community organically. Use the Pending Request Page to handle join requests efficiently, and configure approval processes based on your community's privacy and moderation requirements. Consider implementing automated invitation tracking and join request notifications to streamline membership management workflows. Focus on providing clear feedback for all membership actions and ensure smooth navigation between member profiles, invitation status, and approval interfaces.

---

### [Comments & Reactions](https://learn.social.plus/uikit/components/social/comments-reactions)

> Engagement features including threaded comments, emoji reactions, multiple reaction types, and real-time interactions

**Key Benefit**: Foster dynamic community engagement with comprehensive comment systems, emoji reactions, and real-time interaction features that encourage meaningful conversations and content discovery.

## Feature Overview

The Comments & Reactions UIKit provides comprehensive tools for building engaging comment systems and reaction features. From threaded conversations and reply management to emoji reactions and user interaction tracking, these components create the foundation for vibrant community discussions and content engagement.

    **Rich Conversations**
    - Threaded comment displays
    - Comment creation and editing
    - Reply management
    - Mention support in comments
    **Expressive Engagement**
    - Emoji reaction systems
    - Reaction list displays
    - Real-time reaction updates
    - Custom reaction support

    **Community Engagement**
    - Comment tray interfaces
    - Reaction picker components
    - User interaction tracking
    - Brand user comment support
    **Moderation Tools**
    - Comment reporting
    - Content moderation
    - User blocking capabilities
    - Administrative controls

## Platform Support

| Feature | iOS | Android | React | React Native | Flutter |
|---------|-----|---------|-------|---------------|---------|
| Create / Edit Comment | ✅ | ✅ | ✅ | ✅ | ✅ |
| View Comments | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report Comment | ✅ | ✅ | ✅ | ✅ | ✅ |
| Mention in Comments | ✅ | ✅ | ✅ | ✅ | ✅ |
| Comment Tray | ✅ | ✅ | ✅ | ❌ | ✅ |
| Brand User Comment | ✅ | ✅ | ✅ | ❌ | ✅ |
| Comment Ads | ✅ | ✅ | ✅ | ✅ | ❌ |
| Multi-Level Comment Replies (2-Level) | ✅ | ✅ | ✅ | ❌ | ❌ |
| Link Rendering in Comments | ✅ | ✅ | ✅ | ❌ | ❌ |
| Post / Comment / Story Reactions | ✅ | ✅ | ✅ | ✅ | ✅ |
| View Reactions | ✅ | ✅ | ✅ | ✅ | ✅ |
| Multiple Reactions | ✅ | ✅ | ✅ | ❌ | ❌ |

**Legend**: ✅ Full Support | ❌ Not Available

## Component Features

    **Interactive Comment Systems**

    - **Threaded Comments**: Nested reply conversations with two-level display model
    - **Comment Creation**: Rich text editing with mention support
    - **Comment Management**: Edit, delete, and report capabilities
    - **Link Rendering**: URLs in comment text are highlighted and tappable, opening the link target. Unlike posts, comments do not render link preview cards
    - **Real-time Updates**: Live comment synchronization

    **Expressive User Engagement**

    - **Emoji Reactions**: Pre-defined and custom emoji support
    - **Reaction Analytics**: User lists and engagement metrics
    - **Multiple Reactions**: Support for various reaction types
    - **Real-time Updates**: Instant reaction synchronization

    **Multi-Level Comment Reply System**

    - **Reply to any bubble**: Users can reply to L0 comments, L1 replies, or L2 replies
    - **Expand & Load More**: "View replies (n)" button to expand reply threads, "View more replies" for pagination (5 replies per page)
    - **Inline Edit**: Edit L1/L2 replies directly within the comment bubble
    - **Per-Level Deletion**: Soft-deleted L0 comments show placeholder; deleted L1/L2 replies are silently removed
    - **Notification Deep-Link**: Tapping a reply notification navigates to the post and display the specific reply

    **Enhanced Functionality**

    - **Mention System**: @username functionality with notifications
    - **Content Moderation**: Reporting and administrative controls
    - **Brand User Support**: Professional commenting capabilities
    - **Accessibility**: Screen reader and keyboard navigation support

## Multi-Level Comment Replies

The UIKit comment system supports a **two-level display model** for replies, enabling richer conversations while keeping the UI clean.

  <img src="/images/uikit/comments/comment-sheet-overview.png" alt="Comment sheet overlay showing top-level comments with reply and reaction options" style={{ maxWidth: '375px', margin: '0 auto', display: 'block' }} />

### Comment Hierarchy

| Level | Display | Reply Action |
|-------|---------|-------------|
| **Level 0 (L0)** | Top-level comment on a post/story | "Reply" creates an L1 reply |
| **Level 1 (L1)** | Direct reply to L0, indented under the parent | "Reply" creates an L2 reply |
| **Level 2 (L2)** | Reply to an L1 comment, indented under L1 | "Reply" creates another L2 reply (auto-resolved to L1 ancestor) |

  <img src="/images/uikit/comments/comment-sheet-threaded-replies.png" alt="Comment sheet showing L0, L1, and L2 reply hierarchy with View replies button" style={{ maxWidth: '375px', margin: '0 auto', display: 'block' }} />

**UIKit supports up to Level 2 only.** All replies beyond Level 1 are always displayed as Level 2. When a user taps "Reply" on an L2 comment, the UIKit automatically resolves the `parentId` to the L1 ancestor, so the new reply is created as another L2 sibling — never L3 or deeper.

When a user taps "Reply" on an L2 reply, the compose bar shows **"Replying to @[author-name]"** and pre-fills the text with `@[author-name]`. The reply is created under the L1 ancestor, not the L2 comment itself.

### Reply Thread Behavior

    **Paginated reply threads with progressive loading**

      <img src="/images/uikit/comments/post-detail-reply-expanded.png" alt="Post detail showing expanded reply threads with L1 and L2 replies and View more replies button" style={{ maxWidth: '375px', margin: '0 auto', display: 'block' }} />

    - When an L0 comment has replies, a **"View replies (n)"** button appears below it
    - Tapping it loads the first page of replies (5 per batch)
    - If more replies exist, a **"View more replies"** button appears at the end of the thread
    - L1 replies are sorted **newest first** (`lastCreated`)
    - L2 replies are sorted **oldest first** (`firstCreated`) for chronological reading

    **Contextual compose bar for replies**

      <img src="/images/uikit/comments/reply-compose-bar.png" alt="Reply compose bar showing Replying to banner with text input" style={{ maxWidth: '375px', margin: '0 auto', display: 'block' }} />

    - Tapping "Reply" on any comment bubble opens the compose bar with focus
    - A **"Replying to @[author]"** chip appears above the text field
    - The text field is pre-filled with `@[author-name] `
    - Tapping the **✕** dismiss button on the chip clears the reply context
    - Reply action is hidden for non-member users in communities (`shouldAllowCreation = false`)

    **Level-specific deletion rules**

    - **L0 soft delete**: Comment shows a placeholder ("This comment has been deleted") — child replies remain visible
    - **L1 delete**: Reply bubble is removed from the UI; L0 parent's reply count decrements
    - **L2 delete**: Only the L2 bubble is removed; L1 parent and sibling L2 replies remain


    **Edit replies directly within the bubble**

    - The bubble transforms into an editable text field with **Cancel** and **Save** buttons
    - Save is disabled if text is empty or unchanged

    **Deep-link from notification tray to specific replies**

    - Tapping a reply notification navigates to the post detail page
    - The screen displays the specific reply bubble with a brief highlight animation

  <img src="/images/uikit/comments/post-detail-multi-level-replies.png" alt="Post detail page showing expanded multi-level comment replies with L0, L1, L2 threading and View more replies" style={{ maxWidth: '375px', margin: '0 auto', display: 'block' }} />

### Limitations

- UIKit supports **up to Level 2** replies. All replies beyond Level 1 are always created and displayed as Level 2 — the UIKit never creates L3 or deeper comments.
- Reply threads load **5 replies per page** by default. This is not configurable through UIKit.

## Implementation Guide

    **Comprehensive comment interface with threading and reactions**

    The Comment Tray Component facilitates dynamic interaction through comments and reactions, designed to foster community engagement directly within content viewing experiences.

    ### Features

    | Feature | Description |
    |---------|-------------|
    | View, create or edit comments | Users can view, create or edit text comments or reply comments, and add reactions to comments |
    | Multi-level replies | Reply to any comment or reply (L0, L1, L2) with "Replying to" chip and @mention pre-fill |
    | Expand reply threads | "View replies (n)" button to expand reply threads with paginated loading (5 per batch) |
    | Inline edit | Edit L1/L2 replies directly within the comment bubble with Cancel/Save actions |
    | Per-level deletion | Soft-deleted L0 shows placeholder; deleted L1/L2 replies are silently removed |
    | Threaded conversations | Support for nested replies with a two-level display model |
    | Real-time updates | Live synchronization of comments and reactions |

    ### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `*/edit_comment_component/*` | Component | You can customize theme |
    | `*/edit_comment_component/cancel_button` | Element | You can customize button_text, icon and background_color |
    | `*/edit_comment_component/save_button` | Element | You can customize button_text, icon and background_color |
    | `*/comment_tray_component/*` | Component | You can customize close_icon |

    ### Code Examples

```swift iOS
// If you want to load comments of a post:
//     referenceId: "<post-id>"
//     referenceType: .post
// If you want to load comments of a story:
//     referenceId: "<story-id>"
//     referenceType: .story
let commentTrayComponent = AmityCommentTrayComponent(
    referenceId: "<story-id>",
    referenceType: .story,
    community: nil,
    shouldAllowInteraction: true,
    shouldAllowCreation: true
)
let viewController = AmitySwiftUIHostingController(rootView: commentTrayComponent)
```

```kotlin Android
@Composable
fun compose(
    storyId: String,
    community: AmityCommunity?,
) {
    // Allow user to interact like adding reaction with the story or not
    val shouldAllowInteraction = true

    // Allow user to create comment on the story or not
    val shouldAllowCreation = true

    // Available as Composable element
    AmityCommentTrayComponent(
        referenceId = storyId,
        referenceType = AmityCommentReferenceType.STORY,
        community = community, // optional
        shouldAllowInteraction = shouldAllowInteraction,
        shouldAllowCreation = shouldAllowCreation,
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityCommentTrayComponent } from '@amityco/ui-kit';

const SampleCommentTray = ({ referenceId, referenceType, community }) => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityCommentTrayComponent
        referenceId={referenceId}
        referenceType={referenceType}
        community={community}
        shouldAllowInteraction
        shouldAllowCreation
      />
    </AmityUIKitProvider>
  );
};
```

```dart Flutter
void viewInCommunityProfileStory({
  required String referenceId,
  AmityCommentReferenceType referenceType = AmityCommentReferenceType.STORY,
  required ScrollController parentScrollController,
}) {
  AmityCommentTrayComponent(
    referenceId: referenceId,
    referenceType: referenceType,
    shouldAllowComments: true,
    scrollController: parentScrollController,
    shouldAllowInteraction: true,
  );
}
```

    ### Navigation Behavior

    Custom navigation behavior can be implemented to enhance or modify the interaction flow on the AmityCommentTrayComponent.

```swift iOS
class CustomAmityCommentTrayComponentBehavior: AmityCommentTrayComponentBehavior {
    override init() {
        super.init()
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommentTrayBehaviour() {
    let customBehavior = CustomAmityCommentTrayComponentBehavior()
    AmityUIKit4Manager.behaviour.commentTrayComponentBehavior = customBehavior
}
```

```kotlin Android
class CustomCommentTrayComponentBehavior : AmityCommentTrayComponentBehavior() {

}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCommentTrayComponentBehavior()
    AmityUIKit4Manager.behavior.commentTrayComponentBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityCommentTrayComponent } from '@amityco/ui-kit';

const SampleCommentTray = ({ referenceId, referenceType, community }) => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityCommentTrayComponentBehavior: {
          goToUserProfile: ({ userId }) => {
            console.log('Navigate to user profile:', userId);
          },
        },
      }}
    >
      <AmityCommentTrayComponent
        referenceId={referenceId}
        referenceType={referenceType}
        community={community}
        shouldAllowInteraction
        shouldAllowCreation
      />
    </AmityUIKitProvider>
  );
};
```

    **Detailed reaction information and user engagement analytics**

    The Reaction List Component displays comprehensive information about users who have reacted to content and their specific reactions.

    ### Features

    | Feature | Description |
    |---------|-------------|
    | Reaction List | Users can view the list of users who reacted to the post with reaction details |
    | User Interaction | Navigate to user profiles from reaction lists |
    | Reaction Analytics | View reaction distribution and engagement metrics |

    ### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `*/reaction_list/*` | Theme | You can customize component theme |
    | `*/reaction_list/user_avatar_view` | Element | You can hide avatar image view |
    | `*/reaction_list/user_display_name` | Element | You can hide display name |
    | `*/reaction_list/reaction_image_view` | Element | You can hide reaction icon |

    ### Code Examples

```swift iOS
// Create reaction list component
let reactionListView = AmityReactionList(referenceId: "<post-id>", referenceType: .post)
let viewController = AmitySwiftUIHostingController(rootView: reactionListView)
```

```kotlin Android
@Composable
fun ReactionListSample(
    referenceType: AmityReactionReferenceType,
    referenceId: String
) {
    AmityReactionList(
        referenceType = referenceType,
        referenceId = referenceId
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityReactionListComponent } from '@amityco/ui-kit';

const SampleAmityReactionListComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityReactionListComponent
        referenceId="post-id"
        referenceType="post"
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityReactionListComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityReactionListComponent
    referenceId="7e93791379"
    referenceType="post"
    isModalVisible={true}
    onCloseModal={() => {}}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget postReactionList() {
  return AmityReactionList(
      referenceId: 'referenceId',
      referenceType: AmityReactionReferenceType.POST);
}
```

    ### Navigation Behavior

```swift iOS
class CustomAmityReactionListBehavior: AmityReactionListBehavior {
    override init() {
        super.init()
    }

    override func goToUserProfile(context: AmityReactionListBehavior.Context) {
        // Custom implementation for navigating to User Profile
    }
}

// Call this function to setup custom behaviour class in UIKit
func setReactionListBehaviour() {
    let customBehavior = CustomAmityReactionListBehavior()
    AmityUIKit4Manager.behaviour.reactionListBehavior = customBehavior
}
```

```kotlin Android
class CustomReactionListBehavior : AmityReactionListBehavior() {
    override fun goToUserProfile(context: Context, userId: String) {
        // Custom implementation for navigating to User Profile
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomReactionListBehavior()
    AmityUIKit4Manager.behavior.reactionListBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityReactionListComponent } from '@amityco/ui-kit';

const SampleReactionList = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
      pageBehavior={{
        AmityReactionListBehavior: {
          goToUserProfile: ({ userId }) => {
            console.log('Navigate to user profile:', userId);
          },
        },
      }}
    >
      <AmityReactionListComponent
        referenceId="post-id"
        referenceType="post"
      />
    </AmityUIKitProvider>
  );
};
```

    **Configurable reaction systems for enhanced user expression**

    The UIKit supports multiple reaction types for both posts and comments, allowing you to customize different reaction sets for social features and messaging features to match your community's engagement patterns.

    **Global Configuration**: These reaction configurations are set at the global level in AmityUIKitConfig.json and apply across all UIKit components automatically.

    ### Features

    | Feature | Description |
    |---------|-------------|
    | Dual Reaction Systems | Separate reaction configurations for social posts/comments and messaging features |
    | Custom Reaction Sets | Configure different emoji reactions for different contexts |
    | Global Configuration | Set once at the application level for consistent experience |
    | Cross-Platform Support | Consistent reaction experience across all supported platforms |

    ### Post/Comment Reactions Configuration

    Configure reactions specifically for social posts and comments:

```json
{
  "social_reactions": [
    {
      "name": "like",
      "image": "messageReactionLike"
    },
    {
      "name": "love",
      "image": "messageReactionHeart"
    },
    {
      "name": "fire",
      "image": "messageReactionFire"
    },
    {
      "name": "happy",
      "image": "messageReactionGrinning"
    },
    {
      "name": "sad",
      "image": "messageReactionSad"
    }
  ]
}
```

    ### Message Reactions Configuration

    Configure reactions specifically for direct messages and chat:

```json
{
  "message_reactions": [
    {
      "name": "heart",
      "image": "messageReactionHeart"
    },
    {
      "name": "like",
      "image": "messageReactionLike"
    },
    {
      "name": "fire",
      "image": "messageReactionFire"
    },
    {
      "name": "grinning",
      "image": "messageReactionGrinning"
    },
    {
      "name": "sad",
      "image": "messageReactionSad"
    }
  ]
}
```

    ### Configuration Benefits

    | Configuration Type | Use Case | Benefits |
    |-------------------|----------|----------|
    | **Social Reactions** | Posts and Comments | Optimized for community engagement and content interaction |
    | **Message Reactions** | Direct Messages and Chat | Tailored for conversational context and quick responses |
    | **Global Level** | Application-wide | Consistent experience across all components and features |

    ### Best Practices

        **Matching reactions to user context**

        Configure different reaction sets based on the interaction context. Use more expressive reactions for social posts and streamlined options for quick message responses. Consider your community's communication patterns when selecting reaction types.

        **maintaining coherent reaction experiences**

        Ensure reaction images and names are consistent across platforms. Use clear, universally understood emoji representations. Test reaction visibility and accessibility across different devices and screen sizes.

## Component Management Strategies

    **Creating engaging conversation experiences**

    Design comment systems that encourage meaningful dialogue while maintaining community standards. Implement clear threading, easy reply mechanisms, and intuitive editing capabilities. Consider moderation needs and user reporting flows early in design.

    **Optimizing reaction engagement**

    Choose reaction sets that match your community culture and content types. Implement clear visual feedback for user interactions and consider analytics to understand engagement patterns. Balance expressiveness with simplicity.


## Best Practices

    **Creating intuitive comment experiences**

    Design comment interfaces that encourage meaningful conversations while maintaining readability. Implement clear visual hierarchy for threaded discussions, provide easy access to reply and edit functions, and ensure comment moderation tools are readily available to maintain community standards.

    **Optimizing reaction engagement**

    Choose reaction sets that match your community culture and content types. Implement clear visual feedback for user interactions, consider analytics to understand engagement patterns, and balance expressiveness with simplicity to avoid overwhelming users.


## Related Components

    Explore post components that integrate with comment and reaction systems.
    Learn about feed components that display posts with comment and reaction previews.
    Understand user profile features that showcase comment and reaction activity.
    Discover community features that provide context for comments and reactions.

**Implementation Strategy**: Start with AmityCommentTrayComponent for comprehensive comment functionality, then add AmityReactionListComponent for detailed user engagement insights. Integrate reaction features gradually based on your community engagement goals and user feedback patterns.

---

### [Content Discovery & Search](https://learn.social.plus/uikit/components/social/content-discovery)

> Comprehensive search and discovery components for finding communities, users, and content across your social platform

**Key Benefit**: Provide powerful search and discovery capabilities that help users find relevant communities, content, and connections through intuitive interfaces and smart categorization.

## Feature Overview

The Content Discovery & Search UIKit provides comprehensive components for building robust search and exploration experiences. From global search functionality to category-based browsing and notification management, these components enable users to discover and connect with the content and communities that matter to them.

    **Universal Discovery**

    - Cross-platform search functionality
    - Real-time search suggestions
    - Multi-content type results
    - Search history and suggestions

    **Organized Exploration**

    - Category-based browsing
    - Community recommendations
    - Search result filtering
    - My communities management

    **Targeted Results**

    - Community and user search
    - Search result customization
    - Filter and sort options
    - Result relevance ranking

    **Stay Connected**

    - Notification tray management
    - Real-time updates
    - Notification categorization
    - User engagement tracking

## Implementation Guide

    **Comprehensive search across communities and users**

    The Global Search Page offers robust and intuitive search functionality, allowing users to search for and discover communities and users that match their interests and needs.

    ### Features

    | Feature | Description |
    | --- | --- |
    | Top Search Bar | Type search keyword and it will search across list of all communities and users. User results match display name only |
    | Community search result | Displays filtered communities, and clicks to open Community Profile Page |
    | User search result | Displays filtered users, and clicks to open User Profile Page |

    UIKit user search matches the keyword against display names only. User IDs and profile handles are not matched. If you need ID matching, call the SDK's user search directly with the `searchBy` option, as described in [Search and Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users).

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `social_global_search_page/*/*` | Page | You can customize page theme |

    ### Code Examples


```swift iOS
let socialGlobalSearchPage = AmitySocialGlobalSearchPage()
let viewController = AmitySwiftUIHostingController(rootView: socialGlobalSearchPage)
```

```kotlin Android
@Composable
fun composeSocialGlobalSearchPage() {
    AmitySocialGlobalSearchPage()
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmitySocialGlobalSearchPage } from '@amityco/ui-kit';

const SampleAmitySocialGlobalSearchPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmitySocialGlobalSearchPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmitySocialGlobalSearchPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmitySocialGlobalSearchPage />
</AmityUiKitProvider>
```

```dart Flutter
Widget socialGlobalSearchPage() {
  return AmitySocialGlobalSearchPage();
}
```


    ### Navigation Behavior


```swift iOS
class CustomAmitySocialGlobalSearchPageBehavior: AmitySocialGlobalSearchPageBehavior {
    override init() {
        super.init()
    }
}

// Call this function to setup custom behaviour class in UIKit
func setSocialGlobalSearchPageBehaviour() {
    let customBehavior = CustomAmitySocialGlobalSearchPageBehavior()
    AmityUIKit4Manager.behaviour.socialGlobalSearchPageBehavior = customBehavior
}
```

```kotlin Android
class CustomSocialGlobalSearchPageBehavior : AmitySocialGlobalSearchPageBehavior() {

}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomSocialGlobalSearchPageBehavior()
    AmityUIKit4Manager.behavior.socialGlobalSearchPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmitySocialGlobalSearchPage } from '@amityco/ui-kit';

const SampleAmitySocialGlobalSearchPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmitySocialGlobalSearchPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmitySocialGlobalSearchPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmitySocialGlobalSearchPage />
</AmityUiKitProvider>
```

    **Quick search component for any page**

    The Top Search Bar provides seamless search functionality, located at the top of the page for easy access with advanced filtering capabilities.

    ### Features

    | Feature | Description |
    | --- | --- |
    | Search | Type keyword to search and cancel searching |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `social_global_search_page/top_search_bar/*` | Component | You can customize component theme |
    | `social_global_search_page/top_search_bar/search_icon` | Element | You can customize icon |
    | `social_global_search_page/top_search_bar/clear_button` | Element | You can customize icon |
    | `social_global_search_page/top_search_bar/cancel_button` | Element | You can customize text |

    ### Code Examples


```swift iOS
let viewModel = AmityGlobalSearchViewModel()
let topSearchBarComponent = AmityTopSearchBarComponent(viewModel: viewModel)
let viewController = AmitySwiftUIHostingController(rootView: topSearchBarComponent)
```

```kotlin Android
@Composable
fun composeTopSearchBarComponent(
    viewModel: AmityGlobalSearchViewModel,
) {
    AmityTopSearchBarComponent(
        viewModel = viewModel
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityTopSearchBarComponent } from '@amityco/ui-kit';

const SampleAmityTopSearchBarComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityTopSearchBarComponent
        search={() => {}} // put your set search value here
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityTopSearchBarComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityTopSearchBarComponent
    setSearchValue={() => {}}
    searchType={TabName.Communities}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget topSearchBarComponent() {
  TextEditingController textController = TextEditingController();
  return AmityTopSearchBarComponent(
    textcontroller: textController,
  );
}
```

    **Specialized search result displays**

    Components for displaying filtered communities and users with clear layouts and interaction patterns.

    ### Community Search Result Component

    Displays a list of filtered communities that match search keywords.

    | Feature | Description |
    | --- | --- |
    | Communities list | A list of communities matching to search keyword |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `social_global_search_page/community_search_result/*` | Component | You can customize component theme |
    | `social_global_search_page/community_search_result/community_private_badge` | Element | You can customize icon |
    | `social_global_search_page/community_search_result/community_official_badge` | Element | You can customize icon |


```swift iOS
let viewModel = AmityGlobalSearchViewModel(searchType: .community)
let communitySerachResultComponent = AmityCommunitySearchResultComponent(viewModel: viewModel)
let viewController = AmitySwiftUIHostingController(rootView: communitySerachResultComponent)
```

```kotlin Android
@Composable
fun composeCommunitySearchResultComponent(
    viewModel: AmityGlobalSearchViewModel,
) {
    AmityCommunitySearchResultComponent(
        viewModel = viewModel,
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityCommunitySearchResultComponent } from '@amityco/ui-kit';

const SampleAmityCommunitySearchResultComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityCommunitySearchResultComponent
        isLoading={} //put your loading state type boolean
        communityCollection={} //put your community collection type array
        onLoadMore={() => {}} //put your load more function
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityCommunitySearchResultComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityCommunitySearchResultComponent
    searchResult={[{}] as (Amity.Community & Amity.User)[]}
    onNextPage={() => {}}
    searchType={TabName.Communities}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget communitySearchResultComponent({
  required ScrollController scrollController,
}) {
  AmityGlobalSearchViewModel viewModel = AmityGlobalSearchViewModel(
    searchType: AmityGlobalSearchType.community,
    scrollController: scrollController,
  );

  return AmityCommunitySearchResultComponent(
    viewModel: viewModel,
  );
}
```


    ### User Search Result Component

    Displays a list of filtered users that match search criteria.

    | Feature | Description |
    | --- | --- |
    | Users list | A list of users whose display name matches the search keyword |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `social_global_search_page/user_search_result/*` | Component | You can customize component theme |


```swift iOS
let viewModel = AmityGlobalSearchViewModel(searchType: .user)
let userSearchResultComponent = AmityUserSearchResultComponent(viewModel: viewModel)
let viewController = AmitySwiftUIHostingController(rootView: userSearchResultComponent)
```

```kotlin Android
@Composable
fun composeUserSearchResultComponent(
    viewModel: AmityGlobalSearchViewModel,
) {
    AmityUserSearchResultComponent(
        viewModel = viewModel,
    )
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityUserSearchResultComponent } from '@amityco/ui-kit';

const SampleAmityUserSearchResultComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityUserSearchResultComponent
        userCollection={} //put your user collection object
        isLoading={} //put your loading state
        onLoadMore={() => {}} //put your load more function
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityUserSearchResultComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityUserSearchResultComponent
    searchResult={[{}] as (Amity.Community & Amity.User)[]}
    onNextPage={() => {}}
  />
</AmityUiKitProvider>
```

```dart Flutter
Widget userSearchResultComponent() {
  ScrollController scrollController = ScrollController();

  AmityGlobalSearchViewModel viewModel = AmityGlobalSearchViewModel(
    searchType: AmityGlobalSearchType.user,
    scrollController: scrollController,
  );

  return AmityUserSearchResultComponent(
    viewModel: viewModel,
  );
}
```


    ### Navigation Behavior

    When users click on search results, they are seamlessly navigated to the appropriate detail pages.


```swift iOS
class CustomAmityCommunitySearchResultComponentBehavior: AmityCommunitySearchResultComponentBehavior {
    override init() {
        super.init()
    }

    override func goToCommunityProfilePage(context: AmityCommunitySearchResultComponentBehavior.Context) {
        // Custom implementation for navigatin to Community Profile Page
    }
}

// Call this function to setup custom behaviour class in UIKit
func setCommunitySearchResultComponentBehaviour() {
    let customBehavior = CustomAmityCommunitySearchResultComponentBehavior()
    AmityUIKit4Manager.behaviour.communitySearchResultComponentBehavior = customBehavior
}
```

```kotlin Android
class CustomCommunitySearchResultComponentBehavior :
    AmityCommunitySearchResultComponentBehavior() {

    override fun goToCommunityProfilePage(context: Context, community: AmityCommunity) {
        // custom implementation for navigating to Community Profile Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomCommunitySearchResultComponentBehavior()
    AmityUIKit4Manager.behavior.communitySearchResultComponentBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityCommunitySearchResultComponent } from '@amityco/ui-kit';

const SampleAmityCommunitySearchResultComponent = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityCommunitySearchResultComponent
        isLoading={} //put your loading state type boolean
        communityCollection={} //put your community collection type array
        onLoadMore={() => {}} //put your load more function
      />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityCommunitySearchResultComponent,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityCommunitySearchResultComponent
    searchResult={[{}] as (Amity.Community & Amity.User)[]}
    onNextPage={() => {}}
    searchType={TabName.Communities}
  />
</AmityUiKitProvider>
```

    **Personal community management**

    Specialized search functionality for users to find and manage their own communities with enhanced filtering options.

    ### Features

    | Feature | Description |
    | --- | --- |
    | Search Bar | Type search keyword and it will search across list of all communities and users |
    | Community search result | Displays filtered communities, and clicks to open Community Profile Page |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `my_communities_search_page/*/*` | Page | You can customize page theme |
    | `my_communities_search_page/*/community_private_badge` | Element | You can customize icon |
    | `my_communities_search_page/*/community_official_badge` | Element | You can customize icon |

    ### Code Examples


```swift iOS
let myCommunitySearchPage = AmityMyCommunitiesSearchPage()
let viewController = AmitySwiftUIHostingController(rootView: myCommunitySearchPage)
```

```kotlin Android
@Composable
fun composeMyCommunitiesSearchPage() {
    AmityMyCommunitiesSearchPage()
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityMyCommunitiesSearchPage } from '@amityco/ui-kit';

const SampleAmityMyCommunitiesSearchPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityMyCommunitiesSearchPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityMyCommunitiesSearchPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityMyCommunitiesSearchPage />
</AmityUiKitProvider>
```

```dart Flutter
Widget myCommunitySearchResultComponent() {
  return AmityMyCommunitiesSearchPage();
}
```


    ### Navigation Behavior


```swift iOS
class CustomAmityMyCommunitiesSearchPageBehavior: AmityMyCommunitiesSearchPageBehavior {
    override init() {
        super.init()
    }
}

// Call this function to setup custom behaviour class in UIKit
func setMyCommunitiesSearchPageBehaviour() {
    let customBehavior = AmityMyCommunitiesSearchPageBehavior()
    AmityUIKit4Manager.behaviour.myCommunitiesSearchPageBehavior = customBehavior
}
```

```kotlin Android
class CustomMyCommunitiesSearchPageBehavior : AmityMyCommunitiesSearchPageBehavior() {
    override fun goToCommunityProfilePage(context: Context, community: AmityCommunity) {
        // custom implementation for navigating to Community Profile Page
    }
}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomMyCommunitiesSearchPageBehavior()
    AmityUIKit4Manager.behavior.myCommunitiesSearchPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUIKitProvider, AmityMyCommunitiesSearchPage } from '@amityco/ui-kit';

const SampleAmityMyCommunitiesSearchPage = () => {
  return (
    <AmityUIKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={config}
    >
      <AmityMyCommunitiesSearchPage />
    </AmityUIKitProvider>
  );
};
```

```jsx React Native
import {
  AmityMyCommunitiesSearchPage,
  AmityUiKitProvider,
} from '@amityco/react-native-social-uikit';
import config from '../../uikit.config.json';

<AmityUiKitProvider
  configs={config}
  apiKey="API_KEY"
  apiRegion="API_REGION"
  userId="userId"
  displayName="displayName"
  apiEndpoint="https://api.{API_REGION}.amity.co"
>
  <AmityMyCommunitiesSearchPage />
</AmityUiKitProvider>
```

    **Organized content exploration**

    Components for category-based community discovery and organized content browsing.

    ### All Categories Page

    Provides users with an organized list of community categories for easy exploration and discovery.

    | Feature | Description |
    | --- | --- |
    | Community Categories | Displays list of community categories with support for pagination |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `all_categories_page/*/*` | Component | You can customize component theme |


```swift iOS
let page = AmityAllCategoriesPage()
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeAllCategoriesPage() {
    AmityAllCategoriesPage()
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityAllCategoriesPage } from '@amityco/ui-kit';

const SampleAmityAllCategoriesPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityAllCategoriesPage />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget allCategoriesPage() {
  return AmityAllCategoriesPage();
}
```


    ### Communities By Category Page

    Offers a quick way to view all communities within a selected category for efficient exploration.

    | Feature | Description |
    | --- | --- |
    | List of communities | Displays list of communities under a particular categories with pagination support |

    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `communities_by_category_page/*/*` | Component | You can customize component theme |


```swift iOS
let page = AmityCommunitiesByCategoryPage(categoryId: "<category-id>")
let viewController = AmitySwiftUIHostingController(rootView: page)
```

```kotlin Android
@Composable
fun composeCommunitiesByCatgoryPage(
    categoryId: String
) {
    AmityCommunitiesByCategoryPage(categoryId = categoryId)
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityCommunitiesByCategoryPage } from '@amityco/ui-kit';

const SampleAmityCommunitiesByCategoryPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityCommunitiesByCategoryPage categoryId="categoryId" />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget communitiesByCategoryPage(AmityCommunityCategory category) {
  return AmityCommunitiesByCategoryPage(category: category);
}
```

    **Centralized notification management**

    The Notification Tray enhances user engagement by providing a comprehensive history of notifications with automatic grouping and organization.

    ### Features

    The Notification Tray automatically creates and groups notification records for each user, ensuring they stay informed about relevant activities within their communities and encouraging deeper platform engagement.

    #### Event Creation Item

    When an event is created in a community, its members receive a notification tray item. The audience depends on the community type — events in **public** communities notify the whole network, while events in **private** communities notify community members only. Tapping the item opens the event detail page.

    #### Refresh Behavior & Data Freshness

    The notification tray — including the social home unread indicator (red dot) — is **not a real-time surface**. Two layers of latency stack up:

    1. **Server-side cache (SDK).** Tray items and the seen/unseen status are served from a short-lived server cache, so a newly triggered notification isn't immediately available to query.
    2. **UIKit polling.** The social home unread indicator re-checks the seen status on a fixed interval (approximately every 60 seconds) rather than streaming updates.

    Because these combine, a poll can land while the server cache still holds the previous value — in that case the change is only picked up on a **later** poll, so it can take up to roughly **two intervals** before a new notification lights or the dot appears in the tray. Opening the tray marks it seen and clears the dot immediately. Design for eventual consistency here, not instant updates.

    ### Code Examples


```swift iOS
let page = AmityNotificationTrayPage()
```

```kotlin Android
@Composable
fun composeNotificationTrayPage(modifier: Modifier = Modifier) {
    AmityNotificationTrayPage(modifier = modifier)
}

fun startAnActivity(
    context: Context,
) {
    val intent = AmityNotificationTrayPageActivity.newIntent(
        context = context,
    )
    context.startActivity(intent)
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityNotificationTrayPage } from '@amityco/ui-kit';

const SampleAmityNotificationTrayPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityNotificationTrayPage />
    </AmityUiKitProvider>
  );
};
```


    ### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `notification_tray_page/*/*` | Page | You can customize page theme |
    | `notification_tray_page/*/back_button` | Element | You can customize image |
    | `notification_tray_page/*/title` | Element | You can customize text |
    | `notification_tray_page/*/empty_notification` | Element | You can customize image and text |
    | `notification_tray_page/*/no_internet_connection` | Element | You can customize image and text |
    | `notification_tray_page/*/event_notification_item` | ListItem | Customize the Event Creation tray item |
    | `notification_tray_page/*/event_type_badge` | Element | Customize the event-type chip (`In-person` / `Virtual`) |

    ### Navigation Behavior

    The behavior can be customized to handle navigation to post detail, community profile, user profile, and event detail pages differently.


```swift iOS
// Default Behavior
let behaviour = AmityNotificationTrayPageBehavior()

// Custom Implementation
class CustomBehaviour: AmityNotificationTrayPageBehavior {

    override func goToPostDetailPage(context: AmityNotificationTrayPageBehavior.Context) {
        // Custom implementation
    }

    override func goToCommunityProfilePage(context: AmityNotificationTrayPageBehavior.Context) {
        // Custom implementation
    }

    override func goToEventDetailPage(context: AmityNotificationTrayPageBehavior.Context) {
        // Custom implementation — invoked when the user taps an Event Creation item
    }
}

// Usage
AmityUIKit4Manager.behaviour.notificationTrayPageBehavior = CustomBehaviour()
```

```kotlin Android
class CustomNotificationTrayPageBehavior : AmityNotificationTrayPageBehavior() {

    override fun goToPostDetailPage(
        context: Context,
        postId: String,
        category: AmityPostCategory,
        commentId: String?,
        parentId: String?,
    ) {
        super.goToPostDetailPage(context, postId, category, commentId, parentId)
    }

    override fun goToCommunityProfilePage(
        context: Context,
        communityId: String,
    ) {
        super.goToCommunityProfilePage(context, communityId)
    }

    override fun goToEventDetailPage(
        context: Context,
        eventId: String,
    ) {
        super.goToEventDetailPage(context, eventId)
    }

}

// Call this function in AmityUIKit4Manager class to setup custom behaviour class in UIKit
fun setCustomBehavior() {
    val customBehaviour = CustomNotificationTrayPageBehavior()
    AmityUIKit4Manager.behavior.notificationTrayPageBehavior = customBehaviour
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityNotificationTrayPage } from '@amityco/ui-kit';

const SampleAmityNotificationTrayPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityNotificationTrayPageBehavior: {
          goToPostDetailPage: ({ postId, hideTarget, category, commentId, parentId }) => {
            console.log('goToPostDetailPage', postId, hideTarget, category, commentId, parentId);
          },
          goToCommunityProfilePage: ({ communityId }) => {
            console.log('goToCommunityProfilePage', communityId);
          },
          goToUserProfilePage: ({ userId }) => {
            console.log('goToUserProfilePage', userId);
          },
          goToEventDetailPage: ({ eventId }) => {
            console.log('goToEventDetailPage', eventId);
          },
        },
      }}
    >
      <AmityNotificationTrayPage />
    </AmityUIKitProvider>
  );
};
```


## Component Management Strategies

    **Designing comprehensive search experiences**

    Plan your search implementation by combining global search with specialized components like top search bars and category browsing. Consider user search patterns and how users move from general exploration to specific discovery.

    **Optimizing discovery pathways**

    Design clear pathways between different discovery methods (search, categories, recommendations). Ensure users can easily navigate between global search, category browsing, and their personal communities.

    **Managing user engagement**

    Implement thoughtful notification policies that keep users engaged without overwhelming them. Use notification grouping and smart categorization to provide relevant information at the right time.

## Implementation Strategy

    **Building comprehensive search features**

    Start with basic global search functionality, then add specialized search components for communities and users. Implement category-based discovery and notification management as your platform grows and user needs become more sophisticated.

    **Designing intuitive discovery paths**

    Plan search and discovery flows that guide users from general exploration to specific content discovery. Design clear navigation patterns between different search contexts and ensure smooth transitions between discovery and engagement.

    **Optimizing search experiences**

    Implement efficient search result caching, progressive loading for large result sets, and appropriate debouncing for real-time search suggestions. Consider indexing strategies and result relevance algorithms for optimal user experience.

## Best Practices

    **Creating effective search interfaces**

    Design clear search flows with intuitive filtering and sorting options. Provide helpful empty states, search suggestions, and clear result categorization. Ensure search interfaces are accessible and provide feedback for user actions.

    **Facilitating content exploration**

    Balance algorithmic recommendations with user-controlled discovery. Provide multiple pathways for content discovery (search, categories, recommendations) and help users understand why certain content is being suggested.

    **Respecting user attention**

    Implement thoughtful notification policies that respect user preferences and attention. Provide granular notification controls, smart batching for related notifications, and clear visual hierarchy for different notification types.

## Related Features

    **Content Streams** Social feeds and content discovery components

    **Community Features** Community creation and management tools

    **Messaging Features** Real-time chat and communication tools

  **Implementation Strategy**: Begin with AmityGlobalSearchPage for comprehensive search functionality, then add specialized components like AmityTopSearchBar and category browsing based on your users' discovery patterns and engagement metrics.

---

### [Discovery Widget](https://learn.social.plus/uikit/components/social/discovery-widget)

> Bring topic-based community conversations to your app's browsing surfaces with a ready-made carousel.

**Discovery Widget brings topic-based content discovery to the pages people already visit.** It helps brands and community teams surface relevant conversations on homepages, category pages, and other browsing surfaces, so users can discover the value of a community without first searching for it.

Your team configures a topic in the social.plus Console, then your app uses that topic's ID to display recommended community posts. Post previews and reaction and comment counts help readers decide what to explore. Your app controls where a selected post opens, providing a route into the conversation and community.

Discovery Widget is supported on **iOS**, **Android**, and **Web**. Flutter and React Native are not supported.

## How it works

The widget fetches an ordered selection of posts for its configured topic and displays them in a read-only carousel. Readers can browse previews and select a card. Reacting, commenting, voting, and media playback happen outside the widget, at the destination your app provides.

Recommendations use topic relevance as the main signal, with post engagement and freshness helping order relevant conversations. They are based on the topic rather than the reader's personal interests. Eligibility rules and viewer-specific restrictions, such as blocked authors, can affect which posts appear. See [Topic-based content discovery](/social-plus-sdk/social/discovery-engagement/feed/curated-content) for the SDK integration.

## Before you start

Configure a topic in the social.plus Console and obtain its topic ID. Set up your app's UIKit integration and establish a [user session](/social-plus-sdk/getting-started/authentication) or a [visitor session](/social-plus-sdk/getting-started/visitor-mode) before displaying the widget.

Choose where a card should open in your app, such as a post detail page or your hosted community.

## Embed the widget

Pass a topic ID and handle card selection with `onCardClick`.


```tsx Web
import { AmityDiscoveryWidgetComponent } from '@amityco/ui-kit';

<AmityDiscoveryWidgetComponent
  topicId="your-topic-id"
  onCardClick={(topicId, post) => {
    // Navigate to the selected post in your app.
  }}
/>
```

```swift iOS
AmityDiscoveryWidgetComponent(
    topicId: "your-topic-id",
    onCardClick: { topicId, post in
        // Navigate to the selected post in your app.
    }
)
```

```kotlin Android
AmityDiscoveryWidgetComponent(
    topicId = "your-topic-id",
    onCardClick = { topicId, post ->
        // Navigate to the selected post in your app.
    },
)
```


### Parameters

| Parameter | Type | Default | Platforms | Description |
| --- | --- | --- | --- | --- |
| `topicId` | string | Required | iOS, Android, Web | The topic ID configured in the Console. |
| `showHeader` | boolean | `true` | iOS, Android, Web | Show the topic heading and navigation controls where supported. |
| `minVisibilityThreshold` | number | `3` | iOS, Android, Web | Minimum number of renderable posts needed to show the widget. Values below 1 are clamped to 1. |
| `onCardClick` | callback | None | iOS, Android, Web | Receives the topic ID and selected post. Overrides the behavior class for this instance. |
| `pageId` | `PageId?` / string | `nil` / `'*'` | iOS, Web | Page identifier for customization scoping. |
| `pageScope` | `AmityComposePageScope?` | `null` | Android | Compose page scope for customization. |
| `modifier` | `Modifier` | `Modifier` | Android | Standard Compose modifier. |

## Display behavior

The widget adapts to compact and expanded layouts. Readers swipe through cards; Web and Android also provide navigation arrows in the expanded layout.

The widget renders nothing when the request fails or the number of renderable posts is below `minVisibilityThreshold`. It shows no heading, empty state, or error message in these cases. Avoid a separate decorative container that would remain visible when the widget hides.

### Host container

The widget sizes itself from its content and does not set a height on its parent. Place it in a container that fits it:

- Use a wrap-content container, or give the container a minimum height that fits the widget. A shorter container clips the cards, starting with the reaction and comment counts at the bottom.
- Avoid a container with zero or undefined height. The widget still loads posts and reports its impression, but readers can't see it.
- Place the widget in a vertically scrolling or non-scrolling container. A horizontally scrolling parent is not supported, because the widget's own horizontal scrolling competes with it for swipes.

### Supported content

| Post type | Display |
| --- | --- |
| Text | Text preview |
| Image | First attachment preview |
| Video or clip | First attachment preview with a play indicator |
| Poll | Read-only results preview |
| Livestream or room | Not rendered |

Unsupported posts do not count toward the visibility threshold. For example, a response with four posts, including two unsupported posts, has only two renderable posts and remains hidden at the default threshold.

Each card shows author and community information, a content preview, and reaction and comment counts. A card is one tap target: mentions, hashtags, links, and preview labels do not have separate actions. Media does not play inside the card, and readers cannot vote in a poll preview.

## Handle card selection

Use `onCardClick` for navigation specific to one placement. For app-wide navigation, override the platform's behavior class instead:

| Platform | Behavior |
| --- | --- |
| Web | `AmityDiscoveryWidgetComponentBehavior.goToDestination({ topicId, post })` |
| Android | `AmityDiscoveryWidgetComponentBehavior.goToDestination(context, topicId, post)` |
| iOS | `AmityDiscoveryWidgetComponentBehavior.goToDestination(context)` |

When `onCardClick` is provided, the behavior class is not called for that instance.

No platform has a default destination. If you provide neither `onCardClick` nor a behavior override, selecting a card does nothing. Provide a navigation handler so a card opens the intended content.

## Analytics

The widget automatically reports its impression, visible post-card impressions, and card clicks. It reports each impression once per page load and reports clicks when readers select cards. You do not need to call the SDK analytics methods again for the widget.

If you build a custom discovery surface with the SDK, report these interactions yourself. See [Report interactions](/social-plus-sdk/social/discovery-engagement/feed/curated-content#report-interactions).

## Customization

Use component parameters to control the topic, header, visibility threshold, and card navigation. The widget uses your app's UIKit theme. See [UIKit customization](/uikit/customization/overview) for general theming guidance.

## Build your own discovery surface

Use the [SDK's topic-based content discovery APIs](/social-plus-sdk/social/discovery-engagement/feed/curated-content) when you need a presentation other than the ready-made carousel. They return standard post objects and topic analytics handles so your app can render recommendations and measure interactions.

---

### [Users](https://learn.social.plus/uikit/components/social/users)

> User profiles, relationships, and social interactions including follow system and user management

**UIKit Component**: User components are built on top of the social.plus SDK,
  providing ready-to-use user profile and relationship management UI with full
  data management handled automatically.

## Feature Overview

The **User** feature in social.plus UIKit v4 provides a comprehensive suite of components designed to manage user profiles, relationships, and interactions within your application. It encompasses functionalities ranging from profile display and editing to managing blocked users and follow requests, ensuring a seamless and engaging user experience.

### Key Features

    **Comprehensive user profile management**
    - User profile page with avatar, display name, and bio
    - User feed components with flexible feed source switching (personal, community, or combined feeds)
    - User profile header with relationship controls
    - Post creation and interaction capabilities
    - Comprehensive activity views across personal and community content
    **Profile editing and customization**
    - Edit user profile details and avatar
    - Update display name and bio information
    - Profile personalization and management
    - Privacy settings and controls
    **Follow system and relationship management**
    - Follow/unfollow user interactions
    - Followers and following lists management
    - Pending follow request handling
    - User blocking and unblocking functionality
    **User safety and privacy controls**
    - Blocked users management
    - Follow request approval system
    - User reporting and safety features
    - Privacy-based content access control

## Implementation Guide

    **User profile pages and feed components for displaying user information and content**

    User Profile components provide comprehensive tools for displaying user information, managing user feeds, and handling user interactions within the social platform.

    ### User Profile Page

    The user profile page displays user information, follow relationships, following and followers count, manages blocked users, enables profile editing, handles follow requests, shows created post feeds, and provides post creation actions.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | User Information | Display user name, description, following and follower count |
    | Follow Request | User can accept or decline follow request from other users |
    | User Feed | Display post, image and video feed posts created by the user |
    | Post Creation | Allow user to create a post on own timeline |
    | Other User Information | User can view other user profile and can follow/unfollow/block that user |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `userId` | `String` | The user ID for the profile to display |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/*/*` | Page | Customize page theme |
    | `user_profile_page/*/back_button` | Element | Customize back button image |
    | `user_profile_page/*/menu_button` | Element | Customize menu button image |
    | `user_profile_page/*/user_feed_tab_button` | Element | Customize user feed tab image |
    | `user_profile_page/*/user_image_feed_tab_button` | Element | Customize image feed tab image |
    | `user_profile_page/*/user_video_feed_tab_button` | Element | Customize video feed tab image |

    #### Code Examples

```swift iOS
let page = AmityUserProfilePage(userId: "user-id")
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeUserProfilePage(userId: String) {
    AmityUserProfilePage(
        userId = userId
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityUserProfilePage } from '@amityco/ui-kit';

const UserProfile = ({ userId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityUserProfilePageBehavior: {
          goToEditUserPage: (context) => {
            // Navigate to edit profile page
          },
          goToBlockedUsersPage: () => {
            // Navigate to blocked users page
          },
          goToPostComposerPage: (context) => {
            // Navigate to post composer
          },
        },
      }}
    >
      <AmityUserProfilePage userId={userId} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget userProfilePage(String userId) {
  return AmityUserProfilePage(userId: userId);
}
```

    ### User Profile Header Component

    The User Profile Header component displays user information, follow relationship, following and followers count, and handles follow request acceptance or decline.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | User Information | Display user name, description, following and follower count |
    | Follow Request | User can accept or decline follow request from other users |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `user` | `AmityUser` | The user object for the profile header |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/user_profile_header/*` | Component | Customize component theme |
    | `user_profile_page/user_profile_header/follow_user_button` | Element | Customize follow button text and image |
    | `user_profile_page/user_profile_header/following_user_button` | Element | Customize following button text and image |
    | `user_profile_page/user_profile_header/unblock_user_button` | Element | Customize unblock button text and image |
    | `user_profile_page/user_profile_header/user_following` | Element | Customize following count text |
    | `user_profile_page/user_profile_header/user_follower` | Element | Customize follower count text |

    #### Code Examples

```swift iOS
let component = AmityUserProfileHeaderComponent(user: user)
let viewController = AmitySwiftUIHostingController(rootView: component)
```

```kotlin Android
@Composable
fun composeUserProfileHeader(user: AmityUser) {
    AmityUserProfileHeaderComponent(
        user = user
    )
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityUserProfileHeaderComponent } from '@amityco/ui-kit';

const UserProfileHeader = ({ user }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityUserProfileHeaderComponentBehavior: {
          goToPendingFollowRequestPage: () => {
            // Navigate to pending follow requests
          },
          goToUserRelationshipPage: (context) => {
            // Navigate to relationship page
          },
        },
      }}
    >
      <AmityUserProfileHeaderComponent user={user} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget userProfileHeaderComponent(AmityUser user) {
  return AmityUserProfileHeaderComponent(user: user);
}
```

    ### User Feed Components

    User feed components display different types of content created by users, including general posts, images, and videos. The enhanced user feed now provides comprehensive activity views with the ability to switch between personal posts, community posts, or combined feeds for a complete picture of user activity across the platform.

    #### User Feed Component

    The User Feed Component displays a comprehensive list of user posts with an integrated filter dropdown to toggle between different feed sources, providing users with the ability to switch between personal posts, community posts, or a combined view.

    **SDK Integration**: This component uses the [Get User Feed API](/social-plus-sdk/social/discovery-engagement/feed/overview) to query user posts with configurable feed sources. Refer to the API documentation for detailed implementation and privacy rules.

    **UIKit Features:**
    - **Feed Source Switching**: Pre-built filter dropdown with three options: "All Posts" (combined), "Community Posts", "Profile Posts"
    - **Community Context Display**: Automatic community context display (name, avatar, moderator badges) for community posts
    - **Privacy-Aware Content**: Respects user privacy settings and community visibility rules
    - **Built-in Navigation**: Navigation handlers for community profiles and original post contexts
    - **Real-time Updates**: Live synchronization of content changes across all feed sources
    - **Comprehensive Activity View**: Unified display of user activity across personal and community content

    **Features:**
    | Feature | Description |
    |---------|-------------|
    | Comprehensive User Activity | Display comprehensive user activity across personal and community content |
    | Feed Source Switching | Toggle between personal posts, community posts, or combined feed view |
    | Community Context | Show community context for posts (name, avatar, moderator badges) |
    | Privacy-Aware Display | Respect user privacy settings and community visibility rules |
    | Real-time Updates | Live synchronization of content changes across all feed sources |

    **Customization Options:**
    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/user_feed/*` | Component | Customize component theme |
    | `user_profile_page/user_feed/empty_user_feed` | Element | Customize empty state text and image |
    | `user_profile_page/user_feed/private_user_feed` | Element | Customize private feed text and image |
    | `user_profile_page/user_feed/blocked_user_feed` | Element | Customize blocked user feed text and image |

    #### User Image Feed Component

    The User Image Feed Component displays a list of images from posts created by the user, providing a visual gallery experience with navigation to original posts.

    **Features:**
    | Feature | Description |
    |---------|-------------|
    | Image Gallery | Display user's image posts in gallery format |
    | Original Post Navigation | Tap on gallery images to navigate to their original posts |

    **Customization Options:**
    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/user_image_feed/*` | Component | Customize component theme |
    | `user_profile_page/user_image_feed/empty_user_image_feed` | Element | Customize empty state text and image |
    | `user_profile_page/user_image_feed/private_user_image_feed` | Element | Customize private feed text and image |

    #### User Video Feed Component

    The User Video Feed Component displays a list of videos from posts created by the user, offering a dedicated video content experience with navigation to original posts.

    **Features:**
    | Feature | Description |
    |---------|-------------|
    | Video Gallery | Display user's video posts in gallery format |
    | Original Post Navigation | Tap on gallery videos to navigate to their original posts |

    **Customization Options:**
    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/user_video_feed/*` | Component | Customize component theme |
    | `user_profile_page/user_video_feed/empty_user_video_feed` | Element | Customize empty state text and image |
    | `user_profile_page/user_video_feed/private_user_video_feed` | Element | Customize private feed text and image |

    #### Code Examples

```swift iOS
// User Feed Component
let userFeed = AmityUserFeedComponent(userId: "user-id")

// User Image Feed Component
let imageFeed = AmityUserImageFeedComponent(userId: "user-id")

// User Video Feed Component
let videoFeed = AmityUserVideoFeedComponent(userId: "user-id")

let viewController = AmitySwiftUIHostingController(rootView: userFeed)
```

```kotlin Android
@Composable
fun composeUserFeeds(userId: String) {
    // User Feed Component
    AmityUserFeedComponent(userId = userId)

    // User Image Feed Component
    AmityUserImageFeedComponent(userId = userId)

    // User Video Feed Component
    AmityUserVideoFeedComponent(userId = userId)
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityUserFeedComponent,
  AmityUserImageFeedComponent,
  AmityUserVideoFeedComponent
} from '@amityco/ui-kit';

const UserFeeds = ({ userId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      {/* User Feed Component */}
      <AmityUserFeedComponent userId={userId} />

      {/* User Image Feed Component */}
      <AmityUserImageFeedComponent userId={userId} />

      {/* User Video Feed Component */}
      <AmityUserVideoFeedComponent userId={userId} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// User Feed Component
Widget userFeedComponent(String userId) {
  return UserFeedComponent(userId: userId);
}

// User Image Feed Component
Widget userImageFeedComponent(String userId) {
  return UserImageFeedComponent(userId: userId);
}

// User Video Feed Component
Widget userVideoFeedComponent(String userId) {
  return UserVideoFeedComponent(userId: userId);
}
```

    ### Navigation Behavior

```swift iOS
// User Profile Page Navigation
class CustomUserProfilePageBehavior: AmityUserProfilePageBehavior {
    override init() {
        super.init()
    }

    override func goToEditUserPage(context: AmityUserProfilePageBehavior.Context) {
        // Navigate to edit profile page
    }

    override func goToBlockedUsersPage(context: AmityUserProfilePageBehavior.Context) {
        // Navigate to blocked users page
    }

    override func goToPostComposerPage(context: AmityUserProfilePageBehavior.Context) {
        // Navigate to post composer
    }
}

// User Profile Header Navigation
class CustomUserProfileHeaderComponentBehavior: AmityUserProfileHeaderComponentBehavior {
    override func goToUserRelationshipPage(context: AmityUserProfileHeaderComponentBehavior.Context) {
        // Navigate to relationship page
    }

    override func goToPendingFollowRequestPage(context: AmityUserProfileHeaderComponentBehavior.Context) {
        // Navigate to pending follow requests
    }
}
```

```kotlin Android
// User Profile Page Navigation
class CustomAmityUserProfilePageBehavior : AmityUserProfilePageBehavior() {
    override fun goToEditUserPage(context: Context) {
        // Navigate to edit profile page
    }

    override fun goToBlockedUsersPage(context: Context) {
        // Navigate to blocked users page
    }

    override fun goToPostComposerPage(context: Context) {
        // Navigate to post composer
    }
}

// User Profile Header Navigation
class CustomAmityUserProfileHeaderComponentBehavior : AmityUserProfileHeaderComponentBehavior() {
    override fun goToUserRelationshipPage(context: Context) {
        // Navigate to relationship page
    }

    override fun goToPendingFollowRequestPage(context: Context) {
        // Navigate to pending follow requests
    }
}
```

```typescript React
// Navigation handled through pageBehavior props
const handleUserProfileNavigation = {
  goToEditUserPage: (context) => {
    // Navigate to edit profile page
    navigate('/profile/edit');
  },
  goToBlockedUsersPage: () => {
    // Navigate to blocked users page
    navigate('/profile/blocked-users');
  },
  goToPostComposerPage: (context) => {
    // Navigate to post composer
    navigate('/post/create');
  }
};

const handleUserHeaderNavigation = {
  goToPendingFollowRequestPage: () => {
    // Navigate to pending follow requests
    navigate('/profile/follow-requests');
  },
  goToUserRelationshipPage: (context) => {
    // Navigate to relationship page
    navigate(`/profile/${context.userId}/relationships`);
  }
};
```

```dart Flutter
// User Profile Page Navigation
void handleUserProfileNavigation(String action, dynamic context) {
  switch (action) {
    case 'goToEditUserPage':
      Navigator.push(
        context,
        MaterialPageRoute(builder: (context) => EditUserProfilePage()),
      );
      break;
    case 'goToBlockedUsersPage':
      Navigator.push(
        context,
        MaterialPageRoute(builder: (context) => BlockedUsersPage()),
      );
      break;
    case 'goToPostComposerPage':
      Navigator.push(
        context,
        MaterialPageRoute(builder: (context) => PostComposerPage()),
      );
      break;
  }
}
```

    **Profile editing and user management features**

    Profile Management components enable users to update their personal information, customize their profiles, and manage their account settings.

    ### Edit User Profile Page

    The Edit User Profile Page allows users to update their avatar image, display name, and about information.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Edit User Profile | Update avatar image, display name or about information |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `userId` | `String` | The user ID for the profile to edit (optional for current user) |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `edit_user_profile_page/*/*` | Page | Customize page theme |
    | `edit_user_profile_page/*/back_button` | Element | Customize back button image |
    | `edit_user_profile_page/*/title` | Element | Customize page title text |
    | `edit_user_profile_page/*/user_display_name_title` | Element | Customize display name field title |
    | `edit_user_profile_page/*/user_about_title` | Element | Customize about field title |
    | `edit_user_profile_page/*/update_user_profile_button` | Element | Customize update button text |

    #### Code Examples

```swift iOS
let page = AmityEditUserProfilePage()
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeEditUserProfilePage() {
    AmityEditUserProfilePage()
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityEditUserProfilePage } from '@amityco/ui-kit';

const EditUserProfile = ({ userId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEditUserProfilePage userId={userId} />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget editUserProfilePage(String userId) {
  return AmityEditUserProfilePage(userId: userId);
}
```

    ### Navigation Behavior

```swift iOS
// Profile editing typically navigates back to profile page
func handleProfileUpdateSuccess() {
    // Navigate back to user profile
    navigationController?.popViewController(animated: true)
}

func handleProfileUpdateError(error: Error) {
    // Show error alert
    let alert = UIAlertController(
        title: "Update Failed",
        message: error.localizedDescription,
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    present(alert, animated: true)
}
```

```kotlin Android
// Profile editing navigation
fun handleProfileUpdate(success: Boolean, error: String? = null) {
    if (success) {
        // Navigate back to profile
        findNavController().popBackStack()
    } else {
        // Show error message
        Toast.makeText(context, "Update failed: $error", Toast.LENGTH_SHORT).show()
    }
}
```

```typescript React
// Profile management navigation
const handleProfileManagement = {
    onUpdateSuccess: () => {
        // Navigate back to profile
        navigate(-1); // Go back
        showNotification('Profile updated successfully');
    },
    onUpdateError: (error) => {
        // Show error message
        showError(`Failed to update profile: ${error.message}`);
    }
};
```

```dart Flutter
// Profile editing navigation
void handleProfileUpdate(bool success, [String? error]) {
    if (success) {
        Navigator.pop(context);
        ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Profile updated successfully')),
        );
    } else {
        ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Update failed: ${error ?? "Unknown error"}')),
        );
    }
}
```


    **Follow system, blocked users, and relationship management**

    Social Relationship components handle user-to-user connections, including following/unfollowing, blocking/unblocking, and managing follow requests.

    ### User Relationship Page

    The User Relationship Page displays lists of users following the current user and users followed by the current user, with options to manage these relationships.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Following list | Display a list of users that the current user is following |
    | Follower list | Display a list of users that are following the current user |
    | User Action | User can report or block the selected user |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `userId` | `String` | The user ID for the relationship page |
    | `selectedTab` | `Tab` | The default selected tab (following or follower) |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_relationship_page/*/*` | Page | Customize page theme |

    #### Code Examples

```swift iOS
// selectedTab - .following or .follower based on the default selected tab you want
let page = AmityUserRelationshipPage(userId: "user-id", selectedTab: .following)
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeUserRelationshipPage(userId: String) {
    AmityUserRelationshipPage(
        userId = userId,
        selectedTab = AmityUserRelationshipPageTab.FOLLOWING
    )
}
```

```typescript React
import React from 'react';
import {
  AmityUiKitProvider,
  AmityUserRelationshipPage,
  AmityUserRelationshipPageTabs,
} from '@amityco/ui-kit';

const UserRelationships = ({ userId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityUserRelationshipPageBehavior: {
          goToUserProfilePage: (context) => {
            // Navigate to user profile
            navigate(`/profile/${context.userId}`);
          },
        },
      }}
    >
      <AmityUserRelationshipPage
        userId={userId}
        selectedTab={AmityUserRelationshipPageTabs.FOLLOWING}
      />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget getUserRelationshipPage(String userId) {
  return AmityUserRelationshipPage(
    userId: userId,
    selectedTab: AmityUserRelationshipPageTab.follower
  );
}
```

    ### Blocked User Page

    The Blocked User Page displays a list of users blocked by the current user, with options to unblock them.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Blocked Users | Display a list of blocked users |
    | Unblock User | User can unblock other users |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `blocked_users_page/*/*` | Page | Customize page theme |
    | `blocked_users_page/*/back_button` | Element | Customize back button image |
    | `blocked_users_page/*/title` | Element | Customize page title text |
    | `blocked_users_page/*/unblock_user_button` | Element | Customize unblock button text |

    #### Code Examples

```swift iOS
let page = AmityBlockedUsersPage()
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeBlockedUsersPage() {
    AmityBlockedUsersPage()
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityBlockedUserPage } from '@amityco/ui-kit';

const BlockedUsers = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityBlockedUsersPageBehavior: {
          goToUserProfilePage: (context) => {
            // Navigate to user profile
            navigate(`/profile/${context.userId}`);
          },
        },
      }}
    >
      <AmityBlockedUserPage />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
// The Flutter UIKit does not currently expose a standalone Blocked Users page.
// Blocked user management is handled through the SDK directly.
```

    ### User Pending Follow Request Page

    The User Pending Follow Request Page displays a list of users that have requested to follow the current user, with options to accept or decline requests.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Follow Request List | Display a list of users that have requested to follow current user |
    | User Action | User can accept or decline follow requests |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_pending_follow_request_page/*/*` | Page | Customize page theme |

    #### Code Examples

```swift iOS
let page = AmityUserPendingFollowRequestsPage()
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeUserPendingFollowRequestsPage() {
    AmityUserPendingFollowRequestsPage()
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityUserPendingFollowRequestPage } from '@amityco/ui-kit';

const PendingFollowRequests = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityUserPendingFollowRequestsPageBehavior: {
          goToUserProfilePage: (context) => {
            // Navigate to user profile
            navigate(`/profile/${context.userId}`);
          },
        },
      }}
    >
      <AmityUserPendingFollowRequestPage />
    </AmityUiKitProvider>
  );
};
```

```dart Flutter
Widget getPendingFollowRequestPage() {
  return AmityUserPendingFollowRequestsPage();
}
```

    ### Navigation Behavior

```swift iOS
// User Relationship Page Navigation
class CustomAmityUserRelationshipPageBehavior: AmityUserRelationshipPageBehavior {
    override func goToUserProfilePage(context: AmityUserRelationshipPageBehavior.Context) {
        // Navigate to user profile
        let profilePage = AmityUserProfilePage(userId: context.userId)
        let viewController = AmitySwiftUIHostingController(rootView: profilePage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Blocked Users Page Navigation
class CustomBlockedUserPageBehavior: AmityBlockedUsersPageBehavior {
    override func goToUserProfilePage(context: AmityBlockedUsersPageBehavior.Context) {
        // Navigate to user profile
        let profilePage = AmityUserProfilePage(userId: context.userId)
        let viewController = AmitySwiftUIHostingController(rootView: profilePage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Pending Follow Requests Navigation
class CustomAmityUserPendingFollowRequestsPageBehavior: AmityUserPendingFollowRequestsPageBehavior {
    override func goToUserProfilePage(context: AmityUserPendingFollowRequestsPageBehavior.Context) {
        // Navigate to user profile
        let profilePage = AmityUserProfilePage(userId: context.userId)
        let viewController = AmitySwiftUIHostingController(rootView: profilePage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}
```

```kotlin Android
// User Relationship Page Navigation
class CustomAmityUserRelationshipPageBehavior : AmityUserRelationshipPageBehavior() {
    override fun goToUserProfilePage(context: Context) {
        // Navigate to user profile page
    }
}

// Blocked Users Page Navigation
class CustomAmityBlockedUsersPageBehavior : AmityBlockedUsersPageBehavior() {
    override fun goToUserProfilePage(context: Context) {
        // Navigate to user profile page
    }
}

// Pending Follow Requests Navigation
class CustomAmityUserPendingFollowRequestsPageBehavior : AmityUserPendingFollowRequestsPageBehavior() {
    override fun goToUserProfilePage(context: Context) {
        // Navigate to user profile page
    }
}
```

```typescript React
// Social relationship navigation workflows
const handleSocialRelationshipNavigation = {
    // User relationship navigation
    goToUserProfile: (userId) => {
        navigate(`/profile/${userId}`);
    },

    // Follow request actions
    handleFollowRequest: async (action, userId) => {
        try {
            if (action === 'accept') {
                await acceptFollowRequest(userId);
                showNotification('Follow request accepted');
            } else if (action === 'decline') {
                await declineFollowRequest(userId);
                showNotification('Follow request declined');
            }
            // Refresh the request list
            refreshFollowRequests();
        } catch (error) {
            showError(`Failed to ${action} follow request: ${error.message}`);
        }
    },

    // Block/unblock actions
    handleBlockAction: async (action, userId) => {
        try {
            if (action === 'block') {
                await blockUser(userId);
                showNotification('User blocked successfully');
            } else if (action === 'unblock') {
                await unblockUser(userId);
                showNotification('User unblocked successfully');
            }
            // Refresh appropriate lists
            refreshUserLists();
        } catch (error) {
            showError(`Failed to ${action} user: ${error.message}`);
        }
    }
};
```

```dart Flutter
// Social relationship navigation
class SocialRelationshipNavigation {
    // Navigate to user profile
    void goToUserProfile(String userId) {
        Navigator.push(
            context,
            MaterialPageRoute(
                builder: (context) => AmityUserProfilePage(userId: userId),
            ),
        );
    }

    // Handle follow request actions
    Future<void> handleFollowRequest(String action, String userId) async {
        try {
            if (action == 'accept') {
                await acceptFollowRequest(userId);
                ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Follow request accepted')),
                );
            } else if (action == 'decline') {
                await declineFollowRequest(userId);
                ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Follow request declined')),
                );
            }
            // Refresh follow requests
            refreshFollowRequests();
        } catch (error) {
            ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Failed to $action follow request: $error')),
            );
        }
    }

    // Handle block/unblock actions
    Future<void> handleBlockAction(String action, String userId) async {
        try {
            if (action == 'block') {
                await blockUser(userId);
                ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('User blocked successfully')),
                );
            } else if (action == 'unblock') {
                await unblockUser(userId);
                ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('User unblocked successfully')),
                );
            }
            // Refresh user lists
            refreshUserLists();
        } catch (error) {
            ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Failed to $action user: $error')),
            );
        }
    }
}
```


## Related Components

    title="Communities"
    href="/uikit/components/social/communities"
    icon="building"
  >
    **Community Features** Community profiles, setup, and member management
    title="Community Membership"
    href="/uikit/components/social/community-membership"
    icon="users"
  >
    **Community Member Management** Member administration and community
    relationships
    title="Posts & Media"
    href="/uikit/components/social/posts"
    icon="photo-film"
  >
    **Post Components** User-generated content creation and management
    title="Social Feeds"
    href="/uikit/components/social/feeds"
    icon="newspaper"
  >
    **Feed Components** Content display and interaction for user feeds
    title="Comments & Reactions"
    href="/uikit/components/social/comments-reactions"
    icon="messages"
  >
    **Interaction Components** User engagement and social interaction features
    title="Content Moderation"
    href="/uikit/components/social/moderation"
    icon="shield"
  >
    **Moderation Tools** User safety and content moderation features

  **Implementation Strategy**: Start with the User Profile Page as your central
  user experience hub, then implement the Edit Profile functionality for user
  personalization. Add social relationship features (follow/unfollow, blocking)
  based on your application's social interaction requirements. Consider
  implementing follow request workflows for private accounts and ensure smooth
  navigation between user profiles, relationship management, and safety
  features. Focus on providing clear feedback for all social actions and
  maintain consistent user experience across profile viewing, editing, and
  relationship management workflows.

---

### [Content Moderation](https://learn.social.plus/uikit/components/social/moderation)

> Comprehensive content moderation tools for community safety and content oversight

**UIKit Component**: Content Moderation components are built on top of the social.plus SDK, providing ready-to-use reporting interfaces and moderation workflows with comprehensive safety controls and community guidelines enforcement.

## Feature Overview

The **Content Moderation** feature in social.plus UIKit v4 empowers community members to actively participate in maintaining safe and on-topic conversations. This comprehensive suite enables users to report inappropriate content through structured reporting mechanisms while providing administrators with powerful tools to review, manage, and resolve moderation issues efficiently.

### Key Features

    **Structured user reporting system**
    - Predefined report reason categories
    - Custom explanation fields for detailed context
    - Post and comment reporting capabilities
    - User-friendly reporting interfaces
    **Administrative oversight and management**
    - Unified moderation feed with filtering
    - Report reason visibility and counts
    - Priority-based issue resolution
    - Context-rich content review tools
    **Community standards implementation**
    - Automated content flagging workflows
    - Customizable community guidelines enforcement
    - Escalation and resolution tracking
    - Appeal and review processes
    **Moderation performance tracking**
    - Reporting trends and analytics
    - Community safety metrics
    - Moderator performance insights
    - Content policy effectiveness analysis

### Platform Support

| Feature | iOS | Android | Web | Flutter | React Native |
|---------|-----|---------|-----|---------|--------------|
| Report Post | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report Comment | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report with Reason Categories | ✅ | ✅ | ✅ | - | - |
| Custom Report Details | ✅ | ✅ | ✅ | - | - |
| Moderation Dashboard | ✅ | ✅ | ✅ | - | - |

## Related Components

    **Content Management**
    Post and media content that can be reported and moderated
    **Comment Moderation**
    Comment-level reporting and moderation capabilities
    **Community Safety**
    Community-level moderation settings and safety controls
    **User Management**
    User profile moderation and account management tools
    **Moderation Analytics**
    Comprehensive reporting and analytics for moderation activities
    **Administrative Tools**
    Advanced moderation and community management features

**Implementation Strategy**: Start with Content Reporting components to enable community members to flag inappropriate content using structured report reasons. Implement the Moderation Dashboard for administrators to review and resolve reports efficiently. Focus on creating clear workflows for report submission, review, and resolution. Consider implementing escalation procedures for serious violations and ensure proper documentation of moderation decisions. Provide clear feedback to both reporters and content creators about report outcomes to maintain transparency and trust in the moderation process.

---

### [Story](https://learn.social.plus/uikit/components/social/story)

> Create, view, and manage ephemeral story content with rich multimedia and engagement features

**UIKit Component**: Story components are built on top of the social.plus SDK, providing ready-to-use story creation and viewing UI with full data management handled automatically.

## Feature Overview

The **Story** feature in social.plus UIKit v4 enables users to create, share, and view ephemeral content, enhancing engagement and fostering community interaction. This suite of components provides a seamless experience for users to capture moments, share multimedia content, and engage with their communities through time-limited stories that disappear after 24 hours.

### Key Features

    **Rich multimedia story creation**

    - Camera integration with image and video capture
    - Media picker for existing content selection
    - Story composer with editing tools and hyperlinks
    - Audience targeting and content customization
    **Immersive story viewing experience**

    - Full-screen story viewer with navigation controls
    - Story ring indicators and progress tracking
    - Auto-play and manual navigation options
    - Interactive engagement features
    **Story lifecycle and content management**

    - Story drafting and preview capabilities
    - 24-hour automatic expiration handling
    - Story deletion and editing controls
    - Analytics and engagement tracking
    **Flexible content distribution options**

    - Community-specific story sharing
    - Personal timeline story creation
    - Target selection workflows
    - Privacy and visibility controls

### Platform Support

| Feature                    | iOS | Android | Web | Flutter | React Native |
| -------------------------- | --- | ------- | --- | ------- | ------------ |
| Story Target Tab Component | ✅   | ✅       | ✅   | ✅       | ✅            |
| Story Creation             | ✅   | ✅       | -   | ✅       | ✅            |
| Story Viewing              | ✅   | ✅       | ✅   | ✅       | ✅            |
| Story Target Selection     | ✅   | ✅       | -   | ✅       | -            |
| Story Drafting             | ✅   | ✅       | ✅   | ✅       | ✅            |
| Live Now                   | ✅   | ✅       | ✅   | -       | -            |

## Implementation Guide

    **Story ring display and navigation component**

    The Story Target Tab Component enables users to view and navigate story collections through circular ring indicators. This component provides seamless story discovery and creation workflows for both community and global feeds.

      ![Story List(1)](/images/StoryList\(1\).png)
    ### Story Target Tab Component

    The Story Target Tab Component is a dynamic feature that enhances the application page by allowing users to discover, view, and create stories. This component provides visual indicators for story availability and enables quick access to story creation and viewing workflows.

    #### Features

    | Feature                 | Description                                                   |
    | ----------------------- | ------------------------------------------------------------- |
    | Story Ring Indicators   | Visual circular progress indicators showing available stories |
    | Live Now Rings          | Visual indicators for currently live streams                  |
    | Community Story Targets | Access to community-specific story collections                |
    | Global Story Feed       | Browse stories from all accessible communities                |
    | Creation Shortcuts      | Quick access to story creation workflows                      |

    #### Required Properties

    | Property | Type                         | Description                              |
    | -------- | ---------------------------- | ---------------------------------------- |
    | `type`   | `AmityStoryTabComponentType` | Type of story feed (community or global) |

    #### Customization Options

    | Config ID                                       | Type      | Description                                                                   |
    | ----------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
    | `*/story_tab_component/*`                       | Component | Customize component theme and styling                                         |
    | `*/story_tab_component/story_ring`              | Element   | Customize ring colors with `progress_color` and `background_color`            |
    | `*/story_tab_component/create_new_story_button` | Element   | Customize creation button with `create_new_story_icon` and `background_color` |

    #### Code Examples


```swift iOS
// Community Feed Story Tab
let storyTabComponent = AmityStoryTabComponent(type: .communityFeed("<community-id>"))
let viewController = AmitySwiftUIHostingController(rootView: storyTabComponent)
navigationController?.pushViewController(viewController, animated: true)

// Global Feed Story Tab
let globalStoryTabComponent = AmityStoryTabComponent(type: .globalFeed)
let globalViewController = AmitySwiftUIHostingController(rootView: globalStoryTabComponent)
navigationController?.pushViewController(globalViewController, animated: true)
```


```kotlin Android
@Composable
fun composeStoryTabComponent(
    community: AmityCommunity
) {
    val feedTypeCommunity = AmityStoryTabComponentType.CommunityFeed(community.getCommunityId())
    val feedTypeGlobal = AmityStoryTabComponentType.GlobalFeed()

    // Community Feed Story Tab
    AmityStoryTabComponent(
        type = feedTypeCommunity
    )

    // Global Feed Story Tab
    AmityStoryTabComponent(
        type = feedTypeGlobal
    )
}
```


```tsx React
import React from 'react';
import { AmityStoryTabComponent } from '@amityco/ui-kit';

const CommunityStoriesTab = ({ communityId }) => {
  return (
    <AmityStoryTabComponent
          pageId='*'
          title='Story'
          haveStoryPermission={false}
          storyRing={false}
          isSeen={false}
          uploadingStory={false}
          isErrored={false}
          avatar=""
          onClick={() => {
            // Handle story tab click
          }}
          onChange={() => {
            // Handle story tab change
          }}
     />
  );
};

export default CommunityStoriesTab;
```


```tsx React Native
import {
  AmityStoryTabComponent,
  AmityUiKitProvider,
  AmityStoryTabComponentEnum
} from '@amityco/react-native-social-uikit';

 <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      apiEndpoint="https://api.{API_REGION}.amity.co"
  >
       <AmityStoryTabComponent
          type={AmityStoryTabComponentEnum.communityFeed}
          targetId={communityId}
       />
 </AmityUiKitProvider>
```


```dart Flutter
void viewStoryTabComponent(
  AmityCommunity community,
) {
  AmityStoryTabComponentType feedTypeCommunity = CommunityFeedStoryTab(
    communityId: community.communityId!,
  );

  AmityStoryTabComponentType feedTypeGlobal = GlobalFeedStoryTab();

  // Community Feed
  AmityStoryTabComponent(
    type: feedTypeCommunity,
  );

  // Global Feed
  AmityStoryTabComponent(
    type: feedTypeGlobal,
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomStoryTabComponentBehaviour: AmityStoryTabComponentBehaviour {
    override init() {
        super.init()
    }

    override func goToViewStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
        // Navigate to story viewing page
        let viewStoryPage = AmityViewStoryPage(type: .communityFeed(context.targetId))
        let viewController = AmitySwiftUIHostingController(rootView: viewStoryPage)
        navigationController?.pushViewController(viewController, animated: true)
    }

    override func goToCreateStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
        // Navigate to story creation page
        let createStoryPage = AmityCreateStoryPage(targetId: context.targetId, targetType: context.targetType)
        let viewController = AmitySwiftUIHostingController(rootView: createStoryPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setStoryTabComponentBehaviour() {
    let customStoryTabComponentBehaviour = CustomStoryTabComponentBehaviour()
    AmityUIKit4Manager.behaviour.storyTabComponentBehaviour = customStoryTabComponentBehaviour
}
```


```kotlin Android
class CustomStoryTabComponentBehaviour : AmityStoryTabComponentBehavior() {

    override fun goToViewStoryPage(
        context: Context,
        type: AmityViewStoryPageType,
    ) {
        // Navigate to story viewing page
        val intent = AmityViewStoryPageActivity.newIntent(
            context = context,
            type = type
        )
        context.startActivity(intent)
    }

    override fun goToCreateStoryPage(
        context: Context,
        targetId: String,
        targetType: AmityStory.TargetType
    ) {
        // Navigate to story creation page
        val intent = AmityCreateStoryPageActivity.newIntent(
            context = context,
            targetId = targetId,
            targetType = targetType
        )
        context.startActivity(intent)
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehaviour = CustomStoryTabComponentBehaviour()
    AmityUIKit4Manager.behavior.storyTabComponentBehavior = customBehaviour
}
```

    **Story creation and multimedia capture**

    Story Creation components enable users to create rich multimedia stories with camera integration, media selection, and content editing capabilities before publishing to their selected audience.

    ### Story Creation Page

    The Story Creation Page provides comprehensive camera functionality and media selection capabilities for creating engaging story content. Users can capture new content or select from existing media to create stories with customizable features and targeting options.

    #### Features

    | Feature            | Description                                                 |
    | ------------------ | ----------------------------------------------------------- |
    | Camera Integration | Real-time camera view for capturing images and videos       |
    | Media Selection    | Access to device gallery for selecting existing content     |
    | Content Preview    | Live preview of captured or selected content                |
    | Recording Controls | Video recording with duration controls and quality settings |

    #### Required Properties

    | Property     | Type                    | Description                                    |
    | ------------ | ----------------------- | ---------------------------------------------- |
    | `targetId`   | `String`                | The ID of the target (community ID or user ID) |
    | `targetType` | `AmityStory.TargetType` | Type of target (community or user)             |

    #### Customization Options

    | Config ID                            | Type    | Description                                                     |
    | ------------------------------------ | ------- | --------------------------------------------------------------- |
    | `camera_page/*/*`                    | Page    | Customize camera page theme and styling                         |
    | `camera_page/*/close_button`         | Element | Customize close button with `close_icon` and `background_color` |
    | `camera_page/*/capture_button`       | Element | Customize capture button styling and behavior                   |
    | `camera_page/*/switch_camera_button` | Element | Customize camera switching controls                             |

    #### Code Examples


```swift iOS
// Create story for community
let createStoryPage = AmityCreateStoryPage(
    targetId: "<community-id>",
    targetType: .community
)
let viewController = AmitySwiftUIHostingController(rootView: createStoryPage)
navigationController?.pushViewController(viewController, animated: true)

// Create story for user timeline
let userStoryPage = AmityCreateStoryPage(
    targetId: "<user-id>",
    targetType: .user
)
let userViewController = AmitySwiftUIHostingController(rootView: userStoryPage)
navigationController?.pushViewController(userViewController, animated: true)
```


```kotlin Android
@Composable
fun composeCreateStoryPage(
    community: AmityCommunity
) {
    AmityCreateStoryPage(
        targetId = community.getCommunityId(),
        targetType = AmityStory.TargetType.COMMUNITY
    )
}

// Using Activity
fun startCreateStoryActivity(context: Context, community: AmityCommunity) {
    val intent = AmityCreateStoryPageActivity.newIntent(
        context = context,
        targetId = community.getCommunityId(),
        targetType = AmityStory.TargetType.COMMUNITY
    )
    context.startActivity(intent)
}
```


```tsx React Native
import {
  AmityCreateStoryPage,
  AmityUiKitProvider
} from '@amityco/react-native-social-uikit';

const onCreateStory = () => {
    // Handle story creation completion
}

const CreateStoryScreen = ({ communityId }) => (
 <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      apiEndpoint="https://api.{API_REGION}.amity.co"
  >
       <AmityCreateStoryPage
          targetId={communityId}
          targetType={"community" | "user" | "content"}
          onCreateStory={onCreateStory}
       />
 </AmityUiKitProvider>
);
```


```dart Flutter
void navigateToCreateStoryPage(
  BuildContext context,
  String targetId,
  AmityStoryTargetType targetType,
) {
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => AmityCreateStoryPage(
        targetType: targetType,
        targetId: targetId,
      ),
    ),
  );
}
```


    ### Story Drafting Page

    The Story Draft Page enables users to preview, edit, and customize their story content before publishing. This component provides comprehensive editing tools including hyperlink addition, aspect ratio adjustment, and content finalization.

    #### Features

    | Feature               | Description                                     |
    | --------------------- | ----------------------------------------------- |
    | Content Preview       | Full preview of story content before publishing |
    | Hyperlink Integration | Add clickable links with customizable text      |
    | Aspect Ratio Control  | Adjust story dimensions and presentation        |
    | Publishing Controls   | Final review and story publishing options       |

    #### Required Properties

    | Property     | Type                    | Description                                    |
    | ------------ | ----------------------- | ---------------------------------------------- |
    | `targetId`   | `String`                | The ID of the target (community ID or user ID) |
    | `targetType` | `AmityStory.TargetType` | Type of target (community or user)             |
    | `mediaType`  | `AmityStoryMediaType`   | Type and source of media content               |

    #### Customization Options

    | Config ID                                    | Type    | Description                                                       |
    | -------------------------------------------- | ------- | ----------------------------------------------------------------- |
    | `create_story_page/*/*`                      | Page    | Customize drafting page theme and styling                         |
    | `create_story_page/*/back_button`            | Element | Customize back navigation with `back_icon` and `background_color` |
    | `create_story_page/*/aspect_ratio_button`    | Element | Customize aspect ratio controls                                   |
    | `create_story_page/*/story_hyperlink_button` | Element | Customize hyperlink button styling                                |
    | `create_story_page/*/share_story_button`     | Element | Customize publish button with `share_icon` and `background_color` |

    #### Code Examples


```swift iOS
// Draft Image Story
let draftImageStoryPage = AmityDraftStoryPage(
    targetId: "<community-id>",
    targetType: .community,
    mediaType: .image(previewImageURL)
)
let viewController = AmitySwiftUIHostingController(rootView: draftImageStoryPage)
navigationController?.pushViewController(viewController, animated: true)

// Draft Video Story
let draftVideoStoryPage = AmityDraftStoryPage(
    targetId: "<community-id>",
    targetType: .community,
    mediaType: .video(previewVideoURL)
)
let videoViewController = AmitySwiftUIHostingController(rootView: draftVideoStoryPage)
navigationController?.pushViewController(videoViewController, animated: true)
```


```kotlin Android
@Composable
fun composeDraftStoryPage(
    community: AmityCommunity,
    mediaType: AmityStoryMediaType = AmityStoryMediaType.Image(Uri.EMPTY)
) {
    AmityDraftStoryPage(
        targetId = community.getCommunityId(),
        targetType = AmityStory.TargetType.COMMUNITY,
        mediaType = mediaType,
    )
}

// Using Activity
fun startDraftStoryActivity(
    context: Context,
    community: AmityCommunity,
    mediaType: AmityStoryMediaType = AmityStoryMediaType.Image(Uri.EMPTY)
) {
    val intent = AmityDraftStoryPageActivity.newIntent(
        context = context,
        targetId = community.getCommunityId(),
        targetType = AmityStory.TargetType.COMMUNITY,
        mediaType = mediaType,
    )
    context.startActivity(intent)
}
```


```tsx React
import React from 'react';
import { AmityCreateStoryPage } from '@amityco/ui-kit-open-source';

const DraftStoryPage = ({ file, targetId }) => {
return (
          <AmityCreateStoryPage
          pageId="create_story_page"
          file={file}
          creatorAvatar=""
          onCreateStory={() => {
            // Handle story creation
          }}
          onDiscardStory={() => {
            // Handle story discard
          }}
          />
);
};

export default DraftStoryPage;
```


```tsx React Native
import {
  AmityDraftStoryPage,
  AmityUiKitProvider
} from '@amityco/react-native-social-uikit';

const onCreateStory = () => {
    // Handle story creation completion
}

const onDiscardStory = () => {
    // Handle story discard
}

const DraftStoryScreen = ({ communityId, mediaType }) => (
 <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      apiEndpoint="https://api.{API_REGION}.amity.co"
  >
       <AmityDraftStoryPage
          targetId={communityId}
          targetType={"community" | "user" | "content"}
          mediaType={mediaType}
          onCreateStory={onCreateStory}
          onDiscardStory={onDiscardStory}
       />
 </AmityUiKitProvider>
);
```


```dart Flutter
void navigateToStoryDraftPage(
  BuildContext context,
  String targetId,
  File image,
  AmityStoryTargetType targetType,
) {
  AmityStoryMediaType mediaType = AmityStoryMediaTypeImage(file: image);
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => StoryDraftPage(
        mediaType: mediaType,
        targetId: targetId,
        targetType: targetType,
      ),
    ),
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomCreateStoryPageBehaviour: AmityCreateStoryPageBehaviour {
    override init() {
        super.init()
    }

    override func goToDraftStoryPage(context: AmityCreateStoryPageBehaviour.Context) {
        // Navigate to story draft page
        let draftPage = AmityDraftStoryPage(
            targetId: context.targetId,
            targetType: context.targetType,
            mediaType: context.mediaType
        )
        let viewController = AmitySwiftUIHostingController(rootView: draftPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setCreateStoryPageBehaviour() {
    let customCreateStoryPageBehaviour = CustomCreateStoryPageBehaviour()
    AmityUIKit4Manager.behaviour.createStoryPageBehaviour = customCreateStoryPageBehaviour
}
```


```kotlin Android
class CustomCreateStoryPageBehaviour : AmityCreateStoryPageBehavior() {

    override fun goToDraftStoryPage(
        context: Context,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String,
        targetType: AmityStory.TargetType,
        mediaType: AmityStoryMediaType
    ) {
        // Navigate to story draft page
        val intent = AmityDraftStoryPageActivity.newIntent(
            context = context,
            targetId = targetId,
            targetType = targetType,
            mediaType = mediaType
        )
        launcher.launch(intent)
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehaviour = CustomCreateStoryPageBehaviour()
    AmityUIKit4Manager.behavior.createStoryPageBehavior = customBehaviour
}
```

    **Story viewing and engagement interface**

    Story Viewing components provide immersive full-screen story consumption with navigation controls, engagement features, and seamless story progression for enhanced user experience.

    ### Story Viewing Page

    The Story Viewing Page provides an immersive full-screen interface for consuming story content. Users can navigate through story collections, engage with content through reactions and comments, and seamlessly progress through multiple stories with intuitive controls.

    #### Features

    | Feature             | Description                                              |
    | ------------------- | -------------------------------------------------------- |
    | Full-Screen Viewing | Immersive story consumption with optimized media display |
    | Progress Indicators | Visual progress tracking across story collections        |
    | Navigation Controls | Tap to advance, hold to pause, swipe gestures            |
    | Engagement Features | React, comment, and interact with story content          |
    | Audio Controls      | Mute/unmute story audio with visual indicators           |

    #### Required Properties

    | Property | Type                     | Description                                        |
    | -------- | ------------------------ | -------------------------------------------------- |
    | `type`   | `AmityViewStoryPageType` | Type of story view (community feed or global feed) |

    #### Customization Options

    | Config ID                              | Type    | Description                                                                |
    | -------------------------------------- | ------- | -------------------------------------------------------------------------- |
    | `story_page/*/*`                       | Page    | Customize story viewing page theme and styling                             |
    | `story_page/*/progress_bar`            | Element | Customize progress indicators with `progress_color` and `background_color` |
    | `story_page/*/overflow_menu`           | Element | Customize options menu with `overflow_menu_icon`                           |
    | `story_page/*/close_button`            | Element | Customize close navigation with `close_icon`                               |
    | `story_page/*/story_impression_button` | Element | Customize impression tracking with `impression_icon`                       |
    | `story_page/*/story_comment_button`    | Element | Customize comment interaction                                              |
    | `story_page/*/story_reaction_button`   | Element | Customize reaction controls                                                |
    | `story_page/*/speaker_button`          | Element | Customize audio controls with `mute_icon` and `unmute_icon`                |

    #### Code Examples


```swift iOS
// Community Feed Story Viewing
let viewStoryPage = AmityViewStoryPage(type: .communityFeed("<community-id>"))
let viewController = AmitySwiftUIHostingController(rootView: viewStoryPage)
navigationController?.pushViewController(viewController, animated: true)

// Global Feed Story Viewing
// Specify communityId to start from specific community in global feed
let globalViewStoryPage = AmityViewStoryPage(type: .globalFeed("<start-community-id>"))
let globalViewController = AmitySwiftUIHostingController(rootView: globalViewStoryPage)
navigationController?.pushViewController(globalViewController, animated: true)
```


```kotlin Android
@Composable
fun composeViewStoryPage(community: AmityCommunity) {
    AmityViewStoryPage(
        type = AmityViewStoryPageType.CommunityFeed(communityId = community.getCommunityId())
    )
}

// Using Activity
fun startViewStoryActivity(context: Context, community: AmityCommunity) {
    val intent = AmityViewStoryPageActivity.newIntent(
        context = context,
        type = AmityViewStoryPageType.CommunityFeed(communityId = community.getCommunityId())
    )
    context.startActivity(intent)
}
```


```tsx React
import React from 'react';
import { AmityViewStoryPage } from '@amityco/ui-kit-open-source';

const StoryViewerPage = ({ targetId }) => {
  return (
      <AmityViewStoryPage
        page="story_page"
        targetId={targetId}
        onStoryEnd={() => {
          // Handle story end
        }}
        onStoryError={(error) => {
          // Handle story viewing errors
        }}
      />
  );
};

export default StoryViewerPage;
```


```tsx React Native
import {
  AmityViewStoryPage,
  AmityUiKitProvider
} from '@amityco/react-native-social-uikit';

const onFinish = () => {
    // Handle story viewing completion
}

const onPressAvatar = () => {
    // Handle avatar tap
}

const onPressCommunityName = () => {
    // Handle community name tap
}

const StoryViewerScreen = ({ communityId }) => (
 <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      apiEndpoint="https://api.{API_REGION}.amity.co"
  >
        <AmityViewStoryPage
          targetId={communityId}
          targetType="community"
          onFinish={onFinish}
          onPressAvatar={onPressAvatar}
          onPressCommunityName={onPressCommunityName}
        />
 </AmityUiKitProvider>
);
```


```dart Flutter
void navigateToViewStoryPage(
  BuildContext context,
  String communityId,
) {
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (BuildContext context) {
        return AmityViewStoryPage(
          type: AmityViewStoryCommunityFeed(communityId: communityId),
        );
      },
    ),
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomViewStoryPageBehaviour: AmityViewStoryPageBehaviour {
    override init() {
        super.init()
    }

    override func goToCreateStoryPage(context: AmityViewStoryPageBehaviour.Context) {
        // Navigate to story creation
        let createStoryPage = AmityCreateStoryPage(
            targetId: context.targetId,
            targetType: context.targetType
        )
        let viewController = AmitySwiftUIHostingController(rootView: createStoryPage)
        navigationController?.pushViewController(viewController, animated: true)
    }

    func handleStoryEnd() {
        // Handle story viewing completion
        navigationController?.popViewController(animated: true)
    }

    func handleStoryError(error: Error) {
        // Handle story viewing errors
        showErrorAlert(error: error)
    }
}

// Setup custom behavior
func setViewStoryPageBehaviour() {
    let customViewStoryPageBehaviour = CustomViewStoryPageBehaviour()
    AmityUIKit4Manager.behaviour.viewStoryPageBehaviour = customViewStoryPageBehaviour
}
```


```kotlin Android
class CustomViewStoryPageBehavior : AmityViewStoryPageBehavior() {

    override fun goToCreateStoryPage(
        context: Context,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String,
        targetType: AmityStory.TargetType,
    ) {
        // Navigate to story creation
        val intent = AmityCreateStoryPageActivity.newIntent(
            context = context,
            targetId = targetId,
            targetType = targetType
        )
        launcher.launch(intent)
    }

    override fun goToCommunityProfilePage(
        context: Context,
        community: AmityCommunity,
    ) {
        // Navigate to community profile
        val intent = AmiityMainActivityCommunityProfilePageActivity.newIntent(
            context = context,
            community = community
        )
        context.startActivity(intent)
    }

    fun handleStoryEnd(context: Context) {
        // Handle story viewing completion
        (context as? Activity)?.finish()
    }

    fun handleStoryError(context: Context, error: String) {
        // Handle story viewing errors
        Toast.makeText(context, "Story error: $error", Toast.LENGTH_LONG).show()
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehavior = CustomViewStoryPageBehavior()
    AmityUIKit4Manager.behavior.viewStoryPageBehavior = customBehavior
}
```

    **Audience and target selection for story distribution**

    Story Target Selection components provide users with flexible options to choose where their stories will be visible, enabling precise audience control and content distribution.

    ### Story Target Selection Page

    The Story Target Selection Page streamlines the process of choosing target audiences for story sharing. Users can select specific communities, target their personal timeline, or broadcast to multiple audiences with comprehensive visibility controls.

    #### Features

    | Feature              | Description                                                   |
    | -------------------- | ------------------------------------------------------------- |
    | Community Selection  | Browse and select specific communities for story distribution |
    | Personal Timeline    | Option to share stories on personal user timeline             |
    | Audience Preview     | Preview potential reach and engagement for selected targets   |
    | Multi-Target Support | Select multiple communities or distribution channels          |

    #### Required Properties

    | Property | Type | Description                                                   |
    | -------- | ---- | ------------------------------------------------------------- |
    | None     | -    | Page requires no mandatory properties for basic functionality |

    #### Customization Options

    | Config ID                                   | Type      | Description                                       |
    | ------------------------------------------- | --------- | ------------------------------------------------- |
    | `select_story_target_page/*/*`              | Page      | Customize target selection page theme and styling |
    | `select_story_target_page/*/close_button`   | Element   | Customize close navigation with custom `image`    |
    | `select_story_target_page/*/title`          | Element   | Customize page title with custom `text`           |
    | `select_story_target_page/*/community_list` | Component | Customize community selection interface           |

    #### Code Examples


```swift iOS
let storyTargetSelectionPage = AmityStoryTargetSelectionPage()
let viewController = AmitySwiftUIHostingController(rootView: storyTargetSelectionPage)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeStoryTargetSelectionPage() {
    AmityStoryTargetSelectionPage()
}

// Using Activity
fun startStoryTargetSelectionActivity(context: Context) {
    val intent = AmityStoryTargetSelectionPageActivity.newIntent(context)
    context.startActivity(intent)
}
```


```dart Flutter
void navigateToStoryTargetPage(BuildContext context) {
  Navigator.of(context).push(
    MaterialPageRoute(
      builder: (context) => const AmityStoryTargetSelectionPage(),
    ),
  );
}
```


    ### Navigation Behavior


```swift iOS
class CustomStoryTargetSelectionPageBehaviour: AmityStoryTargetSelectionPageBehaviour {
    override init() {
        super.init()
    }

    override func goToCreateStoryPage(context: AmityStoryTargetSelectionPageBehaviour.Context) {
        // Navigate to story creation with selected target
        let createStoryPage = AmityCreateStoryPage(
            targetId: context.targetId,
            targetType: context.targetType
        )
        let viewController = AmitySwiftUIHostingController(rootView: createStoryPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setStoryTargetSelectionPageBehaviour() {
    let customStoryTargetSelectionPageBehaviour = CustomStoryTargetSelectionPageBehaviour()
    AmityUIKit4Manager.behaviour.storyTargetSelectionPageBehaviour = customStoryTargetSelectionPageBehaviour
}
```


```kotlin Android
class CustomStoryTargetSelectionPageBehaviour : AmityStoryTargetSelectionPageBehavior() {
    override fun goToStoryCreationPage(
        context: Context,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String,
        targetType: AmityStory.TargetType
    ) {
        // Navigate to story creation with selected target
        val intent = AmityCreateStoryPageActivity.newIntent(
            context = context,
            targetId = targetId,
            targetType = targetType
        )
        launcher.launch(intent)
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehaviour = CustomStoryTargetSelectionPageBehaviour()
    AmityUIKit4Manager.behavior.storyTargetSelectionPageBehavior = customBehaviour
}
```


## Related Components

    **Post Components** Permanent content creation and media management for lasting social content
    **Feed Components** Story integration within social feeds and timeline displays
    **Community Features** Community-based story sharing and audience targeting
    **User Management** User profile integration with story content and viewing history
    **Interaction Components** Story engagement through comments, reactions, and impressions
    **Live Content** Real-time video broadcasting and live story alternatives

  **Implementation Strategy**: Begin with the Story Target Tab Component to establish story discovery workflows, then implement Story Creation for capturing and drafting content. Add Story Viewing for consumption experiences and ensure proper target selection with the Selection Page. Remember that stories are ephemeral content with 24-hour expiration - implement proper cleanup mechanisms and user notifications. Focus on smooth media transitions, responsive controls, and seamless navigation between story creation, viewing, and engagement features.

---

### [Clip](https://learn.social.plus/uikit/components/social/clip)

> Create, share, and discover short-form video content with engaging vertical feed experiences

**UIKit Component**: Clip components are built on top of the social.plus SDK, providing ready-to-use short-form video creation, editing, and viewing UI with full data management handled automatically.

## Feature Overview

The **Clip** feature in social.plus UIKit v4 enables users to create, share, and discover engaging short-form video content, fostering community interaction through immersive vertical feed experiences. This suite of components provides comprehensive tools for capturing moments, editing content, and consuming user-generated videos within communities.

### Key Features

    **Rich short-form video creation**
    - Camera integration with video recording
    - Media picker for existing video selection
    - Video editing and trimming capabilities
    - Community and user targeting options
    **Immersive vertical video feed**
    - TikTok-style vertical scrolling experience
    - Auto-play with seamless transitions
    - Engagement features (reactions, comments)
    - Community-based content discovery
    **Video preparation and customization**
    - Video preview and trimming tools
    - Aspect ratio adjustment controls
    - Audio mute/unmute options
    - Publishing and draft management
    **Interactive video features**
    - Real-time reactions and comments
    - User profile integration
    - Community content sharing
    - Engagement analytics and insights

### Platform Support

| Feature | iOS | Android | Web | Flutter | React Native |
|---------|-----|---------|-----|---------|--------------|
| Clip Creation | ✅ | ✅ | ✅ | - | - |
| Clip Editing & Draft | ✅ | ✅ | ✅ | - | - |
| Clip Feed Viewing | ✅ | ✅ | ✅ | - | - |
| Video Recording | ✅ | ✅ | - | - | - |
| Engagement Features | ✅ | ✅ | ✅ | - | - |

## Implementation Guide

    **Short-form video creation and recording**

    Clip Creation components enable users to capture or select video content with comprehensive recording controls, media selection, and content preparation workflows.

    ### Clip Post Creation Page

    The Clip Post Creation Page provides integrated camera functionality and media selection for creating engaging short-form video content. Users can record new videos or select existing content from their device gallery.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Video Recording | Real-time camera integration for capturing short-form videos |
    | Media Selection | Access to device gallery for selecting existing video content |
    | Recording Controls | Video duration limits, quality settings, and capture controls |
    | Target Selection | Choose community or personal timeline for content sharing |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `targetId` | `String` | The ID of the target (community ID or user ID) |
    | `targetType` | `AmityPostTargetType` | Type of target (community or user) |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `create_clip_post_page/*/*` | Page | Customize clip creation page theme and styling |
    | `create_clip_post_page/*/add_thumbnail_button` | Element | Customize thumbnail selection with custom `image` |
    | `create_clip_post_page/*/switch_camera_button` | Element | Customize camera switching controls with custom `image` |
    | `create_clip_post_page/*/recording_controls` | Element | Customize video recording interface elements |

    #### Code Examples

```swift iOS
// Create clip for community
let createClipPage = AmityCreateClipPostPage(
    targetId: "<community-id>",
    targetType: .community
)
let viewController = AmitySwiftUIHostingController(rootView: createClipPage)
navigationController?.pushViewController(viewController, animated: true)

// Create clip for user timeline
let userClipPage = AmityCreateClipPostPage(
    targetId: "<user-id>",
    targetType: .user
)
let userViewController = AmitySwiftUIHostingController(rootView: userClipPage)
navigationController?.pushViewController(userViewController, animated: true)
```

```kotlin Android
@Composable
fun composeCreateClipPage(
    community: AmityCommunity? = null,
    targetType: AmityPostTargetType
) {
    AmityCreateClipPage(
        targetId = community?.getCommunityId() ?: "UserId",
        targetType = targetType
    )
}

// Using Activity
fun startCreateClipActivity(
    context: Context,
    community: AmityCommunity? = null,
    targetType: AmityPostTargetType
) {
    val intent = AmityCreateClipPageActivity.newIntent(
        context = context,
        targetId = community?.getCommunityId() ?: "UserId",
        targetType = targetType
    )
    context.startActivity(intent)
}
```

    ### Draft Clip Page

    The Draft Clip Page enables users to preview, edit, and customize their video content before publishing. This component provides comprehensive editing tools including trimming, aspect ratio adjustment, and audio controls.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Video Preview | Full preview of clip content before publishing |
    | Content Editing | Video trimming and editing capabilities |
    | Aspect Ratio Control | Adjust video dimensions and presentation format |
    | Audio Controls | Mute/unmute audio with visual feedback |
    | Publishing Options | Final review and clip publishing controls |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `targetId` | `String` | The ID of the target (community ID or user ID) |
    | `targetType` | `AmityPostTargetType` | Type of target (community or user) |
    | `clipURL` | `URL` | Local URL of the video content to edit |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `draft_clip_page/*/*` | Page | Customize draft page theme and styling |
    | `draft_clip_page/*/back_button` | Element | Customize back navigation with custom `image` |
    | `draft_clip_page/*/mute_button` | Element | Customize audio controls with custom `image` |
    | `draft_clip_page/*/aspect_ratio_button` | Element | Customize aspect ratio controls with custom `image` |
    | `draft_clip_page/*/publish_button` | Element | Customize publishing controls and styling |

    #### Code Examples

```swift iOS
// Draft clip for community
let draftClipPage = AmityDraftClipPage(
    targetId: "<community-id>",
    targetType: .community,
    clipURL: localVideoURL
)
let viewController = AmitySwiftUIHostingController(rootView: draftClipPage)
navigationController?.pushViewController(viewController, animated: true)

// Draft clip for user timeline
let userDraftPage = AmityDraftClipPage(
    targetId: "<user-id>",
    targetType: .user,
    clipURL: localVideoURL
)
let userViewController = AmitySwiftUIHostingController(rootView: userDraftPage)
navigationController?.pushViewController(userViewController, animated: true)
```

```kotlin Android
@Composable
fun composeDraftClipPage(
    community: AmityCommunity? = null,
    targetType: AmityPostTargetType = AmityPostTargetType.COMMUNITY,
    mediaUri: Uri,
) {
    AmityDraftClipPage(
        targetId = community?.getCommunityId() ?: "UserId",
        targetType = targetType,
        media = mediaUri,
    )
}

// Using Activity
fun startDraftClipActivity(
    context: Context,
    community: AmityCommunity? = null,
    targetType: AmityPostTargetType = AmityPostTargetType.COMMUNITY,
    mediaUri: Uri,
) {
    val intent = AmityDraftClipPageActivity.newIntent(
        context = context,
        targetId = community?.getCommunityId() ?: "UserId",
        targetType = targetType,
        media = mediaUri,
    )
    context.startActivity(intent)
}
```

```tsx React
import React from 'react';
import { AmityUiKitProvider, AmityDraftClipPage } from '@amityco/ui-kit';

const DraftClipPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityDraftClipPageBehavior: {
          goToPostComposerPage: (context) => {
            // Handle navigation to post composer
            console.log('Navigate to post composer:', context);
          },
        },
      }}
    >
      <AmityDraftClipPage
        targetId={null}
        targetType="user"
        community={undefined}
      />
    </AmityUiKitProvider>
  );
};

export default DraftClipPage;
```

    ### Navigation Behavior

```swift iOS
class CustomDraftClipBehavior: AmityDraftClipPageBehavior {
    override init() {
        super.init()
    }

    override func goToPostComposerPage(context: AmityDraftClipPageBehavior.Context) {
        // Navigate to post composer with clip content
        let composerPage = AmityPostComposerPage(
            mode: .create,
            targetId: context.targetId,
            targetType: context.targetType,
            isClipPost: true
        )
        let viewController = AmitySwiftUIHostingController(rootView: composerPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setDraftClipBehavior() {
    let customBehavior = CustomDraftClipBehavior()
    AmityUIKit4Manager.behaviour.draftClipPageBehavior = customBehavior
}
```

```kotlin Android
class CustomDraftClipPageBehavior : AmityDraftClipPageBehavior() {
    override fun goToPostComposerPage(
        context: Context,
        clip: AmityClip,
        uri: Uri,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String,
        targetType: AmityPostTargetType,
        community: AmityCommunity?,
        isMute: Boolean,
        aspectRatio: AmityClip.DisplayMode
    ) {
        // Navigate to post composer with clip content
        val intent = AmityPostComposerPageActivity.newIntent(
            context = context,
            mode = AmityPostComposerPageMode.CREATE,
            targetId = targetId,
            targetType = targetType,
            isClipPost = true
        )
        launcher.launch(intent)
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehaviour = CustomDraftClipPageBehavior()
    AmityUIKit4Manager.behavior.draftClipPageBehavior = customBehaviour
}
```

    **Immersive vertical video feed experience**

    Clip Feed components provide TikTok-style vertical scrolling video consumption with engagement features, community integration, and seamless content discovery.

    ### Clip Feed Page

    The Clip Feed Page offers an immersive vertical scrolling experience for discovering and engaging with short-form video content. Users can swipe through clips, interact with content, and discover videos from their communities.

    #### Features

    | Feature | Description |
    |---------|-------------|
    | Vertical Scrolling | TikTok-style vertical feed with seamless transitions |
    | Auto-Play Videos | Automatic video playback with smooth progression |
    | Engagement Controls | Like, comment, and share functionality |
    | Content Discovery | Community-based and personalized content recommendations |
    | User Interaction | Profile viewing and community navigation |

    #### Required Properties

    | Property | Type | Description |
    |----------|------|-------------|
    | `type` | `AmityClipFeedPageType` | Type of clip feed (community, user, or global) |

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `clip_feed_page/*/*` | Page | Customize clip feed page theme and styling |
    | `clip_feed_page/*/create_new_clip_button` | Element | Customize clip creation button with custom `image` |
    | `clip_feed_page/*/reaction_button` | Element | Customize reaction controls with custom `image` |
    | `clip_feed_page/*/comment_button` | Element | Customize comment interface with custom `image` |
    | `clip_feed_page/*/mute_button` | Element | Customize audio controls with custom `image` |
    | `clip_feed_page/*/option_button` | Element | Customize options menu with custom `image` |

    #### Code Examples

```swift iOS
// General clip feed
let clipFeedPage = AmityClipFeedPage()
let hostController = AmitySwiftUIHostingNavigationController(rootView: clipFeedPage)
present(hostController, animated: true)

// Community-specific clip feed
let communityClipFeed = AmityClipFeedPage(type: .community("<community-id>"))
let communityController = AmitySwiftUIHostingNavigationController(rootView: communityClipFeed)
present(communityController, animated: true)
```

```kotlin Android
@Composable
fun composeClipFeedPage(type: AmityClipFeedPageType) {
    AmityClipFeedPage(
        type = type
    )
}

// Using Activity
fun startClipFeedActivity(context: Context, type: AmityClipFeedPageType) {
    val intent = AmityClipFeedPageActivity.newIntent(
        context = context,
        type = type
    )
    context.startActivity(intent)
}
```

```tsx React
import React from 'react';
import { AmityUiKitProvider, AmityClipFeedPage } from '@amityco/ui-kit';

const ClipFeedPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
      pageBehavior={{
        AmityClipFeedPageBehavior: {
          goToSelectClipPostTargetPage: (context) => {
            // Handle clip creation navigation
          },
          goToPostDetailPage: (context) => {
            // Handle post detail navigation
          },
          goToUserProfilePage: (context) => {
            // Handle user profile navigation
          },
          goToCommunityPage: (context) => {
            // Handle community navigation
          },
        },
      }}
    >
      <AmityClipFeedPage
        currentPostId="postId"
        postIndex={0}
        targetType="user"
        targetId={null}
      />
    </AmityUiKitProvider>
  );
};

export default ClipFeedPage;
```

    ### Navigation Behavior

```swift iOS
class CustomClipFeedPageBehavior: AmityClipFeedPageBehavior {
    override init() {
        super.init()
    }

    override func goToPostDetailPage(context: AmityClipFeedPageBehavior.Context) {
        // Navigate to post detail page
        let postDetailPage = AmityPostDetailPage(postId: context.postId)
        let viewController = AmitySwiftUIHostingController(rootView: postDetailPage)
        navigationController?.pushViewController(viewController, animated: true)
    }

    override func goToUserProfilePage(context: AmityClipFeedPageBehavior.Context) {
        // Navigate to user profile page
        let userProfilePage = AmityUserProfilePage(userId: context.userId)
        let viewController = AmitySwiftUIHostingController(rootView: userProfilePage)
        navigationController?.pushViewController(viewController, animated: true)
    }

    override func goToCommunityProfilePage(context: AmityClipFeedPageBehavior.Context) {
        // Navigate to community profile page
        let communityProfilePage = AmityCommunityProfilePage(community: context.community)
        let viewController = AmitySwiftUIHostingController(rootView: communityProfilePage)
        navigationController?.pushViewController(viewController, animated: true)
    }

    override func goToSelectPostTargetPage(context: AmityClipFeedPageBehavior.Context) {
        // Navigate to post target selection
        let targetSelectionPage = AmityPostTargetSelectionPage(isClipPost: true)
        let viewController = AmitySwiftUIHostingController(rootView: targetSelectionPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setClipFeedBehavior() {
    let customBehavior = CustomClipFeedPageBehavior()
    AmityUIKit4Manager.behaviour.clipFeedPageBehavior = customBehavior
}
```

```kotlin Android
class CustomClipFeedPageBehavior : AmityClipPageBehavior() {
    override fun goToPostDetailPage(context: Context, postId: String) {
        // Navigate to post detail page
        val intent = AmityPostDetailPageActivity.newIntent(
            context = context,
            postId = postId
        )
        context.startActivity(intent)
    }

    override fun goToClipPostComposerPage(
        context: Context,
        targetId: String?,
        targetType: AmityPostTargetType,
    ) {
        // Navigate to clip creation
        val intent = AmityCreateClipPageActivity.newIntent(
            context = context,
            targetId = targetId ?: "UserId",
            targetType = targetType
        )
        context.startActivity(intent)
    }

    override fun goToCommunityProfilePage(
        context: Context,
        community: AmityCommunity,
    ) {
        // Navigate to community profile
        val intent = AmityCommunityProfilePageActivity.newIntent(
            context = context,
            community = community
        )
        context.startActivity(intent)
    }

    override fun goToUserProfilePage(context: Context, userId: String) {
        // Navigate to user profile
        val intent = AmityUserProfilePageActivity.newIntent(
            context = context,
            userId = userId
        )
        context.startActivity(intent)
    }

    override fun goToSelectPostTargetPage(
        context: Context,
        type: AmityPostTargetSelectionPageType,
    ) {
        // Navigate to target selection
        val intent = AmityPostTargetSelectionPageActivity.newIntent(
            context = context,
            type = type
        )
        context.startActivity(intent)
    }

    override fun goToCreateCommunityPage(context: Context) {
        // Navigate to community creation
        val intent = AmityCreateCommunityPageActivity.newIntent(context)
        context.startActivity(intent)
    }
}

// Setup custom behavior
fun setCustomBehavior() {
    val customBehaviour = CustomClipFeedPageBehavior()
    AmityUIKit4Manager.behavior.clipFeedPageBehavior = customBehaviour
}
```

## Related Components

    **Post Components**
    Standard post creation and media management for longer-form content
    **Feed Components**
    Traditional social feeds and timeline content displays
    **Community Features**
    Community-based clip sharing and content organization
    **User Management**
    User profile integration with clip content and viewing history
    **Interaction Components**
    Clip engagement through comments, reactions, and social features
    **Story Features**
    Ephemeral content creation as an alternative to permanent clips

**Implementation Strategy**: Start with the Clip Creation Page to establish video capture and editing workflows, then implement the Draft Page for content refinement and publishing controls. Add the Clip Feed Page for consumption experiences with TikTok-style vertical scrolling. Focus on smooth video transitions, responsive controls, and seamless navigation between creation, editing, and viewing features. Consider implementing proper video compression and quality optimization for mobile performance, and ensure engagement features work smoothly during video playback.

---

### [Livestream](https://learn.social.plus/uikit/components/social/livestream)

> Live video broadcasting, viewing, and stream management components

**UIKit Component**: Livestream components are built on top of the social.plus
  SDK, providing ready-to-use live video broadcasting and viewing UI with full
  data management handled automatically.

  <img
    src="/images/Livestream(4).png"
    alt="Livestream(4)"
    title="Livestream(4)"
    className="mx-auto"
    style={{ width: "37%" }}
  />

## Feature Overview

The **Livestream** feature in social.plus UIKit v4 empowers users to broadcast and engage with live video content seamlessly. It provides a suite of components designed to facilitate the creation, viewing, and management of live streams within your application, offering comprehensive tools for both content creators and viewers.

### Key Features

    **Live stream setup and broadcasting**

    - Target audience selection (community or timeline)
    - Stream title, description, and thumbnail setup
    - Real-time broadcasting controls
    - Camera switching and stream management
    - Start from a Bluetooth remote or hardware volume key (iOS & Android)


    **Multi-broadcaster collaboration**\
    **(community only)**

    - Invite co-hosts to join your stream
    - Co-host management and controls
    - Real-time multi-broadcaster stage
    - Audio/video controls for each broadcaster
    - AI-powered content moderation


    **Live and recorded stream playback**

    - Real-time live stream viewing
    - Recorded stream playback for ended streams
    - Automatic thumbnail display from backend
    - Interactive viewer interface
    - Stream status and engagement features
    - Live Chat (community only)
    - Picture-in-Picture on leaving the player (iOS & Android)
    - Pinned message in live chat (community only)


    **Broadcast control and administration**

    - Stream termination handling
    - Moderation and safety controls
    - Stream status management
    - Co-host permission management


    **Flexible content distribution**

    - Community-specific broadcasting
    - Personal timeline streaming
    - Audience selection workflows


    **Multi-host broadcasting**

    - Invite co-hosts to join the stream
    - Real-time co-host participant streaming
    - Co-host permission controls
    - Collaborative stream management


    **Real-time audience visibility**

    - Real-time viewer count display
    - Who's watching list to see active viewers
    - Live audience engagement tracking
    - Viewer presence monitoring


    **Automatic watch time tracking**

    - Watch minutes collection for viewers
    - Pause/resume aware tracking
    - No additional implementation required


    **Tap-to-reveal player controls**

    - Tap-to-reveal controls overlay on mobile
    - Pause a live stream and resume at the live edge
    - Chat keeps updating while video is paused
    - 10-second skip on video posts and recorded livestreams


### Livestream Analytics

  **Zero Implementation Required**: Livestream analytics is automatically built
  into UIKit's livestream viewing components. When users watch live or recorded
  streams through the Room Player Page, watch minutes are automatically tracked
  and synced to the backend—no additional code needed.

UIKit automatically handles all analytics tracking including:

- **Watch Session Creation**: Sessions are created when viewers enter the room player page
- **Accurate Duration Tracking**: Only counts actual watching time (paused/buffering time is excluded)
- **Role Transition Handling**: Automatically stops tracking when a viewer becomes a co-host
- **Network Resilient Sync**: Data is stored locally and synced with retry logic

For developers who want to understand the underlying analytics capabilities or implement custom tracking in non-UIKit applications, see the [SDK Livestream Analytics documentation](/social-plus-sdk/video-new/analytics/overview).

### Platform Support

| Feature                                                      | iOS | Android | Web         | Flutter | React Native |
| ------------------------------------------------------------ | --- | ------- | ----------- | ------- | ------------ |
| Create Live Stream Post                                      | ✅  | ✅      | ✅(desktop) | -       | ✅           |
| Stream Viewing                                               | ✅  | ✅      | ✅          | -       | ✅           |
| Co-Streaming<br />(Community)                                | ✅  | ✅      | ✅          | -       | -            |
| Live Stream Chat & Moderation<br />(Community)               | ✅  | ✅      | ✅          | -       | -            |
| Pin Message in Live Chat<br />(Community)                    | ✅  | 🚧      | ✅          | -       | -            |
| Watching Now Viewer Count<br />                              | ✅  | ✅      | ✅          | -       | -            |
| Livestream Analytics<br />(Watch Minutes)                    | ✅  | ✅      | ✅          | -       | -            |
| Playback Controls<br />(tap-to-reveal, pause live, 10s skip) | ✅  | ✅      | ✅          | 🚧      | 🚧           |
| Picture-in-Picture<br />(floating window on leaving the player)| ✅  | ✅      | -           | 🚧      | 🚧           |

  Livestream creation and co-host streaming on web is supported only on desktop
  view. On mobile web, only viewing livestreams is supported.

## Implementation Guide

    **Live stream creation and broadcasting setup**

    Stream Creation components enable users to set up and broadcast live video content with comprehensive controls for targeting, customization, and real-time management.

    ### Livestream Target Selection Page

    The target selection page allows users to choose where their live stream will be broadcasted - either to a specific community or their personal timeline.

    #### Features

    | Feature | Description |
    | --- | --- |
    | Target Selection | Choose between community or personal timeline broadcasting |
    | Community Browsing | Browse and select specific communities for broadcasting |

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | None | - | Page requires no mandatory properties |

    #### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `livestream_post_target_selection_page/*/*` | Page | Customize page theme |
    | `livestream_post_target_selection_page/*/close_button` | Element | Customize close button image |
    | `livestream_post_target_selection_page/*/my_timeline_text` | Element | Customize timeline option text |
    | `livestream_post_target_selection_page/*/title` | Element | Customize page title text |

    #### Code Examples


```swift iOS
let page = AmityLivestreamPostTargetSelectionPage()
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeLivestreamTargetSelection() {
    AmityLivestreamPostTargetSelectionPage()
}

// Using Activity
fun startTargetSelectionActivity(context: Context) {
    val intent = AmityLivestreamPostTargetSelectionPageActivity.newIntent(
        context = context,
    )
    context.startActivity(intent)
}
```

```typescript React
<AmityUiKitProvider
    apiKey="API_KEY"
    apiRegion="API_REGION"
    userId="userId"
    displayName="displayName"
    configs={{}}
>
    <LivestreamTargetSelectionPage />
</AmityUiKitProvider>
```


    ### Livestream Creation Page

    The creation page enables users to set up their live stream by adding title, description, and thumbnail before starting the broadcast. Supports both solo broadcasting and co-streaming with invited co-hosts.

    **Optional Thumbnail Upload**: Adding a thumbnail during stream creation is optional. The backend automatically generates a live thumbnail once the stream starts (`liveThumbnailUrl`), and a recorded thumbnail after the stream ends. If the creator does upload a cover image, it will take priority over the auto-generated thumbnails.

    #### Features

    | Feature | Description |
    | --- | --- |
    | Stream Setup | Add title, description, and thumbnail for the live stream |
    | Camera Controls | Switch between front and back cameras |
    | Broadcasting Controls | Start, pause, and end live stream broadcasting |
    | Hardware Start Triggers | Start the stream with a paired Bluetooth remote shutter or the device's hardware volume key, the same way those controls fire the shutter in the native camera app (iOS and Android) |
    | Co-Host Management | Invite co-hosts to join your stream |
    | Co-Host Stage | View and manage active co-hosts during broadcast |
    | Real-time Preview | Live preview of stream content before broadcasting |
    | Viewer Count | Real-time display of total number of users currently watching the stream |
    | Who's Watching List | View the list of users currently watching the live stream |

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | `targetId` | `String` | The ID of the target (community ID or user ID) |
    | `targetType` | `AmityPost.TargetType` | Type of target (community or user) |
    | `community` | `AmityCommunity?` | Community object (optional, for community streams) |

    #### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `create_livestream_page/*/*` | Page | Customize page theme |
    | `create_livestream_page/*/start_livestream_button` | Element | Customize start stream button |
    | `create_livestream_page/*/add_thumbnail_button` | Element | Customize thumbnail selection button |
    | `create_livestream_page/*/switch_camera_button` | Element | Customize camera switch button |
    | `create_livestream_page/*/invite_co_host_button` | Element | Customize invite co-host button |
    | `create_livestream_page/*/microphone_button` | Element | Customize microphone toggle button |
    | `create_livestream_page/*/camera_toggle_button` | Element | Customize camera on/off toggle button |
    | `create_livestream_page/*/moderation_menu_button` | Element | Customize moderation menu access button |
    | `create_livestream_page/*/co_host_stage` | Component | Customize co-host video stage layout |
    | `create_livestream_page/*/end_live_stream_button` | Element | Customize end stream button |
    | `create_livestream_page/*/live_timer_status` | Element | Customize live timer display |
    | `create_livestream_page/*/invite_co_host_button` | Element | Customize invite co-host button |

    #### Code Examples


```swift iOS
// For community stream
let creationPage = AmityCreateLivestreamPage(
    targetId: "community-id",
    targetType: .community
)
let viewController = AmitySwiftUIHostingController(rootView: creationPage)
navigationController?.pushViewController(viewController, animated: true)

// For user timeline stream
let timelineStream = AmityCreateLivestreamPage(
    targetId: "user-id",
    targetType: .user
)
```

```kotlin Android
@Composable
fun composeCreateLivestreamPage(
    targetId: String,
    targetType: AmityPost.TargetType,
    community: AmityCommunity? = null,
) {
    AmityCreateLivestreamPage(
        targetId = targetId,
        targetType = targetType,
        targetCommunity = community
    )
}

// Using Activity
fun startCreateLivestreamActivity(
    context: Context,
    targetId: String,
    targetType: AmityPost.TargetType,
    community: AmityCommunity? = null,
) {
    val intent = AmityCreateLivestreamPageActivity.newIntent(
        context = context,
        targetId = targetId,
        targetType = targetType,
        community = community,
    )
    context.startActivity(intent)
}
```

```typescript React
<AmityUiKitProvider
    apiKey="API_KEY"
    apiRegion="API_REGION"
    userId="userId"
    displayName="displayName"
    configs={{}}
>
    <CreateLivestreamPage
        targetType="community"
        targetId="communityId"
        event={{}}
    />
</AmityUiKitProvider>
```


    ### Navigation Behavior


```swift iOS
// Livestream Target Selection Navigation
class CustomLivestreamPostTargetSelectionPageBehavior: AmityLivestreamPostTargetSelectionPageBehavior {
    override func goToLiveStreamComposerPage(context: AmityLivestreamPostTargetSelectionPageBehavior.Context) {
        // Navigate to livestream creation page
        let creationPage = AmityCreateLivestreamPage(
            targetId: context.targetId,
            targetType: context.targetType
        )
        let viewController = AmitySwiftUIHostingController(rootView: creationPage)
        navigationController?.pushViewController(viewController, animated: true)
    }
}

// Setup custom behavior
func setupLivestreamTargetSelectionBehavior() {
    let customBehavior = CustomLivestreamPostTargetSelectionPageBehavior()
    AmityUIKit4Manager.behaviour.liveStreamPostTargetSelectionPageBehavior = customBehavior
}
```

```kotlin Android
// Custom Livestream Target Selection Behavior
class CustomLivestreamPostTargetSelectionPageBehavior : AmityLivestreamPostTargetSelectionPageBehavior() {
    override fun goToLivestreamPostComposerPage(
        context: Context,
        launcher: ActivityResultLauncher<Intent>,
        targetId: String,
        targetType: AmityPost.TargetType,
        community: AmityCommunity?,
    ) {
        // Custom navigation to livestream creation
        val intent = AmityCreateLivestreamPageActivity.newIntent(
            context = context,
            targetId = targetId,
            targetType = targetType,
            community = community,
        )
        launcher.launch(intent)
    }
}

// Setup custom behavior
fun setCustomLivestreamBehavior() {
    val customBehaviour = CustomLivestreamPostTargetSelectionPageBehavior()
    AmityUIKit4Manager.behavior.livestreamTargetSelectionPageBehavior = customBehaviour
}
```

```typescript React
    // Custom behavior override for livestream post target selection is not currently supported in React. This functionality will be available in a future release.
```


    **Multi-broadcaster collaboration with co-hosting**

    Co-streaming components enable hosts to invite other users to join their livestream as co-hosts, creating collaborative broadcasting experiences with multiple broadcasters on a shared stage.

    ### Co-Host Invitation Page

    The co-host invitation page allows the host to invite other users to join their livestream as co-broadcasters.

    #### Features

    | Feature | Description |
    | --- | --- |
    | User Search | Search for users to invite as co-hosts |
    | User Selection | Select multiple users to invite |
    | Invitation Sending | Send co-host invitations to selected users |
    | Invitation Status | Track invitation status (pending/accepted/declined) |

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | `roomId` | `String` | The ID of the livestream room |

    #### Customization Options

    | Config ID | Type | Description | |-----------|------|-------------|| | `livestream_invite_co_host_page/*/*` | Page | Customize invitation page theme | | `livestream_invite_co_host_page/*/search_bar` | Element | Customize user search input | | `livestream_invite_co_host_page/*/invite_button` | Element | Customize invite button | | `livestream_invite_co_host_page/*/user_list_item` | Component | Customize user list item display | | `livestream_invite_co_host_page/*/title` | Element | Customize page title text |

    #### Code Examples


```swift iOS
let invitePage = AmityLivestreamInviteCoHostPage(roomId: "room-123")
let viewController = AmitySwiftUIHostingController(rootView: invitePage)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeInviteCoHostPage(roomId: String) {
    AmityLivestreamInviteCoHostPage(
        roomId = roomId
    )
}

// Using Activity
fun startInviteCoHostActivity(context: Context, roomId: String) {
    val intent = AmityLivestreamInviteCoHostPageActivity.newIntent(
        context = context,
        roomId = roomId
    )
    context.startActivity(intent)
}
```


    ### Co-Host Stage Component

    The co-host stage displays all active broadcasters (host \+ co-hosts) with their video feeds and audio/video controls.

    #### Features

    | Feature | Description |
    | --- | --- |
    | Multi-Video Layout | Display video feeds for host and co-hosts |
    | Audio/Video Controls | Mute/unmute audio, enable/disable video for each broadcaster |
    | Co-Host Management | Remove co-hosts (host only) |
    | Role Indicators | Visual badges showing host vs co-host roles |
    | Moderation Menu | Access moderation actions for the stream |

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | `roomId` | `String` | The ID of the livestream room |
    | `participants` | `[AmityRoomParticipant]` | Array of room participants (host \+ co-hosts) |

    #### Customization Options

    | Config ID | Type | Description | |-----------|------|-------------|| | `livestream_co_host_stage/*/*` | Component | Customize co-host stage theme | | `livestream_co_host_stage/*/video_tile` | Element | Customize individual video tile | | `livestream_co_host_stage/*/host_badge` | Element | Customize host role badge | | `livestream_co_host_stage/*/co_host_badge` | Element | Customize co-host role badge | | `livestream_co_host_stage/*/microphone_button` | Element | Customize microphone toggle button | | `livestream_co_host_stage/*/camera_button` | Element | Customize camera toggle button | | `livestream_co_host_stage/*/remove_co_host_button` | Element | Customize remove co-host button |

    #### Code Examples


```swift iOS
let coHostStage = AmityLivestreamCoHostStage(
    roomId: "room-123",
    participants: room.participants
)
// Embedded in livestream creation page
```

```kotlin Android
@Composable
fun composeCoHostStage(
    roomId: String,
    participants: List<AmityRoomParticipant>
) {
    AmityLivestreamCoHostStage(
        roomId = roomId,
        participants = participants
    )
}
```


    ### Navigation Behavior


```swift iOS
// Custom Co-Host Invitation Behavior
class CustomLivestreamInviteCoHostPageBehavior: AmityLivestreamInviteCoHostPageBehavior {
    override func onInvitationsSent(context: AmityLivestreamInviteCoHostPageBehavior.Context) {
        // Navigate back to livestream page
        navigationController?.popViewController(animated: true)
        showToast("Invitations sent successfully")
    }

    override func onBackPressed() {
        navigationController?.popViewController(animated: true)
    }
}

// Setup custom behavior
func setupInviteCoHostBehavior() {
    let customBehavior = CustomLivestreamInviteCoHostPageBehavior()
    AmityUIKit4Manager.behaviour.livestreamInviteCoHostPageBehavior = customBehavior
}
```

```kotlin Android
// Custom Co-Host Invitation Behavior
class CustomLivestreamInviteCoHostPageBehavior : AmityLivestreamInviteCoHostPageBehavior() {
    override fun onInvitationsSent(
        context: Context,
        roomId: String,
        invitedUserIds: List<String>
    ) {
        // Navigate back to livestream page
        (context as? Activity)?.finish()
        Toast.makeText(context, "Invitations sent successfully", Toast.LENGTH_SHORT).show()
    }

    override fun onBackPressed(context: Context) {
        (context as? Activity)?.finish()
    }
}

// Setup custom behavior
fun setupInviteCoHostBehavior() {
    val customBehaviour = CustomLivestreamInviteCoHostPageBehavior()
    AmityUIKit4Manager.behavior.livestreamInviteCoHostPageBehavior = customBehaviour
}
```


    ### Co-Streaming Workflow

```mermaid
graph TD
    A[Host Creates Stream] --> B[Stream Goes Live]
    B --> C{Host Action}
    C -->|Invite Co-Hosts| D[Open Invite Page]
    D --> E[Select Users]
    E --> F[Send Invitations]
    F --> G{Co-Host Response}
    G -->|Accepts| H[Co-Host Joins Stage]
    G -->|Declines| I[Invitation Declined]
    H --> J[Multi-Broadcaster Stage]
    J --> K{Stream Actions}
    K -->|Mute/Unmute| L[Toggle Audio]
    K -->|Camera On/Off| M[Toggle Video]
    K -->|Remove Co-Host| N[Co-Host Removed]
    K -->|End Stream| O[Stream Ends]

    style A fill:#e3f2fd
    style H fill:#c8e6c9
    style J fill:#fff9c4
    style O fill:#ffebee
```

    ### AI Content Moderation

    Co-streaming includes built-in AI moderation for safety:

    | Moderation Action | Trigger | Result |
    | --- | --- | --- |
    | Flag Stream | AI detects inappropriate content | Warning shown to host |
    | Terminate Stream | Severe policy violation | Stream automatically ended |
    | Remove Co-Host | Co-host violates policies | Co-host removed from stream |

    **Moderation Menu Access:**

    - Host only: Full moderation controls
    - Co-hosts: Cannot access moderation menu
    - Viewers: Can report stream

    **Live stream viewing and playback interfaces**

    Stream Viewing components provide comprehensive interfaces for watching live broadcasts and playing back recorded streams with interactive features and controls.

    ### Livestream Player Page

    The player page provides viewers with the interface to watch live or recorded streams, supporting real-time viewing and playback of previously ended streams.

    #### Features

    | Feature | Description |
    | --- | --- |
    | Live Viewing | Real-time live stream viewing with minimal latency |
    | Recorded Playback | Playback of previously ended live streams |
    | Interactive Controls | Stream controls, volume, and playback options |
    | Stream Information | Display stream title, description, and metadata |
    | Co-host Display | View active co-hosts in the live stream |
    | Viewer Count | Real-time display of total number of users currently watching the stream, gated by the network-level [viewer count visibility rule](#viewer-count-visibility) |
    | Who's Watching List | View the list of users currently watching the live stream |
    | Tap-to-Reveal Controls (mobile) | Tap the player to reveal controls; only the central button toggles playback |
    | Pause Live Stream (mobile) | Pause playback locally while the broadcast continues; resume jumps to the live edge |
    | Live Chat During Pause | Chat keeps receiving messages in real time while the video is paused |
    | 10-Second Skip (recorded playback) | ±10s skip buttons on recorded livestreams; hidden on live |

    **Automatic Thumbnail**: The backend automatically generates a live thumbnail for the room session once the stream goes live (available via `liveThumbnailUrl` on the room model). After the stream ends and recording is processed, a recorded thumbnail is also auto-generated. UIKit uses these thumbnails automatically when displaying livestream posts in feeds -- no additional configuration is needed. If the creator uploaded a custom cover image, it takes priority over the auto-generated thumbnails.

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | `post` | `AmityPost` | The livestream post object to display |

    #### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `livestream_player_page/*/*` | Page | Customize player page theme |
    | `livestream_player_page/*/play_button` | Element | Customize play/pause button |
    | `livestream_player_page/*/volume_control` | Element | Customize volume controls |
    | `livestream_player_page/*/fullscreen_button` | Element | Customize fullscreen toggle |
    | `livestream_player_page/*/stream_info` | Component | Customize stream information display |
    | `livestream_player_page/*/inivte_co_host_list` | Component | Customize who's watching list display |
    | `livestream_player_page/*/live_viewer_count_element` | Element | Customize the viewer-count pill |

    #### Code Examples


```swift iOS
let livestreamPlayer = AmityLivestreamPlayerPage(post: post)
let viewController = AmitySwiftUIHostingController(rootView: livestreamPlayer)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeLivestreamPlayerPage(post: AmityPost) {
    AmityLivestreamPlayerPage(
        post = post,
    )
}

// Using Activity
fun startLivestreamPlayerActivity(context: Context, post: AmityPost) {
    val intent = AmityLivestreamPlayerPageActivity.newIntent(
        context = context,
        post = post,
    )
    context.startActivity(intent)
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityLiveStreamPlayerPage } from '@amityco/ui-kit';

const LiveStreamPlayer = ({ post }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityLiveStreamPlayerPage
        post={post}
        goToDetailPage={(context) => {
          // Optional: override navigation to the post detail page
        }}
      />
    </AmityUiKitProvider>
  );
};
```


    ### Navigation Behavior


```swift iOS
// Handle livestream player navigation
func handleLivestreamPlayerNavigation() {
    // Player navigation typically handled internally
    // Custom actions can be implemented for stream end, errors, etc.
}

func handleStreamEnd() {
    // Navigate back or to stream summary
    navigationController?.popViewController(animated: true)
}

func handleStreamError(error: Error) {
    // Show error alert and navigate back
    let alert = UIAlertController(
        title: "Stream Error",
        message: error.localizedDescription,
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .default) { _ in
        self.navigationController?.popViewController(animated: true)
    })
    present(alert, animated: true)
}
```

```kotlin Android
// Handle livestream player navigation
fun handleLivestreamPlayerNavigation(context: Context) {
    // Player navigation typically handled internally
    // Custom actions can be implemented for stream end, errors, etc.
}

fun handleStreamEnd(context: Context) {
    // Navigate back or to stream summary
    (context as? Activity)?.finish()
}

fun handleStreamError(context: Context, error: String) {
    // Show error message and navigate back
    Toast.makeText(context, "Stream error: $error", Toast.LENGTH_LONG).show()
    (context as? Activity)?.finish()
}
```

```typescript React
// Handle livestream player navigation
// AmityLiveStreamPlayerPage accepts only `post`, `roomId` and `goToDetailPage`.
// It has no onStreamEnd, onError or onFullscreen callbacks.
const handleLivestreamPlayerNavigation = {
    goToDetailPage: (context) => {
        // Optional: override navigation to the post detail page
    }
};
```


    **Stream termination, moderation, and administrative controls**

    Stream Management components handle the administrative aspects of live streaming, including stream termination, moderation actions, and post-stream workflows.

    ### Livestream Terminated Page

    The terminated page is displayed when a live stream ends, either by the host or due to moderation actions, providing appropriate messaging and next steps.

    #### Features

    | Feature | Description |
    | --- | --- |
    | Termination Messaging | Display appropriate messages for different termination reasons |
    | Action Options | Provide relevant actions post-termination (restart, view recording, etc.) |
    | Stream Summary | Show stream statistics and performance metrics |
    | Navigation Controls | Options to return to feed or create new stream |

    #### Required Properties

    | Property | Type | Description |
    | --- | --- | --- |
    | `livestreamScreenType` | `LivestreamScreenType` | Type of termination screen to display |

    #### Customization Options

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `livestream_terminated_page/*/*` | Page | Customize terminated page theme |
    | `livestream_terminated_page/*/livestream_terminated_action_button` | Element | Customize action button appearance |
    | `livestream_terminated_page/*/termination_message` | Element | Customize termination message text |
    | `livestream_terminated_page/*/stream_summary` | Component | Customize stream summary display |

    #### Code Examples


```swift iOS
let terminatedPage = AmityLivestreamTerminatedPage()
let viewController = AmitySwiftUIHostingController(rootView: terminatedPage)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeLivestreamTerminatedPage(livestreamScreenType: LivestreamScreenType) {
    AmityLivestreamTerminatedPage(
        livestreamScreenType = livestreamScreenType,
    )
}

// Using Activity
fun startLivestreamTerminatedActivity(
    context: Context,
    livestreamScreenType: LivestreamScreenType
) {
    val intent = AmityLivestreamTerminatedPageActivity.newIntent(
        context = context,
        screenType = livestreamScreenType,
    )
    context.startActivity(intent)
}
```

```typescript React
import React from 'react';
import { AmityUiKitProvider, AmityLivestreamTerminatedPage } from '@amityco/ui-kit';

const LiveStreamTerminated = ({ terminationReason, streamData }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityLivestreamTerminatedPage
        terminationReason={terminationReason}
        streamData={streamData}
        onActionButtonClick={(action) => {
          // Handle post-termination actions
          switch(action) {
            case 'restart':
              // Navigate to new stream creation
              break;
            case 'viewRecording':
              // Navigate to recorded stream
              break;
            case 'returnToFeed':
              // Navigate back to main feed
              break;
          }
        }}
      />
    </AmityUiKitProvider>
  );
};
```


    ### Navigation Behavior


```swift iOS
// Handle post-termination navigation
func handleStreamTerminationActions(action: StreamTerminationAction) {
    switch action {
    case .restart:
        // Navigate to new stream creation
        let targetSelectionPage = AmityLivestreamPostTargetSelectionPage()
        let viewController = AmitySwiftUIHostingController(rootView: targetSelectionPage)
        navigationController?.pushViewController(viewController, animated: true)
    case .viewRecording:
        // Navigate to recorded stream if available
        if let recordedPost = getRecordedStream() {
            let playerPage = AmityLivestreamPlayerPage(post: recordedPost)
            let viewController = AmitySwiftUIHostingController(rootView: playerPage)
            navigationController?.pushViewController(viewController, animated: true)
        }
    case .returnToFeed:
        // Navigate back to main feed
        navigationController?.popToRootViewController(animated: true)
    }
}
```

```kotlin Android
// Handle post-termination navigation
fun handleStreamTerminationActions(context: Context, action: StreamTerminationAction) {
    when (action) {
        StreamTerminationAction.RESTART -> {
            // Navigate to new stream creation
            val intent = AmityLivestreamPostTargetSelectionPageActivity.newIntent(context)
            context.startActivity(intent)
        }
        StreamTerminationAction.VIEW_RECORDING -> {
            // Navigate to recorded stream if available
            getRecordedStream()?.let { recordedPost ->
                val intent = AmityLivestreamPlayerPageActivity.newIntent(context, recordedPost)
                context.startActivity(intent)
            }
        }
        StreamTerminationAction.RETURN_TO_FEED -> {
            // Navigate back to main feed
            (context as? Activity)?.finish()
        }
    }
}
```

```typescript React
// Handle post-termination navigation
const handleStreamTerminationNavigation = {
    restart: () => {
        // Navigate to new stream creation
        navigate('/livestream/create');
    },
    viewRecording: (streamId) => {
        // Navigate to recorded stream
        navigate(`/livestream/watch/${streamId}`);
    },
    returnToFeed: () => {
        // Navigate back to main feed
        navigate('/feed');
    },
    shareStream: (streamData) => {
        // Share stream functionality
        shareContent({
            title: streamData.title,
            url: streamData.shareUrl,
            description: streamData.description
        });
    }
};
```


## Viewer Count Visibility

Enterprise customers can control whether the viewer count is shown to viewers on livestreams — a low count can read as an empty room, and a high count reads as social proof. Network admins pick a mode in the Console at the network level; the UIKit `LiveViewerCountElement` in the Livestream Player Page top bar applies the rule automatically.

  The rule applies to **viewers only**. Hosts and co-hosts always see the actual count regardless of mode.

### Modes

| Mode | Viewer behavior |
| --- | --- |
| **Always show** (default) | The count is visible whenever there is at least one viewer. At zero viewers the pill shows the `LIVE` indicator without a number. Matches the previous behavior for tenants that never configured this setting. |
| **Hide entirely** | Viewers never see the count. The `LIVE` indicator still renders. |
| **Show above minimum** | Viewers see the count only when it reaches a network-configured threshold (positive integer, `1`–`1000`, default `50`). Below the threshold, the `LIVE` indicator still renders without a number. |

### Propagation

UIKit reads the config **once when the viewer joins the stream**. Config changes made by an admin while a stream is live do not push to already-connected viewers — the new rule takes effect the next time each viewer opens the player page. A viewer who leaves and rejoins picks up the latest saved config.

Two things do update in-place within a single mount:

- **Count ticks.** Under _Show above minimum_, the pill appears or disappears as the count naturally crosses the threshold.
- **Role changes.** A viewer promoted to co-host mid-stream immediately sees the actual count — no rejoin needed.

### Fail-Open

If the SDK cannot read the config (network error, malformed payload, threshold out of range), the element treats the effective config as _Always show_ — today's behavior is never silently regressed to hiding the count.

### Platform Support

| Platform | Support |
| --- | --- |
| iOS | ✅ |
| Android | ✅ |
| Web | ✅ |
| Flutter | ❌ |
| React Native | ❌ |

  Building a custom viewer surface instead of using UIKit? Read the config yourself via `client.getLiveViewerCountConfig()` — see the [Live Viewer Count Config SDK guide](/social-plus-sdk/video-new/broadcasting/viewer-count-config).

## Product Tagging

Product tagging in livestreams allows hosts and authorized co-hosts to showcase products to viewers during live broadcasts. Viewers can browse tagged products and open product links without leaving the stream.

  <img
    src="/images/livestream-product-tagging.png"
    alt="Livestream with a pinned product overlay and tagged product count badge"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

  Product tagging requires the Product Catalog to be configured and enabled for
  your network in the console. Available on iOS, Android, and Web only.

### Tagging Phases

Product tagging is available across all livestream phases, with different access levels at each stage:

| Phase                           | Who can tag                             | Who can pin                             |
| ------------------------------- | --------------------------------------- | --------------------------------------- |
| **Pre-live** (backstage)        | Host only                               | Host only                               |
| **During livestream**           | Host \+ co-host (if permission granted) | Host \+ co-host (if permission granted) |
| **Post-live** (host management) | Host only                               | —                                       |

Viewers can browse and open tagged products during all phases, including replay.

### Product Pinning

A host or authorized co-host can pin one product at a time to display it as a prominent overlay card for all viewers.

- Only **one** product can be pinned at a time — pinning a new product automatically replaces the previous pin
- The pinned product always appears at the top of the product list
- If the pinned product is removed from the tag list, it is automatically unpinned
- When the livestream ends, the pin overlay is removed; the product list remains accessible to replay viewers

### Co-host Product Permissions

The host controls whether a co-host can manage products. This permission can be toggled from the backstage after the co-host accepts an invite, or from the co-host name menu during the stream.

- **Enabled**: Co-host can tag, remove, pin, and unpin products
- **Disabled**: Co-host cannot see or interact with any product management controls
- Permission changes apply immediately in real-time

### Viewer Experience

- The tag icon is only visible when at least one product is tagged
- A count badge on the tag icon updates in real-time as products are added or removed
- Tapping the tag icon opens a scrollable product list overlay
- Tapping a product opens its link in an in-app browser — the livestream continues playing behind the browser

### Customize the Product Tap

To route that tap somewhere else, override `onLivestreamProductTagClick` on `AmityGlobalBehavior`. The handler receives the tapped product on `context.product`.

```swift iOS
class MyGlobalBehavior: AmityGlobalBehavior {
    override func onLivestreamProductTagClick(context: AmityGlobalBehavior.Context) {
        guard let product = context.product else { return }
        MyNavigator.showProduct(id: product.productId)
    }
}

AmityUIKit4Manager.behaviour.globalBehavior = MyGlobalBehavior()
```

```kotlin Android
AmityUIKit4Manager.behavior.globalBehavior = object : AmityGlobalBehavior() {
    override fun onLivestreamProductTagClick(context: AmityGlobalBehavior.Context): Boolean {
        val product = context.product ?: return false
        MyCommerceFlow.openProduct(product.getProductId())

        // Return true to claim the tap, so the built-in product web view is skipped.
        return true
    }
}
```

```typescript Web
<AmityUIKitProvider
  pageBehavior={{
    AmityGlobalBehavior: {
      onLivestreamProductTagClick: ({ product }) => {
        router.push(`/products/${product.productId}`);
      },
    },
  }}
>
```

**Returning `false` on Android is not the same as doing nothing.** It gives you UIKit's built-in product web view, which leaves the stream playing in a floating window over it. iOS and Web return no value, so an override always replaces the default. On iOS, call `super.onLivestreamProductTagClick(context:)` where you still want the in-app browser.

### Limits & Constraints

| Limit                        | Value |
| ---------------------------- | ----- |
| Max products per livestream  | 20    |
| Simultaneous pinned products | 1     |

### Components Used in Livestreams

Product tagging in livestreams uses two shared UIKit components. See [Product Tagging Components](/uikit/components/social/product-tagging) for full parameter reference and code examples.

| Component                       | Used for                                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ProductTagSelectionComponent`  | Searching and selecting products to tag (via `livestream` mode)                                                                                  |
| `ManageProductTagListComponent` | Managing tagged products with pin/unpin and remove controls (host/co-host view); browsing products in read-only overlay (viewer and replay view) |

The `ProductTagSelectionComponent` in `livestream` mode has a higher product limit (up to 20 total) and a different header label ("Add products") compared to post mode. The `ManageProductTagListComponent` in `playback` render mode disables pin controls for the post-live replay experience.

## Pinned Messages

A host, co-host, or moderator can pin one chat message during a livestream so it stays visible above the live chat for every viewer, no matter how fast the feed scrolls. Use it for rules, a promo code, a link, or an announcement.

  <img
    src="/images/livestream-pinned-message-collapsed.png"
    alt="Livestream chat with a collapsed pinned message banner above the feed"
    style={{ maxWidth: "36%", display: "inline-block", margin: "0 2%" }}
  />
  <img
    src="/images/livestream-pinned-message-expanded.png"
    alt="Livestream chat with the pinned message banner expanded to show the full text"
    style={{ maxWidth: "36%", display: "inline-block", margin: "0 2%" }}
  />

### Who Can Pin

| Role | Pin from the ⋮ menu | Unpin (banner "X" or the ⋮ menu) | Sees the banner |
| --- | --- | --- | --- |
| Host | ✅ | ✅ | ✅ |
| Co-host | ✅ | ✅ | ✅ |
| Moderator or any role with `PIN_MESSAGE` | ✅ | ✅ | ✅ |
| Viewer, including muted viewers | — | — | ✅ |

The UIKit shows the pin controls when the current user is the host or a co-host, or holds `PIN_MESSAGE` in the live chat channel, and the room is live. The server enforces the permission on every request. When a user's permission changes mid-stream, the pin controls appear or disappear on their own — no user action, no error message: a **channel-level** role change (moderator or co-host) arrives over the `channel.roleAdded` / `channel.roleRemoved` realtime events, and a **network-level** change made from the Console arrives over the `user.updated` event (the UIKit subscribes to the current user's events while the livestream chat is open). The pinned message banner itself is unaffected (it is server-owned and stays visible to everyone). A stale pin or unpin that still slips through returns `403`, and the UIKit refreshes permissions then as a backstop.

### Pinning Behavior

- **Pin from the message menu.** "Pin message" appears at the top of a message's ⋮ menu, above "Report message" and "Delete message". It is hidden on deleted messages and on messages that failed to send. There is no confirmation dialog.
- **One pin at a time.** Pinning another message replaces the current pin in one step. The previous message loses its banner and stays in the feed.
- **The original message never moves.** Pinning only adds the banner. No pin indicator is drawn on the message inside the feed, and the feed is not reordered.
- **Unpin.** The "X" on the banner unpins, and is shown only to users who can pin. The ⋮ menu of the pinned message also offers **Unpin message** in place of **Pin message**, so there are two ways to unpin.
- **Live only.** The banner and the pin controls exist only while the room status is live. When the stream is idle, ended, or in recorded playback, the banner is not rendered even if the channel still has a pinned message.
- **Automatic unpin.** When the pinned message is deleted, or its author is banned from the channel or globally banned, the server clears the pin. The banner disappears for everyone and the message shows the "This message was deleted." placeholder in the feed. A community ban does not affect the pin.
- **Muted authors.** A muted user's message can be pinned and unpinned. The banner shows the muted indicator next to the author with the same visibility rules as message bubbles.

### Pinned Message Banner

The banner renders at the top of the chat column, above the feed and above the pinned product card. Messages scroll behind it.

| Part | Description |
| --- | --- |
| Byline | Author display name with the brand, host, co-host, or moderator badge, and the muted indicator when the author is muted |
| "Pinned" pill | Thumbtack icon with the "Pinned" label, right-aligned |
| Text | Every new pin renders collapsed to one line with an ellipsis and a trailing "more" indicator. Text that fits on one line shows no indicator. |
| "X" | Unpin control, shown only to users who can pin |

**Tap the bubble to expand or collapse.** The whole bubble is the tap target. "more" and "less" are passive labels, not buttons. Tapping anywhere on a collapsed banner expands it to the full text with a trailing "less" indicator. Tapping again collapses it. A replacing pin always starts collapsed. On mobile the chat column grows upward as the banner expands, and taps on the banner do not toggle the video controls.

### Customization Options

The pin controls and the banner use the `livestream_chat_feed` component ID. Existing `livestream_chat` keys for the compose bar and theme keep working.

All platforms build a config key as `pageId/componentId/elementId`, and `livestream_chat_feed` is the **component** ID — so it goes in the **middle** slot: `*/livestream_chat_feed/<element>`.

| Config ID | Type | Description |
| --- | --- | --- |
| `*/livestream_chat_feed/pinned_message_banner` | Element | Customize or exclude the pinned message banner. **All platforms.** |
| `*/livestream_chat_feed/pin_message_button` | Element | Customize or exclude the "Pin message" item in the message ⋮ menu. **Web and Android only** — iOS does not register this element (the pin control is not customizable there). |
| `*/livestream_chat_feed/unpin_message_button` | Element | Customize or exclude the unpin control: the "X" on the banner and, on Android and Web, the ⋮ menu's "Unpin message" item. **Web and Android only** — not registered on iOS. |

### Code Examples

The pin action and the banner are built into the livestream chat, so the pages you already use render them. The viewer sees them on the livestream player page and the streamer sees them on the broadcast view. There is nothing to mount separately. Use the config keys above to relabel or exclude the controls.


```tsx React
import React from 'react';
import { AmityUiKitProvider, AmityLiveStreamPlayerPage } from '@amityco/ui-kit';

// Pin controls appear automatically for hosts, co-hosts, and PIN_MESSAGE holders.
const config = {
  // Hide a control entirely by excluding its element key.
  excludes: [],
  customizations: {
    '*/livestream_chat_feed/pin_message_button': { text: 'Pin message' },
    '*/livestream_chat_feed/unpin_message_button': { text: 'Unpin message' },
    '*/livestream_chat_feed/pinned_message_banner': {},
  },
};

const LivestreamViewer = ({ post }) => (
  <AmityUiKitProvider
    apiKey="API_KEY"
    apiRegion="API_REGION"
    userId="userId"
    displayName="displayName"
    configs={config}
  >
    <AmityLiveStreamPlayerPage post={post} />
  </AmityUiKitProvider>
);

export default LivestreamViewer;
```

```json iOS config.json
{
  "excludes": [],
  "customizations": {
    // iOS registers only the banner element (`pinned_message_banner`).
    // There are no `pin_message_button` / `unpin_message_button` element IDs on iOS,
    // so the ⋮-menu pin/unpin items cannot be customized or excluded there.
    "*/livestream_chat_feed/pinned_message_banner": {}
  }
}
```

```swift iOS
// The pinned message banner renders inside the livestream player page
// and the broadcast view. No extra wiring is needed.
let livestreamPlayer = AmityLivestreamPlayerPage(post: post)
let viewController = AmitySwiftUIHostingController(rootView: livestreamPlayer)
navigationController?.pushViewController(viewController, animated: true)
```

```json Android config.json
{
  "excludes": [],
  "customizations": {
    "*/livestream_chat_feed/pin_message_button": { "text": "Pin message" },
    "*/livestream_chat_feed/pinned_message_banner": {},
    "*/livestream_chat_feed/unpin_message_button": {}
  }
}
```

```kotlin Android
// The pinned message banner renders inside the livestream player page
// and the broadcast view. No extra wiring is needed.
@Composable
fun composeLivestreamPlayerPage(post: AmityPost) {
    AmityLivestreamPlayerPage(
        post = post,
    )
}
```


  All platforms write the component ID in the **middle** slot of a config key (`*/livestream_chat_feed/<element>`). To remove a control, add its key to `excludes`. Excluding `unpin_message_button` keeps the banner visible but removes the "X" for everyone; on Android and Web it also removes the ⋮ menu's "Unpin message" item, because both controls share that key. On **iOS**, only `pinned_message_banner` is registered — the pin and unpin menu items have no element IDs there, so they cannot be relabeled or excluded.

### Error Handling

Pin and unpin failures are silent by design. No toast or dialog is shown. The ⋮ menu closes, the pin state is unchanged, and the banner keeps following the channel.

| Scenario | What the viewer sees |
| --- | --- |
| Network failure on pin or unpin | Nothing pin-specific. The existing "No internet connection." indicator applies when the device is offline. |
| Pin a message that was deleted concurrently | No pin is applied. The message row becomes the "This message was deleted." placeholder. |
| Pin or unpin after the user's role was revoked | Nothing. The pin controls are hidden from the next menu open onward. |
| Unpin a message that is no longer the current pin | Nothing. The banner already shows the newer pin. |

### Limits

| Limit | Value |
| --- | --- |
| Pinned messages per channel | 1 |
| Supported message type | Text |
| Channel type | `live` channels only |

## Playback Controls

Playback Controls standardize the tap and pause behavior of the video player across the UIKit — for both video posts and livestreams. On mobile, tapping the player reveals a controls overlay (instead of toggling playback), pausing a live stream is a real state with a visible pause indicator, and recorded content offers ±10s skip.

  Playback Controls apply to the livestream viewer and the shared video player
  used by video posts, media gallery, community video feeds, and recorded
  livestream playback. Live streams do not show skip controls.

### Tap-to-Reveal Controls (Mobile)

On mobile clients, tapping the player surface reveals a controls overlay — it no longer toggles pause/play directly. Only the central pause/play button changes playback state.

| Behavior                      | Detail                                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| Tap surface while playing     | Reveals the controls overlay; playback continues                                                          |
| Auto-dismiss while playing    | Overlay hides after ~1 second of inactivity                                                               |
| Tap central pause/play button | Toggles playback (the only affordance for pause/play on mobile)                                           |
| Tap outside while paused      | Dismisses the overlay; the video stays paused. Tap the surface again to re-reveal the central play button |
| Auto-dismiss while paused     | Disabled — the overlay only dismisses on an explicit tap-outside                                          |

  **Desktop web player:** One-step click-to-toggle is retained. Clicking the
  video pauses or resumes it directly; the central play icon persists while
  paused, the central pause icon appears briefly when resuming. Hover-to-reveal,
  mute, and fullscreen behavior are unchanged.

### Pause a Live Stream

Viewers can pause a live stream locally. The broadcast continues on the sender's side; only the viewer's playback is frozen. On mobile, pause/resume goes through the central button in the tap-to-reveal overlay. On desktop, a single click on the video surface toggles play/pause directly.

| Behavior                 | Detail                                                                                                                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| How to pause / resume    | **Mobile:** tap the surface to reveal the overlay, then tap the central pause/play button. **Desktop:** single-click anywhere on the video surface to toggle play/pause                        |
| Pause indicator          | The central `play` icon shown while paused communicates the paused state — no separate badge is added                                                                                          |
| Resume behavior          | On resume, playback **jumps to the current live edge** — the viewer catches up to live rather than replaying from the paused position                                                          |
| Chat during pause        | Chat continues to receive and render new messages in real time; **no messages are missed or replayed** on resume                                                                               |
| `LIVE` badge             | Not repurposed — the badge continues to reflect broadcast status, not viewer playback state                                                                                                    |
| Stream ends while paused | If the room transitions to `ended` or `recorded` while the viewer is paused, that state **takes priority** — the pause indicator dismisses and the player moves to the ended or recorded state |

  **Live edge resolution:** On resume, the player seeks to the HLS live-sync
  position when available, or to the end of the seekable range otherwise. No
  paused offset is tracked or restored.

### 10-Second Skip (Video Posts & Recorded Livestreams)

Viewers can jump backward or forward 10 seconds while watching a video post or a recorded livestream. On mobile, skip buttons appear in the controls overlay next to the central pause/play button. On desktop, they sit in the existing web-player control bar.

| Behavior                   | Detail                                                                                                                                                                                       |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Availability               | Video posts and recorded livestreams (VOD-of-live), on **mobile and desktop**. **Hidden on live streams.**                                                                                   |
| −10s at start              | Seeking below `0:00` clamps to `0:00`; the current play state is preserved (playing stays playing, paused stays paused)                                                                      |
| +10s near end              | Clamps to the final frame **and pauses (end state)** — it does not loop or error                                                                                                            |
| Rapid repeated taps        | Each tap adds or subtracts 10 seconds to the target position (e.g. three quick `+10s` taps at `1:00` seek to `1:30`). The icon always shows `+10` / `−10` — it does not accumulate on-screen |
| Boundary during rapid taps | Boundary clamps apply mid-burst — back clamps to `0:00` (keeps the current play state), forward clamps to the final frame (pauses)                                                           |
| Desktop                    | The existing skip controls now use `−10s` / `+10s` (previously 15s). No other desktop behavior changes                                                                                       |

### Flow — Pause and Resume to Live (Mobile)

```mermaid
flowchart TD
    A[Live stream playing at live edge] --> B[User taps player surface]
    B --> C[Controls overlay revealed]
    C --> D[User taps central pause button]
    D --> E[Playback pauses; central icon flips to play]
    E --> F{User action}
    F -->|Tap outside| G[Overlay dismisses; video stays paused]
    G --> H[User taps surface again → play button re-revealed]
    F -->|Tap play button| I[Player seeks to live edge]
    I --> J[Playback resumes live; overlay auto-dismisses in 1s]
    E --> K{Room ends or transitions to recorded?}
    K -->|Yes| L[Pause indicator dismissed; player switches to ended/recorded state]
```

### Platform Support

| Feature                                        | iOS | Android | Web (mobile) | Web (desktop) | Flutter | React Native |
| ---------------------------------------------- | --- | ------- | ------------ | ------------- | ------- | ------------ |
| Tap-to-reveal controls overlay                 | ✅  | ✅      | ✅           | —             | 🚧      | 🚧           |
| 1s auto-dismiss while playing                  | ✅  | ✅      | ✅           | —             | 🚧      | 🚧           |
| Pause live stream + resume-to-live             | ✅  | ✅      | ✅           | ✅            | 🚧      | 🚧           |
| Chat continues during pause                    | ✅  | ✅      | ✅           | ✅            | 🚧      | 🚧           |
| Ended-while-paused hand-off                    | ✅  | ✅      | ✅           | ✅            | 🚧      | 🚧           |
| ±10s skip (video posts + recorded livestreams) | ✅  | ✅      | ✅           | ✅            | 🚧      | 🚧           |
| ±10s skip hidden on live                       | ✅  | ✅      | ✅           | ✅            | 🚧      | 🚧           |

**Legend:** ✅ Supported | 🚧 Planned | — Not applicable

  On desktop web, playback controls are a **UI refresh only** — icons are
  updated and the skip amount changes from 15s to 10s. Click-to-toggle,
  hover-to-reveal, mute, and fullscreen behavior are unchanged.

## Picture-in-Picture

Picture-in-Picture (PiP) keeps a livestream playing in a small floating window when the viewer leaves the player — by backgrounding the app or navigating to another page, such as opening a tagged product. Both live streams and recorded livestreams can float, and playback continues uninterrupted as the viewer moves away and back.

  PiP uses each platform's **native system Picture-in-Picture window**, so its size, position, styling, and gestures come from the operating system. **iOS and Android only** — no configuration is required to turn it on. Broadcasters (host, co-host, and backstage) are excluded so they stay in the app to keep streaming.

### Window controls

Controls inside the floating window are drawn by the operating system. Android and iOS behave slightly differently:

| Control        | Android              | iOS                                    |
| -------------- | -------------------- | -------------------------------------- |
| Play / pause   | ✅ (recorded & live) | ✅ recorded — on live, shown but inactive |
| Skip ±10s      | ✅ recorded only     | ✅ recorded — on live, shown but disabled |
| Expand / close | ✅                   | ✅                                     |

On a live stream there is nothing to seek or hold past the live edge, so the skip and pause controls have no effect there. Mute is not available in the window on either platform — the device volume controls serve that purpose.

### Returning to the full player

- Expanding the window returns to the full player with playback continuing — the stream is not restarted, and a recording keeps its position.
- Live streams resume at the **live edge** rather than replaying the buffered part.
- Chat reloads at the latest messages on return.
- If the stream ends or is removed while floating, playback stops in the window and the reason (ended, terminated, or restricted) is shown when the viewer expands it.
- Closing the window stops playback.

### Setup

| Platform    | Required setup                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| **Android** | None. UIKit declares Picture-in-Picture support in its own manifest, which merges into your app automatically.       |
| **iOS**     | Enable the **Background Modes** capability with *Audio, AirPlay, and Picture in Picture*. Without it, PiP never starts. |

**Minimum OS:** Android 12 (API 31) or iOS 14.2 for full support. Below that, playback stops when the viewer leaves the player, as it did before PiP.

  Viewers can turn Picture-in-Picture off in their device settings. When it is off, leaving the player simply stops playback with no error. The two platforms differ: the **Android** setting blocks every trigger including in-app navigation, while the **iOS** setting only blocks automatic entry on backgrounding. Neither platform exposes this setting to the app, so it cannot be detected in advance.

### Platform Support

| Feature                            | iOS | Android | Web | Flutter | React Native |
| ---------------------------------- | --- | ------- | --- | ------- | ------------ |
| Float on backgrounding             | ✅  | ✅      | —   | 🚧      | 🚧           |
| Float on in-app navigation         | ✅  | ✅      | —   | 🚧      | 🚧           |
| Live and recorded playback         | ✅  | ✅      | —   | 🚧      | 🚧           |
| Expand back to the full player     | ✅  | ✅      | —   | 🚧      | 🚧           |
| Broadcasters excluded              | ✅  | ✅      | —   | 🚧      | 🚧           |

**Legend:** ✅ Supported | 🚧 Planned | — Not applicable

  The floating window cannot be branded or restyled — it is rendered by the operating system, so its colors, placement, and gestures are outside UIKit's control.

## Related Components

    **Post Components** Post creation and media management for livestream posts

  title="Social Feeds"
  icon="newspaper"
  href="/uikit/components/social/feeds"
>
  **Feed Components** Livestream post display and interaction in social feeds

  title="Communities"
  icon="building"
  href="/uikit/components/social/communities"
>
  **Community Features** Community-based livestream broadcasting and management

  title="Users & Profiles"
  icon="user"
  href="/uikit/components/social/users"
>
  **User Management** User profile integration with livestream content

  title="Comments & Reactions"
  icon="heart"
  href="/uikit/components/social/comments-reactions"
>
  **Interaction Components** Real-time engagement during live streams

  title="Content Moderation"
  icon="shield"
  href="/uikit/components/social/moderation"
>
  **Moderation Tools** Livestream content moderation and safety controls

    **Commerce Integration** Shared UIKit components for product tagging and management

---

### [Event](https://learn.social.plus/uikit/components/social/event)

> Comprehensive event management UI components for creating, discovering, and managing scheduled events

**UIKit Component**: Event components are built on top of the social.plus SDK,
  providing ready-to-use event creation and discovery UI with full data
  management handled automatically.

  <img
    src="/images/Explore.png"
    alt="Explore"
    title="Explore"
    className="mx-auto"
    style={{ width: "40%" }}
  />

## Feature Overview

The **Event** feature in social.plus UIKit v4 enables users to create scheduled events, discover upcoming/past events, manage attendees, and navigate between event-related experiences.

### Key Features

    **Schedule events with rich details**

    - Select where to create the event
    - Configure details (name, description, date & time)
    - In-person or virtual options

    **Explore and manage your events**

    - Explore events feed
    - Upcoming events page
    - Past events page
    - Community-specific event feed

    **Track and manage attendance**

    - RSVP (Going/Not going)
    - Attendees list
    - Reminder Notifications

    **Publish an event to a feed**

    - Create-post entry point on the event
    - Target selection with private-community lock
    - Event-post composer with prefilled fields
    - Event card in feeds, tap opens event detail
    - Read-only pinned / featured badges


### Platform Support

| Feature                    | iOS | Android | Web | Flutter | React Native |
| -------------------------- | --- | ------- | --- | ------- | ------------ |
| Event Creation             | ✅  | ✅      | ✅  | -       | -            |
| Event Detail & Attendees   | ✅  | ✅      | ✅  | -       | -            |
| Event discovery            | ✅  | ✅      | ✅  | -       | -            |
| Event in community profile | ✅  | ✅      | ✅  | -       | -            |
| Event as Post              | ✅  | ✅      | ✅  | -       | -            |

## Permission Handling

The visibility rules for the entry points that trigger event creation are:

1. **Global feed**: Only users with global permission will see the create event button
   - Check: `client.hasPermission(AmityPermission.createEvent)`
2. **Community feed**: Users with global OR community permission will see the create event button
   - Check: `client.hasPermission(AmityPermission.createEvent, communityId)`

  UIKit applies these permission checks automatically. If you implement your own
  custom entry points, keep the same permission logic for consistent UX.

## Implementation Guide

    ### Event Target Selection Page

    Use **AmityEventTargetSelectionPage** to choose the destination for the event (Note: community only).

    #### Customization Options

    | Config ID                                 | Type    | Description                  |
    | ----------------------------------------- | ------- | ---------------------------- |
    | `select_event_target_page/*/*`            | Page    | Customize page theme         |
    | `select_event_target_page/*/close_button` | Element | Customize close button image |
    | `select_event_target_page/*/title`        | Element | Customize page title         |

    #### Code Examples


```swift iOS
let page = AmityEventTargetSelectionPage()
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeEventTargetSelectionPage() {
    AmityEventTargetSelectionPage()
}

// Using Activity
fun startEventTargetSelectionActivity(context: Context) {
    val intent = AmityEventTargetSelectionPageActivity.newIntent(
        context = context,
    )
    context.startActivity(intent)
}
```

```typescript React
import { AmityUiKitProvider, AmityEventTargetSelectionPage } from '@amityco/ui-kit';

const SampleEventTargetSelectionPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventTargetSelectionPage />
    </AmityUiKitProvider>
  );
};
```


    ### Event Setup Page

    Use **AmityEventSetupPage** to create or edit an event.

      ![Create Commupublic(1)](/images/create-commupublic\(1\).png)

    **Public API:**

```swift
enum AmityEventSetupPageMode {
  case create(targetId, targetName)
  case edit(AmityEvent)
}

AmityEventSetupPage(mode: AmityEventSetupPageMode)
```

    #### Customization Options

    | Config ID                                  | Type    | Description                     |
    | ------------------------------------------ | ------- | ------------------------------- |
    | `event_setup_page/*/*`                     | Page    | Customize page theme            |
    | `event_setup_page/*/title`                 | Element | Customize title                 |
    | `event_setup_page/*/camera_button`         | Element | Customize camera label/icon     |
    | `event_setup_page/*/image_button`          | Element | Customize photo label/icon      |
    | `event_setup_page/*/event_name_title`      | Element | Customize “Event name” label    |
    | `event_setup_page/*/event_details_title`   | Element | Customize “Event details” label |
    | `event_setup_page/*/event_date_time_title` | Element | Customize “Date and time” label |
    | `event_setup_page/*/event_location_title`  | Element | Customize “Location” label      |

    #### Code Examples


```swift iOS
// Create
let page = AmityEventSetupPage(mode: .create("<targetId>", "<targetName>"))
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)

// Edit
// When you already have an AmityEvent object
let editPage = AmityEventSetupPage(mode: .edit(event))
```


```kotlin Android
@Composable
fun composeCreateEventSetupPage(targetId: String, targetName: String) {
    AmityEventSetupPage(mode = AmityEventSetupPageMode.Create(targetId, targetName))
}

@Composable
fun composeEditEventSetupPage(event: AmityEvent) {
    AmityEventSetupPage(mode = AmityEventSetupPageMode.Edit(event))
}
```

```typescript React
import { AmityUiKitProvider, AmityEventSetupPage } from '@amityco/ui-kit';

// Create mode
const SampleCreateEventSetupPage = ({ targetId, targetName }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventSetupPage
        mode="create"
        targetId={targetId}
        targetName={targetName}
      />
    </AmityUiKitProvider>
  );
};

// Edit mode
const SampleEditEventSetupPage = ({ event }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventSetupPage mode="edit" event={event} />
    </AmityUiKitProvider>
  );
};
```


    ### Event Detail Page

    Use **AmityEventDetailPage** to view event details and access event actions.

      ![Skeleton(2)](/images/Skeleton\(2\).png)
    **Public API:**

```swift
AmityEventDetailPage(eventId: string)
```

    #### Code Examples


```swift iOS
let page = AmityEventDetailPage(eventId: "<eventId>")
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeEventDetailPage(eventId: String) {
    AmityEventDetailPage(eventId = eventId)
}
```

```typescript React
import { AmityUiKitProvider, AmityEventDetailPage } from '@amityco/ui-kit';

const SampleEventDetailPage = ({ eventId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventDetailPage eventId={eventId} />
    </AmityUiKitProvider>
  );
};
```


    #### Post the event to a feed

    The event detail page's 3-dot action menu exposes **Post event to feed**, which starts the event-post creation flow. It appears for Host, Moderator, and Member roles of the event's origin community and is hidden for non-members and visitors.

    A **user-hosted** event has no origin community. The full target picker is still available, and it offers the user's own feed plus communities where the user can post. The entry point is shown only when the current user is eligible to publish the event.

    | Config ID | Type | Description |
    | --- | --- | --- |
    | `event_detail_page/*/create_event_post_button` | Element | Customize the "Post event to feed" action label and icon |

    Tapping the action always opens `AmityEventPostTargetSelectionPage`. The page chooses its variant from the event's origin:

    - **Public-community or user-hosted event** → an open picker with My Timeline and eligible communities. No target is selected automatically.
    - **Private-community event** → the same page in its restricted variant, showing only the event's origin community as the valid target.

    The destination is overridable through `AmityEventDetailPageBehavior` — see [Behavior Customization](#behavior-customization).

    #### Share an event

    The event detail page's 3-dot action menu can surface shareable-link actions that open the event directly:

    | Action | Platforms | Behavior |
    | --- | --- | --- |
    | **Copy event link** | iOS, Android, React | Copies the event URL to the clipboard and shows a "Link copied." toast |
    | **Share to** | iOS, Android | Opens the native OS share sheet with the event URL (not rendered on Web) |

    These actions are backed by the SDK's `Client.getShareableLinkConfiguration()` and appear only when **all** of the following are true:

    - Event shareable links are configured for the network — `config.isEnabled(AmitySharableContentType.EVENT)` is `true` (deep link toggle on and an event URL pattern is set in Console).
    - The event's origin community is **public**.
    - The event is not cancelled and not in a draft/unpublished state.

    If any condition fails, the Copy / Share actions are hidden. See [Content Sharing](/social-plus-sdk/social/content-management/content-sharing) for the SDK link-generation API.

    Event shareable links are available on iOS, Android, and React (Web). "Share to" (native share sheet) is mobile-only. Refer to the platform UIKit for Flutter and React Native availability.

    ### Event Attendees Page

    Use **AmityEventAttendeesPage** to browse attendees and navigate to a user profile.

    **Public API:**

```swift
AmityEventAttendeesPage(eventId: string)
```

    #### Code Examples


```swift iOS
let page = AmityEventAttendeesPage(eventId: "<eventId>")
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeEventAttendeesPage(eventId: String) {
    AmityEventAttendeesPage(eventId = eventId)
}
```

```typescript React
import { AmityUiKitProvider, AmityEventAttendeesPage } from '@amityco/ui-kit';

const SampleEventAttendeesPage = ({ eventId }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventAttendeesPage eventId={eventId} />
    </AmityUiKitProvider>
  );
};
```


    ### Upcoming Events Pages

    Use **AmityUpcomingEventsPage** to browse upcoming events.

      ![Default(1)](/images/Default\(1\).png)
    #### Customization Options

    | Config ID                  | Type | Description                    |
    | -------------------------- | ---- | ------------------------------ |
    | `upcoming_events_page/*/*` | Page | Customize upcoming events page |

     #### Code Examples


```swift iOS
// Show all upcoming events (Explore mode)
let upcomingEventsPage = AmityUpcomingEventsPage(
    context: .init(onlyMyEvents: false)
)
let viewController = AmitySwiftUIHostingController(rootView: upcomingEventsPage)
navigationController?.pushViewController(viewController, animated: true)

// Show only user's upcoming events (My Events mode)
let myEventsPage = AmityUpcomingEventsPage(
    context: .init(onlyMyEvents: true)
)
let myEventsViewController = AmitySwiftUIHostingController(rootView: myEventsPage)
navigationController?.pushViewController(myEventsViewController, animated: true)
```


```kotlin Android
// Using Activity - All events
fun startUpcomingEventsActivityAllEvents(context: Context) {
    val intent = AmityUpcomingEventsPageActivity.newIntent(
        context = context,
        showAllEvents = true
    )
    context.startActivity(intent)
}

// Using Activity - My events only
fun startUpcomingEventsActivityMyEvents(context: Context) {
    val intent = AmityUpcomingEventsPageActivity.newIntent(
        context = context,
        showAllEvents = false
    )
    context.startActivity(intent)
}
```

```typescript React
import { AmityUiKitProvider, AmityUpcomingEventsPage } from '@amityco/ui-kit';

const SampleAmityUpcomingEventsPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityUpcomingEventsPage fromExplore={true} />
    </AmityUiKitProvider>
  );
};
```


    ### Past Events Page

    Use **AmityPastEventsPage** to browse past events.

      ![Default(1)](/images/past-event-page.png)

     #### Customization Options

    | Config ID                  | Type | Description                    |
    | -------------------------- | ---- | ------------------------------ |
    | `past_events_page/*/*`     | Page | Customize past events page     |

     #### Code Examples


```swift iOS
// Show past events page
let pastEventsPage = AmityPastEventsPage()
let viewController = AmitySwiftUIHostingController(rootView: pastEventsPage)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
// Using Activity - All events
fun startPastEventsActivityAllEvents(context: Context) {
    val intent = AmityPastEventsPageActivity.newIntent(context)
    context.startActivity(intent)
}

// Using Activity - My events only
fun startPastEventsActivityMyEvents(context: Context) {
    val intent = AmityPastEventsPageActivity.newIntent(context)
    context.startActivity(intent)
}
```

```typescript React
import { AmityUiKitProvider, AmityPastEventsPage } from '@amityco/ui-kit';

const SampleAmityPastEventsPageActivityPage = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPastEventsPage />
    </AmityUiKitProvider>
  );
};
```


    ### Feed Components

    **Event discovery surfaces embedded in existing feature pages**

    The Event feature integrates with these components:

    - **AmityExploreEventFeedComponent**
    - **AmityMyEventFeedComponent**
    - **AmityEventInfoComponent**
    - **AmityEventDiscussionFeedComponent**

    These components are typically used inside existing UIKit pages (e.g., Social Home and Community Profile). If you’re using the standard Social Home experience, you get these feeds automatically.

      The **Explore** and **Happening now** discovery feeds exclude events created by the current user, so people only see events from others when browsing. This is handled automatically by the UIKit — no configuration required.


    #### Code Examples

    #### AmityExploreEventFeedComponent


```swift iOS
    // Show explore event feed component
    let exploreEventComponent = AmityExploreEventFeedComponent(pageId: .socialHomePage)
    let viewController = AmitySwiftUIHostingController(rootView: exploreEventComponent)
    navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeExploreEventFeed() {
    // Get flows directly from SDK repository
    val liveEvents = remember {
        AmitySocialClient.newEventRepository()
            .getLiveEvents()
            .cachedIn(viewModelScope)
    }.collectAsLazyPagingItems()

    val upcomingEvents = remember {
        AmitySocialClient.newEventRepository()
            .getUpcomingEvents()
            .cachedIn(viewModelScope)
    }.collectAsLazyPagingItems()

    AmityExploreEventFeedComponent(
        liveEvents = liveEvents,
        upcomingEvents = upcomingEvents
    )
}
```

```typescript React
import { AmityUiKitProvider, AmityExploreEventFeedComponent } from '@amityco/ui-kit';

const SampleAmityExploreEventFeedComponent = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityExploreEventFeedComponent pageId="your_pageId" />
    </AmityUiKitProvider>
  );
};
```


     #### AmityMyEventFeedComponent


```swift iOS
    // Show my event feed component
    let myEventComponent = AmityMyEventFeedComponent(pageId: .socialHomePage)
    let viewController = AmitySwiftUIHostingController(rootView: myEventComponent)
    navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeMyEventFeed() {
    // Get flows directly from SDK repository
    val liveEvents = remember {
        AmitySocialClient.newEventRepository()
            .getLiveEvents()
            .cachedIn(viewModelScope)
    }.collectAsLazyPagingItems()

    val upcomingEvents = remember {
        AmitySocialClient.newEventRepository()
            .getMyUpcomingEvents()
            .cachedIn(viewModelScope)
    }.collectAsLazyPagingItems()

    val pastEvents = remember {
        AmitySocialClient.newEventRepository()
            .getPastEvents()
            .cachedIn(viewModelScope)
    }.collectAsLazyPagingItems()

    AmityMyEventFeedComponent(
        liveEvents = liveEvents,
        upcomingEvents = upcomingEvents,
        pastEvents = pastEvents
    )
}
```

```typescript React
import { AmityUiKitProvider, AmityMyEventFeedComponent } from '@amityco/ui-kit';

const SampleAmityMyEventFeedComponent = () => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityMyEventFeedComponent pageId="your_pageId" />
    </AmityUiKitProvider>
  );
};
```


     #### AmityEventInfoComponent


```swift iOS
    let eventDetailViewModel = AmityEventDetailPageViewModel(event: event)
    let eventInfoComponent = AmityEventInfoComponent(viewModel: eventDetailViewModel)
    let viewController = AmitySwiftUIHostingController(rootView: eventInfoComponent)
    navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeEventInfo(
    event: AmityEvent
) {
    AmityEventInfoComponent(
        event = event
    )
}
```

```typescript React
import { AmityUiKitProvider, AmityEventInfoComponent } from '@amityco/ui-kit';

const SampleAmityEventInfoComponent = ({ event }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventInfoComponent pageId="your_pageId" event={event} />
    </AmityUiKitProvider>
  );
};
```


     #### AmityEventDiscussionFeedComponent


```swift iOS
// Show event discussion feed component (requires an event and view model)
let eventDetailViewModel = AmityEventDetailPageViewModel(event: event)
let discussionFeedComponent = AmityEventDiscussionFeedComponent(viewModel: eventDetailViewModel)
let viewController = AmitySwiftUIHostingController(rootView: discussionFeedComponent)
navigationController?.pushViewController(viewController, animated: true)
```


```kotlin Android
@Composable
fun composeEventDiscussionFeed(
    eventId: String
) {
    val viewModel: AmityEventDetailViewModel = viewModel()
    val lazyListState = rememberLazyListState()

    LaunchedEffect(eventId) {
        viewModel.loadEvent(eventId)
    }

    AmityEventDiscussionFeedComponent(
        viewModel = viewModel,
        lazyListState = lazyListState,
        shouldRefresh = false,
        header = {
            item {
                Text("Event Discussion Header")
            }
        }
    )
}
```

```typescript React
import { AmityUiKitProvider, AmityEventDiscussionFeedComponent } from '@amityco/ui-kit';

const SampleAmityEventDiscussionFeedComponent = ({ event }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventDiscussionFeedComponent pageId="your_pageId" event={event} />
    </AmityUiKitProvider>
  );
};
```


    #### Customization Options

    | Config ID                                               | Type      | Description                                      |
    | ------------------------------------------------------- | --------- | ------------------------------------------------ |
    | `social_home_page/my_event_feed_component/*`            | Component | Customize My Event feed section                  |
    | `social_home_page/explore_event_feed_component/*`       | Component | Customize Explore Event feed section             |
    | `community_profile_page/*/create_event_button`          | Element   | Customize create event button label              |
    | `social_home_page/create_post_menu/create_event_button` | Element   | Customize create-event entry in create-post menu |

      If you need to hook navigation (e.g., “View all upcoming”), use the corresponding Behavior class documented in the next tab.

    Any event can be published as a post so it renders as an **event card** inside a feed. The post carries the author's text and the event supplies the card; tapping the card opens the event detail page rather than a generic post detail view. The SDK contract is documented in [Event Posts](/social-plus-sdk/social/content-management/posts/creation/event-post).

    ### Flow

    1. Host / Moderator / Member taps **Post event to feed** in the event detail 3-dot menu.
    2. `AmityEventPostTargetSelectionPage` shows the target choices. For a private-community event, it shows only the origin community; for other events, it shows My Timeline and eligible communities.
    3. `AmityPostComposerPage` opens in event-post mode with the title and body prefilled from the event.
    4. The user optionally edits the text, then publishes. The post appears in the target feed as an event card.

    #### Post-creation prompt

    There is a second entry point into the same flow. Immediately after a host creates an event, a modal bottom sheet prompts them to publish it — "Your event was created successfully" / "Post it to a feed so more people can find and join", with **Post to feed** and **Maybe later** actions. **Post to feed** enters the flow at step 2.

    This sheet **replaces** the usual "event created" toast for the host, so it changes the existing create-event flow, not just the event-post flow. It is shown once per creation.

    ### AmityEventPostTargetSelectionPage

    Use **AmityEventPostTargetSelectionPage** to pick where the event post is published. It has two variants driven by the event's origin:

    - **Full variant** (public-community or user-hosted event) — the "My Timeline" row plus the paginated list of communities the user can post in. No target is preselected; the user chooses one.
    - **Restricted variant** (private-community event) — a banner explains the lock and a single row shows the event's origin community with a `Private` badge. The user cannot pick any other target.

    **Public API:**

```swift
AmityEventPostTargetSelectionPage(event: AmityEvent)
```

    #### Customization Options

    Android and Web use event-specific configuration keys. iOS uses the shared post-target-selection page identifier because the event-post page reuses the normal post-target-selection configuration.

    | Config ID | Platforms | Type | Description |
    | --- | --- | --- | --- |
    | `event_post_target_selection_page/*/*` | Android, Web | Page | Customize page theme |
    | `event_post_target_selection_page/*/title` | Android, Web | Element | Customize page title |
    | `event_post_target_selection_page/*/close_button` | Android, Web | Element | Customize close button image |
    | `select_post_target_page/*/*` | iOS | Page | Customize page theme |
    | `select_post_target_page/*/title` | iOS | Element | Customize page title |
    | `select_post_target_page/*/close_button` | iOS | Element | Customize close button image |

    #### Code Examples


```swift iOS
let page = AmityEventPostTargetSelectionPage(event: event)
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeEventPostTargetSelectionPage(event: AmityEvent) {
    AmityEventPostTargetSelectionPage(event = event)
}

// Or launch the activity directly:
val intent = AmityEventPostTargetSelectionPageActivity.newIntent(
    context = context,
    event = event,
)
context.startActivity(intent)
```

```typescript React
import { AmityUiKitProvider, AmityEventPostTargetSelectionPage } from '@amityco/ui-kit';

const SampleAmityEventPostTargetSelectionPage = ({ event }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityEventPostTargetSelectionPage event={event} />
    </AmityUiKitProvider>
  );
};
```


    ### Composer in Event-Post Mode

    `AmityPostComposerPage` accepts an event-post mode that prefills fields from the event and disables inputs that the backend rejects for event posts.

    **Prefill (one-time copy, editable):**

    | Composer field | Source |
    | --- | --- |
    | Title | `event.title` |
    | Body | `event.description` |

    Clearing both fields still publishes — the event card is the payload.

    **Unavailable in event-post mode:**

    - Media attachments (image / video / file / audio / clip)
    - Product tags
    - URL link-preview card (URLs still autolink inside the body)
    - Detach or swap event — the event reference is immutable

    **Public API:**

    iOS and Web add a dedicated composer mode:

```swift
public enum AmityPostComposerOptions {
  case createOptions(mode, targetId, targetType, community?, event?)
  case editOptions(mode, post)
  case createEventPostOptions(event, targetId, targetType)
}

AmityPostComposerPage(options: AmityPostComposerOptions)
```

    On iOS the private-community target lock is applied upstream on `AmityEventPostTargetSelectionPage` (which decides `targetId` before the composer opens), so `createEventPostOptions` has no `isTargetLocked` parameter.

    Android has no separate mode. The existing create options carry optional event parameters, and the composer switches into event-post mode when `attachedEventId` is set. Note that it takes an **event ID**, not an `AmityEvent`, and has no `isTargetLocked` — on Android the lock is applied upstream on the target-selection page.

```kotlin
AmityPostComposerOptions.AmityPostComposerCreateOptions(
    targetId: String?,
    targetType: AmityPostTargetType,
    community: AmityCommunity?,
    attachedEventId: String?,
    prefilledTitle: String?,
    prefilledBody: String?,
)

AmityPostComposerPage(options: AmityPostComposerOptions)
```

    #### Code Examples


```swift iOS
let options = AmityPostComposerOptions.createEventPostOptions(
    event: event,
    targetId: targetId,
    targetType: .community
)
let page = AmityPostComposerPage(options: options)
let viewController = AmitySwiftUIHostingController(rootView: page)
navigationController?.pushViewController(viewController, animated: true)
```

```kotlin Android
@Composable
fun composeCreateEventPost(
    event: AmityEvent,
    targetId: String,
    targetType: AmityPostTargetType,
    community: AmityCommunity?,
) {
    AmityPostComposerPage(
        options = AmityPostComposerOptions.AmityPostComposerCreateOptions(
            targetId = targetId,
            targetType = targetType,
            community = community,
            attachedEventId = event.getEventId(),
            prefilledTitle = event.getTitle(),
            prefilledBody = event.getDescription(),
        )
    )
}
```

```typescript React
import { AmityUiKitProvider, AmityPostComposerPage } from '@amityco/ui-kit';

const SampleCreateEventPost = ({ event, targetId, targetType, isTargetLocked }) => {
  return (
    <AmityUiKitProvider
      apiKey="API_KEY"
      apiRegion="API_REGION"
      userId="userId"
      displayName="displayName"
      configs={{}}
    >
      <AmityPostComposerPage
        mode="createEventPost"
        event={event}
        targetId={targetId}
        targetType={targetType}
        isTargetLocked={isTargetLocked}
      />
    </AmityUiKitProvider>
  );
};
```


    ### Editing an Event Post

    Editing an event post uses `AmityPostComposerPage` in `edit` mode. Only `data.title` and `data.text` are editable — the event reference is immutable, and the event itself is never modified from the post.

    If the referenced event has been deleted, the composer still opens and text edits still save; the embedded event card renders its deleted state. A **cancelled** event is treated identically to a deleted one.

    ### Event Post in Feeds

    `AmityPostContentComponent` renders an event card whenever a post's `dataType` is `event`. The event card reuses the existing `EventCard` component — no new element is introduced.

    **Card states:**

    | State | Behavior |
    | --- | --- |
    | Resolved | Cover image, start–end time, title, "By {host}". Tapping the card navigates to the event detail page. |
    | Loading | Skeleton while the event resolves; not tappable. |
    | Deleted | Shows "This event is no longer available." The card is non-interactive; only the resolved card navigates. Comments and reactions on the post survive. |

    A **cancelled** event and an event missing from the payload both normalise into the deleted state — there is no separate cancelled treatment.

    **Tap-through:**

    The tap-through behavior differs from other post types:

    | Region tapped | Destination |
    | --- | --- |
    | Event card | Event detail page, via `AmityPostContentComponentBehavior.goToEventDetailPage` |
    | Header / author avatar | Author profile (default) |
    | Caption text | Post detail (default) |
    | Engagement bar | Post detail with comments (default) |
    | 3-dot menu | Action sheet (default) |

    **Pinned / featured badges are read-only in UIKit.** The badge renders whenever a post is pinned or featured, but there is no in-app control to change that state — the control lives in the Console. See the [Console note on pin/feature](/social-plus-sdk/social/content-management/posts/moderation/pin-post) for details.

      A post published to a user's own feed can never be pinned. Global featuring requires a public community.


## Customization

UIKit provides these customization keys for event entry points and pages.

```json
{
  "*/community_sidebar/communities_sidebar_menu_item": {
    "text": "Communities",
    "icon": ""
  },
  "*/community_sidebar/events_sidebar_menu_item": {
    "text": "Events",
    "icon": ""
  },

  "social_home_page/*/communities_button": {
    "text": "Communities"
  },
  "social_home_page/*/events_button": {
    "text": "Events"
  },
  "social_home_page/create_post_menu/create_event_button": {
    "text": "Event",
    "image": ""
  },
  "social_home_page/my_event_feed_component/*": {},
  "social_home_page/explore_event_feed_component/*": {},

  "community_profile_page/*/create_event_button": {
    "text": "Event"
  },

  "select_event_target_page/*/*": {},
  "select_event_target_page/*/close_button": {
    "image": ""
  },
  "select_event_target_page/*/title": {
    "text": "Create event in"
  },

  "event_setup_page/*/*": {},
  "event_setup_page/*/title": {
    "text": "Create event"
  },
  "event_setup_page/*/camera_button": {
    "text": "Camera",
    "image": ""
  },
  "event_setup_page/*/image_button": {
    "text": "Photo",
    "image": ""
  },
  "event_setup_page/*/event_name_title": {
    "text": "Event name"
  },
  "event_setup_page/*/event_details_title": {
    "text": "Event details"
  },
  "event_setup_page/*/event_date_time_title": {
    "text": "Date and time"
  },
  "event_setup_page/*/event_location_title": {
    "text": "Location"
  },

  "upcoming_events_page/*/*": {},

  "past_events_page/*/*": {},

  "event_detail_page/*/create_event_post_button": {
    "text": "Post event to feed",
    "image": ""
  },

  "event_post_target_selection_page/*/*": {},
  "event_post_target_selection_page/*/title": {
    "text": "Post to"
  },
  "event_post_target_selection_page/*/close_button": {
    "image": ""
  },

  "select_post_target_page/*/*": {},
  "select_post_target_page/*/title": {
    "text": "Post to"
  },
  "select_post_target_page/*/close_button": {
    "image": ""
  }
}
```

## Behavior Customization

UIKit provides behavior classes to customize navigation and actions for event-related pages and components.

### Page Behaviors

```swift
class AmityEventTargetSelectionPageBehavior {

    goToEventSetupPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityEventSetupPageBehavior {

    goToEventDetailPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityEventDetailPageBehavior {

    goToEventSetupPage(context): void {
      // navigation logic
    }

    goToLivestreamPostComposerPage(context): void {
      // navigation logic
    }

    goToPostDetailPage(context): void {
      // navigation logic
    }

    goToPostComposerPage(context): void {
      // navigation logic — used for private-community events (target locked)
    }

    goToPollPostComposerPage(context): void {
      // navigation logic
    }

    goToEventPostTargetSelectionPage(context): void {
      // navigation logic — used for public-community / user-hosted events
    }

    goToCommunityProfilePage(context): void {
      // navigation logic
    }

    goToEventAttendeesPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityEventPostTargetSelectionPageBehavior {

    goToPostComposerPage(context): void {
      // navigation logic — opens composer in event-post mode with the resolved target
    }

}
```

```swift
class AmityEventAttendeesPageBehavior {

    goToUserProfilePage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityNotificationTrayPageBehavior {

    // ... existing behaviors

    goToEventDetailPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityCommunityProfilePageBehavior {

    // ... existing behaviors

    goToEventDetailPage(context): void {
      // navigation logic
    }

}
```


### Component Behaviors

```swift
class AmityExploreEventFeedComponentBehavior {

    goToUpcomingEventsPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityMyEventFeedComponentBehavior {

    goToUpcomingEventsPage(context): void {
      // navigation logic
    }

    goToPastEventsPage(context): void {
      // navigation logic
    }

}
```

```swift
class AmityCreatePostMenuComponentBehavior {

    // ... existing behaviors

    goToSelectEventTargetPage(): void {
      // navigation logic
    }

}
```

```swift
class AmityPostContentComponentBehavior {

    // ... existing behaviors

    goToEventDetailPage(context): void {
      // navigation logic — invoked when the event card region of an event post is tapped
    }

}
```

```swift
class AmityMyCommunitiesComponentBehavior {

    // ... existing behaviors

    goToCommunitySetupPage(): void {
      // navigation logic
    }

}
```


## Related Topics

    title="Events SDK"
    icon="code"
    href="/social-plus-sdk/social/events/overview"
  >
    SDK event APIs and data models
    title="Community"
    icon="users"
    href="/uikit/components/social/community"
  >
    Community UI components
    title="Livestream"
    icon="video"
    href="/uikit/components/social/livestream"
  >
    Livestream UI components

---

### [Content Sharing](https://learn.social.plus/uikit/components/social/sharing)

> Enable users to share content through customizable sharing interfaces with copy and native share options

**UIKit Component**: Sharing components are built on top of the social.plus
  UIKit, providing ready-to-use sharing interfaces with customizable copy and
  native share sheet functionality across all supported content types.

## Feature Overview

The Sharing UIKit components provide comprehensive tools for enabling content sharing throughout your application. Users can share posts, profiles, communities, live streams, and events through two primary methods: copying shareable links or using native platform share sheets. These components integrate seamlessly across multiple pages and content types.

### Key Features

    **Copy link and native sharing** - Copy shareable links to clipboard -
    Native platform share sheet integration - Consistent sharing experience
    across content types - Platform-optimized sharing workflows
    **Flexible UI customization** - Custom icons and text labels - Page-specific
    configurations - Theme-consistent styling - Brand-aligned messaging

<div style={{ textAlign: "center", margin: "40px 0" }}>
  <img
    src="/images/uikit-shareable-link.png"
    alt="UIKit Sharing Interface"
    style={{ maxWidth: "100%", height: "auto" }}
  />
</div>

The sharing functionality is available across these key areas of your application:

| Location                    | Share Types       | Description                                      |
| --------------------------- | ----------------- | ------------------------------------------------ |
| **User Profile Page**       | Profile links     | Share user profiles for networking and discovery |
| **Community Profile Page**  | Community links   | Share community pages to grow membership         |
| **Post Content Component**  | Post links        | Share individual posts across all post types     |
| **Post Detail Page**        | Post links        | Share posts from detailed view                   |
| **Live Stream Player Page** | Live stream links | Share active live streams                        |
| **Create Live Stream Page** | Live stream links | Share live stream setup and promotion            |
| **Clip Feed Page**          | Clip links        | Share video clips from feed views                |
| **Event Detail Page**       | Event links       | Share events from the event detail page's 3-dot menu |

## Customization

    Enable sharing for user profiles and networking

    User profile sharing allows users to share their own profiles or other users' profiles for networking, collaboration, and community building purposes.

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `user_profile_page/*/share_link` | Element | Customize share button icon and text |
    | `user_profile_page/*/copy_link` | Element | Customize copy button icon and text |


    Enable sharing for communities and growth

    Community sharing facilitates community discovery and growth by allowing users to share community links through multiple channels.

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `community_profile_page/*/share_link` | Element | Customize share button icon and text |
    | `community_profile_page/*/copy_link` | Element | Customize copy button icon and text |


    Enable sharing for all post types

    Post content sharing allows users to share individual posts across all supported post types, including text, image, video, clip, and live stream posts.

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `*/post_content/share_link` | Element | Customize share button icon and text for post components |
    | `*/post_content/copy_link` | Element | Customize copy button icon and text for post components |
    | `post_detail_page/*/share_link` | Element | Customize share button icon and text for post detail page |
    | `post_detail_page/*/copy_link` | Element | Customize copy button icon and text for post detail page |


    Enable sharing for live streaming content

    Live stream sharing allows users to share live streaming content both during stream creation and while viewing active streams.

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `livestream_player_page/*/share_link` | Element | Customize share button for live stream player |
    | `livestream_player_page/*/copy_link` | Element | Customize copy button for live stream player |
    | `create_livestream_page/*/share_link` | Element | Customize share button for stream creation |
    | `create_livestream_page/*/copy_link` | Element | Customize copy button for stream creation |
    | `clip_feed_page/*/share_link` | Element | Customize share button for clip feeds |
    | `clip_feed_page/*/copy_link` | Element | Customize copy button for clip feeds |


    Enable sharing for events

    Event sharing adds **Copy event link** (all platforms) and **Share to** (mobile only) to the event detail page's 3-dot action menu. Visibility follows the network shareable-link configuration and the event's community type — see [Event → Share an event](/uikit/components/social/event#share-an-event).

    #### Customization Options

    | Config ID | Type | Description |
    |-----------|------|-------------|
    | `event_detail_page/*/*` | Page | Customize the event detail page theme |

    The Copy / Share actions are menu items rather than standalone elements — customize their labels through [localization](/uikit/customization/localization) (`amity_social_button_copy_event_link`, `amity_social_button_share_to`).


## Best Practices

    - **Clear Visual Feedback**: Provide immediate feedback when links are copied
    - **Consistent Placement**: Position share options consistently across similar content types
    - **Contextual Messaging**: Use content-specific share messages and labels
    - **Accessibility**: Ensure share buttons are accessible with proper labels and touch targets

{" "}

  - **Brand Consistency**: Use consistent icons and messaging that match your
  brand - **Platform Optimization**: Customize labels for platform-specific
  sharing conventions - **Content Context**: Tailor share messages to the
  specific content being shared - **User Guidance**: Use clear, action-oriented
  text for share and copy buttons

    - **Lazy Link Generation**: Generate share links only when sharing is initiated
    - **Error Handling**: Implement graceful error handling for failed share operations
    - **Network Optimization**: Cache share configurations to minimize API calls
    - **Background Processing**: Handle link generation without blocking the UI

## Common Use Cases

- **Content Virality**: Enable easy sharing to increase content reach and engagement
- **Community Growth**: Share community links to attract new members and expand reach
- **User Acquisition**: Use profile sharing for networking and user discovery
- **Live Engagement**: Share live streams to maximize viewer participation
- **Content Discovery**: Share interesting posts to help users discover new content

## Troubleshooting

    **Problem**: Share buttons are not visible in expected locations

    **Solutions**:
    - Verify sharing functionality is enabled in your app configuration
    - Check that URL patterns are properly configured in the social.plus console
    - Ensure proper authentication and permissions for content access
    - Validate that the content exists and is accessible

```swift
// Verify share configuration
let config = AmityUIKitManager.getShareConfiguration()
if config.isEnabled {
    // Sharing should be available
}
```

    **Problem**: Copy to clipboard functionality not working

    **Solutions**:
    - Check clipboard permissions on the platform
    - Verify that the generated link is valid
    - Ensure proper error handling for clipboard operations
    - Test on different devices and platforms

```typescript
try {
  await navigator.clipboard.writeText(shareLink);
  // Show success feedback
} catch (error) {
  // Handle clipboard permission or other errors
  console.error('Copy failed:', error);
}
```

    **Problem**: Native share sheet not opening or functioning correctly

    **Solutions**:
    - Verify platform-specific share sheet permissions
    - Check that the content and link are properly formatted
    - Ensure the app has proper entitlements for sharing
    - Test with different content types and platforms

```swift
// iOS share sheet validation
if UIActivityViewController.canPerform(activity: .postToFacebook) {
    // Share sheet should work
}
```

## Related Components

    Learn about user profile components and profile sharing
    title="Communities"
    href="/uikit/components/social/communities"
    icon="users"
  >
    Discover community components and community sharing
    title="Posts & Media"
    href="/uikit/components/social/posts"
    icon="photo-film"
  >
    Explore post components and content sharing options
    title="Live Streaming"
    href="/uikit/components/social/livestreaming"
    icon="video"
  >
    Learn about live streaming and stream sharing features
    title="Social Feeds"
    href="/uikit/components/social/feeds"
    icon="newspaper"
  >
    Understand feed components and inline sharing
    title="Events"
    href="/uikit/components/social/event"
    icon="calendar"
  >
    Explore event components and event link sharing
    title="SDK Content Sharing"
    href="/social-plus-sdk/social/content-management/content-sharing"
    icon="code"
  >
    Learn about the underlying SDK sharing implementation

  **Implementation Strategy**: Start by enabling sharing in high-engagement
  areas like post feeds and user profiles. Configure consistent branding and
  messaging across all sharing locations. Test both copy and native share
  functionality on all target platforms. Consider analytics tracking to
  understand which sharing methods users prefer and optimize accordingly.

---

### [Product Tagging Components](https://learn.social.plus/uikit/components/social/product-tagging)

> Shared UIKit components for product selection, display, and management used in posts and livestreams

These are shared UIKit components used by both post and livestream product tagging features. For feature-level documentation — including behaviour, limits, and when to use each component — see [Post Components](/uikit/components/social/posts#product-tagging) and [Livestream](/uikit/components/social/livestream#product-tagging).

## Platform Support

| Component | iOS | Android | Web | React Native | Flutter |
| --- | --- | --- | --- | --- | --- |
| ProductTagSelectionComponent | ✅ | ✅ | ✅ | ❌ | ❌ |
| ProductTagListComponent | ✅ | ✅ | ✅ | ❌ | ❌ |
| ManageProductTagListComponent | ✅ | ✅ | ✅ | ❌ | ❌ |

## ProductTagSelectionComponent

A searchable, multi-select product picker used when tagging products in a post or livestream. The component operates in one of three modes depending on context.

  <img
    src="/images/product-tag-selection.png"
    alt="ProductTagSelectionComponent shows interface for selecting products"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

### Mode Behaviour

| Mode | Header Title | Used in |
| --- | --- | --- |
| `create` | "Tag products" | Post creation |
| `edit` | "Edit tags" | Post editing |
| `livestream` | "Add products" | Livestream tagging |

Products already tagged elsewhere (e.g. on another media item) are shown in the list but appear disabled and cannot be re-selected.

### Code Examples


```swift iOS
AmityProductTagSelectionComponent(
    pageId: .postComposerPage,
    selectedProductTags: selectedProducts,
    existingProducts: ["product-3", "product-4"], // Already tagged - shown disabled
    mode: .create,  // .create | .edit | .livestream
    onTagChanges: { tags in
        // Handle selection changes
    },
    onDone: {
        // Handle completion (create/edit modes)
    },
    onClose: {
        // Handle dismissal (livestream mode)
    }
)
```

```kotlin Android
AmityProductTagSelectionComponent(
    pageScope = pageScope,
    selectedProductTags = selectedProductTags,
    existingProducts = listOf("product-3", "product-4"),
    mode = SelectionMode.CREATE,  // CREATE | EDIT | LIVESTREAM
    maxCount = 20,
    canMultiSelect = true,
    onTagChanges = { tags ->
        // Handle selection changes
    },
    onDone = {
        // Handle completion (create/edit modes)
    },
    onClose = {
        // Handle dismissal
    }
)
```

```typescript Web/React
<AmityProductTagSelectionComponent
  pageId="post_composer_page"
  selectedProductTags={selectedProducts}
  existingProducts={["product-3", "product-4"]}
  mode="create"  // "create" | "edit" | "livestream"
  displayMode="mobile"  // "desktop" | "mobile"
  onTagChanges={(tags) => {
    // Handle selection changes
  }}
  onDone={() => {
    // Handle completion (create/edit modes)
  }}
  onClose={() => {
    // Handle dismissal
  }}
/>
```


## ProductTagListComponent

A read-only, vertically scrollable list that displays tagged products below post content. The header label adapts to the render mode context.

  <img
    src="/images/product-tag-list.png"
    alt="ProductTagListComponent shows products list"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

### Render Mode Header Text

| Mode | Header Text | Used in |
| --- | --- | --- |
| `post` | "Products tagged in this post" | Post feed and post detail |
| `image` | "Products tagged in this photo" | Image attachment view |
| `video` | "Products tagged in this video" | Video attachment view |
| `livestream` | "Products tagged" | Livestream viewer overlay |

  <img
    src="/images/product-tag-list-livestream.png"
    alt="ProductTagListComponent in livestream mode — viewer product list bottom sheet"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

### Code Examples


```swift iOS
AmityProductTagListComponent(
    pageId: .postDetailPage,
    productTags: taggedProducts,
    renderMode: .post,  // .post | .livestream | .image | .video
    onProductClick: { productTag in
        // Handle product interaction
    }
)
.environmentObject(host)
```

```kotlin Android
AmityProductTagListComponent(
    productTags = taggedProducts,
    renderMode = RenderModeEnum.POST,  // POST | LIVESTREAM | IMAGE | VIDEO
    displayMode = "mobile",
    onDismiss = {
        // Handle dismissal
    },
    onProductClick = { product, analyticsLocation ->
        // Handle product click
    }
)
```

```typescript Web/React
<AmityProductTagListComponent
  productTags={taggedProducts}
  renderMode="post"  // "post" | "livestream" | "image" | "video"
  displayMode="desktop"  // "desktop" | "mobile"
  onProductClick={(productTag) => {
    // Handle product interaction
  }}
/>
```


## ManageProductTagListComponent

A management interface for hosts and co-hosts to tag, pin, and remove products during a livestream. Used in a bottom sheet (mobile) or popup (desktop). Also used in read-only mode for post-live replay.

  <img
    src="/images/manage-product-tag-list.png"
    alt="ManageProductTagListComponent showing pinned product and other products list"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

### Render Mode Behaviour

| Mode | Pin controls | Used in |
| --- | --- | --- |
| `livestream` | Enabled | Active livestream — host/co-host management |
| `playback` | Disabled | Post-live replay view |

When products are present, the list is organised into a pinned section at the top (single product) and an "Other products" section below. When empty, a call-to-action to add products is shown.

### Code Examples


```swift iOS
import AmityUIKit4

AmityManageProductTagListComponent(
    pageId: .livestreamPage,
    viewModel: manageProductTagViewModel,
    renderMode: .livestream,
    onClose: { products in
        // Update local tagged products state
        taggedProducts = products
    },
    onAddProducts: {
        // Present product selection sheet
    },
    onPinToggle: { productId, shouldPin in
        viewModel.pinProduct(productId: productId, pin: shouldPin)
    },
    onProductRemove: { productId in
        viewModel.removeProduct(productId: productId)
    }
)
.environmentObject(host)
```

```kotlin Android
import com.amity.socialcloud.uikit.community.compose.livestream.room.create.AmityManageProductTagListComponent

AmityManageProductTagListComponent(
    taggedProducts = taggedProducts,
    maxCount = 20,
    pinnedProductId = pinnedProductId,
    componentScope = componentScope,
    canManageProducts = true,
    isPostLive = true,
    onDismiss = {
        // Dismiss the bottom sheet
    },
    onRemoveProduct = { productId ->
        viewModel.removeProduct(productId)
    },
    onPinProduct = { productId ->
        viewModel.pinProduct(productId)
    },
    onAddProducts = {
        // Navigate to product selection screen
    },
    onProductClick = { product, location ->
        // Handle product tap (e.g. open product detail)
    },
    onProductViewed = { product, location ->
        // Fire analytics impression event
    }
)
```

```typescript Web/React
import { AmityManageProductTagListComponent } from "@amityco/ui-kit-open-source";

<AmityManageProductTagListComponent
  pageId="livestream_page"
  productTags={productTags}
  pinnedProductId={pinnedProductId}
  maxCount={20}
  isHost={true}
  renderMode="livestream"
  sourceId={streamId}
  onProductTagsChange={(tags) => {
    setProductTags(tags);
  }}
  onUpdateProductTags={async (tags) => {
    return await updatePostProductTags(tags);
  }}
  onRemove={(productTag) => {
    removeProductTag(productTag);
  }}
  onPinnedProductIdChange={(newPinnedId) => {
    setPinnedProductId(newPinnedId);
  }}
  isPinning={isPinning}
  isUnpinning={isUnpinning}
  onClose={(tags, pinnedId) => {
    handleClose(tags, pinnedId);
  }}
/>
```


## Related

    Product tagging behaviour, limits, and UX rules for posts

    Product tagging phases, pinning, co-host permissions, and viewer experience for livestreams

## UIKit — Customization

### [UIKit Customization](https://learn.social.plus/uikit/customization/overview)

> Comprehensive guide to customizing social.plus UIKit components to match your brand

social.plus UIKit offers three levels of customization to match your needs. Choose the right approach based on how much control you need over the user interface.

## Choose Your Customization Level

    title="Dynamic UI"
    icon="palette"
    href="/uikit/customization/dynamic-ui"
  >
    **Minimal Customization**
    - Colors, text, and basic styling
    - No code changes required
    - Perfect for brand consistency
    - Real-time updates without app releases
    title="Component Styling"
    icon="paintbrush"
    href="/uikit/customization/component-styling"
  >
    **Moderate Customization**
    - Custom CSS and styling overrides
    - Advanced theming options
    - Component-level modifications
    - Still within UIKit framework
    title="Fork & Extend"
    icon="code-fork"
    href="/uikit/customization/advanced-customization"
  >
    **Advanced Customization**
    - Complete control over components
    - Custom layouts and workflows
    - Maintain your own version
    - Jumpstart for complex projects

**Start simple and scale up:** Begin with Dynamic UI for quick brand consistency, move to Component Styling for deeper control, or Fork & Extend when you need complete customization freedom.

---

## Level 1: Dynamic UI - Minimal Cacheustomization

Perfect for teams who want to **quickly customize colors, text, and basic styling** without writing any code.

    title="Configuration-Based"
    icon="file-code"
    href="/uikit/customization/dynamic-ui"
  >
    **Single config.json File**
    - Centralized customization
    - Light and dark themes
    - Brand colors and typography
    - No app updates required
    title="Real-time Updates"
    icon="wand-magic-sparkles"
    href="/uikit/customization/dynamic-ui"
  >
    **Live Configuration**
    - Instant theme switching
    - A/B testing capabilities
    - Remote configuration
    - Version control friendly

**Best for:** Quick launches, MVPs, brand consistency, teams without deep frontend expertise.

---

## Level 2: Component Styling - Moderate Customization

For teams who need **deeper styling control** while staying within the UIKit framework.

    title="Advanced Theming"
    icon="paintbrush"
    href="/uikit/customization/theming-basics"
  >
    **CSS & Style Overrides**
    - Custom stylesheets
    - Component-specific styling
    - Advanced color schemes
    - Typography control
    title="Component Control"
    icon="puzzle-piece"
    href="/uikit/customization/component-styling"
  >
    **Granular Customization**
    - Individual component styling
    - Page-specific themes
    - Element-level customization
    - Conditional styling

**Best for:** Custom brand experiences, unique styling requirements, teams with frontend expertise.

---

## Level 3: Fork & Extend - Advanced Customization

For teams who need **complete control** over components and user flows.

    title="Complete Control"
    icon="code-fork"
    href="https://github.com/AmityCo/Amity-Social-UIKit-React-Native-OpenSource"
  >
    **Fork GitHub Repository**
    - Access to full source code
    - Modify any component or workflow
    - Custom layouts and interactions
    - Unlimited customization freedom
    title="Maintain Your Version"
    icon="code-branch"
    href="/uikit/customization/advanced-customization"
  >
    **Full Ownership**
    - Your own codebase
    - Custom feature development
    - Integration with existing systems
    - Professional development workflow

**Best for:** Complex custom requirements, existing app integration, teams with strong development resources.

### When to Fork & Extend

Consider forking when you need:
- Custom user flows that don't exist in UIKit
- Integration with complex existing systems
- Unique layouts that can't be achieved with styling
- Complete control over the development roadmap

---

## Decision Matrix

| Goal / Constraint | Dynamic UI | Component Styling | Fork & Extend |
|-------------------|-----------|-------------------|---------------|
| Rebrand colors quickly | ✅ | ✅ | Overkill |
| Per-component styling | ❌ | ✅ | ✅ (more cost) |
| New flow / navigation paradigm | ❌ | ⚠️ Limited | ✅ |
| Replace data layer / inject custom services | ❌ | ❌ | ✅ |
| Deep performance tuning / virtualization changes | ❌ | ❌ | ✅ |
| Add brand-new primitive (e.g. Custom feed) | ❌ | ❌ | ✅ |
| Minimal maintenance capacity | ✅ | ✅ | ❌ |

## Taxonomy: Elements → Components → Pages

    Primitive building blocks (buttons, text, avatar). Light logic. Style mostly via tokens; rarely stateful beyond hover / active / disabled.
    <strong>Presentational</strong>: Compose elements; focus on layout / visuals.
    <br/>
    <strong>Controller</strong>: Contain orchestration logic (e.g. data fetch, pagination). Examples: <code>FeedList</code>, <code>PostView</code>.
    Route-level surfaces combining multiple controller/components with navigation context.


**Need Help with Customization?**

Our design team is available to help you create the perfect look for your app. [Contact our customization experts](https://support.socialplus.com) for personalized assistance.

---

### [Dynamic UI](https://learn.social.plus/uikit/customization/dynamic-ui)

> Level 1: Minimal customization with real-time updates using configuration files

<strong>Key Benefit:</strong> Ship brand updates instantly. Dynamic UI lets non-engineering teams update theme tokens (colors today; typography & spacing roadmap) without app rebuilds.

<strong>Flutter:</strong> to switch the theme (light / dark / system) from your own code at runtime — e.g. an in-app appearance toggle — use <a href="/uikit/customization/set-preferred-theme">Set Preferred Theme</a>.

## Feature Overview

    Pure configuration-based customization, just need to trigger the sync function.
    Changes apply almost instantly without app updates
    Non-technical team members can make changes
    Maintain consistent styling across all platforms

## When to Choose Dynamic UI

Dynamic UI is ideal when you need:

✅ **Rapid brand implementation** – Ship palette changes fast without rebuilds
✅ **Near real-time theme rollout** – Toggle or refine colors almost instantly (A/B ready)
✅ **Non-engineering updates** – Design / product can adjust safely
✅ **Cross-platform consistency** – One remote source drives all clients
✅ **Low-risk experimentation** – Revert by re‑publishing a previous config

❌ **Structural layout changes** – Use Component Styling or Fork & Extend
❌ **Per-component state styling depth** – Escalate to Component Styling
❌ **Custom data flows / logic injection** – Fork & Extend
❌ **Brand-new UI or primitives** – Fork & Extend

Start here; you can layer Component Styling or Fork & Extend later without discarding work.

## How It Works


Edits remain in preview until published. A publish atomically replaces prior values. Clients already running will pick it up on the next sync trigger.

## Sync & Caching Behavior

    Fetches JSON → validates → caches → applies tokens → triggers UI re-render where token consumers exist.
    Uses last cached config. If none, falls back to build defaults (no crash / safe visuals).
    If validation fails, client ignores new payload and keeps prior cache (defensive). Log a warning.
    Auth required; only roles with Console permission can publish new themes.

## Implementation

    Call once at launch + on resume (and optionally a manual refresh action).

```swift iOS
import AmityUIKit

@MainActor
func syncTheme() async {
    do {
        try await AmityUIKit4Manager.syncNetworkConfig()
        print("Dynamic UI synced")
    } catch {
        print("Sync failed: \(error)")
    }
}
```

```kotlin Android
fun syncTheme() {
  AmityUIKit4Manager.syncNetworkConfig()
    .subscribeOn(Schedulers.io())
    .doOnComplete { Log.d("DynamicUI", "Synced") }
    .doOnError { e -> Log.e("DynamicUI", "Failed", e) }
    .subscribe()
}
```

```typescript React
import { AmityUIKitManager } from '@amityco/ui-kit';

export async function syncTheme() {
  try {
    await AmityUIKitManager.syncNetworkConfig();
    console.log('Dynamic UI synced');
  } catch (e) {
    console.error('Sync failed', e);
  }
}
```

```dart Flutter
import 'package:amity_uikit/amity_uikit.dart';

Future<void> syncTheme() async {
  try {
    await AmityUIKit4Manager.syncNetworkConfig();
    print('Dynamic UI synced');
  } catch (e) {
    print('Sync failed: $e');
  }
}
```

    **React Native**: The React Native UIKit doesn't support Dynamic UI sync — it has no `syncNetworkConfig`. Theme it with the local config file passed to `AmityUiKitProvider` through `configs`.
```js
// Pseudocode lifecycle examples
app.on('launch', syncTheme);
app.on('resume', syncTheme);
refreshButton.on('click', syncTheme);
```


## Next Steps


Log a design token adoption plan early so future roadmap features (typography/spacing) slot in without refactors.

---

### [Component Styling](https://learn.social.plus/uikit/customization/component-styling)

> Level 2: Moderate customization with CSS overrides and advanced theming

For teams who need **deeper styling control** while staying within the UIKit framework. Component Styling allows you to override CSS, customize individual components, and implement advanced theming.

    Override styles with custom config json
    Customize specific components and pages
    Complex color schemes and typography
    Still within the UIKit ecosystem

## When to Choose Component Styling

Component Styling is ideal when you need:

✅ **Custom brand experiences** - Basic colors and fonts
✅ **Granular control** - Target specific components or pages
✅ **Advanced theming** - Complex color schemes and typography
✅ **Framework benefits** - Want to stay within UIKit's ecosystem

❌ **Simple branding** - `Dynamic UI` is easier for basic needs
❌ **Complex layouts** - `Fork & Extend` offers more freedom
❌ **Custom components** - Need source code access for new components

------------
## Configuration Model

Component Styling uses a single `config.json` surface for cross-platform overrides. It layers on top of default UIKit tokens (and Dynamic UI if present) using a path pattern: <code>page_id/component_id/element_id</code> with wildcards (`*`).

### Path Pattern & Levels

| Level | Example | Description | Wildcard Use |
|-------|---------|-------------|--------------|
| Page | `camera_page/*/*` | Entire screen / route | Replace component & element with `*/*` |
| Component | `*/comment_tray_component/*` | Functional unit within a page | Wildcard page to apply globally |
| Element | `story_page/*/close_button` | Single interactive / visual element | Wildcard component for all instances |

Specific beats generic: Element overrides > Component overrides > Page overrides > Global theme.

### Supported Theme Tokens

Every key below may be set under `theme.light` and `theme.dark`. Any key you omit falls back to the
default shown. Defaults are identical across platforms — they ship in the same config template.

**Where each token applies.** Thirteen tokens resolve across **every** UIKit feature:
`primary_color`, `secondary_color`, `base_color`, `base_shade1_color` through `base_shade4_color`,
`base_inverse_color`, `alert_color`, `background_color`, `background_shade1_color`,
`highlight_color`, and `toast_background_color`.

The rest belong to a revised color set that currently drives **chat** components only. Setting them
has no effect on other features yet — those continue to resolve through the thirteen above, and
adopt the expanded set in a later release.

The revised set is available from these UIKit versions:

| Platform | Available from |
| :------- | :------------- |
| Android  | 4.23.0         |
| iOS      | 4.25.0         |
| Web      | 4.20.0         |
| Flutter  | 4.22.0         |

#### Core

| Token | Purpose | Default (light) | Default (dark) |
|-------|---------|-----------------|----------------|
| primary_color | Actions / highlights | `#1054DE` | `#1054DE` |
| secondary_color | Secondary actions / borders | `#292B32` | `#EBECEF` |
| base_color | Primary text color | `#292B32` | `#EBECEF` |
| base_shade1_color | Secondary text — subtitles, meta | `#636878` | `#A5A9B5` |
| base_shade2_color | Tertiary text / hints — placeholders, inactive | `#898E9E` | `#6E7487` |
| base_shade3_color | Disabled text | `#A5A9B5` | `#40434E` |
| base_shade4_color | Faint text / separators | `#EBECEF` | `#292B32` |
| base_inverse_color | Text on inverted surfaces | `#000000` | `#FFFFFF` |
| alert_color | Errors / destructive | `#FA4D30` | `#FA4D30` |
| background_color | Page and component surface | `#FFFFFF` | `#191919` |
| background_shade1_color | Secondary surface — grouped rows, wells | `#F6F7F8` | `#40434E` |

#### Brand shades

Variants of `primary_color` and `secondary_color` used for hover, pressed, disabled and emphasis states.

| Token | Default (light) | Default (dark) |
|-------|-----------------|----------------|
| primary_shade1_color | `#4A82F2` | `#4A82F2` |
| primary_shade2_color | `#A9C4F9` | `#A9C4F9` |
| primary_shade3_color | `#D9E5FC` | `#D9E5FC` |
| primary_shade4_color | `#1A4499` | `#1A4499` |
| secondary_shade1_color | `#636878` | `#A5A9B5` |
| secondary_shade2_color | `#898E9E` | `#898E9E` |
| secondary_shade3_color | `#A5A9B5` | `#40434E` |
| secondary_shade4_color | `#EBECEF` | `#292B32` |

#### Neutral greys

A light-to-dark ramp used for borders, dividers, skeletons and muted text. These are mode-independent
by default — set them per mode if your dark theme needs a different ramp.

| Token | Default | | Token | Default |
|-------|---------|-|-------|---------|
| neutral_grey_shade1_color | `#EBECEF` | | neutral_grey_shade4_color | `#636878` |
| neutral_grey_shade2_color | `#A5A9B5` | | neutral_grey_shade5_color | `#40434E` |
| neutral_grey_shade3_color | `#898E9E` | | neutral_grey_shade6_color | `#292B32` |

#### Destructive

Escalating scale for destructive actions and error states.

| Token | Default | | Token | Default |
|-------|---------|-|-------|---------|
| destructive_shade1_color | `#F38F96` | | destructive_shade4_color | `#E50B1B` |
| destructive_shade2_color | `#EE5C66` | | destructive_shade5_color | `#A30813` |
| destructive_shade3_color | `#EA3C49` | | alert_shade1_color | `#FB7159` |

#### Overlays

Semi-transparent fills for scrims, media overlays and pressed states. Values carry an alpha channel
(`#RRGGBBAA`).

| Token | Default | | Token | Default |
|-------|---------|-|-------|---------|
| transparent_black_shade1_color | `#0000004D` | | transparent_white_shade1_color | `#FFFFFF1A` |
| transparent_black_shade2_color | `#0000004D` | | transparent_white_shade2_color | `#FFFFFF1A` |
| transparent_black_shade3_color | `#00000080` | | transparent_white_shade3_color | `#FFFFFF33` |
| transparent_black_shade4_color | `#00000099` | | transparent_white_shade4_color | `#FFFFFF4D` |
| transparent_black_shade5_color | `#000000CC` | | transparent_white_shade5_color | `#FFFFFF4D` |
| transparent_red_shade1_color | `#FF305A4D` | | transparent_white_shade6_color | `#FFFFFF4D` |
| | | | transparent_white_shade7_color | `#FFFFFF4D` |

#### Fixed and feature colors

| Token | Purpose | Default (light) | Default (dark) |
|-------|---------|-----------------|----------------|
| white_color | Fixed white — surfaces that stay light in both modes | `#FFFFFF` | `#FFFFFF` |
| black_color | Fixed black — surfaces that stay dark in both modes | `#000000` | `#000000` |
| highlight_color | Search and selection highlight | `#1054DE` | `#4A82F2` |
| live_color | Live / streaming indicator | `#FF305A` | `#FF305A` |
| toast_background_color | Toast surface | `#292B32` | `#40434E` |
| event_host_bg_color | Event host badge background | `#EAE2FF` | `#EAE2FF` |
| event_host_fg_color | Event host badge text | `#4B1BD0` | `#4B1BD0` |

### Minimal Config Skeleton

```json Full theme
{
  "theme": {
    "light": {
      "primary_color": "#1054DE",
      "secondary_color": "#292B32",
      "base_color": "#292B32",
      "base_shade1_color": "#636878",
      "base_shade2_color": "#898E9E",
      "base_shade3_color": "#A5A9B5",
      "base_shade4_color": "#EBECEF",
      "base_inverse_color": "#000000",
      "alert_color": "#FA4D30",
      "background_color": "#FFFFFF",
      "background_shade1_color": "#F6F7F8",
      "primary_shade1_color": "#4A82F2",
      "primary_shade2_color": "#A9C4F9",
      "primary_shade3_color": "#D9E5FC",
      "primary_shade4_color": "#1A4499",
      "secondary_shade1_color": "#636878",
      "secondary_shade2_color": "#898E9E",
      "secondary_shade3_color": "#A5A9B5",
      "secondary_shade4_color": "#EBECEF",
      "neutral_grey_shade1_color": "#EBECEF",
      "neutral_grey_shade2_color": "#A5A9B5",
      "neutral_grey_shade3_color": "#898E9E",
      "neutral_grey_shade4_color": "#636878",
      "neutral_grey_shade5_color": "#40434E",
      "neutral_grey_shade6_color": "#292B32",
      "destructive_shade1_color": "#F38F96",
      "destructive_shade2_color": "#EE5C66",
      "destructive_shade3_color": "#EA3C49",
      "destructive_shade4_color": "#E50B1B",
      "destructive_shade5_color": "#A30813",
      "alert_shade1_color": "#FB7159",
      "transparent_black_shade1_color": "#0000004D",
      "transparent_black_shade2_color": "#0000004D",
      "transparent_black_shade3_color": "#00000080",
      "transparent_black_shade4_color": "#00000099",
      "transparent_black_shade5_color": "#000000CC",
      "transparent_red_shade1_color": "#FF305A4D",
      "transparent_white_shade1_color": "#FFFFFF1A",
      "transparent_white_shade2_color": "#FFFFFF1A",
      "transparent_white_shade3_color": "#FFFFFF33",
      "transparent_white_shade4_color": "#FFFFFF4D",
      "transparent_white_shade5_color": "#FFFFFF4D",
      "transparent_white_shade6_color": "#FFFFFF4D",
      "transparent_white_shade7_color": "#FFFFFF4D",
      "white_color": "#FFFFFF",
      "black_color": "#000000",
      "highlight_color": "#1054DE",
      "live_color": "#FF305A",
      "toast_background_color": "#292B32",
      "event_host_bg_color": "#EAE2FF",
      "event_host_fg_color": "#4B1BD0"
    },
    "dark": {
      "primary_color": "#1054DE",
      "secondary_color": "#EBECEF",
      "base_color": "#EBECEF",
      "base_shade1_color": "#A5A9B5",
      "base_shade2_color": "#6E7487",
      "base_shade3_color": "#40434E",
      "base_shade4_color": "#292B32",
      "base_inverse_color": "#FFFFFF",
      "alert_color": "#FA4D30",
      "background_color": "#191919",
      "background_shade1_color": "#40434E",
      "primary_shade1_color": "#4A82F2",
      "primary_shade2_color": "#A9C4F9",
      "primary_shade3_color": "#D9E5FC",
      "primary_shade4_color": "#1A4499",
      "secondary_shade1_color": "#A5A9B5",
      "secondary_shade2_color": "#898E9E",
      "secondary_shade3_color": "#40434E",
      "secondary_shade4_color": "#292B32",
      "neutral_grey_shade1_color": "#EBECEF",
      "neutral_grey_shade2_color": "#A5A9B5",
      "neutral_grey_shade3_color": "#898E9E",
      "neutral_grey_shade4_color": "#636878",
      "neutral_grey_shade5_color": "#40434E",
      "neutral_grey_shade6_color": "#292B32",
      "destructive_shade1_color": "#F38F96",
      "destructive_shade2_color": "#EE5C66",
      "destructive_shade3_color": "#EA3C49",
      "destructive_shade4_color": "#E50B1B",
      "destructive_shade5_color": "#A30813",
      "alert_shade1_color": "#FB7159",
      "transparent_black_shade1_color": "#0000004D",
      "transparent_black_shade2_color": "#0000004D",
      "transparent_black_shade3_color": "#00000080",
      "transparent_black_shade4_color": "#00000099",
      "transparent_black_shade5_color": "#000000CC",
      "transparent_red_shade1_color": "#FF305A4D",
      "transparent_white_shade1_color": "#FFFFFF1A",
      "transparent_white_shade2_color": "#FFFFFF1A",
      "transparent_white_shade3_color": "#FFFFFF33",
      "transparent_white_shade4_color": "#FFFFFF4D",
      "transparent_white_shade5_color": "#FFFFFF4D",
      "transparent_white_shade6_color": "#FFFFFF4D",
      "transparent_white_shade7_color": "#FFFFFF4D",
      "white_color": "#FFFFFF",
      "black_color": "#000000",
      "highlight_color": "#4A82F2",
      "live_color": "#FF305A",
      "toast_background_color": "#40434E",
      "event_host_bg_color": "#EAE2FF",
      "event_host_fg_color": "#4B1BD0"
    }
  }
}
```

```json Minimal
{
  "preferred_theme": "default",
  "theme": {
    "light": { "primary_color": "#1054DE", "background_color": "#FFFFFF" },
    "dark": { "primary_color": "#1054DE", "background_color": "#191919" }
  },
  "excludes": [],
  "customizations": {}
}
```

```json Page Override
{
  "customizations": {
    "camera_page/*/*": {
      "theme": {
        "light": { "primary_color": "#1742C0", "background_color": "#FFFFFF" },
        "dark": { "primary_color": "#508BFF", "background_color": "#101014" }
      }
    }
  }
}
```

```json Component Override
{
  "customizations": {
    "*/comment_tray_component/*": {
      "theme": {
        "light": { "primary_color": "#0D62F2" },
        "dark": { "primary_color": "#4C91FF" }
      }
    }
  }
}
```

```json Element Override
{
  "customizations": {
    "story_page/*/close_button": {
      "close_icon": "close.png",
      "background_color": "#1A1A1A80"
    }
  }
}
```

```json Exclude Example
{
  "excludes": [
    "create_story_page/*/aspect_ratio_button"
  ]
}
```

``` json Full config.json Example
{
  "preferred_theme": "default",
  "theme": {
    "light": {
      "primary_color": "#1054DE",
      "secondary_color": "#292B32",
      "base_color": "#292b32",
      "base_shade1_color": "#636878",
      "base_shade2_color": "#898e9e",
      "base_shade3_color": "#a5a9b5",
      "base_shade4_color": "#ebecef",
      "alert_color": "#FA4D30",
      "background_color": "#FFFFFF",
    },
    "dark": {
      "primary_color": "#1054DE",
      "secondary_color": "#292B32",
      "base_color": "#ebecef",
      "base_shade1_color": "#a5a9b5",
      "base_shade2_color": "#6e7487",
      "base_shade3_color": "#40434e",
      "base_shade4_color": "#292b32",
      "alert_color": "#FA4D30",
      "background_color": "#191919",
    }
  },
  "excludes": [
  ],
  "customizations": {
    "select_target_page/*/*": {
      "page_theme": {
        "light_theme": {
          "primary_color": "#1D1234",
          "secondary_color": "#AB1234"
        }
      },
      "title": "Share to"
    },
    "select_target_page/*/back_button": {
      "back_icon": "back.png"
    },
    "camera_page/*/*": {
      "resolution": "720p",
      "theme": {
        "light": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#292b32",
          "base_shade1_color": "#636878",
          "base_shade2_color": "#898e9e",
          "base_shade3_color": "#a5a9b5",
          "base_shade4_color": "#ebecef",
          "alert_color": "#FA4D30",
          "background_color": "#FFFFFF",
        },
        "dark": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#ebecef",
          "base_shade1_color": "#a5a9b5",
          "base_shade2_color": "#6e7487",
          "base_shade3_color": "#40434e",
          "base_shade4_color": "#292b32",
          "alert_color": "#FA4D30",
          "background_color": "#191919",
        }
      }
    },
    "camera_page/*/close_button": {
      "close_icon": "close.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/*": {},
    "create_story_page/*/back_button": {
      "back_icon": "back.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/aspect_ratio_button": {
      "aspect_ratio_icon": "aspect_ratio.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/story_hyperlink_button": {
      "hyperlink_button_icon": "hyperlink_button.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/hyper_link": {
      "hyper_link_icon": "hyper_link.png",
      "background_color": "#80000000"
    },
    "create_story_page/*/share_story_button": {
      "share_icon": "share_story_button.png",
      "background_color": "#FFFFFF",
      "hide_avatar": false
    },
    "story_page/*/*": {},
    "story_page/*/progress_bar": {
      "progress_color": "#FFFFFF",
      "background_color": "#50FFFFFF"
    },
    "story_page/*/overflow_menu": {
      "overflow_menu_icon": "threeDot.png"
    },
    "story_page/*/close_button": {
      "close_icon": "close.png"
    },
    "story_page/*/story_impression_button": {
      "impression_icon": "impressionIcon.png"
    },
    "story_page/*/story_comment_button": {
      "comment_icon": "comment.png",
      "background_color": "#1234DD"
    },
    "story_page/*/story_reaction_button": {
      "reaction_icon": "like.png",
      "background_color": "#1243EE"
    },
    "story_page/*/create_new_story_button": {
      "create_new_story_icon": "plus.png",
      "background_color": "#1243EE"
    },
    "story_page/*/speaker_button": {
      "mute_icon": "mute.png",
      "unmute_icon": "unmute.png",
      "background_color": "#1243EE"
    },
    "*/edit_comment_component/*": {
    },
    "*/edit_comment_component/cancel_button": {
      "cancel_icon": "",
      "cancel_button_text": "cancel",
      "background_color": "#1243EE"
    },
    "*/edit_comment_component/save_button": {
      "save_icon": "",
      "save_button_text": "Save",
      "background_color": "#1243EE"
    },
    "*/hyper_link_config_component/*": {
      "theme": {
        "light": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#292b32",
          "base_shade1_color": "#636878",
          "base_shade2_color": "#898e9e",
          "base_shade3_color": "#a5a9b5",
          "base_shade4_color": "#ebecef",
          "alert_color": "#FA4D30",
          "background_color": "#FFFFFF",
        },
        "dark": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#ebecef",
          "base_shade1_color": "#a5a9b5",
          "base_shade2_color": "#6e7487",
          "base_shade3_color": "#40434e",
          "base_shade4_color": "#292b32",
          "alert_color": "#FA4D30",
          "background_color": "#191919",
        }
      }
    },
    "*/hyper_link_config_component/done_button": {
      "done_icon": "",
      "done_button_text": "Done",
      "background_color": "#1243EE"
    },
    "*/hyper_link_config_component/cancel_button": {
      "cancel_icon": "",
      "cancel_button_text": "Cancel"
    },
    "*/comment_tray_component/*": {
      "theme": {
        "light": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#292b32",
          "base_shade1_color": "#636878",
          "base_shade2_color": "#898e9e",
          "base_shade3_color": "#a5a9b5",
          "base_shade4_color": "#ebecef",
          "alert_color": "#FA4D30",
          "background_color": "#FFFFFF",
        },
        "dark": {
          "primary_color": "#1054DE",
          "secondary_color": "#292B32",
          "base_color": "#ebecef",
          "base_shade1_color": "#a5a9b5",
          "base_shade2_color": "#6e7487",
          "base_shade3_color": "#40434e",
          "base_shade4_color": "#292b32",
          "alert_color": "#FA4D30",
          "background_color": "#191919",
        }
      }
    },
    "*/story_tab_component/*": {
    },
    "*/story_tab_component/story_ring": {
      "progress_color": [
        "#339AF9",
        "#78FA58"
      ],
      "background_color": [
        "#EBECEF"
      ]
    },
    "*/story_tab_component/create_new_story_button": {
      "create_new_story_icon": "plus.png",
      "background_color": "#1243EE"
    },
    "*/*/close_button": {
      "close_icon": "close.png"
    }
  }
}

```

## Theme Application & Preferred Mode

Set the app's theme resolution strategy with `preferred_theme`:

| Value | Behavior |
|-------|----------|
| default | Follow OS setting (light/dark) |
| light | Force light regardless of OS |
| dark | Force dark regardless of OS |

Use `default` unless you have a business requirement to lock theme (e.g., brand guidelines for launch).

## Targeting Examples

    Override a whole screen. Great for hero / camera / immersive surfaces.
```json
"select_target_page/*/*": { "title": "Share To" }
```
```json
"camera_page/*/*": {
  "theme": { "light": { "primary_color": "#1D1234" } }
}
```
    Adjust reusable functional blocks everywhere.
```json
"*/edit_comment_component/*": { "theme": { "light": { "primary_color": "#1254DE" } } }
```
```json
"*/comment_tray_component/*": { "theme": { "dark": { "background_color": "#161A20" } } }
```
    Fine-grain tweak for single control.
```json
"story_page/*/story_comment_button": {
  "comment_icon": "comment.png",
  "background_color": "#1234DD"
}
```
```json
"story_page/*/create_new_story_button": {
  "create_new_story_icon": "plus.png",
  "background_color": "#1243EE"
}
```

## Reference: Allowed IDs

```text
select_target_page/*/*
camera_page/*/*
create_story_page/*/*
story_page/*/*
```
```text
*/edit_comment_component/*
*/comment_tray_component/*
*/story_tab_component/*
*/hyper_link_config_component/*
```
```text
select_target_page/*/back_button
camera_page/*/close_button
create_story_page/*/back_button
create_story_page/*/aspect_ratio_button
create_story_page/*/story_hyperlink_button
create_story_page/*/hyper_link
create_story_page/*/share_story_button
story_page/*/progress_bar
story_page/*/overflow_menu
story_page/*/close_button
story_page/*/story_impression_button
story_page/*/story_comment_button
story_page/*/story_reaction_button
story_page/*/create_new_story_button
story_page/*/speaker_button
*/edit_comment_component/cancel_button
*/edit_comment_component/save_button
*/hyper_link_config_component/done_button
*/hyper_link_config_component/cancel_button
*/story_tab_component/story_ring
*/story_tab_component/create_new_story_button
*/*/close_button
```

## Exclusions

Remove (hide) specific elements by adding their path to `excludes`:

```json
"excludes": [
  "create_story_page/*/aspect_ratio_button"
]
```

Excluding structural elements (like a required close button) may degrade usability. Test flows after any exclusion.

## Precedence & Conflict Resolution

| Scenario | Winning Value |
|----------|---------------|
| Page vs Global | Page override |
| Component vs Page | Component override |
| Element vs Component | Element override |
| Multiple matches same level | Last in file (bottom-most) |

Group related overrides together to prevent accidental shadowing by later blocks.


## Custom Config File (iOS)

<strong>iOS only.</strong> On Android, Flutter, and React Native, the config JSON is loaded differently per platform. On iOS, use <code>setConfigFile</code> to load a local JSON file from your app bundle at initialisation time.

By default UIKit reads its bundled `config.json`. `setConfigFile` lets you supply a replacement from your own app bundle — useful for per-environment configs, white-label builds, or shipping your own defaults without modifying UIKit source.

### Implementation

```swift iOS
import AmityUIKit4

func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    // Load a custom config.json from the app bundle
    if let filePath = Bundle.main.path(forResource: "AmityUIKitConfig", ofType: "json") {
        AmityUIKit4Manager.setConfigFile(filePath)
    }
}
```

Call <code>setConfigFile</code> before presenting any UIKit view. Config values are read at render time — calling it after the first render may leave some components using the default config.

| Parameter | Type | Description |
|-----------|------|-------------|
| `filePath` | `String` | Absolute path to your `config.json` file. Use `Bundle.path(forResource:ofType:)` to resolve it safely. |

If the file path is invalid or the JSON is malformed, UIKit silently falls back to its bundled defaults. Validate your JSON locally before shipping.

## Custom Asset Bundle (iOS)

<strong>iOS only.</strong> On Android, Flutter, and React Native, image overrides are handled through the <code>config.json</code> element keys (e.g. <code>"close_icon": "close.png"</code>).

In addition to `config.json`, iOS lets you supply a custom `Bundle` containing your own images. UIKit uses it as a fallback — your assets are loaded only for image names that do **not** exist in UIKit's own bundle.

If you provide an image with the same name as a UIKit default asset, UIKit's copy wins. To replace an exposed icon, point its <code>config.json</code> key to a uniquely named file and provide that file in your custom bundle.

### How It Works

    If the image name exists in UIKit's own bundle, that version is always used.
    Only when the name is **not** found in UIKit's bundle does it fall through to your registered custom bundle.
    If the image is absent from both bundles, UIKit renders a placeholder rather than crashing.

### Implementation

    Call `setCustomAssetBundle` once during app initialisation, after `AmityUIKit4Manager.setup(client:)`.

```swift iOS
import AmityUIKit4

func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    // Register your app's main bundle as the custom asset source
    AmityUIKit4Manager.setCustomAssetBundle(bundle: .main)
}
```
    Combine bundle registration with a custom `config.json` so UIKit resolves icon keys to your asset names.

```swift iOS
func setupUIKit() {
    AmityUIKit4Manager.setup(client: AmityUIKitManager.client)

    if let filePath = Bundle.main.path(forResource: "AmityUIKitConfig", ofType: "json") {
        AmityUIKit4Manager.setConfigFile(filePath)
    }

    AmityUIKit4Manager.setCustomAssetBundle(bundle: .main)
}
```

```json config.json
{
  "customizations": {
    "story_page/*/close_button": {
      "close_icon": "my_close_icon.png"
    }
  }
}
```

    UIKit looks for <code>my_close_icon.png</code> in its own bundle first. Since that name does not exist there, it falls back to your custom bundle where the file is found.
    For modular apps where assets live in a Swift Package or framework bundle, pass that bundle instead of `Bundle.main`.

```swift Swift Package
// Bundle.module is generated automatically by SwiftPM
AmityUIKit4Manager.setCustomAssetBundle(bundle: .module)
```

```swift Framework
// Assets are inside a custom framework
let assetBundle = Bundle(for: MyAssetProvider.self)
AmityUIKit4Manager.setCustomAssetBundle(bundle: assetBundle)
```

Register the bundle before any UIKit view is presented. Images are resolved at render time — late registration may cause some views to display the wrong asset.

### Troubleshooting

    Verify the asset is included in the bundle you registered:

```swift
let url = AmityUIKit4Manager.customAssetBundle?
    .url(forResource: "my_icon", withExtension: "png")
print(url ?? "not found in custom bundle")
```

    Check that the file name, extension, and capitalisation match exactly what is referenced in `config.json`.
    An asset with the same name in UIKit's bundle always wins. Rename your asset uniquely and update the matching `config.json` icon key to point to the new name.
    Ensure the image file appears under **Copy Bundle Resources** in Build Phases. Loose PNG/PDF files (not inside an `.xcassets` catalog) must be added manually.

## Best Practices


## Overriding Navigation Behaviour

Navigation can be customized without forking by overriding the provided Behaviour classes. UIKit isolates navigation & event hooks into behaviour objects per page/component so you can inject custom flows (e.g., presenting a different creation screen, analytics, guards) while keeping styling overrides separate.

### Behaviour Architecture

- Each major screen/component exposes a `Behaviour` (iOS) / `Behavior` (Android) class with overridable navigation methods.
- A top-level `AmityUIKit4Manager.behaviour` (iOS) / `AmityUIKit4Manager.behavior` (Android) aggregates these instances.
- Replace only the concrete behaviour you need; leave others at default.

### Override Example

```swift iOS
// Custom behaviour for Story Tab component
class CustomStoryTabComponentBehaviour: AmityStoryTabComponentBehaviour {
  override init() { super.init() }

  override func goToViewStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
    // Custom navigation (e.g., analytics, gated modal, custom host)
  }

  override func goToCreateStoryPage(context: AmityStoryTabComponentBehaviour.Context) {
    // Present alternative creation UI or permission flow
  }
}

// Register once (e.g. after SDK init)
func configureNavigationOverrides() {
  AmityUIKit4Manager.behaviour.storyTabComponentBehaviour = CustomStoryTabComponentBehaviour()
}
```

```kotlin Android
// Custom behavior for Story Tab component
class CustomStoryTabComponentBehavior : AmityStoryTabComponentBehavior() {

  override fun goToViewStoryPage(
    context: Context,
    type: AmityViewStoryPageType,
  ) {
    // Launch custom activity / compose destination
  }

  override fun goToCreateStoryPage(
    context: Context,
    targetId: String,
    targetType: AmityStory.TargetType
  ) {
    // Inject permission checks or route to experimental editor
  }
}

fun configureNavigationOverrides() {
  AmityUIKit4Manager.behavior.storyTabComponentBehavior = CustomStoryTabComponentBehavior()
}
```

```dart Flutter
// Custom behavior for Message Bubble component
class CustomMessageBubbleBehavior extends AmityMessageBubbleBehavior {

  @override
  void onAvatarTap(
    BuildContext context,
    String? avatarUrl,
    String? userId,
  ) {
    // Navigate to custom user profile or inject analytics
    if (userId != null) {
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => CustomUserProfilePage(userId: userId),
        ),
      );
    }
  }
}

// Apply custom behavior in your app initialization
class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    configureNavigationOverrides();

    return AmityUIKitProvider(
      child: Builder(builder: (context) {
        return const HomePage();
      }),
    );
  }

  void configureNavigationOverrides() {
    AmityUIKit4Manager.behavior.messageBubbleBehavior =
      CustomMessageBubbleBehavior();
  }
}
```

Only override the specific methods you need; keep defaults for forward compatibility.

### Advanced iOS Navigation (Swipe Back & SwiftUI Hosting)

UIKit v4 pages are predominantly SwiftUI, embedded in `UINavigationController` via helper controllers:

| Class | Purpose |
|-------|---------|
| `AmitySwiftUIHostingController` | Wrap a single SwiftUI view |
| `AmitySwiftUIHostingNavigationController` | Provide a navigation stack hosting SwiftUI pages |

To preserve the interactive swipe‑to‑go‑back gesture while customizing appearance, UIKit globally overrides navigation gesture delegate methods. You can supply your own gesture behaviour logic via `AmitySwipeToBackGestureBehavior`.

```swift iOS
// Default usage
let defaultGestureBehavior = AmitySwipeToBackGestureBehavior()

// Custom gesture policy
class CustomSwipeBackGestureBehavior: AmitySwipeToBackGestureBehavior {
  override func gestureRecognizerShouldBegin(
    navigationController: UINavigationController,
    _ gestureRecognizer: UIGestureRecognizer
  ) -> Bool {
    // Example: disable swipe on root page or during modal overlay
    return navigationController.viewControllers.count > 1
  }

  override func gestureRecognizer(
    _ gestureRecognizer: UIGestureRecognizer,
    shouldRecognizeSimultaneouslyWith otherGestureRecognizer: UIGestureRecognizer
  ) -> Bool {
    // Allow simultaneous recognition with horizontally scrollable carousels
    return true
  }
}

func configureGestureBehavior() {
  AmityUIKit4Manager.behaviour.swipeToBackGestureBehavior = CustomSwipeBackGestureBehavior()
}
```

Keep gesture logic lightweight—long operations here can block UI responsiveness.

### When to Escalate

If navigation changes require altering internal view composition (e.g., embedding a new container architecture), consider moving to <a href="/uikit/customization/advanced-customization">Fork & Extend</a>. Simple route substitutions, analytics, permission gates, and gesture tweaks belong here.

## Next Steps

---

### [Fork & Extend](https://learn.social.plus/uikit/customization/advanced-customization)

> Level 3: Advanced customization with complete source code control

For teams who need **complete control** over UIKit components and user flows. Fork & Extend gives you access to the full source code, allowing unlimited customization freedom.

    Complete control over all components
    Build entirely new user flows
    Maintain your own version and roadmap
    Full development environment setup


Pick Fork & Extend only after validating that <a href="/uikit/customization/dynamic-ui">Dynamic UI</a> and <a href="/uikit/customization/component-styling">Component Styling</a> cannot achieve your goals with acceptable complexity.

## When to Choose Fork & Extend

Fork & Extend is ideal when you need:

✅ **Complete customization freedom** – Modify any rendering or data flow
✅ **Custom user flows** – Create navigation patterns not exposed by standard pages
✅ **Deep integration** – Embed UIKit pieces inside a complex existing architecture
✅ **Performance tuning** – Rework virtualization, batching, caching layers
✅ **Extensible domain logic** – Inject proprietary moderation, ranking, analytics
✅ **Long-term ownership** – Maintain an internal roadmap independent of upstream release cadence

❌ **Simple branding only** – Use Dynamic UI (faster, zero maintenance)
❌ **Just per-component styling** – Use Component Styling (lower effort)
❌ **Limited engineering capacity** – Forks require continual rebasing
❌ **Short-lived experiment** – Prefer a lighter extension path first

If you expect to contribute improvements back later, maintain a **light fork** (few direct core edits) and use extension points / adapters where possible.

## Repository Directory

| Platform | Repository | Language / Stack | Package / Tooling | Notes |
|----------|------------|------------------|-------------------|-------|
| iOS | https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource | Swift | SwiftPM | SwiftUI wrappers & UIKit interop |
| Android | https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Android | Kotlin (Compose) | Gradle (KTS) | Jetpack Compose components |
| Web (React) | https://github.com/AmityCo/Amity-Social-Cloud-UIKit-Web-OpenSource | TypeScript / React | pnpm / npm / Vite (variant) | Modular import points |
| React Native | https://github.com/AmityCo/Amity-Social-UIKit-React-Native-CLI-OpenSource | TypeScript / RN | Yarn / Metro | Native bridges in subpackages |
| Flutter | https://github.com/AmityCo/Amity-Social-UIKit-Flutter-Opensource | Dart / Flutter | pub | Composable widgets |

## Forking Strategies

    Keep upstream directory structure; override via extension hooks, subclassing, dependency injection. Avoid editing core logic; instead patch behavior through public APIs.
    Copy only needed modules (e.g. feed + reactions) into your mono‑repo, leaving update path harder but reducing dependency surface.
    Broad internal rewrites; highest divergence risk; only for teams prepared to maintain a private long‑term branch & merge engine changes manually.

## Recommended Workflow


## Git Operations (Examples)

```bash Add upstream
git remote add upstream https://github.com/AmityCo/ASC-UIKit-iOS-OpenSource.git
git fetch upstream
```
```bash Rebase with upstream main
git checkout main
git fetch upstream
git rebase upstream/main
```
```bash Feature branch
git checkout -b feat/custom-channel-flow
```
```bash Tag internal release
git tag -a v4.2.1-fork.1 -m "Add custom channel retention policy"
git push origin v4.2.1-fork.1
```

## Extension Points & Patterns

| Pattern | Use Case | Example |
|---------|----------|---------|
| Subclass / Inherit | Override rendering | Custom PostCell layout |
| Composition Wrapper | Inject analytics / guards | Wrap FeedList with tracking HOC / decorator |
| Dependency Injection | Swap services (auth, storage) | Provide custom AuthProvider |
| Behavior Strategy Object | Change navigation / flows | Custom CommentTrayBehavior |
| Theming Adapter | Align design tokens | Map internal design system → UIKit tokens |

Prefer adding a new extension seam over editing multiple call sites—easier to rebase.

## Upgrade Strategy


## Risk & Mitigation

| Risk | Impact | Mitigation |
|------|--------|------------|
| Divergence from upstream | Hard upgrades | Rebase weekly; avoid large refactors in core files |
| Hidden security fix missed | Exposure | Subscribe to repo releases; implement dependabot/security scanning |
| Unbounded scope creep | Maintenance drag | Define exit criteria for each forked change |
| Performance regression | User experience | Profile before/after; keep benchmarks |

## Performance Tuning Targets


## Security & Compliance


## Anti-Patterns


## Contribution Opportunity

If a customization becomes broadly useful (e.g., accessibility improvement), consider opening an upstream PR instead of maintaining a private delta long-term.

## Checklist Before Forking

- Confirmed lower customization levels insufficient
- Identified scope & success metrics
- Allocated maintenance owner
- Established rebase cadence (e.g. weekly)
- Added contract tests

## Repository Links


## Next Steps


Reassess periodically whether parts of your fork can collapse back to vanilla via newly added upstream extension points.

## UIKit — Platform Guides

### [iOS Platform Guide](https://learn.social.plus/uikit/platform-guides/ios-specific)

> Advanced iOS-specific features, optimizations, and best practices for social.plus UIKit

# iOS Platform Guide

This guide covers iOS-specific features, optimizations, and advanced configurations for social.plus UIKit. For basic installation, see our [Installation Guide](/uikit/getting-started/installation#ios).

**Prerequisites**: iOS 12.0+, Xcode 12+, Swift 5.0+. Ensure you've completed the basic installation before following these advanced guides.

## Advanced Installation Options

### 🔧 **Custom Build Configurations**

Configure UIKit for different build environments:

```swift
// AppDelegate.swift - Debug setup
#if DEBUG
AmityUIKitManager.setup(
    apiKey: "YOUR_DEBUG_API_KEY",
    region: .US,
    httpSettings: AmityHTTPSettings(
        enableLogging: true,
        logLevel: .verbose
    )
)
#endif
```

```swift
// AppDelegate.swift - Production setup
#if !DEBUG
AmityUIKitManager.setup(
    apiKey: "YOUR_PRODUCTION_API_KEY",
    region: .US,
    httpSettings: AmityHTTPSettings(
        enableLogging: false,
        logLevel: .error
    )
)
#endif
```

```swift
// AppDelegate.swift - Staging setup
#if STAGING
AmityUIKitManager.setup(
    apiKey: "YOUR_STAGING_API_KEY",
    region: .EU,
    httpSettings: AmityHTTPSettings(
        enableLogging: true,
        logLevel: .info
    )
)
#endif
```

### 🎯 **Performance Optimizations**

#### Memory Management
```swift
// Implement proper memory management
class ChatViewController: UIViewController {
    private var amityViewController: AmityChatViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupAmityChat()
    }

    private func setupAmityChat() {
        amityViewController = AmityChatViewController()
        addChild(amityViewController!)
        view.addSubview(amityViewController!.view)
        amityViewController!.didMove(toParent: self)
    }

    deinit {
        // Clean up resources
        amityViewController?.willMove(toParent: nil)
        amityViewController?.view.removeFromSuperview()
        amityViewController?.removeFromParent()
    }
}
```

#### Image Caching Configuration
```swift
// Configure image caching for better performance
AmityUIKitManager.configure { settings in
    settings.imageCacheSettings = AmityImageCacheSettings(
        memoryLimit: 50 * 1024 * 1024, // 50MB
        diskLimit: 200 * 1024 * 1024,   // 200MB
        diskAge: 60 * 60 * 24 * 7       // 1 week
    )
}
```

---

## iOS-Specific Features

### 📱 **Native iOS Integrations**

#### Push Notifications
```swift
import UserNotifications

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Setup UIKit
        AmityUIKitManager.setup(apiKey: "YOUR_API_KEY", region: .US)

        // Configure push notifications
        UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { granted, error in
            if granted {
                DispatchQueue.main.async {
                    application.registerForRemoteNotifications()
                }
            }
        }

        return true
    }

    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Register device token with Amity
        AmityUIKitManager.registerDeviceToken(deviceToken)
    }
}
```

#### Background App Refresh
```swift
// Configure background refresh for real-time updates
func applicationDidEnterBackground(_ application: UIApplication) {
    AmityUIKitManager.enterBackground()
}

func applicationWillEnterForeground(_ application: UIApplication) {
    AmityUIKitManager.enterForeground()
}
```

#### Scene Delegate Support
```swift
// SceneDelegate.swift - iOS 13+ multi-window support
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }

        window = UIWindow(windowScene: windowScene)

        // Setup UIKit for this scene
        let mainViewController = MainViewController()
        window?.rootViewController = UINavigationController(rootViewController: mainViewController)
        window?.makeKeyAndVisible()
    }
}
```

### 🎨 **iOS Design System Integration**

#### Dynamic Type Support
```swift
// Configure UIKit to support Dynamic Type
AmityUIKitManager.configure { settings in
    settings.accessibilitySettings = AmityAccessibilitySettings(
        supportDynamicType: true,
        minimumFontSize: 12.0,
        maximumFontSize: 24.0
    )
}
```

#### Dark Mode Support
```swift
// Automatic dark mode detection
override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
    super.traitCollectionDidChange(previousTraitCollection)

    if traitCollection.hasDifferentColorAppearance(comparedTo: previousTraitCollection) {
        // Update UIKit theme based on system appearance
        let isDarkMode = traitCollection.userInterfaceStyle == .dark
        AmityUIKitManager.setTheme(isDarkMode ? .dark : .light)
    }
}
```

#### Safe Area Handling
```swift
// Proper safe area integration
class ContainerViewController: UIViewController {
    private let amityViewController = AmityFeedViewController()

    override func viewDidLoad() {
        super.viewDidLoad()

        addChild(amityViewController)
        view.addSubview(amityViewController.view)

        amityViewController.view.translatesAutoresizingMaskIntoConstraints = false
        NSLayoutConstraint.activate([
            amityViewController.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
            amityViewController.view.leadingAnchor.constraint(equalTo: view.leadingAnchor),
            amityViewController.view.trailingAnchor.constraint(equalTo: view.trailingAnchor),
            amityViewController.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
        ])

        amityViewController.didMove(toParent: self)
    }
}
```

---

## Advanced Customization

### 🎭 **Custom Theming**

#### Brand Color Integration
```swift
// Custom color scheme
let customTheme = AmityTheme()
customTheme.primaryColor = UIColor(red: 0.2, green: 0.4, blue: 0.8, alpha: 1.0)
customTheme.secondaryColor = UIColor(red: 0.1, green: 0.2, blue: 0.4, alpha: 1.0)
customTheme.backgroundColor = UIColor.systemBackground
customTheme.textColor = UIColor.label

AmityUIKitManager.setCustomTheme(customTheme)
```

#### Typography Customization
```swift
// Custom fonts
let customTypography = AmityTypography()
customTypography.headingFont = UIFont(name: "YourCustomFont-Bold", size: 18) ?? UIFont.systemFont(ofSize: 18, weight: .bold)
customTypography.bodyFont = UIFont(name: "YourCustomFont-Regular", size: 16) ?? UIFont.systemFont(ofSize: 16)
customTypography.captionFont = UIFont(name: "YourCustomFont-Light", size: 14) ?? UIFont.systemFont(ofSize: 14, weight: .light)

AmityUIKitManager.setCustomTypography(customTypography)
```

### 🔧 **Component Customization**

#### Custom Navigation Bar
```swift
class CustomFeedViewController: AmityFeedViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        // Customize navigation bar
        navigationItem.title = "My Social Feed"
        navigationController?.navigationBar.prefersLargeTitles = true

        // Add custom buttons
        let profileButton = UIBarButtonItem(
            image: UIImage(systemName: "person.circle"),
            style: .plain,
            target: self,
            action: #selector(showProfile)
        )
        navigationItem.rightBarButtonItem = profileButton
    }

    @objc private func showProfile() {
        let profileVC = AmityUserProfileViewController()
        present(profileVC, animated: true)
    }
}
```

#### Custom Cell Layouts
```swift
// Register custom cell classes
class CustomizedFeedViewController: AmityFeedViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        // Register custom post cell
        registerCustomPostCell(CustomPostTableViewCell.self, forCellType: .text)
        registerCustomPostCell(CustomImagePostTableViewCell.self, forCellType: .image)
    }
}

class CustomPostTableViewCell: AmityPostTableViewCell {
    override func setupCustomLayout() {
        super.setupCustomLayout()

        // Add custom UI elements
        contentView.backgroundColor = UIColor.systemGray6
        contentView.layer.cornerRadius = 12
        contentView.layer.masksToBounds = true
    }
}
```

---

## Debugging & Troubleshooting

### 🐛 **Common iOS Issues**

    **Issue**: Build fails with dependency conflicts

    **Solutions**:
    1. Clean build folder: `Cmd + Shift + K`
    2. Delete derived data: `~/Library/Developer/Xcode/DerivedData`
    3. Reset package cache: Xcode → File → Packages → Reset Package Caches
    4. Verify deployment target matches UIKit requirements (iOS 12.0+)

```bash
# Terminal command to clean derived data
rm -rf ~/Library/Developer/Xcode/DerivedData
```

    **Issue**: App crashes when loading UIKit components

    **Solutions**:
    1. Verify API key is valid and properly set
    2. Check network connectivity
    3. Enable debug logging to see detailed error messages
    4. Ensure proper memory management

```swift
// Enable detailed logging
AmityUIKitManager.setLogLevel(.verbose)
```

    **Issue**: Components don't display correctly

    **Solutions**:
    1. Check auto-layout constraints
    2. Verify safe area handling
    3. Test on different device sizes
    4. Check for custom theme conflicts

```swift
// Debug view hierarchy
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    view.debugSubviews() // Custom debug method
}
```

### 📊 **Performance Monitoring**

```swift
// Monitor UIKit performance
class PerformanceMonitor {
    static func trackComponentLoad(componentName: String) {
        let startTime = CFAbsoluteTimeGetCurrent()

        // Component loading logic

        let timeElapsed = CFAbsoluteTimeGetCurrent() - startTime
        print("Component \(componentName) loaded in \(timeElapsed) seconds")
    }
}

// Usage
PerformanceMonitor.trackComponentLoad(componentName: "AmityFeedViewController")
```

---

## Production Deployment

### 🚀 **App Store Preparation**

#### Info.plist Configuration
```xml
<!-- Required permissions -->
<key>NSCameraUsageDescription</key>
<string>This app uses camera to capture photos for posts and profile pictures</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>This app accesses photo library to select images for posts</string>

<key>NSMicrophoneUsageDescription</key>
<string>This app uses microphone for voice messages and video calls</string>
```

#### Build Configuration
```swift
// Production-ready configuration
#if !DEBUG
AmityUIKitManager.setup(
    apiKey: "PRODUCTION_API_KEY",
    region: .US,
    httpSettings: AmityHTTPSettings(
        enableLogging: false,
        logLevel: .error,
        enableCrashReporting: true
    )
)
#endif
```

### 📈 **Analytics Integration**

```swift
// Custom analytics tracking
extension AmityUIKitManager {
    static func trackUserAction(_ action: String, parameters: [String: Any] = [:]) {
        // Your analytics service integration
        Analytics.track(action, properties: parameters)
    }
}

// Usage in custom view controllers
class AnalyticsEnabledFeedViewController: AmityFeedViewController {
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        AmityUIKitManager.trackUserAction("feed_viewed")
    }
}
```

---

## Resources & Best Practices

### 📚 **Recommended Architecture**

```swift
// MVVM pattern with UIKit
class FeedViewModel: ObservableObject {
    @Published var posts: [AmityPost] = []
    private let amityDataSource = AmityFeedDataSource()

    func loadPosts() {
        amityDataSource.loadPosts { [weak self] posts in
            DispatchQueue.main.async {
                self?.posts = posts
            }
        }
    }
}

class FeedViewController: UIViewController {
    private let viewModel = FeedViewModel()
    private let amityFeedView = AmityFeedView()

    override func viewDidLoad() {
        super.viewDidLoad()
        setupBindings()
        viewModel.loadPosts()
    }

    private func setupBindings() {
        viewModel.$posts.sink { [weak self] posts in
            self?.amityFeedView.updatePosts(posts)
        }.store(in: &cancellables)
    }
}
```

### 🔗 **Additional Resources**

    Complete iOS sample application with best practices
    Detailed component documentation for iOS
        End-to-end guide to theming & customizing UIKit
        Learn how to apply brand colors & typography

**Need Help?** Join our [iOS developers community](https://community.socialplus.com/ios) for platform-specific discussions and support.

## Use Cases — Overview

### [Guides](https://learn.social.plus/use-cases/overview)

> End-to-end implementation guides — each one walks through a complete feature from SDK wiring to admin tooling.

Each guide answers one question: _"How do I wire up feature X end-to-end?"_ — from SDK code to Admin Console configuration to webhook automation. The guides follow the product journey: **build your community → engage & grow → monetize**.

  <img
    src="/images/use-cases/landing-guides.png"
    alt="Why social.plus — fully white-label, fast to launch with modular APIs, developer-friendly SDKs for TypeScript, Swift, Kotlin, Flutter, in-app engagement, and privacy-first with zero-party data"
  />

  Not sure where to start? Pick your app type (social, community, gaming, marketplace, livestream, DMs, group chat, live chat) and get a recommended build order.

All guides assume SDK installed + authenticated session. → [SDK Getting Started](/social-plus-sdk/getting-started/overview)

---

## How Every Guide Works

    Collapsible code-only version — copy-paste the whole feature in one go.
    Mermaid diagram showing the data flow and entity relationships.
    Each step links directly to the SDK reference page with full multi-platform code.
    Wire up moderation, analytics, webhooks, and reporting in the console.
    Performance, UX, common pitfalls, and what to build next.

---

## Concepts

    The primary content unit. Types: `text`, `image`, `video`, `poll`, `clip`, `livestream`. Always targets a **community** or a **user feed**.
    A group space with members, roles (member / moderator), and its own feed. Can be `public` or `private`.
    A queryable collection of posts for a target. Review states: `published`, `reviewing`, `declined`.
    The container for chat. Types: **Community** (public/discoverable), **Live** (broadcast), **Conversation** (private 1:1 or small group).
    A reply on a post or story. Two levels of threading: top-level comments and nested replies.
    A named response on any content object. Freeform strings you define (e.g. `"like"`, `"love"`). No fixed SDK enum.
    Ephemeral content (image/video) visible for 24 hours. Per-story view counts and impression analytics.
    A user-to-user relationship: `pending`, `accepted`, or `blocked`. Drives the home feed and social graph.
    The container for a video session. Statuses: `idle`, `live`, `recorded`, `ended`. A live-type **Channel** can attach to a Room via `attachedTo.roomId` for live chat alongside the stream.

Full field-level reference → [Social Data Model](/api-reference/social-data-model) · [Chat Data Model](/api-reference/chat-data-model)

---

## Build Your Community

Set up users, profiles, communities, and the feeds that tie them together.

| Guide | Level |
|---|---|
| [User Onboarding & Visitor Mode](/use-cases/social/user-onboarding-and-visitor-mode) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Community Platform](/use-cases/social/community-platform) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Roles, Permissions & Governance](/use-cases/social/roles-permissions-and-governance) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Build a Social Feed](/use-cases/social/build-a-social-feed) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |

## Create & Share Content

Posts, comments, polls, stories, and video — the content layer on top of communities.

| Guide | Level |
|---|---|
| [Rich Content Creation](/use-cases/social/rich-content-creation) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Comments & Reactions](/use-cases/social/comments-and-reactions) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Polls & Interactive Content](/use-cases/social/polls-and-interactive-content) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Stories & Ephemeral Content](/use-cases/social/stories-and-ephemeral-content) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Short-Form Video Clips](/use-cases/social/short-form-video-clips) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |

## Communication

Channels, messaging, rich media, roles, and chat moderation.

| Guide | Level |
|---|---|
| [Channels & Conversations](/use-cases/chat/channels-and-conversations) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Sending Messages](/use-cases/chat/sending-messages) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Reactions & Threaded Replies](/use-cases/chat/message-reactions-and-replies) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Unread Counts & Read Receipts](/use-cases/chat/unread-counts-and-read-receipts) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Rich Media Messages](/use-cases/chat/rich-media-messages) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Channel Roles & Permissions](/use-cases/chat/channel-roles-and-permissions) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Chat Moderation](/use-cases/chat/chat-moderation) | <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span> |

## Engage & Grow

Notifications, presence, search, sharing, analytics, events, and moderation — everything that drives retention and growth.

| Guide | Level |
|---|---|
| [Notifications & Engagement](/use-cases/social/notifications-and-engagement) | <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span> |
| [Real-time Presence & Activity](/use-cases/social/realtime-presence-and-activity) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Search & Discovery](/use-cases/social/search-and-discovery) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [User Search & People Discovery](/use-cases/social/user-search-and-people-discovery) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Content Sharing & Deep Links](/use-cases/social/content-sharing-and-deep-links) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Post Impressions & Creator Analytics](/use-cases/social/post-impressions-and-creator-analytics) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |
| [Events & Activities](/use-cases/social/events-and-activities) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline) | <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span> |
| [User Profile Moderation](/use-cases/social/user-profile-moderation) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |

## Livestream

Go live with co-hosting, product tagging, and real-time chat.

| Guide | Level |
|---|---|
| [Livestream Overview](/use-cases/social/livestream/overview) | — |
| [Go Live & Room Management](/use-cases/social/livestream/go-live-and-room-management) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Co-Hosting](/use-cases/social/livestream/co-hosting) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Live Chat & Engagement](/use-cases/social/livestream/live-chat-and-engagement) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Product Tagging (Livestream)](/use-cases/social/livestream/product-tagging) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |

## Monetize

Turn engagement into revenue with product tagging and native ads.

| Guide | Level |
|---|---|
| [Product Tagging & Social Commerce](/use-cases/social/product-tagging-and-social-commerce) | <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span> |
| [Advertising & Monetization](/use-cases/social/advertising-and-monetization) | <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span> |

---

### [Choose Your Path](https://learn.social.plus/use-cases/choose-your-path)

> Recommended guide sequences for 8 app types — pick your closest match and follow the build order.

Not sure where to start? Pick the app type closest to what you're building. Each path is an ordered sequence of guides — follow them in order for the smoothest build, or jump to any step directly.

    Instagram, BeReal, Strava
    Reddit, Discord, Facebook Groups
    Clans, streams, presence
    Depop, Etsy, social commerce
    Twitch, YouTube Live
    Dating, support, DMs
    Discord, Slack, team rooms
    Twitch chat, events, Q&A

---

## Social

> **Instagram, BeReal, Strava** — content sharing with profiles, stories, and a social graph.

```mermaid
graph LR
    subgraph Build
        A["Onboarding"] --> B["Feed"]
        B --> C["Content"]
        C --> D["Comments"]
        D --> E["Stories"]
        E --> F["Profiles"]
    end
    subgraph Engage & Grow
        G["Notifications"] --> H["Moderation"]
        H --> I["1:1 Chat"]
    end
    subgraph Monetize
        J["Product Tags"] --> K["Ads"]
    end
    F --> G
    I --> J

    style A fill:#e1f5fe,stroke:#0288d1
    style E fill:#fff3e0,stroke:#f57c00
    style J fill:#fff3e0,stroke:#f57c00
    style K fill:#e8f5e9,stroke:#388e3c
```

### Build

Core platform — users, content, and social graph.

    Let users explore content before signing up, then transition to authenticated sessions with profile setup.

    → [Open guide](/use-cases/social/user-onboarding-and-visitor-mode) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    The core loop — home timeline, community feeds, and a global discovery feed with real-time updates.

    → [Open guide](/use-cases/social/build-a-social-feed) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Text, image, video, and poll posts with @mentions, hashtags, and media uploads.

    → [Open guide](/use-cases/social/rich-content-creation) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Threaded comments and emoji reactions on posts — the engagement layer.

    → [Open guide](/use-cases/social/comments-and-reactions) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    24-hour stories with story rings, view counts, and impression analytics.

    → [Open guide](/use-cases/social/stories-and-ephemeral-content) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Follow/unfollow, connection requests, profile pages, and follower lists.

    → [Open guide](/use-cases/social/user-profiles-and-social-graph) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

### Engage & Grow

Retention, safety, and private messaging.

    In-app notification tray and push notifications to drive retention.

    → [Open guide](/use-cases/social/notifications-and-engagement) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>
    User flagging → admin review → AI moderation → webhook automation.

    → [Open guide](/use-cases/social/content-moderation-pipeline) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>
    Private direct messaging between users.

    → [See Direct Messages path](#direct-messages) · <span style={{color:"#2563eb",background:"#dbeafe",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>All levels</span>

### Monetize

Turn engagement into revenue.

    Turn posts into shoppable content — tag products from your catalogue so followers can browse and buy.

    → [Open guide](/use-cases/social/product-tagging-and-social-commerce) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Native ads in feeds — console-driven placement, frequency, and impression tracking.

    → [Open guide](/use-cases/social/advertising-and-monetization) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

---

## Community

> **Reddit, Discord, Facebook Groups** — discussions, moderation, and discovery.

```mermaid
graph LR
    subgraph Build
        A["Communities"] --> B["Roles"]
        B --> C["Content"]
        C --> D["Comments"]
    end
    subgraph Engage & Grow
        E["Search"] --> F["Moderation"]
        F --> G["Group Chat"]
    end
    subgraph Monetize
        H["Product Tags"] --> I["Ads"]
    end
    D --> E
    G --> H

    style A fill:#f3e5f5,stroke:#7b1fa2
    style D fill:#fce4ec,stroke:#c62828
    style H fill:#fff3e0,stroke:#f57c00
    style I fill:#e8f5e9,stroke:#388e3c
```

### Build

Community spaces, governance, and content.

    Create public and private communities with categories, membership, and governance settings.

    → [Open guide](/use-cases/social/community-platform) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Moderator roles, post review queues, and ban management.

    → [Open guide](/use-cases/social/roles-permissions-and-governance) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Posts and polls inside community feeds.

    → [Open guide](/use-cases/social/rich-content-creation) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Threaded discussions and emoji reactions.

    → [Open guide](/use-cases/social/comments-and-reactions) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

### Engage & Grow

Discovery, safety, and communication.

    Find communities, trending topics, and category browsing.

    → [Open guide](/use-cases/social/search-and-discovery) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Rules enforcement — flagging, AI screening, webhook automation.

    → [Open guide](/use-cases/social/content-moderation-pipeline) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>
    Persistent chat rooms for community members.

    → [See Group Chat path](#group-chat) · <span style={{color:"#2563eb",background:"#dbeafe",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>All levels</span>

### Monetize

Turn community activity into revenue.

    Let members tag products in community posts — marketplace boards, group buys, and curated recommendations.

    → [Open guide](/use-cases/social/product-tagging-and-social-commerce) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Sponsored posts and native ads in community feeds.

    → [Open guide](/use-cases/social/advertising-and-monetization) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

---

## Gaming

> **Discord, Twitch** — clans, livestreams, and real-time presence.

```mermaid
graph LR
    subgraph Build
        A["Clans"] --> B["Roles"]
        B --> C["Livestream"]
    end
    subgraph Engage & Grow
        D["Presence"] --> E["Group Chat"]
        E --> F["Notifications"]
    end
    subgraph Monetize
        G["Product Tags"] --> H["Ads"]
    end
    C --> D
    F --> G

    style A fill:#f3e5f5,stroke:#7b1fa2
    style C fill:#ede7f6,stroke:#4527a0
    style E fill:#e0f2f1,stroke:#00695c
    style G fill:#fff3e0,stroke:#f57c00
    style H fill:#e8f5e9,stroke:#388e3c
```

### Build

Clans, governance, and streaming.

    Clan and team spaces with membership and privacy settings.

    → [Open guide](/use-cases/social/livestream/go-live-and-room-management) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>
    Clan leadership roles, mod tools, and member management.

    → [Open guide](/use-cases/social/roles-permissions-and-governance) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    In-game streams, co-hosting, VOD playback, and live chat.

    → [Open guide](/use-cases/social/livestream-and-video-posts) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

### Engage & Grow

Presence, chat, and push alerts.

    "Online now" indicators and channel presence tracking.

    → [Open guide](/use-cases/social/realtime-presence-and-activity) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Text channels for clans and teams.

    → [See Group Chat path](#group-chat) · <span style={{color:"#2563eb",background:"#dbeafe",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>All levels</span>
    Match alerts, tournament updates, and push notifications.

    → [Open guide](/use-cases/social/notifications-and-engagement) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

### Monetize

Merch, sponsorships, and partner revenue.

    Tag merch, in-game items, and partner products in clan posts and stream content.

    → [Open guide](/use-cases/social/product-tagging-and-social-commerce) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    In-feed ads for tournament sponsorships and partner promotions.

    → [Open guide](/use-cases/social/advertising-and-monetization) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

---

## Marketplace

> **Depop, Etsy** — social commerce with buyer-seller messaging and shoppable content.

```mermaid
graph LR
    subgraph Build
        A["Onboarding"] --> B["User Search"]
        B --> C["Deep Links"]
        C --> D["Product Tagging"]
    end
    subgraph Engage & Grow
        E["1:1 Chat"] --> F["Moderation"]
    end
    subgraph Monetize
        G["Ads"]
    end
    D --> E
    F --> G

    style A fill:#e1f5fe,stroke:#0288d1
    style D fill:#fff3e0,stroke:#f57c00
    style G fill:#e8f5e9,stroke:#388e3c
```

### Build

Storefront, discovery, and shoppable content.

    Let browsers explore listings before signing up.

    → [Open guide](/use-cases/social/user-onboarding-and-visitor-mode) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Find sellers, creators, and shops.

    → [Open guide](/use-cases/social/user-search-and-people-discovery) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Shareable product pages and deep-link routing.

    → [Open guide](/use-cases/social/content-sharing-and-deep-links) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Turn posts and livestreams into shoppable storefronts with product tagging, catalogues, and engagement analytics.

    → [Open guide](/use-cases/social/product-tagging-and-social-commerce) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>

### Engage & Grow

Buyer-seller communication and trust & safety.

    Buyer-seller messaging with read receipts.

    → [See Direct Messages path](#direct-messages) · <span style={{color:"#2563eb",background:"#dbeafe",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>All levels</span>
    Keep listings safe — flagging, AI screening, and admin review.

    → [Open guide](/use-cases/social/content-moderation-pipeline) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

### Monetize

Promoted listings and native ads.

    Native ads in feeds with console-driven config and impression tracking.

    → [Open guide](/use-cases/social/advertising-and-monetization) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

---

## Livestream

> **Twitch, YouTube Live** — broadcast with interactive chat, streamer profiles, and shoppable streams.

```mermaid
graph LR
    subgraph Build
        A["Livestream"] --> B["Communities"]
    end
    subgraph Engage & Grow
        C["Live Chat"] --> D["Profiles"]
        D --> E["Notifications"]
    end
    subgraph Monetize
        F["Product Tags"] --> G["Ads"]
    end
    B --> C
    E --> F

    style A fill:#ede7f6,stroke:#4527a0
    style C fill:#e0f2f1,stroke:#00695c
    style F fill:#fff3e0,stroke:#f57c00
    style G fill:#e8f5e9,stroke:#388e3c
```

### Build

Broadcasting and community spaces.

    Broadcast rooms, co-hosting, live chat overlay, and recorded playback.

    → [Open guide](/use-cases/social/livestream/go-live-and-room-management) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>
    Stream communities where followers gather and discover content.

    → [Open guide](/use-cases/social/community-platform) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>

### Engage & Grow

Chat, audience building, and notifications.

    Real-time stream chat with high-volume message handling.

    → [See Live Chat path](#live-chat) · <span style={{color:"#2563eb",background:"#dbeafe",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>All levels</span>
    Follow streamers, view streamer profiles, and build an audience.

    → [Open guide](/use-cases/social/user-profiles-and-social-graph) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    "X just went live" push alerts and activity notifications.

    → [Open guide](/use-cases/social/notifications-and-engagement) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

### Monetize

Shoppable streams and ad revenue.

    Pin products during a stream, let viewers browse and buy — turn broadcasts into revenue.

    → [Open guide](/use-cases/social/product-tagging-and-social-commerce) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Native ads alongside streams and in the VOD feed.

    → [Open guide](/use-cases/social/advertising-and-monetization) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>

---

## Direct Messages

> **Dating apps, customer support, marketplace DMs** — private 1:1 messaging with read receipts and rich media.

```mermaid
graph LR
    A["Conversation"] --> B["Messaging"]
    B --> C["Read Receipts"]
    C --> D["Rich Media"]

    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#e8f5e9,stroke:#388e3c
    style C fill:#fff3e0,stroke:#f57c00
    style D fill:#fce4ec,stroke:#c62828
```

    Create a private Conversation channel between two users and display a chat list.

    → [Open guide](/use-cases/chat/channels-and-conversations) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Build the message thread — send, receive, and load history.

    → [Open guide](/use-cases/chat/sending-messages) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Show the sender when their message was delivered and read.

    → [Open guide](/use-cases/chat/unread-counts-and-read-receipts) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Photos, voice notes, files, and custom content types.

    → [Open guide](/use-cases/chat/rich-media-messages) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>

---

## Group Chat

> **Discord, Slack, team rooms** — persistent channels with roles, media, threaded replies, and moderation.

```mermaid
graph LR
    A["Channels"] --> B["Roles"]
    B --> C["Messaging"]
    C --> D["Threads"]
    D --> E["Moderation"]

    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#e8f5e9,stroke:#388e3c
    style C fill:#fff3e0,stroke:#f57c00
    style D fill:#fce4ec,stroke:#c62828
    style E fill:#f3e5f5,stroke:#7b1fa2
```

    Create a Community channel, invite members, and display a real-time channel list.

    → [Open guide](/use-cases/chat/channels-and-conversations) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Establish who can do what before the first message is sent.

    → [Open guide](/use-cases/chat/channel-roles-and-permissions) · <span style={{color:"#d97706",background:"#fef3c7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Intermediate</span>
    Text, images, audio, files, and custom message types.

    → [Open guide](/use-cases/chat/sending-messages) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Threaded replies and emoji reactions to keep the main chat clean.

    → [Open guide](/use-cases/chat/message-reactions-and-replies) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Muting, banning, AI content screening, and webhook automation.

    → [Open guide](/use-cases/chat/chat-moderation) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

---

## Live Chat

> **Twitch chat, sports events, live Q&A** — high-volume, many-to-many commentary alongside live content.

```mermaid
graph LR
    A["Live Channel"] --> B["Real-time Chat"]
    B --> C["Reactions"]
    C --> D["Moderation"]

    style A fill:#e1f5fe,stroke:#0288d1
    style B fill:#e8f5e9,stroke:#388e3c
    style C fill:#fff3e0,stroke:#f57c00
    style D fill:#fce4ec,stroke:#c62828
```

    Create a Live-type channel that persists across broadcast sessions.

    → [Open guide](/use-cases/chat/channels-and-conversations) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Real-time message sending and querying with automatic rate limiting.

    → [Open guide](/use-cases/chat/sending-messages) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Emoji reactions without flooding the chat with text messages.

    → [Open guide](/use-cases/chat/message-reactions-and-replies) · <span style={{color:"#16a34a",background:"#dcfce7",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Beginner</span>
    Automated and manual tools for high-volume chat — mute, ban, AI screening.

    → [Open guide](/use-cases/chat/chat-moderation) · <span style={{color:"#dc2626",background:"#fee2e2",padding:"2px 8px",borderRadius:"12px",fontSize:"0.85em",fontWeight:"500"}}>Advanced</span>

## Use Cases — Chat

### [Channels & Conversations](https://learn.social.plus/use-cases/chat/channels-and-conversations)

> Create and manage Community, Live, and Conversation channels — the building blocks of every chat experience.

```typescript
// Create a Community channel
const channel = await ChannelRepository.createChannel({
  type: 'community',
  displayName: 'General',
  isPublic: true,
  tags: ['team', 'general'],
});

// Query channels the current user is in
const liveCollection = ChannelRepository.getChannels({
  sortBy: 'lastActivity',
  includeDeleted: false,
});
liveCollection.on('dataUpdated', (channels) => renderChannelList(channels));

// Join a channel
await ChannelRepository.joinChannel(channelId);
```
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.

Channels are the container for every chat conversation in social.plus. There are three types — **Community** (public/discoverable), **Live** (broadcast events), and **Conversation** (private 1:1 or small group). This guide covers creating and managing all three.

```mermaid
graph TD
    A[User opens chat] --> B{Channel type?}
    B -->|Open community| C[Community Channel]
    B -->|Event stream| D[Live Channel]
    B -->|Private DM| E[Conversation Channel]
    C --> F[Discover & join]
    D --> G[Join for event duration]
    E --> H[Auto-created on first DM]
    F & G & H --> I[Real-time message stream]
    I --> J{Leave?}
    J -->|Yes| K[Leave channel]
    J -->|No| I

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,J decision
    class C,D,E,F,G,H process
    class I,K outcome
```

## Data Model

```mermaid
erDiagram
    CHANNEL {
        string channelId PK
        string type "community | live | conversation"
        string displayName
        boolean isPublic
        int memberCount
        int messageCount
    }
    SUB_CHANNEL {
        string subChannelId PK
        string channelId FK
    }
    MEMBER {
        string channelId FK
        string userId FK
        string role "member | moderator"
        boolean isMuted
        boolean isBanned
    }
    MESSAGE {
        string messageId PK
        string subChannelId FK
        string creatorId FK
        string dataType "text | image | audio | video | file | custom"
    }
    CHANNEL ||--|{ SUB_CHANNEL : contains
    CHANNEL ||--o{ MEMBER : "has members"
    SUB_CHANNEL ||--o{ MESSAGE : contains
```

**Prerequisites**: SDK installed with authenticated users → [SDK Setup](/social-plus-sdk/getting-started/overview)

## Quick Start: Create and Join a Channel

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

try {
  // Create a public Community channel
  const { data: channel } = await ChannelRepository.createChannel({
    type: 'community',
    displayName: 'General',
    isPublic: true,
  });

  // Join it
  await ChannelRepository.joinChannel(channel.channelId);
} catch (error) {
  console.error('Channel operation failed:', error);
}
```

## Step-by-Step Implementation

    | Type | Use case | Visibility |
    |---|---|---|
    | `community` | Team rooms, Discord-style, community chat | Public or Private |
    | `live` | Livestream chat, event commentary | Public |
    | `conversation` | 1:1 DMs, customer support | Private |

    → [Channel Types](/social-plus-sdk/chat/conversation-management/overview)
```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// Community channel
const { data: channel } = await ChannelRepository.createChannel({
  type: 'community',
  displayName: 'Product Feedback',
  isPublic: true,
  tags: ['feedback', 'product'],
  metadata: { category: 'support' },
});

// Conversation (1:1 DM) — use the other user's ID as channel ID
const { data: dm } = await ChannelRepository.createChannel({
  type: 'conversation',
  userIds: ['user-123', 'user-456'],
});
```

    → [Create Channel](/social-plus-sdk/chat/conversation-management/channels/create-channel)
```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

const liveCollection = ChannelRepository.getChannels({
  filter: 'member',       // channels the current user is in
  sortBy: 'lastActivity', // most recently active first
});

// Re-renders whenever a new message arrives or channel is added
liveCollection.on('dataUpdated', (channels) => {
  channels.forEach(channel => {
    console.log(channel.displayName, channel.lastActivity);
  });
});
```

    → [Query Channels](/social-plus-sdk/chat/conversation-management/channels/query-channels)
```typescript
// Join
await ChannelRepository.joinChannel(channelId);

// Leave
await ChannelRepository.leaveChannel(channelId);

// Query members
const members = ChannelRepository.Membership.getMembers({ channelId, limit: 20 });
```

    → [Join/Leave Channel](/social-plus-sdk/chat/conversation-management/members/join-leave-channel)
```typescript
// Update display name and metadata
await ChannelRepository.updateChannel(channelId, {
  displayName: 'New Name',
  metadata: { archived_reason: null },
});

// Archive (hides from list but keeps message history)
// archiving: set archived_reason in metadata (no dedicated archive method in v6)
```

    → [Update Channel](/social-plus-sdk/chat/conversation-management/channels/update-channel) · [Archive Channels](/social-plus-sdk/chat/conversation-management/channels/archive-channels)

## Connect to Moderation & Analytics

    Community channels and their members can be reviewed and managed from **Admin Console → Channels**. Moderators can view message history, ban members, and close channels.

    → [Channel Moderation](/social-plus-sdk/chat/conversation-management/overview)
    Subscribe to `channel.created`, `channel.updated`, and `channel.deleted` webhook events to sync channel data with your own backend or trigger automations.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

## Common Mistakes

**Creating duplicate Conversation channels** — For 1:1 DMs, always check if a conversation already exists between two users before creating a new one. Pass both userIds and the SDK will return the existing channel if one exists.

**Not handling the Live Collection's dispose** — Always call `liveCollection.dispose()` when your UI component unmounts to avoid memory leaks and stale update callbacks.

## Best Practices

    Don't poll for channel updates. Live Collections push updates automatically — new messages, new channels, and member changes all arrive without any extra requests.
    Use the `metadata` field to attach any application-specific data to a channel (event ID, category, feature flags). Keep it under 500KB.
    Archiving preserves message history — users who rejoin can read old messages. Hard deletion is permanent. Default to archive unless regulatory requirements mandate deletion.

**Dive deeper**: [Conversation Management API Reference](/social-plus-sdk/chat/conversation-management/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Start sending and receiving messages in the channels you just created.
    Set up moderator roles before your community grows.
    Add unread badges to your channel list.

---

### [Sending Messages](https://learn.social.plus/use-cases/chat/sending-messages)

> Send text messages, query history, subscribe to real-time updates, and edit or delete messages in any channel.

```typescript
// Send a text message
await MessageRepository.createMessage({
  subChannelId: channelId,
  data: { text: 'Hello world!' },
  dataType: 'text',
});

// Query 20 most recent messages
const liveCollection = MessageRepository.getMessages({
  subChannelId: channelId,
  limit: 20,
});
liveCollection.on('dataUpdated', (messages) => renderMessages(messages));

// Edit a message
await MessageRepository.updateMessage(messageId, {
  data: { text: 'Hello, corrected world!' },
});

// Delete
await MessageRepository.deleteMessage(messageId);
```
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.

Messages are the core of every chat experience. This guide covers the full send-read-edit-delete lifecycle, plus real-time subscriptions so your UI stays in sync without polling.

```mermaid
graph TD
    A[User types message] --> B[createMessage]
    B --> C{Optimistic render}
    C -->|Immediately| D[Show in UI]
    C -->|Background| E[Server processing]
    E -->|Success| F[Message confirmed]
    E -->|Failure| G[Mark as failed]
    F --> H[Live Collection notifies all subscribers]
    H --> I[Other users see message]
    D --> J{User edits?}
    J -->|Yes| K[updateMessage]
    J -->|Delete| L[deleteMessage]
    K & L --> M[Live Collection updates]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class C,J decision
    class B,E,K,L process
    class D,F,G,H,I,M outcome
```

**Prerequisites**: Channel created and user is a member → [Channels & Conversations](/use-cases/chat/channels-and-conversations)

## Limits at a Glance

| Property | Limit |
|---|---|
| Max text length | 20,000 characters |
| Max tags per message | 5 |
| Max metadata size | 100 KB JSON |
| Max mentions per message | 30 |
| Soft-delete behavior | Placeholder remains visible |

## Quick Start: Send and Receive Messages

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

try {
  // Send
  await MessageRepository.createMessage({
    subChannelId: channelId,
    data: { text: 'Hey everyone! 👋' },
    dataType: 'text',
  });
} catch (error) {
  console.error('Failed to send message:', error);
}

// Receive (Live Collection — no try/catch needed)
const feed = MessageRepository.getMessages({ subChannelId: channelId });
feed.on('dataUpdated', (msgs) => console.log(msgs.length, 'messages'));
```

## Step-by-Step Implementation

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

await MessageRepository.createMessage({
  subChannelId: channelId,   // Target channel
  data: { text: 'Hello from TypeScript!' },
  dataType: 'text',
  tags: ['greeting'],        // Optional tags for filtering
  metadata: { source: 'web' }, // Optional custom metadata
});
```

    → [Send Message](/social-plus-sdk/chat/messaging-features/message-creation/send-a-message)
```typescript
const liveCollection = MessageRepository.getMessages({
  subChannelId: channelId,
  limit: 20,           // Load 20 messages per page
  reverse: true,       // Newest first (typical chat layout)
});

// Initial render + any future updates
liveCollection.on('dataUpdated', (messages) => {
  setMessages(messages);
});

// Load older messages
if (liveCollection.hasPrevPage) {
  liveCollection.prevPage();
}
```

    → [Query Messages](/social-plus-sdk/chat/messaging-features/messages/query-and-filter-messages)
    The Live Collection already handles real-time updates — new messages, edits, and deletions all trigger `dataUpdated`. No extra setup required.

    Channel and message subscriptions keep documented SDK data current, but they do not expose typing-indicator state. Do not infer “typing” from user presence, a channel subscription, or message-collection activity.

    → [Real-time Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events)
```typescript
// Edit
await MessageRepository.updateMessage(messageId, {
  data: { text: 'Edited message text' },
});

// Soft delete (message placeholder remains, content removed)
await MessageRepository.deleteMessage(messageId);
```


    → [Edit & Delete Messages](/social-plus-sdk/chat/messaging-features/messages/edit-and-delete-messages)

## Connect to Moderation & Analytics

    social.plus AI Moderation automatically scans message text and flags violations before they're visible to other users. Enable it in **Admin Console → AI Content Moderation**.

    → [AI Content Moderation](/analytics-and-moderation/console/ai-content-moderation)
    Subscribe to `message.created`, `message.updated`, and `message.deleted` webhook events to sync message data or trigger business logic in your backend.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

## Common Mistakes

**Sending to the wrong subChannelId** — For Community and Live channels, `subChannelId` is the same as `channelId`. For Conversation channels (1:1), use the channel's `defaultSubChannelId`. Double-check which ID you're using when switching channel types.

**Forgetting to dispose Live Collections** — Every `liveCollection.on('dataUpdated', …)` subscription holds an open connection. Always call `liveCollection.dispose()` when your component unmounts to prevent memory leaks and ghost re-renders.

## Best Practices

    - Show the message instantly in the UI **before** the server confirms it
    - Mark it with a `sending` state indicator (spinner or dim text)
    - Replace with the confirmed message on success, or show a **retry button** on failure
    - This is the standard pattern for all major chat apps
    - Start with 20–30 messages on first load
    - Paginate backwards only when the user scrolls to the top
    - Fetching large histories upfront increases load time and memory use, especially on mobile
    - The optional `tags` field on messages supports full-text search
    - Tag system messages (join/leave events, announcements) so you can filter them out of the main feed
    - Useful for building filtered views like "only show media messages" or "only announcements"

**Dive deeper**: [Messaging API Reference](/social-plus-sdk/chat/messaging-features/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Add emoji reactions and threaded replies to messages.
    Send images, audio, video, and file attachments.
    Surface unread badges and per-message read receipts.

---

### [Rich Media Messages](https://learn.social.plus/use-cases/chat/rich-media-messages)

> Send images, audio, video, files, and custom message types to elevate the chat experience beyond text.

```typescript
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.

```mermaid
graph TD
    A[User picks file / records audio] --> B[Upload to social.plus File API]
    B --> C{Upload success?}
    C -->|Yes| D[Get fileId]
    C -->|No| E[Show upload error + retry]
    D --> F[createMessage with dataType + fileId]
    F --> G[Message delivered to channel]
    G --> H[Recipients see media preview]
    H --> I{Tap to view?}
    I -->|Yes| J[Open full-screen / native player]
    I -->|No| H

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class C,I decision
    class B,F process
    class D,E,G,H,J outcome
```

**Prerequisites**: Basic message sending is working → [Sending Messages](/use-cases/chat/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

```typescript
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

    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.

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

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

    → [File Upload](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/file)
```typescript
// 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 },
});
```
```typescript
// 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 },
});
```
    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.

```typescript
// 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'],
  },
});
```


    → [Custom Messages](/social-plus-sdk/chat/messaging-features/message-creation/custom-message)
    When querying messages, each media message includes pre-generated thumbnail URLs:

```typescript
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

    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](/analytics-and-moderation/console/ai-content-moderation)
    Configure allowed file types and maximum file sizes in **Admin Console → Network Settings**. The SDK enforces these limits client-side before uploading.

    → [Network Settings](/analytics-and-moderation/social+-apis-and-services/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

    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 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.
    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](/social-plus-sdk/chat/messaging-features/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Let users react to and thread on your rich media messages.
    Moderate images and files before they reach other members.
    Full DM build path showing where rich media fits in the flow.

---

### [Message Reactions & Replies](https://learn.social.plus/use-cases/chat/message-reactions-and-replies)

> Add emoji reactions to messages and build threaded reply conversations inside any channel.

```typescript
// React to a message
await ReactionRepository.addReaction({
  referenceType: 'message',
  referenceId: messageId,
  reactionName: '👍',
});

// Reply to a message (parentId creates a thread)
await MessageRepository.createMessage({
  subChannelId: channelId,
  parentId: parentMessageId,    // ← this is what makes it a reply
  data: { text: 'Great point!' },
  dataType: 'text',
});

// Query replies for a message
const replies = MessageRepository.getMessages({
  subChannelId: channelId,
  parentId: parentMessageId,
});
```
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.

Reactions turn passive reading into participation. Threaded replies keep side conversations organized without cluttering the main feed. Together they're the core engagement layer of any chat experience.

```mermaid
graph TD
    A[Message in channel] --> B{User interaction}
    B -->|Tap emoji| C[addReaction]
    B -->|Press reply| D[createMessage with parentId]
    C --> E[Reaction stored on message]
    E --> F[Live Collection updates reaction counts]
    F --> G[All users see updated emoji + count]
    D --> H[Reply message created]
    H --> I[Thread visible under parent]
    I --> J[getMessages with parentId]
    J --> K[Paginate replies]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B decision
    class C,D,H,J process
    class E,F,G,I,K outcome
```

**Prerequisites**: Messages are being sent and received → [Sending Messages](/use-cases/chat/sending-messages)

## Quick Start: React to a Message

```typescript
import { ReactionRepository } from '@amityco/ts-sdk';

try {
  await ReactionRepository.addReaction({
    referenceType: 'message',
    referenceId: messageId,
    reactionName: '❤️',
  });
} catch (error) {
  console.error('Failed to add reaction:', error);
}
```

## Step-by-Step Implementation

```typescript
import { ReactionRepository } from '@amityco/ts-sdk';

// Add
await ReactionRepository.addReaction({
  referenceType: 'message',
  referenceId: messageId,
  reactionName: '👍',
});

// Remove
await ReactionRepository.removeReaction({
  referenceType: 'message',
  referenceId: messageId,
  reactionName: '👍',
});
```

    → [Message Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)
    Reaction data is available directly on the message object. The Live Collection automatically pushes updates when another user reacts.

```typescript
// Message object from Live Collection
liveCollection.on('dataUpdated', (messages) => {
  messages.forEach(msg => {
    // reactions is a map of reactionName → count
    const hearts = msg.reactions?.['❤️'] ?? 0;
    const thumbsUp = msg.reactions?.['👍'] ?? 0;
    console.log(`❤️ ${hearts}, 👍 ${thumbsUp}`);
  });
});
```

    For a detailed breakdown (who reacted), query the reaction list:

```typescript
const reactors = ReactionRepository.getReactions({
  referenceType: 'message',
  referenceId: messageId,
  reactionName: '❤️',        // Optional: filter to one reaction
});

reactors.on('dataUpdated', (items) => {
  const userIds = items.map(r => r.userId);
});
```
    Replies use the same `createMessage` call with an additional `parentId`. This links the reply to its parent without a separate thread API.

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

await MessageRepository.createMessage({
  subChannelId: channelId,
  parentId: parentMessageId,   // ← Creates a reply thread
  data: { text: 'I agree with this!' },
  dataType: 'text',
});
```

    → [Reply to a Message](/social-plus-sdk/chat/messaging-features/message-creation/reply-to-a-message)
    Pass `parentId` to `getMessages` to retrieve only the replies in a thread.

```typescript
const thread = MessageRepository.getMessages({
  subChannelId: channelId,
  parentId: parentMessageId,   // Only replies to this message
  limit: 10,
});

thread.on('dataUpdated', (replies) => {
  console.log(`${replies.length} replies in thread`);
});
```

    The parent message itself contains a `replyCount` property that you can use to display a "View N replies" button without loading the full thread.

## Connect to Moderation & Analytics

    Users can report messages that have received reactions containing offensive content. Reports appear in **Admin Console → Content Moderation → Flagged Items**.
    `reaction.added` and `reaction.removed` webhook events let you track engagement patterns or sync reaction data to your analytics pipeline.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

## Common Mistakes

**Duplicating reactions** — A user can add the same `reactionName` only once per message. Calling `addReaction` a second time with the same name is a no-op (not an error). Track local state to style the "active" reaction button correctly.

**Querying root messages with parentId set** — When querying the main channel feed, always set `parentId: null` (or omit it). Otherwise you'll get only replies and miss all top-level messages.

## Best Practices

    Curate a small emoji picker (6–8 options) rather than exposing the full Unicode emoji keyboard. This speeds up rendering and keeps reaction data cleaner. Store allowed reactions in your app's config or in the channel's `metadata`.
    Use the `replyCount` field on the parent message to render a "View 3 replies" button. Only query the thread on demand — lazy loading keeps the initial message feed fast.
    social.plus supports single-level threading (replies to a message). Deeply nested threads hurt UX on mobile. Flatten all replies to one level even if your users try to reply-to-a-reply.

**Dive deeper**: [Messaging API Reference](/social-plus-sdk/chat/messaging-features/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Surface unread message and mention badges across channels.
    Let users share images, files, and audio in addition to reactions.
    Moderate inappropriate reactions and replies from the admin console.

---

### [Unread Counts & Read Receipts](https://learn.social.plus/use-cases/chat/unread-counts-and-read-receipts)

> Show per-channel unread badges, mention indicators, and per-message delivery and read status.

```typescript
// Get unread count for a single channel
const channel = await ChannelRepository.getChannel(channelId);
console.log(channel.unreadCount);      // unread messages
console.log(channel.isMentioned);      // @-mentioned in this channel

// List all channels sorted by unread
const list = ChannelRepository.getChannels({
  filter: 'member',
  sortBy: 'lastActivity',
});
list.on('dataUpdated', (channels) => {
  channels.forEach(c => console.log(c.displayName, c.unreadCount));
});

// Mark channel as read (resets unread count to 0)
await channel.markAsRead();
```
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.

Unread counts and read receipts are often the first thing users look at when opening a chat app. A clean badge system drives re-engagement; missing badges feel like a broken product. This guide covers both the per-channel unread count and per-message delivered/read status.

```mermaid
graph TD
    A[New message arrives] --> B[Server increments unreadCount]
    B --> C[Live Collection pushes update]
    C --> D[Channel badge shows unreadCount]
    D --> E{User opens channel?}
    E -->|Yes| F[markAsRead called]
    F --> G[unreadCount resets to 0]
    F --> H[readAt timestamp recorded]
    H --> I[Sender sees read receipt ✓✓]
    E -->|No| D
    A --> J{Contains @mention?}
    J -->|Yes| K[isMentioned = true]
    K --> L[Highlight mention badge]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class E,J decision
    class B,C,F,H process
    class D,G,I,K,L outcome
```

**Prerequisites**: User is a member of channels with messages → [Channels & Conversations](/use-cases/chat/channels-and-conversations)

## Quick Start

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

try {
  const channel = await ChannelRepository.getChannel(channelId);
  console.log(`${channel.unreadCount} unread, mentioned: ${channel.isMentioned}`);

  // After the user opens the channel view
  await channel.markAsRead();
} catch (error) {
  console.error('Failed to read channel status:', error);
}
```

## Step-by-Step Implementation

    Pull `unreadCount` and `isMentioned` from the channel list Live Collection for a real-time inbox view:

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

const list = ChannelRepository.getChannels({
  filter: 'member',
  sortBy: 'lastActivity',
});

list.on('dataUpdated', (channels) => {
  channels.forEach(channel => {
    const badge = channel.isMentioned
      ? '@'                          // Mention badge takes priority
      : channel.unreadCount > 0
        ? String(channel.unreadCount) // Numeric badge
        : '';
    updateChannelRow(channel.channelId, badge);
  });
});
```

    → [Channel Unread Count](/social-plus-sdk/chat/engagement-features/unread-status/channel-unread-count)
    Some channel configurations do not support unread counts (e.g., channels joined before unread tracking was enabled). Always check `isUnreadCountSupported` before rendering the badge:

```typescript
channels.forEach(channel => {
  if (!channel.isUnreadCountSupported) {
    // Hide badge UI for this channel
    return;
  }
  renderBadge(channel.unreadCount);
});
```

    → [Unread Count Support](/social-plus-sdk/chat/engagement-features/unread-status/channel-unread-count)
    Call `markAsRead` as soon as the user views the channel. Deferring this call creates a confusing experience where the user has already read messages but still sees a badge.

```typescript
// Call when the channel view mounts or becomes active
async function onChannelOpen(channel: Amity.Channel) {
  await channel.markAsRead();
}
```
    For 1:1 Conversation channels, show individual message delivery and read status (the ✓ / ✓✓ pattern):

```typescript
liveCollection.on('dataUpdated', (messages) => {
  messages.forEach(msg => {
    let status = '⏱ Sending';
    if (msg.syncState === 'synced') status = '✓ Sent';
    if (msg.readByCount > 0)        status = '✓✓ Read';
    renderMessageStatus(msg.messageId, status);
  });
});
```

    | Property | Meaning |
    |---|---|
    | `syncState === 'synced'` | Message delivered to server |
    | `readByCount > 0` | At least one member has read it |
    | `deliveredToMemberCount` | How many members received it |

    → [Message Read Status](/social-plus-sdk/chat/engagement-features/unread-status/message-read-status)

## Connect to Moderation & Analytics

    Pair unread counts with push notifications so users re-engage even when the app is backgrounded. Configure notification templates in **Admin Console → Push Notifications**.

    → [Push Notifications Setup](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device)
    Track how often users @mention each other using the Analytics API to surface power users for community health reporting.

    → [Analytics Overview](/analytics-and-moderation/console/analytics/)

## Common Mistakes

**Calling `markAsRead` too early** — If you call `markAsRead` when the channel row is tapped rather than when the message list is visible, messages might be marked read before the user sees them. Call it inside the component that shows the message list (`componentDidMount` / `onResume` / `viewDidAppear`).

**Rendering unread counts on unsupported channels** — Always check `isUnreadCountSupported`. Rendering a badge of `0` (not null) from an unsupported channel is misleading — it implies tracking is working when it isn't.

## Best Practices

    Display `@` when `isMentioned` is true, even if `unreadCount` is low. A direct mention requires attention regardless of total message volume.
    Channels with hundreds of unread messages are likely muted or archived. Show `99+` to avoid layout overflow and signal to the user that they should mute or catch up.
    Unread counts only help users already in the app. Configure push notifications in the Admin Console to bring users back when they have unread messages. The two systems share the same underlying unread data.

**Dive deeper**: [Messaging API Reference](/social-plus-sdk/chat/messaging-features/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Core message send/receive implementation.
    Control who can post and who can moderate unread/read state.
    Full DM build path where read receipts matter most.

---

### [Channel Roles & Permissions](https://learn.social.plus/use-cases/chat/channel-roles-and-permissions)

> Assign moderator and member roles to control who can post, manage members, and moderate content in every channel.

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// Add a moderator role
await ChannelRepository.Moderation.addRole(channelId, 'channel-moderator', [userId]);

// Remove a moderator role
await ChannelRepository.Moderation.removeRole(channelId, 'channel-moderator', [userId]);

// Query members by role
const mods = ChannelRepository.Membership.getMembers({
  channelId,
  roles: ['channel-moderator'],
});
mods.on('dataUpdated', (members) => renderModeratorList(members));
```
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.

Channel roles let you delegate community management without giving users platform-wide admin access. A **moderator** can mute, ban, and delete messages. A **channel owner** (automatically assigned on creation) can manage roles and channel settings. Regular **members** can read and write, but nothing more.

```mermaid
graph TD
    A[Channel created] --> B[Creator = channel-owner]
    B --> C{Assign roles}
    C -->|Promote user| D[addRole: channel-moderator]
    C -->|Demote user| E[removeRole: channel-moderator]
    D --> F[Moderator can ban/mute/delete]
    E --> G[User reverts to member]
    B --> H[Owner can manage roles + settings]
    F & H --> I{Permission check in SDK}
    I -->|Allowed| J[Action proceeds]
    I -->|Denied| K[Permission error]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class C,I decision
    class B,D,E,F,G,H process
    class J,K outcome
```

**Prerequisites**: Community channel with at least a few members → [Channels & Conversations](/use-cases/chat/channels-and-conversations)

## Quick Start: Promote a Member to Moderator

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

try {
  // Grant moderator privileges to a user
  await ChannelRepository.Moderation.addRole(channelId, 'channel-moderator', [userId]);
} catch (error) {
  console.error('Failed to assign role:', error);
}
```

## Step-by-Step Implementation

    | Role | Permissions |
    |---|---|
    | `channel-owner` | Manage roles, update channel, archive, all moderator permissions |
    | `channel-moderator` | Ban/unban members, mute/unmute, delete any message |
    | *(member — default)* | Send messages, react, view members |


    → [Roles and Permissions Reference](/social-plus-sdk/chat/conversation-management/overview)
```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// Add moderator
await ChannelRepository.Moderation.addRole(channelId, 'channel-moderator', [userId]);

// Remove moderator
await ChannelRepository.Moderation.removeRole(channelId, 'channel-moderator', [userId]);

// Transfer ownership (remove from self, add to other)
await ChannelRepository.Moderation.removeRole(channelId, 'channel-owner', [myUserId]);
await ChannelRepository.Moderation.addRole(channelId, 'channel-owner', [newOwnerId]);
```
```typescript
// All members
const members = ChannelRepository.Membership.getMembers({ channelId });
members.on('dataUpdated', (list) =>
  list.forEach(m => console.log(m.userId, m.roles))
);

// Only moderators
const mods = ChannelRepository.Membership.getMembers({
  channelId,
  roles: ['channel-moderator', 'channel-owner'],
});
```

    → [Query Channel Members](/social-plus-sdk/chat/conversation-management/members/query-members)
    Check the current user's roles before showing ban/mute buttons:

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

const { data: membership } = await ChannelRepository.Membership.getMembers(channelId, currentUserId);
const canModerate = membership.roles.some(
  r => r === 'channel-moderator' || r === 'channel-owner'
);

if (canModerate) {
  showModerationControls();
}
```

    Beyond the built-in roles, you can define custom roles (e.g., `vip`, `verified-seller`) with specific permission sets in **Admin Console → Roles & Permissions**. Custom roles appear in `member.roles` exactly like built-in ones.

    → [Custom Roles](/analytics-and-moderation/console/management/)

## Connect to Moderation & Analytics

    `member.roles_added` and `member.roles_removed` webhook events let you sync role changes with your own database or trigger downstream workflows (e.g., granting a user access to a private board after becoming a moderator).

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)
    All role assignments are logged in **Admin Console → Audit Log**. Use this to review who granted moderator access and when.

## Common Mistakes

**Forgetting to remove the owner role before transferring** — Calling `addRole` for `channel-owner` on a new user without removing it from the current owner results in two owners, which may cause unexpected permission behavior. Always remove before adding for ownership transfer.

**Checking roles only on the client** — Roles are enforced server-side. Client-side checks are only for UI gating. A user who has been demoted but still has a cached role object in memory will receive a server error on their next moderation action.

## Best Practices

    Promote at least one moderator immediately after creating a channel, especially for public Community channels. Unmoderated channels fill up with spam within hours of gaining traction.
    Create roles like `vip` or `premium` to give paying users or power members special UI treatment (highlighted names, extended media limits) without granting full moderation powers.
    Review moderator lists quarterly. Former moderators who no longer actively participate should be demoted — stale moderator accounts are a common attack vector.

**Dive deeper**: [Moderation & Safety API Reference](/social-plus-sdk/chat/conversation-management/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Use your new moderators to ban, mute, and remove content.
    Full group chat build path where roles and permissions matter most.
    Back to channel management fundamentals.

---

### [Chat Moderation](https://learn.social.plus/use-cases/chat/chat-moderation)

> Mute and ban users, remove messages, set rate limits, and connect AI moderation to keep your chat communities safe.

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// Mute a user in a channel (temporarily silence them)
await ChannelRepository.Moderation.muteMembers(channelId, [userId], 60); // 60 seconds

// Ban a user from a channel (removes them + deletes their messages)
await ChannelRepository.Moderation.banMembers(channelId, [userId]);

// Unban
await ChannelRepository.Moderation.unbanMembers(channelId, [userId]);

// Delete a specific message
import { MessageRepository } from '@amityco/ts-sdk';
await MessageRepository.deleteMessage(messageId);
```
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.

Effective moderation is what separates thriving communities from abandoned ones. This guide covers the full moderation toolkit: temporary mutes for friction, channel bans for violations, network-wide global bans for bad actors, AI moderation for scale, and webhooks for custom workflows.

```mermaid
graph TD
    A[User sends a message] --> B{AI moderation?}
    B -->|Enabled| C[AI scans content]
    C -->|Clean| D[Message visible]
    C -->|Flagged| E[Message blocked/reviewed]
    B -->|Disabled| D
    D --> F{Human report?}
    F -->|Reported| G[Admin reviews in Console]
    G --> H{Decision}
    H -->|Warn| I[Send warning message]
    H -->|Mute| J[muteMembers in channel]
    H -->|Ban from channel| K[banMembers removes + deletes]
    H -->|Global ban| L[Network-wide block]
    J & K & L --> M[User cannot send more messages]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,F,H decision
    class C,G,I,J,K,L process
    class D,E,M outcome
```

**Prerequisites**: Channel with member roles configured → [Channel Roles & Permissions](/use-cases/chat/channel-roles-and-permissions)

## Quick Start: Ban a User

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

try {
  // Ban removes the user from the channel and deletes their messages
  await ChannelRepository.Moderation.banMembers(channelId, [userId]);
}
```

## Step-by-Step Implementation

    Muting silences a user for a fixed duration without removing them from the channel. Use this for first offenses or to de-escalate a heated argument.

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// Mute for 5 minutes (300 seconds)
await ChannelRepository.Moderation.muteMembers(channelId, [userId], 300);

// Mute indefinitely
await ChannelRepository.Moderation.muteMembers(channelId, [userId]);

// Unmute
await ChannelRepository.Moderation.unmuteMembers(channelId, [userId]);
```

    → [Mute / Unmute](/social-plus-sdk/chat/conversation-management/overview)
    Banning removes the user from the channel and deletes their messages in one operation. Unbanning restores access but does not restore deleted messages.

```typescript
// Ban
await ChannelRepository.Moderation.banMembers(channelId, [userId]);

// Unban
await ChannelRepository.Moderation.unbanMembers(channelId, [userId]);

// Query banned users
const banned = ChannelRepository.Membership.getMembers({
  channelId,
  filter: 'bannedMember',
});
banned.on('dataUpdated', (list) => renderBannedList(list));
```


    → [Ban / Unban](/social-plus-sdk/chat/conversation-management/overview)
    When a specific message (not the user) needs to be removed:

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

// Any channel moderator or admin can delete any message
await MessageRepository.deleteMessage(messageId);
```

    Deleted messages are soft-deleted — a placeholder "Message was deleted" remains visible in the thread so the conversation history stays coherent.
    For users who violate your terms of service across multiple channels, use the Global Ban API to block them at the network level. This is typically done from the Admin Console or via the server-side API.

    **From Admin Console**: **User Management → Find User → Ban**

    **Via API (server-side)**:
```bash
curl -X POST 'https://apix.<region>.amity.co/api/v3/users/<userId>/ban' \
  -H 'x-admin-token: <your-admin-token>'
```

    → [Global Ban API](/analytics-and-moderation/social+-apis-and-services/README)
    social.plus AI Moderation automatically analyzes messages before they're published and can block, flag, or allow content based on configurable policies.

    1. Go to **Admin Console → AI Content Moderation**
    2. Enable text and/or image moderation
    3. Configure severity thresholds (block vs. review vs. allow)
    4. Review flagged items in **Moderation → Flagged Items**

    → [AI Content Moderation](/analytics-and-moderation/console/ai-content-moderation)
    Use webhook events to trigger custom workflows when moderation actions occur:

    | Event | Trigger |
    |---|---|
    | `user.banned` | User banned (channel or global) |
    | `user.unbanned` | Ban lifted |
    | `message.flagged` | User reported a message |
    | `message.deleted` | Message deleted by moderator |

```javascript
// Webhook handler example
app.post('/webhook', (req, res) => {
  const { event, data } = req.body;

  if (event === 'user.banned') {
    notifyUserOfBan(data.userId, data.reason);
    logModerationAction(data);
  }

  res.status(200).json({ status: 'received' });
});
```

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

## Connect to Moderation & Analytics

    **Admin Console → Moderation** gives your trust & safety team a centralized view of flagged content, user reports, and pending review items across all channels.

    → [Moderation Overview](/analytics-and-moderation/console/moderation/)
    Configure per-user message rate limits in **Admin Console → Network Settings** to automatically throttle users who send messages too quickly — without requiring manual moderator action.

    → [Network Settings](/analytics-and-moderation/social+-apis-and-services/network-settings)
    Pre-hook webhooks let your server inspect and optionally block messages *before* they are accepted by social.plus. Use this for custom profanity filters, link blocking, or compliance workflows.

    → [Pre-Hook Events](/analytics-and-moderation/social+-apis-and-services/pre-hook-event)

## Common Mistakes

**Using ban instead of mute for minor rule breaks** — Banning is irreversible in the sense that it deletes messages. Reserve bans for serious violations. Use mutes for temporary timeouts — they're adjustable and reversible without data loss.

**Not informing users why they were moderated** — Unexplained bans drive users away permanently. Always send a `custom` system message to the channel or a direct notification explaining the reason. This also reduces false positive appeals.

## Best Practices

    Define a progression: (1) verbose content warning → (2) temporary mute → (3) channel ban → (4) global ban. Using the most severe option first for minor violations destroys community trust and drives false appeal volume.
    Grant `channel-moderator` roles to trusted community members before the channel grows. Reactive moderator assignment (after problems start) means violations compound faster than you can respond. See [Channel Roles & Permissions](/use-cases/chat/channel-roles-and-permissions).
    AI moderation catches spam and NSFW content reliably, but misses context-specific violations. Pair it with a human review queue for flagged items and empower community members to report edge cases.

**Dive deeper**: [Moderation & Safety API Reference](/social-plus-sdk/chat/conversation-management/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

    Who to promote before channels need moderation.
    Complete group chat build path from creation to moderation.
    Review flagged items from a trust & safety dashboard.

## Use Cases — Social

### [Build a Social Feed](https://learn.social.plus/use-cases/social/build-a-social-feed)

> Query user feeds, community feeds, and a global aggregated feed with real-time updates and custom post ranking.

```typescript
// 1. Query a user feed
const repository = new AmityFeedRepository();
const posts = await repository.getUserFeed(
  'user-123',
  ['user', 'community'],
  undefined,
  'lastCreated',
  false,
  true
);

// 2. Query a community feed with live updates
import { PostRepository, subscribeTopic, getCommunityTopic, SubscriptionLevels } from '@amityco/ts-sdk';

const unsubscribe = PostRepository.getPosts(
  { targetId: 'communityId', targetType: 'community', sortBy: 'lastCreated' },
  ({ data: posts }) => {
    if (posts) { /* render posts */ }
  },
);

// 3. Subscribe to real-time events (required for server-side updates)
subscribeTopic(getCommunityTopic(community, SubscriptionLevels.POST));

// 4. Unsubscribe when done
unsubscribe();
```
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.

  <img
    src="/images/use-cases/social-feed-hero.png"
    alt="Three social feed screens: mobile newsfeed with story ring bar and featured posts, community sidebar with explore and member list, and desktop feed with video post and hashtags"
  />

A social feed is the heart of any social app. This guide walks through querying the right feed for each context, subscribing to real-time updates, and controlling post ranking.

```mermaid
graph TD
    A[User opens app] --> B{Feed type?}
    B -->|Home timeline| C[User Feed]
    B -->|Inside a community| D[Community Feed]
    B -->|Explore page| E[Global Feed]
    B -->|Personalized| FY[For You Feed]
    C --> F[Live Collection]
    D --> F
    E --> F
    FY --> F
    F --> G[Posts render in-app]
    G --> H{Post flagged?}
    H -->|Yes| I[Hidden from feed]
    H -->|No| G

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,H decision
    class C,D,E,F process
    class G,I outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). You'll need a valid `userId` for the current user and optionally a `communityId` for community-scoped feeds.

**After completing this guide you'll have:**
- A live-updating user feed, community feed, and global feed rendering in your app
- Real-time post additions and deletions via Live Collections
- Post ranking configured and connected to the Admin Console

---

## Quick Start: Query a User Feed

Use `AmityFeedRepository` to query a user's combined feed (their own posts + community posts they authored):


Full reference → [Get User Feed](/social-plus-sdk/social/discovery-engagement/feed/overview)

---

## Step-by-Step Implementation

    Use `PostRepository.getPosts()` to query all posts within a specific community. Filter by post type, sort order, and deletion status.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

const unsubscribe = PostRepository.getPosts(
  { targetId: 'communityId', targetType: 'community', sortBy: 'lastCreated' },
  ({ data: posts, onNextPage, hasNextPage, loading }) => {
    if (posts) { /* render posts */ }
  },
);
```

    Full reference → [Query Posts](/social-plus-sdk/social/content-management/posts/retrieval/query-posts)
    The global feed aggregates posts across all communities. The SDK provides both chronological ordering and custom-ranked feeds based on engagement metrics.

```typescript TypeScript
import { FeedRepository } from '@amityco/ts-sdk';

const unsubscribe = FeedRepository.getGlobalFeed(
  { limit: 20, includeDeleted: false },
  ({ data: posts, onNextPage, hasNextPage, loading }) => {
    if (posts) { /* render global feed */ }
  },
);
```

    Full reference → [Query Global Feed](/social-plus-sdk/social/discovery-engagement/feed/global-feed)
    For You is a backend-personalized global feed. It is a network-level feature — gate the surface on `Client.getForYouFeedSetting()` and handle `AmityForYouFeedDisabledError` for networks where it is not enabled. `getForYouFeed()` takes no query parameters; page through the callback.

```typescript TypeScript
import { Client, FeedRepository } from '@amityco/ts-sdk';

const { forYouFeed } = await Client.getForYouFeedSetting();
if (!forYouFeed.enabled) return; // hide the For You surface

const unsubscribe = FeedRepository.getForYouFeed(
  ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
    if (error instanceof FeedRepository.AmityForYouFeedDisabledError) return;
    if (posts) { /* render For You feed */ }
  },
);
```

    Full reference → [Query For You Feed](/social-plus-sdk/social/discovery-engagement/feed/for-you-feed)
    Live Collections auto-update from **local cache** changes (e.g., the current user creates a post). To also receive **server-side** updates (new posts from other users, moderator deletions), you must explicitly subscribe to the relevant topic.

```typescript TypeScript
import { subscribeTopic, getCommunityTopic, getUserTopic, SubscriptionLevels } from '@amityco/ts-sdk';

// For a community feed — receive new/edited/deleted post events
const disposers: (() => void)[] = [];
disposers.push(subscribeTopic(getCommunityTopic(community, SubscriptionLevels.POST)));

// For a user feed — receive events for that user's posts
disposers.push(subscribeTopic(getUserTopic(user, SubscriptionLevels.POST)));

// Clean up when the view unmounts
disposers.forEach(fn => fn());
unsubscribe(); // also stop the Live Collection query
```

    Full reference → [Social Real-time Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events)
    Live Collections provide `onNextPage` and `hasNextPage` in the callback. Trigger load-more when the user scrolls near the bottom.

```typescript TypeScript
// Inside your callback, capture the pagination helpers:
let nextPageFn: (() => void) | undefined;
let hasMore: boolean | undefined;

// In the callback:
hasMore = hasNextPage;
nextPageFn = onNextPage;

// When user scrolls to bottom:
if (hasMore) nextPageFn?.();
```

    Full reference → [Live Objects & Collections](/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview)
    Pin specific posts to the top of a community feed or enable the engagement-based ranking algorithm that factors in comments, reactions, and time decay.

    Full reference → [Custom Post Ranking](/social-plus-sdk/social/discovery-engagement/feed/custom-ranking)

---

## Connect to Moderation & Analytics

    When a user flags a post via the SDK, the post is submitted for moderator review. By default, flagged posts remain visible until a moderator takes action. You can configure automatic hiding of reported content in the **Admin Console → Content Moderation → Settings**.

    - SDK flagging → [Content Flagging](/social-plus-sdk/social/content-management/moderation/content-flagging)
    - Console review → [Admin Console Moderation](/analytics-and-moderation/console/moderation/overview)
    Track how many users viewed posts in the feed using impression analytics.

    View aggregated impression data in **Admin Console → Social Management → Post Analytics**.

    Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Receive a webhook event whenever a post is created in a community your server monitors. Use this to send push notifications or trigger downstream workflows.

    Reference → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Fetching the entire feed at once** — Loading all posts without pagination causes memory spikes and slow initial renders. Always use `limit` and paginate with cursors.

```typescript
// ❌ Bad — fetches everything at once
const allPosts = await repository.getUserFeed('user-123', ['user', 'community']);

// ✅ Good — use Live Collection with pagination
const unsubscribe = PostRepository.getPosts(
  { targetId: 'communityId', targetType: 'community', sortBy: 'lastCreated' },
  ({ data: posts, onNextPage, hasNextPage }) => {
    renderPosts(posts);
    // Load more only when the user scrolls down
  },
);
```

**Skipping topic subscription** — Live Collections auto-update from local cache, but **not** from server-side events (other users' posts, moderator actions) unless you call `subscribeTopic()`. Without it your feed goes stale.

```typescript
// ❌ Bad — no topic subscription, misses server events
const unsubscribe = PostRepository.getPosts(params, callback);

// ✅ Good — subscribe to the community topic for real-time post events
subscribeTopic(getCommunityTopic(community, SubscriptionLevels.POST));
```

**Not handling deleted or flagged posts** — Posts can be removed by moderators between fetches. Always check `post.isDeleted` before rendering to avoid showing blank cards.

## Best Practices

    - Use `dataTypes` filtering to limit payload size when you only need specific post types
    - Avoid observing the global feed on low-memory devices — use paginated queries instead
    - Unsubscribe Live Collection observers when the screen goes off-screen (lifecycle-aware)
    - Use `untilAt` (iOS/Android) for time-bounded pagination to prevent content jumping when new posts arrive
    - Always show a skeleton/placeholder while the first page loads
    - Show a "New posts" banner (like Twitter) rather than auto-scrolling to the top when live updates arrive
    - Preserve scroll position when the user navigates away and returns
    - Cache the first page of the feed for offline display
    - Never expose the raw API key in client-side code — use the SDK's built-in auth flow
    - Respect `isPublic: false` communities — the SDK automatically filters private communities from feeds
    - Don't cache deleted posts — observe deletions via Live Collections and remove them immediately

---

## Next Steps

  title="Your next step → Rich Content Creation"
  icon="arrow-right"
  href="/use-cases/social/rich-content-creation"
>
  Now that you have a working feed, give users something to post — text, images, videos, polls, and file posts.

Or explore related guides:

    Create the posts that appear in the feed
    Add engagement features to feed posts
    Build the communities that power community feeds

---

### [Rich Content Creation](https://learn.social.plus/use-cases/social/rich-content-creation)

> Let users create text, image, video, poll, and file posts with @mentions, hashtags, and product tagging.

```typescript
// 1. Create a text post
const { data: post } = await PostRepository.createPost({
  targetType: 'community', targetId: 'communityId',
  data: { text: 'Hello world!' },
});

// 2. Create an image post
const { data: imagePost } = await PostRepository.createPost({
  targetType: 'community', targetId: 'communityId',
  data: { text: 'Check this out!' },
  attachments: [{ fileId: 'uploadedFileId', type: 'image' }],
});

// 3. Create a poll post (two-step)
const { data: poll } = await PollRepository.createPoll({
  question: 'Favorite color?',
  answerType: 'single',
  answers: [{ dataType: 'text', data: 'Red' }, { dataType: 'text', data: 'Blue' }],
});
const { data: pollPost } = await PostRepository.createPost({
  targetType: 'community', targetId: 'communityId',
  data: { text: 'Vote now! 👇', pollId: poll.pollId },
});
```
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.

Posts are the primary unit of social content. social.plus supports 11 post types — from simple text to live streams. This guide covers how to implement creation, target posts to users or communities, and attach rich metadata.

```mermaid
graph TD
    A[User taps Create Post] --> B{Post type}
    B --> C[Text]
    B --> D[Image / Video]
    B --> E[Poll]
    B --> F[File / Audio]
    B --> G[Mixed Media]
    B --> H[Custom]
    C & D & E & F & G & H --> I{Target}
    I -->|Own profile| J[User Feed]
    I -->|Community| K[Community Feed]
    J & K --> L[Post published]
    L --> M[Moderation check]
    M -->|ADMIN_REVIEW| N[Post queued]
    M -->|ANYONE_CAN_POST| O[Post live immediately]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,I decision
    class C,D,E,F,G,H,J,K,L,M process
    class N,O outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). For image, video, or file posts: media upload configured → [Media Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/image-handling). You'll need a `targetType` (`user` or `community`) and `targetId`.

**Also recommended:** Complete [Build a Social Feed](/use-cases/social/build-a-social-feed) first so you can see posts appear in a feed as you create them.

**After completing this guide you'll have:**
- A post creation flow supporting text, image, video, and poll post types
- Media upload wired up with progress tracking
- @mentions and hashtag parsing enabled

## Limits at a Glance

| Property | Limit |
|---|---|
| Max text length | 50,000 characters |
| Max images per post | 10 |
| Max video size | 1 GB |
| Max file attachments | 10 |
| Post types | `text`, `image`, `video`, `file`, `poll`, `clip`, `livestream` |
| Mentions per post | 30 |
| Metadata size | 100 KB JSON |

---

## Quick Start: Create a Text Post

Use `AmityPostRepository` to create a text post on a community feed. The same pattern applies to all post types — just add attachments or poll data as needed.

Full reference → [Text Post](/social-plus-sdk/social/content-management/posts/creation/text-post)

---

## Step-by-Step Implementation

    For image, video, audio, and file posts, upload the media first and use the returned file ID in the post builder.

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

const data = new FormData();
data.append('files', file); // file from <input type="file">

const { data: image } = await FileRepository.uploadImage(
  data,
  (percent: number) => console.log(`Upload: ${percent}%`),
);
```

    Full reference → [Image Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/image-handling) · [Video Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/video-handling)
    | Post Type | Use Case | Reference |
    |---|---|---|
    | Text | Status updates, announcements | [Text Post](/social-plus-sdk/social/content-management/posts/creation/text-post) |
    | Image | Photo sharing | [Image Post](/social-plus-sdk/social/content-management/posts/creation/image-post) |
    | Video | Video sharing | [Video Post](/social-plus-sdk/social/content-management/posts/creation/video-post) |
    | Audio | Podcasts, voice notes | [Audio Post](/social-plus-sdk/social/content-management/posts/creation/audio-post) |
    | File | Document sharing | [File Post](/social-plus-sdk/social/content-management/posts/creation/file-post) |
    | Poll | Community votes | [Poll Post](/social-plus-sdk/social/content-management/posts/creation/poll-post) |
    | Mixed Media | Multiple images/videos | [Mixed Media Post](/social-plus-sdk/social/content-management/posts/creation/mixed-media-post) |
    | Clip | Short-form video (TikTok-style) | [Clip Post](/social-plus-sdk/social/content-management/posts/creation/clip-post) |
    | Live Stream | Live video posts | [Live Stream Post](/social-plus-sdk/social/content-management/posts/creation/live-stream-post) |
    | Custom | Any structured data | [Custom Post](/social-plus-sdk/social/content-management/posts/creation/custom-post) |

    Each reference page includes full multi-platform code examples (iOS, Android, TypeScript, Flutter).
    Follow the same pattern as text posts — instantiate a post builder, set the target, attach media or data, and submit.

    Full reference → [Image Post](/social-plus-sdk/social/content-management/posts/creation/image-post) · [Poll Post](/social-plus-sdk/social/content-management/posts/creation/poll-post)
    Mentions trigger notifications to the mentioned users. Pass user IDs alongside their text positions in the post.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

const { data: post } = await PostRepository.createPost({
  data: { text: 'Great idea @userId1!' },
  targetType: 'community',
  targetId: 'communityId',
  mentionees: [{ type: 'user', userIds: ['userId1'] }],
  metadata: {
    mentioned: [{ userId: 'userId1', type: 'user', index: 11, length: 8 }],
  },
});
```

    Full reference → [Mentions in Posts](/social-plus-sdk/core-concepts/content-handling/mentions)
    Update a post's text, tags, or media attachments after creation. You can also soft-delete (hides from feeds) or hard-delete (permanent removal).

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

// Update a post
const { data: updated } = await PostRepository.editPost('postId', {
  data: { text: 'Updated content' },
  tags: ['tag1', 'tag2'],
});

// Soft-delete — hides from feeds, recoverable
await PostRepository.softDeletePost('postId');

// Hard-delete — permanent removal
await PostRepository.hardDeletePost('postId');
```

    Full reference → [Edit Post](/social-plus-sdk/social/content-management/posts/moderation/edit-post) · [Delete Post](/social-plus-sdk/social/content-management/posts/moderation/delete-post)

---

## Connect to Moderation & Analytics

The Admin Console **Posts and comments management** page is the central hub for moderating content. Moderators can filter posts by feed, creator, and status, and create posts directly from the console. AI moderation status is shown inline for every post.

  <img src="/images/analytics-and-moderation/console/posts-page-overview.png" alt="Admin Console — Posts and comments management page" />

You can also create posts directly from the console — useful for platform announcements or seeded content:

  <img src="/images/analytics-and-moderation/console/social-management/create-post-form.png" alt="Admin Console — Create post form" />

    If your community uses `ADMIN_REVIEW_POST_REQUIRED`, new posts land in a review queue in the Admin Console. Moderators can approve, reject, or edit posts before they go live.

    → [Post Review](/social-plus-sdk/social/content-management/posts/moderation/post-review) · [Admin Console: Posts](/analytics-and-moderation/console/social-management/social-management/posts)
    Enable automatic AI screening of post text and images in **Admin Console → Settings → AI Content Moderation**. Posts with policy violations can be auto-rejected or flagged for human review.

    → [AI Content Moderation](/analytics-and-moderation/console/ai-content-moderation)
    Track how many unique users viewed each post using impression analytics. Call `markAsViewed()` when a post enters the viewport.

    → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Posts with product tags surface in the console with linked product cards — admins can see which products are referenced and filter posts by tag. Manage your product catalogue at **Admin Console → Product catalogue**.

    ![Posts with product tags visible in the Admin Console post list](/images/analytics-and-moderation/console/social-management/posts-list-with-product-tags.png)

    → [Product Tagging & Social Commerce](/use-cases/social/product-tagging-and-social-commerce)

---

## Common Mistakes

**Publishing before the file upload completes** — Creating a post with an attachment before `FileRepository.uploadImage()` resolves produces a post with a broken media reference.

```typescript
// ❌ Bad — fire and forget
FileRepository.uploadImage(blob); // no await
PostRepository.createPost({ attachments: [{ fileId: '???' }] });

// ✅ Good — wait for upload
const { data: file } = await FileRepository.uploadImage(blob);
await PostRepository.createPost({ attachments: [{ fileId: file.fileId, type: 'image' }] });
```

**Exceeding the 50,000-character text limit** — Posts with text longer than 50,000 characters are rejected by the API. Validate length in your UI before calling `createPost`.

**Forgetting `targetType` and `targetId`** — Omitting these fields creates a post on the user's own feed. If you intend to post in a community, both fields are required.

## Best Practices

    - Always show an upload progress indicator for image and video posts
    - Compress images client-side before upload (recommended max: 1MB per image)
    - Implement resumable uploads for video files over 10MB
    - Handle upload failures gracefully — store the draft locally and retry
    - Auto-save drafts so users don't lose work if the app is backgrounded
    - Show character count for text posts (max 50,000 characters)
    - Preview images before submission
    - Give clear feedback when a post is pending review vs. immediately published
    - Use custom posts to store structured data (product cards, event summaries, etc.)
    - Always version your custom post `dataType` string so you can evolve the schema
    - Provide a fallback renderer for unknown custom post types

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Comments & Reactions"
  icon="arrow-right"
  href="/use-cases/social/comments-and-reactions"
>
  Content is live — now let users engage with threaded comments and emoji reactions.

Or explore related guides:

    Add engagement features to the posts you create
    Display posts in a feed with real-time updates
    Set up review queues and AI moderation

---

### [Comments & Reactions](https://learn.social.plus/use-cases/social/comments-and-reactions)

> Add threaded comments with @mentions and emoji reactions to posts, stories, and messages.

```typescript
// 1. Add a reaction
await ReactionRepository.addReaction('post', 'postId', 'like');

// 2. Remove a reaction
await ReactionRepository.removeReaction('post', 'postId', 'like');

// 3. Create a comment
await CommentRepository.createComment({
  referenceId: 'postId', referenceType: 'post',
  data: { text: 'Great post!' },
});

// 4. Query comments
CommentRepository.getComments(
  { referenceId: 'postId', referenceType: 'post', limit: 20 },
  ({ data: comments }) => { /* render */ }
);
```
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.

Comments and reactions turn passive content consumption into active engagement. This guide covers creating threaded comments, adding reactions to any content object, querying both in real-time, and surfacing them in your UI.

```mermaid
graph TD
    A[Post / Story / Message] --> B[Add Reaction]
    A --> C[Add Comment]
    B --> D[Reaction stored on content]
    C --> E[Top-level comment]
    E --> F[Reply comment]
    F --> G[Nested thread]
    D & E & G --> H[Live Collection update]
    H --> I[UI updates in real-time]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,C,D,E,F,G,H process
    class I outcome
```

**Prerequisites**: SDK installed and authenticated. You'll need a `referenceId` (post ID, comment ID, or story ID) and `referenceType` to attach comments and reactions to.

**Also recommended:** Complete [Rich Content Creation](/use-cases/social/rich-content-creation) first — you need posts to comment on and react to.

**After completing this guide you'll have:**
- Threaded comments (comments + replies) on any post or story
- Emoji reactions added and removed in real-time
- Reaction counts and comment counts updating live in your UI

---

## Quick Start: Add a Reaction

Use the reactions API to add emoji reactions to posts, comments, stories, and messages:


Full reference → [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)

---

## Step-by-Step Implementation

    Use `referenceType: .post` for post comments. Other valid values: `.content` (stories), `.message` (chat).

```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

const { data: comment } = await CommentRepository.createComment({
  data: { text: 'hello!' },
  referenceId: 'postId',
  referenceType: 'post' as Amity.CommentReferenceType,
});
```

    Full reference → [Text Comment](/social-plus-sdk/social/content-management/comments/creation/text-comment)
    Pass the parent comment's ID as `parentId` to create a nested reply.

```typescript TypeScript
const { data: reply } = await CommentRepository.createComment({
  data: { text: 'I agree!' },
  referenceId: 'postId',
  referenceType: 'post' as Amity.CommentReferenceType,
  parentId: 'parent-comment-id', // makes this a reply
});
```

    Full reference → [Text Comment](/social-plus-sdk/social/content-management/comments/creation/text-comment)
    Use a Live Collection to get comments and subscribe to new additions. Filter by `filterByParentId` to get top-level comments only or a flat list.

```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

const unsubscribe = CommentRepository.getComments(
  { referenceType: 'post', referenceId: 'postId', dataTypes: { values: ['text'], matchType: 'exact' } },
  ({ data: comments, onNextPage, hasNextPage, loading }) => {
    if (comments) { /* render comment thread */ }
  },
);
```

    Full reference → [Query Comments](/social-plus-sdk/social/content-management/comments/retrieval/query-comments)
    Reactions use a single `addReaction()` call. Built-in types: `like`, `love`, `wow`, `laugh`, `sad`, `angry`. Custom types are also supported.


    Full reference → [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)
    Pass user IDs and their positions in the comment text to trigger mention notifications.

```typescript TypeScript
const { data: comment } = await CommentRepository.createComment({
  data: { text: 'great point @userId1!' },
  referenceId: 'postId',
  referenceType: 'post' as Amity.CommentReferenceType,
  mentionees: [{ type: 'user', userIds: ['userId1'] }] as Amity.UserMention[],
});
```

    Full reference → [Mentions](/social-plus-sdk/core-concepts/content-handling/mentions)

---

## Connect to Moderation & Analytics

The Admin Console **Posts and comments management** page gives moderators full visibility into every comment thread — including threaded replies, AI moderation status, and direct action menus.

  <img src="/images/analytics-and-moderation/console/posts-page-comments-tab.png" alt="Admin Console — Comments & Replies tab showing threaded comment management" />

    Users can flag comments for moderator review using the same flagging system as posts. Flagged comments appear in the Admin Console moderation queue.

    → [Content Flagging](/social-plus-sdk/social/content-management/moderation/content-flagging) · [Admin Console Moderation](/analytics-and-moderation/console/moderation/overview)
    Query aggregated reaction counts and per-user reaction data via the SDK. View engagement metrics in the Admin Console analytics dashboard.

    → [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions) · [Admin Console Social Analytics](/analytics-and-moderation/console/analytics/)
    Receive `comment.created` webhook events to build notification workflows or sync comment data to your own backend.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Adding duplicate reactions** — Calling `addReaction` twice with the same reaction name throws an error. Check the post's `myReactions` array before adding.

```typescript
// ❌ Bad — no check
await ReactionRepository.addReaction('post', postId, 'like');

// ✅ Good — check first
if (!post.myReactions.includes('like')) {
  await ReactionRepository.addReaction('post', postId, 'like');
}
```

**Loading all comments without pagination** — Deeply nested threads can have hundreds of replies. Always set a `limit` and let users tap "Load more" for the rest.

**Not subscribing to comment Live Collections** — If another user replies while the thread is open, your UI won't update. Use the observable pattern so new comments appear in real time.

## Best Practices

    - Limit visible nesting depth to 2-3 levels in the UI — deeper nesting is confusing to users
    - Show a "View X replies" collapsed state instead of rendering all replies upfront
    - Use `getLatestComment()` to show a preview of the most recent comment in feed cards without loading the full comment thread
    - Sort by `lastCreated` (newest first) for fast-moving communities; `firstCreated` for long-form discussion
    - Display a compact reaction pill with the top 3 reactions and total count
    - Show the user's own reaction as highlighted/selected so they can tap to remove it
    - Animate reaction additions — a small bounce or pop goes a long way
    - For communities that want positivity-only, restrict available reactions to a custom subset
    - Paginate comments — load 20 at a time and use `loadMore()` on scroll
    - Unsubscribe comment Live Collections when the user navigates away
    - Cache reaction counts client-side and reconcile with server state on resume

---

**Dive deeper**: [Comments API Reference](/social-plus-sdk/social/content-management/comments/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → User Profiles & Social Graph"
  icon="arrow-right"
  href="/use-cases/social/user-profiles-and-social-graph"
>
  Engagement is working — now build profile pages, follow/unfollow flows, and friend connections.

Or explore related guides:

    Create the posts that comments attach to
    Notify users of new comments and reactions
    Handle flagged comments and abusive content

---

### [Community Platform](https://learn.social.plus/use-cases/social/community-platform)

> Create public and private communities, manage membership and roles, set up governance rules, and surface trending communities.

```typescript
// 1. Create a community
const { data: community } = await CommunityRepository.createCommunity({
  displayName: 'Gaming Hub', isPublic: true,
  postSetting: CommunityPostSettings.ANYONE_CAN_POST,
});

// 2. Join a community
await CommunityRepository.joinCommunity('communityId');

// 3. Query trending communities
CommunityRepository.getTrendingCommunities(
  { limit: 10 },
  ({ data }) => { /* render */ }
);
```
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.

Communities are the organizational backbone of social apps. This guide walks through the full lifecycle: create a community, grow its membership, set governance rules, and help users discover it.

```mermaid
graph TD
    A[Create Community] --> B{Public or Private?}
    B -->|Public| C[Discoverable via Search & Browse]
    B -->|Private| D[Invitation Only]
    C --> E[Members Join]
    D --> F[Send Invitations]
    F --> E
    E --> G[Post Content]
    G --> H{Moderation Setting}
    H -->|Admin Review| I[Posts Queue for Approval]
    H -->|Anyone Can Post| G
    I --> J[Moderator Approves]
    J --> G
    G --> K[Community Feed]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,G action
    class B,H decision
    class C,D,E,F,I,J process
    class K outcome
```

## Data Model

```mermaid
erDiagram
    COMMUNITY {
        string communityId PK
        string displayName
        boolean isPublic
        string postSetting "ANYONE | ADMIN_REVIEW | ADMIN_ONLY"
        int membersCount
        string[] categoryIds
    }
    CATEGORY {
        string categoryId PK
        string name
    }
    MEMBER {
        string communityId FK
        string userId FK
        string role "member | moderator | admin"
    }
    POST {
        string postId PK
        string communityId FK
        string creatorId FK
        string reviewStatus "published | reviewing | declined"
    }
    COMMUNITY ||--o{ MEMBER : "has members"
    COMMUNITY ||--o{ POST : "contains"
    COMMUNITY }o--o{ CATEGORY : "tagged with"
    MEMBER }o--|| USER : "is a"
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). By default, all authenticated users can create communities.

**After completing this guide you'll have:**
- Community creation flow (public and private) with categories
- Member join/leave and role assignment wired up
- Trending and recommended communities discoverable in-app

---

## Quick Start: Create a Community

Use `AmityCommunityRepository` to create a community with privacy and moderation settings:


Full reference → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community)

---

## Step-by-Step Implementation

    Pick the right `postSettings` for your community type before creating it. This controls the entire content governance model.

    | `postSettings` | Who can post | Best for |
    |---|---|---|
    | `ANYONE_CAN_POST` | All members | Open communities |
    | `ADMIN_REVIEW_POST_REQUIRED` | All members, but posts need approval | Curated communities |
    | `ONLY_ADMIN_CAN_POST` | Admins/moderators only | Announcement channels |

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const { data: community } = await CommunityRepository.createCommunity({
  displayName: 'My Community',
  isPublic: true,
  postSetting: 'ANYONE_CAN_POST',   // or 'ADMIN_REVIEW_POST_REQUIRED'
});
```

    Full reference → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community)
    Categorizing communities improves discoverability. Fetch available categories, then set category IDs on creation.

```typescript TypeScript
import { CategoryRepository } from '@amityco/ts-sdk';

const unsubscriber = CategoryRepository.getCategories(
  {},
  ({ data: categories, loading }) => {
    if (categories) { /* render category picker */ }
  },
);
```

    Full reference → [Community Categories](/social-plus-sdk/social/communities-spaces/organization/community-categories)
    For public communities, join is immediate. For private communities, joining sends a request that moderators can accept or reject.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsub = CommunityRepository.getCommunity(communityId, async (response) => {
  const community = response.data;
  await community.join();
  unsub();
});
```

    Full reference → [Join / Leave Community](/social-plus-sdk/social/communities-spaces/organization/join-leave-community)
    Promote members to moderator or admin, ban members, or remove them from the community.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

await CommunityRepository.Membership.addMembers(communityId, ['userId1', 'userId2']);
```

    Full reference → [Member Management](/social-plus-sdk/social/communities-spaces/organization/member-management)
    For private communities, invite specific users by their user IDs. Invitees receive a notification and can accept or decline.

```typescript TypeScript
// Send invitations to users
await community.createInvitations(['userId1', 'userId2']);
```

    Full reference → [Community Invitation](/social-plus-sdk/social/communities-spaces/organization/community-invitation)
    Query trending and recommended communities for an explore page, or browse by category.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getTrendingCommunities(
  { limit: 5 },
  ({ data: communities, loading }) => {
    if (communities) { /* render trending section */ }
  },
);
```

    Full reference → [Trending & Recommended Communities](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities) · [Query Communities](/social-plus-sdk/social/communities-spaces/discovery/query-communities)

---

## Connect to Moderation & Analytics

  <img src="/images/create-commupublic(1).png" alt="Admin Console — Community management" />

    The Admin Console gives moderators a full view of every community: member lists, post queues (when `ADMIN_REVIEW_POST_REQUIRED` is set), banned users, and community settings.

    → [Admin Console: Social Management](/analytics-and-moderation/console/social-management/README)
    Subscribe to `community.created`, `member.joined`, `member.left`, and `post.flagged` webhook events to sync community state with your own backend or trigger automation.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)
    Subscribe users to community push notifications so they're alerted when new posts are approved or when they're mentioned.

    → [Community Notification Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/community-settings)

---

## Common Mistakes

**Creating communities without setting `postSetting`** — If you omit `postSetting`, the default may prevent regular members from posting. Always specify `ANYONE_CAN_POST` or `ADMIN_REVIEW_POST_REQUIRED` explicitly.

**Joining private communities without handling the pending state** — `joinCommunity` on a private community returns a pending request, not immediate membership. Your UI should show a "Request Sent" state instead of community content.

**Querying communities without `filter`** — Without a filter, `getCommunities` returns all communities including ones the user isn't a member of. Use `filter: 'member'` when building "My Communities" views.

## Best Practices

    - Default new communities to **public** unless your use case requires private — discoverability drives growth
    - Use `ADMIN_REVIEW_POST_REQUIRED` for communities with compliance requirements (e.g., healthcare, finance)
    - Define clear community guidelines and surface them during the join flow
    - Assign at least two moderators per community to avoid single-point-of-failure moderation
    - Cache category lists — they change infrequently
    - Paginate member queries (`queryMembers`) with a reasonable page size (20-50)
    - Use Live Collections for member counts so they update in real-time without manual refresh
    - Show the member count and post count on community cards to signal activity level
    - Surface trending communities on the home screen to drive initial engagement
    - Send an in-app notification when a private community approves a join request

---

**Dive deeper**: [Communities API Reference](/social-plus-sdk/social/communities-spaces/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Roles, Permissions & Governance"
  icon="arrow-right"
  href="/use-cases/social/roles-permissions-and-governance"
>
  Communities are live — now set up moderator roles, post review gating, and ban management.

Or explore related guides:

    Query and render the community feed
    Let community members create posts
    Set up moderation for community content

---

### [User Profiles & Social Graph](https://learn.social.plus/use-cases/social/user-profiles-and-social-graph)

> Build user profiles, follow/unfollow with connection requests, bidirectional blocking, and follower/following lists.

```typescript
// 1. Follow a user
await UserRepository.Relationship.follow('targetUserId');

// 2. Unfollow
await UserRepository.Relationship.unfollow('targetUserId');

// 3. Accept a follow request
await UserRepository.Relationship.acceptMyFollower('requesterId');

// 4. Block a user
await UserRepository.Relationship.blockUser('targetUserId');

// 5. Query followers
UserRepository.Relationship.getFollowers('userId', 'accepted',
  ({ data }) => { /* render */ }
);
```
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.

  <img
    src="/images/use-cases/user-profile-hero.png"
    alt="Three user profile screens: Sarah's Journey wellness profile with streak stats and sleep chart, Alex_Predictor sports profile with prediction accuracy and achievement badges, and Caroline Parker music genre selection onboarding"
  />

A social graph connects your users to each other. This guide covers querying and displaying user profiles, building the follow/unfollow system with pending-request support, and implementing bidirectional blocking.

```mermaid
graph TD
    A[User A] -->|follows| B[User B]
    B -->|accepts request| C[Connected]
    A -->|blocks| D[User C]
    D -.->|content hidden from| A
    C --> E[User A sees User B's posts]
    C --> F[User B sees follower count increase]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,D process
    class C,E,F outcome
```

## Data Model

```mermaid
erDiagram
    USER {
        string userId PK
        string displayName
        string avatarUrl
        object metadata
        int followersCount
        int followingCount
        int flagCount
    }
    FOLLOW_RELATIONSHIP {
        string sourceUserId FK
        string targetUserId FK
        string status "pending | accepted"
    }
    BLOCK {
        string sourceUserId FK
        string targetUserId FK
    }
    USER ||--o{ FOLLOW_RELATIONSHIP : "has followers"
    USER ||--o{ FOLLOW_RELATIONSHIP : "is following"
    USER ||--o{ BLOCK : "blocks"
```

**Prerequisites**: SDK installed and authenticated. You'll need valid `userId` values for the current user and any target users.

**After completing this guide you'll have:**
- User profile display with avatar, bio, and follower/following counts
- Follow, unfollow, and connection-request flows working end-to-end
- Bidirectional blocking implemented with proper feed filtering

---

## Quick Start: Follow a User

Use the relationship API to follow another user:


Full reference → [Follow / Unfollow User](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)

---

## Step-by-Step Implementation

    Query a user's profile to display their name, bio, avatar, and follower/following counts.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUser(userId, ({ data: user, loading }) => {
  if (user) {
    console.log(user.displayName, user.description, user.avatarFileId);
  }
});
```

    Full reference → [Get User Information](/social-plus-sdk/core-concepts/user-management/user-operations/get-user-information)
    For public accounts, following is immediate. For accounts with privacy settings requiring approval, this sends a follow request.


    Full reference → [Follow / Unfollow User](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)

    Full reference → [Follow / Unfollow User](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)
    When a user's account requires approval for follows, incoming requests land in a pending queue. Moderators or the target user can accept or decline.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

const isAccepted = await UserRepository.Relationship.acceptMyFollower('userId');
```

    Full reference → [Accept/Decline Follow Request](/social-plus-sdk/social/user-relationship/following/accept-decline-follow-request)
    Check the relationship between two users before displaying follow/unfollow buttons. Status can be: `none`, `following`, `pending`, or `blocked`.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscriber = UserRepository.Relationship.getFollowInfo(
  'userId',
  ({ data: followInfo }) => {
    console.log('Followers:', followInfo.followerCount);
    console.log('Following:', followInfo.followingCount);
  },
);
```

    Full reference → [Get Connection Status](/social-plus-sdk/social/user-relationship/following/get-connection-status)
    Query paginated lists of a user's followers and the users they follow.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscriber = UserRepository.Relationship.getFollowers(
  { userId: 'my-user-id' },
  ({ data: followers, onNextPage, hasNextPage }) => {
    if (followers) { /* render follower list */ }
  },
);
```

    Full reference → [Get Follower / Following List](/social-plus-sdk/social/user-relationship/following/get-follower-following-list)
    Blocking is bidirectional — neither user can see the other's content or interact with them. You can also read both directions: the users you blocked, and the users who blocked you.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

// Block — handle the per-network block limit
try {
  await UserRepository.Relationship.blockUser('userId');
} catch (error) {
  if (error?.code === Amity.ServerError.MAX_BLOCKED_USERS_REACHED) {
    showBlockedUserLimitReached();
  }
}

// Users the current user blocked
const blocked = await UserRepository.getAllBlockedUsers();

// Users who blocked the current user (reverse direction)
const blocking = await UserRepository.getAllBlockingUsers();
```

    Full reference → [Block / Unblock User](/social-plus-sdk/social/user-relationship/blocking/block-unblock-user), [Manage Blocked Users](/social-plus-sdk/social/user-relationship/blocking/manage-blocked-users), [Users Who Blocked You](/social-plus-sdk/social/user-relationship/blocking/manage-blocking-users)

---

## Connect to Moderation & Analytics

    Users can flag other users for abuse or spam. Flagged users appear in the Admin Console for moderator review.

    → [Flag / Unflag User](/social-plus-sdk/core-concepts/user-management/user-operations/flag-unflag-user) · [Admin Console: User Insights](/analytics-and-moderation/console/user-and-content-management/user-insights)
    View per-user analytics including post count, comment count, and activity history in **Admin Console → User Management → User Insights**.
    Receive `user.followed` and `follow.request.created` webhook events to build notification flows and sync social graph state to your backend.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Not handling the pending follow state** — When a user requires approval, `follow()` creates a pending request — not an immediate follow. Your UI must show "Requested" instead of "Following".

```typescript
// ❌ Bad — assumes instant follow
await UserRepository.Relationship.follow('userId');
setState('following'); // wrong!

// ✅ Good — check the returned status
const { data } = await UserRepository.Relationship.follow('userId');
setState(data.status); // 'accepted' or 'pending'
```

**Blocking without unfollowing first** — Blocking a user does not automatically unfollow them. Call `unfollow` before `blockUser` to fully sever the relationship.

**Querying the full follower list on profile load** — Large accounts can have thousands of followers. Only fetch a count for the profile header, and paginate the full list on demand.

## Best Practices

    - Show follower counts as rounded numbers for large accounts ("1.2K") to avoid gaming dynamics
    - Never expose private account content before a follow request is accepted
    - Let users choose between public and request-based following in their account settings
    - When a user blocks another, immediately hide the blocked user's content from all feeds client-side
    - Show the connection status in a single CTA button: "Follow" → "Requested" → "Following"
    - Display mutual followers ("3 people you follow also follow this account") to drive trust
    - Add empty states for users with 0 followers/following — show suggestions instead of a blank list
    - Cache the current user's following list locally for fast "is following" checks without a network call
    - Paginate follower/following lists — request 30 at a time
    - Observe user Live Objects sparingly — only subscribe when the profile screen is active

---

**Dive deeper**: [User Relationships API Reference](/social-plus-sdk/social/user-relationship/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → User Search & People Discovery"
  icon="arrow-right"
  href="/use-cases/social/user-search-and-people-discovery"
>
  Profiles are live — now let users find each other with search, suggestions, and "People you may know".

Or explore related guides:

    Show posts from followed users in a personalized feed
    Notify users of new followers and follow requests
    Manage member roles within communities

---

### [User Search & People Discovery](https://learn.social.plus/use-cases/social/user-search-and-people-discovery)

> Search users by display name, browse user directories, and build people-discovery features like suggested follows and mutual connections.

```typescript
// Search users by display name only
UserRepository.searchUsers(
  { displayName: 'jane', limit: 20, searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data }) => { renderUsers(data); }
);

```
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.

The existing Search & Discovery guide covers finding posts and communities. This guide focuses on finding *people* — searching users by name, browsing user directories, and building "People you may know" features.

```mermaid
graph TD
    A[User wants to find someone] --> B{Discovery method}
    B -->|Search bar| C[Search by display name]
    B -->|Suggestions| D[People you may know]
    B -->|Browse| E[User directory]
    C --> F[UserRepository.searchUsers]
    D --> G[Mutual followers algorithm]
    E --> H[UserRepository.getUsers]
    F & G & H --> I[User cards with follow button]
    I --> J[User taps follow]
    J --> K[Social graph grows]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,J action
    class B decision
    class C,D,E,F,G,H,I process
    class K outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). Users must have `displayName` set for search to work.

**After completing this guide you'll have:**
- Display-name user search integrated and returning paginated results
- A "People you may know" suggestion list populated from the SDK
- Follow action triggered directly from search results

---

## Quick Start: Search Users by Name

```typescript TypeScript
import { SearchUsersByEnum, UserRepository } from '@amityco/ts-sdk';

const unsub = UserRepository.searchUsers(
  { displayName: 'Joe', searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data: users }) => {
    console.log(users); // Array of matching users
  },
);
```

Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users)

---

## Step-by-Step Implementation

    Use `searchUsers()` to search as the user types. Results are returned as a live collection that updates in real-time. Pass `searchBy` to control which user fields the keyword is matched against; omit it to keep the server default, which matches all searchable fields. `searchUserByDisplayName()` still works but is deprecated.

```typescript TypeScript
import { SearchUsersByEnum, UserRepository } from '@amityco/ts-sdk';

const unsub = UserRepository.searchUsers(
  { displayName: 'Joe', searchBy: [SearchUsersByEnum.DISPLAY_NAME] },
  ({ data: users, loading }) => {
    if (users) { /* render user result cards */ }
  },
);

// Unsubscribe when the search screen closes
unsub();
```

    Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users)
    Query all users with pagination for a "People" directory or admin user list.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUsers(
  {},
  ({ data: users, onNextPage, hasNextPage, loading }) => {
    if (users) { /* render user list */ }
    // Load more: if (hasNextPage) onNextPage?.();
  },
);
```

    Full reference → [Search & Query Users](/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users)
    For each search result, display their avatar, display name, bio, and follower count by querying the user profile.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getUser(userId, ({ data: user }) => {
  if (user) {
    console.log(user.displayName, user.description, user.avatarFileId);
  }
});
```

    Full reference → [Get User Information](/social-plus-sdk/core-concepts/user-management/user-operations/get-user-information)
    Check the connection status and show the right button state: "Follow", "Requested", or "Following".

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscriber = UserRepository.Relationship.getFollowInfo(
  userId,
  ({ data: followInfo }) => {
    console.log('Status:', followInfo.status); // 'none' | 'following' | 'pending'
    console.log('Followers:', followInfo.followerCount);
  },
);
```

    Full reference → [Get Connection Status](/social-plus-sdk/social/user-relationship/following/get-connection-status) · [Follow / Unfollow User](/social-plus-sdk/social/user-relationship/following/follow-unfollow-user)
    Combine multiple signals to suggest relevant connections: mutual followers, shared community membership, and activity patterns.

```typescript TypeScript
// Strategy: Find users in the same communities who aren't followed yet
import { CommunityRepository, UserRepository } from '@amityco/ts-sdk';

// 1. Get the user's communities
const communities = await getUserCommunities(currentUserId);

// 2. Get members from those communities
const members = await getCommunityMembers(communities[0].communityId);

// 3. Filter out users already followed
const suggestions = members.filter(m => !followedUserIds.has(m.userId));
```

---

## Connect to Moderation & Analytics

    Track what users search for in **Admin Console → Analytics → Search Insights**. High-frequency searches with 0 results indicate missing content or users.
    Search results should include a "Report" action. Flagged users appear in the Admin Console moderation queue.

    → [Flag / Unflag User](/social-plus-sdk/core-concepts/user-management/user-operations/flag-unflag-user)
    Visitor and bot users are automatically excluded from search results. Only authenticated (`SIGNED_IN`) users appear in `searchUsers()` results.

---

## Common Mistakes

**Searching with an empty string** — An empty keyword returns no results or throws an error. Disable the search button or show suggestions when the input is empty.

**Not paginating search results** — Popular names can match hundreds of users. Always set a `limit` and implement "Load more" for additional pages.

**Showing stale follow status in search results** — The follow relationship may have changed since the list was fetched. Verify the relationship status when the user opens a profile from search results.

## Best Practices

    - Add a 300ms debounce before firing the search query — prevents excessive API calls while typing
    - Show recent searches and suggested users before the user starts typing
    - Display skeleton placeholders while results load
    - Show "No users found" with a suggestion to try a different name if the query returns 0 results
    - Highlight the matching portion of the display name in results (bold "Joe" in "Joey Smith")
    - Show avatar + display name + short bio (first 50 characters) + follower count
    - Include a single CTA button: "Follow" / "Requested" / "Following" based on connection status
    - Show a verified badge or role badge (e.g., "Moderator") for users with special roles
    - Cache user cards for recently viewed profiles to avoid re-fetching on back navigation
    - Limit search results to 20 items; use pagination for deeper results
    - Unsubscribe the search live collection when the search screen closes
    - For "People you may know", compute suggestions server-side or cache them — don't recompute on every render
    - Pre-fetch connection status for visible users in batch rather than one-by-one

---

**Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → User Profiles & Social Graph"
  icon="arrow-right"
  href="/use-cases/social/user-profiles-and-social-graph"
>
  Users can find each other — now build rich profiles with avatars, bios, and follow connections.

Or explore related guides:

    Build the profile page users navigate to from search
    Search posts and communities alongside users
    Discover users within communities

---

### [Notifications & Engagement](https://learn.social.plus/use-cases/social/notifications-and-engagement)

> Build a notification inbox with seen/unseen state, real-time delivery, push notification setup, and granular event-based triggers.

**TypeScript SDK gap**: `Client.registerPushNotification` is not available in the TypeScript SDK. iOS and Android use native push token registration. In TS/Web, configure push notifications via your web push service (e.g., Firebase Messaging). Tracking: see `.docs-ops/evals/sdk-tickets-to-file.md`.
```typescript
// 1. Get notification tray items
const { data } = await notificationTray.getNotificationTrayItems({ limit: 20 });

// 2. Mark a notification as seen
await notificationTray.markTraySeen('notificationId');

// 3. Register push token
// Push token registration not in TS SDK (see Warning above)
// Configure push via your web push service (e.g., Firebase Messaging)
});

// 4. Subscribe to real-time tray updates
notificationTray.onNotificationTraySeenUpdated(({ data }) => {
  showBadge(data.unseenCount);
});
```
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.

Notifications are your primary re-engagement tool. This guide covers building an in-app notification tray with seen/unseen tracking, setting up push notifications across all platforms, and subscribing to real-time social events.

```mermaid
graph TD
    A[Social activity occurs] --> B{Who triggered it?}
    B -->|Comment on post| C[Post author notified]
    B -->|Reaction on content| D[Content author notified]
    B -->|Mention in comment| E[Mentioned user notified]
    B -->|New follower| F[Followed user notified]
    B -->|Community post| G[Community member notified]
    C & D & E & F & G --> H{Delivery channel}
    H -->|In-app open| I[Notification tray item]
    H -->|App backgrounded| J[Push notification]
    I --> K[User taps → navigates to content]
    J --> K

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,H decision
    class C,D,E,F,G,I,J process
    class K outcome
```

**Prerequisites**: SDK installed and authenticated. For push notifications: APNs certificate (iOS) or FCM credentials (Android) configured in **Admin Console → Settings → Integrations**.

**Also recommended:** Complete [Build a Social Feed](/use-cases/social/build-a-social-feed) and [Community Platform](/use-cases/social/community-platform) first — notifications are triggered by feed and community events.

**After completing this guide you'll have:**
- An in-app notification tray with seen/unseen state and real-time delivery
- Push notifications (APNs and FCM) registered and firing for key events
- Notification triggers mapped to SDK events and webhook callbacks


---

## Quick Start: Query Notification Tray


---

## Part 1: In-App Notification Tray

    Use the tray status to show a badge count on your notification icon. The `unseenCount` updates in real-time.

```typescript
import { notificationTray } from '@amityco/ts-sdk';

const unsubscribe = await notificationTray.getNotificationTraySeen(
  ({ data: notificationTraySeen, loading }) => {
    if (!loading && notificationTraySeen) {
      updateBadge(notificationTraySeen.unseenCount);
    }
  },
);
```

    Full reference → [Notification Tray Status](/social-plus-sdk/social/discovery-engagement/notifications/notification-tray-status)
    When the user opens the tray, mark all unseen items as seen. Or mark individual items as seen on tap. Both bulk and per-item marking are supported.

```typescript
import { notificationTray } from '@amityco/ts-sdk';

// Mark all as seen
await notificationTray.markTraySeen();

// Or mark a single item
await item.markSeen();
```

    Full reference → [Notification Tray Status](/social-plus-sdk/social/discovery-engagement/notifications/notification-tray-status)
    Each notification item contains `targetType` and `targetId` fields you can use to deep-link to the source content (post, comment, user, or community).

    Reference all notification types → [Notification Events Reference](/social-plus-sdk/social/discovery-engagement/notifications/notification-events-reference)

---

## Part 2: Push Notifications

```mermaid
sequenceDiagram
    participant Device as User's Device
    participant SDK
    participant Server as social.plus Server
    participant APNs as APNs / FCM

    Device->>SDK: registerPushNotification(token)
    SDK->>Server: Register device token
    Server-->>SDK: Registered

    Note over Server: Another user comments on the post
    Server->>Server: Generate notification
    alt App in foreground
        Server->>SDK: Real-time event
        SDK->>Device: In-app notification tray item
    else App in background
        Server->>APNs: Push payload
        APNs->>Device: System push notification
        Device->>SDK: User taps → deep link to content
    end
```

    Before registering devices, add your push credentials in **Admin Console → Settings → Push Notifications**:
    - **iOS**: Upload your APNs certificate or key
    - **Android**: Add your FCM Server Key
    - **React Native / Flutter**: Configure per platform

    → Platform setup guides: [iOS](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/ios-setup) · [Android](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/android-setup) · [React Native](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/react-native-setup) · [Flutter](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/setup/flutter-setup)
    After the user logs in, retrieve the device token and register it with the SDK. This associates the device with the authenticated user so the backend can route pushes correctly.

```typescript
import { Client } from '@amityco/ts-sdk';

// Register a device token (web push or React Native FCM token)
await client.registerPushNotification({ token: deviceToken });
```

    Full reference → [Register Push Notifications](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device)
    Always unregister the device token when the user logs out to prevent push notifications being sent to the wrong user's device.

```typescript
// Unregister on logout — stops push notifications to this device
await client.unregisterPushNotification({ token: deviceToken });
```

    Full reference → [Register Push Notifications](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device)

---

## Part 3: User Notification Preferences

Let users control what they're notified about at a granular level. Settings are organised by module (`SOCIAL`, `CHAT`, `LIVE_STREAM`) and apply across all of the user's devices.

    Read the user's current preferences to populate a settings screen.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

// Notification settings API: see push-notification docs for v6 SDK approach
console.log('Notifications enabled:', settings.isEnabled);
settings.modules.forEach(m => console.log(m.moduleType, m.isEnabled));
```
    Enable or disable individual modules, or turn off all notifications at once.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

// Disable social, keep chat enabled
// Notification settings update: see push-notification docs for v6 SDK approach
// await legacySettingsUpdate({
  modules: [
    { moduleType: 'social', isEnabled: false },
    { moduleType: 'chat',   isEnabled: true },
  ],
});

// Or disable all notifications at once
// Notification settings update: see push-notification docs for v6 SDK approach
// await legacySettingsUpdate({ isEnabled: false });
```

    Full reference → [User Notification Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/user-settings)
    For finer control, users can configure which notification types they receive per community (new post, new comment, mentions). This is separate from the global user setting above.

    Full reference → [Community Notification Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/community-settings)

---

## Connect to Moderation & Analytics

  <img src="/images/console-push-notifications-overview.png" alt="Admin Console — Push notification settings" />

    When a moderator removes content, use webhook events (`post.deleted`, `user.banned`) to send a custom in-app or push notification explaining the action to the affected user.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)
    Track notification open rates and click-through rates in **Admin Console → Analytics Dashboard → Engagement Metrics** to understand which notification types drive the most re-engagement.

---

## Common Mistakes

**Polling for notifications on a timer** — This drains battery and creates unnecessary API calls. Use real-time tray subscriptions instead:

```typescript
// ❌ Bad — polling every 5 seconds
setInterval(() => fetchNotifications(), 5000);

// ✅ Good — real-time tray subscription
notificationTray.onNotificationTraySeenUpdated(({ data }) => {
  updateBadge(data.unseenCount);
});
```

**Not handling push permission rejection** — On iOS, users can deny push permissions. Always check the permission status and provide an in-app fallback (notification tray) when push is disabled.

**Registering push tokens before login** — Push token registration requires an active session. Always call `registerPushNotification` after `login()` completes, not in parallel.

## Best Practices

    - Group related notifications (e.g., "5 reactions on your post") instead of showing individual items
    - Show a relative timestamp ("2 min ago") that updates while the tray is open
    - Mark all as seen when the tray is closed, not opened — allows the user to scan without losing unseen state
    - Include a thumbnail of the content the notification relates to
    - Keep push payloads minimal — fetch full content on tap, not in the payload
    - Include `userId` in the notification payload to support multi-account scenarios
    - Group pushes by thread on iOS using `threadIdentifier`
    - Respect iOS Critical Alert restrictions — social notifications should never be critical
    - Default to email digest for low-activity users rather than per-event push
    - Respect platform quiet hours (iOS Focus mode, Android DND)
    - Provide granular opt-out: users should be able to mute a specific community without turning off all notifications
    - Rate-limit push if a post gets hundreds of reactions — send "50+ reactions on your post" not one push per reaction

---

**Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Content Moderation Pipeline"
  icon="arrow-right"
  href="/use-cases/social/content-moderation-pipeline"
>
  Notifications are flowing — now ensure content quality with flagging, AI moderation, and admin review.

Or explore related guides:

    Follow activity that drives notification events
    Engagement events that trigger notification items
    Use webhooks to notify users of moderation actions

---

### [Stories & Ephemeral Content](https://learn.social.plus/use-cases/social/stories-and-ephemeral-content)

> Add image and video stories with story rings, view counts, impression analytics, and per-user or per-community targeting.

```typescript
// 1. Create an image story
await StoryRepository.createImageStory({
  targetType: 'community', targetId: 'communityId',
  imageFileId: 'uploaded-image-id',
});

// 2. Create a video story
await StoryRepository.createVideoStory({
  targetType: 'community', targetId: 'communityId',
  videoFileId: 'uploaded-video-id',
});

// 3. Query active stories
StoryRepository.getActiveStoriesByTarget('communityId',
  ({ data }) => { /* render story ring */ }
);

// 4. Mark as seen — use storyItem.analytics.markAsSeen() via getActiveStoriesByTarget
StoryRepository.getActiveStoriesByTarget(
  { targetType: 'community', targetId: 'communityId' },
  ({ data: storiesData }) => {
    storiesData?.forEach(storyItem => storyItem?.analytics.markAsSeen());
  },
);
```
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.

  <img
    src="/images/use-cases/stories-hero-ring-bar.png"
    alt="Three story experiences: full-screen sports story with community badge, fitness app clips feed with trending categories, and fashion brand story with close button"
  />


Stories are 24-hour ephemeral content units that drive daily active usage. This guide covers creating image and video stories, rendering story rings, tracking views and impressions, and targeting stories to users or communities.

```mermaid
graph TD
    A[User creates story] --> B{Story type}
    B -->|Image| C[Upload image]
    B -->|Video| D[Upload video]
    C & D --> E[Story published]
    E --> F{Target}
    F -->|User profile| G[User story ring]
    F -->|Community| H[Community story ring]
    G & H --> I[Other users view story]
    I --> J[Impression tracked]
    J --> K[Story expires in 24h]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,F decision
    class C,D,E,G,H,I,J process
    class K outcome
```

**Prerequisites**: SDK installed and authenticated. For video stories: video upload configured → [Video Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/video-handling). You'll need a `targetType` (`user` or `community`) and `targetId`.

**Also recommended:** Complete [User Profiles & Social Graph](/use-cases/social/user-profiles-and-social-graph) — stories target user profiles and communities.

**After completing this guide you'll have:**
- Image and video story creation targeting communities and user profiles
- Story ring display with viewed/unviewed state on avatars
- Per-story view count and impression data accessible

## Limits at a Glance

| Property | Limit |
|---|---|
| Story lifespan | 24 hours (auto-deleted) |
| Max image size | 1 GB |
| Max video size | 1 GB |
| Max video duration | 2 minutes |
| Target types | `user` or `community` |
| Hyperlinks per story | 1 |
| Story types | `image` or `video` |


---

## Quick Start: Create an Image Story


---

## Step-by-Step Implementation

    Story targets are the entities (users or communities) that have active stories. Each target has a `hasUnseenStory` flag you can use to highlight the ring.

```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getStoriesByTargetIds(
  {
    targets: [
      { targetType: 'community', targetId: 'communityId_1' },
      { targetType: 'community', targetId: 'communityId_2' },
    ],
    options: { orderBy: 'asc' },
  },
  ({ data: storiesData, loading }) => {
    if (storiesData) { /* render story rings */ }
  },
);
```

    Full reference → [Get Story Targets](/social-plus-sdk/social/content-management/stories/retrieval/get-story-targets)
    For an explore page, query all communities with active stories.

```typescript TypeScript
import { StoryRepository } from '@amityco/ts-sdk';

const unsubscribe = StoryRepository.getGlobalStoryTargets(
  { seenState: Amity.StorySeenQuery.SMART, limit: 10 },
  ({ data, onNextPage, hasNextPage }) => {
    /* render explore story bar */
  },
);
```

    Full reference → [Get Global Story Targets](/social-plus-sdk/social/content-management/stories/retrieval/get-global-story-targets)
    Query individual stories for a specific user or community to display in the full-screen viewer.

```typescript TypeScript
const unsubscribe = StoryRepository.getActiveStoriesByTarget(
  { targetType: 'community', targetId: 'communityId' },
  ({ data: stories, loading }) => {
    if (stories) { /* open full-screen story viewer */ }
  },
);
```

    Full reference → [Get Stories](/social-plus-sdk/social/content-management/stories/retrieval/get-stories)
    When a story is shown full-screen, call `markAsSeen()` to record the view impression. View analytics in **Admin Console → Social Management → Stories**.

```typescript TypeScript
// Inside the story viewer callback:
storiesData.forEach(storyItem => {
  if (storyItem) storyItem.analytics.markAsSeen();
});
```

    Full reference → [Story Impressions](/social-plus-sdk/social/content-management/stories/analytics/story-impressions)
    Stories support the same reaction system as posts. Use `ReactionRepository` with `referenceType: 'story'` and the story ID.

```typescript TypeScript
import { ReactionRepository } from '@amityco/ts-sdk';

// Add a reaction to a story
await ReactionRepository.addReaction('story', 'storyId', 'like');

// Remove a reaction
await ReactionRepository.removeReaction('story', 'storyId', 'like');
```

    Full reference → [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)

---

## Connect to Moderation & Analytics

    View total views, unique viewers, and per-story impression data in **Admin Console → Social Management → Stories**. Programmatic access via `story.impressions` in the SDK.

    → [Story Impressions](/social-plus-sdk/social/content-management/stories/analytics/story-impressions)
    Users can flag inappropriate stories. Flagged stories appear in the Admin Console for moderator action.

    → [Content Flagging](/social-plus-sdk/social/content-management/moderation/content-flagging)
    Per-community story settings control whether comments are allowed on community stories. Configure in the Admin Console or via the SDK when creating/updating a community.

    → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community)

---

## Common Mistakes

**Uploading full-resolution images without compression** — Stories are short-lived content. Uploading 4K images wastes bandwidth and slows story rings. Compress to ~1080p before uploading.

**Not checking story expiration client-side** — The API returns active stories, but network delays can cause a story to expire between fetch and render. Always check `story.expiresAt` before displaying.

**Polling for new stories instead of subscribing** — Stories update frequently. Use Live Collections to observe story changes instead of polling on a timer, which wastes battery and bandwidth.

## Best Practices

    - Use a colored ring for unseen stories, a grey/transparent ring for fully seen stories
    - Order story rings: currently-active user's story → friends → communities
    - Show a "+" button on the current user's ring to open the creation flow
    - Animate the ring on tap to give tactile feedback before opening the viewer
    - Auto-advance to the next story after ~5-7 seconds for images, or at video end
    - Allow tap-left / tap-right to navigate between stories
    - Show a progress bar across the top of the viewer for each story segment
    - Pause auto-advance when the user long-presses (hold to read)
    - Pre-fetch stories for the first 3 targets in the story ring so they open instantly
    - Compress images to ≤1MB before upload — story images are full-screen and load time matters
    - For video stories, start downloading the next story's video while the current one plays

---

**Dive deeper**: [Stories API Reference](/social-plus-sdk/social/content-management/stories/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Notifications & Engagement"
  icon="arrow-right"
  href="/use-cases/social/notifications-and-engagement"
>
  Stories are live — now set up push notifications so followers know when new stories are posted.

Or explore related guides:

    Create posts alongside stories for a complete content loop
    Notify users when someone reacts to their story
    Combine a story bar at the top of the feed

---

### [Short-Form Video Clips](https://learn.social.plus/use-cases/social/short-form-video-clips)

> Build a TikTok-style clip feed — upload videos, create clip posts, display a scrollable clip reel, and track engagement.

```typescript
// 1. Upload a video file
const { data: file } = await FileRepository.uploadVideo(videoBlob);

// 2. Create a clip post
await PostRepository.createClipPost({
  targetType: 'community', targetId: 'communityId',
  videoFileId: file.fileId,
  thumbnailFileId: 'thumbnail-id', // optional
});

// 3. Query clip posts in a feed
PostRepository.getPosts(
  { targetType: 'community', targetId: 'communityId', dataTypes: ['video'] },
  ({ data }) => { renderClipReel(data); }
);
```
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.

Clip posts let users share videos up to 15 minutes directly in community and user feeds. They are distinct from livestream posts (live broadcast) and regular video posts — they're purpose-built for short-form, scrollable video content with full reactions, comments, and impression tracking. This guide walks through uploading a clip, publishing it to a feed, and displaying a clip reel.

```mermaid
graph TD
    A[User picks a video] --> B[Upload to File Repository]
    B --> C{Upload status}
    C -->|transcoding| D[Show progress indicator]
    C -->|transcoded| E[fileId ready]
    E --> F[Create clip post]
    F --> G[Post appears in feed]
    G --> H[Viewer scrolls past clip]
    H --> I[markAsViewed called]
    I --> J[Impression + reach count updated]
    G --> K[Viewer reacts / comments]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,H,K action
    class C decision
    class B,D,E,F,I process
    class G,J outcome
```

## Limits at a Glance

| Property | Limit |
|---|---|
| Max file size | 2 GB |
| Max duration | 15 minutes |
| Supported formats | 3gp, avi, f4v, flv, m4v, mov, mp4, ogv, 3g2, wmv, vob, webm, mkv |
| Caption length | 10,000 characters |

**After completing this guide you'll have:**
- Clip post upload flow (video up to 15 min) with progress tracking
- Auto-play clip reel rendering in the feed with proper display mode
- Impression tracking firing when clips are visible on screen

---

## Quick Start: Create a Clip Post

```typescript TypeScript
import { PostRepository, PostContentType } from '@amityco/ts-sdk';

try {
  const { data: post } = await PostRepository.createClipPost({
    data: { text: 'Check out this moment!' },
    attachments: [
      { fileId: 'videoFileId1', type: PostContentType.CLIP, displayMode: 'fill', isMuted: false },
    ],
    targetType: 'community',
    targetId: 'communityId1',
  });
} catch (error) {
  console.error('Failed to create clip post:', error);
}
```

Full reference → [Clip Posts](/social-plus-sdk/social/content-management/posts/creation/clip-post)

---

## Step-by-Step Implementation

    Upload the raw video file before creating the post. The SDK returns a `fileId` once the upload is complete. Transcoding then happens automatically in the background.

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

// uploadFile accepts a File (web) or file path (native)
const { data: uploadedFile } = await FileRepository.uploadVideo(videoFile, {
  onProgress: (progress) => console.log(`Upload: ${progress}%`),
});

const fileId = uploadedFile.fileId;
```

    Full reference → [Video Handling](/social-plus-sdk/core-concepts/content-handling/files-images-and-videos/video-handling)
    Pass the `fileId` as an attachment. Set `displayMode` to `'fill'` for vertical reels (TikTok-style) or `'fit'` to letterbox horizontal video.

```typescript TypeScript
import { PostRepository, PostContentType } from '@amityco/ts-sdk';

const { data: post } = await PostRepository.createClipPost({
  data: { text: 'Behind the scenes 🎬' },
  attachments: [
    {
      fileId,
      type: PostContentType.CLIP,
      displayMode: 'fill',   // 'fill' crops to container; 'fit' letterboxes
      isMuted: false,         // start unmuted
    },
  ],
  targetType: 'community',   // 'community' or 'user'
  targetId: communityId,
});
```

    Full reference → [Clip Posts](/social-plus-sdk/social/content-management/posts/creation/clip-post)
    Query clip posts for a community or user feed. Filter by `PostContentType.CLIP` to build a dedicated clips tab. Render each post as a full-screen vertical video card.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

const unsubscribe = PostRepository.getPosts(
  {
    targetType: 'community',
    targetId: communityId,
    dataTypes: ['clip'],   // filter to clips only
    limit: 10,
  },
  ({ data: posts, hasNextPage, onNextPage }) => {
    renderClipReel(posts);
    // loadMoreButton.onClick = onNextPage when hasNextPage is true
  },
);
```

    Full reference → [Query Posts](/social-plus-sdk/social/content-management/posts/retrieval/query-posts)
    Call `markAsViewed()` when a clip is at least 50% visible for 1 second. This updates the post's `impression` (total views) and `reach` (unique viewers) counters.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

// Called from your IntersectionObserver / viewability tracker
function onClipVisible(post: Amity.Post) {
  post.analytics.markAsViewed();
  console.log(`Impressions: ${post.impression}, Reach: ${post.reach}`);
}
```

    Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Clip posts support the same reactions and comments as any other post type — no additional setup required.

```typescript TypeScript
import { ReactionRepository } from '@amityco/ts-sdk';

// Add a heart reaction to a clip post
await ReactionRepository.addReaction('post', post.postId, 'heart');
```

    Full reference → [Reactions](/social-plus-sdk/core-concepts/content-handling/reactions)

---

## Connect to Moderation & Analytics

    Impression and reach data rolls up to **Admin Console → Analytics → Content**. Filter by post type to see clip-specific engagement trends across communities.
    Users can flag clip posts with the same SDK flagging APIs used for other content. Flagged clips surface in **Admin Console → Moderation → Flagged Content**.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';
await PostRepository.flagPost(post.postId);
```

    Full reference → [Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline)
    Receive `post.created` and `post.deleted` webhook events filtered to `dataType: 'clip'` to trigger downstream workflows like CDN pre-warming or notification dispatch.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Uploading uncompressed video** — Raw video files can be hundreds of megabytes. Always compress to H.264/MP4 at a reasonable bitrate (2–5 Mbps for 1080p) before uploading.

**Skipping thumbnail generation** — Without a `thumbnailFileId`, clip posts render with a blank placeholder in feeds. Extract a frame from the video and upload it as the thumbnail.

**Auto-playing clips with audio** — Auto-playing with sound is disruptive and violates platform guidelines (iOS/Android). Start clips muted and let users tap for audio.

## Best Practices

    - Show a progress bar during upload — clip files can be up to 2 GB
    - After upload completes, poll the file's `status` field until it reaches `transcoded` before publishing the post. Show a "Processing…" state in the meantime
    - Validate file size and duration on the client before uploading to give instant feedback
    - Auto-play clips when they scroll into view; pause immediately on scroll away
    - Default to `isMuted: true` for autoplay in feeds to comply with browser autoplay policies
    - Show a tap-to-unmute affordance visibly on the first clip
    - Use `displayMode: 'fill'` for portrait clips and `'fit'` for landscape
    - Pre-load the next clip in the reel while the current one is playing to eliminate inter-clip buffer
    - Use the `720p` transcoded URL for mobile playback — the original resolution is usually excessive
    - Pause and release memory for clips that are more than 2 positions away from the current view

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Post Impressions & Creator Analytics"
  icon="arrow-right"
  href="/use-cases/social/post-impressions-and-creator-analytics"
>
  Clips are publishing — now track views, reach, and engagement for your creators.

Or explore related guides:

    Build a creator dashboard with per-post impression, reach, and viewed-users data
    Other post types — images, text, polls, files — in one guide
    Add threaded comments and emoji reactions to clip posts

---

### [Polls & Interactive Content](https://learn.social.plus/use-cases/social/polls-and-interactive-content)

> Add polls to community feeds — create single or multiple-choice votes with expiry timers, let users vote and change their minds, and close polls manually.

```typescript
import { PollRepository, PostRepository } from '@amityco/ts-sdk';

// 1. Create a poll
const { data: poll } = await PollRepository.createPoll({
  question: 'Favorite color?', answerType: 'single',
  answers: [{ dataType: 'text', data: 'Red' }, { dataType: 'text', data: 'Blue' }],
});

// 2. Wrap it in a post
const { data: post } = await PostRepository.createPost({
  targetType: 'community',
  targetId: communityId,
  data: { text: 'Vote now! 👇', pollId: poll.pollId },
});

// 3. Vote
await PollRepository.votePoll(poll.pollId, ['answerId-1']);

// 4. Close the poll
await PollRepository.closePoll(poll.pollId);
```
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.

  <img
    src="/images/use-cases/polls-hero-in-feed.png"
    alt="Two poll screens: dark-themed Studio Polls page with active polls count, vote percentages, and expiry timer; light-themed product poll asking 'Which color should we stock next?' with percentage bars and vote counts"
  />

Polls are one of the highest-engagement content types in social apps. social.plus provides a full poll lifecycle: create the poll, wrap it in a feed post, let users vote (and change their vote), and close or delete when done. All four platforms are supported — iOS, Android, TypeScript, and Flutter.

```mermaid
graph TD
    A[Decide poll question + options] --> B[Create poll via PollRepository]
    B --> C[pollId returned]
    C --> D[Create poll post via PostRepository]
    D --> E[Post appears in community feed]
    E --> F{User action}
    F -->|vote| G[PollRepository.votePoll]
    F -->|change mind| H[PollRepository.unvotePoll]
    G --> I[Real-time vote counts update]
    H --> I
    I --> J{Poll owner}
    J -->|manual close| K[PollRepository.closePoll]
    J -->|timer expires| K
    K --> L[Poll locked — results final]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class F,J decision
    class B,C,D,G,H,K process
    class E,I,L outcome
```

Polls are always published as part of a post — there are no standalone polls in the current SDK. The two-step flow (create poll → create post) is by design so polls appear in feeds like any other content.

**Image polls**: Poll answers can include images instead of text — useful for "Which design do you prefer?" or "Which product looks better?" questions. Set `answer.dataType: 'image'` and provide a `fileId` (upload the image first) for each visual option. See [Poll Posts](/social-plus-sdk/social/content-management/posts/creation/poll-post) for the full answer object structure.

**After completing this guide you'll have:**
- Poll creation embedded inside a feed post (single and multiple choice)
- Voting, vote-change, and poll-close flows implemented
- Vote counts updating in real-time in your feed

## Limits at a Glance

| Property | Limit |
|---|---|
| Max poll options | 10 |
| Min poll options | 2 |
| Answer types | `single` or `multiple` |
| Answer data types | `text` or `image` |
| Question length | 500 characters |
| Poll closure | Manual close or auto-expire via `closedIn` |
| Vote changes | Allowed until poll closes |

---

## Quick Start: Create a Poll and Publish It

```typescript TypeScript
import { PollRepository, PostRepository } from '@amityco/ts-sdk';

try {
  // Step 1: Create the poll
  const { data: poll } = await PollRepository.createPoll({
    question: 'What feature should we build next?',
    answerType: 'single',
    answers: [
      { dataType: 'text', data: 'Dark mode' },
      { dataType: 'text', data: 'Offline support' },
      { dataType: 'text', data: 'Video reactions' },
    ],
  });

  // Step 2: Publish as a community post
  const { data: post } = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    data: { text: 'Help us prioritise our roadmap! 👇', pollId: poll.pollId },
  });
} catch (error) {
  console.error('Failed to create poll post:', error);
}
```

Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll) · [Poll Posts](/social-plus-sdk/social/content-management/posts/creation/poll-post)

---

## Step-by-Step Implementation

    Create the poll object first. Choose `'single'` for one answer or `'multiple'` for multi-select. Set `timeToClosePoll` in milliseconds — omit it for a poll that stays open until you manually close it.

```typescript TypeScript
import { PollRepository } from '@amityco/ts-sdk';

const { data: poll } = await PollRepository.createPoll({
  question: 'Which platform are you building on?',
  answerType: 'single',   // or 'multiple' for multi-select
  answers: [
    { dataType: 'text', data: 'iOS' },
    { dataType: 'text', data: 'Android' },
    { dataType: 'text', data: 'Web' },
    { dataType: 'text', data: 'Flutter' },
  ],
  // Optional: close automatically after 24 hours
  // timeToClosePoll: 24 * 60 * 60 * 1000,
});

const pollId = poll.pollId;
```

    Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll)
    Create a poll post with the `pollId`. Add context text as the post caption — this is what users see before expanding the poll.

```typescript TypeScript
import { PostRepository } from '@amityco/ts-sdk';

const { data: post } = await PostRepository.createPost({
  targetType: 'community',
  targetId: communityId,
  data: { text: 'Vote now! 👇', pollId: pollId },
});
```

    Full reference → [Poll Posts](/social-plus-sdk/social/content-management/posts/creation/poll-post)
    Pass the poll ID and an array of answer IDs. For `single` polls, the array will have one item. For `multiple`, users can select up to all options.

```typescript TypeScript
import { PollRepository } from '@amityco/ts-sdk';

// Cast the vote
const { data: updatedPoll } = await PollRepository.votePoll(
  poll.pollId,
  [selectedAnswerId]   // array of answer IDs
);

// Show updated vote counts immediately
updatedPoll.answers.forEach(answer => {
  console.log(`${answer.data}: ${answer.voteCount} votes`);
});
```

    Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll)
    Users can unvote and re-vote as long as the poll is still open. Call `unvotePoll` first, then `votePoll` with the new selection.

```typescript TypeScript
import { PollRepository } from '@amityco/ts-sdk';

// Remove existing vote
await PollRepository.unvotePoll(poll.pollId);

// Cast a new vote
await PollRepository.votePoll(poll.pollId, [newAnswerId]);
```

    Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll)
    Poll owners and admins can close a poll early — for example, after a timed announcement. Once closed, no new votes are accepted and results are final.

```typescript TypeScript
import { PollRepository } from '@amityco/ts-sdk';

const { data: closedPoll } = await PollRepository.closePoll(poll.pollId);

// closedPoll.isVotable === false — show results, hide vote button
if (!closedPoll.isVotable) {
  showFinalResults(closedPoll);
}
```

    Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll)
    Permanently removes the poll and all vote data. Only the poll creator or an admin can delete. The associated post should also be deleted separately.

```typescript TypeScript
import { PollRepository } from '@amityco/ts-sdk';

const isDeleted = await PollRepository.deletePoll(poll.pollId);
```

    Full reference → [Polls](/social-plus-sdk/core-concepts/content-handling/poll)

---

## Rendering Poll Results

Use the poll's `answers` array to render a visual results bar. Show current vote percentages while the poll is open, and pin the winner after it closes.

```typescript TypeScript
function renderPollResults(poll: Amity.Poll) {
  const totalVotes = poll.answers.reduce((sum, a) => sum + a.voteCount, 0);

  return poll.answers.map(answer => ({
    text: answer.data,
    votes: answer.voteCount,
    percentage: totalVotes > 0 ? Math.round((answer.voteCount / totalVotes) * 100) : 0,
    isSelected: answer.isVoted,   // true if current user voted for this option
  }));
}
```

---

## Connect to Moderation & Analytics

    Use the pin-post API to pin a poll post to the top of a community feed during active voting.

    → [Pin Post](/social-plus-sdk/social/content-management/posts/moderation/pin-post)
    Poll posts can be flagged by users and reviewed in **Admin Console → Moderation → Flagged Content** like any other post type.
    Receive `post.created` and `post.updated` events for poll posts to trigger downstream actions like push notifications to community members when a new poll is published.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Creating a poll with fewer than 2 answers** — The API requires at least 2 answer options. Validate your form before calling `createPoll`.

**Forgetting to close polls** — Polls without a `closedAt` date stay open forever. If your poll is time-bound, either set `closedAt` at creation or call `closePoll` explicitly when the window ends.

**Displaying results before the user votes** — Showing percentages before voting biases choices. Hide results until the current user has voted or the poll is closed.

## Best Practices

    - Keep questions under 100 characters — readable at a glance in a feed card
    - Provide 2–5 options for most polls; more than 6 reduces completion rates
    - Avoid vague options like "Option A" — every answer should be self-explanatory without reading the question
    - Use `'multiple'` answer type for taste/preference questions, `'single'` for factual or decision polls
    - Check `poll.isVotable` before showing the vote button — hide it entirely when `false`
    - Highlight the winning option (most votes) with a distinct visual treatment after close
    - Show the total vote count prominently — social proof drives engagement on future polls
    - Keep the poll post visible in the feed after closing; don't delete it just because voting has ended
    - Subscribe to the post live object to receive vote count updates without manual refresh
    - Animate the percentage bar as it changes — a smooth transition feels more alive than a jump
    - Debounce vote button presses to prevent accidental double-votes

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Comments & Reactions"
  icon="arrow-right"
  href="/use-cases/social/comments-and-reactions"
>
  Polls are interactive — now add comments and reactions so users can discuss the results.

Or explore related guides:

    Polls alongside all other post types in one guide
    Publish polls to community feeds with pinning support
    Notify members when a new poll is published

---

### [Events & Activities](https://learn.social.plus/use-cases/social/events-and-activities)

> Create structured events with RSVP, attendance tracking, event discovery, and calendar integration.

```typescript
// 1. Create an event
const { data: event } = await EventRepository.createEvent({
  title: 'Community Meetup', description: 'Monthly gathering',
  startDate: '2026-04-01T18:00:00Z', endDate: '2026-04-01T20:00:00Z',
  targetType: 'community', targetId: 'communityId',
});

// 2. RSVP — called on the event linked object
const rsvp = await event.createRSVP(AmityEventResponseStatus.Going);

// 3. Query upcoming events
EventRepository.getEvents({ status: 'upcoming', limit: 10 },
  ({ data }) => { /* render */ }
);
```
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.

Events give communities and users a way to organize real-world and virtual activities. social.plus supports three event types — **livestream**, **external link** (virtual), and **in-person** — each with RSVP tracking, attendee lists, and push notification reminders.

    Go live directly within the app — attendees watch and chat in real time.
    Redirect attendees to Zoom, Google Meet, or any external URL.
    Physical gatherings with an address field and map support.

This guide covers creating events, managing RSVPs, querying attendees, admin console management, and building an event discovery experience.

```mermaid
graph TD
    A[User creates event] --> B[Event published to community]
    B --> C[Members see event in feed or calendar]
    C --> D{Member response}
    D -->|Going| E[RSVP: going]
    D -->|Not going| F[RSVP: not_going]
    D -->|Interested| G[RSVP: interested]
    E & G --> H[Attendee list grows]
    H --> I[Event creator sees attendance stats]
    B --> J[Push notification to community members]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class D decision
    class B,C,E,F,G,J process
    class H,I outcome
```

**Prerequisites**: SDK installed and authenticated. A `communityId` is required — events are always attached to a community.

**Also recommended:** Complete [Community Platform](/use-cases/social/community-platform) first — events live inside communities.

**After completing this guide you'll have:**
- Event creation with title, description, date/time, and location
- RSVP (going / not going) flow with attendee list
- Events discoverable in community feeds and a dedicated events list


---

## Quick Start: Create an Event


---

## Step-by-Step Implementation

    Query events for a specific community, filtered by status and sort order. Results are returned as a live collection.

```typescript TypeScript
import { EventRepository, AmityEventOriginType, AmityEventSortOption, AmityEventOrderOption } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvents(
  {
    originType: AmityEventOriginType.Community,
    originId: 'community-123',
    sortBy: AmityEventSortOption.StartTime,
    orderBy: AmityEventOrderOption.Ascending,
  },
  ({ data: events, loading }) => {
    if (events) {
      events.forEach(event => console.log(event.title, event.startTime));
    }
  },
);
```

    Full reference → [Manage Events](/social-plus-sdk/social/events/manage-events)
    Let users respond with `going`, `not_going`, or `interested`. Users can change their RSVP at any time before the event starts.

```typescript TypeScript
import { EventRepository, AmityEventResponseStatus } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent(
  'event-123',
  async ({ data: event }) => {
    if (event) {
      const rsvp = await event.createRSVP(AmityEventResponseStatus.Going);
      console.log('RSVP:', rsvp?.status);
    }
  },
);
```

    Full reference → [Event RSVP](/social-plus-sdk/social/events/event-rsvp)
    Query the list of attendees filtered by RSVP status. Use this to show who's going, display an attendee count, or build an attendee list screen.

```typescript TypeScript
import { EventRepository, AmityEventResponseStatus } from '@amityco/ts-sdk';

const unsubscribe = EventRepository.getEvent('event-123', ({ data: event }) => {
  if (event) {
    event.getRSVPs(
      { status: AmityEventResponseStatus.Going },
      ({ data: responses }) => {
        if (responses) {
          responses.forEach(rsvp => console.log('Attendee:', rsvp.user?.displayName));
        }
      },
    );
  }
});
```

    Full reference → [Event RSVP](/social-plus-sdk/social/events/event-rsvp)
    Event creators and community moderators can update event details (title, description, time, location) or delete events entirely.

```typescript TypeScript
import { EventRepository } from '@amityco/ts-sdk';

// Update an event
const { data: updated } = await EventRepository.updateEvent('event-123', {
  title: 'Updated Event Title',
  description: 'New details for the event',
  startTime: '2025-04-20T15:00:00Z',
});

// Delete an event
await EventRepository.deleteEvent('event-123');
```

    Full reference → [Manage Events](/social-plus-sdk/social/events/manage-events)

---

## Admin Console: Manage & Monitor Events

Admins can create, view, and manage all events across communities from **Admin Console → Events**.

### Events Dashboard

  <img
    src="/images/analytics-and-moderation/console-events-management.png"
    alt="Admin Console events management table showing event titles, types, communities, creators, dates, and status"
  />

The dashboard shows all events at a glance with filtering by **creator** and **status** (Upcoming, Ongoing, Ended). Columns include event title, type, community, creator, start/end dates, status, and attendee count.

### Create Events from Console

Click **Create event** to build events directly from the console — useful for official community events or marketing campaigns.

  <img
    src="/images/analytics-and-moderation/console-events-create.png"
    alt="Admin Console create event form with community selector, event name, thumbnail upload, and scheduling fields"
  />

The creation form covers:
- **Feed & account** — target community and creator identity
- **Event details** — name (60 chars), description (1,000 chars), optional 16:9 thumbnail
- **Schedule** — timezone-aware start and end date/time pickers
- **Event type** — Livestream, External Link (URL), or In-Person (address)

### Event Detail View

Click any event to see its detail page with three tabs:

  <img
    src="/images/analytics-and-moderation/console-events-detail.png"
    alt="Admin Console event detail page with Activities tab showing post count and status badges"
  />

| Tab | What it shows |
|---|---|
| **Activities** | Posts and engagement tied to the event |
| **Attendees** | Users who RSVP'd — going, interested, not going |
| **Details** | Full event config (community, schedule, type, address/link) — editable |

  <img
    src="/images/analytics-and-moderation/console-events-detail-tab.png"
    alt="Admin Console event detail Details tab showing community, name, thumbnail, timezone, dates, and event type fields"
  />

### Push Notification Configuration

Enable event-related push notifications in **Admin Console → Settings → Push notifications → Community event**.

  <img
    src="/images/console-push-notifications-community-events.png"
    alt="Admin Console push notification settings for community events showing toggles for post, reaction, approval, and review notifications"
  />

    Receive `event.created`, `event.updated`, `event.rsvp.created`, and `event.rsvp.updated` webhook events to sync attendance data with an external calendar system, CRM, or trigger reminder emails.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)
    Use webhooks to send reminder push notifications to RSVP'd attendees before an event starts. Trigger this from your backend when `event.startAt - 24h` is reached.

    → [Notifications guide](/use-cases/social/notifications-and-engagement)
    Full console documentation for events management including all field descriptions, event types, and status lifecycle.

    → [Console: Events Management](/analytics-and-moderation/console/management/events-management)

---

## Common Mistakes

**Creating events without an end date** — Events without `endDate` appear as ongoing indefinitely. Always set both `startDate` and `endDate` for a clear timeline.

**Displaying event times without timezone conversion** — The API stores dates in UTC. Always convert to the user's local timezone before rendering, or display the timezone label.

```typescript
// ❌ Bad — raw UTC string
<span>{event.startDate}</span>

// ✅ Good — localized
<span>{new Date(event.startDate).toLocaleString()}</span>
```

**Not refreshing RSVP counts after changes** — After a user RSVPs, other attendees' counts are stale. Use Live Collections or re-query after RSVP actions to keep counts accurate.

## Best Practices

    - Show upcoming events prominently in the community feed — pin an event post in the week before it starts
    - Add filtering: "This week", "This month", "Past events"
    - Show a map preview for in-person events with a location field
    - Display the RSVP counts prominently ("42 going · 18 interested") to create social proof

      <img
        src="/images/past-event-page.png"
        alt="Mobile past events list with thumbnails, virtual and in-person badges, dates, and brand names"
        style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
      />
    - Send a confirmation in-app notification when a user RSVPs to an event
    - Allow users to change their RSVP up until the event starts
    - Send a reminder push notification 24h and 1h before the event to "going" attendees
    - After the event ends, ask attendees to leave a review or reaction
    - Always store event times in UTC and convert to local time for display
    - Show the timezone explicitly on event details (e.g., "3:00 PM PDT") to avoid confusion
    - For virtual events, show the time in both the creator's and viewer's timezone

---

**Dive deeper**: [Events API Reference](/social-plus-sdk/social/events/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Notifications & Engagement"
  icon="arrow-right"
  href="/use-cases/social/notifications-and-engagement"
>
  Events are live — now set up notifications so members get alerted about new events and RSVP reminders.

Or explore related guides:

    Events are typically hosted within communities
    Send event reminders and RSVP notifications
    Surface upcoming events in the community feed

---

### [Search & Discovery](https://learn.social.plus/use-cases/social/search-and-discovery)

> Add semantic and hashtag post search, community search, trending communities, content recommendations, and category browsing.

```typescript
// 1. Semantic search for communities
CommunityRepository.semanticSearchCommunities(
  { query: 'gaming', limit: 10 },
  ({ data }) => { renderResults(data); }
);

// 2a. Semantic (AI) search for posts
PostRepository.semanticSearchPosts(
  { query: 'healthy recipes', dataTypes: ['text', 'image'], limit: 20 },
  ({ data }) => { renderResults(data); }
);

// 2b. Hashtag search for posts
PostRepository.searchPostsByHashtag(
  { hashtags: ['recipe'], limit: 20 },
  ({ data }) => { renderResults(data); }
);

// 3. Get trending communities
CommunityRepository.getTrendingCommunities(
  { limit: 10 },
  ({ data }) => { renderTrending(data); }
);
```
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. One exception: hashtag post search (`searchPostsByHashtag`) is not available in the Flutter SDK.

Discovery turns a closed social app into a growing platform. This guide walks through implementing semantic and hashtag search for posts, semantic search for communities, surfacing trending content, and building a category-based browsing experience.

```mermaid
graph TD
    A[User wants to find content] --> B{Discovery method}
    B -->|Search bar| C[Intelligent Search]
    B -->|Explore tab| D[Trending Communities]
    B -->|Category browse| E[Community Categories]
    B -->|Algorithm-driven| F[Recommended Communities]
    C --> G[Search posts]
    C --> H[Search communities]
    D & E & F --> I[Community cards]
    G & H & I --> J[User navigates to content]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B decision
    class C,D,E,F,G,H,I process
    class J outcome
```

**Prerequisites**: SDK installed and authenticated. By default, search returns public communities. Semantic community search can also include discoverable private communities when `includeDiscoverablePrivateCommunity: true`; hidden private communities remain excluded.

**After completing this guide you'll have:**
- Semantic and hashtag post search integrated into your app's search bar
- Community search with trending and recommended community lists
- User-facing category browsing connected to community filtering


---

## Quick Start: Search Communities

Community search is the primary discovery surface — use a semantic query with optional membership, tag, category, and discoverable-private filters:


```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.semanticSearchCommunities(
  {
    query: 'gaming',
    communityMembershipStatus: AmityCommunityMemberStatusFilter.ALL,
  },
  ({ data: communities, onNextPage, hasNextPage, loading }) => {
    if (communities) { /* render community search results */ }
  },
);
```

```dart Flutter
final liveCollection = AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
      query: 'gaming',
      filter: AmityCommunityFilter.ALL,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((communities) {
  // Render communities in your UI.
});
await liveCollection.loadNext();
```


Full reference → [Intelligent Search: Communities](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-community)

---

## Step-by-Step Implementation

    Search communities with optional membership status (`all`, `member`, `notMember`), tags, discoverable-private, and category filters. Semantic results are ordered by backend relevance; use regular `getCommunities()` when you need an explicit sort order.


```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.semanticSearchCommunities(
  { query: 'game', communityMembershipStatus: AmityCommunityMemberStatusFilter.ALL },
  ({ data: communities, onNextPage, hasNextPage, loading }) => {
    if (communities) { /* render community results */ }
  },
);
```

```dart Flutter
final liveCollection = AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
      query: 'game',
      filter: AmityCommunityFilter.ALL,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((communities) {
  // Render communities in your UI.
});
await liveCollection.loadNext();
```


    Full reference → [Intelligent Search: Communities](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-community)
    Trending communities are ranked by recent activity (posts, members, engagement). Surface these on your explore page for new users.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getTrendingCommunities(
  { limit: 5 },
  ({ data: communities, loading }) => {
    if (communities) { /* render trending section */ }
  },
);
```

    Full reference → [Trending & Recommended Communities](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities)
    Recommended communities are personalized for the current user based on their activity and interests. Returns up to 15 communities.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getRecommendedCommunities(
  { limit: 5, includeDiscoverablePrivateCommunity: true },
  ({ data: communities, loading }) => {
    if (communities) { /* render recommended section */ }
  },
);
```

    Full reference → [Trending & Recommended Communities](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities)
    Organize communities into browsable categories. Query all categories, then filter communities by a selected category.

```typescript TypeScript
import { CategoryRepository } from '@amityco/ts-sdk';

const unsubscriber = CategoryRepository.getCategories(
  {},
  ({ data: categories, loading }) => {
    if (categories) { /* render category filter pills */ }
  },
);
```

    Full reference → [Community Categories](/social-plus-sdk/social/communities-spaces/organization/community-categories) · [Query Communities](/social-plus-sdk/social/communities-spaces/discovery/query-communities)
    Two complementary search methods are available for posts:
    - **Semantic search** (`PostRepository.semanticSearchPosts`) — AI-powered natural-language search. Best for open-ended queries like "healthy breakfast ideas".
    - **Hashtag search** (`PostRepository.searchPostsByHashtag`) — exact hashtag matching. Best for tag-driven browsing like `#recipe`.


    Full reference → [Intelligent Search: Posts](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-post)

---

## Connect to Moderation & Analytics

    Track search query volume and discovery patterns in **Admin Console → Analytics Dashboard → Social Insights** to understand what users are looking for and which communities are growing.

    → [Admin Console: Analytics](/analytics-and-moderation/console/analytics/)
    Create and manage community categories in the Admin Console. Categories appear in the community creation flow and in the discovery browse view.

    → [Admin Console: Product Management](/analytics-and-moderation/console/product-management/overview)

---

## Common Mistakes

**Firing a search API call on every keystroke** — This creates excessive API calls and flickers results. Debounce the input by 300–500ms before searching.

```typescript
// ❌ Bad — search on every key
<input onChange={(e) => search(e.target.value)} />

// ✅ Good — debounce
const debouncedSearch = useMemo(
  () => debounce((q) => search(q), 400), []
);
<input onChange={(e) => debouncedSearch(e.target.value)} />
```

**Not handling empty search results** — "No results found" is not enough. Suggest alternative queries, show trending content, or recommend popular communities to keep users engaged.

**Searching without a minimum query length** — Single-character searches return too many results and waste resources. Require at least 2–3 characters before triggering a search.

## Best Practices

    - Add a 300ms debounce to search input before firing the query — prevents excessive API calls while the user types
    - Show suggested/recent searches before the user starts typing
    - Display skeleton placeholders while results load
    - Clearly differentiate post results from community results with distinct card styles
    - Show a "No results" empty state with suggestions if the query returns 0 results
    - Show trending communities prominently for logged-in users with no following history
    - Once a user has joined 5+ communities, replace trending with personalized recommendations
    - Use horizontal scrolling category pills for browsing — they take less vertical space than a list
    - Cache trending and recommended results for 5-10 minutes — they don't need to be real-time
    - Use `searchPosts()` Live Collection — this handles debounced re-querying automatically on most platforms
    - Limit search result sets to 20-30 items; use pagination for deeper results
    - Pre-load categories at app launch and cache locally — they change infrequently

---

**Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → User Search & People Discovery"
  icon="arrow-right"
  href="/use-cases/social/user-search-and-people-discovery"
>
  Content search is working — now let users find each other with people search and suggestions.

Or explore related guides:

    Build the communities that discovery surfaces
    Show content from discovered communities in a feed
    Notify users about trending content they'd be interested in

---

### [Content Sharing & Deep Links](https://learn.social.plus/use-cases/social/content-sharing-and-deep-links)

> Generate shareable links for posts, communities, and user profiles to drive viral growth and cross-platform deep linking.

```typescript
import { AmitySharableContentType, Client } from '@amityco/ts-sdk';

// 1. Get share link configuration
const config = await Client.getShareableLinkConfiguration();

// 2. Generate a share URL for a post (null if the post pattern is not configured)
const shareUrl = config.generateLink(AmitySharableContentType.POST, postId);

// 3. Handle incoming deep link
// (deep link routing is app-layer responsibility — not part of the TS SDK)
handleDeepLink(incomingUrl, (resolved) => {
  if (resolved.type === 'post') navigateToPost(resolved.postId);
  if (resolved.type === 'community') navigateToCommunity(resolved.communityId);
});
```
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.

Shareable links turn your users into a growth engine. When a user shares a post or community to WhatsApp, Twitter, or SMS, the recipient can tap straight into your app. This guide covers generating share URLs from the SDK, configuring link patterns in the console, and handling incoming deep links.

```mermaid
graph TD
    A[User taps Share] --> B[SDK generates shareable URL]
    B --> C{Share target}
    C -->|WhatsApp/SMS/Email| D[Recipient receives link]
    C -->|Social media| E[Link with preview card]
    D --> F{App installed?}
    E --> F
    F -->|Yes| G[Open app → deep link to content]
    F -->|No| H[Fallback to web/store]
    G --> I[User views post/community/profile]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class C,F decision
    class B,D,E,G,H process
    class I outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). Shareable links must be configured in **Admin Console → Settings → Shareable Links** (custom domain is optional).

**After completing this guide you'll have:**
- Shareable URLs generated for posts, communities, and user profiles
- Deep link routing that opens your app directly to the target content
- Share sheet integration for native OS sharing on iOS, Android, and Web

---

## Quick Start: Generate a Shareable Link

```typescript TypeScript
import { AmitySharableContentType, Client } from '@amityco/ts-sdk';

const getPostShareLink = async (postId: string) => {
  try {
    const config = await Client.getShareableLinkConfiguration();
    // generateLink returns null when the post pattern is not configured.
    return config.generateLink(AmitySharableContentType.POST, postId);
  } catch (error) {
    console.error('Failed to generate share link:', error);
    return null;
  }
};

// Returns: "https://your-domain.com/posts/post-123"
```

Full reference → [Content Sharing](/social-plus-sdk/social/content-management/content-sharing)

**Shareable links are for sharing *outside* the app.** They produce a URL a user can send to WhatsApp, SMS, or social media that deep-links back into your app. social.plus does not have an in-app repost or reshare API — there is no way to reshare a post into another feed from the SDK.

---

## Step-by-Step Implementation

    The SDK fetches your configured domain and URL patterns from the server. Call this once and cache the result — it rarely changes.

```typescript TypeScript
import { AmitySharableContentType, Client } from '@amityco/ts-sdk';

const config = await Client.getShareableLinkConfiguration();
// config.domain — your configured base domain
// config.isEnabled(type) — whether a content type has a link pattern configured
// config.getPattern(type) — the raw pattern for a content type
// config.generateLink(type, referenceId) — the ready-to-share URL (null if unconfigured)
```

    Full reference → [Content Sharing](/social-plus-sdk/social/content-management/content-sharing)
    Use `generateLink` with the content type and reference ID. It returns `null` when that content type has no configured pattern, so gate on `isEnabled` if you need to hide the share action.

```typescript TypeScript
import { AmitySharableContentType } from '@amityco/ts-sdk';

// Post link
const postLink = config.generateLink(AmitySharableContentType.POST, postId);

// Community link
const communityLink = config.generateLink(AmitySharableContentType.COMMUNITY, communityId);

// User profile link
const userLink = config.generateLink(AmitySharableContentType.USER, userId);
```

    Full reference → [Content Sharing](/social-plus-sdk/social/content-management/content-sharing)
    Pass the generated URL to the platform's native share API. On web, use the Web Share API with a clipboard fallback.

```typescript TypeScript
// Web Share API
if (navigator.share) {
  await navigator.share({
    title: post.data.text?.substring(0, 50),
    url: postLink,
  });
} else {
  // Fallback: copy to clipboard
  await navigator.clipboard.writeText(postLink);
  showToast('Link copied!');
}
```
    When your app opens from a shared link, parse the URL and navigate to the right screen. Match against the same patterns from the configuration.

```typescript TypeScript
const handleDeepLink = (url: string) => {
  const postMatch = url.match(/\/posts\/([^/]+)/);
  if (postMatch) {
    navigateToPost(postMatch[1]);
    return;
  }
  const communityMatch = url.match(/\/communities\/([^/]+)/);
  if (communityMatch) {
    navigateToCommunity(communityMatch[1]);
    return;
  }
};
```
    Set up your custom domain and URL patterns in **Admin Console → Settings → Shareable Links**:
    - **Domain**: Your app's domain (e.g., `https://your-app.com`)
    - **Post pattern**: `/posts/{postId}`
    - **Community pattern**: `/communities/{communityId}`
    - **User pattern**: `/users/{userId}`

    These patterns are served to the SDK via `getShareableLinkConfiguration()`.

---

## Connect to Moderation & Analytics

  <img src="/images/uikit-shareable-link.png" alt="UIKit — Shareable link component" />

    Shareable links are generated on the client, so the SDK does not emit a built-in share event or a per-post share count. To measure sharing, log your own analytics event when a user taps share, and combine it with [post impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions) for a reach picture.
    Links to private community content should only work for authenticated users who are members. Visitors landing on a private community link should see a "Request to join" prompt, not the content.
    If a shared post is later removed by moderators, the link should show a "Content unavailable" message rather than a 404. Handle this gracefully in your deep link handler.

---

## Common Mistakes

**Exposing internal object IDs in share URLs** — Use the SDK's shareable link configuration to generate safe, user-facing URLs instead of constructing them manually with raw IDs.

**Not testing deep links on all platforms** — iOS Universal Links, Android App Links, and web fallbacks all have different requirements. Test the full flow on each platform — especially the "app not installed" case.

**Skipping deep link verification** — Always validate the incoming deep link format before navigating. Malformed or tampered URLs should redirect to a safe fallback, not crash the app.

## Best Practices

    - Add Open Graph meta tags to your web fallback pages so shared links show rich previews on social media
    - Use UTM parameters on share links to track which channels drive the most installs
    - Cache `getShareableLinkConfiguration()` at app startup — it only needs to refresh once per session
    - Always implement a web fallback for users who don't have the app installed
    - Handle edge cases: deleted content, private content the user can't access, expired links
    - Test deep links on both iOS Universal Links and Android App Links — each platform has different setup requirements
    - Log failed deep link navigations to catch broken patterns early
    - Pre-compose the share text with the post's first 50 characters + the link
    - Show a "Copied!" toast when the clipboard fallback fires
    - On mobile, use the native share sheet (iOS `UIActivityViewController`, Android `Intent.createChooser`) for the best experience

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Post Impressions & Creator Analytics"
  icon="arrow-right"
  href="/use-cases/social/post-impressions-and-creator-analytics"
>
  Content is shareable — now track who's viewing it with impression analytics and reach metrics.

Or explore related guides:

    Handle visitors who arrive via shared links
    Build the feed that shared links navigate to
    Create the communities that users share

---

### [Real-time Presence & Activity](https://learn.social.plus/use-cases/social/realtime-presence-and-activity)

> Show who's online with user and channel presence, heartbeat sync, and real-time event subscriptions for live social updates.

```typescript
// 1. Enable presence for the current user
await PresenceManager.enable();

// 2. Start heartbeat to stay online
PresenceManager.startHeartbeat({ intervalMs: 10000 });

// 3. Observe a channel's online members
ChannelRepository.Membership.getMembers(
  { channelId: 'ch-123', filter: 'online' },
  ({ data }) => { renderOnlineUsers(data); }
);

// 4. Subscribe to real-time topic events
```
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.

Presence makes your app feel alive. When users can see who's online, which communities are active, and get instant content updates, engagement increases. This guide covers enabling user presence, syncing channel activity, managing heartbeats, and subscribing to real-time social events.

```mermaid
graph TD
    A[App starts] --> B[Enable presence]
    B --> C[Start heartbeat]
    C --> D[SDK sends heartbeat every 20-30s]
    D --> E[Server marks user as online]
    E --> F[Other users see green dot]

    G[Open community] --> H[Subscribe to community topic]
    H --> I{Event type}
    I -->|Post created| J[New post appears in feed]
    I -->|Comment added| K[Comment count updates]
    I -->|Reaction added| L[Reaction count updates]

    M[Open chat list] --> N[Sync channel presence]
    N --> O[See which channels have active members]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,G,M action
    class I decision
    class B,C,D,E,H,N process
    class F,J,K,L,O outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). Presence features must be enabled for your network — check **Admin Console → Settings**.

**After completing this guide you'll have:**
- Online/offline presence indicators on user avatars throughout the app
- Channel-level presence (who is currently viewing a community or room)
- Real-time event subscriptions for platform-wide activity tracking

---

## Quick Start: Enable User Presence

```typescript TypeScript
import { PresenceManager, UserPresenceRepository } from '@social-plus/sdk';

try {
  const presence = new PresenceManager();
  await presence.enable();
  presence.startHeartbeat();

  // Track another user's online status
  const userPresence = new UserPresenceRepository();
  await userPresence.syncUserPresence('user-123');
} catch (error) {
  console.error('Presence setup failed:', error);
}
```

Full reference → [Presence Overview](/social-plus-sdk/core-concepts/realtime-communication/presence-state/overview)

---

## Part 1: User Presence (Online/Offline)

```mermaid
sequenceDiagram
    participant App as Your App
    participant SDK
    participant Server as social.plus Server
    participant Other as Other User's App

    App->>SDK: presence.enable()
    SDK->>Server: Register online
    loop Every 20-30 seconds
        SDK->>Server: Heartbeat ping
        Server-->>Server: Refresh TTL
    end
    Other->>SDK: syncUserPresence('user-123')
    SDK->>Server: Subscribe to user-123 presence
    Server-->>Other: status: online
    Note over App: User closes app
    App->>SDK: presence.dispose()
    SDK->>Server: Unregister
    Note over Server: Heartbeat TTL expires
    Server-->>Other: status: offline
```

    Enable presence tracking for the current user and start the automatic heartbeat. The SDK sends a heartbeat every 20-30 seconds to keep the user's online status current.

```typescript TypeScript
import { PresenceManager } from '@social-plus/sdk';

const presence = new PresenceManager();

const isAvailable = await presence.isEnabled();
if (isAvailable) {
  await presence.enable();
  presence.startHeartbeat();
}
```

    Full reference → [Heartbeat Sync](/social-plus-sdk/core-concepts/realtime-communication/presence-state/heartbeat-sync)
    Check whether specific users are online. Query up to 220 users at once for a member list or chat contact screen.

```typescript TypeScript
import { UserPresenceRepository } from '@social-plus/sdk';

const presenceRepo = new UserPresenceRepository();
const presences = await presenceRepo.getUserPresence(['user-1', 'user-2', 'user-3']);

presences.forEach(p => {
  console.log(`${p.userId}: ${p.isOnline ? 'Online' : 'Offline'}`);
});
```

    Full reference → [User Presence](/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence)
    For users visible on screen (profile page, chat list), sync their presence to get live updates when they come online or go offline. Max 20 synced users at a time.

```typescript TypeScript
const presenceRepo = new UserPresenceRepository();

// Start syncing (call for each visible user)
await presenceRepo.syncUserPresence('user-123');

// Observe changes
presenceRepo.getSyncingUserPresence().subscribe(presences => {
  presences.forEach(p => {
    updateStatusDot(p.userId, p.isOnline);
  });
});

// Stop when user scrolls off screen
await presenceRepo.unsyncUserPresence('user-123');
```

    Full reference → [User Presence](/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence)
    Display a global "X users online" counter for your platform.

```typescript TypeScript
const presenceRepo = new UserPresenceRepository();
const count = await presenceRepo.getOnlineUsersCount();
console.log(`${count} users online`);
```

    Full reference → [User Presence](/social-plus-sdk/core-concepts/realtime-communication/presence-state/user-presence)
    Stop the heartbeat when the app goes to the background and restart it when the app returns to the foreground. This prevents false "online" status while the app is minimized.

```typescript TypeScript
// Web: use visibility change
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    presence.stopHeartbeat();
  } else {
    presence.startHeartbeat();
  }
});
```

    Full reference → [Heartbeat Sync](/social-plus-sdk/core-concepts/realtime-communication/presence-state/heartbeat-sync)

---

## Part 2: Channel Presence

    Track which channels have active members. Useful for chat lists showing "2 members active" or highlighting active communities.

```typescript TypeScript
import { ChannelPresenceRepository } from '@social-plus/sdk';

const channelPresence = new ChannelPresenceRepository();
await channelPresence.syncChannelPresence('channel-123');

channelPresence.getSyncingChannelPresence().subscribe(updates => {
  updates.forEach(cp => {
    console.log(`Channel ${cp.channelId}: ${cp.activeUserCount} active`);
  });
});
```

    Full reference → [Channel Presence](/social-plus-sdk/core-concepts/realtime-communication/presence-state/channel-presence)
    Sync/unsync channels as the user scrolls through a chat list. Max 20 synced channels at a time.

```typescript TypeScript
// When a new channel becomes visible
await channelPresence.syncChannelPresence('channel-456');

// When a channel scrolls off screen
await channelPresence.unsyncChannelPresence('channel-123');

// Cleanup on unmount
await channelPresence.unsyncAllChannelPresence();
```

    Full reference → [Channel Presence](/social-plus-sdk/core-concepts/realtime-communication/presence-state/channel-presence)

---

## Part 3: Real-time Social Event Subscriptions

Beyond presence, you can subscribe to content events — new posts, comments, reactions — so your UI updates instantly without polling.

    Subscribe at different granularity levels: community-level, post-level, or comment-level.

```typescript TypeScript
import { getCommunityTopic, SubscriptionLevels } from '@amityco/ts-sdk';

// Subscribe to all post events in a community
const topic = getCommunityTopic(community, SubscriptionLevels.POST);

// Subscribe to posts AND comments
const fullTopic = getCommunityTopic(community, SubscriptionLevels.POST_AND_COMMENT);
```

    Full reference → [Social Real-time Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events)
    For a post detail screen, subscribe to comment-level events on a specific post.

```typescript TypeScript
import { getPostTopic, getCommentTopic, SubscriptionLevels } from '@amityco/ts-sdk';

// Subscribe to comment events on a post
const postCommentTopic = getPostTopic(post, SubscriptionLevels.COMMENT);

// Subscribe to a specific comment's events
const commentTopic = getCommentTopic(comment);
```

    Full reference → [Social Real-time Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events)
    Get real-time updates when someone follows or unfollows the current user.

```typescript TypeScript
import { getMyFollowersTopic, getMyFollowingsTopic } from '@amityco/ts-sdk';

const myFollowers = getMyFollowersTopic();
const myFollowings = getMyFollowingsTopic();
```

    Full reference → [Social Real-time Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events)

---

## Connect to Moderation & Analytics

    Track daily active concurrent users and peak online times in **Admin Console → Analytics Dashboard**. This helps with capacity planning and understanding peak engagement windows.
    Enable or disable presence features for your network in **Admin Console → Settings**. Presence can be toggled per-network without code changes.
    Combine SDK real-time events with webhook events for server-side workflows. For example, subscribe to `post.created` in the SDK for instant UI updates, and also handle it via webhook for server-side indexing.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Forgetting to stop the heartbeat on logout** — If you start `PresenceManager.startHeartbeat()` but don't stop it when the user logs out, the user appears "online" indefinitely.

```typescript
// ❌ Bad — heartbeat leaks
async function logout() {
  await Client.logout(); // heartbeat still running
}

// ✅ Good — stop heartbeat first
async function logout() {
  PresenceManager.stopHeartbeat();
  await Client.logout();
}
```

**Setting the heartbeat interval too low** — Intervals under 5 seconds waste bandwidth and may trigger rate limits. The recommended minimum is 10 seconds.

**Subscribing to too many topics at once** — Each topic subscription maintains a WebSocket channel. Subscribe only to topics visible on screen and unsubscribe when the user navigates away.

## Best Practices

    - Use a green dot for "online", grey dot for "offline", and show "Last seen X min ago" for recently active users
    - Don't show exact "last seen" timestamps for privacy — round to "a few minutes ago", "an hour ago", etc.
    - Let users opt out of showing their online status in profile settings
    - Use presence for supported online/offline availability in chat; do not label presence or channel-subscription state as "typing"
    - Respect the 20-user sync limit — sync only users currently visible on screen
    - Unsync users/channels as they scroll off screen; re-sync when they scroll back
    - Use `getUserPresence()` for one-time queries (member lists); use `syncUserPresence()` only for screens that need live updates
    - Stop heartbeat in background to avoid battery drain on mobile
    - Use `viewId` when the same user is displayed in multiple UI components to avoid duplicate unsubscriptions
    - Subscribe at the highest useful level: one `getCommunityTopic(community, POST_AND_COMMENT)` subscription is better than separate post + comment subscriptions
    - Unsubscribe when the component/screen unmounts — don't leak subscriptions
    - Use real-time events for UI updates; use webhooks for server-side workflows
    - Don't subscribe to everything globally — only subscribe to topics the user is actively viewing

---

**Dive deeper**: [Real-time Communication Reference](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Notifications & Engagement"
  icon="arrow-right"
  href="/use-cases/social/notifications-and-engagement"
>
  Presence is live — now pair it with push notifications to keep users informed across sessions.

Or explore related guides:

    Use Live Collections for real-time feed updates
    Combine presence with notification delivery
    Show online status on user profiles

---

### [Roles, Permissions & Governance](https://learn.social.plus/use-cases/social/roles-permissions-and-governance)

> Implement role-based access control with custom roles, hierarchical permissions, and community-level governance rules.

```typescript
// 1. Check if user has a specific permission
const allowed = await client.hasPermission('editCommunity')
  .community('communityId')
  .check();

// 2. Assign a community role
await ChannelRepository.Moderation.addRole(
  'communityId', ['userId'], 'moderator'
);

// 3. Remove a community role
await ChannelRepository.Moderation.removeRole(
  'communityId', ['userId'], 'moderator'
);
```
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.

As your platform grows beyond a single community, you need a permission system. social.plus provides a hierarchical RBAC model: global roles → community roles → per-action permissions. This guide covers checking permissions in the SDK, assigning community roles, and configuring governance rules.

```mermaid
graph TD
    A[User] --> B{Global role}
    B -->|Admin| C[Full platform access]
    B -->|Regular user| D{Community role?}
    D -->|Community Admin| E[Full community control]
    D -->|Moderator| F[Moderate content + manage members]
    D -->|Member| G[Post, comment, react]
    D -->|Not a member| H[View-only for public communities]
    E --> I[Actions: edit community, assign roles, delete posts]
    F --> J[Actions: approve posts, ban members, flag content]
    G --> K[Actions: create posts, add reactions, follow users]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,D decision
    class E,F,G,H process
    class C,I,J,K outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). At least one community created → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community). Admin Console access needed for global role management.

**Also recommended:** Complete [Community Platform](/use-cases/social/community-platform) first — roles and permissions govern community behavior.

**After completing this guide you'll have:**
- SDK permission checks (`hasPermission`) gating actions in your UI
- Community moderator role assignment and revocation working
- Post review mode (content gating) enabled in at least one community
- User ban and unban flows implemented

---

## Quick Start: Check a Permission

```typescript
try {
  const canEdit = await client.hasPermission({
    permission: 'EDIT_COMMUNITY_POST',
    communityId: 'community123',
  });

  if (canEdit) {
    showEditButton();
  }
} catch (error) {
  console.error('Permission check failed:', error);
}
```

Full reference → [Roles & Permissions](/social-plus-sdk/core-concepts/user-management/roles-permissions)

---

## Step-by-Step Implementation

    Always check permissions before rendering action buttons (edit, delete, ban, etc.). This prevents users from seeing controls they can't use and avoids server-side permission errors.

```typescript
const canEdit = await client.hasPermission({
  permission: 'EDIT_COMMUNITY_POST',
  communityId: 'community123',
});

const canBan = await client.hasPermission({
  permission: 'BAN_COMMUNITY_USER',
  communityId: 'community123',
});
```

    Full reference → [Roles & Permissions](/social-plus-sdk/core-concepts/user-management/roles-permissions)
    Promote a member to moderator via the member management API. Moderators can approve/reject posts, ban users, and manage content within their community.

```typescript
import { CommunityRepository } from '@amityco/ts-sdk';

// Add roles to a member
await ChannelRepository.Moderation.addRole(communityId, 'userId', ['moderator']);

// Remove a role
await ChannelRepository.Moderation.removeRole(communityId, 'userId', ['moderator']);
```

    Full reference → [Member Management](/social-plus-sdk/social/communities-spaces/organization/member-management)
    Set the `postSettings` when creating or updating a community to control who can post and whether posts need approval.

    | Setting | Who posts | Review needed | Best for |
    |---|---|---|---|
    | `ANYONE_CAN_POST` | All members | No | Open communities |
    | `ADMIN_REVIEW_POST_REQUIRED` | All members | Yes, admin approves | Curated communities |
    | `ONLY_ADMIN_CAN_POST` | Admins/mods only | No | Announcement channels |

    Full reference → [Create Community](/social-plus-sdk/social/communities-spaces/community-lifecycle/create-community)
    Community admins and moderators can ban members who violate guidelines. Banned users cannot view or interact with the community.

```typescript
import { CommunityRepository } from '@amityco/ts-sdk';

// Ban a member
await CommunityRepository.Moderation.banMembers(communityId, ['userId']);

// Unban a member
await CommunityRepository.Moderation.unbanMembers(communityId, ['userId']);
```

    Full reference → [Community Moderation](/social-plus-sdk/social/communities-spaces/governance/community-moderation)
    When a community uses `ADMIN_REVIEW_POST_REQUIRED`, new posts land in the `reviewing` feed type. Check a post's `feedType` to know its state, then approve or decline it. Only users with the `REVIEW_COMMUNITY_POST` permission can take these actions.

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// Check a post's review status
const isUnderReview = post.feedType === Amity.FeedType.Reviewing;
const isPublished  = post.feedType === Amity.FeedType.Published;
const isDeclined   = post.feedType === Amity.FeedType.Declined;

// Approve — moves post to published feed
await PostRepository.approvePost(post.postId);

// Decline — moves post to declined feed (author can still see it)
await PostRepository.declinePost(post.postId);
```

    Full reference → [Post Review](/social-plus-sdk/social/content-management/posts/moderation/post-review)
    Global roles (super admin, admin, support) are managed in **Admin Console → Settings → Admin Access Control**. These roles grant cross-community permissions.

    → [Admin Console: Roles & Privileges](/analytics-and-moderation/console/moderation/roles-and-privileges)

---

## Permission Reference

| Permission | Description | Who has it by default |
|---|---|---|
| `EDIT_COMMUNITY_POST` | Edit any post in a community | Community admin, moderator |
| `DELETE_COMMUNITY_POST` | Delete any post in a community | Community admin, moderator |
| `BAN_COMMUNITY_USER` | Ban/unban members | Community admin, moderator |
| `EDIT_COMMUNITY` | Change community name, description, settings | Community admin |
| `REVIEW_COMMUNITY_POST` | Approve/decline posts in review queue | Community admin, moderator |
| `MUTE_COMMUNITY_USER` | Temporarily silence a member | Community admin, moderator |

---

## Connect to Moderation & Analytics

    Create custom roles with specific permission sets in **Admin Console → Settings → Roles**. Assign users to roles globally or per-community.

    → [Roles & Privileges](/analytics-and-moderation/console/moderation/roles-and-privileges)
    All moderator actions (ban, post removal, role change) are logged. Review the audit trail in **Admin Console → Moderation → Activity Log** for compliance.
    Receive `community.role.assigned` and `community.role.removed` webhook events to sync role state with your backend or trigger notifications.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Checking permissions only on the client** — Client-side permission checks are for UI gating only. The server enforces permissions regardless, but relying solely on client checks creates a confusing UX when the server rejects an action.

**Assigning roles without verifying the assigner's permission** — Only users with `editCommunityUser` permission can assign roles. Check this before showing the role assignment UI to avoid failed requests.

**Forgetting that global roles override community roles** — A global admin can do anything in any community, even without a community-level role. Don't build UI that implies global admins need community roles.

## Best Practices

    - Check permissions in the SDK before showing UI elements (buttons, menus)
    - The server enforces permissions even if the client doesn't check — but a good UX never shows controls a user can't use
    - Assign at least 2 moderators per community to avoid single-point-of-failure moderation
    - Use `ADMIN_REVIEW_POST_REQUIRED` for communities with compliance requirements (healthcare, finance, education)
    - Keep your role hierarchy flat: admin → moderator → member is sufficient for most apps
    - Don't create more than 3-4 custom roles — complexity creates confusion
    - Define clear escalation paths: moderator handles content, admin handles users, super admin handles settings
    - Document role responsibilities in community guidelines
    - Show a "You're now a moderator" notification when someone is promoted
    - Surface moderation tools contextually: show "Approve" button inline on queued posts, not buried in settings
    - Give moderators a dedicated "Mod queue" view with pending posts and flagged content
    - Let users see their own role in the community header ("You are a Moderator")

---

**Dive deeper**: [User Management API Reference](/social-plus-sdk/core-concepts/user-management/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Content Moderation Pipeline"
  icon="arrow-right"
  href="/use-cases/social/content-moderation-pipeline"
>
  Roles are set — now wire up the moderation pipeline with flagging, AI review, and webhooks.

Or explore related guides:

    Build communities that use these governance rules
    Set up the full moderation workflow
    Manage user relationships and blocking

---

### [Content Moderation Pipeline](https://learn.social.plus/use-cases/social/content-moderation-pipeline)

> Wire up the full moderation loop: SDK flagging → admin review → AI moderation → webhook automation — keeping your platform safe at scale.

```typescript
// 1. Flag a post
await PostRepository.flagPost('postId', 'spam');

// 2. Unflag a post
await PostRepository.unflagPost('postId');

// 3. Flag a comment
await CommentRepository.flagComment('commentId', 'harassment');

// 4. Flag a user
await UserRepository.flagUser('userId', 'impersonation');
```
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.

At scale, manual moderation doesn't work. This guide shows how all the moderation pieces connect — from users flagging content in the SDK, to AI auto-screening, to moderators reviewing in the Admin Console, to webhooks triggering automated responses.

```mermaid
graph TD
    A[User creates content] --> B[AI screening]
    B -->|Clean| C[Content goes live]
    B -->|Violation| D[Auto-rejected or flagged for review]
    C --> E{User reports content}
    E -->|Flag via SDK| F[Flagged content queue]
    F --> G[Moderator reviews in Admin Console]
    G -->|Approve| C
    G -->|Remove| H[Content deleted]
    G -->|Warn/Ban user| I[User action taken]
    H & I --> J[Webhook event fired]
    J --> K[Your backend / automation]
    K -->|Send notification| L[Notified user]
    K -->|Log incident| M[Incident database]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class E decision
    class B,D,F,G,J,K process
    class C,H,I,L,M outcome
```

**Prerequisites**: SDK installed with authenticated users, Admin Console access for moderator configuration, and a server endpoint to receive webhook events.

**Also recommended:** Complete [Rich Content Creation](/use-cases/social/rich-content-creation) and [Community Platform](/use-cases/social/community-platform) first — you need content and communities to moderate.

**After completing this guide you'll have:**
- User-side flag/unflag implemented for posts and comments
- Admin Console moderation review queue receiving flagged content
- An AI moderation rule set configured with at least one auto-action
- A webhook handler receiving moderation events for downstream automation


---

## Layer 1: SDK — User Flagging

Let users flag content they find inappropriate. Flagged content enters a moderation queue. The SDK provides methods to flag posts, comments, and users.

### Quick Start: Flag a Post


Full reference → [Content Flagging](/social-plus-sdk/social/content-management/moderation/content-flagging)

---

## Layer 2: AI Content Moderation

Configure automatic content screening in the Admin Console. AI moderation runs before content goes live.

    Navigate to **Admin Console → Settings → AI Content Moderation**.

    - **Text moderation**: Screen post text and comments for policy violations (hate speech, spam, explicit content, etc.)
    - **Image moderation**: Screen uploaded images for nudity, violence, and other violations
    - **Auto-action**: Configure whether violations are auto-rejected or flagged for human review

    → [AI Content Moderation](/analytics-and-moderation/console/ai-content-moderation)
    Pre-hook events let your server intercept content before it's published. Your endpoint receives the content, evaluates it, and returns an allow/deny decision.

```javascript Node.js pre-hook handler
const express = require('express');
const app = express();
app.use(express.json());

app.post('/pre-hook', (req, res) => {
  const { event, data } = req.body;

  if (event === 'post.didCreate') {
    const { text } = data;
    const isAllowed = runCustomContentPolicy(text);

    if (!isAllowed) {
      // Reject the post
      return res.status(200).json({ allow: false });
    }
  }

  // Allow all other content
  res.status(200).json({ allow: true });
});
```

    → [Pre-Hook Events](/analytics-and-moderation/social+-apis-and-services/pre-hook-event)

---

## Layer 3: Admin Console — Human Review

Flagged content and AI-held content lands in the Admin Console review queues. The **Posts and comments management** page shows every post with its AI moderation status inline — making it fast to spot, review, and action flagged content.

  <img src="/images/analytics-and-moderation/console/posts-page-overview.png" alt="Admin Console — Posts and comments management with AI Mod status badges" />

    - **Admin Console → Content Moderation → Flagged Content**: Posts, comments, and stories flagged by users
    - Each item shows: content, reporter, flag reason, and action buttons (approve, remove, warn user)
    - Bulk actions available for high-volume queues

    → [Admin Console: Content Moderation](/analytics-and-moderation/console/moderation/overview)
    For communities using `ADMIN_REVIEW_POST_REQUIRED`, new posts land in a review queue:
    - **Admin Console → Social Management → Posts**: Review pending posts
    - Approve → post goes live; Reject → post removed

    → [Post Review](/social-plus-sdk/social/content-management/posts/moderation/post-review)
    Give community moderators access to their community's moderation queue without granting full admin access:

    - **Admin Console → Admin Access Control → Roles**: Create community moderator roles
    - Assign users to roles per community

    → [Roles & Privileges](/analytics-and-moderation/console/moderation/roles-and-privileges)

---

## Layer 4: Webhooks — Automation

Receive real-time events when content is actioned to trigger downstream workflows.

```mermaid
sequenceDiagram
    participant User
    participant SDK
    participant Server as social.plus Server
    participant PreHook as Your Pre-Hook
    participant Webhook as Your Webhook

    User->>SDK: createPost(text, images)
    SDK->>Server: POST /posts
    Server->>PreHook: pre-hook: post.didCreate
    PreHook-->>Server: { allow: true } or { allow: false }
    alt Allowed
        Server-->>SDK: 201 Post created
        SDK-->>User: Post appears in feed
        Note over Server: AI moderation runs async
        Server->>Webhook: post.created event
        Webhook-->>Webhook: Log & index
    else Rejected by pre-hook
        Server-->>SDK: 403 Rejected
        SDK-->>User: "Post could not be published"
    end
    Note over User: Later — another user flags the post
    User->>SDK: flagPost(postId)
    SDK->>Server: POST /posts/{id}/flag
    Server->>Webhook: post.flagged event
    Webhook-->>Webhook: Notify moderator
```

    In **Admin Console → Settings → Integrations → Webhooks**, register your endpoint URL and select which events to subscribe to.

    → [Admin Console: Integrations](/analytics-and-moderation/console/settings/)
    Always verify the webhook signature before processing:

```javascript Node.js
const crypto = require('crypto');
const express = require('express');
const app = express();

app.use('/webhook', express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-amity-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSig, 'hex')
  )) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  handleModerationEvent(event);

  res.status(200).json({ received: true });
});
```
    Key moderation webhook events to subscribe to:

    | Event | Trigger | Common action |
    |---|---|---|
    | `post.flagged` | User flags a post | Notify moderator, log incident |
    | `post.deleted` | Post removed by moderator | Notify author, log |
    | `comment.flagged` | User flags a comment | Notify moderator |
    | `user.banned` | User banned from community | Revoke access in your system |
    | `community.post.approved` | Post approved in review queue | Notify author |

```javascript Node.js
function handleModerationEvent(event) {
  switch (event.event) {
    case 'post.flagged':
      notifyModerationTeam(event.data);
      logIncident({ type: 'flag', content: event.data });
      break;
    case 'user.banned':
      revokeUserAccess(event.data.userId);
      notifyUser(event.data.userId, 'community-ban');
      break;
    case 'post.deleted':
      notifyAuthor(event.data.userId, 'post-removed');
      break;
  }
}
```

    → [Webhook Events Reference](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Exposing moderation status to content authors** — Telling a user their post was "flagged" or "under review" can encourage them to create alt accounts. Show the content normally to the author while hiding it from others (shadow moderation).

**Skipping webhook signature verification** — Moderation webhooks trigger automated actions (bans, deletions). Without signature verification, an attacker could send fake webhook payloads to your endpoint.

**Auto-deleting all AI-flagged content** — AI moderation produces false positives. Use AI to queue content for human review, not to delete automatically. Reserve auto-actions only for high-confidence categories like CSAM.

## Best Practices

    Run three complementary layers for best coverage:
    1. **Pre-publish AI screening** — catches obvious violations before content is visible
    2. **Community self-moderation** — users flag what AI misses
    3. **Human moderator review** — maintains context and handles edge cases

    Avoid relying on any single layer alone.
    - Return `200 OK` quickly and process events asynchronously — slow responses cause webhook retries
    - Implement idempotent handlers — webhooks may be delivered more than once
    - Log all received events before processing so you can replay them if your handler fails
    - Set up a dead-letter queue for events that fail processing
    - Set up role-based access so community moderators only see their community's queue
    - Define clear escalation paths: community moderator → admin → legal
    - Log all moderator actions with reason codes for audit trails
    - Provide moderators with appeal management tools for banned users
    - Always notify users when their content is removed — explain why and link to guidelines
    - Provide an appeal process for content removal decisions
    - Show a submission confirmation to users who flag content so they know it was received

---

**Dive deeper**: [Content Moderation API Reference](/social-plus-sdk/social/content-management/moderation/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Roles, Permissions & Governance"
  icon="arrow-right"
  href="/use-cases/social/roles-permissions-and-governance"
>
  Moderation is active — now set up community roles and permission gates for fine-grained governance.

Or explore related guides:

    Understand how posts feed into the moderation pipeline
    Configure post moderation settings per community
    Notify users of moderation actions via push or in-app

---

### [Comment Review Workflow](https://learn.social.plus/use-cases/social/comment-review-workflow)

> Hold community comments for moderator approval: turn review on, show authors an awaiting-review state, and build a reviewer queue with approve and decline.

```typescript
import { Client, CommentRepository, CommunityRepository } from '@amityco/ts-sdk';

// 1. Require review for a community's comments
await CommunityRepository.updateCommunity(communityId, {
  needApprovalOnCommentCreation: true,
});

// 2. Create a comment and wait for the server's approval status
const { data: comment } = await CommentRepository.createComment(
  { referenceType: 'post', referenceId: postId, data: { text: 'Hello!' } },
  false, // isOptimistic
);
if (comment.approvalStatus === 'pending') showAwaitingReview(comment);

// 3. Reviewer: list the queue, then approve or decline
const canReview = Client.getActiveClient()
  .hasPermission(Amity.Permission.ReviewCommunityCommentPermission)
  .community(communityId);

CommentRepository.getCommentReviewQueue({ communityId }, ({ data }) => renderQueue(data));
await CommentRepository.approveComment(commentId);
await CommentRepository.declineComment(commentId, 'Off-topic');
```
Full walkthrough below ↓

**Platform note** — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift) and Android (Kotlin) SDKs — see [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review) for all three. Flutter does not ship comment review.

Some communities need a moderator to read a comment before anyone else does: a brand community during a product launch, a support forum, a group for younger members. Comment review holds a member's comment until a moderator approves it, while the author still sees their own comment as "awaiting review" rather than watching it vanish. This guide wires the whole loop: the community setting, the author's experience, and the reviewer's queue.

```mermaid
graph TD
    A[Member writes a comment] --> B{Community requires review<br/>and author cannot review?}
    B -->|No| C[Published — everyone sees it]
    B -->|Yes| D[Pending — only the author sees it]
    D --> E[Appears in the review queue]
    E --> F{Reviewer decision}
    F -->|Approve| C
    F -->|Decline| G[Rejected and deleted]
    C -->|Author edits the text| D

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,F decision
    class D,E process
    class C,G outcome
```

**Prerequisites**: SDK installed and authenticated, a community whose settings you can change, and a user who holds `REVIEW_COMMUNITY_COMMENT` on it (community moderators do by default).

**Also recommended:** [Comments & Reactions](/use-cases/social/comments-and-reactions) for the comment thread this guide builds on.

**After completing this guide you'll have:**
- A community that holds members' comments for review
- An author experience that shows a pending comment as "awaiting review"
- Comment threads and counts that stay correct as comments are approved
- A reviewer screen that lists pending comments and approves or declines them

---

## How Comment Review Works

A comment is held only when three things are true: it is on a post in a community, that community requires comment review, and its author cannot review the community's comments. The community's creator and its moderators publish immediately. Comments on stories, on user-feed posts, and on your own content IDs are never held.

A held comment is `pending`. A reviewer approves it (`approved`, visible to everyone) or declines it (`rejected`, and deleted). Editing an approved comment's content sends it back to `pending`. The full rules, with every transition and what it changes, are in the [Approval Lifecycle](/social-plus-sdk/social/content-management/comments/moderation/comment-review#approval-lifecycle).

## Step-by-Step Implementation

    Set `needApprovalOnCommentCreation` when you create or update the community. From then on, new comments by members who cannot review are held.

```typescript TypeScript
import { CommunityRepository } from '@amityco/ts-sdk';

await CommunityRepository.updateCommunity(communityId, {
  needApprovalOnCommentCreation: true,
});
```

    Moderators can also turn it on from the Admin Console: the community's **Permissions** tab → **Approve member comments**. On Android, use `isCommentReviewEnabled(true)` on the community create or update builder.

    Full reference → [Require Review for Community Comments](/social-plus-sdk/social/content-management/comments/moderation/comment-review#require-review-for-community-comments)

    Create with optimistic creation turned off. An optimistic create shows a local comment before the server answers, and the SDK cannot determine its approval status until the server responds; with it off, the comment you receive already carries the server's decision.

```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

const { data: comment } = await CommentRepository.createComment(
  {
    referenceType: 'post',
    referenceId: postId,
    data: { text: commentText },
  },
  false, // isOptimistic
);

if (comment.approvalStatus === 'pending') {
  // Not in the thread yet — show it to the author only
  showAwaitingReviewCard(comment);
}
```

    Keep that returned comment and render it yourself. A pending comment never appears in a comment query, not even its author's, so the thread alone would make it look as if the comment disappeared.

    Full reference → [Read Approval Status on a Comment](/social-plus-sdk/social/content-management/comments/moderation/comment-review#read-approval-status-on-a-comment)

    Subscribe to the post's comment topic so approvals reach the client. The comment query then inserts an approved comment into the thread on its own, in the position where it was written, and moves the count.

```typescript TypeScript
import {
  CommentRepository,
  getPostTopic,
  subscribeTopic,
  SubscriptionLevels,
} from '@amityco/ts-sdk';

const unsubscribeTopic = subscribeTopic(getPostTopic(post, SubscriptionLevels.COMMENT));

const unsubscribeComments = CommentRepository.getComments(
  { referenceType: 'post', referenceId: post.postId, parentId: null, sortBy: 'lastCreated' },
  ({ data: comments, loading }) => {
    if (!loading) renderThread(comments); // approved comments only
  },
);

// Remove the author's awaiting-review card once the comment is approved
const disposeApproved = CommentRepository.onCommentApproved((approved) => {
  removeAwaitingReviewCard(approved.commentId);
});
```

    For the post's comment count, `post.commentsCount` counts approved comments for everyone, the author included. Use `post.getLocalCommentCount(true)` when the author should see their own pending comment counted.

    Full reference → [Social Realtime Events](/social-plus-sdk/core-concepts/realtime-communication/realtime-events/social-realtime-events) · [What Approving or Declining Changes](/social-plus-sdk/social/content-management/comments/moderation/comment-review#what-approving-or-declining-changes)

    Show review controls only to users who hold `REVIEW_COMMUNITY_COMMENT` on the community. The server enforces the permission on every call; the client check is for hiding controls.

```typescript TypeScript
import { Client, CommentRepository } from '@amityco/ts-sdk';

const canReview = Client.getActiveClient()
  .hasPermission(Amity.Permission.ReviewCommunityCommentPermission)
  .community(communityId);

if (canReview) {
  const unsubscribeQueue = CommentRepository.getCommentReviewQueue(
    { communityId, limit: 10 },
    ({ data: pending, loading, hasNextPage, onNextPage }) => {
      if (loading) return;
      renderQueue(pending); // newest first
      if (hasNextPage) showLoadMore(onNextPage);
    },
  );
}
```

    Approve or decline by comment ID. Approving publishes the comment; declining rejects and deletes it.

```typescript TypeScript
import { CommentRepository } from '@amityco/ts-sdk';

async function decide(commentId: string, approve: boolean) {
  try {
    if (approve) {
      await CommentRepository.approveComment(commentId);
    } else {
      await CommentRepository.declineComment(commentId, 'Off-topic');
    }
  } catch (error) {
    // 400300: another reviewer decided first — refresh the queue, don't retry
    handleReviewError(error);
  }
}
```

    Full reference → [Query the Review Queue](/social-plus-sdk/social/content-management/comments/moderation/comment-review#query-the-review-queue) · [Approve or Decline a Comment](/social-plus-sdk/social/content-management/comments/moderation/comment-review#approve-or-decline-a-comment)

    An effective edit by the author sends an approved comment back to review, so read the status on the edited comment too. Whether an author may edit a comment that is still pending is a network setting; read it before you show an edit control on a pending comment.

```typescript TypeScript
import { Client, CommentRepository } from '@amityco/ts-sdk';

const { isAllowEditCommentWhenReviewingEnabled } = await Client.getSocialSettings();
const canEdit = comment.approvalStatus !== 'pending' || isAllowEditCommentWhenReviewingEnabled;

if (canEdit) {
  const { data: edited } = await CommentRepository.updateComment(comment.commentId, {
    data: { text: newText },
  });

  if (edited.approvalStatus === 'pending') showAwaitingReviewCard(edited);
}
```

    Full reference → [How the Status Changes](/social-plus-sdk/social/content-management/comments/moderation/comment-review#how-the-status-changes)

---

## Admin Console: Review Comments Without Building a Screen

Moderators can work the same queue from the Admin Console instead of an in-app screen: the **Requires approval** queue on the Comments page lists pending comments, with approve and decline actions. Both surfaces act on the same comments, so a decision in one is reflected in the other.

→ [Comment Approval in the Console](/analytics-and-moderation/console/social-management/social-management/comments#comment-approval)

## Common Mistakes

**Showing the optimistic comment as published** — With optimistic creation on, a local comment appears before the server decides whether it needs review. Create with `isOptimistic` set to `false` and read `approvalStatus` on the result.

```typescript
// ❌ Bad — renders before the server's decision
const { data } = await CommentRepository.createComment(bundle);
appendToThread(data);

// ✅ Good — wait for the server, then branch on status
const { data: comment } = await CommentRepository.createComment(bundle, false);
comment.approvalStatus === 'pending' ? showAwaitingReviewCard(comment) : appendToThread(comment);
```

**Waiting for a pending comment to show up in the thread** — Comment queries return approved comments only, for the author too. Render the author's pending comment from the create or edit result.

**Telling the author why their comment was declined** — The decline `reason` is kept for the moderation record only and is never returned to the author or anyone else through the SDK. There is also no `comment.declined` event: a decline arrives as a deletion.

**Retrying a `400300` on approve or decline** — It means the comment was already decided, usually by another reviewer. Refresh the queue instead of retrying.

**Building an "N awaiting review" badge** — The review queue returns no total. Page through it instead.

## Best Practices

    - Label a pending comment clearly, for example "Awaiting review — only you can see this", so the author does not post it twice
    - Keep the author's pending card below the thread rather than mixing it into approved comments
    - Disable reply, reaction, and flag controls on a pending comment; the server refuses all three
    - Filter the queue by `postId` or a date range when a community is busy
    - Treat a `404` on a pending comment as "not visible to you", not as "deleted"
    - Remember that turning review off does not clear the queue; pending comments still need a decision

---

**Dive deeper**: [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review) has the full lifecycle, parameter tables, errors, and iOS and Android examples for every API in this guide.

## Next Steps

  title="Your next step → Content Moderation Pipeline"
  icon="arrow-right"
  href="/use-cases/social/content-moderation-pipeline"
>
  Comments are reviewed before they go live — now add flagging, AI moderation, and webhook automation.

Or explore related guides:

    Build the comment threads that review applies to
    Decide who can review a community's comments
    Set up the communities that carry the review setting

---

### [User Profile Moderation](https://learn.social.plus/use-cases/social/user-profile-moderation)

> Moderate user profiles with AI-powered scanning, admin reset from the Users tab or User History, profile blocklists, and webhook automation.

```typescript
// 1. Flag a user profile
await UserRepository.flagUser('userId', 'inappropriate_profile');

// 2. Unflag a user profile
await UserRepository.unflagUser('userId');

// 3. Update a user profile (triggers AI scan)
await UserRepository.updateUser('userId', {
  displayName: 'New Display Name',
  description: 'Updated bio text',
});
```
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.

Content moderation catches bad posts — but what about bad profiles? Offensive display names, NSFW avatars, and scam-laden bios erode trust before a user even posts. This guide covers the full user profile moderation pipeline: AI-powered scanning, the admin review workflow, profile reset tools, and blocklists.

```mermaid
graph TD
    A[User updates profile] --> B[Profile saved]
    B --> C[AI scans text & image]
    C -->|Clean| D[Profile live — no action]
    C -->|Violation detected| E[Profile flagged]
    E --> F[Appears in Moderation Feed — Users tab]
    F --> G{Admin action}
    G -->|Reset profile| H[Fields reset to defaults]
    G -->|Clear flag| I[Flag dismissed]
    G -->|Ban globally| J[User banned]
    H --> K[User receives notification]
    B --> L[Blocklist check]
    L -->|Match| E

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class G decision
    class B,C,E,F,L process
    class D,H,I,J,K outcome
```

**Prerequisites**: SDK installed and authenticated, Admin Console access for moderation configuration.

**Also recommended:** Complete [Content Moderation Pipeline](/use-cases/social/content-moderation-pipeline) first — user profile moderation extends the same AI and console infrastructure.

**After completing this guide you'll have:**
- User profile flagging via SDK (flag / unflag users)
- AI scanning of display names, descriptions, and avatars
- Admin review workflow with reset, clear, and ban actions, plus reset for any user from User History
- Profile blocklist configured for display names and descriptions

---

## How Profile Moderation Differs from Content Moderation

User profile moderation is **flag-only** — unlike posts and messages, flagged profiles are never auto-deleted. The block confidence threshold that auto-removes content does **not** apply to profiles. Admins must explicitly decide what to do.

| Behavior | Content (Posts / Messages) | User Profiles |
|---|---|---|
| Pre-moderation | ✅ Images blocked before upload | ✅ Avatar images blocked before upload |
| Post-moderation | ✅ AI scans after publish | ✅ AI scans after profile save |
| Auto-delete at block confidence | ✅ Content removed automatically | ❌ Never — flag only |
| Admin reset | N/A | ✅ Tick which fields to reset — flagged profiles from the Users tab, any user from User History |

**Flag-only for profiles**: Flagged profiles always require manual admin review. This prevents automated systems from silently wiping user accounts.

---

## Step-by-Step Implementation

    Let users report profiles they find inappropriate. Flagged profiles enter the moderation queue alongside AI-flagged profiles.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

// Flag a user with a reason
await UserRepository.flagUser('user-456');

// Unflag if the report was a mistake
await UserRepository.unflagUser('user-456');
```

    Full reference → [Content Flagging](/social-plus-sdk/social/content-management/moderation/content-flagging)
    When a user saves profile changes, AI scans three fields automatically:

    | Field | Scan Type |
    |---|---|
    | **Display Name** | Text |
    | **Description** | Text |
    | **Avatar** (uploaded file) | Image |

    Text is scanned for: harassment, sexual content, violence, hate speech, scam promotion, self-harm, and PII (URLs, person types).

    Avatars are scanned for: nudity, suggestive imagery, violence, hate symbols, and substance-related content.

    **External avatar URLs**: Avatars set with `avatarCustomUrl` are not moderated. Only uploaded avatars (`avatarFileId`) are scanned, flagged, and reset.
    Flagged profiles appear in **Admin Console → Moderation → Moderation Feed → Users** tab.

    Each flagged profile shows:
    - AI moderation labels with category counts (e.g., "Hate (2)", "Violence (1)")
    - Which field triggered the flag — display name or description
    - User report count from community members
    - Last flagged timestamp

    **Available actions:**
    - **Reset profile** — restore flagged fields to safe defaults
    - **Ban globally** — ban the user across all communities
    - **Clear flag** — dismiss the flag and approve the profile

    → [AI User Profile Moderation](/analytics-and-moderation/console/ai-user-profile-moderation)
    Whichever route you take, fields are restored to these defaults:

    | Field | Reset behavior |
    |---|---|
    | **Display Name** | Set to `{prefix}{UUID}` (e.g., `User_a1b2c3d4e5f6`) |
    | **Description** | Cleared to empty |
    | **Avatar** | Removed — reverts to default; original file deleted from storage |

    There are two places to reset from, both opening the **same reset modal** where you tick the fields to restore:

    | Where | Applies to |
    |---|---|
    | **Moderation Feed → Users tab** | Profiles in the review queue (AI-flagged and user-reported) |
    | **User History page** | Any user, flagged or not |

    To reset a profile that was never flagged — or to reset just one field, such as an avatar while leaving the display name alone — open the user's [User History](/analytics-and-moderation/console/user-and-content-management/user-social-history) page, click the three-dot (**⋮**) menu, and choose **Profile moderation → Reset profile**. Tick the fields to restore; unticked fields are left untouched.

    The user receives a `USER_PROFILE_RESET` notification through the notification tray listing the fields that were reset.

    **Avatar reset is irreversible** — the original image file is deleted from storage. Only the reset event is logged; the original image cannot be recovered.
    Block specific words and phrases from appearing in display names and descriptions.

    In **Admin Console → Moderation → Blocklist**, add terms under the **User Profile** category. This blocklist is independent from the content blocklist — you can maintain different blocked terms for profiles versus posts.

    | Blocklist Category | Applies to |
    |---|---|
    | **Content** | Posts, comments, messages |
    | **User Profile** | Display names, descriptions |

---

## Admin Console: Moderation Feed — Users Tab

The Users tab in the Moderation Feed is the central hub for profile moderation.

    Displays all profiles requiring moderator attention — both AI-flagged and user-reported.

    - AI moderation labels with detected categories and occurrence counts
    - **(Profile description is flagged)** label when the description triggered the flag
    - User report counts from other community members
    - Actions: **Reset profile**, **Ban globally**, **Clear flag**
    Displays profiles that have already been moderated, with the action taken:

    - **Flag cleared by [moderator]**
    - **Globally banned by [moderator]**
    - **Profile reset by [moderator]**

    Use the **Select moderator** filter to view actions by a specific team member.

---

## Confidence Thresholds

Profile moderation reuses the same confidence thresholds configured for content moderation — but only the **flag** threshold applies.

| Threshold | Applies to profiles? | Behavior |
|---|---|---|
| **Flag Confidence** (default: 40) | ✅ Yes | Profile flagged for admin review |
| **Block Confidence** (default: 80) | ❌ No | Does **not** auto-delete profile fields |

Start with medium flag confidence (40–60) and adjust based on false positive rates. Since profiles are never auto-deleted, a lower threshold is safer — it just means more items in the review queue.

---

## Webhook Automation

Profile moderation events trigger webhooks for downstream automation — sending notifications, syncing with CRM systems, or logging incidents.

```typescript Node.js
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-amity-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSig, 'hex')
  )) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;

  switch (event) {
    case 'user.didFlag':
      notifyModerationTeam(data);
      break;
    case 'user.didBan':
      revokeAccessAcrossSystems(data.userId);
      break;
  }

  res.status(200).json({ received: true });
});
```

→ [Webhook Events Reference](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Relying only on AI scanning without a blocklist** — AI moderation catches broad categories but may miss brand-specific terms, competitor names, or community-specific slurs. Always pair AI scanning with a curated blocklist for display names.

**Assuming `avatarCustomUrl` avatars are moderated** — Only uploaded avatars (`avatarFileId`) are scanned. If avatars need to be moderated, set them with `avatarFileId`.

**Auto-banning on first flag** — A single AI flag or user report may be a false positive. Use the reset action for first offenses and escalate to bans for repeat violations. Check user history for patterns before banning.

## Best Practices

    Apply escalating actions based on violation history:
    1. **First offense** — Reset only the offending field and notify the user
    2. **Second offense** — Reset + temporary mute
    3. **Repeat violations** — Global ban

    Check the **User History** page for past moderation events before deciding on an action.
    - Review and update the profile blocklist monthly — slang and evasion tactics evolve
    - Add leetspeak and Unicode variants of blocked terms (e.g., `h4te`, `ⓗⓐⓣⓔ`)
    - Keep the profile blocklist separate from the content blocklist — profile terms are often different (impersonation names, brand abuse, etc.)
    - Assign profile moderation to a dedicated moderator or rotation — profile flags require different judgment than content flags
    - Use the **Select moderator** filter in the Reviewed tab for audit and load-balancing
    - Document your reset-vs-ban criteria so the team is consistent
    - The `USER_PROFILE_RESET` notification tells users what happened — but consider also linking to your community guidelines
    - Allow users to update their profile again after a reset — the new version will be re-scanned
    - Provide an appeal path for users who believe the reset was incorrect

---

**Dive deeper**: [AI User Profile Moderation](/analytics-and-moderation/console/ai-user-profile-moderation) has the full console reference including detection categories, threshold configuration, and admin reset details.

## Next Steps

  title="Your next step → Roles, Permissions & Governance"
  icon="arrow-right"
  href="/use-cases/social/roles-permissions-and-governance"
>
  Profile moderation is live — now configure who gets moderator access and what they can do.

Or explore related guides:

    The full content moderation loop — AI screening, user flagging, admin review, and webhook automation
    Build the profile pages and social graph that this guide moderates
    Configure the notification tray that delivers profile reset alerts

---

### [Post Impressions & Creator Analytics](https://learn.social.plus/use-cases/social/post-impressions-and-creator-analytics)

> Track post views, measure reach, query who saw each post, and build a creator analytics dashboard.

```typescript
// 1. Mark a post as viewed (impression + reach)
await post.analytics.markAsViewed();

// 2. Read impression & reach counters
const { impressionsCount, reachCount } = post.analytics;

// 3. Query who viewed the post
const viewers = await post.analytics.getReachUsers({ limit: 50 });
```
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.

social.plus tracks two key content performance metrics for every post:

- **Impressions** — total number of times the post was viewed (same user can contribute multiple impressions)
- **Reach** — number of *unique* users who viewed the post

Both are updated in near-real time. This guide shows you how to record impressions as users scroll a feed, read the counters, and query the list of users who reached a post — the building blocks for a creator analytics dashboard.

```mermaid
graph TD
    A[Post appears in feed] --> B{Viewability check}
    B -->|≥50% visible for ≥1s| C[post.analytics.markAsViewed]
    C --> D[impression count +1]
    C --> E{First view by this user?}
    E -->|yes| F[reach count +1]
    E -->|no| G[reach unchanged]
    D & F --> H[Dashboard reads post.impression + post.reach]
    H --> I[Creator sees updated stats]
    I --> J[Creator queries who viewed the post]
    J --> K[UserRepository.getViewedUsers]
    K --> L[Paginated list of Amity.User]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,E decision
    class C,D,F,G,H,J,K process
    class I,L outcome
```

**After completing this guide you'll have:**
- Post impression tracking firing on every feed scroll event
- Unique reach (`impression`) and total views (`markAsViewed`) both captured
- A "Who viewed this" list queryable per post for creator dashboards

---

## Quick Start: Record a View and Read the Counters

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// Called from your IntersectionObserver when a post is ≥50% visible
function onPostVisible(post: Amity.Post) {
  post.analytics.markAsViewed();
  console.log(`Impressions: ${post.impression} · Reach: ${post.reach}`);
}
```

Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)

---

## Step-by-Step Implementation

    Call `markAsViewed()` when a post becomes meaningfully visible. In web apps, use an `IntersectionObserver`; in native apps, use your list's viewability callbacks. Aim for a threshold of ≥50% visible for at least 1 second to avoid counting rapid scroll-past views.

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// Subscribe to the feed so we have live post objects
const unsubscribe = PostRepository.getPosts(
  { targetType: 'community', targetId: communityId },
  ({ data: posts }) => {
    posts.forEach(post => trackVisibility(post));
  },
);

function trackVisibility(post: Amity.Post) {
  const observer = new IntersectionObserver(
    (entries) => {
      entries.forEach(entry => {
        if (entry.isIntersecting) {
          post.analytics.markAsViewed();
          observer.disconnect();   // count each scroll-into-view once per session
        }
      });
    },
    { threshold: 0.5 }
  );
  observer.observe(document.getElementById(post.postId)!);
}
```

    Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Read `post.impression` and `post.reach` from the live post object. Both update in near-real time as views come in.

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// Subscribe to a single post for live counter updates
const unsubscribe = PostRepository.getPost(postId, ({ data: post }) => {
  updateDashboard({
    impressions: post.impression,
    reach: post.reach,
  });
});
```

    Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Get a paginated list of every unique user who reached a post — useful for "Seen by" UI, audience profiling, and creator insights.

```typescript
import { UserRepository } from '@amityco/ts-sdk';

const unsubscribe = UserRepository.getReachedUsers(
  { postId: post.postId, limit: 20 },
  ({ data: users, hasNextPage, onNextPage, loading, error }) => {
    if (loading) return;
    if (error) console.error(error);

    renderViewedByList(users);

    if (hasNextPage) {
      loadMoreButton.onclick = onNextPage;
    }
  },
);
```

    Full reference → [Post Impressions](/social-plus-sdk/social/content-management/posts/analytics/post-impressions)
    Combine impressions, reach, reaction count, and comment count into a compact analytics card shown on the creator's post detail view.

```typescript
import { PostRepository } from '@amityco/ts-sdk';

const unsubscribe = PostRepository.getPost(postId, ({ data: post }) => {
  const stats = {
    impressions: post.impression,
    reach: post.reach,
    reactions: post.reactionsCount,      // total reactions across all types
    comments: post.commentsCount,
    // engagement rate: (reactions + comments) / reach * 100
    engagementRate: post.reach > 0
      ? ((post.reactionsCount + post.commentsCount) / post.reach * 100).toFixed(1)
      : '0',
  };

  renderCreatorStats(stats);
});
```

---

## Analytics Metrics Reference

| Metric | Where to read | What it means |
|---|---|---|
| `post.impression` | Post live object | Total views (one user can generate multiple) |
| `post.reach` | Post live object | Unique users who viewed the post |
| `post.reactionsCount` | Post live object | Total reactions across all reaction types |
| `post.commentsCount` | Post live object | Total comments including replies |
| Viewed users list | `UserRepository.getViewedUsers` | Paginated list of `Amity.User` objects |

---

## Connect to Moderation & Analytics

  <img src="/images/analytics-and-moderation/post-analytics.png" alt="Admin Console — Post analytics dashboard" />

    Impression and reach data aggregates across all posts and is visible in **Admin Console → Analytics → Content**. Filter by community, date range, or content type to spot high-performing content.
    Stories have their own impression tracking via the Story SDK — the same impression/reach concept applies.

    → [Stories & Ephemeral Content](/use-cases/social/stories-and-ephemeral-content)
    Although there's no real-time webhook per impression, you can combine `post.created` and `post.updated` webhooks with your own analytics pipeline to build server-side engagement scoring.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Calling `markAsViewed()` on every re-render** — React and Flutter components can re-render dozens of times. Debounce the call or use an Intersection Observer to fire it only when the post enters the viewport for the first time.

```typescript
// ❌ Bad — fires on every render
useEffect(() => { post.analytics.markAsViewed(); });

// ✅ Good — fire once with Intersection Observer
const observer = new IntersectionObserver(([entry]) => {
  if (entry.isIntersecting) {
    post.analytics.markAsViewed();
    observer.disconnect();
  }
});
```

**Confusing impressions with reach** — Impressions count total views (one user can contribute many). Reach counts unique viewers. Display the right metric for the right context.

**Building analytics dashboards without caching** — Fetching reach user lists on every refresh is expensive. Cache the data for at least 30 seconds and show loading states for fresh queries.

## Best Practices

    - **Feed scroll**: fire when ≥50% of the post card is visible for ≥1 second
    - **Post detail view**: fire immediately on open — the user navigated intentionally
    - **Clip reel**: fire when the clip starts playing (it's clearly in focus)
    - **Don't fire** on posts that are briefly visible during a fast scroll-to-top gesture
    - `markAsViewed()` is a fire-and-forget call — never `await` it in a render path
    - If it fails due to network conditions, don't retry in the same session; impressions are best-effort
    - Impression accuracy is near-real time; don't expect sub-second updates in the dashboard
    - If your app shows creators a "Seen by" list, disclose this to viewers in your privacy policy
    - The `getViewedUsers` API returns user objects — only show identifiable information (name, avatar) where appropriate for your app's context
    - Respect user block relationships: don't show a blocked user's name to a creator in the viewed list
    - Lead with **reach** (unique viewers) as the headline metric — it's more meaningful than raw impressions for most creators
    - Show a 7-day or 28-day trend line, not just the current snapshot
    - Display engagement rate (reactions + comments / reach) to help creators judge content quality
    - For communities with many posts, sort by reach descending to surface top-performing content first

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Advertising & Monetization"
  icon="arrow-right"
  href="/use-cases/social/advertising-and-monetization"
>
  You're tracking views — now monetize that attention with native ads in the feed.

Or explore related guides:

    Track impressions on clip posts as users scroll a vertical reel
    Story-specific impression and reach analytics
    The feed query that powers impression tracking at scale

---

### [Advertising & Monetization](https://learn.social.plus/use-cases/social/advertising-and-monetization)

> Integrate native ads into social feeds with console-driven configuration, impression tracking, and click analytics.

```typescript
// 1. Fetch network ads
const { ads, settings } = await AdRepository.getNetworkAds();

// 2. Track an impression (when ad enters viewport)
ads.forEach((ad: Amity.Ad) => {
  ad.analytics.markAsSeen(Amity.AdPlacement.FEED);
});

// 3. Track a click (when user taps the ad link)
ads.forEach((ad: Amity.Ad) => {
  ad.analytics.markLinkAsClicked(Amity.AdPlacement.FEED);
});
```
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.

Native ads blend into your social feed, generating revenue without disrupting the user experience. social.plus provides a console-driven ad system — configure ad placements and creatives in the Admin Console, then fetch and render them in your app using the SDK. This guide covers fetching ads, tracking impressions and clicks, and placing ads within feeds.

```mermaid
graph TD
    A[Admin Console] --> B[Configure ad creatives]
    B --> C[Set placement rules]
    C --> D[SDK fetches ads + settings]
    D --> E{Where to place?}
    E -->|In feed| F[Insert ad card every N posts]
    E -->|In story ring| G[Sponsored story slot]
    E -->|In community| H[Community banner ad]
    F & G & H --> I[User sees ad]
    I --> J{User action}
    J -->|Views ad| K[markAsSeen — impression tracked]
    J -->|Taps ad| L[markLinkAsClicked — click tracked]
    K & L --> M[Analytics in Admin Console]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class E,J decision
    class B,C,D,F,G,H,I process
    class K,L,M outcome
```

**Prerequisites**: SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview). Ads must be configured in **Admin Console → Settings → Premium Ads** with at least one active creative uploaded.

**Also recommended:** Complete [Build a Social Feed](/use-cases/social/build-a-social-feed) first — ads render inline within feed content.

**After completing this guide you'll have:**
- Native ad units rendering in the feed at configured intervals
- Impression and click events tracked and sent to the Admin Console
- Ad frequency and targeting rules configured via the Admin Console

---

## Quick Start: Fetch and Display Ads

```typescript TypeScript
import { AdRepository } from '@amityco/ts-sdk';

try {
  const { ads, settings } = await AdRepository.getNetworkAds();
  // ads: Array of Ad objects with creative URLs, CTAs, and metadata
  // settings: placement configuration (frequency, positions)
} catch (error) {
  console.error('Failed to fetch ads:', error);
}
```

Full reference → [Ads](/social-plus-sdk/core-concepts/content-handling/ads)

---

## Step-by-Step Implementation

    Call `getNetworkAds()` on app launch and cache the result. The response includes the ad creatives (images, text, CTAs) and settings that define where and how often to show them.

```typescript TypeScript
import { AdRepository } from '@amityco/ts-sdk';

const { ads, settings } = await AdRepository.getNetworkAds();
console.log(`${ads.length} ads available`);
console.log('Placement frequency:', settings.frequency);
```

    Full reference → [Ads](/social-plus-sdk/core-concepts/content-handling/ads)
    Use the placement settings to insert ad cards at the right intervals in your social feed. A common pattern is to insert an ad every N posts.

```typescript TypeScript
const buildFeedWithAds = (posts: any[], ads: Amity.Ad[], frequency: number) => {
  const feedItems: any[] = [];
  let adIndex = 0;

  posts.forEach((post, i) => {
    feedItems.push({ type: 'post', data: post });

    // Insert ad every `frequency` posts
    if ((i + 1) % frequency === 0 && adIndex < ads.length) {
      feedItems.push({ type: 'ad', data: ads[adIndex] });
      adIndex++;
    }
  });

  return feedItems;
};
```
    When an ad enters the viewport, mark it as seen. This records an impression for analytics. Use an Intersection Observer (web) or equivalent visibility detection on mobile.

```typescript TypeScript
// When ad card becomes visible in the viewport
ad.analytics.markAsSeen(Amity.AdPlacement.FEED);
```

    Full reference → [Ads](/social-plus-sdk/core-concepts/content-handling/ads)
    When a user taps an ad's call-to-action, record the click before opening the destination URL.

```typescript TypeScript
const handleAdClick = (ad: Amity.Ad) => {
  // Record the click
  ad.analytics.markLinkAsClicked(Amity.AdPlacement.FEED);

  // Open the destination
  window.open(ad.callToActionUrl, '_blank');
};
```

    Full reference → [Ads](/social-plus-sdk/core-concepts/content-handling/ads)
    Set up ad creatives, targeting, and placement rules in **Admin Console → Settings → Premium Ads**:
    - **Creative**: Upload ad image/video, set headline text and CTA button text
    - **Targeting**: Choose which communities or content categories to show the ad in
    - **Frequency**: How often ads appear in the feed (every N posts)
    - **Schedule**: Start/end dates for the campaign

    → [Admin Console: Premium Ads](/analytics-and-moderation/console/premium-ads/)

---

## Connect to Moderation & Analytics

    View impression counts, click-through rates, and conversion metrics per ad creative in **Admin Console → Analytics → Ads Performance**. Use this to optimize creative and placement.
    Community moderators can flag ads that don't fit their community's tone. Flagged ads are reviewed in the Admin Console moderation queue.
    Receive ad impression and click events via webhooks to sync with your ad server or analytics pipeline.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Rendering ads without tracking impressions** — If you display an ad but don't call `markAdSeen()`, the impression isn't counted and revenue isn't attributed. Always track when the ad enters the viewport.

```typescript
// ❌ Bad — ad shown but no tracking
return <AdBanner ad={ad} />;

// ✅ Good — track on visibility
// Ad impression tracking not in TS SDK (see Warning)
return <AdBanner ad={ad} onVisible={onVisible} />;
```

**Caching ads for too long** — Ad creatives and targeting change frequently. Fetch fresh ads on each feed load instead of caching them across sessions.

**Placing ads too frequently in the feed** — Ads every 3–4 posts degrade user experience. A ratio of 1 ad per 8–10 organic posts maintains engagement while generating revenue.

## Best Practices

    - Don't show ads in the first 3 positions of the feed — let users see content first
    - Match the ad card styling to your post card styling for a native feel
    - Label ads clearly with an "Ad" or "Sponsored" tag — transparency builds trust
    - Don't show more than 1 ad per 5 posts — higher density drives users away
    - Hide ads from the feed when ad count is 0 — never show a broken ad placeholder
    - Only call `markAsSeen()` when the ad is at least 50% visible for 1+ seconds — this matches industry standards
    - Don't track impressions when the app is backgrounded or the screen is off
    - De-duplicate impressions client-side — only track the first impression per ad per session
    - Use `Amity.AdPlacement.FEED` for in-feed ads and the appropriate placement enum for other positions
    - Cache `getNetworkAds()` for the session — ads change infrequently
    - Pre-load ad images while the user is scrolling through content
    - Lazy-load ad video creatives — only start playback when the ad is in view
    - Keep ad card rendering lightweight — heavy ad views slow down feed scrolling

---

**Dive deeper**: [Posts API Reference](/social-plus-sdk/social/content-management/posts/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Post Impressions & Creator Analytics"
  icon="arrow-right"
  href="/use-cases/social/post-impressions-and-creator-analytics"
>
  Ads are running — now track organic content performance alongside ad metrics.

Or explore related guides:

    Build the feed where ads are placed
    Integrate sponsored stories alongside user stories
    Handle flagged ad content

---

### [Product Tagging & Social Commerce](https://learn.social.plus/use-cases/social/product-tagging-and-social-commerce)

> Turn posts and livestreams into shoppable experiences — set up your catalogue, tag products in text, image, video, and livestream content, and track engagement.

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// 1. Text post with product tags
const textPost = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'text',
    data: { text: 'Loving this Nike Air Max for my morning runs!' },
    productTags: [
        { productId: 'prod_001', text: 'Nike Air Max', index: 12, length: 12 },
    ],
});

// 2. Image post with attachment product tags
const imagePost = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'image',
    data: { text: 'Check out these products!' },
    attachments: [
        { fileId: 'image-file-id-1', type: 'image' },
        { fileId: 'image-file-id-2', type: 'image' },
    ],
    attachmentProductTags: {
        'image-file-id-1': [{ productId: 'prod_001' }],
        'image-file-id-2': [{ productId: 'prod_002' }],
    },
});

// 3. Track engagement
product.analytics.markAsViewed('feed_page/product_list/product_item', 'post', postId);
product.analytics.markAsClicked('feed_page/product_list/product_item', 'post', postId);
```
Full walkthrough below ↓

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

  <img
    src="/images/post-product-tagging.png"
    alt="Post composer showing product tag dropdown with Radiant Glow Vitamin C Elixir and Radiant Brightening Citrus Serum results"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

Product tagging lets users attach products from your catalogue to posts and livestreams, turning social content into a shoppable storefront. Viewers see product cards with images, prices, and direct links — without leaving the feed or stream.

```mermaid
graph LR
    A[Admin Console<br/>Product Catalogue] --> B{Content type}
    B -->|Post| C[Text tags<br/>+ attachment tags]
    B -->|Livestream| D[Room post tags<br/>+ pin/unpin]
    C --> E[Viewers browse<br/>& click products]
    D --> E
    E --> F[Analytics:<br/>views + clicks]
```

## Where Product Tagging Works

| Content type | Tag mechanism | Max tags | Pinning | Platforms |
|-------------|--------------|---------|---------|-----------|
| **Text post** | `productTags` — reference product by position in text | 20 | — | iOS, Android, Web |
| **Image post** | `attachmentProductTags` — link products to specific images by `fileId` | 20 | — | iOS, Android, Web |
| **Video post** | `attachmentProductTags` — link products to specific videos by `fileId` | 20 | — | iOS, Android, Web |
| **Livestream** | `productTags` + `pinnedProductId` on room post | 20 | 1 at a time | iOS, Android, Web |

Flutter and React Native do not yet support product tagging.

---

## Step 0: Set Up Your Product Catalogue

Before any tagging can happen, products must exist in **Admin Console → Product catalogue**.

    Navigate to **Product catalogue** in the Admin Console sidebar.

      <img
        src="/images/analytics-and-moderation/console/product-management/product-catalogue-list.png"
        alt="Admin Console Product Catalogue showing product list with IDs, names, prices, statuses, and action buttons"
      />
    Click **+ Add product** to create one product at a time, or use **Import** to upload a CSV for bulk creation. Each product needs:
    - **Product ID** — unique identifier (cannot change after creation)
    - **Product Name** — display name shown when tagged
    - **Product URL** — link for viewers to click through
    - **Status** — must be **Active** to appear in tag search

      <img
        src="/images/analytics-and-moderation/console/product-management/add-product.png"
        alt="Admin Console Add Product form with Product ID, Status, Product name, Product URL, Price, and image upload fields"
      />
    Only **Active** products are discoverable in the tag-product search. Set seasonal or discontinued products to **Archived** to hide them without deleting.

Full Admin Console guide → [Product Catalogue](/analytics-and-moderation/console/product-management/overview)

---

## Tag Products in Posts

### UIKit (recommended)

The post composer includes built-in product tagging — type `@` and switch to the product tab:

      <img
        src="/images/post-product-tagging.png"
        alt="Post composer showing @ trigger with product tag tab and product results"
        style={{ maxWidth: "100%" }}
      />
      <img
        src="/images/product-tag-list.png"
        alt="Products tagged in this post bottom sheet showing Radiant Glow Vitamin C Elixir ($32) and Serum CitrusGlow Brightening ($32)"
        style={{ maxWidth: "100%" }}
      />

UIKit components used:

| Component | Role |
|-----------|------|
| `ProductTagSelectionComponent` | Search and multi-select products (mode: `create`, `edit`, or `livestream`) |
| `ProductTagListComponent` | Read-only list below the post (mode: `post`, `image`, `video`, `livestream`) |

Component reference → [Product Tagging Components](/uikit/components/social/product-tagging)

### SDK: Text Post with Product Tags

Tag products inline within the text. Each tag references a product by ID and a position range in the text.

```typescript
const post = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'text',
    data: { text: 'Loving this Nike Air Max for my morning runs!' },
    productTags: [
        { productId: 'prod_001', text: 'Nike Air Max', index: 12, length: 12 },
    ],
});
```

### SDK: Image Post with Attachment Product Tags

For image (and video) posts, attach products to specific media files using `attachmentProductTags`. Products are linked by the `fileId` of each uploaded image.

```typescript
const post = await PostRepository.createPost({
    targetType: 'community',
    targetId: communityId,
    dataType: 'image',
    data: { text: 'Check out these products!' },
    attachments: [
        { fileId: 'image-file-id-1', type: 'image' },
        { fileId: 'image-file-id-2', type: 'image' },
    ],
    attachmentProductTags: {
        'image-file-id-1': [{ productId: 'prod_001' }],
        'image-file-id-2': [{ productId: 'prod_002' }],
    },
});
```

SDK reference → [Text Posts](/social-plus-sdk/social/content-management/posts/creation/text-post) · [Image Posts](/social-plus-sdk/social/content-management/posts/creation/image-post) · [Video Posts](/social-plus-sdk/social/content-management/posts/creation/video-post)

---

## Tag Products in Livestreams

Livestream product tagging adds **pinning** — the host (or authorized co-host) can pin one product at a time as a prominent overlay visible to all viewers.

      <img
        src="/images/livestream-product-tagging.png"
        alt="Livestream with a pinned product card (GlowLab Soft Glow Blush Stick, $24) at the bottom and Unpin button"
        style={{ maxWidth: "100%" }}
      />
      <img
        src="/images/product-tag-list-livestream.png"
        alt="Products tagged bottom sheet with pinned product at top, View buttons, and scrollable list"
        style={{ maxWidth: "100%" }}
      />

### Key differences from post tagging

| Capability | Posts | Livestreams |
|-----------|-------|-------------|
| Pin a product as overlay | — | ✅ (1 at a time, auto-replaces) |
| Swap pin mid-session | — | ✅ |
| Co-host product permissions | — | ✅ (host grants per co-host) |
| Update tags after creation | ✅ | ✅ (full replacement) |
| Viewer click-through | ✅ | ✅ (in-app browser, stream continues) |

Full livestream product tagging walkthrough → [Livestream: Product Tagging](/use-cases/social/livestream/product-tagging)

### Manage tagged products during the stream

  <img
    src="/images/manage-product-tag-list.png"
    alt="ManageProductTagListComponent showing pinned product at top, other products with Pin and Delete buttons, and Add products button"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

---

## Track Product Engagement

Both post and livestream product tags support fire-and-forget analytics for views and clicks. Events are automatically deduplicated per product per source.

```typescript
// When a product card enters the viewport
product.analytics.markAsViewed(
  'feed_page/product_list/product_item',   // location
  AnalyticsSourceTypeEnum.POST,             // or ROOM for livestreams
  postId,                                   // source ID
);

// When a viewer taps the product link
product.analytics.markAsClicked(
  'feed_page/product_list/product_item',
  AnalyticsSourceTypeEnum.POST,
  postId,
);
```

| Event | Deduplication key | Notes |
|-------|------------------|-------|
| `markAsViewed` | `{productId}.view.{sourceType}.{sourceId}` | Same product in different posts = separate events |
| `markAsClicked` | `{productId}.linkClicked.{sourceType}.{sourceId}` | Fire before opening the product URL |

### Admin Console: Review product performance

Tagged posts surface in the console with linked product cards — admins can see which products are referenced and filter posts by tag.

  <img
    src="/images/analytics-and-moderation/console/social-management/posts-list-with-product-tags.png"
    alt="Admin Console post list showing posts with product tags including thumbnails and product names"
  />

---

## Posts vs. Livestreams: Choosing the Right Approach

    **Best for**: Product reviews, influencer recommendations, curated collections, community marketplaces.

    - Tag products in text, image, or video posts
    - Products appear as a "Products tagged in this post" section below the content
    - Viewers browse and click through at their own pace
    - No real-time coordination required
    **Best for**: Flash sales, product demos, Q&A sessions, unboxing events.

    - Pin one product at a time as a prominent overlay
    - Swap pins mid-stream to match what the host is discussing
    - Co-hosts can manage products if the host grants permission
    - Pair with live chat for real-time questions about the product
    **Best for**: Maximizing content lifespan.

    - After a livestream ends, the post remains in the feed with all tagged products still browsable
    - Viewers who missed the live event can still shop the product list
    - Pin overlay is removed in replay, but the product list persists

---

## Common Mistakes

**Tagging an Archived product** — Only products with **Active** status in the Admin Console appear in the tag-product search. If a host can't find a product, check its status.

**Confusing text tags vs. attachment tags** — Text posts use `productTags` (position in text). Image and video posts use `attachmentProductTags` (keyed by `fileId`). Mixing them up causes silent failures.

**Using the parent post ID for livestream pin/unpin** — `pinProduct` and `unpinProduct` require the **child** room post ID, not the parent. See [Livestream Product Tagging](/use-cases/social/livestream/product-tagging) for details.

## Best Practices

    - Use CSV import for initial catalogue setup with many products
    - Use consistent Product IDs (e.g., `SKU-001`) — they're immutable after creation
    - Archive seasonal products instead of deleting to preserve tag history
    - Keep thumbnails at 1:1 aspect ratio for consistent display
    - Tag 3–5 products per post for best engagement — too many dilutes focus
    - For livestreams, pre-tag all products before going live so they're ready immediately
    - In image posts, link each product to the specific image that shows it
    - Use text tags for editorial posts, attachment tags for visual-first content
    - Call `markAsViewed` when the product card enters the viewport (use intersection observer on Web)
    - Call `markAsClicked` on tap before opening the URL
    - Review view-to-click ratios in the Admin Console to optimize product placement
    - A/B test text tags vs. attachment tags to see which drives more clicks

---

## Related Topics

    Deep-dive: pin/unpin, co-host permissions, and per-stream analytics.
    Text, image, video, poll, and file posts with @mentions and hashtags.
    Admin guide for uploading, importing, and managing your product database.

    ProductTagSelectionComponent, ProductTagListComponent, and ManageProductTagListComponent.
    productTags parameter reference for text posts.
    Room post creation, pinProduct, unpinProduct, and co-host permissions.

---

### [User Onboarding & Visitor Mode](https://learn.social.plus/use-cases/social/user-onboarding-and-visitor-mode)

> Build the full onboarding funnel: anonymous browsing with visitor mode, authenticated login, profile setup, and session management.

```typescript
// 1. Visitor login (anonymous, read-only)
await Client.loginAsVisitor();

// 2. Upgrade to authenticated user
await Client.login({ userId: 'user-123', displayName: 'Jane' });

// 3. Update the user profile
await UserRepository.updateUser('user-123', {
  displayName: 'Jane Doe',
  description: 'Hello world!',
  avatarFileId: 'uploaded-avatar-id',
});
```
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.

A great onboarding funnel lets users browse before committing. social.plus supports three user types — visitors (anonymous, read-only), authenticated users (full access), and bots (crawler/SEO). This guide walks through the entire flow from first launch to complete profile.

```mermaid
graph TD
    A[App launched] --> B{Has account?}
    B -->|No| C[Login as Visitor]
    B -->|Yes| D[Login with credentials]
    C --> E[Browse feeds read-only]
    E --> F{User taps write action}
    F --> G[Show signup prompt]
    G --> D
    D --> H[Session established]
    H --> I[Set up profile]
    I --> J[Full social experience]
    H --> K{Token expires?}
    K -->|Yes| L[Session handler renews]
    L --> H

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B,F,K decision
    class C,D,E,G,H,I,L process
    class J outcome
```

**Prerequisites**: SDK installed → [SDK Setup](/social-plus-sdk/getting-started/overview), plus an API key from the social.plus console. Production apps also need a backend server to generate auth tokens.

**After completing this guide you'll have:**
- Visitor mode enabled so unauthenticated users can browse content
- A smooth visitor → authenticated transition with session continuity
- Profile setup step (display name, avatar) at first login

---

## Quick Start: Login as Visitor

Let users browse your app without creating an account:

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');

try {
  await Client.loginAsVisitor({ sessionHandler });
} catch (error) {
  console.error('Visitor login failed:', error);
}
```

Full reference → [Visitor Mode](/social-plus-sdk/getting-started/visitor-mode)

---

## Step-by-Step Implementation

    Create the client once at app startup. This must happen before any login call.

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

const client = Client.createClient('your-api-key', 'sg');
```

    Full reference → [Authentication](/social-plus-sdk/getting-started/authentication)
    Visitors get read-only access — they can view feeds, communities, and profiles but cannot post, comment, react, or follow. The SDK skips MQTT connections and push notification registration for visitors, saving resources.

```typescript TypeScript
try {
  await Client.loginAsVisitor({ sessionHandler });
  console.log('Visitor login successful');
} catch (error) {
  console.error('Visitor login failed:', error);
}
```

    Full reference → [Visitor Mode](/social-plus-sdk/getting-started/visitor-mode)
    Check the current user type before allowing write operations. Show a signup prompt when visitors try to interact.

```typescript TypeScript
import { Client, UserTypeEnum } from '@amityco/ts-sdk';

const userType = Client.getCurrentUserType();
if (userType === UserTypeEnum.VISITOR) {
  // Show signup/login prompt
  showSignupModal('Create an account to post');
}
```

    Full reference → [Visitor Mode](/social-plus-sdk/getting-started/visitor-mode)
    After the user signs up or logs in through your auth system, call the authenticated login. In production, always pass an `authToken` generated by your backend.

```typescript TypeScript
try {
  await client.login({
    userId: 'user-123',
    displayName: 'John Doe',
    authToken: 'token-from-your-backend', // Required in production
  }, sessionHandler);
  console.log('Login successful');
} catch (error) {
  console.error('Login failed:', error);
}
```

    Full reference → [Authentication](/social-plus-sdk/getting-started/authentication)
    Monitor the session lifecycle to show the right UI: loading spinner during `establishing`, navigate to app on `established`, re-auth prompt on `tokenExpired`.

```typescript TypeScript
import { Client } from '@amityco/ts-sdk';

Client.onSessionStateChange((state: Amity.SessionStates) => {
  switch (state) {
    case 'established':
      navigateToApp();
      break;
    case 'tokenExpired':
      showTokenRefreshIndicator();
      break;
    case 'terminated':
      handleSessionTermination();
      break;
  }
});
```

    Full reference → [Authentication](/social-plus-sdk/getting-started/authentication)
    After first login, let users set their display name, bio, and avatar. The SDK auto-creates the user record on first login — this step updates it.

```typescript TypeScript
import { UserRepository } from '@amityco/ts-sdk';

const { data: updatedUser } = await UserRepository.updateUser('userId', {
  displayName: 'Jane Smith',
  description: 'Loves hiking and photography',
});
```

    Full reference → [Update User Information](/social-plus-sdk/core-concepts/user-management/user-operations/update-user-information)
    In production, tokens expire. The session handler lets the SDK request a fresh token from your backend without interrupting the user.

```typescript TypeScript
const sessionHandler: Amity.SessionHandler = {
  sessionWillRenewAccessToken: async (renewal: Amity.AccessTokenRenewal) => {
    try {
      const newToken = await AuthService.refreshToken();
      renewal.renewWithAuthToken(newToken);
    } catch (error) {
      renewal.unableToRetrieveAuthToken();
    }
  },
};
```

    Full reference → [Authentication](/social-plus-sdk/getting-started/authentication)
    Always call `secureLogout()` when the user logs out. This clears the session, stops real-time connections, and unregisters push tokens.

```typescript TypeScript
await Client.secureLogout();
```

    Full reference → [Authentication](/social-plus-sdk/getting-started/authentication)

---

## Connect to Moderation & Analytics

    Track how many visitors browse vs. convert to authenticated users. Visitor device IDs are available via `client.getVisitorDeviceId()` for analytics attribution.
    Use `Client.loginAsBot()` for search engine crawlers to index public content. Bots have even more restricted permissions than visitors — they can only read, never interact.

    → [Visitor Mode — Bot Users](/social-plus-sdk/getting-started/visitor-mode)
    Receive a `user.created` webhook event when a visitor converts to an authenticated user (first login). Use this to trigger welcome emails or onboarding flows.

    → [Webhook Events](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Hardcoding auth tokens in client-side code** — Auth tokens should be generated server-side. Embedding them in your app exposes them to extraction.

```typescript
// ❌ Bad — token in source code
await Client.login({ userId: 'u1', authToken: 'hardcoded-secret' });

// ✅ Good — fetch token from your backend
const { authToken } = await yourServer.getAmityToken(currentUser.id);
await Client.login({ userId: currentUser.id, authToken });
```

**Skipping the session handler** — Without a session handler, expired sessions silently fail. Always implement `sessionHandler` to detect token expiry and re-authenticate.

**Calling write APIs as a visitor** — Visitors are read-only. Attempting to create posts or reactions as a visitor throws a permission error. Gate write actions behind an authentication check.

## Best Practices

    - Show a subtle "Sign up for full access" banner while visitors browse — don't block the experience
    - Track which actions visitors attempt most (post, react, comment) to optimize your signup prompt placement
    - Pre-fill the display name from your auth provider so users don't have to type it twice
    - Gate write actions at the UI layer (disable buttons) rather than catching SDK errors
    - **Never ship without auth tokens in production** — without them, anyone can impersonate any `userId`
    - Use `secureLogout()` on every logout path (manual logout, session expiry, account deletion)
    - Implement the session handler — without it, sessions will fail silently when tokens expire
    - Store auth tokens server-side and pass them to the client at login time; never generate tokens client-side
    - Visitors skip MQTT connections and push notification registration automatically — no extra optimization needed
    - Cache the user type check result per session; `getCurrentUserType()` is synchronous and fast
    - For SSR/SEO, use bot mode to pre-render public content without consuming authenticated user slots

---

**Dive deeper**: [Getting Started Reference](/social-plus-sdk/getting-started/overview) has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

## Next Steps

  title="Your next step → Build a Social Feed"
  icon="arrow-right"
  href="/use-cases/social/build-a-social-feed"
>
  Users can sign in — now give them a feed full of content to explore.

Or explore related guides:

    Build the profile page your new users land on
    Show the feed that visitors browse before signing up
    Set up push notifications after first login

## Use Cases — Livestream

### [Livestream](https://learn.social.plus/use-cases/social/livestream/overview)

> Go live with co-hosting, room management, live chat, product tagging, and viewer analytics.

<img
    src="/images/Livestream (1).png"
    alt="Livestream viewer experience showing co-host video, live chat overlay, and reaction emojis"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

social.plus provides a full livestream stack built on top of LiveKit. A broadcast lives inside a **Room**, which owns the live chat channel, co-host invitations, and recording lifecycle. Products are tagged on the published room post (the child room post), not on the Room entity itself. This section breaks the livestream workflow into focused guides.

## Architecture

```mermaid
graph TD
    A[Host creates Room] --> B[Room is IDLE]
    B --> C[Host gets broadcast credentials]
    C --> D[Host connects to LiveKit]
    D --> E[Room goes LIVE]

    E --> F[Viewers watch stream]
    E --> G[Live chat channel active]
    E --> H[Co-hosts invited & join]
    E --> I[Products pinned to stream]

    F --> J[Watch session analytics]
    G --> K[Reactions & mentions]
    H --> L[Multi-host video layout]
    I --> M[Viewers browse & click products]

    E --> N[Host stops broadcast]
    N --> O[Room status: ENDED]
    O --> P[Recording processed]
    P --> Q[Room status: RECORDED]
    Q --> R[Video-on-demand playback]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A,N action
    class E decision
    class B,C,D,F,G,H,I,J,K,L,M,O,P process
    class Q,R outcome
```

## Room Lifecycle

Every livestream session is a **Room**. A Room transitions through these states:

| State | Meaning | Available actions |
|---|---|---|
| `IDLE` | Room created, not yet broadcasting | Start broadcast, invite co-hosts, delete |
| `LIVE` | Currently broadcasting | Stream, invite co-hosts, pin products, live chat |
| `ENDED` | Broadcast stopped, recording processing | Wait for recording |
| `RECORDED` | Recording available for playback | Video-on-demand playback |

```mermaid
stateDiagram-v2
    [*] --> IDLE : createRoom()
    IDLE --> LIVE : connect to LiveKit
    LIVE --> ENDED : stopBroadcast()
    LIVE --> LIVE : reconnect after drop
    ENDED --> RECORDED : recording ready
    RECORDED --> [*]
```

## Choose Your Approach

    Pre-built UI for stream creation, co-hosting, viewing, live chat, and product tagging. Drop in and go — no LiveKit wiring needed. → iOS · Android · Web
    Build a custom livestream experience with the APIs covered in the guides below. You manage the LiveKit connection, UI layout, and player.

## Guides

    Create a room, get broadcaster credentials, connect to LiveKit, monitor room status, and access recordings.
    Invite co-hosts, accept/decline invitations, manage the multi-host stage, and handle co-host events.
    Wire up real-time chat alongside the video, show viewer count, reactions, mentions, and moderation controls.
    Tag products to a livestream post, pin/unpin featured products, and track viewer clicks and impressions.

## Prerequisites

All guides in this section assume:
- SDK installed and authenticated → [SDK Setup](/social-plus-sdk/getting-started/overview)
- Video SDK configured → [Video Getting Started](/social-plus-sdk/video-new/broadcasting/overview)
- A `communityId` to host the room (rooms are community-only)
- `livekit-client` package installed (for SDK approach)

**Dive deeper**: [Video SDK Reference](/social-plus-sdk/video-new/broadcasting/overview) has full parameter tables, method signatures, and platform-specific details for every API used in these guides.

---

### [Go Live & Room Management](https://learn.social.plus/use-cases/social/livestream/go-live-and-room-management)

> Create broadcast rooms, connect to LiveKit, monitor room lifecycle, query live rooms, and access recordings.

```typescript
import { RoomRepository, PostRepository } from '@amityco/ts-sdk';
import { Room as LiveKitRoom } from 'livekit-client';

// 1. Create a room with live chat enabled
const room = await RoomRepository.createRoom({
  title: 'Friday AMA', channelEnabled: true,
});

// 2. Publish a livestream post
await PostRepository.createPost({
  targetType: 'community', targetId: communityId,
  dataType: 'livestream', data: { streamId: room.roomId },
});

// 3. Get broadcaster credentials & connect
const bd = await RoomRepository.getBroadcasterData(room.roomId);
const lk = new LiveKitRoom();
await lk.connect(bd.coHostUrl, bd.coHostToken);
await lk.localParticipant.setCameraEnabled(true);
await lk.localParticipant.setMicrophoneEnabled(true);

// 4. Stop & get recording
await lk.disconnect();
await RoomRepository.stopRoom(room.roomId);
```
Full walkthrough below ↓

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

  <img
    src="/images/Livestream(4).png"
    alt="Host broadcasting a livestream with live chat messages and reactions visible"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

This guide covers the host's journey: create a room, wire up the broadcast, monitor lifecycle transitions, query live rooms for a "Live Now" section, and access recordings after the stream ends.

```mermaid
sequenceDiagram
    participant Host
    participant SDK as social.plus SDK
    participant LK as LiveKit
    participant Viewers

    Host->>SDK: createRoom()
    SDK-->>Host: room (IDLE)
    Host->>SDK: createPost(livestream)
    Host->>SDK: getBroadcastData(roomId)
    SDK-->>Host: coHostUrl + coHostToken
    Host->>LK: connect(url, token)
    Host->>LK: setCameraEnabled(true)
    Note over Host,LK: Room is now LIVE
    Viewers->>LK: Watch stream
    Host->>LK: disconnect()
    Host->>SDK: stop(roomId)
    Note over SDK: Room → ENDED → RECORDED
    Viewers->>SDK: getRecordedUrls(roomId)
```

**Prerequisites**: SDK + Video SDK installed and authenticated → [Video Getting Started](/social-plus-sdk/video-new/broadcasting/overview). A `communityId` is required — rooms are community-only.

---

## Quick Start: Create a Room and Go Live

```typescript
const room = await RoomRepository.createRoom({
  title: 'Product Launch Event',
  description: 'Join us for the unveiling',
  channelEnabled: true,  // auto-creates a live chat channel
});
console.log('Room created:', room.roomId, '— status:', room.status); // IDLE
```

Full reference → [Create Room](/social-plus-sdk/video-new/broadcasting/create-room)

---

## Step-by-Step Implementation

    A room is the container for a livestream session. Set `channelEnabled: true` to automatically create a live chat channel for viewer comments.

```typescript
import { RoomRepository } from '@amityco/ts-sdk';

const room = await RoomRepository.createRoom({
  title: 'Weekly Q&A Session',
  description: 'Ask us anything',
  thumbnailFileId: null,
  metadata: { category: 'education' },
  channelEnabled: true,
  parentRoomId: null,
});
```

    Full reference → [Create Room](/social-plus-sdk/video-new/broadcasting/create-room)
    Create a post in the community feed that links to the room. This shows a "LIVE" badge in the feed while the room is broadcasting.

```typescript
import { PostRepository, PostContentType } from '@amityco/ts-sdk';

const { data: post } = await PostRepository.createPost({
  dataType: PostContentType.LIVESTREAM,
  targetType: 'community',
  targetId: communityId,
  data: { text: 'We are live!', streamId: room.roomId },
});
```

    Full reference → [Live Stream Post](/social-plus-sdk/social/content-management/posts/creation/live-stream-post)
    Fetch the LiveKit URL and token, then connect the host's camera and microphone.

```typescript
import { Room as LiveKitRoom, RoomEvent } from 'livekit-client';

const broadcastData = await RoomRepository.getBroadcasterData(room.roomId);

const liveKitRoom = new LiveKitRoom();
liveKitRoom.on(RoomEvent.Connected, () => console.log('Connected!'));
liveKitRoom.on(RoomEvent.Disconnected, (reason) => console.log('Disconnected:', reason));

await liveKitRoom.connect(broadcastData.coHostUrl, broadcastData.coHostToken);
await liveKitRoom.localParticipant.setCameraEnabled(true);
await liveKitRoom.localParticipant.setMicrophoneEnabled(true);
// Room status is now LIVE
```

    Full reference → [Start Broadcasting](/social-plus-sdk/video-new/broadcasting/start-broadcasting)
    Observe the room to update your UI for each status transition.

```typescript
const roomLiveObject = RoomRepository.getRoom(room.roomId);

roomLiveObject.on('dataUpdated', (room) => {
  switch (room.status) {
    case 'idle':     showUI('Ready to start'); break;
    case 'live':     showUI('Broadcasting'); break;
    case 'ended':    showUI('Stream ended — processing recording…'); break;
    case 'recorded': showUI('Recording available'); break;
  }
});
```

    Full reference → [Manage Rooms](/social-plus-sdk/video-new/broadcasting/manage-rooms)
    Show currently-active livestreams in your app.

```typescript
const liveRooms = RoomRepository.getRooms({
  statuses: ['live'],
  types: ['co_hosts'],
  isDeleted: false,
  sortBy: 'lastCreated',
});

liveRooms.on('dataUpdated', (rooms) => {
  console.log('Currently live:', rooms.length, 'rooms');
});
```

    Full reference → [Manage Rooms](/social-plus-sdk/video-new/broadcasting/manage-rooms)
    Disconnect LiveKit first, then stop the room. Recordings become available within a few minutes.

```typescript
// 1. Disconnect from LiveKit
await liveKitRoom.disconnect();

// 2. Stop the room
await RoomRepository.stopRoom(room.roomId);

// 3. Poll for recording (room status transitions: ENDED → RECORDED)
const recordedUrls = await RoomRepository.getRecordedUrl(room.roomId);
recordedUrls.forEach(url => console.log('Recording:', url));
```

    Full reference → [Recorded Playback](/social-plus-sdk/video-new/broadcasting/recorded-playback)

---

## Admin Console: Manage & Monitor Streams

After streams are created, you can manage them from **Admin Console → Live stream**.

  <img
    src="/images/analytics-and-moderation/console-live-stream-management.png"
    alt="Admin Console live stream management table showing stream titles, types, broadcast status, and moderation results"
  />

Click any stream to see its detail page with recording playback, metadata, and moderation status.

  <img
    src="/images/analytics-and-moderation/console-live-stream-detail.png"
    alt="Admin Console stream detail page showing video player, stream ID, feed details, and moderation labels"
  />

To review stream performance, go to **Admin Console → Video Analytics → Live stream**.

  <img
    src="/images/dashboard-livestream-analytics.png"
    alt="Admin Console livestream analytics showing total streams created, views, unique viewers, and minutes watched"
  />

Click any row in the stream table to see per-stream metrics including concurrent viewers over time and chat messages.

  <img
    src="/images/dashboard-livestream-detail.png"
    alt="Admin Console individual stream analytics showing viewer timeline, chat message count, and reaction count"
  />

---

## Connect to Moderation & Analytics

    Track peak concurrent viewers, total watch time, and engagement per stream in **Admin Console → Analytics → Video**.

    → [Video Analytics](/social-plus-sdk/video-new/analytics/overview)
    Moderators can view and manage all active and past livestreams in **Admin Console → Moderation → Livestream Moderation**.

    → [Livestream Moderation](/analytics-and-moderation/console/moderation/livestream-moderation)
    Receive `stream.started`, `stream.ended`, `recording.completed` webhook events for backend automation (e.g., notify followers, archive recordings).

    → [Stream Events](/social-plus-sdk/video-new/broadcasting/overview) · [Webhooks](/analytics-and-moderation/social+-apis-and-services/webhook-event)

---

## Common Mistakes

**Stopping the room before disconnecting LiveKit** — Always call `liveKitRoom.disconnect()` first, then `RoomRepository.stop(roomId)`. Reversing the order can leave orphaned media tracks.

**Forgetting to end rooms when the stream stops** — If the broadcaster disconnects without calling `stop()`, the room stays in `live` status and appears in "Live Now" feeds as a ghost stream. Always call stop in your cleanup logic.

```typescript
// ❌ Bad — broadcaster crashes, room stays live
window.onbeforeunload = () => { /* nothing */ };

// ✅ Good — end room on disconnect
window.onbeforeunload = () => {
  RoomRepository.stopRoom(roomId);
};
```

**Not refreshing the LiveKit token** — LiveKit tokens expire. If you don't handle token refresh, the video connection drops mid-stream. Implement a token renewal callback.

**Creating rooms without `channelEnabled: true`** — Without this flag, no live chat channel is created and viewers can't comment during the stream. Almost all livestream UIs need live chat.

**Not observing the room lifecycle** — The status transitions (`idle → live → ended → recorded`) are asynchronous. Hardcoding delays instead of observing the room live object results in brittle UI states.

**Polling for recordings too aggressively** — Recordings take a few minutes to process. Use the room's live object with a `dataUpdated` listener to detect when `status === 'recorded'` rather than polling every second.

## Best Practices

    - Pre-fetch `getBroadcastData()` before the user taps "Go Live" to cut startup time
    - Request camera and microphone permissions during the room creation step, not at connect time
    - Show a preview of the camera feed while the LiveKit connection is establishing
    - Listen for `RoomEvent.Reconnecting` and `RoomEvent.Reconnected` from LiveKit
    - Show a "Reconnecting…" banner to the host — don't silently drop to ended
    - Configure LiveKit's `autoSubscribe` and `reconnectPolicy` for aggressive retry
    - Show a 3-second countdown before going live so the broadcaster can prepare
    - Display a "LIVE" badge with a pulsing animation on the post card in the feed
    - Show concurrent viewer count in real-time using the room's participant data
    - Provide camera flip, mute, and end-stream controls in a floating overlay
    - Auto-play the livestream on mute when the post enters the viewport — require a tap for audio
    - Show the live chat alongside the video in a split-screen layout
    - Allow viewers to send reactions (emoji) that float across the video
    - When the stream ends, show a "Stream ended" card with a link to the recording when available
    - The livestream post stays in the feed after the stream ends — update it to show the recording thumbnail
    - Store recording URLs in your backend; platform URLs may have retention policies
    - Offer a "Watch replay" CTA on the post once `status === 'recorded'`

---

## Next Steps

  title="Your next step → Short-Form Video Clips"
  icon="arrow-right"
  href="/use-cases/social/short-form-video-clips"
>
  Livestreams are running — now add TikTok-style clip posts for shorter, snackable video content.

Or explore related guides:

    Invite co-hosts to share the stage during a broadcast.
    Wire up chat, reactions, and viewer count alongside the video.
    Pin products to the stream for live commerce.

---

### [Live Chat & Engagement](https://learn.social.plus/use-cases/social/livestream/live-chat-and-engagement)

> Add real-time chat, reactions, viewer counts, and moderation alongside your livestream.

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

```typescript
import { ChannelRepository } from '@amityco/ts-sdk';

// 1. Create the live chat channel (after room + post exist)
const channel = await ChannelRepository.createChannel({
  displayName: room.title,
  type: 'live',
  postId: post.postId,
  roomId: room.roomId,
});

// 2. Drop in the UIKit component — that's it
// React: <AmityLiveChatPage channelId={channel.channelId} />
// iOS:   AmityLiveChatPage(channelId: channel.channelId)
// Android: AmityLiveChatPage(channelId = channel.channelId)
```
Full walkthrough below ↓

  <img
    src="/images/Livestream (2).png"
    alt="Livestream viewer with host-badged chat message, viewer reply, and thumbs-up reaction button"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

Every livestream needs a chat. This guide walks through creating the live chat channel, wiring up the UIKit chat components (or building with the SDK directly), adding reactions, and tracking viewer engagement.

```mermaid
graph LR
    A[Create Room] --> B[Create Post]
    B --> C[Create Channel]
    C --> D{Choose approach}
    D -->|UIKit| E["AmityLiveChatPage<br/>(header + messages + compose)"]
    D -->|SDK| F[Custom Chat UI]
    E --> G[Live viewers see chat]
    F --> G
```

**Prerequisites**:
- A room and livestream post already exist → [Go Live & Room Management](/use-cases/social/livestream/go-live-and-room-management)
- UIKit installed if using the pre-built components → [UIKit Getting Started](/uikit/getting-started/overview)

**Channels are NOT auto-created.** Setting `channelEnabled: true` on the room only flags that a channel is supported. You must manually create the live channel after the post is created, passing both `postId` and `roomId`.

---

## Step 1: Create the Live Chat Channel

Create the channel after the room and livestream post exist. The channel needs both the `postId` and `roomId` to be properly linked.

```typescript
const channel = await ChannelRepository.createChannel({
    displayName: room.title,
    type: 'live',
    postId: post.postId,
    roomId: room.roomId,
});

console.log('Live chat channel created:', channel.channelId);
```

Once created, the channel ID is also available on the room object as `room.channelId`.

---

## Step 2: Add the Chat UI

### Option A: UIKit (recommended)

Drop in a single component for a full chat experience — header with channel name + member count, scrolling message list, and compose bar with mentions and reactions.

```swift
import AmityUIKit

let liveChatPage = AmityLiveChatPage(channelId: channel.channelId)

// Use in SwiftUI directly, or wrap for UIKit:
let viewController = AmitySwiftUIHostingController(rootView: liveChatPage)
present(viewController, animated: true)
```
```kotlin
import co.amity.socialplus.uikit.AmityLiveChatPage

@Composable
fun LiveChatScreen(channelId: String) {
    AmityLiveChatPage(channelId = channelId)
}
```
```tsx
import { AmityLiveChatPage } from '@amityco/ui-kit';

function LiveChat({ channelId }: { channelId: string }) {
  return <AmityLiveChatPage channelId={channelId} />;
}
```

`AmityLiveChatPage` bundles three sub-components you can also use individually:

| Component | What it does |
|-----------|-------------|
| `AmityLiveChatHeader` | Channel name, avatar, live member count |
| `AmityLiveChatMessageList` | Scrolling messages with copy, reply, delete, and flag actions |
| `AmityLiveChatMessageComposeBar` | Text input with `@mention` suggestions, reply, and character limit |

Full component reference → [Live Chat Components](/uikit/components/chat/live-chat)

### Option B: Build with the SDK

If you need a fully custom UI, use the Chat SDK to send and observe messages directly.

```typescript
import { MessageRepository, ChannelRepository, ReactionRepository } from '@amityco/ts-sdk';

// Send a message
await MessageRepository.createMessage({
  subChannelId: channel.channelId,
  dataType: 'text',
  data: { text: 'Hello from the stream!' },
});

// Observe messages in real time
const unsubscribe = MessageRepository.getMessages(
  { subChannelId: channel.channelId, limit: 50 },
  ({ data, loading, error }) => {
    if (data) renderMessages(data);
  },
);
```

Full reference → [Chat SDK](/social-plus-sdk/chat/overview)

---

## Step 3: Reactions

Live chat messages support emoji reactions to drive engagement during the stream.

### UIKit

The `AmityReactionList` component renders reaction counts and user lists out of the box:

```typescript
const reactionList = AmityReactionList({
  referenceId: message.messageId,
  referenceType: 'message',
});
```

### SDK

Add and remove reactions programmatically:

```typescript
// Add a reaction
await ReactionRepository.addReaction('message', message.messageId, 'fire');

// Remove a reaction
await ReactionRepository.removeReaction('message', message.messageId, 'fire');
```

---

## Step 4: Viewer Count & Channel Info

The live chat channel exposes real-time metadata you can display alongside the stream:

| Property | What it tells you |
|----------|-------------------|
| `channel.memberCount` | Total members who joined the channel |
| `channel.metadata` | Custom data (e.g., pinned announcement) |
| Room `watcherCount` (via analytics) | Active viewers watching the stream |

The `AmityLiveChatHeader` UIKit component renders member count automatically.

---

## Step 5: Moderation

    Any user can flag an inappropriate message. Flagged messages appear in the Admin Console for moderator review.

```typescript
await MessageRepository.flagMessage(message.messageId);
```
    Community moderators and admins can hard-delete messages:

```typescript
await MessageRepository.deleteMessage(message.messageId);
```
    Remove disruptive users from the live chat channel:

```typescript
await ChannelRepository.Moderation.banMembers(channel.channelId, ['user-id']);
```
    Enable AI moderation in **Admin Console → AI Content Moderation** to auto-flag or auto-remove messages matching your policy. Works in real-time for live chat.

    → [AI Content Moderation](/analytics-and-moderation/console/ai-content-moderation)

---

## Common Mistakes

**Forgetting to create the channel** — `channelEnabled: true` does NOT auto-create the channel. You must call `createChannel()` with the `postId` and `roomId` after both exist. Without this step, `room.channelId` is null and the chat UI renders nothing.

**Creating the channel before the post** — The channel needs the `postId` to be linked properly. Always create in order: room → post → channel.

**Not handling high message volume** — Live streams can generate hundreds of messages per second. Use UIKit's built-in virtualization, or if building custom, limit the visible message window and batch DOM updates.

## Best Practices

    - On desktop/tablet, show chat in a right panel alongside the video player
    - On mobile, use a bottom sheet or overlay that can be swiped away
    - Keep the compose bar always visible — don't hide it behind a tap
    - Use UIKit's `AmityLiveChatPage` which is optimized for high-volume streams
    - If building custom, debounce re-renders and virtualize the message list
    - Consider showing only the last 100 messages and lazy-loading history on scroll-up
    - Pin an announcement message at the top of chat (use channel `metadata`)
    - Show host and co-host messages with a distinct badge color
    - Add a "slow mode" (rate limit) during peak moments to keep chat readable

---

## Next Steps

    Room creation, broadcast setup, and lifecycle management.
    Invite co-hosts to share the stage during a broadcast.
    Pin products to the stream for live commerce.

---

### [Co-Hosting](https://learn.social.plus/use-cases/social/livestream/co-hosting)

> Invite co-hosts, accept or decline invitations, join the broadcast together, and manage co-host permissions.

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

```typescript
import { RoomRepository, InvitationRepository } from '@amityco/ts-sdk';
import { Room as LiveKitRoom } from 'livekit-client';

// HOST: invite a co-host
await room.createInvitation('co-host-user-id');

// CO-HOST: poll for invitation & accept
const invitation = await room.getInvitation();
if (invitation?.status === 'pending') await invitation.accept();

// CO-HOST: get credentials & go live
const bd = await RoomRepository.getBroadcasterData(room.roomId);
const lk = new LiveKitRoom();
await lk.connect(bd.coHostUrl, bd.coHostToken);
await lk.localParticipant.setCameraEnabled(true);
await lk.localParticipant.setMicrophoneEnabled(true);
```
Full walkthrough below ↓

  <img
    src="/images/Livestream (1).png"
    alt="Livestream showing host in main view and co-host Carla Philips in secondary view, with live chat messages and reaction emojis"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

Co-hosting lets multiple broadcasters share the stage during a live session. This guide covers both sides of the flow — the **host** sending and managing invitations, and the **co-host** accepting and joining the broadcast.

```mermaid
sequenceDiagram
    participant Host
    participant SDK as social.plus SDK
    participant CoHost as Co-Host
    participant LK as LiveKit

    Host->>SDK: createInvitation(userId)
    SDK-->>CoHost: Invitation (pending)
    CoHost->>SDK: getMyRoomInvitations()
    CoHost->>SDK: accept()
    SDK-->>Host: Invitation status → approved
    CoHost->>SDK: getBroadcastData(roomId)
    SDK-->>CoHost: coHostUrl + coHostToken
    CoHost->>LK: connect(url, token)
    CoHost->>LK: setCameraEnabled(true)
    Note over Host,LK: Both are now broadcasting
```

**Prerequisites**: A room must already exist and the host must be connected to LiveKit. See [Go Live & Room Management](/use-cases/social/livestream/go-live-and-room-management) first.

---

## How Co-Hosting Works

| Role | Can do | Can't do |
|------|--------|----------|
| **Host** | Send / cancel invitations, remove co-hosts, stop room | — |
| **Co-Host** | Broadcast audio + video, interact in chat | Stop room, send invitations |

Invitation statuses:

| Status | Meaning |
|--------|---------|
| `pending` | Awaiting the invitee's response |
| `approved` | Invitee accepted — ready to join broadcast |
| `rejected` | Invitee declined |
| `cancelled` | Host cancelled before invitee responded |

---

## Host Side

    Invitations are sent one user at a time. The host must already have a room.

```typescript
await room.createInvitation(userId);
```

    To invite multiple co-hosts, call `createInvitation` once per user.
    Observe all invitations you've sent to show pending / accepted / declined states in your UI.

```typescript
const unsubscribe = InvitationRepository.getInvitations(
  {
    targetId: roomId,
    targetType: InvitationTargetType.Room,
    limit: 20,
  },
  ({ data, loading, error }) => {
    if (data) {
      data.forEach(inv => console.log(inv.userId, inv.status));
    }
  },
);
```
    Cancel before the invitee responds — e.g., if you sent the wrong user.

```typescript
await invitation.cancel();
```

---

## Co-Host Side

    Poll or observe your pending room invitations. Show them as an in-app notification or banner.

```typescript
const unsubscribe = InvitationRepository.getMyCommunityInvitations(
  { limit: 20 },
  ({ data }) => {
    const pending = data?.filter(inv => inv.status === 'pending');
    // Show pending invitations to the user
  },
);
```
    Present an "Accept / Decline" UI. Both operations are one-liners.

```typescript
// Accept
await invitation.accept();

// Decline
await invitation.reject();
```
    After accepting, fetch broadcast credentials and connect to LiveKit — same flow as the host.

```typescript
const broadcastData = await RoomRepository.getBroadcasterData(roomId);
const liveKitRoom = new LiveKitRoom();
await liveKitRoom.connect(broadcastData.coHostUrl, broadcastData.coHostToken);
await liveKitRoom.localParticipant.setCameraEnabled(true);
await liveKitRoom.localParticipant.setMicrophoneEnabled(true);
```

---

## UIKit: Pre-Built Co-Host Components

If you're using UIKit, the co-hosting UI is handled for you:

| Component | What it does | Platforms |
|-----------|-------------|-----------|
| `AmityLivestreamInviteCoHostPage` | Full-screen invite picker for the host | iOS, Android, Web |
| `AmityLivestreamCoHostStage` | Grid layout showing all active co-hosts | iOS, Android, Web |

See the component reference → [Livestream Components](/uikit/components/social/livestream)

---

## Common Mistakes

**Calling `getBroadcastData` before accepting** — The co-host must accept the invitation first. Calling `getBroadcastData` while the invitation is still `pending` or `rejected` will fail.

**Not listening for invitation status changes** — Use the live collection (`getInvitations` / `getMyRoomInvitations`) instead of a one-shot fetch. Statuses update in real-time (e.g., host cancels while you're looking at the invite).

**Assuming the room is still live** — Between the invitation and the accept, the host may have stopped the stream. Always check `room.status === 'live'` before calling `getBroadcastData`.

## Best Practices

    - Show pending invitations as a prominent banner or bottom-sheet, not a buried list
    - Include the host's display name and room title in the invitation UI
    - After accepting, navigate directly to a "Preparing to go live…" screen
    - If a co-host's LiveKit connection drops, listen for `RoomEvent.Disconnected` and show a "Reconnecting" state
    - Give co-hosts a "Leave stage" button that disconnects from LiveKit without ending the room
    - The host should see a visual indicator when a co-host goes offline
    - Each co-host adds a video track — bandwidth and layout get complex above 4–6 hosts
    - Consider a grid layout that caps visible tiles and puts overflow in a scrollable strip
    - Test on lower-end devices to verify performance with multiple video tracks

---

## Next Steps

    Room creation, broadcast setup, and lifecycle management.
    Wire up chat, reactions, and viewer count alongside the video.
    Pin products to the stream for live commerce.

---

### [Product Tagging](https://learn.social.plus/use-cases/social/livestream/product-tagging)

> Tag products on a livestream, pin featured items for viewers, grant co-host permissions, and track engagement analytics.

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

```typescript
import { PostRepository } from '@amityco/ts-sdk';

// 1. Create a room post with product tags + pinned product
const post = await PostRepository.createRoomPost({
  targetType: 'community', targetId: communityId,
  data: { roomId: room.roomId, title: 'Flash Sale Live!' },
  productTags: [
    { productId: 'prod_001' },
    { productId: 'prod_002' },
  ],
  pinnedProductId: 'prod_001',
});

// 2. Swap pinned product mid-stream (uses CHILD post ID)
await PostRepository.pinProduct(childPostId, 'prod_002');

// 3. Unpin when done showcasing
await PostRepository.unpinProduct(childPostId);
```
Full walkthrough below ↓

  <img
    src="/images/livestream-product-tagging.png"
    alt="Livestream with a pinned product card, Unpin button, viewer count, and live chat"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

Product tagging turns a livestream into a shoppable experience. Hosts tag products from the catalog, pin one at a time as a prominent overlay, and viewers can browse and click through — all without leaving the stream.

```mermaid
graph LR
    A[Create Room Post<br/>with productTags] --> B[Pin a product]
    B --> C[Viewers see overlay]
    C --> D[Swap pin mid-stream]
    D --> E[Unpin / remove tags]
    E --> F[Analytics:<br/>views + clicks]
```

**Prerequisites**:
- A room and livestream post already exist → [Go Live & Room Management](/use-cases/social/livestream/go-live-and-room-management)
- **Product Catalog** is configured and enabled in your Admin Console
- Available on **iOS, Android, and Web** only (Flutter / React Native not yet supported)

**Child Post ID** — `pinProduct`, `unpinProduct`, and `updateProductTags` all operate on the **child** room post, not the parent. Use the child post ID returned at creation.

---

## How Product Tagging Works

| Phase | Who can tag | Who can pin |
|-------|-----------|-------------|
| **Pre-live** (backstage) | Host only | Host only |
| **During livestream** | Host + co-host (if granted) | Host + co-host (if granted) |
| **Post-live** (management) | Host only | — |

Viewers can browse and open tagged products during all phases, including replay.

| Limit | Value |
|-------|-------|
| Max products per livestream | 20 |
| Simultaneously pinned products | 1 |

---

## Admin Console: Set Up Your Product Catalogue

Before you can tag products in a livestream, your catalogue must be populated in **Admin Console → Product catalogue**.

    Navigate to **Product catalogue** in the Admin Console sidebar.

      <img
        src="/images/analytics-and-moderation/console/product-management/product-catalogue-list.png"
        alt="Admin Console Product Catalogue showing product list with IDs, names, prices, statuses, and action buttons"
      />
    Click **+ Add product** to create products individually, or use **Import** to upload a CSV for bulk creation. Each product needs an ID, name, URL, and status set to **Active**.

      <img
        src="/images/analytics-and-moderation/console/product-management/add-product.png"
        alt="Admin Console Add Product form with fields for Product ID, Status, Product name, Product URL, Price, and image upload"
      />
    Only products with **Active** status show up in the tag-product search on the app side. Archived products are hidden from tagging.

Full Admin Console guide → [Product Catalogue](/analytics-and-moderation/console/product-management/overview)

---

## In-App: Tag & Pin Products

Once products exist in the catalogue, hosts (and co-hosts with permission) can tag and pin them during the stream.

      <img
        src="/images/product-tag-selection.png"
        alt="Tag products bottom sheet showing selected products at top, search field, and catalogue results with checkboxes"
      />
      <img
        src="/images/manage-product-tag-list.png"
        alt="Tagged products management view showing pinned product, other products with Pin and Delete buttons, and Add products button"
      />

### Viewer experience

Viewers see a tag icon with a badge count. Tapping opens a scrollable product list with prices and "View" buttons.

  <img
    src="/images/product-tag-list-livestream.png"
    alt="Products tagged bottom sheet showing product thumbnails, names, prices, Pinned badge on first item, and View buttons"
    style={{ maxWidth: "40%", margin: "0 auto", display: "block" }}
  />

---

## Step-by-Step Implementation

    Attach products at creation time. Optionally pre-pin one.

```typescript
const post = await PostRepository.createRoomPost({
  targetType: 'community',
  targetId: communityId,
  data: {
    roomId: room.roomId,
    title: 'Flash Sale',
    text: 'Flash Sale Live! Explore featured products!',
  },
  productTags: [
    { productId: 'prod_001' },
  ],
  pinnedProductId: 'prod_001',
});
```

    Full reference → [Product Tagging SDK](/social-plus-sdk/video-new/broadcasting/overview)
    Only one product can be pinned at a time. Pinning a new product automatically replaces the previous one — no need to unpin first.

```typescript
// Pin a product (uses CHILD post ID)
await PostRepository.pinProduct(childPostId, 'prod_002');

// Unpin the current product
await PostRepository.unpinProduct(childPostId);
```
    `updateProductTags` does a full replacement. To add a product, merge it with the existing array. If the currently pinned product is not in the new array, it is automatically unpinned.

```typescript
await PostRepository.updateProductTags(childPostId, [
  { productId: 'prod_001' },
  { productId: 'prod_002' },
  { productId: 'prod_003' },
]);
```
    By default co-hosts cannot manage products. The host must explicitly grant permission.

```typescript
await RoomRepository.updateCohostPermission(
  room.roomId,
  'cohost_456',
  true, // canManageProductTags
);
```

    Full reference → [Co-Host Management](/social-plus-sdk/video-new/broadcasting/co-host-management)
    Fire view and click analytics to measure which products drive the most interest.

```typescript
// When a product card becomes visible
product.analytics.markAsViewed(
  'livestream_page/product_list/product_item',
  AnalyticsSourceTypeEnum.ROOM,
  roomId,
);

// When a viewer taps the product link
product.analytics.markAsClicked(
  'livestream_page/product_list/product_item',
  AnalyticsSourceTypeEnum.ROOM,
  roomId,
);
```

    Events are fire-and-forget and automatically deduplicated per product per source.

---

## UIKit: Pre-Built Product Tagging Components

If you're using UIKit, the product tagging UI is handled with two shared components:

| Component | Used for | Platforms |
|-----------|---------|-----------|
| `ProductTagSelectionComponent` | Searching and selecting products to tag (up to 20 in livestream mode) | iOS, Android, Web |
| `ManageProductTagListComponent` | Managing tagged products with pin/unpin/remove (host view); browsable read-only list (viewer view) | iOS, Android, Web |

The viewer sees a tag icon with a badge count. Tapping it opens a scrollable product list overlay. Tapping a product opens its link in an in-app browser while the stream continues playing.

Full component reference → [Product Tagging Components](/uikit/components/social/product-tagging) · [Livestream Components](/uikit/components/social/livestream)

---

## Common Mistakes

**Using the parent post ID instead of the child post ID** — `pinProduct`, `unpinProduct`, and `updateProductTags` all require the **child** room post ID. Using the parent ID silently fails or throws an error.

**Calling `updateProductTags` with just the new product** — This is a full replacement, not an append. If you pass only the new product, all existing tags are removed. Always merge with the existing array first.

**Pinning a product that isn't in `productTags`** — The product must already exist in the tag list. Pin it after adding it via `createRoomPost` or `updateProductTags`.

## Best Practices

    - Pre-tag all products before going live so they're ready immediately
    - Pin the highest-margin or most-relevant product first
    - Swap the pinned product every 3–5 minutes to keep the showcase fresh
    - Remove sold-out products from the tag list in real-time
    - Grant product permissions to a dedicated "product manager" co-host
    - Have the host focus on presenting while the co-host manages pin swaps
    - Revoke permissions if a co-host leaves mid-stream
    - Call `markAsViewed` when the product card enters the viewport (use intersection observer on Web)
    - Call `markAsClicked` on tap/click before opening the product URL
    - Review view-to-click ratios in the Admin Console to optimize product placement
    - A/B test pin timing to find the optimal pin duration per product category

---

## Next Steps

    Room creation, broadcast setup, and lifecycle management.
    Invite co-hosts to share the stage during a broadcast.
    Wire up chat, reactions, and viewer count alongside the video.

## Analytics & Moderation — Overview

### [Analytics & Moderation](https://learn.social.plus/analytics-and-moderation/overview)

> Comprehensive tools for monitoring, managing, and moderating your social.plus applications

![Analytics Moderation Dark Pn](/images/Analytics-Moderation-Dark.png)


Monitor your community's health, moderate content effectively, and manage your social.plus applications with powerful administrative tools. This section covers three essential areas for application management and community safety.

    Administrative dashboard for monitoring and moderating your social.plus applications
    Server-to-server APIs for programmatic administration and moderation
    Application lifecycle management, billing, and organizational settings

## Key Capabilities

### **Community Moderation**

- **Content Moderation**: Review, approve, and manage user-generated content
- **User Management**: Handle user behavior, roles, and access controls
- **AI-Powered Tools**: Automated content filtering and detection
- **Reporting Systems**: Comprehensive flagging and review workflows

### **Analytics & Insights**

- **User Activity**: Track engagement, participation, and growth metrics
- **Content Analytics**: Monitor post performance, interactions, and trends
- **Moderation Reports**: Review flagging patterns and moderator performance
- **Custom Dashboards**: Create tailored views for your specific needs

### **Moderation Activity Reports**

Comprehensive audit trail system that tracks all moderation activities across your social.plus applications, providing transparency and accountability for content moderation decisions.

    Monitor all moderation actions including content flags, deletions, user bans, and community removals
    Download detailed CSV reports for compliance auditing and moderation effectiveness analysis

#### **What's Tracked**

The moderation activity report captures all key moderation events:

- **Content Actions**: Post/comment flagging, deletion, and flag clearing
- **User Management**: Global bans, community bans, and user removals
- **Message Moderation**: Chat message flags, deletions, and AI detection events
- **Community Events**: Member bans, removals, and role changes
- **AI Detection**: Automated AI moderation, topic detection, and PII identification

#### **Report Data Structure**

Each report entry includes comprehensive metadata in a structured format:

| Field | Description |
|-------|-------------|
| `network_id` | Your network identifier |
| `user_id` | Public ID of the content creator |
| `event` | Type of moderation event |
| `note` | Reason or note for the action |
| `content_type` | Type of content moderated |
| `content_public_id` | Unique identifier for the content |
| `target_type` | Context type where action occurred |
| `target_id` | Target identifier |
| `is_ai` | Whether action was automated |
| `created_at` | When the event occurred |
| `updated_at` | When the record was last updated |
| `metadata` | Additional context and actor information |

#### **Key Fields**

    - `post.flagged`, `post.deleted`, `post.flagsCleared`
    - `comment.flagged`, `comment.deleted`, `comment.flagsCleared`
    - `v5.message.flagged`, `v5.message.deleted`, `v5.message.flagCleared`
    - `community.userBanned`, `community.userRemoved`
    - `user.didGlobalBan`, `user.flagCleared`
    - `content_type`: Type of content (post, comment, message, community, user)
    - `content_public_id`: Unique identifier for the content
    - `target_type` & `target_id`: Context where the action occurred
    - `user_id`: Public ID of the content creator
    - `is_ai`: Whether the action was performed by AI automation
    - `created_at` & `updated_at`: Timestamps for audit trail
    - `metadata`: Additional context including actor information

#### **Enabling Reports**

**Feature Activation Required**: Moderation activity reports must be enabled before data collection begins. Historical data before activation is not available.

To enable moderation activity reports for your network:

    Use the [Update Moderation Network Settings API](/api-reference/network-setting/update-moderation-configuration) to enable reporting:

```json
{
  "isReportEnabled": true
}
```
    Contact our support team at [support@social.plus](mailto:support@social.plus) to enable moderation activity reports for your network.

    Include your network ID and specify that you need moderation reporting activated.

#### **Use Cases**

    Generate audit trails for regulatory compliance and internal policy reviews
    Analyze moderator activity patterns and decision-making effectiveness
    Compare automated moderation performance against human moderator decisions
    Track moderation trends to identify community health patterns and issues

### **Application Management**

- **Multi-Application Support**: Manage up to 10 applications per organization
- **Regional Configuration**: Set up applications in different geographic regions
- **Billing & Subscriptions**: Monitor usage, MAUs, and subscription plans
- **Team Management**: Collaborate with team members and assign roles

## Getting Started

    Navigate to your Admin Console through the [Admin Portal](https://portal.amity.co) to begin managing your applications.
    Set up content moderation rules, user roles, and community guidelines for your applications.
    Review user engagement, content performance, and community health metrics.
    Implement server-to-server APIs for advanced administrative automation.

## Common Workflows

    1. **Configure Rules**: Set up automated content filtering and AI moderation
    2. **Review Queue**: Process flagged content through moderation dashboard
    3. **Take Actions**: Approve, remove, or escalate content based on guidelines
    4. **Monitor Results**: Track moderation effectiveness and adjust policies
    1. **Assign Roles**: Set up moderators and assign appropriate permissions
    2. **Monitor Behavior**: Track user activity and identify problematic patterns
    3. **Enforce Policies**: Apply warnings, temporary restrictions, or bans
    4. **Handle Appeals**: Process user appeals and review moderation decisions
    1. **Enable Reporting**: Activate moderation activity reports via API or support request
    2. **Monitor Activities**: Track all moderation actions in real-time as they occur
    3. **Generate Reports**: Download CSV reports for analysis and compliance auditing
    4. **Analyze Trends**: Review patterns in moderation actions and moderator performance
    1. **Daily Monitoring**: Check key metrics for user activity and engagement
    2. **Trend Analysis**: Identify patterns in content performance and user behavior
    3. **Report Generation**: Create regular reports for stakeholders
    4. **Strategy Adjustment**: Modify features and policies based on data insights

## Integration with SDK

The analytics and moderation tools work seamlessly with your social.plus SDK implementation:

- **Console Settings** automatically apply to SDK behavior
- **API Actions** can be triggered by SDK events and webhooks
- **Moderation Rules** configured in console affect SDK content validation
- **Analytics Data** reflects all SDK-driven user activities

## Best Practices

  **Privacy & Compliance**: Always ensure your moderation and analytics practices comply with relevant privacy laws and platform policies. Maintain transparency with users about data collection and moderation actions.

- **Clear Policies**: Establish and communicate clear community guidelines
- **Balanced Automation**: Combine AI tools with human judgment for best results
- **Regular Review**: Continuously evaluate and improve your moderation processes
- **Data-Driven Decisions**: Use analytics to inform feature and policy changes
- **User Feedback**: Maintain channels for user feedback on moderation decisions

## Next Steps

Choose your area of focus to dive deeper into social.plus administration:

    Learn the administrative dashboard and basic moderation features
    Implement programmatic administration and advanced automation

## Analytics & Moderation — Portal

### [Overview](https://learn.social.plus/analytics-and-moderation/social+-portal/README)

> Comprehensive platform management through Admin Portal - your central hub for application management, billing, analytics, and organizational administration.

Admin Portal is your comprehensive management platform for overseeing social.plus applications, monitoring usage analytics, managing billing and subscriptions, and controlling organizational settings across your entire social.plus ecosystem.

  Access the Admin Portal to manage your applications and account settings.

## Platform Overview

    Create, configure, and manage up to 10 social.plus applications per organization
    Monitor Monthly Active Users (MAUs), usage analytics, and platform metrics
    Complete setup guide for new social.plus Portal users

## Core Features

    ### Multi-Application Support

        **Create New Applications:**

        - Support for up to 10 applications per organization
        - Regional deployment options
        - Custom application configurations
        - Environment-specific settings (development, staging, production)
        **Global Infrastructure:**

        - Multiple server regions available
        - Optimized for low-latency connections
        - Data residency compliance options
        - Automatic failover and redundancy

        **Available Regions:**

        - North America (US)
        - Europe (EU)
        - Asia Pacific (SG)
        **Development Lifecycle:**

        - Separate environments for different stages
        - Easy promotion between environments
        - Configuration migration tools
        - Testing and validation workflows
    ### Platform Analytics

        **Monthly Active Users (MAUs):**

        - Daily MAU tracking
        - Historical usage trends
        - User engagement patterns
        - Growth rate analytics
        **Feature Utilization:**

        - Most popular features
        - User engagement by feature
        - Content creation statistics
    ### Team & Access Control

        **User Access:**

        - Invite team members
        - Assign role-based permissions
        - Manage user access levels
        **Account Security:**

        - Single Sign-On (SSO) integration
        - Access audit logs

## Best Practices

    - **Environment Strategy**: Use separate applications for development, staging, and production
    - **Regional Optimization**: Choose regions closest to your user base
    - **Naming Convention**: Use clear, descriptive names for applications
    - **Documentation**: Maintain documentation for application configurations
    - **API Key Security**: Rotate API keys regularly and store securely
    - **Access Control**: Use principle of least privilege for team permissions
    - **Monitoring**: Regularly review access logs and usage patterns
    - **Compliance**: Stay updated with data protection regulations
    - **Usage Monitoring**: Track MAU usage to avoid overage charges
    - **Resource Management**: Optimize application settings for efficiency
    - **Budget Planning**: Set up billing alerts and notifications

---

---

### [Getting Started](https://learn.social.plus/analytics-and-moderation/social+-portal/getting-started)

> Access and manage your applications, and organization settings through the unified portal

Admin Portal provides three different sign-in options to cater to your organization's needs and preferences. These options are designed to provide convenience and security for users accessing the portal. Access the sign-in page at the Admin Portal.

Access the unified Portal to manage applications, organization configuration, and secure administrator access. This guide covers current sign‑in methods (Email & SAML SSO), rollout, and operational best practices. Google sign-in has been deprecated (@gmail domain).


## Sign-In Options


## SSO (SAML) Enablement Workflow


## Post-SSO Behavior


## Migration Tips


## Metrics & Monitoring

| Metric | Purpose | Healthy Signal | Action Trigger |
|--------|---------|----------------|----------------|
| First Login Success % | Onboarding friction | ≥ 95% | Drop → review IdP attribute mapping |
| Legacy Account Count | Progress toward full SSO adoption | Trending to 0 | Flat > 0 for 2 cycles → enforce cleanup |
| SSO Provision Time | Automation latency | < 30s | Delays → check webhook / IdP latency |
| Failed SAML Assertions | Detect config issues | Near 0 | Spike → validate Audience / ACS URL |
| Duplicate Emails | Identity collision | 0 | Any → merge / remove stale account |

## Troubleshooting

| Issue | Likely Cause | Resolution |
|-------|--------------|-----------|
| SSO option not shown | Org not enabled | Confirm enablement with support |
| Assertion Consumer mismatch | Wrong ACS URL | Update IdP to official URL |
| Audience validation error | Incorrect Audience string | Use urn:amazon:cognito:sp:eu-central-1_gcJoCA15K |
| User loops back to login | Attribute (email) not mapped | Map email claim correctly |
| Duplicate account created | Case variation in email | Normalize email casing & merge |
| Cannot remove legacy account | Still active sessions | Terminate sessions then delete |

## Best Practices


## Related

---

### [Account Management](https://learn.social.plus/analytics-and-moderation/social+-portal/account-management)

> Comprehensive team management and access control in Admin Portal with role-based permissions, user invitations, and collaborative workspace administration.

Manage your organization's Admin Portal access with comprehensive team management capabilities. Control user permissions, facilitate collaboration, and maintain security through role-based access control and user management features.

<iframe width="720" height="405" src="https://www.youtube.com/embed/TAItd6aB-nY?si=6wwfIrZJFESlazcK" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  Account Management enables teams of up to 50 users to collaborate effectively on social.plus applications with granular permission controls and secure access management.

## Overview

    Invite team members and manage collaborative access to applications
    Control access with five distinct role levels and granular permissions
    Streamlined invitation process with email-based user onboarding
    Authentication methods and access control for organizational security

## Team Collaboration

    ### Collaborative Workspace

    **Team Benefits:**

    - Support for up to 50 team members per organization
    - Simultaneous access for multiple users
    - Collaborative application management
    - Shared dashboard and analytics access
    - Coordinated development and operations

    **Collaboration Features:**

    - Real-time activity sharing
    - Audit trails for all actions
    - Team notification systems
    - Shared resource management
    - Coordinated permission management

    **Workspace Organization:**

    - Department-based access control
    - Project-specific team assignments
    - Cross-functional collaboration support
    - External consultant access management
    - Temporary access provisions
    ### Permission Control

        **Common Team Structures:**

        - **Development Teams**: Developers and technical leads
        - **Operations Teams**: Moderators and administrators
        - **Analytics Teams**: Analysts and data scientists
        - **Management Teams**: Executives and project managers
        - **Mixed Teams**: Cross-functional collaboration groups

        **Access Strategies:**

        - Role-based team composition
        - Project-based access grants
        - Temporary contractor access
        - Client collaboration spaces
        - Vendor integration support
        **Efficiency Improvements:**

        - Reduced bottlenecks from single-user access
        - Distributed workload management
        - Specialized role assignments
        - Improved response times
        - Enhanced operational continuity

        **Security Advantages:**

        - Granular permission control
        - Audit trail visibility
        - Access revocation capabilities
        - Role-based security policies
        - Principle of least privilege enforcement

## Roles & Permissions

    ### Permission Levels

        **Dashboard-Focused Role:**

        - **Primary Access**: Dashboard and analytics only
        - **Use Cases**: Data analysis, reporting, performance monitoring
        - **Restrictions**: No application management or billing access
        - **Ideal For**: Data scientists, business analysts, reporting specialists

        **Capabilities:**

        - View comprehensive analytics dashboards
        - Generate and export reports
        - Monitor key performance indicators
        - Track user engagement metrics
        - Analyze platform usage trends

        **Security Benefits:**

        - Read-only access minimizes risk
        - No configuration change capabilities
        - Limited exposure to sensitive data
        - Focused access scope
        - Audit trail for all activities
        **Technical Implementation Role:**

        - **Primary Access**: Application configuration and technical details
        - **Use Cases**: SDK integration, API management, technical configuration
        - **Restrictions**: No dashboard, billing, or member management access
        - **Ideal For**: Software developers, technical integrators, DevOps engineers

        **Technical Capabilities:**

        - View and manage API keys
        - Configure application settings
        - Access technical documentation
        - Monitor integration health
        - Manage development environments

        **Development Workflow:**

        - Safe environment for technical changes
        - Separation from business analytics
        - Focus on implementation tasks
        - Reduced distractions from non-technical features
        - Clear technical responsibility boundaries
        **Content & Community Management:**

        - **Primary Access**: Applications and dashboard for community oversight
        - **Use Cases**: Community management, content moderation, user engagement
        - **Restrictions**: No billing, member management, or financial access
        - **Ideal For**: Community managers, content moderators, customer success teams

        **Moderation Capabilities:**

        - Monitor community health metrics
        - Access user engagement analytics
        - View application performance data
        - Track content and interaction trends
        - Generate community reports

        **Community Focus:**

        - Balanced access to operational and analytical tools
        - Community health monitoring
        - User behavior analysis
        - Content performance tracking
        - Engagement optimization insights
        **Operational Management Role:**

        - **Primary Access**: Full application management and team coordination
        - **Use Cases**: Project management, team coordination, operational oversight
        - **Restrictions**: No billing or plan management access
        - **Ideal For**: Project managers, team leads, operations managers

        **Administrative Capabilities:**

        - Create and edit applications
        - Manage team members and invitations
        - Access comprehensive dashboard analytics
        - Coordinate development and operations
        - Oversee project execution

        **Management Features:**

        - Team member invitation and management
        - Application lifecycle management
        - Cross-project coordination
        - Resource allocation oversight
        - Performance monitoring and reporting
        **Full Organizational Control:**

        - **Primary Access**: Complete platform access including financial management
        - **Use Cases**: Organizational leadership, financial oversight, strategic planning
        - **Capabilities**: All features including billing and user role management
        - **Ideal For**: C-level executives, financial managers, organizational leaders

        **Executive Capabilities:**

        - Full financial oversight and billing management
        - Complete user role management
        - Strategic planning and resource allocation
        - Organizational policy enforcement
        - Vendor and partner relationship management

        **Strategic Features:**

        - Comprehensive business intelligence access
        - Financial performance tracking
        - Strategic decision-making support
        - Organizational compliance oversight
        - Long-term planning and forecasting
    ### Detailed Access Control

    | **Permission**          | **Analyst** | **Developer** | **Moderator** | **Admin** | **Super Admin** |
    | ----------------------- | ----------- | ------------- | ------------- | --------- | --------------- |
    | **View Applications**   | ❌           | ✅             | ✅             | ✅         | ✅               |
    | **Create Applications** | ❌           | ❌             | ❌             | ✅         | ✅               |
    | **Edit Applications**   | ❌           | ❌             | ❌             | ✅         | ✅               |
    | **Delete Applications** | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **View Dashboard**      | ✅           | ❌             | ✅             | ✅         | ✅               |
    | **Export Analytics**    | ✅           | ❌             | ✅             | ✅         | ✅               |
    | **View Billing**        | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **Manage Payments**     | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **View Plan Details**   | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **Upgrade/Downgrade**   | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **View Members**        | ❌           | ❌             | ❌             | ✅         | ✅               |
    | **Invite Members**      | ❌           | ❌             | ❌             | ✅         | ✅               |
    | **Remove Members**      | ❌           | ❌             | ❌             | ❌         | ✅               |
    | **Change Roles**        | ❌           | ❌             | ❌             | ❌         | ✅               |

    ### Advanced Permissions

        **Application Lifecycle:**

        - **Create**: Set up new social.plus applications
        - **Configure**: Modify application settings and parameters
        - **Deploy**: Manage application deployment and environments
        - **Monitor**: Track application performance and health
        - **Archive**: Decommission and archive unused applications

        **Configuration Control:**

        - API key management and rotation
        - Webhook configuration and testing
        - Security settings and access controls
        - Integration setup and management
        - Environment variable management
        **Billing Oversight:**

        - View and manage subscription plans
        - Monitor usage and billing metrics
        - Configure payment methods and billing cycles
        - Generate financial reports and forecasts
        - Manage cost optimization strategies

        **Budget Control:**

        - Set spending limits and alerts
        - Track cost allocation across applications
        - Monitor usage-based billing
        - Manage vendor relationships
        - Plan capacity and scaling costs
        **User Administration:**

        - Invite and onboard new team members
        - Assign and modify user roles
        - Manage user access and permissions
        - Monitor user activity and performance
        - Handle user offboarding and access revocation

        **Collaboration Management:**

        - Facilitate cross-team collaboration
        - Manage project-based access
        - Configure notification preferences
        - Coordinate team communication
        - Oversee compliance and security training

## User Management

    ### Team Member Onboarding

        Navigate to **Account** → **Manage Members** in the Admin Portal
        Click **"Invite Members"** button in the top-right corner
        Enter email address and select appropriate role for the new team member
        Specify which applications the user can access based on their role
        Click **"Invite Member"** to send invitation email
        Track invitation status and follow up as needed
    ### Invitation Management

        **Email-Based Invitations:**

        - Automated invitation email delivery
        - Secure invitation links with expiration
        - Role-specific onboarding information
        - Clear instructions for account setup
        - Support contact information included

        **Invitation Tracking:**

        - Sent invitation monitoring
        - Acceptance status tracking
        - Resend capabilities for expired invitations
        - Bulk invitation management
        - Integration with HR systems

        **Security Measures:**

        - Time-limited invitation links
        - Email verification requirements
        - Domain-based restrictions
        - Multi-factor authentication setup
        - Access audit trail initiation
        **Organization Limits:**

        - Maximum 50 users per organization
        - Role-based distribution recommendations
        - Active user monitoring
        - Seat management and optimization
        - Expansion planning guidance

        **Quota Management:**

        - Current user count tracking
        - Available seat monitoring
        - Usage optimization recommendations
        - Upgrade guidance for larger teams
        - Cost optimization strategies

        **Planning Considerations:**

        - Team growth projections
        - Role distribution strategies
        - Seasonal access requirements
        - Contractor and consultant access
        - Client collaboration needs
    ### Complete User Management

        **New User Setup:**

        - Welcome email with portal access instructions
        - Role-specific training materials and resources
        - Initial configuration guidance
        - Team introduction and contact information
        - Security policy acknowledgment

        **First-Time Experience:**

        - Guided portal tour based on user role
        - Essential feature introductions
        - Relevant documentation access
        - Team communication channel setup
        - Initial task assignments

        **Training & Support:**

        - Role-specific training programs
        - Documentation and resource libraries
        - Mentoring and buddy system options
        - Regular check-ins and feedback sessions
        - Continuous learning opportunities
        **User Activity Monitoring:**

        - Login frequency tracking
        - Feature usage analytics
        - Collaboration pattern analysis
        - Performance contribution assessment
        - Security compliance monitoring

        **Role Evolution:**

        - Performance-based role adjustments
        - Career development pathway support
        - Cross-functional collaboration enablement
        - Skill development recognition
        - Leadership development opportunities

        **Maintenance Tasks:**

        - Regular access reviews and audits
        - Permission updates and adjustments
        - Security policy compliance verification
        - Training completion tracking
        - User satisfaction surveys
        **Access Termination:**

        - Immediate access revocation upon departure
        - Data backup and knowledge transfer
        - Equipment and credential recovery
        - Exit interview and feedback collection
        - Documentation updates and maintenance

        **Security Procedures:**

        - Account deactivation and archival
        - API key revocation and rotation
        - Shared account password changes
        - Access audit trail review
        - Security incident assessment

        **Knowledge Preservation:**

        - Project documentation handover
        - Configuration and setup documentation
        - Client relationship transition
        - Institutional knowledge capture
        - Successor training and preparation

## Security Features

    ### Secure Access Control

        **Super Admin Authentication:**

        - Single Sign-On (SSO) integration
        - SAML-based authentication
        - Multi-factor authentication (MFA)
        - Domain-based access controls
        - Corporate identity provider integration

        **Standard User Authentication:**

        - Email and password authentication
        - Strong password policy enforcement
        - Account lockout protection
        - Password reset and recovery
        - Session management and timeouts

        **Enhanced Security Features:**

        - Conditional access policies
        - Risk-based authentication
        - Device registration and management
        - Geographic access restrictions
        - Time-based access controls
        **Access Control Policies:**

        - Role-based access control (RBAC)
        - Principle of least privilege
        - Regular access reviews and audits
        - Automated provisioning and deprovisioning
        - Compliance monitoring and reporting

        **Security Compliance:**

        - Industry standard compliance (SOC 2, ISO 27001)
        - Data protection regulation adherence (GDPR, CCPA)
        - Security audit trail maintenance
        - Incident response procedures
        - Security awareness training

        **Monitoring & Alerting:**

        - Failed authentication monitoring
        - Suspicious activity detection
        - Access pattern analysis
        - Real-time security alerts
        - Comprehensive audit logging
    ### Advanced Security Management

        **Granular Controls:**

        - Feature-level permission assignment
        - Time-based access restrictions
        - IP address whitelist management
        - Device-based access controls
        - Application-specific permissions

        **Dynamic Access Control:**

        - Context-aware permission adjustment
        - Risk-based access modification
        - Temporary privilege elevation
        - Emergency access procedures
        - Automated permission reviews

        **Compliance Features:**

        - Segregation of duties enforcement
        - Approval workflows for sensitive actions
        - Change management controls
        - Data access governance
        - Privacy protection measures
        **Activity Monitoring:**

        - Comprehensive audit trail logging
        - User activity tracking and analysis
        - Permission change notifications
        - Security event monitoring
        - Compliance report generation

        **Regulatory Compliance:**

        - GDPR data protection compliance
        - SOX financial controls adherence
        - HIPAA healthcare privacy protection
        - Industry-specific compliance support
        - Regular compliance assessments

        **Risk Management:**

        - Continuous risk assessment
        - Threat detection and response
        - Vulnerability management
        - Incident response procedures
        - Business continuity planning

## Best Practices

    **Effective Team Structure:**

    - **Role Alignment**: Match user roles to actual job responsibilities
    - **Minimal Access**: Apply principle of least privilege consistently
    - **Regular Reviews**: Conduct quarterly access and role reviews
    - **Clear Responsibilities**: Define role boundaries and expectations clearly
    - **Documentation**: Maintain current role and access documentation

    **Collaboration Optimization:**

    - Create cross-functional teams for projects
    - Establish clear communication channels
    - Define escalation procedures for issues
    - Implement regular team sync meetings
    - Foster knowledge sharing and mentoring
    **Security Best Practices:**

    - **Access Reviews**: Conduct regular access audits and reviews
    - **Strong Authentication**: Implement MFA for all users
    - **Monitoring**: Monitor user activity and access patterns
    - **Training**: Provide regular security awareness training
    - **Incident Response**: Maintain clear incident response procedures

    **Compliance Considerations:**

    - Understand regulatory requirements for your industry
    - Implement data protection and privacy controls
    - Maintain comprehensive audit trails
    - Regular compliance assessments and reviews
    - Document security policies and procedures
    **Management Optimization:**

    - **Automation**: Automate routine user management tasks
    - **Scalability**: Plan for team growth and changing needs
    - **Efficiency**: Streamline onboarding and offboarding processes
    - **Performance**: Monitor and optimize team collaboration
    - **Continuous Improvement**: Regularly assess and improve processes

    **Success Metrics:**

    - User satisfaction with access and tools
    - Time to productivity for new team members
    - Security incident frequency and resolution
    - Compliance audit results
    - Team collaboration effectiveness

---

  Effective account management balances security with usability. Regularly review role assignments and access patterns to ensure optimal team collaboration while maintaining security standards.

---

### [Application Management](https://learn.social.plus/analytics-and-moderation/social+-portal/application-management)

> Comprehensive guide to creating, configuring, and managing social.plus applications through the portal, including regional deployment and organizational settings.

<iframe width="720" height="405" src="https://www.youtube.com/embed/Ym4XhKWaEPA?si=dJOPrEacTT7SKamk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  Create and govern up to 50 applications per organization, selecting an immutable data residency region and maintaining clear naming, lifecycle, and audit practices.

    Add new application & region

    Locate by ID / name / plan / region

    Rename application safely

    Choose optimal data residency

    Track approach to 50 app limit

    Apply naming & ownership rules

## Access

    Use Email & Password or SAML SSO.

    Portal sidebar → My Applications.

    Scan list, use search & sort tools.

## Create an Application

    Click “Create Application”.

    Enter unique name; select region (EU, SG, US).

    Confirm you remain within 50 application cap.

    Click Next → Confirm to finalize.

    Distribute app ID, configure security (Secure Mode, tokens) in Console.

  The selected region cannot be changed after creation. Choose based on latency, data residency, and compliance constraints.

## Edit an Application

    Search by APP ID or Name or filter by Plan / Region.

    Click “Edit” next to target application.

    Modify name or descriptive metadata (region locked).

    Click Save; verify updated label appears in listing.

    Notify teams if name changes impact tooling / dashboards.

## Region Selection Strategy

    Pick geographically closest region to majority user base to reduce round‑trip time.

    Align with legal / compliance restrictions (e.g., EU data constraints).

    Use separate applications in multiple regions rather than expecting in‑place region migration.

    Reserve name conventions (e.g., product-env-region) to avoid collisions.

## Naming & Governance

    Use pattern: <code>
    \<product\>-\<env\>-\<region\></code>

     (e.g., chat-prod-eu).

    Assign an accountable owner for each application for audits & incident response.

    Apply tags for cost center, environment, and compliance classification.

    Document any rename in central log (date, old, new, approver).

## Capacity & Limits

  You may create up to 50 applications. Contact support to request a higher cap with justification (e.g., multi-tenant SaaS segmentation).

    Approaching ≥ 45 apps with planned roadmap growth & clear separation rationale.

    Audit unused / duplicate staging apps before expansion.

## Metrics & Monitoring

| Metric                | Purpose                    | Healthy Signal       | Action Trigger                               |
| --------------------- | -------------------------- | -------------------- | -------------------------------------------- |
| App Count Utilization | Track usage vs cap (50)    | \< 90%               | ≥ 90% → consolidation review / raise request |
| Naming Compliance %   | Standardized names / total | 100%                 | \< 95% → enforce pattern                     |
| Orphaned Apps         | Apps without owner         | 0                    | \> 0 → assign or archive                     |
| Edit Frequency        | Name changes per month     | Low & intentional    | Spike → investigate process drift            |
| Region Distribution   | Apps per region            | Balanced vs strategy | Unexpected cluster → latency review          |

## Troubleshooting

| Issue                          | Likely Cause             | Resolution                                                    |
| ------------------------------ | ------------------------ | ------------------------------------------------------------- |
| Cannot create new app          | Reached 50 cap           | Archive unused or request limit increase                      |
| Region incorrect post-creation | Mis-selection            | Create new app in correct region; migrate data; deprecate old |
| App not found via search       | Typo / stale name        | Use APP ID or confirm rename log                              |
| Frequent renames               | Lack of naming standards | Adopt enforced pattern & approval gate                        |
| Latency complaints             | Suboptimal region        | Plan transition via new region app & user migration           |

## Best Practices

    Highlight region lock in internal onboarding docs.

    Quarterly review for orphaned or redundant staging apps.

    Update internal runbooks when app names change.

    Isolate higher compliance workloads to dedicated applications for clearer audit scoping.

## Quick Reference

    50 applications

    EU • SG • US

    product-env-region

    Single accountable contact

## Related

    Portal sign‑in & SSO

    Secure Mode & keys

  Need to adjust the application cap? Prepare justification (use cases, consolidation audit) before contacting support.

---

### [Overview](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/README)

> Unified guide to the dashboards: activity, community & content, chat, video, and AI social insights—what each shows, when to use them, and how to interpret KPI families.

Use the Dashboard suite to answer three core questions: (1) Are we growing & retaining healthy users? (2) Is engagement deep, distributed, and safe across social, chat, and video surfaces? (3) What qualitative themes & gaps explain quantitative changes?


## When to Use Which Dashboard

| Scenario | Go Here | Primary KPIs | Typical Action |
|----------|---------|--------------|----------------|
| Sudden user spike or dip | Activity | New / Returning Users, Concurrency | Validate campaign or investigate outage |
| A community declines | Social | Net Growth, Engagement Rate | Intervention (spotlight, moderation) |
| Chat feels noisy / spammy | Chat | Flagged Rate, MPAU (Message per Active User), Channel Concentration | Tighten limits, rebalance channels |
| Livestream buffering complaints | Video | Peak Concurrency, Avg Minutes / Viewer | Expand limits |
| Negative sentiment rising | AI Insights | Sentiment Score, Topic Skew | Root cause analysis & remediation ticket |
| Need custom cohort model | Raw Export | Event-level records | Build external analysis / ML |

## KPI Families


## Navigation & Filters


## Quick Start (First Week)


## Core KPI Snapshot Reference

| Domain | KPI | Definition | Why It Matters | Common Trigger |
|--------|-----|------------|----------------|----------------|
| Activity | Returning Users % | Returning / Active | Stickiness | % drops >5pts w/w |
| Activity | Peak Concurrency | Max simultaneous connections | Capacity risk | >80% provisioned |
| Social | Engagement Rate | (Comments + Reactions)/Posts | Quality over volume | Below target band |
| Social | Net Community Growth | Joins - Leaves | Community health | Negative 3+ days |
| Chat | MPAU | Messages / Unique Senders | Power user dependence | Sharp rise + flat senders |
| Chat | Flagged Rate | Flagged / Messages | Safety cleanliness | Above threshold |
| Video | Avg Min / Viewer | Minutes Watched / Unique Viewers | Retention depth | < baseline -15% |
| AI Insights | Sentiment Score | Net polarity −100 to +100 (0 = balanced) | Morale / satisfaction | Drop >5 pts d/d |
| AI Insights | Gap Index (Top) | Weight (search vol vs coverage) | Self-service opportunity | Top unchanged 2 cycles |

## Governance & Best Practices

---

### [User & Activity Analytics](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/activity-analytics)

> Operational guide to interpret user growth, retention, concurrency, and feature adoption metrics in the Portal dashboard.

Use this dashboard to monitor acquisition, retention, concurrency load, visitor traffic, and cross-feature adoption so you can prioritize growth levers and capacity planning.

<img src="/images/dashboard-visitor-usage.png" alt="My network dashboard showing signed-in user metrics, feature usage, and month-to-date MAU charts including overused visitors" />


## KPI Overview (Main View)


## Interpreting Feature Overlap


## Understanding Visitor Traffic & Fair-Use Classification

Visitors are anonymous, unauthenticated users browsing your community without signing in. To keep platform costs aligned with actual resource usage, visitor activity is tracked and classified into the following buckets:


Overused Visitor MAU figures refresh daily. Because reclassification moves a visitor out of the Visitor MAU bucket entirely, your Visitor MAU and Overused Visitor MAU counts always reconcile without double-counting.

## Historical Trends


## Core Metrics Definitions

| Metric | Definition | Use Case | Watch For |
|--------|------------|----------|-----------|
| New Users | Accounts created in period | Acquisition tracking | Spikes without retention lift |
| Returning Users | Previously active & active again | Stickiness / engagement | Declining ratio vs total active |
| Inactive Users | Previously active; no activity now | Churn monitoring | Uptrend across consecutive periods |
| Concurrent Connections (Peak) | Max simultaneous connections | Capacity planning | Peak nearing infra limit |
| MAU MTD | Unique users active month-to-date | Month pacing | Flattening mid-month slope |
| Visitor MAU | Anonymous, unauthenticated users (by device ID) within the monthly fair-use threshold | Public traffic & SEO reach | Large gap vs. signed-in growth |
| Overused Visitor MAU | Visitors who exceeded the monthly fair-use threshold and are billed at the signed-in rate | Cost & conversion monitoring | Rising share of total visitor traffic |
| Feature Overlap % | Users using multiple core features | Adoption depth | Low overlap vs benchmarks |
| Video Watch Minutes (FHD/HD/SD) | Minutes consumed by quality tier | Bandwidth & cost mgmt | Disproportionate FHD spike |
| File Storage | Total storage consumed | Cost forecasting | Sudden growth (unoptimized media) |

## Leading Indicators & Actions


## Dashboards Operating Cadence


## Troubleshooting

| Symptom | Possible Cause | Resolution |
|---------|----------------|-----------|
| New Users spike; returning flat | Low first-week activation | Improve onboarding sequence & feature discovery |
| Concurrency plateau while new users grow | Session clustering / timezone pattern | Rebalance infra schedule; analyze session length |
| Inactive surge after release | Regression or UX friction | Review release telemetry & session error logs |
| Video minutes drop, storage rising | Incomplete uploads accumulating | Implement cleanup of failed uploads |
| FHD minutes sudden spike | Default quality forced high | Re-enable adaptive bitrate / CDN config check |

## Related

---

### [Chat Analytics](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/chat-analytics)

> Operational insight into messaging volume, participation, channel health, quality, and moderation load to optimize chat retention and scalability.

Use Chat Analytics to detect participation shifts, capacity risks, emerging spam, and moderation workload so you can sustain healthy real‑time conversations.


## Fast Questions You Can Answer


## Daily Operational Workflow


## Modules & Interpretation

### KPI Cards
High-level snapshot (Messages, Flagged Messages, Reactions, Unique Senders). Deltas contextualize growth vs prior period.

### New Messages by Day
Volume rhythm; use for feature launch impact and anomaly detection. Gentle cyclic pattern is normal; abrupt plateau indicates engagement stall.

### Channels Count by Type
Composition (public, private, broadcast). Skew heavily toward one type may limit discovery or create moderation blind spots.

### Users by Day
Active unique senders; rising volume without matching unique sender growth implies intensity, not breadth.

### Total Messages by Type / Channel Distribution
Identifies reliance on a small set of channels. Over-concentration risks single-point community health issues.

### Top Group Chat Channels Leaderboard
Sort by Members, Messages, Engagement Rate (messages per member), or Flagged Rate to surface exemplars or risk clusters.

### Messages Heatmap
Hourly/daily density. Align moderator shifts and system scaling policies with dark (peak) cells.

## Key Metrics & Formulas

| Metric | Definition | Formula (Illustrative) | Why It Matters | Action Trigger |
|--------|------------|------------------------|----------------|----------------|
| Messages | Total messages sent | count(messages) | Overall volume | Drop >15% w/w |
| Unique Senders | Distinct users sending ≥1 message | distinct(user_id) | Participation breadth | Flat while messages rise |
| Messages per Active User (MPAU) | Avg intensity per sender | Messages / Unique Senders | Detect over-reliance | Sharp rise + flat senders |
| Reactions | Total reactions on messages | count(reactions) | Lightweight engagement | Reactions/Message down |
| Reaction Rate | Reactions per message | Reactions / Messages | Content resonance | Below baseline band |
| Flagged Messages | Messages flagged by systems/users | count(flag events) | Moderation workload | Spike >25% w/w |
| Flagged Rate | Flagged / Messages | Flagged / Messages | Safety cleanliness | > threshold (e.g., 1–2%) |
| New Channels | Channels created period | count(channel_create) | Organic growth / fragmentation | Spike + falling engagement rate |
| Channel Concentration Index | Engagement distribution (simplified HHI) | Σ (channel_share^2) | Diversity of conversation | > prior period + rising churn |
| Messages per Channel | Avg messages per active channel | Messages / active_channels | Capacity & sprawl measure | Decline + rising channel count |
| Peak Hour Factor | Peak hour messages vs avg hour | peak_hour / avg_hour | Staffing & infra planning | Factor rising > target |
| Newly Activated Chat Users | First-time senders in period | distinct(new_sender_ids) | Feature adoption | Activation drop consecutive weeks |
| Retained New Senders (7d) | New senders returning within 7d | returning_new / new_sender_ids | Early retention | < benchmark band |

## Participation & Quality Lenses


## Benchmark & Governance Strategy


## Early Warning Signals


## Troubleshooting

| Symptom | Likely Cause | Investigation | Resolution |
|---------|-------------|---------------|-----------|
| Volume up; engagement flat | Few users posting heavily | Distribution of messages per user | Encourage broader participation; prompts, onboarding nudge |
| Flagged rate surge | Spam / abusive burst | Review top flagged channels & user IDs | Apply rate limits; tighten filters; temp-ban offenders |
| Reaction rate drop | Content low relevance / UI friction | Compare reaction latency post message | Improve quick reaction UI; highlight engaging threads |
| New channels spike; avg messages/channel down | Fragmentation / channel creation sprawl | Correlate channel age vs activity | Introduce channel creation guidelines & approval |
| Moderation backlog aging | Understaffed peak or automation gap | Backlog aging metric by hour | Add on-call; refine auto-flag thresholds |
| Low new sender retention | Poor onboarding into existing channels | Funnel: Signup → First message → Return visit | Provide channel suggestions & starter messages |
| Peak hour factor rising | Emerging synchronized usage cluster | Compare heatmap vs previous weeks | Pre-scale infra; adjust sharding or throughput configs |


## Related

---

### [Post Analytics](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/post-analytics)

> Browse, moderate, and measure individual post performance—view engagement metrics, manage flagged and pinned content, and drill into per-post impression and reach charts.

Use the Posts dashboard to review every piece of content in your network, take moderation actions, and open the **Post Performance** panel to inspect per-post engagement over time.


## Posts Overview

The Posts page displays the latest posts and comments across your network. Each post card shows the author, target community or content feed, creation date, and inline engagement counters.

<img src="/images/analytics-and-moderation/post-analytics.png" alt="Posts dashboard showing post feed with engagement metrics" />

### Post Card Anatomy

Each post in the feed includes:

| Element | Description |
|---------|-------------|
| **Author** | Display name of the user who created the post |
| **Target** | Community or content feed the post belongs to, with type label |
| **Timestamps** | Created date and last-active date |
| **Content Preview** | Text, images, video player, or poll results inline |
| **Engagement Row** | Reactions · Comments · Impressions · Reach · Flags |
| **Comment Box** | Inline "Comment as admin" field for direct engagement |
| **Action Buttons** | Post Performance · Delete · Pin (top-right of each card) |

## Filtering & Search

    Click the date picker in the top-right corner to select a custom range. Quick presets include **Last 7 days**, **Last 30 days**, **Last 6 Months**, and **This year**.
    Use the search bar to find posts containing specific text.
    Use the **Search community** dropdown to isolate posts from a specific community.
    Click the sort button (filter icon) to change the ordering of results.
    Use the **All** dropdown to filter posts by category.

## Post Tabs

    The default view showing every post in your network within the selected date range. Each post displays full content preview with engagement metrics and admin action buttons.
    Shows posts that have been pinned by administrators. Pinned posts receive higher visibility in community feeds. Use this tab to manage which content is currently promoted.
    Displays posts that have been reported by users or auto-flagged by moderation rules. Use this tab for your moderation workflow to review, approve, or remove flagged content.

    Flagged posts require timely review. Establish a daily moderation cadence to keep the flagged queue clear.

## Moderation Actions

Each post card provides three action buttons in the top-right corner:

    Opens a detailed side panel with per-post engagement charts for Reactions, Comments, Impressions, and Reach over the selected date range. See [Post Performance Panel](#post-performance-panel) below.
    Permanently removes the post and its associated comments from the network. Use with caution—this action cannot be undone.
    Pins the post to the top of its community feed, giving it persistent visibility. Unpin by clicking the button again on a pinned post.

You can also comment on any post directly as the network admin using the inline comment box beneath each post.

## Post Performance Panel

Clicking the **Post Performance** button (bar-chart icon) on any post opens a detailed side panel with time-series charts for that specific post.

<img src="/images/analytics-and-moderation/post-performance.png" alt="Post Performance panel showing reactions, comments, impressions, and reach metrics" />
<img src="/images/analytics-and-moderation/post-performance-scroll2.png" alt="Post Performance impressions and reach charts with time-series data" />

The panel includes its own date range picker, allowing you to analyse performance across different time windows independently of the main feed filter.

Data is available from the post's creation date up to yesterday. Today's data is not yet included.

### Performance Metrics

    **Definition:** Number of reactions (likes, emojis) on this post.

    Displayed as a daily time-series chart. Use to identify reaction spikes that correlate with distribution events or viral moments.
    **Definition:** Number of comments on this post.

    Tracks comment volume over time. A healthy post typically sees comments taper gradually after an initial burst—flat-lining immediately may indicate low engagement quality.
    **Definition:** Total times the content was viewed, including members and visitors.

    Measures raw exposure. Compare with Reach to understand whether the same users are seeing the post repeatedly.
    **Definition:** Unique people who saw the content, including members and visitors.

    Reach represents distribution breadth. A high Impressions-to-Reach ratio indicates repeated exposure to the same audience—consider broadening distribution.

### Performance Metrics Reference

| Metric | Definition | Why It Matters | Action Trigger |
|--------|------------|----------------|----------------|
| Reactions | Total reactions on the post | Lightweight engagement signal | Zero reactions after 24h of reach |
| Comments | Total comments on the post | Discussion depth indicator | Comments/Impressions ratio below baseline |
| Impressions | Total content renders (members + visitors) | Exposure volume | Flat despite distribution push |
| Reach | Unique viewers (members + visitors) | Distribution breadth | High impressions but stagnant reach |

## Best Practices

    1. Start with the **Flagged Posts** tab to clear the moderation queue
    2. Switch to **All Posts** and scan for anomalies (spam bursts, engagement drops)
    3. Review **Pinned Posts** to ensure promoted content is still relevant
    4. Open **Post Performance** on key posts to validate distribution health
    - Compare Impressions vs Reach to detect audience saturation
    - Check Reactions and Comments trends to assess engagement quality
    - Adjust the date range to isolate specific campaign periods
    - Use the per-post data to inform content strategy decisions
    - Pin announcements, events, or high-quality community content
    - Rotate pinned posts regularly to keep feeds fresh
    - Limit pinned posts per community to avoid feed clutter
    - Monitor pinned post performance to confirm visibility impact

## Troubleshooting

| Symptom | Likely Cause | Resolution |
|---------|-------------|------------|
| Posts not appearing | Date range too narrow | Expand the date range or reset to "Last 30 days" |
| Metrics show zero | Post is very new | Data is available from creation date up to yesterday—wait 24h |
| Flagged tab empty | No flagged content | Healthy state; continue monitoring |
| Post Performance panel shows "No data" | Post has no engagement in selected range | Adjust the date range to cover the post's active period |
| Search returns no results | Keyword mismatch | Try broader search terms or clear filters |

## Related

---

### [Social Analytics](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/social-analytics)

> Monitor community & content health—engagement velocity, growth vs churn, reach, impressions, and top community performance.

Use this dashboard to understand how communities, posts, comments, and reactions are performing so you can amplify healthy spaces and intervene in declining ones.


## Daily Operational Workflow


## Community Filtering

Filter analytics to a specific community to isolate engagement, growth, and content patterns—helping you diagnose whether trends are platform-wide or community-specific.

### Why Filter by Community?

- Identify which communities drive or drag overall metrics
- Diagnose localized issues vs platform-wide trends
- Compare individual community performance against baseline

Widget **Top Communities** and **Reach and Impression** will always show data for all communities, even when a specific community is selected in the filter.

### How to Apply


Analytics shows data for **one community at a time**. To compare multiple communities, filter each separately and record results.

## Modules & Interpretation

### Community Activity Overview (Stacked Bars)
Shows aggregate daily counts for: Posts, Comments, Reactions, Members Joined, Members Left. Look for proportion shifts (e.g., comments dropping relative to posts may indicate lower discussion depth).

### Top Communities Table
Leaderboard with: Posts, Comments, Reactions, Members Joined, Members Left, Engagement Rate. Use relative KPI columns rather than just raw counts to avoid bias toward largest audience spaces.

### Reach & Impression Graph
Reach = unique users exposed. Impressions = total displays. High impressions with flat reach suggests repeated exposure to same users; rotate content spots to counter fatigue.

### Growth & Churn
Joined vs Left provides directional community health. Persistent churn outpacing joins → investigate content relevance, governance friction, or onboarding gaps.

### Content Velocity
Rate of new posts per active community. Helps detect stagnation or spam bursts. Sudden spike unaccompanied by reactions/comments may indicate low-quality or automated posting.

## Metrics & Formulas

| Metric | Definition | Formula (Illustrative) | Why It Matters | Action Trigger |
|--------|------------|------------------------|----------------|----------------|
| Posts | New posts in period | count(posts) | Core creation volume | Drop >20% w/w |
| Comments | New comments in period | count(comments) | Depth of discussion | Comments/Post ratio < baseline |
| Reactions | Emoji/like style reactions | count(reactions) | Lightweight engagement breadth | Reactions/Post ratio dips |
| Members Joined | New joins to communities | count(join events) | Acquisition into spaces | Join decline consecutive 3 days |
| Members Left | Departures / leaves | count(leave events) | Churn pressure | Left rising >15% w/w |
| Net Community Growth | Growth after churn | Joined - Left | Community trajectory | Negative 3+ days |
| Engagement Rate | (Comments + Reactions)/Posts | (C + R) / P | Quality vs spam | Falls below target band |
| Comment Depth | Avg comments per post | C / P | Conversation richness | < baseline percentile |
| Reaction Saturation | Unique reactors / reach | distinct(reactors)/reach | Engagement distribution | Concentrated small reactor core |
| Reach | Unique users who saw content | distinct(viewers) | Distribution breadth | Stagnant vs user growth |
| Impressions | Total content renders | sum(views) | Frequency / exposure | High impressions, flat reach |
| Frequency Factor | Impressions / Reach | I / R | Repetition index | > target (content fatigue risk) |
| Content Velocity | Posts per active community | P / active_communities | Sustain momentum | Sharp rise (spam) or fall (stagnation) |

## Growth & Engagement Lenses


## Benchmark Strategy


## Early Warning Signals


## Troubleshooting

| Symptom | Likely Cause | Investigation | Resolution |
|---------|-------------|---------------|-----------|
| Engagement Rate drop | Low comment depth / passive reactions | Compare comments/post vs reactions/post | Add prompts; highlight discussion-oriented posts |
| Net growth negative | Churn event (policy change, incident) | Overlay join/leave with incident timeline | Publish transparency note; adjust policy UX |
| Reach flat; impressions high | Overexposure algorithm weighting | Review recommendation distribution logs | Tune ranking to broaden diversity |
| Velocity spike; low quality | Spam or bot posting | Sample post authors & content patterns | Tighten rate limits; enhance moderation rules |
| Reaction saturation low | Same small set reacting repeatedly | Unique reactors vs total reactions analysis | Encourage broader participation (badges, prompts) |
| Frequency factor high | Repeat impressions to same cohort | Examine impression distribution by user | Introduce capping / cooldown logic |

## Related

---

### [AI Social Insights](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/social-insights)

> Qualitative intelligence for topics, sentiment, search intent, and AI research—convert community conversations into actionable product, support, and content decisions.

This dashboard augments quantitative usage analytics with qualitative insight—surfacing what people talk about, how they feel, what they search (but cannot find), and why churn or satisfaction shifts are emerging.

**Sentiment Analysis has moved.** The sentiment analysis capabilities described here have been expanded into a dedicated feature with AI-powered topic detection, per-topic summaries, and thread-level analysis. See [Sentiment Analysis](./sentiment-analysis) for the new experience.


## What Can You Answer in Minutes?


## Daily Operational Workflow


## Community & Topic Filtering

Refine any insight to the communities and topics that matter—filtering removes noise so trend, sentiment, and gap signals stay actionable.


### Why Use Community-Level Filters?

- Targeted insights: Each community exhibits distinct engagement & sentiment patterns.
- Faster diagnosis: Narrow scope to confirm whether an issue is broad or localized.
- Segment strategies: Tailor interventions (content, moderation, onboarding) per cohort.
- Reduce noise: Avoid dilution from mega-communities overshadowing smaller niches.

### Getting Started

| Requirement | Details |
|-------------|---------|
| Access | Portal login with Social Insights permission |
| Feature Enablement | Social Insights enabled (contact support if disabled) |
| Data Window | Default range (e.g., last 30 days)—adjust as needed |


### Interface Tour

| Element | Location | Purpose |
|---------|----------|---------|
| Filter Bar | Top of insights view | Houses Topic & Community selectors + date range |
| Topic Dropdown | Left selector | Choose one or multiple topics to include |
| Community Dropdown | Right selector | Search & pick one or more communities |
| Date Range | Right side | Adjust temporal scope for comparison |


### Applying Filters (Step-by-Step)


### Interpreting Filtered Results


### Best Practice Patterns


### Example Workflow

1. Start unfiltered → identify emerging topic.
2. Apply topic filter → confirm growth & sentiment skew.
3. Add top 3 related communities → detect which exhibits worst negative skew.
4. Run AI Research prompt: "Root causes of negative sentiment about &lt;topic&gt; in &lt;community&gt;."
5. Validate references → create targeted remediation ticket.


## Modules & Interpretation

### Mentions & Topic Breakdown
Highlights conversation concentration. A healthy distribution usually shows a balanced long-tail—extreme concentration may indicate a blocking issue OR a successful campaign.

### Trend Graph
Multi-line frequency lines reveal acceleration or decay. Sustained upward slope + positive sentiment → amplify; upward + negative → triage.

### Sentiment (Overall + Per Topic)
Overall gauge (−100 to +100, where 0 is balanced). Correlate dips with deployment timestamps or incident reports. Topic sentiment bars isolate outlier issues masked by aggregate positivity.

### AI Post Summaries
Condense thousands of posts into 5–10 key statements per sentiment polarity. Treat as directional—spot check references before broad decisions.

### AI Recommendations
Strategic remediation / opportunity list derived from the weighted intersection of volume, sentiment skew, and recency. Confidence score (if shown) reflects model certainty; low-confidence items may require manual verification.

### AI Research (Conversational Analyst)
Natural language Q&A across indexed conversations. Returns a structured mini-report: Introduction, Methodology, Findings, References (canonical post links) to enable traceability.

### Search Insights & Content Gaps
Maps expressed intent (search queries) vs existing content coverage. Gap Index ranks unmet demand to drive documentation & self-service improvements.

## Metrics & Signals

| Metric | Definition | Why It Matters | Action Trigger |
|--------|------------|----------------|----------------|
| Total Mentions | Total topic references in filtered period (one thread counts once per topic it is classified under) | Measures conversation volume / engagement energy | Spike > X% without planned campaign |
| Topic Share % | Mentions of topic / total mentions | Identifies dominance or neglect | Single topic >40% share 2+ days |
| Emerging Topic | Topic with high period-over-period growth and baseline low prior volume | Surfacing new opportunities or issues | Growth rate > threshold (e.g., >150%) |
| Overall Sentiment Score | Net sentiment across topic mentions, `(positive − negative) / total × 100`, on a −100 to +100 scale | Health & morale indicator | Drop of >5 pts d/d or >8 pts w/w |
| Topic Sentiment Skew | Deviation between topic sentiment and overall baseline | Prioritizes hotspots | Negative skew > (baseline -10) |
| Negative Summary Themes Count | Distinct negative themes extracted | Complexity of issues / support load | Rapid increase in count |
| Total Searches | Volume of internal search queries | Demand / intent scale | Sustained decline (possible UX findability issue) |
| Trending Searches Count | # of search terms with rapid growth | Emerging informational needs | Large increase → accelerate content creation |
| Content Gap Count | Unique queries with low/no results | Self-service deficiency | > predetermined target |
| Gap Index | Weighted (query volume vs results available) | Prioritization of content production | Top index unchanged across cycles (stale backlog) |
| Zero-Result Rate % | (Queries with no result) / total searches | Support deflection efficiency | Rate > target (e.g., >8%) |

## Leveraging AI Research Effectively


## Prompt Patterns


## Related

---

### [Livestream Analytics](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/livestream-analytics)

> Monitor and analyze your livestream performance with comprehensive metrics, viewer engagement data, and detailed stream reports

Track and analyze the performance of your livestream content with comprehensive analytics. The Livestream Analytics Dashboard provides real-time insights into viewer engagement, watch time, and stream performance metrics.

<img
  className="block"
  src="/images/dashboard-livestream-analytics.png"
  alt="Livestream Analytics"
/>

## Overview

The Livestream Analytics offers a centralized view of all your livestream metrics, helping you understand viewer behavior, content performance, and engagement patterns.

    Track total streams created, views, unique viewers, and watch time with historical comparisons
    Monitor viewer engagement with per-stream and per-user watch time metrics
    Browse all livestreams with detailed performance data including views, duration, messages, and reactions
    Compare performance across custom date ranges with percentage change indicators

**Migration Notice**: The new room-based livestreams appear in the Live Streams (New) section, while legacy streams remain available under Live Streams (Legacy) for accounts still using the previous system.

## Accessing the Dashboard

    From the social.plus Portal sidebar, locate the **Video Analytics** section
    Click on **Live stream** (marked with "New" badge) to access the latest analytics dashboard
    Use the date range picker to filter analytics for your desired time period

## Key Metrics

### Total Streams Created

    **Description**: Number of livestreams created during the selected period

    **Displays**:
    - Total count of streams
    - Percentage change compared to previous period
    - Trend visualization over time

    **Use Cases**:
    - Monitor content creation frequency
    - Identify peak streaming periods
    - Track creator activity levels

    This metric helps you understand your streaming cadence and content production rate. A consistent or growing number of streams indicates active creator engagement.

    **Insights**:
    - **High Volume**: Strong creator activity and content supply
    - **Low Volume**: May indicate need for creator incentives
    - **Fluctuating**: Seasonal or event-driven patterns

### Total Views

    **Description**: Total times your livestreams were watched across all streams

    **Calculation**: Sum of all view instances, including repeat views from the same user

    **Displays**:
    - Total view count
    - Percentage change vs previous period
    - Time-series chart showing view trends

    **Use Cases**:
    - Measure overall content reach
    - Assess audience interest levels
    - Compare performance across periods

    **Increase Views**:
    - Promote upcoming streams through notifications
    - Schedule streams during peak audience hours
    - Create compelling stream titles and thumbnails
    - Encourage repeat viewing with series content

    **Benchmarking**:
    - Compare views per stream ratio
    - Track growth trends month-over-month
    - Identify top-performing content types

### Total Unique Viewers

    **Description**: Number of distinct users who watched at least once during the period

    **Calculation**: Unique user count across all streams, counted once per user regardless of view frequency

    **Key Differences**:
    - **Total Views**: Counts every view instance (repeats included)
    - **Unique Viewers**: Counts each person only once

    **Example**: If User A watches 5 times = 5 views, 1 unique viewer

    **Insights from Unique Viewers**:

    **High Unique Viewers + Low Total Views**:
    - Broad reach but low engagement
    - Users watching briefly or once
    - Consider improving content retention

    **Low Unique Viewers + High Total Views**:
    - Strong loyal audience
    - High repeat viewership
    - Good content retention

    **Both Growing**:
    - Healthy expansion
    - Good balance of new and returning viewers

### Total Minutes Watched

    **Description**: Combined watch time across all viewers and streams

    **Calculation**: Sum of all minutes watched by all viewers across all streams

    **Why It Matters**:
    - Primary indicator of content value
    - Reflects true engagement depth
    - Key metric for monetization and growth

    **Interpreting Watch Time**:

    **High Watch Time**:
    - Engaging, valuable content
    - Good stream quality and pacing
    - Strong audience retention

    **Low Watch Time**:
    - Short stream durations
    - Early viewer drop-off
    - Content-audience mismatch

    **Optimization**:
    - Analyze drop-off points
    - Improve content pacing
    - Enhance production quality
    - Create compelling opening segments

### Minutes Watched Per Stream

    **Description**: Average watch time earned by each livestream

    **Calculation**: `Total Minutes Watched ÷ Total Streams Created`

    **Benchmark Values**:
    - **< 1 minute**: Very low engagement, investigate issues
    - **1-5 minutes**: Below average, room for improvement
    - **5-15 minutes**: Good engagement
    - **> 15 minutes**: Excellent engagement

    **What This Tells You**:
    - Content quality and appeal
    - Stream duration effectiveness
    - Topic relevance to audience

    **Improving This Metric**:
    - Create compelling openings (first 30 seconds critical)
    - Maintain consistent pacing
    - Deliver value throughout stream
    - Use engagement prompts (Q&A, polls)
    - Optimize stream length for content type

### Minutes Watched Per User

    **Description**: Average watch time per individual viewer

    **Calculation**: `Total Minutes Watched ÷ Total Unique Viewers`

    **Insights**:
    - Individual user engagement level
    - Content value perception
    - Audience loyalty indicator

    **High Minutes Per User**:
    - Loyal, engaged audience
    - High-value content
    - Strong retention

    **Low Minutes Per User**:
    - Casual viewers
    - Discovery/browsing behavior
    - Potential targeting issues

    **Strategies to Improve**:
    - Build community through interaction
    - Create consistent streaming schedules
    - Develop content series to encourage return visits
    - Implement viewer rewards/recognition
    - Enhance production quality

## All Live Streams Table

The streams table provides detailed performance data for each individual livestream, allowing you to identify top performers and analyze specific content.

<img
  className="block"
  src="/images/dashboard-livestream-table.png"
  alt="Livestream Table with Performance Metrics"
/>

### Table Columns

    **Content**: Stream title and creator name

    **Information Displayed**:
    - Stream title (top line)
    - Creator name prefixed with "By" (bottom line)

    **Usage**:
    - Identify specific streams
    - Track creator-specific performance
    - Analyze title effectiveness

    **Content**: Date and time when stream was created

    **Format**: `DD MMM YYYY, HH:MM` (e.g., "11 Feb 2026, 14:43")

    **Features**:
    - Sortable column (click header to sort)
    - Helps identify recent vs older content
    - Useful for time-based analysis

    **Content**: Total length of the livestream

    **Format**: `HH:MM:SS` (Hours:Minutes:Seconds)

    **Insights**:
    - Optimal stream length analysis
    - Content pacing evaluation
    - Correlation with engagement metrics

    **Note**: "00:00:00" indicates a stream that was created but not started or ended immediately

    **Content**: Total number of times the stream was viewed

    **Includes**:
    - Live viewers during broadcast
    - Replay/recording views (if enabled)
    - Repeated views from same users

    **Analysis**: Compare with unique viewers to understand repeat viewing behavior

    **Content**: Number of distinct users who watched the stream

    **Usage**:
    - Measure reach per stream
    - Calculate average views per unique viewer
    - Identify high-appeal content

    **Example**: 10 views with 5 unique viewers = 2 views per person average

    **Content**: Total minutes watched for this specific stream

    **Calculation**: Sum of watch time from all viewers

    **Key Metric**: Indicates overall engagement value of the stream

    **Analysis**: Divide by unique viewers to get average watch time per viewer

    **Content**: Number of chat messages sent during the livestream

    **Indicates**:
    - Viewer interaction level
    - Community engagement
    - Real-time conversation activity

    **High Messages**:
    - Active, engaged audience
    - Interactive content style
    - Strong community presence

    **Content**: Total number of reactions (likes, emojis) during stream

    **Engagement Indicator**:
    - Quick engagement metric
    - Emotional response to content
    - Viewer appreciation level

    **Usage**: Reactions require less effort than messages, indicating broader audience sentiment

### Table Features

**Sorting**: Click on column headers marked with sort icons to order streams by that metric (ascending or descending)

**Row Click**: Click on any stream row to view [detailed analytics](#individual-livestream-analytics) for that specific livestream, including time-series charts and comprehensive stream information

**Export**: Use the export button (top right of table) to download stream data for external analysis

## Date Range Comparison

The dashboard automatically compares your selected period with the equivalent previous period, showing percentage changes for all metrics.

### Understanding Comparisons

**Positive Change (+%)**:
- Metric increased compared to previous period
- Growth in the measured activity

**No Change (0%)**:
- Metric remained the same
- Consistent performance

**Negative Change (-%)**:
- Metric decreased compared to previous period
- Requires investigation if significant

**Context Matters**: A 0% change might indicate stagnation in some cases or stable performance in others. Consider your growth goals and market conditions when interpreting trends.

## Best Practices

    **Recommended Review Frequency**:
    - **Daily**: For active streaming platforms during campaigns
    - **Weekly**: For regular content creators
    - **Monthly**: For strategic planning and goal setting

    **Key Actions**:
    - Check percentage changes for significant shifts
    - Identify trending streams to replicate success
    - Spot issues early (declining metrics)
    - Adjust content strategy based on data

    **Analyze Metrics Together**:

```
Engagement Rate = Minutes Watched Per User
Retention Rate = Unique Viewers ÷ Views
Content Value = Minutes Watched Per Stream
Reach Efficiency = Unique Viewers ÷ Streams Created
```

    **Healthy Patterns**:
    - Growing unique viewers + stable watch time per user
    - Increasing streams + proportional view growth
    - Rising minutes watched across all metrics

    **Data-Driven Improvements**:

    1. **Identify Top Performers**
       - Sort by minutes watched
       - Analyze what makes them successful
       - Replicate winning patterns

    2. **Optimize Timing**
       - Review created dates of high-performing streams
       - Identify best days/times for your audience
       - Schedule streams accordingly

    3. **Content Strategy**
       - Compare stream titles and topics
       - Measure engagement metrics per category
       - Focus on high-performing content types

    4. **Engagement Enhancement**
       - Streams with high messages/reactions = successful interaction
       - Study and replicate engagement techniques
       - Build community through consistent interaction

    **Low Views/Unique Viewers**:
    - Improve promotion and discoverability
    - Optimize stream titles and descriptions
    - Leverage push notifications
    - Schedule during peak audience times

    **Low Watch Time**:
    - Improve content quality and pacing
    - Create compelling openings
    - Enhance production value
    - Reduce technical issues

    **Low Messages/Reactions**:
    - Encourage interaction through prompts
    - Ask questions and respond to viewers
    - Create interactive content (Q&A, polls)
    - Build community culture

## Use Cases

    Identify which livestreams resonate most with your audience by comparing views, watch time, and engagement metrics across streams
    Track individual creator performance by filtering the streams table by creator name to understand productivity and engagement
    Analyze viewer patterns through unique viewer counts vs total views to understand audience loyalty and repeat viewing habits
    Calculate return on investment for livestream initiatives by tracking engagement metrics against production costs and resources
    Use historical data and trends to plan future content calendars, optimal streaming times, and content themes
    Monitor platform growth through trending metrics and percentage changes to validate strategy effectiveness

## Comparing with Legacy Analytics

For accounts that have migrated from the legacy livestream system, both analytics dashboards remain accessible during the transition period.

### Key Differences

| Feature | Live Stream (New) | Live Stream (Legacy) |
|---------|-------------------|---------------------|
| **Stream Type** | Room-based livestreams | Channel-based livestreams |
| **Date Coverage** | Streams created after migration | Streams created before migration |
| **Analytics Depth** | Enhanced metrics and visualizations | Standard metrics |
| **Real-time Updates** | More frequent updates | Standard update frequency |
| **Export Options** | Enhanced export capabilities | Basic export |

**Migration Recommendation**: New livestreams should use the room-based system (Live Stream New) to take advantage of improved features and analytics capabilities.

---

## Individual Livestream Analytics

Access comprehensive analytics for individual livestream sessions by clicking on any stream row in the table above. Each detail page includes viewer engagement metrics, chat activity, reactions, and detailed stream information.

<img
  className="block"
  src="/images/dashboard-livestream-detail.png"
  alt="Individual Livestream Analytics Page"
/>

**Back Navigation**: Use the breadcrumb navigation at the top (Live stream analytics) to return to the overview page.

### Detail Page Metrics

#### Total Unique Viewers

    **Description**: Number of distinct people who watched this specific livestream at least once

    **Displayed With**:
    - Total count of unique viewers
    - Time-series chart showing viewer count throughout the stream duration
    - X-axis: Stream timeline (HH:MM:SS format)
    - Y-axis: Number of unique viewers at that moment

    **Use Cases**:
    - Identify peak viewership moments
    - Understand viewer join/drop patterns
    - Correlate content with viewership changes

    **Time-Series Insights**:

    **Steady Growth**: Content is discoverable and engaging, viewers staying throughout

    **Early Peak, Then Decline**: Strong initial interest but retention issues

    **Mid-Stream Peak**: Viral moment or notification spike

    **Late Growth**: Word-of-mouth effect or delayed notifications

#### Total Chat Messages

    **Description**: Number of chat messages sent during the livestream

    **Displayed With**:
    - Total message count
    - Time-series chart showing message frequency over time
    - Visualization of conversation peaks and valleys

    **Indicates**:
    - Audience engagement level
    - Interactive content effectiveness
    - Community participation

    **High Message Activity**: Engaged, interactive audience with effective community building

    **Message Spikes**: Identify what triggered conversation — controversial or exciting moments, Q&A effectiveness

    **Low Message Activity**: Passive viewing behavior — opportunity to add interactive elements

    **Optimization Tips**:
    - Ask questions to prompt chat
    - Acknowledge and respond to messages
    - Run polls or interactive segments

#### Total Reactions

    **Description**: Number of reactions (likes, emojis, etc.) sent during the livestream

    **Displayed With**:
    - Total reaction count
    - Time-series chart showing reaction frequency
    - Visual representation of emotional response moments

    **Reactions vs Messages Ratio**:
    - **High Reactions, Low Messages**: Passive but appreciative audience
    - **High Both**: Very engaged, interactive community
    - **Low Both**: Need to improve engagement strategies

### Stream Information

The Stream Info panel provides comprehensive metadata about the livestream session.

    - **Stream ID**: Unique alphanumeric identifier (e.g., `694a196acb7aa9a4dc1fef9a`) — useful for API integration and debugging
    - **Creator**: Username or display name of the stream creator

    - **Created At**: Timestamp when the livestream was created (format: `DD MMM YYYY, HH:MM:SS`)
    - **Started At**: Exact timestamp when the livestream began broadcasting
    - **Ended At**: Timestamp when the livestream ended
    - **Duration**: Total length of the livestream (`HH:MM:SS`)

    - **Total Minutes Watched**: Sum of all time spent watching by all viewers
    - **Total Views**: Number of view instances (includes repeat views)
    - **Average Concurrent Viewers**: Average number of viewers watching simultaneously (`Total Viewer-Minutes ÷ Stream Duration`)
    - **Peak Concurrent Viewers**: Maximum number of viewers watching at the same time — indicates highest engagement moment

### Time-Series Chart Analysis

All three engagement metrics display time-series charts showing activity throughout the stream.

    Shows stream timeline from start (00:00:00) to end. Hover over any point to see exact timestamp and value.
    Number of viewers, messages, or reactions at that moment. Adjusts automatically to data range.
    Identify peaks (highest engagement), valleys (low activity), and trends (growth, decline, or stability).

    Growing engagement throughout stream — content getting more interesting, word-of-mouth sharing, or delayed notifications reaching users.
    Declining engagement over time — content became repetitive, technical issues, or stream running too long.
    Sudden increases in activity — exciting moments, Q&A segments, or viral sharing. Review content at spike timestamp and replicate tactics.
    Consistent, stable engagement — high flat indicates solid audience; low flat suggests room for improvement.

---
## Related Topics

    Comprehensive analytics for posts, communities, and user interactions
    Detailed metrics for channel and direct message engagement
    User activity baseline and engagement patterns

---

### [Sentiment Analysis](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/sentiment-analysis)

> AI-powered sentiment analysis that automatically detects topics, classifies sentiment, and generates actionable summaries from community conversations.

Sentiment Analysis uses AI to examine threads across your application, detect conversation topics, classify each mention as positive, neutral, or negative, and produce summaries with actionable recommendations — all without manual tagging or surveys.

## Features

    Overall sentiment score (−100 to +100) with period-over-period comparison to track community health trends
    AI automatically identifies and tracks conversation topics across all analyzed threads
    Per-topic summaries of negative, neutral, and positive mentions with actionable recommendations
    Browse individual analyzed threads with detected topics and full conversation context
    Sentiment over time and mentions over time visualizations with percentage and absolute views
    Define the custom topics the AI tracks, and re-run the current configuration over past threads with retroactive tagging

## Getting Started

| Requirement | Details |
|---|---|
| Access | Dashboard login with Moderator or Analyst permission |
| Feature enablement | Sentiment Analysis enabled on your network (contact support if not visible) |
| Credits | Analysis uses thread credits — monitor usage in the credit banner |
| Navigation | **Dashboard → Social Insights → Sentiment analysis** |

Need Sentiment Analysis enabled? Email <a href="mailto:support@social.plus">support@social.plus</a> with your network ID.

## Credit & Analysis Coverage

At the top of the page a credit banner shows how many threads have been analyzed this calendar month, out of your monthly credit allocation.

- **Coverage percentage** — A circular gauge (e.g., *95%*) indicates how much of your monthly allocation has been consumed.
- **Thread count** — For example, *9520 of 10000 threads analyzed*.
- **Manage credit** — Click to view or adjust your credit allocation.

The credit banner always reflects the current calendar month and resets at the start of each month. It is **not** affected by the date range or filters you select on the page — changing the date picker will not change these numbers.

If the number of threads created or updated in your application exceeds your credit, not all threads will be analyzed by AI.

## Filtering & Date Range

### Date Range
Use the date picker in the top-right corner to select the analysis period. Comparison metrics (e.g., *+2 pts*, *+80%*) automatically reference the equivalent prior period.

### Filters
Click the **Filter** button to narrow analysis scope:

| Filter | Description |
|---|---|
| **Community** | Filter by one or more communities using *Matches any of* logic |
| **User tag** | Filter by user tags to focus on specific user segments |

    Click the **Filter** button next to the date picker.
    Choose communities and/or user tags from the dropdowns.
    Click **Apply** to refresh all tabs with the filtered data. Use **Clear all** to reset.

## Overview Tab

The Overview tab provides a high-level snapshot of sentiment across your entire application (or filtered scope).

### Key Metrics

    Net sentiment score from −100 to +100, where 0 means positive and negative mentions are balanced. Labeled **Positive** (above 0), **Neutral** (exactly 0), or **Negative** (below 0). Shows point change vs. the prior comparison period.
    Number of distinct topics the AI identified in the selected period. Shows percentage change vs. prior period.
    Aggregate count of all topic mentions across analyzed threads. Shows percentage change vs. prior period.

### How the Sentiment Score Is Calculated

The score is the **net balance** between positive and negative mentions, expressed on a scale from −100 to +100:

```
score = (positive mentions − negative mentions) / total mentions × 100
```

Worked example — 12 positive, 15 negative, and 63 neutral mentions (90 total):

```
(12 − 15) / 90 × 100 = −3.33  →  displayed as −3
```

    Neutral mentions **are** included in the total (the denominator), but never in the positive or negative counts.

    This means neutral mentions can never change whether a score is positive or negative — they only pull it *closer to zero*. A period that is overwhelmingly neutral will score near 0 even when the small non-neutral remainder leans one way:

    | Positive | Negative | Neutral | Total | Score |
    |---|---|---|---|---|
    | 12 | 15 | 0 | 27 | −11.1 |
    | 12 | 15 | 63 | 90 | −3.3 |
    | 12 | 15 | 300 | 327 | −0.9 |

    A small negative score such as −3 therefore means **"essentially balanced, leaning very slightly negative"** — not "3 out of 100".

    A mention is one **topic classification on one thread** — not one thread, and not one post.

    If a single thread is classified under three topics, it contributes **three mentions**, each with its own sentiment. A thread that is negative about several topics therefore carries more weight in the score than a single-topic thread.

    Because of this, the **Total Mentions** figure is normally higher than the number of threads analyzed, and will not match the thread count shown in the credit banner.

    Mentions are grouped by day across the selected range, then summed. The score is calculated **once on the period totals** — it is not an average of the daily scores, so higher-volume days carry proportionally more weight.

    The score is rounded to the nearest whole number for display only; the underlying value keeps full precision.

    Any manual sentiment overrides your team has applied take priority over the AI classification and are reflected in all charts and totals.

    The comparison period is the window of **equal length immediately preceding** your selection. Selecting a 14-day range compares it against the 14 days directly before it.

    The change is shown in **points on the −100 to +100 scale**, not as a percentage — if the current period scores −3 and the change reads *−25 pts*, the earlier period scored +22.

    The score is highly sensitive when mention volume is low. A period with just 3 positive and 2 neutral mentions scores +60. Large point swings between periods usually reflect a small sample rather than a real shift in community sentiment — check the mention counts for both periods before acting on a big change.

### Top Negative & Positive Topics

Two side-by-side panels highlight the topics with the highest concentration of negative and positive sentiment:

- **Top topic callout** — Shows the topic name, total mention count, and what percentage was negative or positive.
- **Horizontal bar chart** — Ranks the top 5 topics by total mentions. Negative chart bars are shown in red/orange; positive chart bars are shown in blue.

Hover over any bar in the chart to see a breakdown of negative, neutral, and positive mention counts for that topic.

### Sentiment Breakdown

A donut chart showing the distribution of all mentions across three categories:

- **Negative mentions** (red) — count and percentage
- **Neutral mentions** (orange/yellow) — count and percentage
- **Positive mentions** (blue) — count and percentage

### Sentiment Over Time

A line chart tracking how sentiment proportions change over the selected date range. Toggle between:

- **Percentage** — Shows each sentiment category as a percentage of daily total
- **Number** — Shows absolute mention counts per day

## Topic Analysis Tab

The Topic Analysis tab provides a sortable table of all detected topics with detailed metrics.

| Column | Description |
|---|---|
| **Topic** | Name of the detected topic |
| **Mentions** | Total number of mentions (sortable) |
| **Change** | Percentage change vs. the prior comparison period (sortable). Shows *No baseline* for newly detected topics |
| **Sentiment** | Stacked horizontal bar showing negative %, neutral %, and positive % |
| **Action** | **View insights** link to drill into the topic detail page |

### Topic Detail Page

Clicking **View insights** on any topic opens a dedicated page with deep analysis for that specific topic.

    - **Sentiment score** — Topic-specific score (−100 to +100) with comparison to prior period
    - **Total mentions** — Mention count for this topic with percentage change

    The right-side panel provides AI-generated insights organized by sentiment:

    - **Negative mentions** — Summary of key negative themes with a **View threads** button to see source posts
    - **Neutral mentions** — Summary of neutral/mixed feedback
    - **Positive mentions** — Summary of positive themes and praise
    - **Recommendation** — Actionable suggestions derived from the analysis (e.g., *"Address concerns urgently. Consider user feedback surveys."*)

    Line chart showing how mention volume for this topic changed over the selected date range.

    Donut chart showing negative, neutral, and positive distribution for this specific topic.

    Line chart with **Percentage** and **Number** toggle showing sentiment trend for this topic.

## Analyzed Threads Tab

The Analyzed Threads tab lets you browse the actual posts and comments that were analyzed.

### Thread List (Left Panel)

A scrollable list of analyzed threads showing:
- **Author name** and avatar
- **Timestamp** (e.g., *2 Apr 2026, 17:35*)
- **Community name** where the thread was posted
- **Content preview** — Truncated text of the original post
- **Engagement** — Reaction count and comment count

### Thread Detail (Right Panel)

Selecting a thread displays:
- **Topic detected** — Tags showing which topics the AI identified in this thread (editable via tag icons)
- **Full post content** — Complete text including hashtags, mentions, and links
- **Engagement metrics** — Reactions and comments count
- **Comment thread** — All comments and replies with author, timestamp, and nested replies

Use the Analyzed Threads tab to validate AI-generated summaries by reviewing the actual source posts that informed them.

## Settings

Access Settings via the **settings gear icon** (⚙) in the top-right corner of the Sentiment Analysis page. Settings has two tabs:

| Tab | Purpose |
|---|---|
| **Topic configuration** | Define the topics the AI tracks in new analyses |
| **Retroactive tagging** | Re-run the current topic configuration over threads that were already analyzed |

## Topic Configuration

This configuration applies to **new analyses only**. Changes take effect from the date they are saved, and previously completed analyses are not affected. To update past threads, use [Retroactive Tagging](#retroactive-tagging).

### Managing Topics

    Click the settings gear icon on the Sentiment Analysis page to navigate to **Topic configuration**.
    View the table of configured topics with their names and date added. The table is sortable by **Date added**.
    Click **+ Add topic** to define a new topic for the AI to track in future analyses.
    Click the delete icon (🗑) in the Action column to remove a topic from future analyses.

Removing a topic stops future analysis for that topic but does not delete historical data. Historical results remain available for the date range when the topic was active.

## Retroactive Tagging

Topic configuration changes only apply going forward, so threads analyzed before a topic existed carry no mentions of it. Retroactive tagging closes that gap: it reprocesses historical threads in a date range you choose using the **current** topic configuration, then updates those threads with the new results.

Open it via **settings gear icon (⚙) → Retroactive tagging**.

Typical use: you add a topic today and want last month's conversations counted against it, or the AI missed an emerging theme you have since configured.

### Job History

The tab lists every retroactive job for the network, newest first.

| Column | Description |
|---|---|
| **Date started** | When the job was submitted |
| **Data range** | The window that was reprocessed — threads published inside it are re-analyzed |
| **Topics applied** | The topic configuration snapshot used for the run (e.g., *30 topics*) |
| **Threads found** | Number of posts in the range that the job analyzed |
| **Status** | **Processing**, **Completed**, or **Failed** |
| **Action** | **View details** opens the job's side panel |

### Job Details

Click **View details** on any row to open a side panel containing:

- **Date range** as the panel title, with a note that historical threads in that range were reprocessed using the topic snapshot
- **Threads found** — the thread count for that job
- **Topic in this snapshot** — the exact topic list the run used, with each topic's *Date added*, sortable

Because the panel stores the snapshot, you can tell which topics existed at the time of a past run — useful when two jobs over the same range return different results.

### Running a Retroactive Job

    On the **Topic configuration** tab, verify the topic list is what you want applied. The job uses the configuration as it exists at submission time.
    On the **Retroactive tagging** tab, click **+ Apply retroactively**.
    Choose the window to reprocess. Presets cover **Last 7 days**, **Last 14 days**, and **Last 30 days**; a two-month calendar handles custom ranges. Future dates are disabled, and preset ranges end on the previous day.
    Click **Estimate**. The review step shows the data range with its day count, the number of topics being applied, the approximate **Threads found**, the **Credit required for this job**, and the **Credit remaining after** it runs.
    Click **Start retroactive**. The job is queued and begins processing when capacity is available; affected threads are updated once it completes.

**Retroactive jobs cannot be undone.** A running job can't be canceled, and a completed job can't be changed or deleted. Confirm the date range and credit cost on the review step before starting.

### Credit Cost

Retroactive jobs draw on the same thread credit pool as ongoing analysis — one credit per thread analyzed. **Threads found** on the review step is an estimate, and the review step is the only place the cost appears before the job starts.

## Daily Operational Workflow

    Open Sentiment Analysis and review the three KPI cards for any significant changes in sentiment score, topic count, or mention volume.
    Check the **Top negative topics** panel. If any topic shows a high negative percentage, click through to investigate.
    On the topic detail page, read the AI Summary panel's negative mentions and recommendations.
    Click **View threads** to review actual posts behind the AI summaries. Confirm findings before taking action.
    Use the **Sentiment over time** chart to check whether negative sentiment is a spike or sustained trend.
    Convert high-confidence recommendations into backlog tickets, content changes, or moderation actions.

## Best Practices

    - Monitor the credit banner regularly — if coverage drops below 80%, consider applying filters to prioritize high-value communities.
    - Use community and user tag filters to focus credits on segments that matter most.
    - Contact support to increase credit limits if your application consistently exceeds allocation.

    - Start with 5–10 broad topics and refine as patterns emerge from the AI analysis.
    - Review the Topic Analysis tab monthly to identify if any configured topics have zero mentions — consider replacing them.
    - Add new topics when you notice emerging themes in the Analyzed Threads tab.
    - Remember that topic changes only affect future analyses — use retroactive tagging to apply them to past threads.

    - Finish adding topics before submitting a job — each run snapshots the configuration, so a forgotten topic means paying for the same range twice.
    - Start with a short range to measure credit cost per day, then widen it.
    - Check **Credit remaining after** on the review step; a wide range over a busy period can consume a large share of the pool.
    - Use each job's detail panel to compare topic snapshots when two runs over the same range disagree.

    - A sentiment score of 0 indicates perfectly balanced sentiment — not necessarily good or bad. Scores near 0 (such as −4 or +3) mean the community is broadly balanced, not that sentiment is poor.
    - Focus on **change over time** rather than absolute scores — a 5+ point drop warrants investigation.
    - Cross-reference sentiment shifts with product releases, incidents, or campaigns for causal analysis.
    - Low mention volumes can cause score volatility — set a minimum threshold before acting on changes.

    - Always validate AI summaries by reviewing source threads before escalating issues.
    - Use the **Recommendation** section as a starting point, not a final directive — apply business context.
    - Compare negative topics against positive topics to understand relative priority.
    - Track whether actions taken improve sentiment in subsequent analysis periods.

## Related Topics

    Ad-hoc natural language analysis across community conversations
    Quantitative engagement and usage metrics for social features
    Export raw data for deeper custom analysis and reporting

---

### [Raw Data Export](https://learn.social.plus/analytics-and-moderation/social+-portal/dashboard/raw-data-export)

> Download row-level CSV snapshots for deeper ad‑hoc, cohort, and anomaly analysis beyond on-screen dashboard visualizations.

Use Raw Data Export when you need to move from dashboard trends to precise, joinable event rows—enabling custom pivots, cohort retention, feature adoption deep-dives, and external BI modeling.


## What You Can Answer


## Export Workflow


## Available Files

| Widget              | File(s) | Granularity | Primary Keys | Typical Question |
|---------------------|--------|-------------|--------------|------------------|
| Daily Engagements   | posts.csv | One row per post created on date | postId, posterUserId | Which creators spiked output? |
| Daily Engagements   | comments.csv | One row per comment/reply on date | commentId, parentCommentId, postId | Where did discussion concentrate? |
| Daily Engagements   | reactions.csv | Each reaction event | reactionId, postId, reactorUserId | Are reactions broad or concentrated? |
| Post Types          | post_types.csv | One row per post (lifecycle snapshot) | postId | Are video posts share increasing? |
| Reach & Impressions | reach.csv | Post-day tuple (unique viewers) | postId + date | Which dormant posts regained visibility? |
| Reach & Impressions | impressions.csv | Post-day tuple (total renders) | postId + date | Frequency vs reach divergence? |


## Column Reference

### Common Core Fields

| Column | Description |
|--------|-------------|
| date | UTC ISO 8601 day of the event/render |
| postId / commentId / reactionId | Unique event identifiers |
| posterUserId / commenterUserId / reactorUserId | Originating user IDs |
| targetType | Location container (community, userFeed, etc.) |
| targetId | ID of target container |
| postType | Content classification (text, image, video, poll, etc.) |
| deleted | Boolean flag (excludes rows if deleted before export) |

### File Specific Highlights


## Data Freshness & Snapshot Semantics

| Aspect | Behavior |
|--------|----------|
| Point-in-Time | Export reflects current state at generation moment. |
| Edits | Latest edited text retained (no historical versions). |
| Deletions | Hard-deleted content omitted to respect policy. |
| Late Events | Events arriving after generation won’t appear (re-export if critical). |
| Timezone | All timestamps normalized to UTC (convert downstream as needed). |

## Governance & Limits

| Area | Policy |
|------|--------|
| Row Cap | 10,000 rows per CSV (enforced server-side). |
| Frequency | Manual—no scheduling yet (automation roadmap). |
| Security | Links are signed & expire in 24h; share internally only. |
| Permissions | Respects dashboard visibility scopes; if you can’t see it, you can’t export it. |
| Format | UTF-8 CSV, comma-delimited, quoted where needed. |


## Joining & Derived Metrics

| Goal | Join Strategy | Derived Formula |
|------|---------------|-----------------|
| Reactions per Post Type | reactions.csv → posts.csv on postId | count(reactions)/count(posts) per postType |
| Comment Depth | comments.csv self-join via parentCommentId | avg(reply_depth) |
| Visibility Decay Curve | impressions.csv grouped by days since post creation | impression_count over lag day index |
| Frequency Factor | impressions.csv join reach.csv (postId+date) | impressions / reach |
| Content Creator Mix | posts.csv aggregated by posterUserRole | % share by role |

## Troubleshooting

| Symptom | Likely Cause | Investigation | Resolution |
|---------|-------------|---------------|-----------|
| Missing expected post | Deleted before export | Check moderation logs | Re-run earlier (if recoverable) or note exclusion |
| Row count hits 10k | Range too broad | Count estimate via shorter sample | Split date range / add filter |
| Stale email arrival | Mail delay / processing backlog | Check status page & timestamp | Wait; re-trigger if >30m |
| Empty CSV | No events in range | Validate widget chart shows data | Adjust date or remove restrictive filters |
| Data mismatch vs chart | Filter drift after export | Confirm filters at generation vs current | Regenerate with correct filters |
| Character encoding issues | Non-UTF tool import settings | Inspect raw file header | Force UTF-8 in BI tool |

## Best Practices


## FAQ

**Can I exceed 10k rows?** Not currently—split range or await API export.

**Are private communities included?** Yes, if your role grants visibility.

**Scheduled exports?** On roadmap—use calendar reminder interim.

**Historical text versions?** Not stored—only latest edit at generation time.

## Analytics & Moderation — Console

### [Overview](https://learn.social.plus/analytics-and-moderation/console/overview)

> Comprehensive administrative dashboard for managing social.plus applications, monitoring community health, and moderating content through an intuitive web interface

The social.plus Console is your comprehensive administrative dashboard for managing social.plus applications. Monitor community health, moderate content, manage users, and configure settings through an intuitive web interface designed for maximum efficiency and control.

## Overview

social.plus offers extensive moderation tools and capabilities designed to provide administrators with greater control over their communities. Moderation can occur at both the user level and admin level, with sophisticated automation and manual review options.

    AI-powered content filtering, automated rule enforcement, and intelligent safety measures
    Admin oversight, manual review workflows, and granular moderation decisions
    Community self-moderation, user reporting, and distributed moderation capabilities
    Centralized control panel for all moderation activities and community management

## Quick Start Guide

    Navigate to your application in [social.plus Portal](https://portal.amity.co) and click **"Go to Console"** to access your administrative dashboard
    Find your API key under **Settings** → **Security** for secure SDK integration and API access
    Set up content filtering rules and community guidelines in the **Moderation** section to establish safety standards
    Review moderation feed regularly to maintain healthy community dynamics

## Core Management Features

        Advanced AI-powered content filtering with customizable rules and automatic enforcement
        Comprehensive manual review workflows for complex moderation decisions
        Community safety tools, role management, and privilege control systems
        Real-time livestream content monitoring and safety enforcement
        Comprehensive user account management, roles, and permissions system
        Detailed user activity tracking and behavioral analysis tools
        Advanced admin access control and permission management
        User behavior patterns, engagement metrics, and community information
        Posts, comments, communities, and social interaction management
        Chat channel moderation, message filtering, and conversation management
        Monetization tools, ad campaign management, and revenue optimization
        Comprehensive analytics, engagement metrics, and performance insights
        Mobile-optimized console for reviewing and moderating content from your phone

## Management Areas

    **Community Operations**
    - **Communities**: Create, configure, and manage community spaces with advanced settings
    - **Posts & Comments**: Moderate user-generated content with automated and manual tools
    - **User Analytics**: Track engagement patterns, community health, and growth metrics
    - **Content Performance**: Monitor trending content and optimize community engagement

    **Engagement Tools**
    - Story management and moderation
    - Reaction system configuration
    - Community discovery optimization
    - User interaction monitoring
    **Real-Time Communication**
    - **Channels**: Moderate chat channels with real-time oversight and automated filters
    - **Messages**: Review, filter, and manage chat content with advanced moderation tools
    - **Member Management**: Control channel membership, permissions, and access levels
    - **Safety Enforcement**: Automated threat detection and response systems

    **Communication Features**
    - Direct message oversight
    - Group chat administration
    - Media sharing controls
    - Chat deletion
    **Platform Configuration**
    - **Security Settings**: API keys, authentication protocols, and access control management
    - **Push Notifications**: Certificate management, delivery optimization, and testing tools
    - **Webhooks**: Real-time event configuration, endpoint management, and integration setup
    - **Platform Integration**: Third-party service connections and API management

## Admin on the go

  The mobile-optimized version of the Console at [go.social.plus](https://go.social.plus) — review pending posts, clear flags, edit content, and publish from your phone, using the same account and the same permissions.

Admin on the go covers the time-sensitive moderation workflows: approving and declining pending posts, flagging and unflagging posts and comments, editing and deleting content, featuring posts globally, and creating or scheduling posts. Configuration, analytics, and advanced administration stay in the full Console.

## Getting Started Resources

    Complete walkthrough of console configuration, from basic setup to advanced features
    Comprehensive guide to content moderation, community safety, and automated enforcement
    Understanding community metrics, engagement data, and performance optimization

## Best Practices

    **Proactive Approach**
    - Establish clear community guidelines from the start
    - Implement graduated response systems for violations
    - Monitor community health metrics regularly
    - Foster positive community culture through recognition

    **Balanced Moderation**
    - Combine automated tools with human oversight
    - Maintain transparency in moderation decisions
    - Provide clear appeal processes for users
    - Regularly review and update moderation policies
    **Monitoring and Maintenance**
    - Set up automated alerts for critical issues
    - Regularly review analytics and performance metrics
    - Maintain updated documentation and procedures
    - Train team members on console features and best practices

    **Continuous Improvement**
    - Gather feedback from community members
    - Analyze moderation effectiveness regularly
    - Update policies based on community evolution
    - Stay informed about platform updates and new features

## Support and Resources

    Comprehensive guides, tutorials, and reference materials for all console features
    Connect with other administrators, share best practices, and get peer support
    Direct access to technical support team for complex issues and implementation guidance
    Video tutorials, webinars, and certification programs for console mastery

**Success Strategy**: Start with basic moderation settings and gradually implement advanced features as your community grows. Regular monitoring and adjustment of policies ensures optimal community health and engagement.

---

### [Getting Started](https://learn.social.plus/analytics-and-moderation/console/getting-started/overview)

> Step-by-step guide to accessing and setting up your social.plus Console for the first time

Get up and running with your social.plus Console in minutes. This guide covers everything you need to know for initial setup and basic configuration.

## Prerequisites

Before accessing your console, ensure you have:

- An active [social.plus Portal](https://portal.amity.co) account
- At least one social.plus application created in your portal
- Administrative access to your organization's social.plus account

## Accessing Your Console

    Navigate to [portal.amity.co](https://portal.amity.co) and sign in with your credentials.

    From the "My Applications" screen, locate the application you want to manage.

  {/* Removed missing image: My Applications Screen */}

    Click the "**Go to Console**" button for your selected application. This will open the social.plus Console in a new tab.

    You should now see the console dashboard with your application's data and management tools.

**Already a portal admin but the Console says "no permission"?** Portal and Console use separate permissions. Only a portal **Super Admin** gets Console access automatically; everyone else starts with no Console role, so **Go to Console** shows a no-permission screen.

A portal **Super Admin** or an existing Console admin must assign you a Console role first. See [Grant first-time access to a portal admin](/analytics-and-moderation/console/management/admin-access-control#grant-first-time-access-to-a-portal-admin).

## Initial Setup Checklist

### **1. Get Your API Key**

Your API key is essential for SDK integration and API access.

    In the console, go to **Settings** → **Security**

    Locate and copy your API key for use in your application

  {/* Removed missing image: API Key Location */}

    Store your API key securely - never expose it in client-side code

### **2. Configure Basic Moderation**

Set up essential moderation rules to keep your community safe.

    Navigate to **Moderation** → **AI Content Moderation**

    Turn on automated content filtering for text, images, and videos

    Configure AI confidence thresholds for different types of content

    Add custom blocked words and phrases specific to your community

### **3. Set Up User Roles**

Configure user roles and permissions for your moderation team.

    Understand the built-in roles: None, Moderator, Super-Moderator, Global-Admin

    Promote trusted users to moderator roles through **User Management**

    Review and adjust permissions for each role level

### **4. Configure Notifications**

Set up push notifications and alerts for your application.

    Add your iOS and Android push notification certificates in **Settings** → **Push Notifications**

    Send test notifications to verify your configuration

    Configure webhooks for real-time event handling in **Settings** → **Webhooks**

## Understanding the Dashboard

### **Main Navigation**

The console is organized into several key sections:

    - **Communities**: Manage community spaces and membership
    - **Posts**: Review and moderate user posts
    - **Comments**: Handle comment moderation and threading
    - **Users**: User account management and analytics

    - **Channels**: Moderate chat channels and conversations
    - **Messages**: Review chat messages and handle reports
    - **Members**: Manage channel membership and permissions

    - **AI Moderation**: Configure automated content filtering
    - **Review Queue**: Process manually flagged content
    - **Reports**: View moderation activity and statistics

    - **Security**: API keys, server keys, and authentication
    - **Push Notifications**: Certificate management and testing
    - **Webhooks**: Real-time event configuration
    - **Admin Users**: Team member management and permissions

### **Key Metrics Dashboard**

Your dashboard shows important metrics at a glance:

- **Active Users**: Current online users and recent activity
- **Content Statistics**: New posts, comments, and messages
- **Moderation Alerts**: Pending reviews and flagged content
- **System Health**: API usage and performance indicators

## Common First Tasks

**Start Simple**: Begin with basic moderation settings and gradually add more sophisticated rules as you understand your community's needs.

### **Review Existing Content**
1. Check the **Social Management** section for any existing posts or comments
2. Review user activity and identify any immediate moderation needs
3. Set up basic content filtering rules if needed

### **Configure Moderation Team**
1. Identify trusted users who should have moderator privileges
2. Assign appropriate roles through **User Management**
3. Set up moderation workflows and escalation procedures

### **Test Integration**
1. Verify your API key works with a simple SDK integration
2. Test push notifications with your mobile applications
3. Confirm webhook events are being received correctly

## Next Steps

Once you've completed the initial setup:

    Learn advanced content moderation techniques and workflows
    Understand your community metrics and engagement patterns
    Dive deeper into security, notifications, and integrations
    Implement programmatic administration with social.plus APIs

## Troubleshooting

    - Verify you're logged into the correct social.plus Portal account
    - Ensure you have admin permissions for the application
    - Check that your application is active and properly configured

    - Confirm you're using the correct API key for your environment
    - Verify the key hasn't been regenerated or revoked
    - Check that you're using the right regional endpoint

    - Verify push certificates are valid and properly uploaded
    - Check that your application bundle IDs match your certificates
    - Test with a simple notification to isolate the issue

**Security Note**: Never share your API keys or admin credentials. Regularly review and rotate keys as needed for security.

---

### [Product Catalogue](https://learn.social.plus/analytics-and-moderation/console/product-management/overview)

> Upload, manage, and preview products used for tagging in community content through the social.plus Console

The Product Catalogue in the social.plus Console allows administrators to manage a centralized product database. Products added here can be tagged in **posts** — in the post text or directly on image and video attachments — and in **livestream posts**, enabling social commerce experiences and product discovery within your application.

    View, search, and filter all products in a comprehensive table view

    Create individual products with details, pricing, images, and URLs

    Import multiple products at once via CSV file upload

    Update existing product details in bulk using CSV files

    Control product visibility with Active and Archived statuses

    Enable products to be tagged in community content for social commerce

## Overview

The Product Catalogue provides a centralized dashboard for uploading, managing, and previewing products that can be tagged in community content. This enables social commerce workflows where users can discover and engage with products directly within posts and livestream posts.

<img
  src="/images/analytics-and-moderation/console/product-management/product-catalogue-list.png"
  alt="Product Catalogue Dashboard"
/>

The product list displays all products with the following information at a glance:

| Column | Description |
|--------|-------------|
| **Thumbnail** | Product image preview |
| **Product ID** | Unique alphanumeric identifier for the product |
| **Product name** | Display name shown when the product is tagged in content |
| **Price** | Product price with currency |
| **URL** | Link to the product page |
| **Status** | Current status — `Active` or `Archived` |
| **Created at** | Timestamp of product creation |
| **Last updated** | Timestamp of the most recent update |
| **Updated by** | The admin user who last modified the product |
| **Actions** | Edit or delete the product |

You can search products by **name** and filter by **status** using the controls at the top of the page. Columns such as **Product name**, **Created at**, and **Last updated** support sorting.

## Quick Start

    Navigate to **Product catalogue** in the left sidebar of your social.plus Console
    Click **+ Add product** to create a product with an ID, name, URL, price, and thumbnail image
    Use the **Import** button to upload a CSV file with multiple products at once
    Set products as **Active** to make them available for tagging, or **Archived** to hide them from content tagging

## Adding a Product

Click the **+ Add product** button in the top-right corner to create a new product entry.

<img
  src="/images/analytics-and-moderation/console/product-management/add-product.png"
  alt="Add Product Form"
/>

### Product Details

    **Required** — A unique alphanumeric identifier for the product (max 100 characters). This ID cannot be changed after creation.

    **Example:** `SKU-12345`, `prod-widget-blue`

    **Required** — Controls product visibility for content tagging:
    - **Active**: Product is available for tagging in community content
    - **Archived**: Product is hidden from content tagging but retained in the catalogue

    **Required** — The display name shown when the product is tagged in content (max 200 characters). Choose a clear, recognizable name for your users.

    **Required** — The URL linking to the product page. The `https://` prefix is automatically applied.

    **Example:** `example.com/products/widget-blue`

    **Optional** — The product price with a selectable currency. The default currency is remembered from your last selection.

    **Optional** — A thumbnail image for the product. You can either:
    - **Upload a file**: Drag and drop or click to upload (`.png`, `.jpg`, up to 10 MB)
    - **Add from URL**: Provide a direct URL to the product image

    Recommended image aspect ratio is **1:1**. Image file size should remain under **1 GB**.

## Editing a Product

Click the **edit icon** (pencil) in the **Actions** column of any product row to modify its details.

<img
  src="/images/analytics-and-moderation/console/product-management/edit-product.png"
  alt="Edit Product Form"
/>

The edit form displays the same fields as the add form, with the following differences:

- **Product ID** is read-only and cannot be changed after creation
- All other fields (name, URL, price, status, images) can be updated
- Click **Save changes** to apply your modifications

## Importing Products via CSV

Click the **Import** button to bulk-create products from a CSV file.

<img
  src="/images/analytics-and-moderation/console/product-management/import-products.png"
  alt="Import Product Dialog"
/>

    Click **Download sample CSV** to get the required file format and column structure
    Fill in the CSV with your product data. Ensure all required columns are included and the file follows the sample format
    Drag and drop your `.csv` file into the upload area, or click **Choose file** to browse. Maximum file size is **15 MB**
    Click **Import** to begin processing. A status notification will appear showing the import progress and summary

The import function creates **new products** in your catalogue. Each row in the CSV should contain a unique product ID that does not already exist in the catalogue.

## Updating Products via CSV

Click the **Update** button to bulk-update existing products from a CSV file.

<img
  src="/images/analytics-and-moderation/console/product-management/update-products.png"
  alt="Update Product Dialog"
/>

Each row in the update CSV must include a valid **product_id** that already exists in the catalogue. Rows with unrecognized product IDs will be skipped.

    Click **Download sample CSV** to see the expected column format for updates
    Include the `product_id` column along with any fields you want to update
    Upload the `.csv` file (up to **15 MB**) and click **Update** to apply changes

## Deleting Products

Click the **delete icon** (trash) in the **Actions** column to remove a product from the catalogue.

Deleting a product is permanent and cannot be undone. Products that have already been tagged in content may show as unavailable after deletion.

You can also select multiple products using the checkboxes in the leftmost column for batch operations.

### Product Tagging in Posts

You can tag products from the Product Catalogue directly in post content by typing `@` followed by the product name, then switching to the **Tag product** tab in the dropdown. Tagged products appear as interactive links in the post and display with thumbnails and pricing below the content.

For the full product tagging workflow, screenshots, and guidelines, see [Tagging Products in Posts](/analytics-and-moderation/console/social-management/social-management/posts#tagging-products-in-posts) in the Post Management documentation.

## Filtering and Searching

The Product Catalogue provides several ways to find specific products:

| Feature | Description |
|---------|-------------|
| **Search by name** | Type in the search field to filter products by product name |
| **Filter by status** | Use the status dropdown to show only `Active` or `Archived` products |
| **Sort by column** | Click sortable column headers (Product name, Created at, Last updated) to reorder the list |

## Best Practices

    - Use a consistent naming scheme for product IDs (e.g., `SKU-001`, `prod-category-name`)
    - Product IDs cannot be changed after creation, so plan your ID structure carefully
    - Keep IDs alphanumeric and under 100 characters

    - Use the **Import** feature for initial catalogue setup with many products
    - Use the **Update** feature for ongoing maintenance and price/status changes
    - Always download and review the **sample CSV** before preparing your data
    - Validate your CSV before uploading to minimize errors

    - Use a **1:1 aspect ratio** for consistent thumbnail display
    - Keep images under **10 MB** for file uploads
    - Use high-quality images that clearly represent the product
    - Provide image URLs from reliable, fast-loading CDNs when using the URL method

    - Set seasonal or discontinued products to **Archived** rather than deleting them
    - Use the status filter to quickly audit active vs. archived products
    - Archived products are retained in the catalogue but hidden from content tagging

## Related Topics

    Manage communities where products can be tagged in content
    Create and manage events alongside product promotions
    Learn about all Console features and administration capabilities

---

### [AI Content Moderation](https://learn.social.plus/analytics-and-moderation/console/ai-content-moderation)

> Leverage AI-powered moderation tools to create safer communities with automated content filtering and intelligent threat detection

Create safer online communities with intelligent, automated content moderation. social.plus leverages advanced AI to scan and filter inappropriate content across text, images, and video, ensuring community standards are maintained without constant manual oversight.

    Block inappropriate content before it's published with proactive AI scanning
    Monitor and review published content with intelligent flagging and automated actions

## Overview

social.plus offers two complementary AI moderation approaches:

    **Proactive Content Filtering**
    - Content is scanned before publication
    - AI generates confidence scores for detected violations
    - Content blocked if confidence exceeds configured threshold
    - User must modify content to proceed with posting

    **Reactive Content Review**
    - Content is scanned after publication
    - Uses `flagConfidence` and `blockConfidence` thresholds
    - Automatically flags content for review or removes violations
    - Maintains community safety without blocking legitimate content

## Getting Started

    Contact our [support team](mailto:support@social.plus) to enable AI content moderation for your application.

    Set up confidence levels and moderation categories through the social.plus Console.

    Test with sample content and monitor moderation effectiveness through analytics.

## AI Pre-Moderation

Prevent inappropriate content from reaching your community with proactive AI scanning. Pre-moderation ensures all content meets your standards before publication.

**Current Availability**: Pre-moderation is currently available for image content, with text and video support coming soon.

### Image Content Detection

Our AI pre-moderation scans all uploaded images for inappropriate content across four key categories:

    - **Nudity**: Detection of explicit or inappropriate nudity
    - **Suggestive Content**: Sexually suggestive or provocative imagery
    - **Violence**: Violent or graphic content detection
    - **Disturbing Content**: Content that may be psychologically disturbing

### Configuration

    Navigate to **Moderation > Image Moderation** in your social.plus Console and toggle "Enable image moderation" to **ON**.

    Configure confidence thresholds for each category based on your community standards.

    Upload test images to verify your confidence settings work as expected.


### Understanding Confidence Levels

**Important**: Confidence levels significantly impact moderation accuracy. Default settings may produce false positives.

Confidence levels represent the AI's certainty in detecting specific content types:

- **Low Confidence (0-30)**: High sensitivity, may block legitimate content
- **Medium Confidence (40-70)**: Balanced approach for most communities
- **High Confidence (80-100)**: Conservative filtering, may miss some violations

**Recommendation**: Start with medium confidence levels (40-60) and adjust based on your community's needs and false positive rates.


### Retaining Rejected Uploads

When pre-moderation refuses an image, the upload fails and the file is gone. There is nothing to look at if the uploader disputes the decision, nothing to tune your thresholds against, and no record that the attempt happened at all.

Turning on **reserved for review** changes that: social.plus keeps the refused original and tells your backend, over a webhook, the moment a rejection happens. Your moderators can then look at what the classifier actually blocked.

Retention is off by default and applies to images, the only content type pre-moderation covers today. The upload response is identical whether it is on or off, so your apps need no changes.

    Send `reservedForReview: true` to [Update file configuration](/api-reference/network-setting/update-file-configuration) with an admin token.

    Add [`file.didReject`](/api-reference/webhook-event/file-didreject-webhook-event) to your webhook subscription. It carries the `fileId` of the retained file — the upload response never does, so this event is the only way to learn it.

    Fetch the retained image with [Download file](/api-reference/file/download-file), using the `fileId` from the event. Remove it when you are done with [Delete file](/api-reference/file/delete-file).

#### What the uploader sees

Nothing changes. A refused image still returns `403` with error code `400314` (`UnsafeContent`) and no `fileId`, whether or not retention is on:

```json
{
  "status": "error",
  "code": 400314,
  "message": "Image uploading failed: Nudity content is not permitted"
}
```

The message names the first category that breached its threshold: `Nudity content is not permitted`, `Suggestive content is not permitted`, `Violence content is not permitted`, or `Disturbing content is not permitted`.

#### What is retained

A retained file is an ordinary file document with `status` set to `rejected`. It uses the same `fileId`, the same file endpoints, and the same `network` access type as any other file your network owns.

Two differences are worth knowing:

- **Only the original is kept.** No resized variants are generated, so a download returns the original whatever `size` you ask for.
- **The rejection details are not on the file.** Reading the file never returns them. They reach you through the `file.didReject` webhook only.

Retention covers images, matching pre-moderation's coverage. A file that is deleted is deleted normally, whether or not it was retained.

#### Rejection and upload events

Three file lifecycle events are available to webhook subscribers:

| Event | Fires when |
|-------|------------|
| [`file.didUpload`](/api-reference/webhook-event/file-didupload-webhook-event) | A user uploads a file successfully |
| [`file.didReject`](/api-reference/webhook-event/file-didreject-webhook-event) | Pre-moderation refuses an image |
| [`file.didDelete`](/api-reference/webhook-event/file-diddelete-webhook-event) | A file is deleted |

`file.didReject` is useful on its own. With retention off, you still receive every rejection — with the classifier's verdict but no `file`, because no file was kept. A rejected upload raises this event instead of `file.didUpload`.

Its `rejection` object lists every category that breached its threshold with the confidence the classifier assigned, echoes your network's configured thresholds, and carries the message the uploader saw — enough to tell a marginal call from a clear one, and to tune your thresholds from real traffic.

**The rejection details are sensitive.** They pair your configured thresholds with the classifier's scores. Treat the `file.didReject` payload as admin-only data and do not forward it to end users. This is why reading the file never returns it.

## AI Post-Moderation

Monitor and moderate published content with intelligent detection and automated response workflows. Post-moderation provides comprehensive scanning across all content types while maintaining user experience.

All AI post-moderation results are surfaced through the **Moderation Feed** in the social.plus Console, located under **Moderation > Moderation feed**.

    Detect inappropriate language, hate speech, and harmful text content
    Scan visual content for policy violations and harmful imagery
    AI moderation for display names, avatars, and descriptions — see dedicated page

### Moderation Feed

The Moderation Feed is the central hub for reviewing AI-flagged content. It is organized into two main workflow tabs:

    The **To review** tab displays all content that requires moderator attention, organized into sub-tabs:

    - **Posts and comments** — Flagged posts and comments from communities and user timelines
    - **Messages** — Flagged messages from channels and direct conversations
    - **Users** — Flagged user profiles — see [AI User Profile Moderation](/analytics-and-moderation/console/ai-user-profile-moderation)

    Each flagged item displays:
    - The AI moderation label and detected categories (e.g., "AI Mod: Harassment or bullying")
    - PII detection results when applicable (e.g., URLs, person types)
    - The number of user reports (e.g., "1 user", "4 users")
    - The last flagged timestamp
    - Available moderation actions

    **Available actions for posts and messages:**
    - **Delete post / Delete message** — Remove the content
    - **Clear flag** — Dismiss the flag and approve the content

    The **Reviewed** tab shows content that has already been moderated, organized into the same three sub-tabs (Posts and comments, Messages, Users).

    Each reviewed item shows the action taken and who performed it:
    - **Flag cleared by [moderator]** — Flag was dismissed
    - **Deleted by [moderator]** — Content was removed
    - **Reviewed by [moderator]** — Content was reviewed without a specific action

    The Reviewed tab includes an additional **Select moderator** filter to view actions taken by a specific team member.

Use the filter dropdowns (All feeds / All Channels, Select creator / Select sender) to narrow down the moderation queue by community, channel, or content creator.

### Content Coverage

    - Text, images, videos, clips, files, and livestream content
    - Posts across all communities and user timelines
    - Comments and reply chains on posts
    - Filter by specific community feed or content creator

    - Text, image, video, audio, and file messages
    - Messages from group channels, direct messages, and live chat
    - Filter by specific channel or message sender

### Text Content Detection

The AI text moderation identifies and handles various types of inappropriate text content. Each category is scored on a severity scale from 0 to 7.

    Each name below is a value for the `category` field. To set thresholds for one, add an entry like this to your configuration:

```json
{ "category": "SelfHarm", "flagConfidence": 2, "blockConfidence": 5, "moderationType": "text" }
```

    - **`Hate`**: Hate speech targeting protected groups
    - **`Sexual`**: Adult content and explicit sexual references
    - **`ViolenceText`**: Violent threats, graphic descriptions, or dangerous activities
    - **`SelfHarm`**: Content related to self-harm or suicidal ideation

    See [API Configuration](#api-configuration) for the full request, and [Understanding Confidence Scores](#understanding-confidence-scores) for the default thresholds.

    In addition to content policy categories, the AI performs **Personally Identifiable Information (PII) detection** to flag sensitive data:
    - **URL** — Links and web addresses embedded in content
    - **PersonType** — References to specific person types or identities

Content that passes all AI checks displays **"AI Mod: Passed"** in the moderation feed. Content with detected violations shows the specific category labels.

### Multimedia Content Detection

**Comprehensive Scanning**: Our AI analyzes both static images and video content frame-by-frame for maximum protection.

Advanced visual content analysis covers extensive categories, each scored on a confidence scale from 0 to 100. Images and videos share the same set of categories.

Every name in the groups below is a value for the `category` field. To set thresholds for one, add an entry like this to your configuration:

```json
{ "category": "Explicit Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" }
```

Categories are grouped here for readability only — the grouping has no effect on configuration, and each name is set independently. See [API Configuration](#api-configuration) for a request containing every category.

    - `Explicit Nudity`, `Exposed Female Genitalia`, `Exposed Male Genitalia`
    - `Explicit Sexual Activity`, `Sexual Activity`, `Sex Toys`
    - `Non-Explicit Nudity of Intimate parts and Kissing`, `Implied Nudity`, `Kissing on the Lips`
    - `Exposed Male Nipple`, `Barechested Male`
    - `Swimwear or Underwear`, `Female Swimwear or Underwear`, `Male Swimwear or Underwear`
    - `Graphic Female Nudity`, `Graphic Male Nudity`, `Illustrated Explicit Nudity`

    - `Violence`, `Physical Violence`, `Weapon Violence`, `Weapons`
    - `Blood & Gore`, `Explosions and Blasts`
    - `Self-Harm`, `Corpses`, `Emaciated Bodies`
    - `Visually Disturbing`, `Air Crash`

    - `Alcohol`, `Alcoholic Beverages`, `Drinking`
    - `Drugs & Tobacco`, `Drugs & Tobacco Paraphernalia & Use`, `Drug Products`
    - `Pills`, `Smoking`

    - `Hate Symbols`, `Extremist`, `Nazi Party`, `White Supremacy`
    - `Rude Gestures`, `Middle Finger`

    - `Gambling`


**User Profile Moderation**: AI moderation for user profiles (display names, avatars, descriptions) is covered in a dedicated page. See [AI User Profile Moderation](/analytics-and-moderation/console/ai-user-profile-moderation) for setup, admin reset workflows, blocklist configuration, and moderation feed details.

### Understanding Confidence Scores

Each category has two thresholds. Content is removed when its score reaches the block threshold, and flagged for review when it reaches the flag threshold.


    **Flag Confidence-Media** (Default: 40)
    - Content scoring at or above this level gets flagged for review
    - Lower values = more content flagged (higher sensitivity)
    - Recommended range: 30-60 depending on community standards

    **Block Confidence-Media** (Default: 80)
    - Content scoring at or above this level gets automatically removed
    - Higher values = fewer false positives
    - Recommended range: 70-90 for balanced protection

    **Flag Confidence-Text** (Default: 3, or 2 for `SelfHarm`)
    - Content scoring at or above this level gets flagged for review
    - Lower values = more content flagged (higher sensitivity)
    - Recommended range: 3-4 depending on community standards

    **Block Confidence-Text** (Default: 5)
    - Content scoring at or above this level gets automatically removed
    - Higher values = fewer false positives
    - Recommended range: 4-5 for balanced protection

    **Media Moderation (From 0 to 100 Scale)**
    - **0-39**: Content passes moderation (approved)
    - **40-79**: Content flagged for human review
    - **80-100**: Content automatically blocked/removed

    **Text Moderation (From 0 to 7 Scale)**
    - **0-2**: Content passes moderation (approved)
    - **3-4**: Content flagged for human review
    - **5-7**: Content automatically blocked/removed

    *Note: These ranges use default thresholds and can be customized. For text moderation, thresholds should be integers from 0 to 7. Because the classifier produces integer severity levels, a fractional threshold is effectively rounded up to the next integer—for example, 4.5 behaves as 5. There is no finer-grained score between integer levels.*

**Default Configuration**: Media categories start with `flagConfidence: 40` and `blockConfidence: 80`. Text categories start with `flagConfidence: 3` and `blockConfidence: 5`, except `SelfHarm`, which flags from 2. Monitor your community's content patterns and adjust these values to optimize for your specific needs.

### Configuration Parameters

    | Parameter | Type | Description |
    |-----------|------|-------------|
    | `enabled` | Boolean | Turns AI post-moderation on or off for the network |
    | `commentDeletionBehavior` | String | `delete_whole_comment` (default) or `delete_attachment_only` |
    | `confidences` | Array | One entry per category, 1 to 100 entries. Sending this field replaces the entire stored list |
    | `category` | String | Exact name of the moderation category, case-sensitive |
    | `flagConfidence` | Number | Threshold for flagging content (0-100 for Media and 0-7 for Text) |
    | `blockConfidence` | Number | Threshold for blocking content (0-100 for Media and 0-7 for Text) |
    | `moderationType` | String | Type of content: `text` or `media`. Images and videos both use `media` |
    | `userModerationExclusionPatterns` | Array | Regex patterns matching user IDs that should never be moderated |
    | `avatarCustomUrlEnabled` | Boolean | Moderates externally hosted avatar URLs. Off by default |

**Sending `confidences` replaces the whole list**: the API does not merge your entry into the stored configuration. Any category you leave out is removed and stops being moderated. Always send the complete list, as shown in the example below.

### API Configuration

    Select the appropriate API endpoint for your region to ensure optimal performance:

    | Region | API Endpoint |
    |--------|-------------|
    | **Europe** | `https://apix.eu.amity.co` |
    | **Singapore** | `https://apix.sg.amity.co` |
    | **United States** | `https://apix.us.amity.co` |

    Both requests use the same path:

```
GET  /api/v3/network-settings/enhance-moderation
PUT  /api/v3/network-settings/enhance-moderation
```

    The `PUT` requires an admin access token. The `GET` can be read with any authenticated user token.

    *Note: The settings API is designed with eventual consistency, so a subsequent GET may temporarily return the previous configuration. The successful PUT response is the authoritative acknowledgement of the accepted update and can be used for programmatic verification.*


```bash Retrieve current configuration
curl 'https://apix.eu.amity.co/api/v3/network-settings/enhance-moderation' \
  -H 'Authorization: Bearer <ADMIN_TOKEN>'
```

```bash Update all categories
curl -X PUT 'https://apix.eu.amity.co/api/v3/network-settings/enhance-moderation' \
  -H 'Authorization: Bearer <ADMIN_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "confidences": [
  { "category": "Hate", "flagConfidence": 3, "blockConfidence": 5, "moderationType": "text" },
  { "category": "Sexual", "flagConfidence": 3, "blockConfidence": 5, "moderationType": "text" },
  { "category": "ViolenceText", "flagConfidence": 3, "blockConfidence": 5, "moderationType": "text" },
  { "category": "SelfHarm", "flagConfidence": 2, "blockConfidence": 5, "moderationType": "text" },
  { "category": "Air Crash", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Alcohol", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Alcoholic Beverages", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Barechested Male", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Blood & Gore", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Corpses", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Drinking", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Drug Products", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Drugs & Tobacco", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Drugs & Tobacco Paraphernalia & Use", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Emaciated Bodies", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Explicit Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Explicit Sexual Activity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Explosions and Blasts", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Exposed Male Genitalia", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Exposed Male Nipple", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Exposed Female Genitalia", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Extremist", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Female Swimwear or Underwear", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Gambling", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Graphic Female Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Graphic Male Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Hate Symbols", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Illustrated Explicit Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Implied Nudity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Kissing on the Lips", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Male Swimwear or Underwear", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Middle Finger", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Nazi Party", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Non-Explicit Nudity of Intimate parts and Kissing", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Physical Violence", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Pills", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Rude Gestures", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Self-Harm", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Sex Toys", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Sexual Activity", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Smoking", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Swimwear or Underwear", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Violence", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Visually Disturbing", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Weapon Violence", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "Weapons", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" },
  { "category": "White Supremacy", "flagConfidence": 40, "blockConfidence": 80, "moderationType": "media" }
    ]
  }'
```

    The example above sends every available category at its default thresholds, so it is a safe starting point to copy and edit. Change the `flagConfidence` and `blockConfidence` values you want to tune, and remove any category you do not want moderated.

    The optional fields `enabled`, `commentDeletionBehavior`, `userModerationExclusionPatterns`, and `avatarCustomUrlEnabled` can be sent in the same request body, and are written only when included.

## API Reference

For detailed administration workflows, see the [Moderation Overview](/analytics-and-moderation/console/moderation/overview) and analytics export documentation.

## Best Practices

    - **Start Conservative**: Begin with moderate confidence levels and adjust based on results
    - **Monitor Performance**: Track false positive and false negative rates
    - **Community-Specific**: Tailor settings to your community's content standards
    - **Regular Review**: Periodically review and update thresholds as your community evolves

    - **Review Queue Management**: Ensure consistent review of flagged content
    - **Moderator Training**: Train team on community standards and edge cases
    - **Appeal Process**: Provide clear paths for users to contest moderation decisions
    - **Transparency**: Communicate moderation policies clearly to users

    - **Batch Processing**: Handle high-volume content efficiently
    - **Regional APIs**: Use geographically appropriate endpoints
    - **Webhook Integration**: Implement real-time event handling for flagged content
    - **Monitoring**: Set up alerts for unusual moderation patterns

---

### [AI User Profile Moderation](https://learn.social.plus/analytics-and-moderation/console/ai-user-profile-moderation)

> AI-powered moderation for user profiles including display names, avatars, and descriptions, with field-level admin reset for any user

Extend your community safety beyond content with AI-powered user profile moderation. social.plus automatically scans user profiles — including display names, avatars, and descriptions — for policy violations, giving admins the tools to review and act on flagged profiles. Admins can also reset **any** user's profile — flagged or not — from the User History page, choosing exactly which fields to reset.

    AI reviews profile content after save — flag-only, no auto-delete
    Reset any user's profile from User History — pick which fields (display name, avatar, description) to restore
    Unified Users tab to review AI-flagged and user-reported profiles
    Dedicated blocklist category for display names and descriptions

## Overview

AI User Profile Moderation is a **post-moderation** system — profiles are scanned after the user saves changes. Unlike content moderation (posts, comments, messages), user profile moderation is **flag-only**: the block confidence threshold that auto-deletes content does not apply to user profiles. Admins must explicitly decide to reset, clear the flag, or ban the user.

```mermaid
graph LR
    A[User Updates Profile] --> B[Profile Saved]
    B --> C[AI Scans Text & Image]
    C -->|Violation Detected| D[Profile Flagged]
    C -->|No Violation| E[AI Mod: Passed]
    D --> F[Appears in Moderation Feed]
    F --> G{Admin Action}
    G -->|Reset Profile| H[Fields Reset to Defaults]
    G -->|Clear Flag| I[Flag Dismissed]
    G -->|Ban Globally| J[User Banned]
    H --> K[User Notified]
```

**Flag-Only for Profiles**: Unlike posts and messages, the block confidence threshold does **not** auto-delete user profile content. All flagged profiles require manual admin review. This ensures that user accounts are never silently wiped by automated systems.

## What Gets Scanned

AI moderation scans three profile fields after each update:

| Field | Scan Type | Pre-Moderation | Post-Moderation |
|-------|-----------|----------------|-----------------|
| **Display Name** | Text | ❌ | ✅ Flagged if violation detected |
| **Description** | Text | ❌ | ✅ Flagged if violation detected |
| **Avatar** (uploaded file) | Image | ✅ Blocked before upload | ✅ Flagged after save |

**Avatar Pre-Moderation**: Uploaded avatar images are already scanned at upload time via. Post-moderation provides a second layer of review after the profile is saved.

**External avatar URLs**: Avatars set with `avatarCustomUrl` are not moderated. Only uploaded avatars (`avatarFileId`) are scanned, flagged, and reset.

## Detection Categories

User profile text is scanned against the same categories as posts, comments, and messages:

    - **Harassment or Bullying**: Targeted abuse or intimidation in display names or descriptions
    - **Sexual Content or Nudity**: Explicit sexual references in profile text
    - **Violence or Threatening Content**: Violent threats or graphic descriptions
    - **Hate**: Hate speech targeting protected groups
    - **Fraudulent Intent and Scam Promotion**: Scam tactics, phishing links in descriptions
    - **Self Harm or Suicide**: Content related to self-harm or suicidal ideation

    - **URL** — Links and web addresses embedded in profile descriptions
    - **PersonType** — References to specific person types or identities

    Avatar images are scanned for the same visual categories as other media content:
    - Adult content, nudity, and suggestive imagery
    - Violence and harmful content
    - Hate symbols and extremist content
    - Substance-related content

    See [AI Content Moderation — Multimedia Content Detection](/analytics-and-moderation/console/ai-content-moderation#multimedia-content-detection) for the full list of image categories.

## Confidence Thresholds

User profile moderation reuses the same text and image confidence thresholds configured for content moderation. However, only the **flag confidence** threshold applies — there is no auto-block for user profiles.

| Threshold | Applies to Profiles? | Behavior |
|-----------|---------------------|----------|
| **Flag Confidence** (default: 40) | ✅ Yes | Profile flagged for admin review |
| **Block Confidence** (default: 80) | ❌ No | Does **not** auto-delete profile fields |

Confidence thresholds are shared across content and user profiles. If you need different sensitivity for profiles, this would require a future enhancement for separate threshold configuration.

## Moderation Feed — Users Tab

Flagged user profiles appear in a dedicated **Users** tab within the Moderation Feed (**Moderation > Moderation feed**), alongside the existing Posts/Comments and Messages tabs.

    The **To Review** list displays all user profiles that require moderator attention.

    Each flagged profile shows:
    - AI moderation labels with category occurrence counts (e.g., "Hate (2)", "Violence (1)")
    - Whether the display name or description triggered the flag — indicated by a **(Profile description is flagged)** label
    - User report counts from other community members (e.g., "4 users")
    - Last flagged timestamp

    **Finding profiles:**
    - **Search by user ID or name** (at least 3 characters)
    - **Report source**: All sources, User reports, or AI moderation
    - **Advanced filter**: Report type (Display name, Description, Profile photo, Behavior), Report reasons for Behavior reports (To Review only), and user Tags
    - **Sort**: Last flag date, Flag count, or Created date

    **Available actions:**
    - **Reset profile** — Reset flagged profile fields to safe defaults
    - **Ban globally** — Ban the user across all communities
    - **Clear flag** — Dismiss the flag and approve the profile. When the user has Child endangerment behavior reports, the confirm dialog says how many reports clearing removes.

    To reset a profile that has **not** been flagged, use the [User History page](#admin-reset) — it opens the same reset modal for any user.

    The **Reviewed** list shows profiles that have already been moderated.

    Each reviewed item displays the action taken and who performed it:
    - **Flag cleared by [moderator]**
    - **Globally banned by [moderator]**
    - **Profile reset by [moderator]**

    Use the **Select reviewer** filter to view actions taken by specific team members, and the **Advanced filter** to narrow by user Tags.

## Admin Reset

Resetting a profile does not require the profile to be flagged. From the **User History** page, admins can reset **any** user's profile at any time — whether it was flagged by AI, reported by other members, or never flagged at all. Flagging simply surfaces the profiles that may be worth resetting.

Both entry points open the **same reset modal**, where the admin ticks which profile fields to restore:

| Where | Applies to |
|-------|-----------|
| **Moderation feed > Users tab** | Profiles in the review queue (AI-flagged and user-reported) |
| **User History page** | Any user, flagged or not |

### Reset Behavior by Field

| Field | Reset Behavior |
|-------|---------------|
| **Display Name** | Set to `{configuredPrefix}{UUID(12)}` (e.g., `User_a1b2c3d4e5f6`) |
| **Description** | Cleared (set to empty) |
| **Avatar** | Removed — reverts to default avatar. Original file is deleted from storage. |

### Resetting a Profile from User History

Reset is **field-level** — the admin ticks which of the three profile fields to restore. Fields that are not ticked are left untouched.

    Find the user in the Console and open their [User History](/analytics-and-moderation/console/user-and-content-management/user-social-history) page. This works for any user, flagged or not.

    Check the user's profile details and moderation history — including any AI moderation labels and past flags — before deciding to reset.

    Click the three-dot (**⋮**) menu and choose **Profile moderation**. The submenu offers **Clear flags** and **Reset profile**.

    Choose **Reset profile**. The reset modal opens — the same one used in the Moderation feed — listing the three profile fields as checkboxes.

    Tick the fields you want restored to defaults: **Display name**, **Avatar**, **Description**, or any combination. At least one field must be ticked.

    Confirm the reset. Only the ticked fields are changed, and the user is notified of which fields were reset.

**Avatar Reset is Irreversible**: When an avatar is reset, the original file is deleted from storage. Only the fact that a reset occurred is logged — the original image cannot be recovered.

The display name reset prefix is configurable via the network setting `moderation.displayNameResetPrefix` (API-only).

## User Notifications

When a profile is reset, the affected user receives a notification through the notification tray:

- **Notification type**: `USER_PROFILE_RESET`
- **Content**: Informs the user which fields were reset — only the fields actually reset are listed — and that they can update their profile again
- Delivered via the existing notification tray system

## Profile Blocklist

A dedicated blocklist category for user profiles allows admins to block specific words and phrases from appearing in display names and descriptions.

| Blocklist Category | Applies To | Description |
|-------------------|-----------|-------------|
| **Content** (existing) | Posts, comments, messages | Standard content blocklist |
| **User Profile** (new) | Display names, descriptions | Blocks words/phrases in profile text |

The profile blocklist is independent from the content blocklist. You can maintain different blocked terms for user profiles versus post/comment content.

## User History

Profile moderation events are recorded in the user's activity history, accessible from the User History page:

- **AI flag events**: When AI detects a violation in a profile field
- **Profile reset events**: Logged as `RESET_USER_PROFILE` activity with details on which fields were reset, the actor, and reason
- **Moderation actions**: Flag cleared, globally banned, etc.

## Best Practices

    - **Prioritize by severity**: Review profiles with multiple AI flag categories first
    - **Check context**: Some display names or descriptions may be flagged incorrectly — review before resetting
    - **Use reset judiciously**: Resetting a profile is disruptive to the user; prefer clearing the flag for borderline cases
    - **Reset only what's wrong**: Untick the fields that are fine — clearing a clean display name alongside an offending avatar is unnecessary churn for the user
    - **Monitor repeat offenders**: Users who are repeatedly flagged may warrant a global ban

    - **Separate concerns**: Maintain different blocklists for content vs. user profiles
    - **Common patterns**: Add known offensive display name patterns to the profile blocklist
    - **Regular updates**: Review and update the blocklist as new patterns emerge
    - **Test impact**: Check existing users before adding broad blocklist terms

    - **Shared thresholds**: Remember that confidence thresholds are shared between content and profiles
    - **Monitor false positives**: Track how often legitimate profile content gets flagged
    - **Flag-only safety net**: Since profiles are flag-only, a lower flag threshold is safer than with content (no risk of auto-deletion)

## Limitations

- **Flag-only**: AI cannot auto-delete user profile content — all flagged profiles require admin review
- **External avatar URLs**: Avatars set with `avatarCustomUrl` are not moderated — use `avatarFileId` for avatars that need moderation
- **Shared confidence thresholds**: Profile and content moderation share the same flag thresholds; separate configuration is not yet available
- **Original avatar not recoverable**: Once an avatar is reset, the original file is permanently deleted from storage

## Related Topics

    AI moderation for posts, comments, messages, images, and video content
    General moderation tools, roles, and workflows
    View detailed user information, history, and activity

---

### [Overview](https://learn.social.plus/analytics-and-moderation/console/moderation/overview)

> Comprehensive guide to moderating content and managing community safety through the social.plus Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/XH9fVIktWP4?si=DCvSwM1SRixHYKk8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  **Key Benefit**: Unified AI \+ human moderation workflows to proactively detect, review, and resolve policy violations while preserving user trust and transparency.

Maintain a safe and healthy community with social.plus Console's comprehensive moderation stack. Combine automated detection, structured review queues, user reporting, and analytics-driven enforcement.

    Automated text / image / video analysis with confidence tuning
    Prioritized queues & human decisions (see AI \+ queue tuning)
    Warnings, suspensions, bans & restriction management
    Granular moderator capability & workflow permissions
  {/* Removed broken Moderation Analytics page: folding into overall analytics dashboard */}

    Raw metrics export for BI & policy tuning
    Thresholds, keyword lists, exception & escalation rules

## Key Capabilities

    - Low-latency AI screening for text, images, video frames
    - Configurable confidence thresholds (auto allow / queue / block)
    - Custom keyword & regex rule layers
    - Metadata & context-aware scoring (history, reputation)
    - Priority scoring (severity, virality, report density)
    - Workload distribution & claim / assign patterns
    - Batch operations for spam waves
    - Full audit log for every action
    - Category-based reports with optional free-form notes
    - Reporter credibility weighting & duplicate collapse
    - SLA timers & escalation triggers
    - Feedback loop to reporters (accepted / rejected)
    - Action ladder: warn → restrict → suspend → ban
    - Time-boxed penalties & automatic expiry
    - Appeal submission & secondary review layer
    - Consistent policy taxonomy & rationale capture
    - False positive / negative tracking & model tuning inputs
    - Moderator performance & queue aging metrics
    - Violation trend & emerging pattern surfacing
    - Policy effectiveness dashboards

## Moderation Approach

    1. Preventive (AI & rules)
    2. Reactive (user & system reports)
    3. Review (human adjudication)
    4. Appeal (fairness & transparency)
    - Proportionate actions matched to severity
    - Standardized decision templates
    - Calibration sessions & spot audits
    - Transparent communication & appeals

## Primary Workflows

    **Goal**: Minimize exposure to harmful content before broad distribution.

    1. Content submitted (post / comment / media / stream event)
    2. AI models \+ rule engine assign risk score
    3. Outcome branch: Allow | Queue | Block
    4. Metadata logged for analytics & tuning
    **Goal**: Consistent human decisions on queued or escalated items.

    1. Moderator claims item from priority queue
    2. Context & history surfaced (user, prior actions, report density)
    3. Decision applied with required rationale
    4. Enforcement \+ user notification (if applicable)
    **Goal**: Leverage community to surface edge cases & emerging abuse.

    1. User selects category & optional note
    2. Deduplication / credibility weighting
    3. Auto-triage (direct queue / auto action / hold)
    4. Resolution & optional reporter feedback
    **Goal**: Provide due process & policy legitimacy.

    1. User submits appeal referencing original action
    2. Secondary reviewer (segregated from original)
    3. Confirmation or reversal logged
    4. Insights looped into calibration

## System Architecture

```mermaid
graph TD
  A[Content Submission] --> B[AI & Rules Engine]
  B -->|Allow| C[Publish]
  B -->|Queue| D[Review Queue]
  B -->|Block| E[Flag/Delete]
  D --> F[Moderator Decision]
  E --> F
  F -->|Approve| C
  F -->|Enforce| G[Clear Flags/Delete]
  G --> H[User State & Restrictions]
  C --> K[Analytics]
  G --> K
```

## Getting Started

    Document violation categories & action ladder.

    Set confidence thresholds & custom rules.

    Ensure user report categories & flows are active.

    Assign moderator / supervisor permissions.

    Prioritize by severity & workload balance.

    Track false positives & SLA compliance.

## Best Practices

    - Calibrate models monthly with sampled decisions
    - Enforce rationale fields on irreversible actions
    - Rotate reviewers for sensitive categories
    - Monitor queue aging; set escalation SLAs
    - Run blind double-review audits
    - Track acceptance / reversal rates per moderator
    - Review appeal overturn patterns
    - Maintain balanced training datasets
    - Start conservative with auto-block thresholds
    - Whitelist benign edge cases iteratively
    - Version & test new rule sets before production
    - Log every automated action with explainability

## Integration Points

    Live events for content status, enforcement & appeals
    Programmatic moderation & bulk operations
    Raw data for external BI & policy tuning

  **Compliance**: Align enforcement with regional legal requirements (e.g., GDPR, DSA) & retain audit logs for mandated retention periods.

---

### [Moderation Roles & Privileges](https://learn.social.plus/analytics-and-moderation/console/moderation/roles-and-privileges)

> Comprehensive guide to user roles, moderation privileges, and administrative controls in social.plus Console for effective community management.

social.plus provides a comprehensive role-based moderation system that enables effective community management through hierarchical permissions, automated tools, and granular control over user interactions across your platform.

Moderation capabilities are determined by user roles, ranging from basic users to global administrators with full platform control.

## Role Hierarchy Overview

    Member, Moderator, and Super-Moderator roles with escalating privileges
    Global Admin and Super-Admin roles for platform administration
    Create custom roles with tailored permissions for specific needs
    Granular control over user actions and moderation capabilities

## User Roles

    ### Standard User Roles

        **Basic User Role:**
        - No moderation privileges
        - Standard content creation and interaction
        - Subject to all moderation rules
        - Can report inappropriate content

        **Capabilities:**
        - Create posts and comments
        - Join communities and channels
        - React to content
        - Send direct messages
        - Update profile information

        **Community Moderation Role:**
        - General moderation privileges
        - Can moderate assigned communities/channels
        - Subject to moderation from Super-Moderators and Admins
        - Enhanced reporting and review capabilities

        **Additional Capabilities:**
        - Delete inappropriate content
        - Mute and unmute users
        - Ban users from channels/communities
        - Review reported content
        - Pin and feature content

        **Enhanced Moderation Role:**
        - All community moderator privileges
        - Exempt from moderation by regular moderators
        - Cross-community moderation capabilities
        - Advanced moderation tools access

        **Enhanced Capabilities:**
        - Global content moderation
        - Cross-community user management
        - Advanced analytics access
        - Escalation handling
        - Policy enforcement

    ### Privilege Comparison

    | Capability | Member | Community Moderator | Global Moderator |
    |------------|---------|-----------|-----------------|
    | Create Content | ✅ | ✅ | ✅ |
    | Join Communities | ✅ | ✅ | ✅ |
    | Delete Others' Content | ❌ | ✅ | ✅ |
    | Mute/Unmute Users | ❌ | ✅ | ✅ |
    | Ban Users | ❌ | ✅ | ✅ |
    | Cross-Community Moderation | ❌ | ❌ | ✅ |
    | Exempt from Moderation | ❌ | ❌ | ✅ |
    | Advanced Analytics | ❌ | Limited | ✅ |

    ### Moderation Scope

        - Moderate across all communities
        - Access to global user management
        - Platform-wide policy enforcement
        - Cross-community analytics
        - Limited to specific communities
        - Community-specific user management
        - Local policy enforcement
        - Community analytics only

## Admin Roles

    ### Administrative Roles

        **Platform Administrator:**
        - Full moderation privileges across platform
        - User role assignment capabilities
        - Exempt from all moderation actions
        - System configuration access

        **Exclusive Capabilities:**
        - Assign roles to other users
        - Create and manage admin accounts
        - Configure platform-wide settings
        - Access to all analytics and reports
        - Global ban/unban capabilities

        Global Admin role is reserved for administrators only and cannot be assigned to regular users.

        **System Administrator:**
        - Highest level of access
        - Reserved for critical system operations
        - Cannot generate Admin API tokens
        - Used for system-level configurations

        **System Operations:**
        - Push notification certificate management
        - Core system configuration
        - Infrastructure-level settings
        - Emergency system access

        Super-Admin access is automatically granted when accessing console from the social.plus Portal. Create separate admin accounts for regular administrative tasks.

    ### Creating Admin Accounts

        Navigate to Console → **Admin Users** → **Manage Admin Users**
        Click **Create New Admin** and provide credentials
        Configure role permissions and access levels
        Test admin account functionality and access

    ### Admin Best Practices

        **Security Measures:**
        - Use strong, unique passwords
        - Enable two-factor authentication
        - Regular password rotation
        - Monitor admin activity logs
        - Limit admin account creation

        **Access Control:**
        - Principle of least privilege
        - Regular access reviews
        - Separate accounts for different purposes
        - Audit trail maintenance

        **API Token Usage:**
        - Use dedicated admin accounts for API access
        - Never use Super-Admin for API token generation
        - Implement token rotation policies
        - Revoke tokens immediately if compromised

## Role Management

    ### User Role Assignment

        Go to **Community** → **Communities** and select target community
        Click the **Manage Members** tab to view community members
        Choose the user whose role you want to change
        Click **Change user role** button and select new role
        Review selection and click **Confirm** to apply changes

    ### Role Change Considerations

        **Member to Moderator:**
        - Verify user's community engagement
        - Assess understanding of community guidelines
        - Consider user's history and behavior
        - Provide moderation training and resources

        **Moderator to Super-Moderator:**
        - Evaluate moderation performance
        - Assess cross-community needs
        - Verify advanced understanding of policies
        - Consider platform-wide responsibilities

        **Role Reduction:**
        - Document reasons for demotion
        - Communicate changes to affected user
        - Review moderation history
        - Implement gradual privilege reduction
        - Monitor post-demotion behavior

        Communities must maintain at least one moderator. The last remaining moderator cannot be demoted to member status.

    ### Creating Custom Roles

        Navigate to **Users** → **Roles** in the console
        Click **Create a new role** button
        Provide role name and select custom permissions
        Review settings and click **Create** to finalize

    ### Permission Categories

        **Content Permissions:**
        - Create, edit, delete posts
        - Moderate comments and replies
        - Pin and feature content
        - Manage content categories
        - Handle reported content

```json
{
  "contentPermissions": {
    "createPost": true,
    "editPost": true,
    "deletePost": true,
    "moderateComments": true,
    "pinContent": true,
    "featureContent": false
  }
}
```

        **User Permissions:**
        - View user profiles and activity
        - Mute and unmute users
        - Ban and unban users
        - Assign community roles
        - Access user social history

```json
{
  "userPermissions": {
    "viewUserProfiles": true,
    "muteUsers": true,
    "banUsers": true,
    "assignRoles": false,
    "accessUserHistory": true
  }
}
```

        **Community Permissions:**
        - Create and edit communities
        - Manage community settings
        - Control community membership
        - Configure community categories
        - Access community analytics

```json
{
  "communityPermissions": {
    "createCommunity": false,
    "editCommunity": true,
    "manageMembership": true,
    "configureCategories": true,
    "accessAnalytics": true
  }
}
```

## Moderation Tools

    ### Automated Moderation

        Reject content that contains words or phrases you don't want in your community.

        **How rules match:**
        - Each rule is a word or phrase, matched case-insensitively.
        - Rules match as plain text. Characters such as `*` or `.` are literal, not patterns.
        - **Partial match** (default): the rule matches anywhere in the text, including inside longer words.
        - **Exact word match** (`isMatchExactWord: true`): the rule matches only as a whole word.
        - Each rule can be enabled or disabled without deleting it.

        **Rule categories:**
        - `content` (default): checked against chat messages, posts, comments, and polls. For posts, the title is checked too.
        - `user`: checked against user display names and descriptions.

        **On violation:**
        - The request is rejected with error `400308` (HTTP 403).
        - For chat messages, the sender can also be muted in the channel when a blocklist mute duration is configured. The duration is one network-wide value, not set per rule.

        **Exemptions:** by default, users with the `global-admin` or `super-moderator` role skip the check for chat messages. Posts and comments are always checked.

        Manage rules with the blocklist API. Test text against your rules with `POST /api/v3/blocklists/verify`:

```json
POST /api/v3/blocklists
{
  "regexs": ["inappropriate word", "spam phrase"],
  "isMatchExactWord": false,
  "category": "content"
}
```

        Keep links in your community limited to sources you trust. When link moderation is on, any link that doesn't match a rule on your allowlist is rejected.

        **Enable or disable:**
        - Link moderation is **on by default**. With an empty allowlist, every link is blocked.
        - Toggle it with the network moderation setting `isWhitelistEnabled`. When off, all links are allowed.

        **How rules match:**
        - Each rule is plain text, matched case-insensitively against every link found in the content.
        - A link is allowed if it **contains** the text of any enabled rule.
        - Wildcards and patterns aren't supported. `*.example.com` matches only the literal text `*.example.com`. To allow a domain and its subdomains, add `example.com`.
        - Protocols get no special treatment. `https://example.com` allows only links containing that exact text, so `http://example.com` is still blocked.
        - Because matching is by substring, a rule can also match text in another link's path or query string. For example, `example.com` allows `https://other.site/?ref=example.com`. Use a more specific rule, such as `https://example.com/`, to reduce this.
        - Each rule can be enabled or disabled without deleting it.

        **Checked content:** chat messages, posts, comments, and polls.

        **On violation:**
        - The request is rejected with error `400309` (HTTP 403).
        - For chat messages, the sender can also be muted in the channel when an allowlist mute duration is configured. The duration is one network-wide value, not set per rule.

        **Exemptions:** by default, users with the `global-admin` or `super-moderator` role skip the check for chat messages. Posts and comments are always checked.

        Manage rules with the allowlist API. Test links against your rules with `POST /api/v3/allowlists/verify`:

```json
POST /api/v3/allowlists
{
  "regexs": ["https://example.com/", "trusted-site.org"]
}
```

    ### User Moderation

        **Platform-Wide Actions:**
        - Remove user from entire platform
        - Disconnect from all channels and communities
        - Delete all chat messages
        - Preserve social content (posts, comments)
        - Prevent re-authentication until unbanned

        **Global Ban Process:**
        1. Navigate to **Users** in console
        2. Select target user
        3. Click ban user icon in **Actions**
        4. Confirm action in popup

        Global ban takes up to 30 seconds to disconnect users. Ban does not emit channel events or update Live Collections.

        **Global Unban Process:**
        1. Go to **Users** in console
        2. Select banned user
        3. Click unban user icon in **Actions**
        4. Confirm unban action

        **Channel-Specific Moderation:**
        - Ban users from specific channels only
        - Soft delete channel messages
        - Real-time ban notifications
        - Immediate LiveCollection updates

        **Channel Ban Process:**
        1. Navigate to **Channels** in console
        2. Select target channel
        3. Click **Members** button
        4. Select user to ban
        5. Click ban icon and confirm

        **Channel Unban Process:**
        1. Go to **Channels** in console
        2. Select relevant channel
        3. Access **Members** section
        4. Select banned user
        5. Click unban icon and confirm

        **Temporary Restrictions:**
        - Prevent message sending
        - Allow message observation
        - Channel-level application
        - Indefinite duration until unmuted

        **Mute Capabilities:**
        - Available to moderators and above
        - Immediate effect implementation
        - Real-time status updates
        - Manual unmute required

## Platform Integration

    ### UI Framework Integration

        **Full Moderation Support:**
        - Network-level moderation
        - Community-level moderation
        - Enhanced moderator menus
        - Real-time permission updates
        **Community-Level Support:**
        - Community moderation only
        - Basic moderator interface
        - Limited cross-community features
        - Standard web interactions


    ### Moderation APIs

        **Role Assignment Endpoints:**
        - `POST /api/v4/communities/{communityId}/users/roles` - Assign community role
        - `PUT /api/v3/users/{userId}/roles` - Update user role
        - `GET /api/v3/users/{userId}/roles` - Get user roles
        - `DELETE /api/v4/communities/{communityId}/users/{userId}/roles` - Remove role

        **Example Role Assignment:**
```bash
curl -X POST "https://api.amity.co/api/v4/communities/123/users/roles" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user456",
    "role": "community-moderator"
  }'
```

        **User Moderation Endpoints:**
        - `POST /api/v3/users/{userId}/ban` - Ban user globally or from channel
        - `DELETE /api/v3/users/{userId}/ban` - Unban user
        - `POST /api/v3/users/{userId}/mute` - Mute user in channel
        - `DELETE /api/v3/users/{userId}/mute` - Unmute user

        **Content Moderation Endpoints:**
        - `DELETE /api/v3/posts/{postId}` - Delete post
        - `DELETE /api/v3/comments/{commentId}` - Delete comment
        - `POST /api/v3/posts/{postId}/flag` - Flag content for review
        - `POST /api/v3/posts/{postId}/approve` - Approve flagged content

## Best Practices

    **Effective Role Management:**
    - **Gradual Progression**: Promote users through role hierarchy gradually
    - **Performance-Based**: Base promotions on demonstrated moderation skills
    - **Community Fit**: Consider user's understanding of community culture
    - **Training**: Provide moderation training before role assignment
    - **Regular Review**: Periodically assess role effectiveness

    **Selection Criteria:**
    - Active community participation
    - Positive user interactions
    - Understanding of platform guidelines
    - Demonstrated leadership qualities
    - Availability for moderation duties

    **Uniform Policy Enforcement:**
    - **Clear Guidelines**: Establish comprehensive moderation guidelines
    - **Decision Documentation**: Record moderation actions and reasoning
    - **Team Communication**: Coordinate between moderators
    - **Policy Updates**: Keep moderation policies current
    - **Training Programs**: Regular moderator training sessions

    **Escalation Procedures:**
    - Define clear escalation paths
    - Set response time expectations
    - Establish appeal processes
    - Document complex decisions
    - Review controversial actions

    **Transparent Moderation:**
    - **Clear Communication**: Explain moderation actions to users
    - **Fair Application**: Apply rules consistently across all users
    - **Appeal Process**: Provide mechanisms for users to appeal decisions
    - **Feedback Collection**: Gather community feedback on moderation
    - **Policy Transparency**: Make community guidelines easily accessible

    **Trust Indicators:**
    - Consistent rule enforcement
    - Responsive to community concerns
    - Clear communication about policy changes
    - Fair handling of disputes
    - Regular community engagement

## Troubleshooting

    **Role Assignment Problems:**
    - **Permission Errors**: Verify admin privileges for role changes
    - **Role Conflicts**: Check for conflicting role assignments
    - **Community Minimums**: Ensure communities maintain minimum moderator count
    - **API Failures**: Verify token permissions and API endpoint access

    **Solutions:**
    - Use Global Admin accounts for role management
    - Resolve role conflicts before new assignments
    - Promote additional moderators before demoting existing ones
    - Check API token scopes and expiration

    **Common Problems:**
    - **Ban Not Effective**: Check user connection status and ban scope
    - **Content Still Visible**: Verify soft deletion vs. hard deletion
    - **Permission Denied**: Confirm moderator privileges and scope
    - **API Timeouts**: Retry operations and check system status

    **Troubleshooting Steps:**
    1. Verify user role and permissions
    2. Check action scope (global vs. channel)
    3. Confirm API token validity
    4. Review system logs for errors
    5. Contact support for persistent issues

---

Effective moderation requires balancing automated tools with human judgment. Regular training and clear guidelines ensure consistent, fair community management.

---

### [Edit User Content with Change History](https://learn.social.plus/analytics-and-moderation/console/moderation/edit-content-history)

> Modify user-generated content with full transparency and accountability through comprehensive edit tracking and change history management

Empower your moderation team to maintain content quality and compliance by enabling direct editing of user-generated posts and comments through the Console. All modifications are tracked in a comprehensive change history, ensuring transparency, accountability, and audit compliance.

**Key Benefit**: Moderators can correct content violations and enforce community standards without deleting entire posts, while maintaining full transparency through automated change tracking.

    Modify text, media, and metadata for posts and comments
    Track all edits with timestamps, actors, and reasons
    Control who can edit content with role-based access
    Full audit trail for regulatory and policy enforcement
    Remove sensitive information while preserving content
    Users see edit indicators and moderators see full history

## Overview

The Edit User Content feature enables authorized moderators to:

1. **Modify Content**: Edit text, media, and metadata for user posts and comments
2. **Add Context**: Optionally include reasons for edits to improve transparency
3. **Track Changes**: Automatically maintain a comprehensive change history
4. **Enforce Standards**: Remove violations while preserving valuable content
5. **Maintain Compliance**: Ensure all modifications meet community guidelines

## Key Capabilities

    **Post Editing:**
    - **Text Posts**: Edit title and content
    - **Image Posts**: Edit title, content, add/remove/reorder images, modify alt text
    - **Video Posts**: Edit title, content, add/remove/reorder videos, modify alt text
    - **File Posts**: Edit title, content, add/remove/reorder files, modify alt text
    - **Clip Posts**: Edit caption only

    **Comment Editing:**
    - Edit text content
    - Support for both comments and replies
    - Preserve threading and context

    **Restrictions:**
    - ❌ Cannot edit poll posts
    - ❌ Cannot edit stories
    - ❌ Cannot edit livestream posts
    - ❌ Cannot edit scheduled posts
    - ❌ Cannot edit deleted posts

    **What's Tracked:**
    - Original version with creator details
    - All edited versions with modifications
    - Edit timestamps and dates
    - Editor identity (moderator/admin)
    - Optional edit reasons
    - Media additions and removals
    - Deleted child posts

    **History Display:**
    - Latest to oldest chronological order
    - Up to 10 most recent edit versions
    - Original version always visible
    - Clear visual indicators for changes
    - Media deletion status (when feasible)

    **New Permission: "Edit posts and comments"**
    - Separate from "Manage posts and comments"
    - Available to Admin role by default
    - Granular control over editing capabilities

    **Access Requirements:**
    - Must have explicit edit permissions
    - Available in Console/Portal only
    - Subject to role hierarchy
    - Audit logged for all actions

    **Content Validation:**
    - Block word detection during editing
    - Character limit enforcement
    - Media format validation
    - Metadata structure checks

    **Error States:**
    - Block word violation alerts
    - API connection failures
    - Network connectivity issues
    - Concurrent edit conflicts

## Getting Started

    Ensure your admin account has the "Edit posts and comments" permission. Navigate to **Admin users** → **Roles & permissions** to verify role permissions.

    Find the content you want to edit through:
    - **Posts & Comments** page
    - **User History** page

    Click the **⋮** → **Edit** button on the content you want to modify. The edit interface will display based on content type.

    Edit the content according to your moderation needs:
    - Update text content
    - Add, remove, or reorder media
    - Modify alt text for accessibility
    - Adjust metadata as needed

    Provide a clear reason for the edit to improve transparency and maintain audit compliance. This appears in the change history.

    Review your modifications and click **Save**. The system will validate content and update both the Console and user-facing views.

    Confirm that:
    - Content displays correctly
    - "View change history" indicator appears
    - Change history is updated
    - Edit appears in moderation activity report

## Permission Management

### Setting Up Edit Permissions

    ### Admin Role Permissions

    The "Edit posts and comments" permission is automatically available to the **Admin** role and can be viewed in the Admin Roles section.

    **To View Permissions:**

        Go to **Settings** → **Admin Roles** in the Console
        Click on the **Admin** role to view details
        Locate "Edit posts and comments" in the permissions list

    The "Edit posts and comments" permission is distinct from "Manage posts and comments" and provides specific editing capabilities without full content management access.

    ### Permission Assignment Guidelines

        **Separation of Duties:**
        - Create distinct roles for different moderation tasks
        - Separate editing from deletion and banning powers
        - Use "Edit posts and comments" for content refinement
        - Use "Manage posts and comments" for full content lifecycle

        **Principle of Least Privilege:**
        - Grant only necessary permissions for each role
        - Review permissions regularly
        - Audit role usage patterns
        - Remove unused or excessive permissions

        **Recommended Role Hierarchy:**

        1. **Content Editors**: Edit permissions only
        2. **Community Moderators**: Edit + basic moderation
        3. **Senior Moderators**: Edit + full moderation
        4. **Administrators**: All permissions

        **Scaling Considerations:**
        - Small teams: Fewer, broader roles
        - Large teams: More specialized roles
        - Global teams: Regional role assignments
        - Contractor teams: Limited permission sets

        **Audit Requirements:**
        - Log all permission changes
        - Review edit actions monthly
        - Track editor performance metrics
        - Maintain permission documentation

        **Regulatory Considerations:**
        - Document edit reason requirements
        - Establish edit approval workflows
        - Define retention policies for change history
        - Ensure GDPR/CCPA compliance

## Editing Content

### Post Editing Workflows

    ### Editing Text Posts

    Text posts support comprehensive editing of title and content fields.

    **Available Edits:**
    - Title modification
    - Content text updates
    - Metadata adjustments

    **Edit Process:**

        Click **Edit** on the text post you want to modify
        Update the title and/or content fields as needed
        Optionally add an edit reason (e.g., "Removed profanity", "Corrected misinformation")
        System automatically checks for block words and policy violations
        Click **Save** to publish the edited content

    **Example Use Cases:**

        Remove profanity or offensive language while preserving the post's intent and value
        Fix factual errors, correct misinformation, or update outdated information
        Remove personal information, contact details, or sensitive data
        Modify content to meet legal requirements or community guidelines

    ### Editing Image, Video & File Posts

    Media posts support extensive editing including content, media management, and accessibility features.

    **Available Edits:**
    - Title and content text
    - Add new media files
    - Remove existing media
    - Reorder media items
    - Update alt text for accessibility

    **Media Management:**

        Click **Edit** on any image, video, or file post
        Modify title and description as needed
        - **Add**: Upload new images, videos, or files
        - **Remove**: Delete inappropriate or unwanted media
        - **Reorder**: Drag and drop to change media sequence
        Edit alt text descriptions for screen readers and accessibility compliance
        Document why media was modified (e.g., "Removed copyrighted image", "Added accessibility text")
        Review all modifications and save to publish updates

    **Media Deletion**: When removing media files, the change history will show a preview as deleted media. But won't preserve the actual media file itself.

    **Example Scenarios:**

        **Situation**: User uploaded copyrighted images without permission

        **Action**:
        - Remove copyrighted images
        - Keep other original media
        - Add edit reason: "Removed copyrighted content"
        - Preserve post for community visibility

        **Situation**: Post contains mix of appropriate and inappropriate images

        **Action**:
        - Remove offensive images only
        - Maintain appropriate content
        - Update post description if needed
        - Document removal reason

        **Situation**: Media lacks proper alt text descriptions

        **Action**:
        - Add descriptive alt text for all media
        - Improve accessibility compliance
        - Enhance user experience for screen readers
        - Note: "Added accessibility descriptions"

    ### Editing Clip Posts

    Clip posts have limited editing capabilities focused on captions.

    **Clip Posts:**
    - Edit caption text only
    - Cannot modify video content
    - Can add edit reasons

    **Edit Process:**

        Navigate to the clip post
        Open the simplified editor for caption modification
        Modify the caption (clips)
        Provide edit reason for transparency
        Publish the updated caption

    **Design Rationale**: Clip posts have limited editing to preserve the integrity of time-sensitive or real-time content. Only metadata can be modified.

### Comment Editing

    ### Editing Comments and Replies

    Comments and replies support text-only editing to maintain threading integrity.

    **Available Edits:**
    - Text content modification
    - Support for comments and replies
    - Preserve threading context

    **Edit Steps:**

        Find the comment in:
        - Posts & Comments page
        - User History page
        - Moderation Feed
        Click **Edit** on the comment or reply
        Update the comment text as needed
        Document why the comment was edited
        System checks for block words and violations
        Publish the edited comment

    ### Comment Editing Guidelines

        **Edit Comments When:**
        - Minor policy violations (profanity, spam elements)
        - Valuable discussion with problematic elements
        - Educational opportunity (show corrected version)
        - Context preservation is important

        **Delete Comments When:**
        - Severe policy violations (harassment, threats)
        - Entirely inappropriate content
        - Spam or bot-generated content
        - Legal removal requirements

        **Threading Integrity:**
        - Preserve conversation flow
        - Don't alter meaning drastically
        - Consider reply context
        - Maintain chronological sense

        **Communication:**
        - Use clear edit reasons
        - Be transparent about changes
        - Document policy violations
        - Provide user guidance when possible

        **Editorial Principles:**
        - Minimal necessary changes
        - Preserve user voice when possible
        - Fix violations without rewriting
        - Maintain factual accuracy

        **Consistency:**
        - Apply same standards across all comments
        - Use standardized edit reasons
        - Follow escalation procedures
        - Document decision rationale

## Change History

### Understanding Change History

    ### Viewing Change History

    Every edited post or comment maintains a comprehensive change history accessible to moderators.

    **Access Points:**

        View history from main content pages
        Access from user profile sections
        Historical data in moderation reports

    **History Contents:**

        - Complete original content
        - Creator name and details
        - Creation date and timestamp
        - Original media attachments

        - Updated text content
        - Media additions/removals
        - Edit date and timestamp
        - Editor (moderator/admin) identity
        - Edit reason (if provided)

        - Latest edit at top
        - Up to 10 recent edits shown
        - Original version always visible
        - Clear version numbering

    **History Limit**: The system displays the 10 most recent edit versions plus the original post. If content has been edited more than 10 times, only the latest 10 edits are shown.

    ### What's Tracked in History

        **Complete Original Content:**
        - Full text content (title, body, captions)
        - All original media attachments
        - Creator user information
        - Creation timestamp (date and time)
        - Original metadata and tags
        - Initial engagement metrics

        **Preservation:**
        - Always retained in history
        - Never overwritten or deleted
        - Serves as baseline for comparison
        - Maintains attribution integrity

        **For Each Edit:**
        - **Text Changes**: Updated title, content, captions
        - **Media Changes**: Added/removed/reordered files
        - **Timestamp**: Exact date and time of edit
        - **Editor Identity**: Moderator/admin who made changes
        - **Edit Reason**: Optional explanation (if provided)
        - **Deleted Child Posts**: References to removed nested content

        **Version Information:**
        - Sequential version numbering
        - Clear change indicators
        - Before/after comparisons
        - Visual diff highlighting (when applicable)

        **Concurrent Edits:**
        - All versions preserved if multiple moderators edit simultaneously
        - Latest saved version displays to users
        - All versions visible in history
        - Timestamp determines display order

        **Deleted Content:**
        - Change history removed when post is deleted
        - Edits not preserved after deletion
        - Consider archiving before deletion if needed

        **Media Deletion:**
        - System attempts to show deleted media preview
        - Fallback to deletion indicator if preview unavailable
        - Media filename and type preserved
        - Reason for removal documented

    ### Practical Applications

        **Regulatory Requirements:**
        - Complete edit trail for legal compliance
        - Timestamped moderator actions
        - Documented reasons for changes
        - Exportable for legal discovery

        **Internal Audits:**
        - Review moderator decision quality
        - Identify patterns in policy enforcement
        - Assess edit necessity and appropriateness
        - Train new moderators with examples

        **Moderator Performance:**
        - Review editing consistency
        - Assess reason quality
        - Identify training needs
        - Recognize excellence

        **Policy Effectiveness:**
        - Track common violations
        - Identify emerging issues
        - Refine moderation guidelines
        - Measure edit impact

        **Transparency:**
        - Show users what changed
        - Explain policy enforcement
        - Build trust through visibility
        - Demonstrate fairness

        **Education:**
        - Help users understand violations
        - Provide improvement guidance
        - Show correct alternatives
        - Encourage compliance

## Validation & Error Handling

### Content Validation

    ### Block Word Detection

    The system automatically validates edited content against your configured block word list before saving.

    **How It Works:**

        System scans edited content for configured block words
        Clear error message indicates which words triggered the block
        Moderator modifies content to remove or replace blocked terms
        System re-checks content upon next save attempt
        Content saves once all validation checks pass

    **Important**: Block word validation applies to edited content even though moderators are editing. This ensures policy consistency and prevents accidental policy violations.

    ### API & Connectivity Issues

        **Error Scenarios:**
        - Server timeout during save operation
        - API endpoint unavailable
        - Authentication token expired
        - Rate limiting exceeded

        **User Experience:**
        - Clear error message displayed
        - Edit content preserved in editor
        - Retry option provided
        - Unsaved changes warning

        **Resolution Steps:**
        1. Check internet connectivity
        2. Refresh authentication if needed
        3. Retry save operation
        4. Contact support if persistent

        **Connection Issues:**
        - Internet connection lost
        - Network timeout
        - DNS resolution failures
        - Firewall blocking

        **Handling:**
        - Detect connection status
        - Display connectivity warning
        - Queue changes locally (if possible)
        - Auto-retry when connection restored
        - Prevent data loss

        **Conflict Scenarios:**
        - Multiple moderators editing same content
        - Content changed by another moderator during edit
        - Version mismatch on save

        **Resolution:**
        - All versions preserved in history
        - Latest save operation wins
        - Both edits visible in change history
        - Conflict notification to moderators
        - Option to review other changes

        **Content Issues:**
        - Character limit exceeded
        - Invalid media format
        - Corrupted file upload
        - Metadata structure errors

        **Error Messages:**
        - Specific validation failure reason
        - Character count if limit exceeded
        - Supported formats for media
        - Suggestions for correction
        - Links to help documentation

    ### Error Prevention Strategies

        **Before Saving Edits:**
        - Review content for block words manually
        - Check character limits
        - Verify media file formats
        - Ensure edit reason is clear
        - Preview changes if possible

        **Workflow Tips:**
        - Save frequently for long edits
        - Use draft mode if available
        - Keep original in separate window for reference
        - Document complex changes incrementally

        **Stable Environment:**
        - Use reliable internet connection
        - Avoid public Wi-Fi for important edits
        - Keep session active during edits
        - Monitor connection status

        **Backup Strategies:**
        - Copy content before major edits
        - Save complex edits in external document first
        - Screenshot original for reference
        - Note key changes in separate log

        **Prevent Conflicts:**
        - Communicate with team about active edits
        - Use assignment systems to claim content
        - Check if others are editing same content
        - Coordinate on complex multi-moderator cases

        **Conflict Resolution:**
        - Review both versions in history
        - Discuss with other moderator if needed
        - Make additional edit if necessary
        - Document coordination in edit reasons

## Use Cases

    **Scenario**: User posts valuable information with minor profanity

    **Solution**:
    - Edit to remove offensive language
    - Preserve valuable content and discussion
    - Add reason: "Removed inappropriate language"
    - Maintain community value while enforcing standards

    **Scenario**: User accidentally shares personal contact information

    **Solution**:
    - Remove phone numbers and email addresses
    - Keep rest of post intact
    - Add reason: "Removed personal information for privacy"
    - Protect user while preserving content

    **Scenario**: Post contains factually incorrect information

    **Solution**:
    - Correct false statements
    - Add source references if appropriate
    - Add reason: "Corrected factual inaccuracies"
    - Consider adding moderator note to original

    **Scenario**: Post includes copyrighted images without permission

    **Solution**:
    - Remove copyrighted media only
    - Maintain user's text content
    - Add reason: "Removed copyrighted images"
    - Preserve post value while ensuring compliance

    **Scenario**: Legitimate post with embedded spam links

    **Solution**:
    - Remove spam URLs and promotional content
    - Keep relevant discussion points
    - Add reason: "Removed spam links"
    - Maintain conversation flow

    **Scenario**: Media posts lacking proper alt text

    **Solution**:
    - Add descriptive alt text to all media
    - Improve accessibility compliance
    - Add reason: "Added accessibility descriptions"
    - Enhance user experience for all users

    **Scenario**: Content requires modification for regulatory compliance

    **Solution**:
    - Edit to meet legal requirements
    - Document compliance reason clearly
    - Add reason: "Modified for legal compliance"
    - Maintain audit trail for records

    **Scenario**: Content violates specific community guidelines

    **Solution**:
    - Edit to align with community standards
    - Preserve user intent where possible
    - Add reason: "Edited for policy compliance"
    - Use as educational opportunity

## Best Practices

    **When to Edit:**
    - Content has value but contains violations
    - Minor policy infractions
    - Fixable privacy issues
    - Misinformation that can be corrected
    - Accessibility improvements needed
    - First-time violations by good-faith users

    **When to Delete:**
    - Severe policy violations (harassment, threats)
    - Entirely inappropriate content
    - Spam or bot-generated posts
    - Repeated violations after warnings
    - Legal removal requirements
    - Content with no salvageable value

    **Decision Matrix:**

    | Severity | Value | History | Action |
    |----------|-------|---------|--------|
    | Minor | High | First | ✅ Edit |
    | Minor | Low | First | ⚠️ Edit or Warn |
    | Moderate | High | First | ✅ Edit + Warn |
    | Moderate | Low | Repeat | ❌ Delete |
    | Severe | Any | Any | ❌ Delete + Ban |

    **Clear and Specific:**
    - "Removed profanity (specific words)"
    - "Corrected factual error about X"
    - "Removed personal contact information"
    - "Deleted copyrighted image"

    **Avoid Vague Reasons:**
    - ❌ "Policy violation"
    - ❌ "Inappropriate"
    - ❌ "Fixed"
    - ❌ "Updated"

    **Professional Language:**
    - Neutral and objective tone
    - Focus on policy, not judgment
    - Provide context when helpful
    - Use standard terminology

    **Reason Templates:**
```
Privacy: "Removed personal information (phone/email)"
Profanity: "Removed offensive language"
Misinformation: "Corrected factual inaccuracy about [topic]"
Copyright: "Removed copyrighted content"
Spam: "Removed promotional links/spam"
Accessibility: "Added alt text for accessibility"
Legal: "Modified for legal compliance with [law/regulation]"
```

    **Transparency Principles:**
    - Always show edit indicators
    - Provide clear edit reasons
    - Make history accessible
    - Be consistent in enforcement

    **Communication:**
    - Consider notifying users of significant edits
    - Explain policy rationale when appropriate
    - Offer guidance for future compliance
    - Be responsive to questions about edits

    **Fairness:**
    - Apply same standards to all users
    - Document decision rationale
    - Allow for context and intent
    - Provide path to compliance

    **Optimization Strategies:**
    - Use templates for common edit scenarios
    - Develop standardized edit reasons
    - Create team style guide
    - Share best edit examples
    - Automate where appropriate

    **Time Management:**
    - Prioritize high-impact content
    - Batch similar edits when possible
    - Set time limits for complex decisions
    - Escalate edge cases
    - Focus on prevention through education

    **Team Coordination:**
    - Regular calibration sessions
    - Shared edit reason library
    - Peer review for complex cases
    - Clear escalation procedures
    - Knowledge sharing culture

    **Self-Review Checklist:**
    - [ ] Edit preserves user intent where possible
    - [ ] All policy violations addressed
    - [ ] Edit reason is clear and specific
    - [ ] No introduction of new errors
    - [ ] Accessibility maintained or improved
    - [ ] Change history will make sense to reviewers

    **Peer Review Indicators:**
    - Highly visible content
    - Complex policy questions
    - Significant content changes
    - Sensitive topics
    - Legal implications
    - Unusual circumstances

    **Continuous Improvement:**
    - Review edit outcomes
    - Track user responses
    - Analyze effectiveness metrics
    - Update guidelines based on learnings
    - Share successes and challenges

## Troubleshooting

    **Possible Causes:**
    - Insufficient permissions
    - Content type not editable (polls, stories, scheduled posts)
    - Content has been deleted
    - Browser cache issues

    **Solutions:**
    1. Verify you have "Edit posts and comments" permission
    2. Check Admin Roles section for your permissions
    3. Confirm content type supports editing
    4. Clear browser cache and reload
    5. Contact administrator to verify role assignment

    **Cause**: Content contains words from the block word list

    **Solutions:**
    1. Review error message for specific blocked words
    2. Remove or replace blocked terms
    3. Rephrase content to avoid triggers
    4. Verify block word list is current and appropriate
    5. Contact administrator if block word seems incorrect

    **Possible Causes:**
    - Cache delay
    - Save operation failed
    - Browser synchronization issue
    - CDN propagation delay

    **Solutions:**
    1. Refresh the page
    2. Check if edit appears in change history
    3. Verify save confirmation was received
    4. Clear browser cache
    5. Wait 1-2 minutes for propagation
    6. Try from incognito/private browser window
    7. Contact support if persistent

    **Situation**: Another moderator edited the same content

    **What Happens:**
    - Both edits preserved in history
    - Latest save wins for display
    - Both moderators notified

    **Resolution:**
    1. Review both versions in change history
    2. Communicate with other moderator
    3. Make additional edit if needed to reconcile
    4. Document coordination in edit reason

    **Possible Causes:**
    - Content was deleted (history not retained)
    - More than 10 edits (only latest 10 shown)
    - System error during history recording

    **Solutions:**
    1. Verify content hasn't been deleted
    2. Check that you're viewing the correct content
    3. Remember only 10 most recent edits are shown
    4. Review moderation activity report for full log
    5. Contact support if history appears corrupted

    **Possible Causes:**
    - File size too large
    - Unsupported file format
    - Network connectivity issue
    - Storage quota exceeded

    **Solutions:**
    1. Check file size and compress if needed
    2. Verify file format is supported
    3. Test internet connection
    4. Try uploading one file at a time
    5. Convert files to supported formats
    6. Contact administrator about storage quota

    **Error Messages:**
    - "Failed to save changes"
    - "Connection timeout"
    - "Network error"

    **Solutions:**
    1. Check internet connectivity
    2. Refresh authentication session
    3. Copy edited content to clipboard as backup
    4. Try saving again
    5. If persistent, save content externally and contact support
    6. Report error with timestamp and content ID

## Related Topics

    Comprehensive moderation workflows and strategies
    Understanding permissions and role management
    Real-time content moderation for live streams
    Automated content detection and filtering

---

### [Livestream Moderation](https://learn.social.plus/analytics-and-moderation/console/moderation/livestream-moderation)

> Enabling safe and engaging live-streaming experiences.

Real-time automated analysis of live video frames & audio to surface or auto-enforce against policy violations with minimal latency. Use this guide to enable, configure thresholds, act on incidents, and continuously tune signal quality.

## Enable the Feature


## How Detection Works

The system continuously samples frames (and audio signals where applicable) and classifies content into risk categories. Each detection produces category confidence scores (0–100%). Your configured thresholds decide whether a stream:

| Outcome | Trigger | System Action | User Experience |
|---------|---------|---------------|-----------------|
| Pass | All confidences below Flagged thresholds | Continues | Normal playback |
| Flagged | Any category ≥ Flagged threshold but < Terminated | Marked for review (no auto-stop) | Appears normal to viewers |
| Terminated | Any category ≥ Terminated threshold | Broadcast stopped; post soft‑deleted | Appears as normally ended |

## Detection Categories


## Configuring Confidence Thresholds


## Tuning Playbook


## Acting on Incidents


## Key Metrics

| Metric | Definition | Target / Signal | Action Trigger |
|--------|-----------|-----------------|----------------|
| Flag Volume per Hour | Flagged streams / hour | Baseline after Week 1 | Sustained spike → investigate attack/content trend |
| False Positive Rate (Flagged) | (Flags cleared as OK) / Flags reviewed | < 30% | Higher → raise Flagged threshold |
| Termination Precision | Valid terminations / Total terminations | > 95% | Drop → raise Terminated threshold & audit samples |
| Miss Incidents | Confirmed violations not flagged/terminated | 0 critical misses | Any miss → lower relevant thresholds or escalate model gap |
| Avg Review Time | Time from flag to moderator decision | Within SLA (e.g., < 5 min) | Rising trend → staffing or threshold adjustment |
| Category Distribution | % flags by category | Stable pattern | Sudden skew → targeted abuse or threshold imbalance |

## Best Practices


## Troubleshooting

| Issue | Likely Cause | Resolution |
|-------|--------------|------------|
| Overloaded Flag Queue | Flagged threshold too low / spike event | Raise threshold 5% or add temporary staffing; isolate noisy category |
| Repeated False Terminations | Terminated threshold aggressive or misclassified scenes | Increase threshold; review sample frames; report to support |
| Missed Severe Violation | Threshold too high or model blind spot | Lower thresholds; capture evidence & escalate for model improvement |
| Cost Surge | Increased broadcast minutes + high flag rate | Audit usage, enforce creator guidelines, optimize thresholds |
| Inconsistent Moderator Decisions | Lack of unified rubric | Establish decision matrix & training refresh |
| Slow Review Times | Understaffing or UI overload | Add shift coverage; refine filters; raise thresholds temporarily |


## Next Steps

---

### [Channel Management](https://learn.social.plus/analytics-and-moderation/console/chat-management/channel-management)

> Guide for moderators and administrators to search, create, configure, moderate, and analyze chat channels in the Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/24XZQHgHZPk?si=-R1n9H5Zq8u8xr-G" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  This page explains how Console moderators and administrators manage channels: discovery, creation, configuration, member governance, lifecycle actions, and activity analytics. Focus: operational workflows (not developer integration).

    Search & filter active, muted, stopped, deleted channels

    Launch Community, Live, or Broadcast channels

    Privacy & notification modes

    Mute, stop, delete, ban, unban members

    Review flagged messages & user chat activity

    Apply governance & engagement best practices

## Access & Filtering

    Go to Chat Management → Channels.

    Use search \+ filter controls at top.

    Identify state (muted, stopped, deleted) via status icons.

    Open target channel for settings & membership.

{/* Removed missing image: Channel List & Filters */}

    - Standard (active)
    - Deleted: Gray trash icon (visible to admins only)
    - Muted: Mute icon (all members read-only)
    - Stopped: Gray stop icon (force-closed; members removed)
    - Show All Channels: Includes active / muted / deleted
    - Hide Deleted Channels: Active & muted only
    - Flagged Messages: Channels containing user-flagged messages for review
    - Audit cleanup: Show All
    - Safety triage: Flagged Messages
    - Operational focus: Hide Deleted

## Channel Actions Overview

    Temporarily suspend new member messages (read-only). Use for cooling-off periods or announcement-only phases.

    Immediately close channel and remove all members. Use for irreversible shutdown (archival or policy breach).

    Hide from non-admin users (soft delete). Still visible to admins with gray trash icon for oversight/audit.

    Default (all subscribed), Silent (suppress all), Subscribe (only opted-in). Adjust to control noise & relevance.

    Public = discoverable; Private = invite-only. Only applies to Community channel type.

## Creating a Channel

    Channels → \+ (Create) button.

    Choose Community, Live, or Broadcast.

    Set Channel ID & Display Name (member-visible).

    Choose Public or Private.

    Pre-mute if staging content before opening.

    Pick Default, Silent, or Subscribe based on expected activity volume.

    Confirm settings and create channel.

{/* Removed missing images: Create Channel Button / Channel Creation Dialog */}

  Use Silent mode for high-volume announcement channels where you want manual opt-in later; use Subscribe mode to reduce irrelevant push volume platform-wide.

## Deleting / Stopping a Channel

    Select target from list.

    Navigate to Settings section.

    Decide: Stop (immediate closure) vs Delete (hide from end users).

    Execute action; verify state icon updates.

{/* Removed missing image: Delete Channel Interface */}

  Stopping a channel forcibly disconnects members. Deleting keeps history accessible to admins but hidden from users.

## Managing Channel Users

    Inside channel, select Members.

    Search or scroll through membership list.

    Mute, Ban, Change Role, or Remove.

    Verify icon/state updates (e.g., ban badge).

{/* Removed missing images: Members List / Member Actions */}

    Temporarily restrict a user from sending messages; reversible at any time.

    Block user and remove them from active participation. Unbanning restores eligibility to rejoin.

    Adjust permissions (e.g., moderator vs standard member) aligned with channel governance.

    Detach user from channel without punitive ban; they may rejoin if channel is public or invited.

    - Ban: User flagged as blocked; cannot rejoin until unbanned.
    - Remove: Membership cleared; no block state.
    - Removing a banned user clears ban status—confirm enforcement intent before removing.

{/* Removed missing image: Banned Indicator */}

  Use ban for policy violations; use remove for inactive or off-topic presence without formal enforcement.

## Chat Activities (Beta)

A user-centric analytics view (Manage Users → Chat Activities) showing per-user metrics:

- Total messages sent
- Channels joined
- Flagged messages involvement
- Channel-level breakdown of participation

{/* Removed missing image: Chat Activities Analytics */}

    Identify high-risk users (flag density), evaluate power contributors, support behavioral audits.

    Prioritize intervention for users generating disproportionate flagged content.

    Spot champions for recognition and retention programs.

  Beta feature: Data refresh latency may apply; cross-verify before enforcement escalation.

## Best Practices

    - Define naming conventions for clarity.
    - Segment high-volume topics into dedicated channels.
    - Use Private Community channels for sensitive collaboration.
    - Default sparingly for high-noise channels.
    - Silent reduces fatigue during heavy announcement cycles.
    - Subscribe mode encourages opt-in relevance.
    - Ban only with documented rationale.
    - Review muted channels regularly; unmute when stability returns.
    - Reassess stopped channels quarterly (archive or permanently remove metadata).
    - Track flagged message ratio per channel.
    - Identify recurring violation patterns (spam clusters, harassment zones).
    - Escalate severe violations per internal protocol.

## Troubleshooting

| Issue                                        | Likely Cause                    | Resolution                               |
| -------------------------------------------- | ------------------------------- | ---------------------------------------- |
| Cannot create channel                        | Missing permission / invalid ID | Verify role & unique ID format           |
| Notification mode not saving                 | Unsaved dialog or permission    | Reopen dialog, confirm role rights       |
| User rejoined after remove                   | Remove used instead of ban      | Apply ban for enforcement scenarios      |
| Ban cleared unexpectedly                     | User removed while banned       | Re-ban without removing membership first |
| Channel still visible to admins after delete | Expected soft delete behavior   | No action; working as designed           |
| Messages still incoming after mute           | Delay / client cache            | Confirm mute state; refresh clients      |
| Flagged count not updating                   | Processing delay                | Wait sync cycle or refresh panel         |

## Quick Reference

    Community • Live • Broadcast

    Default • Silent • Subscribe

    Mute • Ban • Role • Remove

    Mute → Stop → Delete (soft)

## Next Steps

    Strengthen enforcement workflows

    Manage users & roles

    Explore chat activity metrics

    Configure official identity

---

### [Message Management](https://learn.social.plus/analytics-and-moderation/console/chat-management/messaging-management)

> Guide for moderators and administrators to broadcast, monitor, filter, action, and govern chat messages in the Console

This page explains how Console moderators and administrators manage real‑time chat: broadcasting, monitoring live streams, filtering, enforcing policy, handling mentions, pinning livestream messages, and applying message-level actions.


## Broadcast Messages

Broadcast channels allow only admin / authorized staff to post while all other members are read‑only—ideal for high-signal announcements, policy updates, campaigns.


{/* Removed missing images: Broadcast Channel View / Broadcast Compose Trigger / Broadcast Message Composer */}


## Live Message Monitoring

Admins can enter any eligible channel to observe real‑time messages, apply filters, enforce policies, and send official interventions.


### Pausing Data Stream

If messages scroll too quickly for review, pause to stabilize viewport:


## Message Types

The system supports multiple structured types:

| Type | Description |
|------|-------------|
| Text | Plain textual content |
| Image | Message containing an image asset |
| File | Message containing a downloadable file |
| Audio | Message containing an audio clip |
| Custom | Developer-defined payload / structured custom data |


## Filtering


## Mentions Governance


{/* Removed missing image: Mention Settings */}


## Message Actions


## Pinned Messages

Pin a message to keep a rule reminder, a link, or an important update in view for every viewer of a livestream, no matter how fast the chat scrolls.

Pinning is available only in livestream channels: chat channels attached to a livestream post. The pin action does not appear in other channel types or in the thread view.

### Pin or unpin a message


### Behavior

A channel holds one pinned message at a time. Pinning another message replaces the current pin. Deleting the pinned message, or banning its author from the channel or globally, clears the pin.

- The pinned message shows as the first row of the Messages table, with a pin marker ("Pinned"). This happens even when the message is on an older page.
- When a message filter is active, the pinned message appears only if it matches the filter and is on the current page. When it appears, it is still the first row.

### Permissions

The server authorizes pin and unpin with the `PIN_MESSAGE` permission. In the console's role editor, it appears under **Manage messages** as "Pin a message in a live channel". Without it, the action fails with an access-restricted error.

## Enforcement Workflow Example


## Best Practices

    - Use Pause only when necessary (avoid missing fast-moving signals).
    - Batch similar actions to reduce context switching.
    - Revisit blocklist quarterly for false positives.
    - Delete only when content violates policy; otherwise educate via reply.
    - Prefer Mute for temporary disruption vs immediate ban.
    - Escalate self-harm / threat content per protocol before deletion.
    - Consolidate multiple small announcements into a single structured broadcast.
    - Avoid marketing repetition; track engagement drop-off metrics.
    - Encourage targeted @user use for clarity.
    - Limit @all to critical updates (target threshold e.g., &lt;2 per week per channel).

## Troubleshooting

| Issue | Likely Cause | Resolution |
|-------|--------------|------------|
| Stream not resuming | Pause still active | Click Resume; verify UI state |
| Flag not clearing | Permission or stale state | Refresh; confirm role; retry |
| @all still works after disable | Cached settings | Refresh channel view; re-save setting |
| Blocklist term not applied | Formatting mismatch | Add normalized (lowercase / trimmed) variant |
| Broadcast failed | Network or missing rights | Retry; verify broadcast privilege |
| User keeps reoffending | Mute instead of ban | Apply ban + document rationale |
| Deleted message visible shell | Expected placeholder | No action—design for audit clarity |
| No **Pin message** action | Not a livestream channel, thread view, or deleted message | Open the livestream channel's Messages tab |

## Quick Reference


## Next Steps

---

### [Communities Management](https://learn.social.plus/analytics-and-moderation/console/social-management/communities)

> Manage community creation, organization, permissions, membership, and activity in the social.plus Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/L08qa3hhQ1k?si=aUStV8KBC_bhTi3y" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  **Goal**: Provide operators and moderators with efficient workflows to create, organize, govern, and moderate user communities at scale.

The Communities section of the Console centralizes everything: creation, categorization, activity oversight, membership governance, and fine‑grained permissions.

    Launch new spaces with avatar, category & visibility
    Review posts, comments, schedules & flags
    Add, remove, ban, or change member roles
    Configure posting, approvals & commenting rules
    Organize & discover related communities
    Surface at‑risk communities & escalation targets

## Primary Workflows

        Navigate: Social Management → Communities.
        Click the \+ (Create New Community) button.
        Avatar, Name, About (≤180 chars), Category.
        Default, Silent or Subscribe (see Notification Modes below).
        Validate visibility & category before saving.
      Screenshot placeholders can be inserted where needed using \<figure\> blocks.
    Use the Activity tab inside a selected community to:

    - View all posts & comments (including soft‑deleted for review)
    - Approve / decline pending (approval-required) posts
    - Schedule future posts
    - Inspect flag counts & reported comment indicators

      Flag filters quickly surface content needing intervention.
    The Members tab provides:

    - Search by user ID or display name
    - Filters: banned / deleted / role-based
    - Role adjustments (member ↔ moderator)
    - Community ban / unban actions

      Banned or deleted users retain status indicators for audit clarity.
    Split across two tabs:

    - Permissions: Posting & commenting governance
    - Settings: Identity & structural attributes (avatar, name, description, category, official flag, visibility)

      Deleting (closing) a community is irreversible. Archive alternatives should be considered first.
    Categories cluster communities by theme to enhance discovery.

    - Create & edit categories centrally
    - Tag multiple communities under a shared interest
    - Enable cross‑promotion (“See more in Fitness”)

## Permissions & Governance

    **Options**:

    - Only admins can post: Restricts creation to moderators/admins (announcement mode)
    - Approve member posts: Member posts enter an approval queue
    - Open posting (default): All members post immediately

      "Only admins can post" and "Approve member posts" are mutually exclusive.
    Global toggle for allowing comments on community stories.

    - Enabled: All active stories accept member comments
    - Disabled: No stories within the community accept comments

      Granular per‑story comment locking is not currently supported.
    Define default push behavior for new community activity:

    - Default: Notifications ON for all members (may opt out)
    - Silent: Notifications OFF & cannot be enabled by members
    - Subscribe: Notifications OFF by default; members may opt in

      Use Silent for low-noise hubs or archive‑style communities.
    Editable fields:

    - Avatar (brand & recognition)
    - Name & Description (≤180 chars recommended)
    - Category (affects discovery grouping)
    - Official Flag (trust / authenticity badge)
    - Visibility: Public vs Private (affects access & join flow)
    - Closure: Permanent removal (non‑recoverable)

## Best Practices

    - Batch resolve low‑risk approvals daily
    - Use categories early to avoid later reclassification overhead
    - Maintain naming conventions (e.g., Region • Topic)
    - Standardize moderator notes for actions
    - Start with open posting \+ approvals for new communities
    - Introduce Only-admin mode for broadcast / compliance spaces
    - Monitor flag ratios: flags per 100 posts as drift indicator
    - Periodically audit moderator role assignments
    - Curate category landing pages with representative communities
    - Highlight official communities for trust signaling
    - Use Subscribe mode for optional-interest clusters
    - Rotate featured categories based on engagement analytics

## Next Steps

    Align moderator capabilities with governance model
    Integrate community workflows with platform moderation

    Track growth & risk indicators across communities
    Manage taxonomy & discoverability structures

---

### [Stories Management](https://learn.social.plus/analytics-and-moderation/console/social-management/stories)

> Guide for moderators and administrators to create, schedule, view, and moderate Stories in the Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/7ZsAIvKEHpY?si=mNRzF-okbcbSPfvG" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  This page explains how Console moderators and administrators manage Stories across communities: creation, scheduling, visibility, moderation, and lifecycle oversight. It focuses on operational workflows (not developer implementation).

    Upload image & video Stories (up to 10 items)

    Plan Story releases up to 30 days ahead

    Track Active, Expired, Scheduled status

    Delete or clear flagged Stories

    Leverage links & narrative sequencing

    Use lifecycle & performance signals

## Accessing Stories

    Go to Admin Console → Stories.

    Search by community name or ID.

    Switch between Active, Expired, and Scheduled.

    Create, schedule, delete, or clear flags as needed.

{/* Removed missing image: Stories Module Entry */}

## Creating Stories

    - Images: up to 1 GB each
    - Videos: under 2 GB, ≤ configured maximum duration (default 90s)
    - Up to 10 media files per Story batch (all publish together as sequential individual Stories)
    - Single creation batch = ordered Story sequence for narrative impact
    Drag to reorder before publishing / scheduling.
    Use sequencing for: event recaps, multi-step tutorials, campaign countdowns.
    Add an optional hyperlink per Story item.
    If URL whitelisting is enabled, destination must be pre-approved or link cannot be saved.
    - Earliest schedule time: ≥ 1 hour from now
    - Latest schedule time: up to 30 days ahead
    - All items in the batch follow the same release time and then display in the order configured
    Console preview approximates in‑app experience (device variances may apply). Validate crop, readability, caption relevance, and link integrity before finalizing.

{/* Removed missing images: Media Upload / Reorder & Links / Scheduling Stories */}

  Reordering and link edits are only possible before publishing or while the batch is still in Scheduled status.

## Story Status Lifecycle

    Currently visible Stories within their active duration window.

    Stories whose visibility period has concluded; retained for reference in Console only.

    Approved Story batches waiting to publish at their scheduled time.

{/* Removed missing image: Status Tabs */}

  The count displayed on a community's Stories card reflects Active \+ Expired only (excludes Scheduled and Deleted).

## Viewing Stories

Within Active & Expired tabs you can:

- View media (image / video)
- Access hyperlinks
- Check comment count (and flagged comment count if applicable)
- View reactions count
- Moderate (delete, clear flags)

{/* Removed missing images: Stories Card in Community / Stories Listing */}

Scheduled tab displays:

- Upcoming batches sorted by scheduled date (latest first)
- Hyperlinks configured per Story item
- Delete option (removes entire scheduled batch)

  Deleted Stories are not viewable in Console once removed. Confirm before deletion.

## Moderation Actions

    Remove inappropriate or outdated Story items. Action is immediate and irreversible.

    After review, clear resolved or invalid reports to maintain accurate escalation focus.

    Delete scheduled batches that are no longer relevant before they publish.

## Operational Best Practices

    - Batch related content for cohesive storytelling.
    - Schedule during high engagement windows (analyze past peak hours).
    - Limit daily volume to avoid fatigue.
    - Maintain consistent aspect ratios & branding.
    - Ensure text overlays remain legible (contrast, safe margins).
    - Keep videos concise and purposeful.
    - Review flagged Stories promptly (ideally within SLA window).
    - Use whitelisted links only; remove any violating destinations.
    - Document deletion rationale for sensitive content categories.
    - Track reactions & comment patterns to refine timing & style.
    - Use links sparingly for high-intent actions (avoid dilution).
    - Sequence multi-part content with clear narrative arcs.

## Troubleshooting

| Issue                      | Likely Cause                      | Resolution                        |
| -------------------------- | --------------------------------- | --------------------------------- |
| Cannot schedule \< 1h      | Minimum lead time rule            | Set time ≥ 1 hour ahead           |
| Schedule \>30 days blocked | Exceeds max window                | Choose date within 30 days        |
| Link rejected              | Not whitelisted                   | Add to whitelist or remove link   |
| Video upload fails         | Size or duration exceeded         | Compress or shorten video         |
| Missing previews           | Temporary network or format issue | Reupload / refresh page           |
| Story not publishing       | Time mismatch / unsaved changes   | Reconfirm schedule & save         |
| Flags not clearing         | Permission or state change        | Verify role permissions & refresh |

## Quick Reference

    10 media files per batch

    Default 90s (configurable)

    1h → 30 days ahead

    Whitelist (if enabled)

## Next Steps

    Configure community settings

    Manage posts & comments

    Strengthen safety workflows

    Evaluate performance trends

---

### [Posts Management](https://learn.social.plus/analytics-and-moderation/console/social-management/social-management/posts)

> Guide for moderators and administrators to view, filter, create, feature, pin, and moderate posts in the Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/-tnVtREQnqk?si=QfgbqERDHR3vPV7Z" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  This page explains how moderators and administrators use the social.plus Console to manage community content. It focuses on operational workflows (not developer implementation).

    Locate content by context: community, user, post, or external feed. Filter by AI-powered quality labels.

    Approve, feature, pin, close polls, or remove content.

    Publish standard and poll posts as yourself or Brand. Tag products from the catalogue in post content.

    Feature globally / in community, maintain pinned collections.

    Monitor flags, activity, engagement, poll participation, and content quality.

    Use AI quality detection to identify excellent posts and surface low-quality content.

## Accessing the Module

    Go to Admin Console → Posts & Comments.

    Choose Content (external), Community, User, or Post.

    Enter required community ID/name, user ID/display name, or post ID.

    Use status tabs, date range, flag toggle, and feed selectors.

    - **Content (External)**: Network-wide external or aggregated content.
    - **Community**: Posts in one community (requires community ID or name).
    - **User**: Posts authored by / to a user (user ID or display name).
    - **Post**: Fetch a single post (post ID) and its comments.
    - Posted
    - Scheduled
    - Requires approval
    - Global featured
    - Community featured
    - Pinned
    - Deleted
    Toggle the Flag filter to surface reported content needing immediate review.

## Post Row Information

Each post line provides:

- Author name / avatar
- Community name (when applicable)
- Timestamp & last activity
- Visibility indicators (featured / pinned / scheduled / requires approval)
- Content Quality Label (Excellent, Good, Fair, Weak, Broken)
- Engagement: reaction count, comment count
- Poll data (when poll): type (Single / Multiple), total votes, option breakdown & percentages, end time

  Poll options are automatically sorted by vote count (highest to lowest) to help you assess performance at a glance.

## AI Content Quality Detection

social.plus now automatically evaluates post quality using AI-powered detection, giving you immediate visibility into which contributions meet your community's standards. Each post receives a quality label based on relevance, structure, clarity, and engagement potential—helping you quickly identify high-value content to feature or low-quality posts that need attention.

    Every post with text content is automatically scored against your community's quality standards.

    Filter by quality level to focus on excellent contributions or identify weak content.

    Hover over any quality label to see detailed explanations of what makes content excellent or weak.

    Reduce manual review time by letting AI surface posts that matter most.

### Getting Started with Quality Detection

  **Feature Enablement Required**: AI Content Quality Detection is an advanced feature that must be enabled by our support team. Contact your account manager or [reach out to support](mailto:support@social.plus) to activate this feature for your application.

#### Customizing Quality Definitions

Every application has unique standards for what makes content valuable. social.plus allows you to customize quality detection criteria to match your application's specific needs and culture.

    Work with our team to define the most suitable quality definitions for your application:

    - **Default Quality Definitions**: The content can be anything in social network. Add a bonus point for a review, reaction, tip, movie and lifestyle. The message should be clear and easy to understand, even if written casually.

    Quality detection improves over time as it learns from your application:

    - Share examples of posts you consider excellent or problematic
    - Provide feedback on scoring accuracy through our support team
    - Request periodic reviews to ensure criteria remain aligned with evolving application standards
    - Access reporting on quality trends to inform strategy adjustments

  **Implementation Timeline**: After requesting enablement, our team will work with you to configure quality definitions.

### Understanding Quality Labels

Each post displaying text content receives one of five quality labels:

    **Fully relevant, strongly written—clear, structured, expressive, and likely to engage.**

    These posts demonstrate exceptional quality with well-structured content that drives meaningful discussions. They're ideal candidates for featuring or pinning.

    **Characteristics:**
    - Clear, focused message aligned with community topics
    - Well-organized with proper formatting
    - Engaging tone that invites interaction
    - Comprehensive yet concise

    **Relevant and well-written with minor room for improvement in clarity or structure.**

    Quality contributions that meet community standards. These posts are valuable but may lack the polish of excellent content.

    **Characteristics:**
    - Clear relevance to community
    - Generally well-structured
    - Minor formatting or clarity issues
    - Solid foundation for engagement

    **Moderately relevant or adequately written, but lacks depth or polish.**

    Acceptable contributions that don't violate guidelines but may not drive significant engagement.

    **Characteristics:**
    - Basic relevance maintained
    - Minimal structure or detail
    - Could benefit from elaboration
    - Meets minimum standards

    **Low relevance or poorly written—unclear, unstructured, or minimally engaging.**

    These posts may require moderator review to determine if they should remain visible or if author guidance is needed.

    **Characteristics:**
    - Unclear purpose or relevance
    - Poor structure or formatting
    - Minimal effort or substance
    - Low engagement potential

    **Irrelevant, unintelligible, or severely lacking in quality—likely spam or off-topic.**

    Content that should be reviewed immediately for potential removal. Often indicates spam, off-topic content, or severe quality issues.

    **Characteristics:**
    - No clear relevance to community
    - Unintelligible or nonsensical
    - Possible spam or abuse
    - Requires immediate attention

  **Text Content Only**: Quality detection analyzes text content exclusively. Posts containing only media (images, videos, files) without text will not display a quality label. Posts with both text and media are scored based on the text content.

### Viewing Quality Labels

Quality labels appear automatically on posts throughout the Console:

    View quality labels on all posts authored by a specific user to assess their overall contribution quality.

    See quality labels on all posted content across communities and contexts.

    Hover over any quality label to see a tooltip explaining what that score means and why it was assigned.

  Quality labels are **not displayed** on Pending, Scheduled, Pinned, Global Featured, Community Featured, or Deleted tabs. They appear only in the Posted tab and User History.

### Filtering by Content Quality

Use quality filtering to focus your moderation efforts where they matter most:

    Filter by one quality level (e.g., "Excellent") to review top contributions for featuring opportunities.

    **Use Cases:**
    - Find excellent posts to feature globally or in communities
    - Identify weak or broken content requiring immediate review
    - Audit fair posts to provide author guidance

    Select multiple quality levels simultaneously to create custom review queues.

    **Example Workflows:**
    - Select "Excellent + Good" to find feature candidates
    - Select "Weak + Broken" to prioritize removal queue
    - Select "Fair + Weak" to identify posts needing author coaching

    Quality filters work independently—they cannot be combined with other filters (status, date range, flags).

    **Best Practice:**
    - Use quality filtering first to identify priority content
    - Then apply other filters in subsequent reviews
    - Combine with context filters (Community, User) for targeted audits

    Go to Posts & Comments → Select your context (Community, User, Content) → Click **Posted** tab.

    Click the **Quality** filter dropdown and select one or more quality levels.

    Posts are displayed by recency (most recent first). Scroll to review all matching content.

    Feature excellent posts, review weak content for removal, or provide guidance to authors.

  **Filtering Limitations:**
  - Quality filtering is available only in the **Posted** tab (excludes Pinned, Global Featured, Community Featured)
  - Cannot combine quality filters with other filter types
  - Deleted posts are excluded from quality filter results

### Quality-Driven Moderation Workflows

    **Morning Routine:**
    1. Filter by "Excellent" to identify featuring candidates
    2. Review top posts for community or global featuring
    3. Filter by "Broken + Weak" to catch quality issues
    4. Remove spam or guide authors to improve content

    **Time Savings:** Focus on extremes (best and worst) rather than reviewing all content.

    **Weekly Analysis:**
    1. Filter each community by quality levels
    2. Track ratio of Excellent/Good vs Weak/Broken posts
    3. Identify communities needing content guidelines
    4. Coach power users creating consistently weak content

    **Insight:** Communities with high "Fair" ratios may need clearer posting guidelines.

    **User History Review:**
    1. Navigate to User context → User History → Posted tab
    2. Review quality distribution of user's posts
    3. Identify top contributors (consistent Excellent/Good)
    4. Provide feedback to users with consistent Weak/Broken scores

    **Recognition:** Use quality data to identify community champions for rewards programs.

    **Strategic Visibility:**
    1. Filter by "Excellent" in high-traffic communities
    2. Review engagement metrics (reactions, comments) alongside quality
    3. Feature posts combining excellent quality with high engagement
    4. Track featured post performance to refine criteria

    **Optimization:** Quality + engagement = maximum community impact.

### Quality Label Best Practices

    Quality labels provide guidance, not absolute rules. Always review flagged content and use your judgment for edge cases.

    **Considerations:**
    - Cultural context and community norms
    - Technical content may appear "weak" but be highly valuable
    - Short announcements may score lower but serve clear purposes

    Use quality insights to coach community members on creating better content.

    **Approach:**
    - Share examples of "Excellent" posts as templates
    - Provide constructive feedback on "Weak" posts
    - Create community guidelines based on quality patterns

    Don't remove content solely based on quality labels—focus on policy violations and community guidelines.

    **Guidelines:**
    - "Broken" posts → Review for spam/off-topic removal
    - "Weak" posts → Consider author guidance before removal
    - "Fair" posts → Generally acceptable, may improve over time

    Leverage quality data to identify and reward top contributors.

    **Ideas:**
    - Monthly highlights of users with consistent "Excellent" posts
    - Community badges for quality contributors
    - Feature "Post of the Week" based on quality + engagement

  **Privacy & Transparency**: Quality labels are visible only to administrators and moderators with appropriate permissions. Community members do not see quality scores on their own or others' posts.

### Community-Level Overview

When filtering by a community you can also see:

- Total posts in period
- Member count
- Pending posts
- Flagged posts/comments
- Last activity timestamp
- Community type (Public / Private)

## Filtering & Discovery

    Use feed type, context selector, and status tabs to narrow results. Combine with flag toggle for urgent reviews. Use **Search posts** to jump straight to posts containing a keyword or hashtag (see Searching Posts by Keyword & Hashtag below).
    Filter by content quality levels (Excellent, Good, Fair, Weak, Broken) in the Posted tab to focus on high-value or problematic content. Select one or multiple quality levels to create custom review queues.
    Use the date range picker in the page header to focus on recent surges or historical review windows (see Filtering by Date Range below). Applies to both the Posts and Comments & Replies tabs.
    Filter by Requires approval \+ Flagged to prioritize intervention queues.
    Periodically scan Deleted and Flagged to validate moderation consistency. Use quality filtering to identify patterns in removed content.

## Searching Posts by Keyword & Hashtag

The **Search posts** field on the Posted tab lets you locate posts by their text content — including hashtags — without scrolling through the full feed.

    From Posts and comments → Posts, stay on (or switch to) the **Posted** tab where the search field lives above the post list.
    Click into **Search posts** and start typing. Results update automatically as you type (search-as-you-type, with a short debounce) — no need to press Enter. Matched terms are highlighted directly in the post text within the results.
    Include the **#** symbol to search for a specific hashtag (e.g. `#DocsHashtagDemo`). The console matches posts containing that hashtag in their body text; hashtags themselves render as clickable links within posts.
    Click the **×** icon inside the search field to clear your query and return to the full list.

<img
  src="/images/analytics-and-moderation/console/social-management/search-posts-keyword-results.png"
  alt="Search posts field showing keyword matches highlighted in post results"
/>

  Search results respect any other active filters — feed type (All feeds / User feed / Community feed), creator, status, and visibility — so you can combine a keyword/hashtag search with these selectors to narrow results further (e.g. search "promo" within a single community's "Active in feed" posts).

  If no posts match your query, the list shows **No results found — Try changing the search keywords.** Double-check spelling, try a shorter/partial term, or remove the **#** to search the surrounding text instead of the exact tag.

## Filtering by Date Range

The date range picker in the top-right of **Posts and comments management** limits the list to content created inside a window you choose. By default it reads **Showing all time content** — no date filter is applied.

<img
  src="/images/analytics-and-moderation/console/social-management/posts-date-range-picker.png"
  alt="Date range picker showing Today, Last 7 days, Last 30 days, Last 6 month, and This year presets beside a two-month calendar with Cancel and Apply buttons"
/>

### Choosing a Range

    Click **Showing all time content** (or the current range) in the page header. A panel opens with quick presets on the left and a two-month calendar on the right.
    Choose **Today**, **Last 7 days**, **Last 30 days**, **Last 6 month**, or **This year**. Presets apply immediately and close the picker — no confirmation needed.
    Click a start date, then an end date. Use the arrows above the calendar to move between months (single arrows move one month, double arrows move one year). Click **Apply** to run it, or **Cancel** to discard.
    The header shows the active window (e.g. *01 Jul 2026 - 15 Jul 2026*) and a **Total posts** count appears above the list. On the Comments & Replies tab the count reads **Total comments and replies**.
    Click the **×** on the date control to return to all-time content. The total count disappears with it.

With a range active, the header shows the window and the list is preceded by the matching total:

<img
  src="/images/analytics-and-moderation/console/social-management/posts-date-range-active.png"
  alt="Page header with an active 01 Jul 2026 - 31 Jul 2026 range and a Total posts count above the post list"
/>

The range filters on **creation date**. A post created inside the window still appears when its **Last activity** timestamp falls outside the window, so an old thread with recent comments won't surface unless its creation date matches.

### Scope and Behavior

| Behavior | Detail |
|---|---|
| **Tab coverage** | The range persists across the **Posts** and **Comments & Replies** tabs, and across the **Posted** / **Deleted** sub-tabs. Each view recounts against the same window. |
| **Other filters** | Combines with feed, creator, status, visibility, and keyword search — results must match the range *and* every other active filter. |
| **Future dates** | Disabled in the calendar; ranges cannot extend past today. |
| **Total count** | Shown only while a range is active. All-time views display no count. |
| **URL parameters** | The active range is written to the URL as `startDate` and `endDate` in `YYYY-MM-DD` form. |

Because the range lives in the URL, a filtered view is shareable and bookmarkable — send a teammate `?startDate=2026-06-01&endDate=2026-06-30` to hand them the exact review window, or keep a bookmark for a recurring audit period.

Quality filters are the exception: they work independently and cannot be combined with a date range. Apply one or the other in a given pass.

## Moderation Actions

    Approve pending posts from Requires approval tab. Reject (delete) content that violates guidelines. Document decisions where policy demands audit trails.
    Temporarily remove a post from all feeds via the action menu (⋮) → Hide post (see Hiding & Unhiding Posts below). Reversible at any time via Unhide post — ideal for borderline content under review.
    Elevate visibility (see Featuring & Pinning section). Combine community featuring with pinned collections for both spotlight \+ lasting access.
    Close polls early via the post action menu (⋮) if policy, abuse, or sufficient responses justify it. Closing locks further votes; results remain visible.
    Inspect flagged content promptly. Confirm valid reports, take action (remove, unfeature, unpin), or clear false positives.
    Delete posts violating policy. Periodically review Deleted tab (if retention enabled) to ensure removals are consistent.
    Confirm scheduled posts timing (timezone, relevance). Adjust or cancel outdated scheduled content before publication.

## Creating Posts

    In Posts & Comments, click Create Post or Create Poll Post.

    Set Share to: Community feed or User feed (other feeds may appear if configured).

    Post as: Yourself or Brand (Brand must be configured in Settings → Brand Settings).

    Add clear text, mention users with @ (≤30 mentions), tag products with @ (switch to Tag product tab), and attach media if applicable.

    Check formatting, attachments, identity, then Post or Schedule.

### Standard Post Guidelines

- Break long text into short paragraphs.
- Use mentions purposefully—avoid notification overload.
- Attach media to increase clarity (events, tutorials, updates).
- Support media types (per configuration) — images, videos, files (single media type per post up to 10 files).

## Tagging Products in Posts

Products from the catalogue can be tagged directly in post content when creating or editing posts in the Console. This enables social commerce workflows where product references appear as interactive links within community content.

<img
  src="/images/analytics-and-moderation/console/social-management/post-tag-product-dropdown.png"
  alt="Tagging a product in post content using the @ symbol"
/>

### How to Tag a Product

    Navigate to **Posts and comments** and click **Create post**. Choose the destination feed and posting account.
    In the **Body text** field, type `@` followed by the product name you want to tag (e.g., `@pizza`). A dropdown will appear with two tabs: **Mention user** and **Tag product**.
    Click the **Tag product** tab to search for products from your catalogue. The dropdown displays matching products with their thumbnail images.
    Click on the desired product from the search results. The product name will be inserted as an interactive link in your post content.
    After tagging, a **View all tagged products** button appears below the body text. Click it to see all products tagged in the post with their images and prices.

### Tagged Products Display

Once a post with tagged products is published, the tagged products appear in two ways:

1. **Inline Links**: Product names appear as clickable links within the post text, linking to the product URL
2. **Product Card Section**: A "Products tagged in this post" section displays below the post content with product thumbnails, names, and prices

<img
  src="/images/analytics-and-moderation/console/social-management/posts-list-with-product-tags.png"
  alt="Published post showing tagged products with thumbnails and prices"
/>

### Tagged Products Panel

Click **View all** on a published post or **View all tagged products** during creation to open a panel showing all tagged products with their images and pricing details.

<img
  src="/images/analytics-and-moderation/console/social-management/post-tagged-products-panel.png"
  alt="Products tagged in this post panel showing product details"
/>

Only products with **Active** status in the Product Catalogue are available for tagging. **Archived** products will not appear in the tag product search results.

Product tagging in posts supports the same `@` trigger used for user mentions. The dropdown provides tab-based switching between **Mention user** and **Tag product** functionality.

### Brand Posting

  Brand appearance and verification icon are configured by Super Admins. Use for authoritative announcements.

- Maintain consistent tone and formatting.
- Reserve for official communications, not casual chatter.
- Distinguish Brand vs personal admin voice to build trust.

## Poll Posts

    Gather structured feedback: feature prioritization, content preferences, scheduling, sentiment checks.

    Use neutral, concise questions. Avoid leading phrasing. Mention key stakeholders only if necessary.

    Provide 2–10 mutually exclusive, balanced options. Keep lengths similar. Remove redundancy.

    Single (decisions) vs Multiple (preference gathering / prioritization).

    Choose preset (1, 3, 7, 14, 30 days) or custom (≤30 days). Align end time with decision cadence.

    Close early only if: consensus reached, abuse occurring, deadline advanced, or policy violation present.

  Media attachments are not currently supported in poll questions.

## Featuring & Pinning

    Add frequently referenced posts (guidelines, FAQs, recurring updates). Up to 20 per community. Sorted newest pin first; manual reordering not supported.

    Steps:

    1. Locate post (Community / Posts context)
    2. Click pin icon in Actions
    3. Confirm appearance in community Pinned tab

    Unpin via same icon. Only non-deleted posts qualify. Public community pinned posts are visible to all; only members may interact.
    Highlight one high-impact post at top of a community feed (one active per community). Ideal for launches, events, urgent notices.

    Steps:

    1. Click star icon → Feature in this community
    2. Visible in Featured tab & top of feed
    3. Remove by un-star → Remove community featured post
    Maximum visibility across all communities/platform surfaces.

    Steps:

    1. Actions menu (⋮) → Feature globally
    2. Track in Global featured tab (timestamp, admin, admin ID)
    3. Remove via (⋮) → Remove global featured post
    - Launches: Feature globally during rollout → Pin for long-term reference.
    - Community events: Feature in community pre-event → Pin logistics → Remove feature post-event.
    - Evergreen policy: Pin indefinitely → Re-feature on major revision.

## Hiding & Unhiding Posts

Hiding gives moderators a quick, reversible way to pull a post out of circulation without permanently deleting it — useful for content that's under review, contested, or only mildly against guidelines.

  Hiding a post removes it from all feeds (community, user, global, search). The creator can still see it on their own profile, and any moderator can reverse the action via **Unhide** at any time.

### Hiding a Post

    In Posts & Comments (or User History → Posted), find the post and click the (⋮) menu on its row.
    Choose **Hide post**. Optionally add a **Reason** (up to 250 characters) — this documents the rationale for audit trails and team handoffs.
    Click **Hide**. The post disappears from all feeds immediately, and its row now displays a **Hidden by** badge with the moderator's avatar.

<img
  src="/images/analytics-and-moderation/console/social-management/hide-post-menu-option.png"
  alt="Hide post option in the post action menu"
/>

<img
  src="/images/analytics-and-moderation/console/social-management/hide-post-confirmation-dialog.png"
  alt="Hide this post confirmation dialog with optional reason field"
/>

<img
  src="/images/analytics-and-moderation/console/social-management/post-hidden-badge.png"
  alt="Post displaying the Hidden by badge after being hidden"
/>

### Restoring a Hidden Post

    On a hidden post (identifiable by its **Hidden by** badge), click the (⋮) menu — it now shows **Unhide post** in place of Hide post.
    Select **Unhide post**, optionally add a reason, then click **Unhide**. The post becomes visible in all feeds again immediately and everyone can interact with it as before.

<img
  src="/images/analytics-and-moderation/console/social-management/unhide-post-confirmation-dialog.png"
  alt="Unhide this post confirmation dialog"
/>

### Finding Hidden Posts

On the Posted tab, use the **Select visibility** filter (alongside the feed and creator selectors) and choose **Hidden** to list only posts that are currently hidden — useful for periodic reviews or to confirm an action took effect. Switch back to **Active in feed** (or clear the filter) to see posts visible in the feed.

  **Hide vs. Delete**: Hiding is reversible and keeps the post intact and visible to its creator; deleting permanently removes the post from the Posted tab into Deleted. Prefer hiding for borderline cases or while awaiting further review, and reserve deletion for clear policy violations.

## Best Practices

    - Review Requires approval & Flagged queues twice daily.
    - Filter by "Broken" quality to catch spam and off-topic content.
    - Check "Excellent" posts for featuring opportunities.
    - Verify scheduled posts relevance and timing.
    - Rotate featured content to prevent banner fatigue.
    - Document rationale for removals affecting policy precedent.
    - Use quality labels as guidance, not absolute rules—consider context.
    - Maintain neutral poll phrasing.
    - Verify media quality & appropriateness.
    - Provide constructive feedback to users with consistently weak content.
    - Track flags per 100 posts (trend indicator).
    - Monitor ratio of Excellent/Good vs Weak/Broken posts by community.
    - Watch for sudden reaction spikes (possible brigading).
    - Identify communities with low activity for activation campaigns.
    - Recognize top contributors with consistent high-quality posts.
    - Avoid over-featuring; scarcity drives attention.
    - Prioritize featuring posts with "Excellent" quality + high engagement.
    - Clean pinned collections monthly (remove outdated guidance).
    - Reassess global features after relevance declines.
    - Balance quality with diversity—don't only feature same authors.

## Troubleshooting

| Issue                          | Likely Cause                              | Resolution                                                      |
| ------------------------------ | ----------------------------------------- | --------------------------------------------------------------- |
| Cannot post as Brand           | Brand not configured / permission missing | Configure in Settings → Brand Settings or adjust admin role     |
| Mentions fail                  | \>30 mentions or invalid usernames        | Reduce mentions, verify usernames                               |
| Media upload blocked           | Unsupported type / size limit exceeded    | Compress or use supported format                                |
| Poll option rejected           | Exceeded 10 options or duplicate text     | Consolidate / remove extras                                     |
| Scheduled post missing         | Timezone mismatch or not approved         | Confirm timezone & approval status                              |
| Cannot feature/pin             | Post deleted or insufficient role         | Verify post state & role permissions                            |
| Hidden post still visible to creator | Expected behavior                   | Hiding only removes the post from feeds — the creator can still see it on their own profile |
| Cannot find hidden posts       | Visibility filter not applied             | On the Posted tab, set **Select visibility** to **Hidden**      |
| Poll cannot close early        | Action menu context mismatch              | Ensure selecting poll row (not filtered out)                    |
| Quality label not showing      | Post has no text content or is pending    | Quality detection requires text; labels appear only on Posted tab |
| Quality filter not working     | Applied in wrong tab or context           | Use quality filter only in Posted tab (excludes featured/pinned) |
| Cannot combine quality filters | Quality filters work independently        | Apply quality filter alone; other filters must be cleared       |
| Product tag not appearing      | Product is Archived or search text too short | Ensure product status is Active in Product Catalogue; type at least part of the product name after @ |
| Tagged product shows as unavailable | Product was deleted after tagging      | Re-tag with an active product or restore the product in the catalogue |

## Next Steps

    Configure communities & permissions.

    Manage products available for tagging in posts.

    Refine moderation workflow.

    Monitor engagement & health.

---

### [Comments Management](https://learn.social.plus/analytics-and-moderation/console/social-management/social-management/comments)

> Guide for moderators and administrators to view, moderate, create, and reply to multi-level comments in the Console

This page explains how Console moderators and administrators manage comment visibility, quality, safety, and engagement. Comments support **multi-level threading**, allowing nested conversations at multiple depths.


## Accessing Comments

There are two ways to access comments in the Console:


      <img src="/images/analytics-and-moderation/console/posts-page-overview.png" alt="Posts page overview" />

      <img src="/images/analytics-and-moderation/console/comments-drawer-open.png" alt="Comment panel" />

      <img src="/images/analytics-and-moderation/console/posts-page-comments-tab.png" alt="Posts page - comment and replies tab" />

## Comment Thread Structure

Comments support **multi-level threading** — replies can be nested multiple levels deep, creating branching conversations within a single post.

    Each comment or reply shows:
    - **Author photo & name** — click to view the user's history
    - **Timestamp** — date and time the comment was posted
    - **Comment text** — including **@mentions** (e.g., `@username`) that link to the mentioned user
    - **AI Moderation status** — shows "AI Mod: Passed" in green, or the flagged category (e.g., "Harassment or bullying")
    - **Engagement counts** — number of reactions and replies; click to expand replies
    - **Flag button** — quickly flag a comment for review
    - **More options menu** (⋮) — additional actions like edit, delete, and copy ID (see [Moderation Actions](#moderation-actions))
    Comments are organized in a **nested tree structure**:
    - **Level 1**: Top-level comments on a post
    - **Level 2**: Replies to top-level comments
    - **Level 3+**: Replies to replies, allowing deep conversational threads

    Each level is shown with:
    - **Indentation** and a reply arrow (↩) to show which comment is being replied to
    - **"X replies" link** — click to expand or collapse replies underneath
    - **"Hide replies"** — collapse an expanded reply thread to keep the view tidy

      <img src="/images/analytics-and-moderation/console/comments-deeper-level.png" alt="Multi-level comments expanded" />
    Users can mention other users in comments and replies using the `@username` syntax. Mentions are:
    - Displayed as **clickable links** that navigate to the mentioned user's profile/history
    - Visually distinguished from regular text
    - Supported at all comment nesting levels
    Use reaction & reply counts to surface:
    - Emerging discussions needing moderation
    - Popular threads for community amplification
    - Potential hotspots for policy enforcement
    - Deep reply chains that may indicate heated discussions
    Every comment and reply is automatically checked by the AI moderation system:
    - **Passed** — a green "AI Mod: Passed" label appears on the comment
    - **Flagged** — the specific violation category is shown (e.g., "Harassment or bullying")
    - This status is visible on every comment at any nesting level
    - Flagged comments are highlighted in the thread
    - Each comment has a **flag button** for quick flagging
    - Prioritize review based on severity & volume
    - Clearing a flag removes it from escalation metrics

## Comment Approval

A community can require that member comments are reviewed before anyone else sees them. While the setting is on, a member's comment is held the moment it is written: the author still sees their own comment, and nobody else does until a moderator approves it.

Comments left by moderators and admins are never held — a reviewer is not gated by their own setting. Comments on stories are never held either, because a story expires and an approval could publish a comment onto a story no member can still open.

### Turning it on

The setting belongs to a community, not the network, so you can require approval in one space and leave the rest open.


  <img src="/images/analytics-and-moderation/console/community-permissions-approve-comments.png" alt="Approve member comments toggle on the community Permissions tab" />

Turning the setting on affects new comments only. Comments already published stay published.

### Reviewing the queue


  <img src="/images/analytics-and-moderation/console/comments-requires-approval-queue.png" alt="Requires approval queue" />

When nothing is waiting, the queue reads "No comments are waiting for approval in this community."

### Approving and declining

    **Approve** publishes the comment to everyone who can see the post. The Console confirms with "Comment has been approved".

    An approved comment appears in the thread **where it was written**, not at the end — so a comment approved some time after it was posted is inserted back into its original position, which readers may already have scrolled past.
    **Decline** opens a confirmation: "Decline this comment?" — "Declining permanently deletes this comment. You can add a reason for your records."

    The reason is optional and accepts up to 250 characters. It is kept with the record for your own audit, and is never shown to the comment's author. The Console confirms with "Comment has been declined".

    Declining cannot be undone, and a declined comment cannot be restored or re-reviewed.

You cannot review your own comment. If you write a comment in a community where you hold review permission, it publishes immediately rather than entering the queue.

### After approval

An approved comment is an ordinary comment, with one exception: **editing it sends it back for review**. If the author edits an approved comment, it returns to the queue and is hidden again until a moderator approves the new text. This stops a comment being approved on innocuous wording and then changed.

Editing by someone who holds review permission does not send the comment back, and neither does a change made by automated moderation.

Whether an author may edit a comment at all while it is awaiting approval is a network-level setting, separate from this one. It is on by default.

### Who can review

| Role | Can review |
| --- | --- |
| Community moderator with the review-comments permission | Yes, in that community |
| Admin with the manage post and comment permission | Yes, in any community |
| Community member | No — they cannot see held comments at all, apart from their own |

## Moderation Actions

Each comment and reply has a **more options menu** (⋮) with actions tailored to the item. The wording adjusts depending on whether it is a top-level comment or a nested reply.

  <img src="/images/analytics-and-moderation/console/comments-comment-action-menu.png" alt="Comment action menu" />

    **Flag comment** / **Flag reply** — mark content for review. Also available via the flag button next to the more options menu.
    **Edit comment** / **Edit reply** — modify the text content of the selected comment or reply.
    **Copy comment ID** / **Copy reply ID** — copy the unique identifier for reference or internal tracking.
    **Delete this comment** / **Delete this reply** — permanently remove the content. This action is immediate and cannot be undone. Shown in red as a warning.

## Replying & Engagement

The comment panel includes a **comment bar** at the bottom where you can select your identity, type your message, and send.


  <img src="/images/analytics-and-moderation/console/comments-identity-selector.png" alt="Identity selector dropdown" />

### Identity Usage

    Found under the **MYSELF** section. Shows your admin name and photo. Use for routine clarifications, community encouragement, and light moderation nudges.
    Found under the **BRAND** section, marked with a verified badge. Use for formal statements, policy clarifications, resolution confirmations, and official announcements.
    You can switch your identity at any time from the comment bar. Avoid switching identities mid-thread unless you need to escalate the tone (e.g., from a casual response to a formal resolution). Always check which identity is selected before sending.


## Quality & Tone Guidelines


## Monitoring & Metrics

Track:
- Comment volume per high-traffic posts
- Reaction-to-reply ratio (engagement depth)
- Flag rate (flags per 100 comments)
- Response latency (time to first moderator/admin reply)
- Recurring offenders (repeat policy friction)


## Best Practices

    - Review high-activity posts at scheduled intervals.
    - Prioritize flagged + high-engagement threads.
    - Batch moderation actions to reduce context switching.
    - Apply deletion criteria uniformly.
    - Use saved internal templates for common responses (if available).
    - Avoid over-moderating constructive critique.
    - Encourage positive contributors with timely acknowledgment.
    - Address misinformation early with factual, sourced replies.
    - Track topics generating recurring friction for potential policy updates.
    - Escalate threats, self-harm, or legal incidents per protocol.
    - Archive (externally) severe violation context before deletion.
    - Document patterns leading to account-level enforcement.

## Troubleshooting

| Issue | Likely Cause | Resolution |
|-------|--------------|------------|
| Comment not appearing | Network delay / stale view | Refresh thread; confirm submission |
| Cannot switch to Brand | Brand not configured / permission | Configure Brand or adjust role |
| Reply posted under wrong identity | Identity not re-selected | Verify identity before sending |
| Flag won’t clear | Insufficient permission / state change | Confirm role & refresh thread |
| High duplicate spam | Automated/bot activity | Apply broader anti-spam measures / escalate |
| Reactions not updating | Cached metrics | Refresh or wait for sync cycle |
| Deleted comment inquiries | User confusion | Provide neutral explanation referencing guidelines |

## Quick Reference


## Next Steps

---

### [User Insights](https://learn.social.plus/analytics-and-moderation/console/user-and-content-management/user-insights)

> Identify and understand your most valuable community members through automated scoring of contribution level and content quality

Discover who's truly driving value in your community with intelligent scoring that goes beyond activity metrics. This feature automatically evaluates user impact based on contribution frequency and content quality, helping you identify top performers, rising stars, and users who need support.

    Surface top contributors instantly

    Measure quality, not just quantity

    Find specific user segments fast

    Prioritize by performance level

    Recognize valuable members

    Guide low performers to improve

## Overview

Community managers face a fundamental challenge: identifying who truly adds value versus who just adds noise. High activity doesn't always mean high impact. A user rapidly posting low-quality content creates volume without value, while thoughtful contributors creating insightful posts may stay hidden in the metrics.

This feature solves that problem with two intelligent scoring systems:

- **Contribution Level**: Transparent points-based scoring that rewards meaningful actions (posts, comments, reactions)
- **Content Quality Level**: Average quality score of all user-generated posts

Together, these scores provide a complete picture of each user's impact, helping you make data-driven decisions about recognition, moderation, and community growth.

## Key Benefits

    Move beyond gut instinct with objective, automated scoring that scales with your community

    Instantly surface top performers or users needing attention with smart filters and sorting

    Understand who drives real value, reward excellence, and build stronger communities

    Clear, explainable metrics with tooltips showing exactly how scores are calculated

## Accessing User Insights

    Sidebar → Users → Manage Users

    Each user displays their Contribution Level and Content Quality Level as clear, color-coded labels

    Use the filter dropdowns to focus on specific contribution or quality levels, or filter by [tags](/analytics-and-moderation/console/user-and-content-management/tag-management) to narrow down specific user segments

    Click column headers to sort by contribution or quality, finding top or low performers instantly

    Click any user to open their User History panel and see detailed activity supporting the scores

## Understanding Contribution Levels

Contribution Level measures **how actively** a user participates in your community through posts, comments, and reactions. It's calculated using a transparent points-based system over the last 30 days.

### Scoring System

    Each action earns points based on effort and impact:
    - **Create a post**: 10 points
    - **Write a comment**: 5 points
    - **Add a reaction**: 1 point

    Deleted posts and comments are automatically excluded from scoring to ensure accuracy.

    Points accumulate to determine your contribution level:

    | Label | Points Range | Meaning |
    |-------|--------------|---------|
    | **Very High** | 501+ points | Power contributor driving significant engagement |
    | **High** | 201-500 points | Active contributor with consistent participation |
    | **Medium** | 51-200 points | Regular contributor with steady activity |
    | **Low** | 1-50 points | Emerging contributor, just getting started |
    | **None** | 0 points | No contribution activity in the last 30 days |

    **Pro Tip**: The 30-day rolling window means contribution levels naturally reflect current engagement, not historical activity.

    Enterprise customers can adjust point weights via API to match your community's unique dynamics:

    - Emphasize posts if you value original content creation
    - Increase comment weights to reward discussion participation
    - Adjust reaction values if engagement style differs

    Contact your account manager to configure custom weighting for your application.

## Understanding Content Quality Levels

Content Quality Level measures **how well** a user creates content, based on the average quality score of their posts. This helps identify users who consistently produce valuable, well-structured content versus those posting spam or low-effort material.

### Quality Assessment

    Content Quality is determined by:

    1. **Individual Post Scores**: Each post receives a quality score (based on AI content moderation and community signals)
    2. **User Average**: The user's Content Quality Level is the average of all their post scores
    3. **Active Posts Only**: Deleted posts are excluded from the calculation

    Only posts are evaluated for quality—comments and reactions don't factor into this score. This focuses the metric on substantive content creation.

    Quality scores map to clear, intuitive labels:

    | Label | Description | Typical Characteristics |
    |-------|-------------|-------------------------|
    | **Excellent** | Highest quality content | Insightful, well-structured, valuable posts |
    | **Good** | Above-average quality | Solid content with clear value |
    | **Fair** | Acceptable quality | Adequate posts, room for improvement |
    | **Weak** | Below-average quality | Low-effort or problematic content |
    | **Broken** | Violates community standards | Spam, inappropriate, or harmful content |
    | **No Posts** | User hasn't created posts | New users or comment-only participants |


## Using Insights in Manage Users

### Display and Tooltips

Both Contribution Level and Content Quality Level are displayed prominently on:

- **Manage Users Page**: See labels for all users at a glance
- **User History Panel**: View scores when investigating individual users

**Hover for Details**: Hovering over any label shows a tooltip explaining:
- How the score is calculated in general
- The specific threshold or range for that label
- What the label means for user behavior

### Sorting Capabilities

Click column headers to sort the user list and quickly identify specific segments:

    **Two sorting options**:
    - **Highest First**: Very High → High → Medium → Low → None (identify top contributors)
    - **Lowest First**: None → Low → Medium → High → Very High (find inactive or low-engagement users)

    Use "Lowest First" to identify users who may be disengaging or need onboarding support.

    **Two sorting options**:
    - **Highest First**: Excellent → Good → Fair → Weak → Broken → No Posts (surface quality creators)
    - **Lowest First**: Broken → Weak → Fair → Good → Excellent → No Posts (flag problem content)

    "Lowest First" quality sorting is critical for moderation—it surfaces users creating problematic content.

    When multiple users have the same score, they're sorted by **Last Created Date** (most recent first) for consistent, predictable ordering

    Sorting applies to the **full result set**, not just the current page. This ensures accurate top/bottom rankings across your entire user base.

### Advanced Filtering

Focus on specific user segments by filtering on Contribution Level or Content Quality Level—or both together:

    Select a single contribution level to view only users at that engagement tier:
    - **Very High** (🔥): Your power users
    - **High** (💪): Strong contributors
    - **Medium** (⚡): Regular participants
    - **Low** (🌱): Emerging members
    - **None** (👻): Inactive users

    **Example Use Cases**:
    - Filter for "Very High" to identify users for a rewards program
    - Filter for "None" to find disengaged users for re-engagement campaigns

    Select a single quality level to view only users creating content at that standard:
    - **Excellent** (✅): Top-quality creators
    - **Good** (👍): Above-average contributors
    - **Fair** (😐): Acceptable content
    - **Weak** (👎): Below-average quality
    - **Broken** (🚫): Policy violations
    - **No Posts** (📝): Non-posting users

    **Example Use Cases**:
    - Filter for "Excellent" to identify content for featured sections
    - Filter for "Broken" to review users for potential bans

    Apply both filters simultaneously to find precise user segments:
    - **High Contribution + Excellent Quality**: Your most valuable members
    - **Very High Contribution + Weak Quality**: High-volume, low-value posters (potential spam)
    - **Low Contribution + Good Quality**: Rising stars with potential
    - **None Contribution + No Posts**: Completely inactive users

    Filters work together using AND logic: results must match BOTH the selected contribution level AND content quality level.

    **Important**: Contribution and Quality filters cannot be combined with:
    - User status filters (Flagged / Non-Flagged)
    - Search by user ID or name

    If you need to search for a specific user, apply the search first, then use insights on the User History panel.

    If no users match your selected filters, you'll see a clear empty state message guiding you to adjust your criteria.

## Strategic Use Cases

    **Goal**: Reward top contributors

    **Workflow**:
    1. Sort by Contribution Level (Highest First)
    2. Filter for Content Quality = "Excellent" or "Good"
    3. Review top 10-50 users
    4. Award badges, privileges, or recognition

    **Impact**: Reinforce positive behavior, increase retention of valuable members

    **Goal**: Identify problematic users

    **Workflow**:
    1. Sort by Content Quality (Lowest First)
    2. Filter for Content Quality = "Broken" or "Weak"
    3. Review flagged content in User History
    4. Take moderation action (warn, ban, remove content)

    **Impact**: Proactively address policy violations, maintain community health

    **Goal**: Find emerging contributors to nurture

    **Workflow**:
    1. Filter for Contribution Level = "Medium" or "Low"
    2. Filter for Content Quality = "Excellent" or "Good"
    3. Engage these users (invite to programs, feature content)
    4. Track progression over time

    **Impact**: Develop future power users, increase engagement

    **Goal**: Bring back inactive valuable users

    **Workflow**:
    1. Filter for Contribution Level = "None"
    2. Cross-reference historical data (if available) for formerly active users
    3. Targeted outreach or incentives

    **Impact**: Reduce churn, revive dormant community members

    **Goal**: Identify high-volume, low-quality posters

    **Workflow**:
    1. Filter for Contribution Level = "Very High" or "High"
    2. Filter for Content Quality = "Weak" or "Broken"
    3. Review post patterns for spam
    4. Take enforcement action

    **Impact**: Reduce noise, maintain content standards

## Best Practices

    Establish a consistent schedule for reviewing user insights:
    - **Weekly**: Check for new "Broken" quality users requiring immediate action
    - **Bi-weekly**: Identify top contributors for recognition
    - **Monthly**: Analyze trends (are quality scores improving? Is contribution concentrated?)
    - **Quarterly**: Review overall community health and adjust strategies

    Set calendar reminders for these reviews to maintain consistency and catch issues early.

    User insights are most powerful when combined with:
    - **User History**: See the specific content behind the scores
    - **Analytics Dashboard**: Track trends over time
    - **Moderation Feed**: Cross-reference with flagged content
    - **Community Engagement Metrics**: Understand context of scores

    Don't rely on scores alone—investigate the underlying behavior.

    Insights only create value when they drive action:
    - **Reward**: Create recognition programs for top performers
    - **Moderate**: Address low-quality content creators promptly
    - **Engage**: Reach out to promising mid-tier contributors
    - **Support**: Provide resources to help users improve
    - **Adjust**: If scores don't match expectations, review community guidelines or score weights

    Scores provide objective data, but context matters:
    - New communities may have many "Low" contributors still finding their voice
    - Niche communities may naturally have lower overall activity
    - Seasonal trends may affect contribution levels
    - Content quality standards vary by community type

    Use scores as a starting point, not the final word.

    Consider sharing how contribution and quality are measured:
    - Include scoring criteria in community guidelines
    - Explain what behaviors earn points
    - Set clear content quality standards
    - Show users their own scores (if your app supports it)

    Transparency helps users understand how to contribute meaningfully.

## Metrics to Monitor

Track these key indicators to understand and optimize your community health:

| Metric | What It Tells You | Action Trigger |
|--------|-------------------|----------------|
| **Distribution of Contribution Levels** | Engagement health across tiers | High concentration in "None" → improve onboarding |
| **% Users with "Excellent" Quality** | Content quality baseline | Low % → review guidelines, improve education |
| **Very High + Broken Users** | Potential spam or abuse | Any occurrence → immediate investigation |
| **Low/None + Excellent Users** | Untapped potential | Rising count → nurture these emerging stars |
| **Trend: Contribution Levels** | Growing or shrinking engagement | Declining high levels → investigate causes |
| **Trend: Quality Levels** | Improving or degrading content | Degrading quality → strengthen moderation |
| **Top 10% Contributor Concentration** | Community dependence risk | Too concentrated → diversify engagement |
| **Broken Quality Rate** | Moderation effectiveness | Rising rate → review moderation processes |

**Benchmarking**: Compare your metrics month-over-month and against similar communities to identify trends and set realistic goals.

## Troubleshooting

    **Symptoms**: User score doesn't match expected behavior

    **Possible Causes**:
    - Score reflects last 30 days only (not historical activity)
    - Deleted content excluded from calculation
    - Recent activity hasn't updated yet (allow time for sync)

    **Resolution**:
    1. Open User History to verify specific posts/comments
    2. Check date range of activity
    3. Confirm no recent bulk deletions
    4. Allow 5-10 minutes for score recalculation after new activity

    **Symptoms**: Missing contribution or quality label, or error message shown

    **Possible Causes**:
    - Score calculation error (backend issue)
    - User data incomplete or corrupted
    - Permission issue

    **Resolution**:
    1. Refresh the page
    2. Check console for error details (if technical admin)
    3. Verify user account status (active, not deleted)
    4. Contact support if error persists across multiple users

    **Symptoms**: Hovering over label doesn't show explanation

    **Possible Causes**:
    - Browser caching issue
    - Tooltip data not loaded

    **Resolution**:
    1. Refresh page (clear cache if needed)
    2. Try different browser
    3. Verify internet connection
    4. If persistent, report as UI bug

    **Symptoms**: Filter selection doesn't update user list, or shows unexpected results

    **Possible Causes**:
    - Conflict with search or status filters
    - No users match criteria (empty state)
    - Filter sync delay

    **Resolution**:
    1. Clear any search queries or status filters first
    2. Verify filter selection is correct (check dropdown)
    3. Try single filter before combining
    4. Refresh page if results seem stale

    **Symptoms**: Clicking sort doesn't reorder list, or order seems wrong

    **Possible Causes**:
    - Active filters limiting result set
    - Secondary sort (by date) creating confusion
    - Cached sort state

    **Resolution**:
    1. Note that users with same score sort by date
    2. Clear filters and try sorting again
    3. Refresh page to reset sort state
    4. Verify pagination—sorting applies across all pages

    **Symptoms**: Want to use contribution + quality + flagged status together

    **Explanation**: This is a current limitation—insights filters work independently from search and status filters.

    **Workaround**:
    1. Apply contribution + quality filters to narrow list
    2. Manually scan for flagged users (flagged indicator still visible)
    3. OR: Filter for flagged users first, then check scores in User History individually

    This limitation ensures filter logic remains clear and predictable. Future releases may expand filter combinations.

## Integration with Other Features

    Combine insight scores with custom tags for powerful user segmentation — tag high performers, rising stars, or users needing support

    See detailed activity supporting contribution and quality scores

    Review flagged content from low-quality users

    View content in full community context

    Track contribution and quality trends over time

## Key Takeaways

    Contribution + Quality scoring reveals true user value, not just volume of activity

    Clear labels, sorting, and filtering make it easy to find and act on user segments

    Use insights to reward excellence, support growth, moderate effectively, and build healthier communities

    Explainable scoring with tooltips helps you understand and trust the data

---

**Need Help?** If you have questions about interpreting scores or optimizing your community strategy based on user insights, contact your Customer Success Manager or visit our [support](mailto:support@social.plus).

---

### [User Social History](https://learn.social.plus/analytics-and-moderation/console/user-and-content-management/user-social-history)

> Guide for moderators and administrators to assess, moderate, and interpret comprehensive user social activity across the platform

Use this workspace to perform holistic user assessments: engagement footprint, behavioral patterns, moderation history, and community influence. Focus: operational decision support (not developer internals).

    Instant snapshot of stats & flags

    Drill into posts, comments, reactions

    Ban, unban, remove with full context

    Cross-community participation insight

    Chronology of past actions

    Data-driven enforcement

## Accessing User History

    Navigate: Users → Manage Users. You can also filter users by [tags](/analytics-and-moderation/console/user-and-content-management/tag-management) to quickly narrow down specific segments before opening their history.

    Click any user row to open Social History panel.

    Click username from Posts & Comments or Community Member list.

    Begin with headline metrics before deep dive.

## Snapshot Metrics

The profile card at the top of the page has three parts.

**Profile**

- Name, profile creation date, following and follower counts, description, and global role
- The **⋮** menu: assign tags, change global role, profile moderation, [global mute/unmute](/analytics-and-moderation/console/user-and-content-management/global-mute), global ban/unban, and copy user ID

**Moderation**

The left side shows what is active on the user right now. Each row appears only when it has something to show.

| Row | Shows |
| --- | --- |
| **Status** | **Globally banned** and **Muted** badges. Hover over **Muted** to see when the mute expires. |
| **User** | Flags on the user's profile: AI moderation detections (labeled with the detected category), reports from users (grouped by report type, for example "Username (2), Behavior (1)"), and flags from admins (labeled with the reason). |
| **Content** | The number of flagged posts and flagged comments. Click either count to open the Posted or Commented & replied tab filtered to flagged items. |

The right side shows the user's moderation record: the total number of moderation actions, and one badge per action type that has happened, with its count. The action types are community bans, community removals, global bans, global mutes, and profile resets.

A user with no active flags and no moderation actions shows a single line: **Nothing active**, "No flags on the user, posts or comments", and "No moderation actions on record".

Counts update as you act. For example, clearing a flag lowers the flagged count, and banning or muting the user from the **⋮** menu updates the moderation record.

**Activity**

- Totals for posts, comments, reactions, and communities joined
- The user's [Contribution level](/analytics-and-moderation/console/user-and-content-management/user-insights)

Counts of 1,000 or more are shortened, for example 1.2K or 45M. Hover over a shortened count to see the exact number.

{/* Removed missing image: User Statistics Panel */}

    Filter by feed (User / Community), status (Flagged, Non-Flagged, Deleted), sort by Created Date / Last Activity. Action: delete content, clear flags. Provides separate totals for posts vs comments & replies.
    View all reactions (posts & comments) from Nov 28, 2024 onward. Filter by Community feed vs User feed. Sort by Reaction Date. Inspect target content, copy IDs, or remove underlying content if policy violated.
    Lists joined (active/deleted), left, banned, removed (tracking removed state starting Dec 19, 2024). Shows per-community counts (posts / comments / reactions). Actions: community ban, unban, remove. Assess spread & influence concentration.
    Chronological log: Ban, [Global Mute](/analytics-and-moderation/console/user-and-content-management/global-mute), Community Ban, Removed (post Dec 19, 2024), plus counts summary. Supports pattern detection (recurring infractions, escalation thresholds).

{/* Removed missing images: Posts List / Comments List / Reactions View / Communities Participation / Moderation History Log */}

## Interpretation Framework

    High comments vs low posts may indicate conversational contributor; high reactions with low authored content may signal passive engager or reaction spam.

    Clustered flags in narrow time windows suggest episodic behavior; distributed flags indicate chronic issues.

    Multiple high-activity communities = broader impact; concentrated activity aids targeted intervention.

    Depending on your moderation policy and the case, you can remove individual content, apply a timed global mute to stop contributions across the network while preserving read access, restrict participation in a community, or globally ban the user to block network access.

## Decision Playbooks

    Minor isolated flags; advise user via response, monitor trend.

    Pattern in 1 community → community ban period, educate, reassess.

    For reports across several communities, review the user's moderation history and consider a global mute to stop further contributions while the case is assessed. Apply a global ban when your moderation policy calls for blocking network access.

    Severe violation (threats, explicit abuse) → immediate global ban \+ document for compliance.

    Declining violation trend post-warning → reduce restrictions; track next 30 days.

## Metrics to Monitor

| Metric                  | Insight                  | Action Trigger                        |
| ----------------------- | ------------------------ | ------------------------------------- |
| Flags / 30 days         | Current behavioral risk  | Sudden spike vs baseline              |
| Flag clearance rate     | Moderator responsiveness | Low clearance → adjust staffing       |
| Communities engaged     | Breadth of influence     | High \+ rising flags → broader review |
| Reaction-to-post ratio  | Engagement style         | Extreme imbalance → review for spam   |
| Ban recurrence interval | Escalation need          | Short intervals → stronger sanction   |

## Best Practices

    - Start with snapshot metrics before deep scroll.
    - Correlate flags with content type & community.
    - Validate if spikes align with platform events (launches, campaigns).
    - Reference prior actions to avoid double-penalizing.
    - Apply same thresholds across communities.
    - Document rationale for escalations externally when required.
    - Identify positive contributors for recognition programs.
    - Track disengagement after sanctions (potential churn risk).
    - Use distribution of contributions to guide community staffing.

## Troubleshooting

| Issue                               | Likely Cause                        | Resolution                                    |
| ----------------------------------- | ----------------------------------- | --------------------------------------------- |
| Missing reactions pre Nov 28 2024   | Historical limit                    | Data collection started then; no retro import |
| Removed not showing pre Dec 19 2024 | Feature availability start          | Only tracked from release date                |
| Flags count mismatch                | Recently cleared / delayed sync     | Refresh or wait sync cycle                    |
| Cannot change global role           | Permission scope lacking            | Adjust admin role privileges                  |
| Ban option disabled                 | Already globally banned             | Unban first to reapply variant action         |
| Mute option unavailable             | Brand account, or insufficient role | Brand accounts cannot be globally muted       |
| Community missing from list         | Deleted & purged / permission scope | Confirm retention policy / scope              |

## Next Steps

    Organize users with custom tags for segmentation, filtering, and streamlined management

    Review content in context

    Strengthen enforcement workflow

    Track platform health

    Manage broader user set

---

### [Moderation Feed](https://learn.social.plus/analytics-and-moderation/console/user-and-content-management/mod-feed)

> Central workspace for reviewing, filtering, actioning, and auditing flagged posts, comments, messages, and user profiles across the platform

<iframe width="720" height="405" src="https://www.youtube.com/embed/uJ_i8utLnBE?si=6Js8nkLmmmHbYF6Y" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  Use the Moderation Feed to triage all flagged content (posts, comments, messages) and flagged user profiles in one place. Designed for speed, consistency, and auditability. This guide focuses on operational workflows (not developer implementation).

    Identify highest-risk flagged items

    Narrow by feed, report source, type, reason, tags

    Delete or clear flags confidently

    Review action history & moderator attribution

    Track moderation throughput & gaps

    Distribute workload across team

## Access

    Sidebar → Moderation → Moderation Feed.

    Start in To Review for active queue; Reviewed for audit.

    Refine by feed type, report source, content type, report reason, tags.

    Delete violations; clear validly resolved flags.

## Interface Structure

    Active flagged content requiring human decision. Split into Posts & Comments, Messages, and Users categories with tailored filters.

    Historical ledger of resolved items (deleted or flags cleared) with moderator name, action, timestamp, and additional filters for attribution and action type.

## To Review: Posts & Comments

Key elements:

- Total flagged count
- Card list: author, timestamp, content preview, context (community / user feed)
- Thread context for comments (view parent \+ siblings)
- AI mod reasons \+ user report reasons
- Child endangerment is listed first among the user report reasons, even when it has fewer reports
- Reporter count & last flag date
- Report reason details: select any report reason to see who reported the item, when, and the detail they added

Actions:

- Delete (immediate removal)
- Clear flag (removes from queue). When the item has Child endangerment reports, the confirm dialog says how many reports clearing removes.

{/* Removed missing image: Flagged Posts & Comments */}

## To Review: Messages

Key elements:

- Total flagged messages
- Sender, timestamp, content preview
- Channel context (Community / Live / Broadcast)
- AI mod reasons \+ user report reasons
- Child endangerment is listed first among the user report reasons, even when it has fewer reports
- Reporter count & last flag date

Actions:

- Delete message
- Clear flag. When the message has Child endangerment reports, the confirm dialog says how many reports clearing removes.

{/* Removed missing image: Flagged Messages */}

## To Review: Users

Flagged user profiles, from AI moderation and from user reports. Find a profile with the **Search by user ID or name** box (at least 3 characters). See [AI User Profile Moderation](/analytics-and-moderation/console/ai-user-profile-moderation) for the profile card, the available actions, and how reports are grouped.

## Filtering & Sorting

    - All feeds
    - Community feed
    - User feed
    - Posts
    - Comments & replies
    - Attachments: Photos / Videos / Files
    - All Channels
    - Community channel
    - Live channel
    - Broadcast channel
    - Text
    - Photo
    - Video
    - File
    - Audio
    Show items by who flagged them. Available on Posts & Comments and Users.
    - All sources
    - User reports: items reported by users
    - AI moderation: items flagged by AI moderation
    - Report reasons (multi-select)
    - Tags (multi-select)
    - Report type (To Review only): **Profile** (Display name, Description, Profile photo) and **Behavior**. An item matches if it was reported for any selected type.
    - Report reasons (To Review only): shows users with a **Behavior** report for any selected reason, for example Child endangerment.
    - Tags: search for and select one or more user tags.
    - Last flag date
    - Flag count
    - Created date
      Order: Latest first / Oldest first
    - Reviewer (select up to 10), on Posts & Comments and Users
    - Moderation Action: Deleted / Flag Cleared
    - Sort: Moderation Date / Created Date

{/* Removed missing images: Feed Filters / Advanced Content Filters / Report Reason Filter / Sorting Controls / Reviewed Moderation Details / Reviewed Action Card / Moderator Filter / Moderation Action Filter / Reviewed Sorting */}

## Review Workflow Examples

    Filter by report reasons (e.g., abuse, threats) → Sort by Flag count → Delete violations → Clear false positives.

    Report source → AI moderation → Use AI mod reasons to pre-group similar infractions → Bulk evaluate for consistency.

    Advanced Filter → Attachments: Videos / Files → Prioritize for manual safety review.

    Sort by Oldest first → Work sequentially → Move to Latest first for fresh queue scan.

    Reviewed tab → Filter by Reviewer → Spot consistency gaps.

## Decision Criteria

    - Delete when content violates policy & removal improves safety.
    - Clear flag when content is compliant or already addressed contextually.
    Higher counts = urgency, but still verify for mass-report brigading.

    Always open parent thread for comments before deletion to avoid losing conversational coherence.

    Prioritize video & file attachments for manual verification if policy sensitive.

## Metrics & Monitoring

| Metric                           | Insight                          | Action                                            |
| -------------------------------- | -------------------------------- | ------------------------------------------------- |
| Average time to resolution       | Workflow speed                   | Reduce queue switching if slow                    |
| Flags cleared vs deleted ratio   | Content quality baseline         | High delete ratio → education / prevention needed |
| Re-flag rate (same user/content) | Effectiveness of prior decisions | Escalate chronic sources                          |
| Moderator action distribution    | Team load balance                | Reassign to reduce bottlenecks                    |
| False positive rate              | Report accuracy                  | Improve reporting guidelines / AI tuning          |

  Track trends weekly; adjust staffing and escalation policies based on sustained shifts.

## Best Practices

    - Pre-filter by highest risk reasons first.
    - Batch similar content types.
    - Use sorting shifts (Oldest → Latest) to prevent stale backlog.
    - Use Reviewed tab for spot audits.
    - Align on deletion criteria to prevent uneven enforcement.
    - Rotate high-intensity queues to mitigate reviewer fatigue.
    - Validate contextual thread before removal.
    - Confirm multi-report events are genuine (avoid brigading effect).
    - Provide internal rationale for ambiguous decisions.

## Troubleshooting

| Issue                       | Likely Cause                       | Resolution                                |
| --------------------------- | ---------------------------------- | ----------------------------------------- |
| Item reappears after clear  | New flag submitted                 | Re-evaluate & document edge cases         |
| Slow loading filters        | High dataset / network latency     | Narrow filters; retry; check connectivity |
| Moderator missing in filter | No actions recorded in window      | Expand date scope or verify permissions   |
| Wrong sort order            | Cached state                       | Reapply sort or refresh page              |
| AI reason absent            | Model confidence threshold not met | Proceed with manual evaluation            |
| High false positives        | Over-broad report reason usage     | Educate users / refine categories         |

## Next Steps

    Deep dive individual users

    Contextual content review

    Moderate chat spaces

    Track moderation KPIs

---

### [Tag Management](https://learn.social.plus/analytics-and-moderation/console/user-and-content-management/tag-management)

> Create, organize, and assign custom tags to users for streamlined segmentation, filtering, and community management

Organize your user base with custom tags that make segmentation, search, and bulk operations effortless. Tag Management lets you create labeled categories — from "Verified ✅" to "New Joiner" — and assign them to users directly or in bulk, so you can filter, track, and act on specific groups instantly.

    Define custom tags with name, color, and description

    Tag individual users or assign in bulk

    Instantly find users by tag on Manage Users

    Set background and text colors for visual distinction

    Find tags quickly by name or ID

    Edit, delete, and track tag usage over time

## Overview

As your community grows, managing users at scale requires more than just names and roles. Tag Management provides a flexible labeling system that lets you categorize users by any criteria meaningful to your organization — expertise areas, membership tiers, geographic regions, behavioral segments, or program participation.

Tags appear directly in the **Manage Users** table, can be used as filters to narrow down user lists, and are visible on individual tag detail pages where you can see and manage all assigned users at a glance.

### Key Benefits

    Create unlimited tags for any categorization need — roles, regions, programs, behaviors, or custom segments

    Color-coded tags make it easy to spot user groups at a glance in the Manage Users table

    Filter the entire user base by one or more tags (up to 10 simultaneously) to quickly find target groups

    Manage all tags from a single page — create, edit, assign users, and track usage in one place

## Accessing Tag Management

    In the sidebar, click **Users** to expand the submenu

    Click **Tag management** from the expanded Users submenu

    View all existing tags in a sortable table with name, ID, description, user count, and timestamps

## Tag Management List

The main Tag Management page displays all tags in a table with the following columns:

| Column | Description |
|--------|-------------|
| **Tag name** | The display name of the tag (sortable) |
| **Tag ID** | Unique identifier for API and SDK integration |
| **Description** | Optional explanation of the tag's purpose |
| **Users** | Number of users currently assigned to this tag (sortable) |
| **Created at** | Timestamp when the tag was created (sortable) |
| **Last updated** | Timestamp of the most recent modification (sortable) |
| **Action** | Edit and more options (edit tag, copy tag ID, delete) |

<img src="/images/analytics-and-moderation/tag-management-list.png" alt="Tag Management list view showing tags with names, IDs, descriptions, user counts, and timestamps" />

You can **search** for tags by name or ID using the search bar at the top of the table.

## Creating a Tag

    Click the **Create tag** button in the top-right corner of the Tag Management page

    Fill in the tag creation form:
    - **Tag name** (required): A unique name up to 20 characters
    - **Background color**: Hex color code for the tag background (default: `#EBEBEB`)
    - **Text color**: Hex color code for the tag text (default: `#464646`)
    - **Tag description** (optional): A brief explanation up to 140 characters

    Click **Save** to create the tag. It will immediately appear in the Tag Management list and become available for assignment.

<img src="/images/analytics-and-moderation/tag-management-create.png" alt="Create tag form with fields for tag name, background color, text color, and description" />

### Tag Creation Parameters

    **Type:** `string`
    **Required:** Yes
    **Max length:** 20 characters

    The display name shown in the tag list, user profiles, and filter dropdowns. Must be unique across all tags.

    **Examples:** `Verified ✅`, `New Joiner`, `Skincare expert`, `Team A`, `USA`

    **Type:** Hex color code
    **Required:** No
    **Default:** `#EBEBEB`

    The background fill color of the tag badge. Use contrasting colors to make tags visually distinct.

    **Type:** Hex color code
    **Required:** No
    **Default:** `#464646`

    The text color displayed on top of the background. Ensure sufficient contrast for readability.

    **Type:** `string`
    **Required:** No
    **Max length:** 140 characters

    An optional explanation of the tag's purpose. Visible in the tag list table to help team members understand each tag's intent.

    **Example:** *"Recognizes emerging members who consistently contribute and show strong engagement within the community."*

## Editing a Tag

    On the Tag Management list, click the **more options** button (⋯) in the Action column for the tag you want to edit

    Choose **Edit tag** from the dropdown menu

    Update the tag name, colors, or description as needed on the tag detail page

    On the tag detail page, you can also view, search, assign, and remove users directly

<img src="/images/analytics-and-moderation/tag-management-detail.png" alt="Tag detail page showing assigned users with search, assign, and remove capabilities" />

### Tag Detail Page

When you open a tag for editing, the detail page shows:

- **Breadcrumb navigation**: Tag management → Tag name
- **Tag header**: The tag's display name
- **Search bar**: Search assigned users by display name or user ID
- **Assign users button**: Add new users to this tag
- **User table**: Lists all assigned users with a remove action for each
- **Pagination**: Navigate through assigned users (with configurable page size)

## Assigning Users to Tags

You can assign users to tags from the tag detail page:

    Navigate to the tag detail page by clicking **Edit tag** from the more options menu

    Click the **Assign users** button at the top of the user list

    Search for users by display name or user ID, then select the users you want to tag

    The selected users will be immediately assigned to the tag and appear in the user list

### Removing Users from Tags

To remove a user from a tag, click the **remove** button (trash icon) next to the user's name on the tag detail page. The user will be untagged immediately.

## Deleting a Tag

    Click the more options button (⋯) for the tag you want to delete

    Choose **Delete this tag** from the dropdown menu

    A confirmation dialog will appear with the message: *"Deleting this tag will remove it from all users it is currently assigned to. This action cannot be undone."*

    Click **Delete** to permanently remove the tag, or **Cancel** to keep it

<img src="/images/analytics-and-moderation/tag-management-delete.png" alt="Delete tag confirmation dialog warning that the action cannot be undone" />

Deleting a tag is **permanent** and will remove it from all users it is currently assigned to. This action cannot be undone. Make sure you no longer need the tag before confirming deletion.

## Additional Actions

The more options menu (⋯) on each tag row provides:

| Action | Description |
|--------|-------------|
| **Edit tag** | Opens the tag detail page for editing and user management |
| **Copy tag ID** | Copies the tag's unique ID to your clipboard for use in API/SDK integrations |
| **Delete this tag** | Permanently deletes the tag and removes it from all assigned users |

## Filtering Users by Tags

Tags integrate directly into the **Manage Users** page for powerful user filtering:

    Sidebar → Users → Manage Users

    Click the **Select tag** dropdown next to the search bar

    Choose one or more tags from the dropdown (up to 10 tags simultaneously). You can search by tag name or ID within the dropdown.

    The user table updates to show only users matching the selected tags. The **Tag** column displays each user's assigned tags.

<img src="/images/analytics-and-moderation/manage-users-tag-filter.png" alt="Manage Users page with tag filter dropdown showing available tags" />

When a user has multiple tags assigned, the Tag column shows the first tag name along with a **+N** badge indicating the number of additional tags. Hover or click to see all assigned tags.

## Use Cases

    Create tags like "Premium", "VIP", or "Free Tier" to segment users by subscription level and customize their experience

    Tag subject matter experts (e.g., "Skincare expert", "Tech Guru") so community members can identify knowledgeable contributors

    Use location-based tags ("USA", "APAC", "EU") to organize users by region for targeted communication or compliance

    Track users enrolled in specific programs ("Beta Tester", "Ambassador", "New Joiner") for streamlined management

    Combine with User Insights to tag high performers ("🌟 Rising Star+") and track them over time

    Organize internal teams or external partner groups with clear, color-coded labels

## Best Practices

    - Use clear, descriptive tag names that any team member can understand
    - Keep names concise (under 20 characters)
    - Consider using emojis for quick visual identification (e.g., ✅, 🌟, 🏆)
    - Establish a consistent naming convention across your organization

    - Assign distinct colors to different tag categories for quick visual scanning
    - Use high-contrast text/background combinations for readability
    - Reserve bright or alert colors (red, orange) for tags that need attention
    - Keep neutral colors for informational or low-priority tags

    - Regularly review and clean up unused tags
    - Monitor the **Users** count column to identify underused tags
    - Use tag descriptions to document the purpose and criteria for each tag
    - Delete deprecated tags to keep the list manageable

    - Combine tag filtering with Contribution Level and Content Quality filters for powerful segmentation
    - Use the **Copy tag ID** action to integrate tags with your SDK or API workflows
    - Assign tags during user onboarding or milestone events for consistent categorization
    - Leverage tags in conjunction with User Insights to identify and reward top contributors

## Troubleshooting

    **Symptoms:** A newly created tag doesn't show in the Manage Users tag filter

    **Solutions:**
    1. Refresh the Manage Users page
    2. Verify the tag was saved successfully on the Tag Management page
    3. Check that you have the correct permissions to view tags

    **Symptoms:** Delete option is not available or fails

    **Solutions:**
    1. Ensure you have admin-level permissions
    2. Confirm you're clicking the correct more options button (⋯) for the intended tag
    3. Try refreshing the page and attempting again

    **Symptoms:** Tag badge shows unexpected colors

    **Solutions:**
    1. Verify the hex color codes are valid 6-character hex values
    2. Ensure you're using the `#` prefix in the color fields
    3. Edit the tag and re-enter the correct color values

## Related Topics

    Combine tags with contribution and content quality scoring for comprehensive user segmentation

    View detailed activity history for tagged users to support moderation and recognition decisions

    Review flagged content from specific user segments identified through tags

---

### [Admin Access Control](https://learn.social.plus/analytics-and-moderation/console/management/admin-access-control)

> Manage admin roles, permissions, and community assignments to enforce least privilege and secure your console.

Use Admin Access Control in the social.plus Console to manage admin roles, permissions, and community-level access. The goal is to give each admin only the permissions and community scope they need.

Use this page for Console administration workflows such as assigning system roles, creating custom roles, managing admin users, and reviewing high-risk permissions.

## Roles and permissions

The Console uses role-based access control (RBAC) to manage admin privileges. You can assign predefined system roles or create custom roles with a specific permission set.

### System roles

| Role | Recommended use case |
| --- | --- |
| **Admin** | Full access to Console features, including channels, communities, posts, moderation, ads, users, roles, and settings. |
| **Community Manager** | Manages channels, posts, comments, livestreams, and users in assigned communities. Cannot access user management, admin, or settings. |
| **Moderator** | Moderates posts, comments, and users in communities. Cannot create channels, manage categories, post as brand, or access admin or settings. |
| **Content Creator** | Creates posts, comments, stories, and communities. Cannot post as brand, manage users, create ads, or access admin tools or settings. |
| **Brand Partner** | Creates posts, comments, stories, livestreams, and communities. Can post as brand. Cannot access user management, ads, admin, roles, or settings. |
| **Viewer** | Read-only access to most areas, including channels, posts, comments, and communities. Cannot view admin users or settings. |

The **Admin** role grants broad privileges. Assign it cautiously. For most team members, use a more specific role such as **Community Manager** or **Moderator**.

### Permission definitions

| Permission | Allows | Recommended restriction |
| --- | --- | --- |
| Manage Admins | Create admin users, edit profiles, assign roles, and manage community assignments. | New admins should start from a deny-by-default stance until permissions are intentionally assigned. |
| Access Secure Mode | Generate and use elevated Admin Tokens for secure server-to-server API authentication. | Restrict this permission to security or platform engineering teams. Keep it separate from daily operational roles when possible. |
| View-Only Access | View Console pages and data without performing actions. | Use for stakeholders who need visibility into analytics or moderation trends without modification rights. |

## Grant first-time access to a portal admin

Portal access and Console permission are separate. A portal **Super Admin** can open every application's Console automatically, but every other portal admin starts with **no Console role assigned**. Until a role is assigned, clicking **Go to Console** shows a no-permission screen.

A portal **Super Admin** or an existing Console admin can grant access:

    In the Console, go to the **Admin Users** section and click **Manage admin users**.

    Find the portal admin in the list and click **Edit profile & access**.

    Select an appropriate role for the user, then save. Choose the narrowest role that fits their duties. See [System roles](#system-roles).

    The admin can now open the Console for that application from the Portal.

Console roles are deny-by-default: a new portal admin has no permissions until a role is assigned here. Grant access intentionally based on the person's responsibilities.

## Admin user management

### Create an admin

Onboard a new admin, assign a role, and scope access to the right communities.

    Go to the **Admin Users** section and click **Manage admin users**.

    Click **Create new admin**.

    Provide the user's identity and password, then click **Continue**.

    Select an appropriate role, such as **Community Manager**.

    Choose the communities the admin can manage. Leave the default only when the admin should have all-community access and their role permits it.

    Review the summary, then click **Create Admin**.

    Share access guidelines and schedule a 30-day permission review.

All permissions are disabled by default for new admins. Activate permissions intentionally based on the assigned role and community scope.

### Edit an admin

Update an existing admin's role, permissions, or community assignments as responsibilities change.

    Go to the **Admin Users** section and click **Manage admin users**.

    Click **Edit** next to the target admin.

    Update the admin display name or assigned role.

    Add or remove communities from the admin's scope.

    Click **Save Changes** and document the reason in your internal change log.

### Generate an admin token

Create a secure token for server-to-server API authentication.

    Go to the **Admin Users** section and click **Manage admin users**.

    Click the settings icon next to the target admin.

    Click **Generate**, then copy the token for use in API calls.

Treat admin tokens as high-risk credentials. Generate them only for admins who require **Access Secure Mode**.

## Governance and best practices

    Grant the minimum permissions required for each admin to perform their duties. Avoid using the **Admin** role for daily operational work when a narrower role is enough.

    Separate high-risk permissions from operational permissions. For example, an admin with `Access Secure Mode` should not also have broad content moderation duties without a secondary approval process.

    Regularly export the admin list and review each account's permissions and community assignments. Confirm that access still matches the admin's current role and employment status.

    Align admin account management with HR processes. Create accounts during onboarding, adjust access when responsibilities change, and revoke access promptly when someone leaves.

## Troubleshooting

| Issue | Likely cause | Resolution |
| --- | --- | --- |
| "Go to Console" shows no permission | The portal admin has no Console role assigned yet. Portal access is separate from Console RBAC. | A portal Super Admin or existing Console admin assigns them a role via **Admin Users → Manage admin users → Edit profile & access**. See [Grant first-time access to a portal admin](#grant-first-time-access-to-a-portal-admin). |
| Cannot edit another admin | Your role lacks the `Manage Admins` permission. | Escalate to an admin with the required permission. |
| Admin can see all communities | The admin's role has global access, or no communities were specified during assignment. | Edit the admin profile and assign specific communities to restrict access. |
| Unauthorized API token creation | The `Access Secure Mode` permission was over-granted. | Revoke the permission from unauthorized users, rotate exposed tokens, and audit API activity logs. |

## Related topics

    Configure global authentication controls and session policies.

    Learn how to use Admin Tokens for secure API access.

---

### [Events Management](https://learn.social.plus/analytics-and-moderation/console/management/events-management)

> Create, manage, and monitor events in the social.plus Console — including virtual livestreams, external link events, and in-person gatherings

Use Events Management in the social.plus Console to create, organize, and monitor scheduled events across communities. Console events can represent livestreams, external-link virtual events, or in-person gatherings.

Events are created inside communities. Use this page for Console administration workflows such as scheduling, attendee monitoring, and event-detail review.

## Dashboard overview

<img
  src="/images/analytics-and-moderation/console-events-management.png"
  alt="Events Management Dashboard"
/>

The events dashboard lists events with their type, source community, creator, schedule, status, attendee count, and creation time.

| Column | Description |
|--------|-------------|
| **Event title** | The name of the event |
| **Type** | Event type — `Livestream`, `In-person`, or `Virtual` (external link) |
| **Created in** | The community or feed where the event was created |
| **Creator** | The user who created the event |
| **Starts / Ends** | Scheduled start and end date/time |
| **Status** | Current status — `Upcoming`, `Ongoing`, or `Ended` |
| **Attendees** | Number of users who joined or RSVP'd |
| **Created at** | Timestamp of event creation |

You can filter events by **creator** and **status** using the dropdown filters at the top of the page.

## Quick start

    Go to **Console > Events** from the left sidebar navigation.

    Click the **Create event** button in the top-right corner of the events dashboard.

    Choose the target community and the account that will create the event.

    Enter the event name, description, thumbnail, and set the schedule.

    Select whether the event is virtual (livestream or external link) or in-person, and provide the relevant address or link.

    Review all details and click **Create event** to publish.

## Create an event

To create a new event, click the **Create event** button from the events dashboard. The creation form is organized into four sections.

<img
  src="/images/analytics-and-moderation/console-events-create.png"
  alt="Create Event Form"
/>

### Feed and account

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Create to | Dropdown | Yes | Choose where the event will be created. Currently supports **Community** feeds. After selecting Community, choose the specific community from the second dropdown. |
| Create as | Dropdown | Yes | Choose the identity used to create the event. Select **Myself** to use your own admin account, or select a specific user to create the event on their behalf. |

### Event details

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Event thumbnail | Upload | No | Upload a preview image for the event. Use a 16:9 image for consistent display across devices. |
| Event name | Text | Yes | Clear event title shown in event lists and detail pages. Maximum length: 60 characters. |
| Event details | Text | No | Description of what the event is about, what attendees can expect, and any relevant context. Maximum length: 1,000 characters. |

### Date and time

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Timezone | Dropdown | Yes | Timezone for the event schedule. Defaults to the browser locale. |
| Starts on | Date and time picker | Yes | Date and time when the event begins. |
| Ends on | Date and time picker | Yes | Date and time when the event ends. Must be after the start time. |

### Event type and address

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Event type | Dropdown | Yes | Select `Virtual` or `In-person`. This selection controls which additional fields are shown. |
| Livestream | Virtual subtype | Conditional | Users join a livestream directly in your app or website. |
| External link | Virtual subtype | Conditional | Users are directed to an external platform. Event URL maximum length: 200 characters. |
| Address | Text | Conditional | Physical location for an in-person event. Maximum length: 100 characters. |

## Event types

    **Virtual event** where users join a live broadcast directly within your app or website. Ideal for webinars, Q&A sessions, and live content.

    **Virtual event** that redirects attendees to an external platform (e.g., Zoom, Google Meet). Provide the event URL during creation.

    **Physical event** at a specified address. Attendees can see the location details and plan to attend in person.

## View event details

Click on any event row in the events list to open its detail page. The detail view provides a comprehensive overview with three tabs.

<img
  src="/images/analytics-and-moderation/console-events-detail.png"
  alt="Event Detail View"
/>

### Activities tab

The **Activities** tab shows all engagement associated with the event, including:

- **Posts** — Content created within the event context
- Engagement metrics and last update timestamps

### Attendees tab

The **Attendees** tab displays a list of users who have joined or RSVP'd to the event, allowing you to monitor participation.

### Details tab

The **Details** tab shows the full event configuration in a read-only format, including:

- Feed and account information (community, creator)
- Event name and description
- Thumbnail image
- Timezone, start date, and end date
- Event type and address/link

<img
  src="/images/analytics-and-moderation/console-events-detail-tab.png"
  alt="Event Details Tab"
/>

## Event status lifecycle

Events automatically transition through statuses based on the current time relative to the scheduled dates:

```mermaid
graph LR
    A[Upcoming] -->|Start time reached| B[Ongoing]
    B -->|End time reached| C[Ended]
```

| Status | Description |
|--------|-------------|
| **Upcoming** | The event has been created but the start time has not yet been reached |
| **Ongoing** | The event is currently active (between start and end times) |
| **Ended** | The event has passed its scheduled end time |

## Filtering and search

Use the filters at the top of the events dashboard to narrow down the event list:

- **Select creator** — Filter events by the user who created them
- **Filter by status** — Show only events with a specific status (`Upcoming`, `Ongoing`, or `Ended`)

The pagination controls at the bottom of the table allow you to navigate through large event lists, with configurable page sizes (default: 10 per page).

## Best practices

    - **Use descriptive titles** — Make event names clear and informative so users can quickly understand the event purpose
    - **Set accurate timezones** — Always verify the timezone matches the intended audience or event location
    - **Add thumbnails** — Events with images attract more attention; use 16:9 ratio for best display
    - **Write detailed descriptions** — Include what attendees can expect, any prerequisites, and relevant links

    - **Create events in relevant communities** — Target the right audience by selecting the appropriate community
    - **Schedule in advance** — Give users enough lead time to plan for attendance
    - **Monitor activities** — Regularly check the Activities tab for engagement and respond to posts
    - **Track attendees** — Use the Attendees tab to understand participation rates

    - **Livestream** — Best for interactive sessions where you want attendees to stay within your platform
    - **External link** — Use when leveraging established conferencing tools (Zoom, Meet, Teams)
    - **In-person** — Provide complete address details so attendees can easily find the venue

## Troubleshooting

    **Symptoms:** The **Create event** button is disabled or creation fails.

    **Solutions**:
    1. Ensure all required fields are filled in (event name, dates, community)
    2. Verify the end date is after the start date
    3. Check that you have the appropriate admin role and permissions
    4. Confirm the selected community exists and is active

    **Symptoms:** A recently created event does not appear in the dashboard.

    **Solutions**:
    1. Clear any active status or creator filters
    2. Refresh the page to fetch the latest data
    3. Check pagination — the event may be on a different page
    4. Verify the event was created successfully (no error messages during creation)

    **Symptoms:** A livestream event shows as **Upcoming** even after the start time.

    **Solutions**:
    1. Verify the timezone is set correctly for the event
    2. Ensure the livestream infrastructure is properly configured
    3. Check with Live Stream Management for stream status
    4. Confirm the event creator has streaming permissions

## Related topics

    Manage live streams with multi-stream support for device-optimized viewing experiences
    Manage communities where events are created and hosted
    Configure admin roles and permissions for event management capabilities

---

### [Live Stream Management (Legacy)](https://learn.social.plus/analytics-and-moderation/console/management/live-stream-management)

> Manage legacy live streams with multi-stream support in the social.plus Console

Use Live Stream Management (Legacy) in the social.plus Console to manage streams created before migration to the room-based live stream architecture. Legacy live streams support parent streams, up to two child feeds, stream status monitoring, post integration, and moderation review.

This page documents the legacy live stream management system. For current room-based streams, use [Live Stream Management](/analytics-and-moderation/console/management/live-stream-management-new).

## Dashboard overview

The legacy live stream dashboard lists parent streams and summarizes status across any child feeds attached to each parent.

<img
  src="/images/analytics-and-moderation/console-live-stream-legacy.png"
  alt="Live Stream Management (Legacy) Dashboard"
/>

| Column | Description | Logic |
| --- | --- | --- |
| **Title** | Parent stream title | Always displays the parent stream title |
| **Creator** | Stream creator | Uses the parent stream creator |
| **Broadcast status** | Current stream state | Unified across the parent stream and child feeds |
| **Duration** | Stream length | Shows the longest completed stream duration |
| **Moderation status** | Content review state | Shows up to five unique status codes |
| **Created at** | Stream creation time | Uses the parent stream creation timestamp |

Multi-stream child feeds are not supported in UIKit. UIKit displays the parent stream only. Use the SDK or API directly for multi-stream selection logic.

Use stream metadata to distinguish parent and child stream purposes, such as `mobile-view` or `desktop-view`. SDK and API integrations can use that metadata to select the best stream for each viewer.

## Quick start

    Set up the main live stream with a title, optional description, and optional thumbnail.

    Add up to two additional feeds for device-specific views, camera angles, or other variants.

    Link the parent stream to a post so audiences can discover and join the live stream.

    Track status, duration, and moderation across the parent stream and child feeds.

## Create a parent stream

A parent stream is the primary live stream and the default feed for the live event.

### Parent stream fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Title | Text | Yes | Clear title for the live stream event. |
| Description | Text | No | Context about the stream or event. |
| Thumbnail | Image upload | No | Preview image for the stream. Recommended for audience engagement. |
| Secure streaming | Toggle | No | Restricts stream access with authentication when enabled. |
| Camera feed name | Text | No | Display name for the parent feed. Defaults to `Main Feed`. Maximum length: 30 characters. |

After creation, the Console generates a unique stream ID. Use this ID to link child streams and create posts. Broadcast setup choices, such as secure streaming and stream relationships, cannot be changed after the stream goes live.

    Go to **Console > Live stream > Live stream (Legacy)**.

    Click **Create live stream**.

    Fill in the title, description, and thumbnail.

    Enable secure streaming if needed and customize the camera feed name.

    Review the details and click **Create** to generate the parent stream.

## Add child streams

Child streams provide additional video feeds under one parent stream. A parent stream can have up to two child streams, for a total of three simultaneous feeds.

### Child stream use cases

    Add a vertical 9:16 feed for mobile viewers.

    Add a horizontal 16:9 feed for desktop and tablet viewers.

    Provide different camera angles for the same event.

    Use the same visual event with different commentary tracks.

### Add a child stream

    Select the parent stream from the legacy live stream dashboard.

    Click **Add Child Stream**. This action is available only when fewer than two child streams exist.

    The child stream inherits the parent title and description.

    Set a camera feed name. The default is `Additional feed 1` or `Additional feed 2`.

    Create the child stream and use its unique stream ID for broadcasting.

| Behavior | Description |
| --- | --- |
| Inherited fields | Child streams inherit title and description from the parent stream. |
| Feed name | Each child stream can have a custom camera feed name. Maximum length: 30 characters. |
| Stream ID | Each child stream receives its own stream ID for independent broadcasting. |
| Moderation | Moderation status is consolidated with the parent stream in the dashboard. |
| Post association | Child streams share the parent stream's post association. |

You can add a maximum of two child streams per parent stream. Plan multi-stream production needs before going live.

## Edit stream details

Update stream details before or during broadcasts when event information changes.

| Stream | Editable fields |
| --- | --- |
| Parent stream | Title, description, thumbnail, and camera feed name |
| Child stream | Inherited title, inherited description, and camera feed name |

## Copy live stream links

The available copy-link action depends on broadcast status.

| Broadcast status | Copy action | Description |
| --- | --- | --- |
| Not started | No copy link button | Link generation begins when the broadcast starts. |
| Ongoing | Copy live stream link | Shares real-time access to the active live stream. |
| Ended | Copy live stream post link | Shares the recorded content and related engagement. |

## Delete child streams

Remove child streams that are no longer needed or were created in error.

    Open the parent stream and locate the child stream to delete.

    Click the delete icon next to the child stream.

    Check the confirmation modal. If the child stream is live, deletion immediately disconnects the stream.

    Confirm to permanently delete the child stream.

Deleting a child stream that is currently broadcasting immediately disconnects that stream. Active viewers lose access.

Parent streams cannot be deleted while they have associated posts or child streams. Remove child streams and unlink posts first.

## Broadcast status

Broadcast status is unified across the parent stream and its child feeds.

| Status | Displayed when | Notes |
| --- | --- | --- |
| Not started | No parent or child stream has started broadcasting. | Initial state after stream creation. |
| Live | At least one parent or child stream is currently broadcasting. | Takes priority over other statuses. |
| Finished | All streams finished, or at least one stream finished while others never started. | Indicates the live event has concluded. |

## Duration

The duration column shows the **longest completed stream** among the parent stream and child feeds.

- Duration is calculated from stream start time to end time.
- Duration appears only after at least one stream has finished.
- If multiple streams have completed, the longest duration is shown.
- Duration remains empty until at least one stream completes.

## Moderation status

Moderation status consolidates content review across the parent stream and child feeds.

| Rule | Description |
| --- | --- |
| Unique statuses | Shows up to five unique status codes across the parent stream and child feeds. |
| Duplicate handling | Hides duplicate status codes from different streams. |
| Severity order | Sorts by severity: red, then yellow, then green. |
| Overflow handling | If more than five unique status codes exist, shows the highest severity codes first. |

Prioritize red status codes first because they indicate critical content that may violate community guidelines or require immediate action.

## Post integration

Create live stream posts that link to parent streams and automatically include associated child streams.

For detailed information about creating and managing posts, see [Posts Management](/analytics-and-moderation/console/social-management/social-management/posts).

When users view a live stream post, SDK or API based client applications can select the best stream based on device type, screen orientation, or custom metadata. UIKit applications display the parent stream only.

Use stream metadata to identify stream purpose. For example, metadata such as `{"deviceType":"mobile","orientation":"vertical"}` can help your application choose the right feed for each viewer.

## API-created streams

Streams created through the API appear in the Console. If the API request does not specify a camera feed name, the Console displays the default feed name. You can edit feed names later in the Console.

## Best practices

    - **Plan ahead**: Decide which devices or production angles need optimized feeds before going live.
    - **Test thoroughly**: Verify every stream is configured before broadcast.
    - **Name clearly**: Use camera feed names such as `Mobile View`, `Desktop View`, or `Camera 2`.
    - **Use metadata**: Add metadata that identifies stream purpose for SDK or API selection logic.
    - **Account for UIKit**: Remember that UIKit displays only the parent stream.

    - **Choose strong thumbnails**: Use engaging, high-quality preview images.
    - **Write clear titles**: Make the event title easy to understand.
    - **Add useful descriptions**: Give viewers context before they join.
    - **Enable secure streaming**: Use secure streaming for private or restricted events.

    - **Watch unified status**: Monitor all feeds from the Console during live events.
    - **Plan bandwidth**: Ensure upload capacity for each simultaneous feed.
    - **Respect child limits**: A parent stream supports up to two child streams.
    - **Review moderation**: Investigate high-severity moderation statuses promptly.

## Troubleshooting

| Issue | Likely cause | Resolution |
| --- | --- | --- |
| Cannot add child stream | Parent already has two child streams | Delete an existing child stream before adding another. |
| Stream not showing as `Live` | Status update delay or broadcaster not actually live | Refresh the page and verify the stream is broadcasting. |
| Cannot delete parent stream | Parent has associated posts or child streams | Remove child streams and unlink posts before deletion. |
| Copy link not available | Broadcast has not started | Start the broadcast before copying the live stream link. |
| Child stream creation fails | Network or permission issue | Verify permissions, check the connection, and retry. |
| Duration not displaying | No stream has completed | Duration appears after at least one stream finishes. |
| Moderation status unclear | Multiple flags exist across streams | Review each stream individually for detailed status. |
| Stream disconnects on deletion | Live child stream was deleted | Avoid deleting child streams during active broadcasts. |
| Feed name too long | Name exceeds 30 characters | Shorten the feed name. |
| Child streams not showing in UIKit | UIKit does not support multi-stream child feeds | Use SDK or API integrations for multi-stream behavior. |
| Cannot identify stream purpose | Missing metadata | Add metadata when creating streams through the SDK or API. |

## Use cases

    Offer a vertical feed for mobile audiences while keeping a horizontal feed for desktop viewers.

    Support multi-camera productions with main-stage and close-up feeds.

    Let client applications choose the best feed for each viewer's device.

    Provide polished desktop viewing while preserving mobile accessibility for remote attendees.

## Technical specifications

| Area | Specification |
| --- | --- |
| Parent streams | Unlimited creation |
| Child streams per parent | Maximum of two |
| Total concurrent feeds | Three: one parent stream and two child streams |
| Camera feed name length | Maximum of 30 characters |
| Status updates | Broadcast status updates in real time; moderation status may require page refresh |
| API-created streams | Appear in Console with default feed names if none are specified |
| UIKit behavior | Displays and interacts with parent streams only |
| Metadata | Custom metadata can identify device type, orientation, camera angle, or stream purpose |

## Related topics

    Manage current room-based live streams.

    Create and manage posts with live stream integration.

    Understand content moderation workflows for live streams.

    Track live stream performance and engagement metrics.

---

### [Live Stream Management](https://learn.social.plus/analytics-and-moderation/console/management/live-stream-management-new)

> Create, manage, and monitor room-based live streams in the social.plus Console, including direct streams, co-streams, product tagging, and content moderation

Use Live Stream Management in the social.plus Console to create, review, and monitor room-based live streams. This page covers the current room-based live stream system, including direct streams, co-streams, product tagging, broadcast status, and moderation review.

This is the current live stream management system. Streams created before migration remain available in [Live Stream Management (Legacy)](/analytics-and-moderation/console/management/live-stream-management).

## Dashboard overview

The live stream dashboard lists room-based streams created after migration to the room-based architecture.

<img
  src="/images/analytics-and-moderation/console-live-stream-management.png"
  alt="Live Stream Management Dashboard"
/>

Live Stream Management shows room-based live streams. For accounts still using legacy streams, streams created before migration remain available under [Live Stream Management (Legacy)](/analytics-and-moderation/console/management/live-stream-management).

| Column | Description |
| --- | --- |
| **Thumbnail** | Preview image of the live stream |
| **Live stream title** | Name of the stream |
| **Live stream type** | Stream type: `Direct stream` or `Co-stream` |
| **Creator** | User who created the stream |
| **Products tagged** | Number of products tagged to the stream |
| **Broadcast status** | Current status: `Not started`, `Live`, `Finished`, or `Terminated` |
| **Duration** | Total broadcast duration, displayed after the stream ends |
| **Moderation** | AI moderation result, such as `Passed` or a flagged category |
| **Created at** | Stream creation timestamp |

Use the **broadcast status** filter at the top of the dashboard to find streams by state.

## Quick start

    Go to **Console > Live stream > Live stream** from the left sidebar navigation.

    Click **Create live stream** in the top-right corner.

    Add the title, optional description, and optional thumbnail.

    Turn on **Enable Live Chat** to let viewers send messages during the broadcast.

    Review the details and click **Create live stream**.

## Create a live stream

To create a new live stream, click **Create live stream** from the dashboard. Streams created from the Console are configured as **direct streams**. Advanced live features, such as co-streaming, are available when starting a stream from your app with the SDK or API.

<img
  src="/images/analytics-and-moderation/console-live-stream-create.png"
  alt="Create Live Stream Form"
/>

### Stream details

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Title | Text | Yes | Clear stream title shown in the dashboard and detail page. Maximum length: 150 characters. |
| Description | Text | No | Context for viewers about what to expect. Maximum length: 500 characters. |
| Thumbnail | Image upload | No | Preview image shown in the dashboard and before broadcast starts. Recommended size: 1280x720. Maximum file size: 2 MB. |
| Enable Live Chat | Toggle | No | Allow viewers to send messages during the stream. Off by default. |

Streams created from the Console are always configured as **direct streams**. To create co-streams or access advanced live features, start the stream from your application using the SDK or API.

### Live chat

Turn on **Enable Live Chat** in the create form to let viewers send messages during the broadcast. The chat becomes available once the live stream starts and has a post attached.

Live chat is off by default. Enable it before creating the stream so viewers can participate in real time once the broadcast goes live.

## Live stream types

| Type | Description | Creation path |
| --- | --- | --- |
| Direct stream | Single-broadcaster stream with one video feed. | Console, SDK, or API |
| Co-stream | Multi-participant stream where multiple broadcasters can stream together. | SDK or API |

## View stream details

Click any stream row to open the stream detail page.

<img
  src="/images/analytics-and-moderation/console-live-stream-detail.png"
  alt="Live Stream Detail View"
/>

The detail page includes stream information, feed details, broadcast information, and moderation results.

| Section | Details |
| --- | --- |
| Stream information | Title, description, thumbnail, live stream type, broadcast status, and stream ID |
| Feed details | Creator, creator ID, and creation timestamp |
| Broadcast info | Started time, ended time, duration, and recorded video playback when available |
| Moderation | Moderation status, flagged categories, and severity indicators |

### Stream actions

- **Edit stream**: Update the title, description, and thumbnail.
- **Delete stream**: Permanently remove the stream.
- **Copy stream ID**: Copy the unique stream identifier.

Deleting a stream is permanent. Associated data, including recordings and moderation history, is removed.

## Broadcast status

| Status | Description |
| --- | --- |
| Not started | The stream has been created, but broadcasting has not begun. |
| Live | The stream is currently broadcasting and viewers can watch in real time. |
| Finished | The broadcast ended normally. Playback and final duration are available when processing completes. |
| Terminated | The stream was forcibly ended, usually because of moderation or policy enforcement. |

## Content moderation

Live streams are automatically reviewed by AI content moderation. Results appear in the dashboard and stream detail page.

| Status | Indicator | Description |
| --- | --- | --- |
| Passed | Green | Stream content passed moderation checks. |
| Violence | Yellow or red | Violent content was detected. Severity can vary. |
| Nudity | Red | Adult or explicit content was detected. |
| Other flags | Varies | Additional content policy violations were detected. |

Prioritize red-flagged streams first because they indicate critical content that may violate community guidelines or require immediate action.

## Product tagging

Live streams support product tagging for shoppable live commerce experiences. The **Products tagged** column shows how many products are associated with each stream.

| Area | Description |
| --- | --- |
| Tag source | Products are tagged to streams through the SDK or API. |
| Console visibility | Tagged products appear on the stream detail page and as a count in the dashboard. |
| Viewer experience | Viewers can browse tagged products during or after the stream. |

## Best practices

    - **Use descriptive titles**: Help viewers find and understand your stream content.
    - **Upload thumbnails**: Use a 1280x720 image when possible.
    - **Add descriptions**: Provide context about what viewers can expect.
    - **Plan ahead**: Create streams in advance and share details before going live.

    - **Monitor broadcast status**: Keep the Console open during live events.
    - **Review moderation flags**: Check flagged streams promptly and take appropriate action.
    - **Use status filters**: Filter by broadcast status to find active or problematic streams.
    - **Track terminated streams**: Investigate terminated streams to understand policy violations.

    - **Tag before going live**: Ensure products are tagged before the broadcast starts.
    - **Limit product count**: Focus on featured items rather than overwhelming viewers.
    - **Update tags post-stream**: Keep product associations current for replay viewers.

## Troubleshooting

| Issue | Likely cause | Resolution |
| --- | --- | --- |
| Cannot create stream | Missing required title field | Enter a stream title. Maximum length: 150 characters. |
| Thumbnail upload fails | Image exceeds 2 MB or uses an unsupported format | Use an image under 2 MB in a supported format such as PNG or JPG. |
| Stream shows `Not started` | Broadcaster has not gone live yet | Wait for the broadcaster to start the stream from the app. |
| Stream terminated unexpectedly | Content moderation flag triggered | Review moderation details on the stream detail page. |
| Products not showing | Product tags have not synced yet | Refresh the page and verify product tagging through the SDK or API. |
| Co-stream not in Console | Co-streams are created from the app | Co-streams created from the app appear in the list automatically. |
| Live chat not available | Stream has not started or has no post attached, or live chat was not enabled | Enable **Live Chat** when creating the stream. Chat becomes available once the broadcast starts and has a post attached. |
| Duration not displaying | Stream has not finished yet | Duration appears after the broadcast ends. |
| Cannot find legacy streams | Legacy streams are in a separate view | Go to **Live stream > Live stream (Legacy)** in the sidebar. |

## Use cases

    Create direct streams with tagged products for real-time shopping experiences during broadcasts.

    Enable multiple participants to broadcast together for interviews, panels, or collaborative content.

    Monitor AI moderation results across all streams to maintain community safety standards.

    Set up and manage scheduled live stream events with preconfigured titles, descriptions, and thumbnails.

## Related topics

    Review and manage content moderation for live stream broadcasts.

    Manage legacy live streams created before migration to room-based architecture.

    Manage products available for tagging in live streams.

---

### [Admin Tokens](https://learn.social.plus/analytics-and-moderation/console/settings/admin-tokens)

> Generate, rotate, and revoke console admin tokens with strong operational governance.

Operational guide to generate, rotate, and revoke admin tokens while minimizing exposure risk.


## Token Basics

| Aspect | Value |
|--------|-------|
| Default Expiry | 1 year (newly generated) |
| Visibility | Shown once at creation dialog |
| Scope | Console administrative API operations |
| Not Available For | Super Admin accounts |


## Generate Token


## Rotation Strategy


## Revoke Token


## Metrics

| Metric | Description | Threshold |
|--------|-------------|-----------|
| Active Tokens | Count of valid admin tokens | Unexpected growth → audit issuance |
| Avg Token Age (days) | Mean age since creation | > 300 → schedule rotations |
| Orphan Tokens | Tokens with no recent usage (≥30d) | >0 → revoke |
| Compromise Incidents | Confirmed leaks | Any >0 → tighten issuance policy |

## Troubleshooting

| Issue | Likely Cause | Fix |
|-------|--------------|-----|
| Cannot generate | Super Admin account | Use general admin account |
| Token lost | Not stored at creation | Generate new token; revoke old if still active |
| Script failing after rotation | Not updated credential | Update secret store & redeploy |
| Revocation error | Username mismatch | Verify exact admin username |


## Related

---

### [Security](https://learn.social.plus/analytics-and-moderation/console/settings/security)

> Enable Secure Mode, manage server & API keys, add mTLS, and compare authentication approaches.

Enable Secure Mode, manage Server & API keys, add mTLS, and compare authentication modes to harden access to social.plus APIs.


## Secure Mode Overview

Without Secure Mode, a client app exchanges API key + userId directly for a long‑lived access token (higher abuse risk). Secure Mode inserts your backend to mint a short‑lived auth token using the Server Key; the client then redeems it for an access token.


## Enable Secure Mode & Generate Server Key


## Authentication Modes


| Mode | Client Secret Exposure | Abuse Risk | Operational Overhead | Recommended Use |
|------|------------------------|-----------|----------------------|-----------------|
| Unsecure | API Key only | High (impersonation) | Low | Prototyping only |
| Secure | None (short auth token) | Low | Medium (backend endpoint) | Standard production |
| Secure + mTLS | None | Lowest | Medium (cert lifecycle) | High compliance / sensitive workloads |

## Key & Token Concepts


## mTLS Certificates


## Governance & Rotation


## Metrics

| Metric | Target | Trigger |
|--------|--------|---------|
| Unauthorized Attempts | 0 | Any → investigate & rotate |
| Server Key Age (days) | < 365 | ≥ 365 → rotate |
| mTLS Coverage (%) | 100% for auth endpoints | &lt;100% → migrate remaining calls |
| Auth Token Failure % | < 2% | Spike → check clocks / code path |
| Cert Expiry Lead (days) | > 30 | < 30 → start renewal |

## Troubleshooting

| Symptom | Cause | Resolution |
|---------|-------|-----------|
| 401 on auth token request | Wrong/rotated Server Key | Update secret & redeploy backend |
| Access token missing | Auth token not supplied | Ensure client sends authToken parameter |
| mTLS handshake fail | Expired or CN mismatch | Renew cert; confirm chain validity |
| High auth failure rate | Clock skew | Sync NTP on servers |
| Sudden unauthorized spike | Key compromise | Rotate Server Key immediately; audit logs |

## Quick Reference


## Related

---

### [Branding](https://learn.social.plus/analytics-and-moderation/console/settings/branding)

> Manage console logo and create a verified brand account for official communications.

Configure console visual identity and manage an official brand account used for verified announcements and engagement.


## Console Logo


## Brand Account

A special account with verification badge for official posts & comments.

### Create Brand Account


### Requirements

| Field | Purpose | Tips |
|-------|---------|------|
| Logo | Avatar identification | Use primary mark; test dark/light modes |
| Brand Name | Display name across posts/comments | Align with public trademark; avoid internal acronyms |

### Usage


### Best Practices


## Metrics

| Metric | Description | Action Trigger |
|--------|-------------|----------------|
| Brand Post Share (%) | Brand posts / total posts | Low reach → schedule consistent cadence |
| Response SLA (mins) | Time to first brand reply (support threads) | Rising → review staffing/access |
| Engagement Rate | Reactions + comments per brand post | Decline → adjust content strategy |
| Misuse Incidents | Unauthorized posts | Any >0 → tighten access |

## Troubleshooting

| Issue | Likely Cause | Resolution |
|-------|--------------|-----------|
| Logo blurry | Low resolution asset | Upload higher-res within recommended ratio |
| Missing badge | Account not created as brand type | Recreate or contact support |
| Duplicate brand voice | Multiple unofficial accounts | Consolidate & communicate official handle |
| Unauthorized post | Credential sharing | Rotate credentials; implement SSO if possible |

## Quick Reference


## Related

---

### [Deep Link & Sharing](https://learn.social.plus/analytics-and-moderation/console/settings/deep-link)

> Manage the URL and deep link structure for shareable content and profile.

Configure domain and URL patterns for content and profile sharing, enabling deep linking into your app.


## Overview

Admins configure URL and deep link patterns for posts, live streams, profiles, and communities via the social.plus console. Once set up, users and managers can copy and share direct links for any of these items—using structures that match their brand. social.plus generates the links and makes them available for sharing, while our customer’s developers implement how these deep links are processed and which screens they open in their app.

## Quick Start


## URL Pattern Configuration

    Enter your primary web domain. This will be the base for all generated web links. For example: `https://myapp.com`
    Enter the path for web and mobile deep links. Use `{postId}` as a placeholder. For example: `/posts/{postId}`
    Enter the path for web and mobile deep links. Use `{livestreamId}` as a placeholder. For example: `/livestreams/{livestreamId}`
    Enter the path for web and mobile deep links. Use `{communityId}` as a placeholder. For example: `/communities/{communityId}`
    Enter the path for web and mobile deep links. Use `{userId}` as a placeholder. For example: `/users/{userId}`

## SDK & UIKit Integration

The URL patterns you configure in the console are stored in the system and accessed by the SDK and UIKit at runtime to generate shareable links.

### SDK Integration

The SDK provides functions to fetch the link patterns stored in the system, allowing you to retrieve the configured URL patterns for each content type programmatically.

**Use the SDK to:**
- Retrieve domain URL and URL patterns for posts, livestreams, communities, and users
- Integrate custom sharing functionality in your app
- Build shareable links dynamically based on your configured patterns

### UIKit Integration

UIKit leverages the SDK to obtain link patterns for each content type from the system. Share buttons appear automatically in the UI once valid link patterns are configured in the console.

**How UIKit sharing works:**

    UIKit fetches the configured URL patterns via SDK when content is displayed
    Share buttons only appear when valid link patterns exist in the system
    When a user clicks the share button, the content ID is applied to the link pattern to generate a complete, shareable URL
    On native platforms (iOS/Android), clicking share triggers the OS's native link sharing behavior

**Important - URL Pattern Usage in UIKit**: UIKit only uses the **Post**, **Community**, and **User** URL patterns. The **Livestream** URL pattern is not used in UIKit because livestreams created in UIKit are implemented as posts. When users share a livestream post, the 'post' content type pattern is used for link generation.

## Best Practices

    While social.plus generates links based on your patterns, you must implement in-app routing. Your app is responsible for handling incoming URLs, navigating to the correct content, and managing access for private items, like prompting non-members to log in.
    Maintain a consistent and predictable URL structure across your application. This improves user experience and makes your links more shareable and understandable.
    For links to private content (e.g., private communities, user-specific content), ensure your app checks user permissions. If the user doesn't have access, redirect them to a login page or a "request access" screen instead of showing an error.

## Troubleshooting

| Symptom | Cause | Resolution |
|---------|-------|------------|
| Links don't open the app | App not configured for deep links | Ensure your iOS (Universal Links) and Android (App Links) projects are correctly configured to handle your domain. |
| Links go to the wrong screen | Incorrect routing logic in app | Review your app's deep link handling code to ensure it correctly parses the URL and navigates to the right destination. |
| 404 errors on shared links | Incorrect domain or pattern | Double-check the Domain URL and URL Patterns in the console settings to ensure they match your website's structure. |

## Related Topics

---

### [Webhooks & Push Notifications Integrations](https://learn.social.plus/analytics-and-moderation/console/settings/integrations)

> Configure webhooks, push notifications, and delivery infrastructure for real-time engagement.

Configure webhooks and push notification infrastructure to stream real-time events and engage users reliably.


## Webhooks


## Push Notifications

Navigate to **Settings → Push notifications** in the console to manage notification settings and certificates.

<img src="/images/console-push-notifications-overview.png" alt="Push notifications overview" />

### Enable Push Notifications

Use the master toggle at the top of the page to enable or disable push notifications for the entire network.


### Certificates

Multiple certificates can be stored per platform (e.g., staging + production), but only **one can be active at a time** per platform/provider.


| Field | Platform Scope | Purpose |
|-------|----------------|---------|
| Certificate Name | All | Internal tracking label |
| Platform | iOS / Android | Target OS |
| Provider (Android) | Android | Firebase Cloud Messaging (FCM) / Baidu Cloud Push |
| Service Account JSON (FCM) | Android | FCM v1 service account credentials |
| .p12 / .p8 Upload | iOS | APNs authentication material |
| Credential Password | iOS | Password for .p12 if set |


### Notification Events

Configure which events trigger push notifications. Events are organized into three tabs:

<img src="/images/console-push-notifications-chat-events.png" alt="Chat events configuration" />

    Chat-related push notification events:

    | Event | Description |
    |-------|-------------|
    | When a new channel is created | Notifies users when a new channel is created |
    | When a user joins a channel | Notifies when a user joins a channel |
    | When a user joins a conversation | Notifies when a user joins a conversation |
    | When there is a new message in the users channel | Notifies on new messages in channels |
    | When there is a new message in the users conversation | Notifies on new messages in conversations |

    Each event has an **Allow** toggle and an **Actions** button to customize the notification message.
    Community events are grouped into subcategories:

    **Post-related events**

    | Event | Description |
    |-------|-------------|
    | When someone creates a new post in the community | New post notification |
    | When someone react to your posts | Reaction notification |
    | When your post has been approved | Moderation approval notification |
    | When there is a post that requires review from you | Moderator review request |

    **Comment-related events**

    | Event | Description |
    |-------|-------------|
    | When someone comments on your posts | Comment notification |
    | When someone replies to your comments | Reply notification |
    | When someone reacts to your comments | Comment reaction notification |
    | When someone comments on your story | Story comment notification |

    **Story-related events**

    | Event | Description |
    |-------|-------------|
    | When someone creates a new story in the community | New story notification |
    | When someone reacts to your story | Story reaction notification |

    **Live stream-related events**

    | Event | Description |
    |-------|-------------|
    | When someone starts a live stream in the community | Community live stream notification |

    **Event-related events**

    | Event | Description |
    |-------|-------------|
    | When an event user marked as 'Going' is about to start | Upcoming event reminder |
    | When an event user marked as 'Going' has started | Event started notification |
    Standalone live stream push notification events:

    | Event | Description |
    |-------|-------------|
    | When someone starts a standalone live stream | Notifies followers about a new standalone live stream |


### Custom Push Message

Click the **Actions** (pencil icon) button next to any event to customize the notification message template. Keep messages concise (&lt;140 chars) and actionable.


## Monitoring & Metrics

| Metric | Description | Trigger |
|--------|-------------|---------|
| Delivery Success % | Successful pushes / total | Drop < 95% → inspect certs & provider status |
| Cert Days to Expiry | Soonest certificate expiry | < 30 days → schedule renewal |
| Event Coverage | Enabled events / intended events | Gap → enable missing categories |
| Webhook Failure Rate | 4xx/5xx responses / total deliveries | > 2% → investigate endpoint health |

## Troubleshooting

| Issue | Likely Cause | Fix |
|-------|--------------|-----|
| No push delivered | Inactive certificate | Activate correct cert in Certificates table |
| Some events silent | Event toggle off | Enable event under the appropriate tab |
| FCM legacy errors | Using deprecated FCM v1 API | Migrate to FCM v1 with service account JSON |
| Webhook 401 errors | Secret mismatch | Regenerate secret and update backend |
| Elevated retries | Endpoint latency | Optimize processing / return 200 quickly |
| Duplicate notifications | Missing idempotency | Track delivery IDs, discard repeats |

## Quick Reference


## Related

---

### [Sponsored Content Overview](https://learn.social.plus/analytics-and-moderation/console/premium-ads/README)

> Monetize your social platform with Sponsored Content - customized ad placements with frequency control

Sponsored Content is **not available** on the Flutter platform. In React Native UIKit, ads appear in the global feed, community feeds, and comment lists.

  Use Sponsored Content to monetize responsibly: configure frequency logic, placements, scoring, and exposure controls while maintaining user experience quality.

**Sponsored Content** is a feature designed to enhance your social network by allowing personalized ad placements. Whether you're promoting personal products or monetizing your platform, Sponsored Content offers versatile tools for various advertising needs. It establishes profitable partnerships and displays ads across your network. For more details, please reach out to our support team.

## Access & Navigation


## Display Modes

    Predictable cadence (e.g., 1 ad every 5 posts). Guarantees minimum visibility even in low-content contexts (at least one ad if some content exists). Avoids empty inventory when content volume is low.

    Enforces temporal pacing (e.g., max 1 ad / 10 minutes). Prevents clustering during rapid scrolling sessions and smooths experience for highly active users.
    - Use Fixed Frequency for stable engagement feeds.<br/>
    - Use Time Window for bursty activity (live events, spikes).<br/>
    - Hybrid strategy: Start with Frequency, switch to Window during campaigns.

## Scoring System

The scoring engine prioritizes ad rotation fairness:


## Placements


## Configuration Workflow


## Performance Metrics

| Metric | Description |
|--------|-------------|
| Clicks | Number of user interactions with the ad |
| Impressions | Total times the ad was displayed |
| Reach | Distinct users who saw the ad |

## Next Steps

---

### [Setting Up Premium Ads](https://learn.social.plus/analytics-and-moderation/console/premium-ads/setting-up-premium-ads)

> Create, configure, edit, and retire Premium Ads and Advertiser Profiles in the Console

<iframe width="720" height="405" src="https://www.youtube.com/embed/B1I4adKLbd0?si=vW3W8-VPNcMEfPFT" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

  This guide walks moderators and marketing administrators through creating ad creatives, configuring placements & scheduling, editing existing ads, and managing advertiser profiles. Focus: operational workflow.

    Build new ad creatives & metadata

    Define start / end windows

    Assign Post • Story • Comment slots

    Update copy, media, CTA

    Control who can publish ads

    Delete expired or invalid ads

## Creation Workflow

    Click Create Ads (ensure Advertiser Profile exists).

    Choose advertiser identity (brand entity).

    Add image (≤30MB) in proper ratio (9:16 Stories / 1:1 Post & Comment).

    Headline, description, optional body text.

    Configure button label \+ destination URL.

    Choose eligible placements (Post / Story / Comment).

    Set required start date & optional end date.

    Confirm preview → submit.

{/* Removed missing images: Create Ads / Ratio Options / Image Guideline / Ads Content / Placement Selection / Scheduling */}

  Only admins can create ads. Restrict creation rights to prevent unauthorized monetization content.

## Media & Copy Guidelines

    - 9:16: Fullscreen vertical, Stories / Reels.
    - 1:1: Square feed & comment surface.
    Images ≤30MB; follow image handling spec for optimization & clarity.

    Headline (concise) → Description (value prop) → Optional body (context / qualifiers).

    Use action verbs, align label with destination (e.g., "Download", "Learn More").

    Ensure tone matches brand profile settings; avoid mismatched capitalization styles.

## Editing Ads

    In Ads list, click Edit on target ad.

    Adjust profile, name, ratio, copy, CTA, placement.

    Verify updated creative & layout.

    Click Save Changes to apply.

{/* Removed missing images: Edit Ad Entry / Edit Form */}

## Deleting Ads

    Click Edit for selected ad.

    Go to bottom of edit screen.

    Click Delete Ad and confirm irreversible removal.

{/* Removed missing images: Access Delete / Delete Confirmation */}

## Advertiser Profiles

  Advertiser Profiles centralize legal identity & branding context used across multiple ads. Editing a profile updates all its associated ads.

    Establish advertiser entity

    Update naming or compliance fields

    Remove unused identity (0 active ads)

### Creating a Profile

    Ads → Settings → Advertiser Profile tab.

    Click Create Profile.

    Enter Display Name & Official / Legal Name.

    Click Save Profile.

{/* Removed missing image: Profile Creation */}

### Editing a Profile

    Ads → Settings → Advertiser Profile.

    Click Edit Profile on target.

    Adjust names / legal identifiers.

    Apply changes; associated ads reflect updates.

  Editing a profile propagates across all linked ads—review large-scale naming shifts carefully.

{/* Removed missing image: Edit Profile */}

### Deleting a Profile

    Ads → Settings → Advertiser Profile.

    Click Edit Profile next to target.

    Ensure 0 active ads linked.

    Click Delete Profile and confirm.

  Profiles with any active or historical active ads in flight cannot be deleted until ads are retired.

## Best Practices

    Retire outdated seasonal creatives promptly; archive for audit if required.

    Avoid overlapping campaigns with identical objectives targeting the same placement—prevents internal competition.

    Use standardized naming (Brand_Campaign_Q#\_Year) for traceability.

    Ensure destination URLs are live, secure (HTTPS), and aligned with label expectation.

    Maintain resolution suitable for largest display; avoid text-heavy imagery.

## Troubleshooting

| Issue                  | Likely Cause                            | Resolution                             |
| ---------------------- | --------------------------------------- | -------------------------------------- |
| Cannot create ad       | Missing advertiser profile / permission | Create profile or adjust role          |
| Image rejected         | Exceeds size / unsupported ratio        | Compress or resize to 9:16 / 1:1       |
| CTA not saving         | Invalid URL format                      | Use full HTTPS URL                     |
| Placement missing      | Not supported for current ratio         | Adjust ratio or choose valid placement |
| Profile delete blocked | Active ads exist                        | Retire or delete linked ads first      |
| Schedule not applying  | Missing start date                      | Set valid start (and optional end)     |

## Quick Reference

    9:16 (Stories) • 1:1 (Feed)

    30MB

    Admins only creation

## Next Steps

    Review monetization strategy

    Measure ad performance

    Align creative identity

    Balance safety & revenue

## Analytics & Moderation — Admin on the go

### [Overview](https://learn.social.plus/analytics-and-moderation/admin-on-the-go/overview)

> The mobile-optimized social.plus Console — review, moderate, and publish content from your phone

**Admin on the go** is the mobile-optimized version of the social.plus Console. It gives moderators the day-to-day content workflows — reviewing posts, clearing flags, approving pending content, editing and publishing — on a phone-sized screen, without waiting to get back to a desktop.

## How it fits with the Console

Admin on the go is not a separate product with its own data or permissions. It reads the same applications, communities, content, and admin roles as the [social.plus Console](/analytics-and-moderation/console/overview) — the same actions, the same permission checks, the same audit trail — made convenient to use on a phone.

Use the Console for configuration, analytics, and advanced administration. Use Admin on the go to handle moderation from your mobile device.

    Approve, decline, flag, and delete straight from your phone — no laptop needed
    Actions are gated by your existing admin role and permissions — nothing is unlocked by moving to mobile
    A web app that runs in your mobile browser — no app store, no build to distribute

## Access

Admin on the go is at [go.social.plus](https://go.social.plus). Sign in with your company email and password, with Google, or with your organisation's SSO — the same credentials you use for the Console. See [Getting Started](/analytics-and-moderation/admin-on-the-go/getting-started) for the full walkthrough.

## What you can do

    The Posts screen is split into three tabs:

    - **Posted** — published posts, newest first, showing author, community, timestamp, content, media, and reaction and comment counts. **Flagged** and **Featured** badges appear on posts that carry them.
    - **Pending** — posts awaiting review in communities that require approval. The tab badge shows how many are waiting, and each post carries **Approve** and **Decline** buttons. Reviewed posts leave the queue immediately, and if another moderator got there first you are told the post has already been reviewed.
    - **Scheduled** — posts queued for a future publish time, each with its scheduled date and a status of **Pending**, **Success**, or **Failed**.

    Tapping a post opens the post detail view with its comments. Tapping media opens a full-screen viewer you can swipe through.
    The three-dots (…) menu on a post opens an action sheet:

    | Action | Required permission |
    | --- | --- |
    | Flag post / Clear flag | Moderate posts & comments |
    | Delete post | Moderate posts & comments |
    | Edit post | Edit posts & comments |
    | Feature globally / Remove featured post | Global featured post |
    | Copy post link | Manage posts & comments |

    Destructive and irreversible actions — deleting, clearing a flag, removing a globally featured post — ask for confirmation first.

    Posts in the **Pending** tab expose **Edit post** only; the remaining actions become available once the post is published.
    The **Comments** tab lists comments across every post and every level, so you can monitor discussion without opening each post one by one.

    - Open a comment to read its reply thread
    - **Flag** or **clear a flag** on a comment or reply
    - **Edit** or **delete** a comment or reply
    - Post a new comment or reply as your personal identity or as a brand
    Beyond moderation, you can publish on behalf of the network:

    - **Create a post** in a community you administer
    - **Schedule a post** for a future date and time
    - **Delete a scheduled post** before it goes live
    - **Browse communities** you administer, filtered by visibility (public, private, official) or searched by name or category

## Admin on the go vs. the Console

| | Admin on the go | Console |
| --- | --- | --- |
| Best for | Reviewing and acting on content away from your desk | Configuration, analytics, and full administration |
| Content moderation | Posts, comments, flags, approvals, featuring | Full moderation suite including chat and livestreams |
| Publishing | Create, edit, and schedule posts | Create, edit, and schedule posts |
| Analytics & reporting | — | [Analytics dashboards](/analytics-and-moderation/console/analytics/overview) and CSV exports |
| Settings & integrations | — | Security, admin tokens, webhooks, branding, premium ads |
| Access | [go.social.plus](https://go.social.plus) | [social.plus Portal](https://portal.amity.co) → **Go to Console** |

New here? Start with [Getting Started](/analytics-and-moderation/admin-on-the-go/getting-started). Anything Admin on the go does not cover is still one sign-in away in the full Console — the two share the same account, the same applications, and the same permissions.

---

### [Getting Started](https://learn.social.plus/analytics-and-moderation/admin-on-the-go/getting-started)

> Sign in to Admin on the go, pick your application, and work your first moderation queue

Admin on the go runs in your mobile browser — there is nothing to install. This guide covers signing in, choosing an application, and finding your way around.

## Prerequisites

Before you start, make sure you have:

- An admin account with access to at least one social.plus application
- A Console role assigned to that account — Admin on the go enforces the same permissions as the Console, so an account with no Console role cannot act on content. See [Admin Access Control](/analytics-and-moderation/console/management/admin-access-control)
- A mobile browser (the interface is built for phone-sized screens)

Portal and Console permissions are separate. If **Go to console** shows a no-permission screen, a Portal Super Admin or an existing Console admin needs to assign you a Console role first.

## Signing in

    Go to [go.social.plus](https://go.social.plus) in your mobile browser.
    Admin on the go supports the same sign-in methods as the Console — see the tabs below.
    After sign-in you land on the applications list. Each card shows the application name and its server region. **Go to console** is disabled for any application that is not active.
    Opening an application takes you straight to its **Content** tab, with **Posts** and **Comments**.

### Sign-in methods

    Enter your company email and password. The **Sign in** button stays disabled until the email is valid and the password is non-empty, and field errors clear as soon as you correct them.
    Tap **Sign in with Google** and complete Google's authentication flow with your company Google account. Cancelling returns you to the sign-in screen with no error.
    Tap **Sign in with SSO** and enter your organisation domain — up to 32 characters, letters and numbers only, no special characters. You are then redirected to your organisation's identity provider.

    If your organisation has exceeded its user limit, or you are not on its whitelist, the screen tells you so and the button stays disabled — contact your organisation's admin.

### Forgot your password

Tap **Forgot your password?** on the sign-in screen, enter your work email, and tap **Reset password**. This follows the same reset flow as the desktop Portal. **Back** returns you to sign-in.

## Finding your way around

    The bar at the top carries the social.plus logo and your avatar. It hides as you scroll down and returns when you scroll back to the top.
    Tap your avatar to see your name, email, role, and the application you are in — plus **Go to Applications** to switch application, and **Sign out**.
    **Posts** (Posted, Pending, Scheduled) and **Comments** — the day-to-day moderation queues. See [What you can do](/analytics-and-moderation/admin-on-the-go/overview#what-you-can-do).
    Browse the communities you administer — scope to all or only your own, filter by visibility, and search by name or category.

## Your first moderation pass

    Open **Posts** → **Pending**. The tab badge shows how many posts are waiting. Read each one and tap **Approve** or **Decline**; the post leaves the queue and the badge decrements immediately.
    On the **Posted** tab, look for posts carrying a **Flagged** badge. Open the three-dots (…) menu to delete the post, or to clear the flag if the report does not hold up.
    Open the **Comments** tab to review comments and replies across every post without opening each post individually.
    Tap your avatar → **Sign out**. Your session is cleared and you return to the sign-in screen.

If your session expires while you are working, you are returned to the sign-in screen — sign in again and you land back on the applications list.

## Next steps

    The full picture of posts, comments, actions, and publishing
    How admin roles and permissions are defined
    Configuration, analytics, and advanced administration on desktop
    Moderation policy and workflows across the platform

## Analytics & Moderation — APIs & Services

### [Overview](https://learn.social.plus/analytics-and-moderation/social+-apis-and-services/README)

> Server-to-server APIs for programmatic administration, moderation, automation, and real-time event processing

![API Dark Pn](/images/API-Dark.png)


Integrate powerful administrative capabilities directly into your applications with social.plus REST APIs. Access the same functionality available in the console programmatically, enabling automated workflows, custom integrations, and advanced community management features.

  **Server-Side Only**: These APIs are designed for server-to-server communication and require admin-level authentication. Never expose admin credentials in client-side applications.

    Admin and user access tokens, secure mode, and API authentication
    Programmatic content moderation, user management, and safety controls
    Access community metrics, user data, and business intelligence programmatically
    Real-time event notifications and automated response systems

## Core API Categories

### **Administrative Functions**

- **User Management**: Create, update, and manage user accounts
- **Content Operations**: Bulk content management and moderation actions
- **Network Configuration**: Application settings and policy management
- **Reporting**: Generate and export analytics data

### **Moderation Automation**

- **Content Review**: Automated flagging and approval workflows
- **User Actions**: Programmatic bans, warnings, and restrictions
- **Policy Enforcement**: Custom rules and violation handling
- **Appeal Processing**: Automated appeal workflows and notifications

### **Analytics & Insights**

- **Usage Metrics**: Access MAU, DAU, and engagement statistics
- **Content Analytics**: Performance data for posts, comments, and media
- **Moderation Reports**: Safety metrics and policy effectiveness data
- **Custom Reporting**: Generate tailored reports for business needs

### **Real-Time Events**

- **Webhook Integration**: Receive real-time notifications for platform events
- **Pre-Hook Events**: Intercept and modify events before processing
- **Custom Workflows**: Build automated response systems and integrations

## Getting Started

    Generate an admin access token from your console under **Settings** → **Admin Users**
    Select between admin tokens for server operations or user tokens for user-context actions
    Set up your server environment with proper authentication and regional endpoints
    Start with simple API calls to verify connectivity and permissions

## Authentication Methods

    ### Admin API Access Token

    For server-to-server API calls with full administrative privileges:

        Navigate to Console → **Settings** → **Security** → **Admin API Access Token**
        Set appropriate scopes and expiration for your integration
        Store the token securely and rotate regularly
      Admin tokens provide full access to your application. Never expose them in client-side code or public repositories.
```bash
curl -X 'GET' \
  'https://apix.<region>.amity.co/api/v3/users' \
  -H 'accept: application/json' \
  -H 'x-admin-token: <your-admin-token>'
```
    ### User Access Token

    For user-context API calls with scoped permissions:

        Use your server key to generate an authentication token for the user
        Register a session using the authentication token
        Use the returned access token for API calls
```bash
# 1. Get authentication token with server key
curl -X 'GET' \
  'https://apix.<region>.amity.co/api/v3/authentication/token?userId=<userId>' \
  -H 'x-server-key: <your-server-key>'

# 2. Create user session
curl -X 'POST' \
  'https://apix.<region>.amity.co/api/v3/sessions' \
  -H 'x-api-key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "<userId>",
    "deviceId": "server",
    "authToken": "<authentication-token>"
  }'
```

      User Access tokens are valid for 30 days but will be invalidated if a different user ID registers with the same device.
    ### Secure Mode Authentication

    Enhanced security with server key authentication:

    - **Additional Security Layer**: Requires server-level authentication
    - **Token Generation**: Server key needed to generate user tokens
    - **Enterprise Feature**: Available for production deployments

```javascript
// Generate user token in secure mode
const response = await fetch(`https://apix.${region}.amity.co/api/v3/authentication/token`, {
  method: 'GET',
  headers: {
    'x-server-key': process.env.AMITY_SERVER_KEY
  },
  params: {
    userId: 'user123'
  }
});
```

## Token Management

    - **Secure Storage**: Use environment variables or secure key management systems
    - **Regular Rotation**: Implement automated token rotation procedures
    - **Scope Limitation**: Use minimum required permissions for each token
    - **Monitoring**: Log and monitor API usage patterns and anomalies
    - **Revocation**: Implement emergency token revocation procedures
    - **HTTPS Only**: Always use HTTPS for API communications
    - **IP Whitelisting**: Implement IP restrictions where possible
    **Validate Tokens**

```javascript
const validateToken = async (token) => {
  try {
    const response = await fetch('https://apix.region.amity.co/api/v3/users/me', {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    return response.ok;
  } catch (error) {
    return false;
  }
};
```

    **Revoke User Access Tokens**
    Admin tokens can revoke user access tokens using the Revoke API:

```bash
curl -X DELETE "https://apix.region.amity.co/api/v4/sessions" \
  -H "x-admin-token: YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user123"}'
```
    **Rate Limiting**

    - Respect API rate limits to avoid throttling
    - Implement exponential backoff for retry logic
    - Use batch operations when available for efficiency
    - Cache responses appropriately to reduce API calls

    **Error Handling**

    - Implement comprehensive error handling for all API calls
    - Log errors with sufficient detail for debugging
    - Provide graceful degradation when APIs are unavailable
    - Monitor API response times and success rates

## Common Use Cases

    **Content Monitoring**

    - Set up automated scanning for new content
    - Apply custom moderation rules based on community guidelines
    - Integrate with external moderation services
    - Handle bulk content operations efficiently

    **User Behavior Management**

    - Automatically flag suspicious user patterns
    - Implement graduated response systems
    - Handle coordinated abuse or spam campaigns
    - Maintain audit trails for compliance
    **Custom Analytics**

    - Export data to business intelligence tools
    - Create custom reports for stakeholders
    - Track KPIs specific to your business model
    - Integrate with existing analytics platforms

    **Growth Analysis**

    - Monitor user acquisition and retention
    - Track feature adoption and usage patterns
    - Analyze community health indicators
    - Generate executive dashboards
    **User Lifecycle Management**

    - Automate user onboarding processes
    - Handle account verification and upgrades
    - Manage subscription and billing integrations
    - Implement custom user journey flows

    **Content Operations**

    - Bulk import/export of content
    - Automated content promotion and featuring
    - Cross-platform content synchronization
    - Content archival and cleanup processes
    **Webhook Automation**

    - Receive real-time notifications for platform events
    - Trigger automated workflows based on user actions
    - Integrate with external systems and services
    - Build custom notification and alert systems

    **Event Processing**

    - Process content creation, modification, and deletion events
    - Handle user registration, login, and activity events
    - Implement custom business logic with pre-hook events
    - Create audit trails and compliance reporting

## Regional Endpoints

Different regions have specific API endpoints for optimal performance:

| Region        | API Endpoint                           |
| ------------- | -------------------------------------- |
| **US East**   | `https://apix.us.amity.co`      |
| **Europe**    | `https://apix.eu.amity.co`   |
| **Singapore** | `https://apix.sg.amity.co` |

  **Performance Optimization**: Always use the regional endpoint closest to your server infrastructure for best performance and lowest latency.


## Next Steps

    Complete API documentation with endpoints and examples
    Configure real-time event notifications and automated responses
    Intercept and modify events before they're processed
    Generate comprehensive user activity and engagement reports

## Related Services

    Configure platform-wide settings and policies
    Generate comprehensive user activity and engagement reports

  **Production Considerations**: Test all API integrations thoroughly in a development environment before deploying to production. Monitor API usage and implement proper error handling and logging.

---

  Need help implementing a specific API integration? Check our [developer community](https://community.amity.co) or contact support for guidance.

---

### [Network Settings](https://learn.social.plus/analytics-and-moderation/social+-apis-and-services/network-settings)

> Configure platform-wide settings and user experience controls through social.plus Network Settings APIs for comprehensive application management.

Network Settings APIs provide comprehensive control over platform-wide configurations that affect all users in your social.plus application. These settings enable you to customize user experience, privacy controls, and feature availability across your entire network.

Network Settings require **Admin API Access Token** and affect all users globally. Changes should be tested thoroughly before deployment.

## Overview

    Control mentions, feeds, and interaction features
    Manage user privacy modes and content visibility
    Enable or disable platform features globally
    Configure content creation and sharing rules

## Core Settings Categories

    ### Feed and Content Settings

        Control what content appears in users' global feeds:

```json
{
  "showAllPosts": true,
  "showFollowedOnly": false,
  "enableContentFiltering": true,
  "defaultFeedType": "global"
}
```

        **Options:**
        - `showAllPosts`: Display all public posts in global feed
        - `showFollowedOnly`: Limit feed to followed users only
        - `enableContentFiltering`: Apply content filtering rules

        Configure user mention functionality:

```json
{
  "enableUserMentions": true,
  "mentionPrivacyMode": "public",
  "maxMentionsPerPost": 10,
  "requireFollowToMention": false
}
```

        **Parameters:**
        - `enableUserMentions`: Allow users to mention others
        - `mentionPrivacyMode`: Control mention visibility
        - `maxMentionsPerPost`: Limit mentions per content

    ### User Privacy Settings

        Configure default privacy settings for users:

```json
{
  "defaultPrivacyMode": "public",
  "allowPrivacyChange": true,
  "privateProfilesByDefault": false,
  "friendsOnlyMode": false
}
```

        **Privacy Levels:**
        - **Public**: Content visible to all users
        - **Friends**: Content visible to friends only
        - **Private**: Content visible to user only

        Control how content is shared and discovered:

```json
{
  "enableContentSharing": true,
  "allowExternalSharing": true,
  "searchableContent": true,
  "publicUserProfiles": true
}
```

    ### Platform Features

        Enable or disable social interaction features:

```json
{
  "enableComments": true,
  "enableReactions": true,
  "enableFollowing": true,
  "enableDirectMessages": true,
  "enableGroupCreation": true
}
```

        Control content creation and management:

```json
{
  "enableImageUpload": true,
  "enableVideoUpload": true,
  "enableFileSharing": true,
  "maxFileSize": 10485760,
  "allowedFileTypes": ["jpg", "png", "gif", "mp4"]
}
```

## Implementation Guide

    Obtain an Admin API Access Token from Console → **Settings** → **Security**
    Retrieve existing network settings to understand current configuration
    Document intended changes and their impact on user experience
    Use the Network Settings API to update configurations
    Verify changes work as expected and monitor user feedback

## API Usage Examples

```bash curl
# Get current network settings
curl -X GET "https://api.amity.co/api/v3/network/settings" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

# Update network settings
curl -X PUT "https://api.amity.co/api/v3/network/settings" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enableUserMentions": true,
    "showAllPosts": false,
    "defaultPrivacyMode": "public"
  }'
```

```javascript JavaScript
// Get network settings
const getNetworkSettings = async () => {
  const response = await fetch('https://api.amity.co/api/v3/network/settings', {
    headers: {
      'Authorization': `Bearer ${ADMIN_TOKEN}`
    }
  });
  return response.json();
};

// Update network settings
const updateNetworkSettings = async (settings) => {
  const response = await fetch('https://api.amity.co/api/v3/network/settings', {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${ADMIN_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(settings)
  });
  return response.json();
};
```

```python Python
import requests

# Get network settings
def get_network_settings(admin_token):
    response = requests.get(
        'https://api.amity.co/api/v3/network/settings',
        headers={'Authorization': f'Bearer {admin_token}'}
    )
    return response.json()

# Update network settings
def update_network_settings(admin_token, settings):
    response = requests.put(
        'https://api.amity.co/api/v3/network/settings',
        headers={
            'Authorization': f'Bearer {admin_token}',
            'Content-Type': 'application/json'
        },
        json=settings
    )
    return response.json()
```

## Common Configuration Scenarios

    **Recommended Settings:**
    - Private profiles by default
    - Limited mentions
    - Curated content feeds
    - Enhanced privacy controls
    **Recommended Settings:**
    - Public profiles
    - Open mentions
    - Global content feeds
    - Social sharing enabled
    **Recommended Settings:**
    - Moderated content
    - Restricted file sharing
    - Teacher-only mentions
    - Limited privacy options
    **Recommended Settings:**
    - Public content sharing
    - Rich media support
    - Discovery features
    - Social interactions

## Best Practices

    - **Impact Assessment**: Evaluate how changes affect existing users
    - **Gradual Rollout**: Consider phased implementation for major changes
    - **User Communication**: Notify users of significant policy changes
    - **Backup Settings**: Document current settings before changes

    - **Staging Environment**: Test changes in a non-production environment
    - **User Scenarios**: Test common user workflows after changes
    - **Permission Validation**: Verify privacy and permission settings work correctly
    - **Performance Impact**: Monitor system performance after changes

    - **Usage Analytics**: Track how settings affect user engagement
    - **Feedback Collection**: Gather user feedback on experience changes
    - **Regular Reviews**: Periodically review and optimize settings
    - **Security Audits**: Ensure privacy settings meet security requirements

## API Reference

  Access the full API documentation for detailed endpoints, parameters, and response schemas for Network Settings management.

## Related Features

    Manage individual user settings and permissions
    Configure content filtering and moderation rules

---

Network Settings changes affect all users immediately. Always test in a staging environment and have a rollback plan ready.

---

### [Webhook Events](https://learn.social.plus/analytics-and-moderation/social+-apis-and-services/webhook-event)

> Real-time event notifications system for extending social.plus functionality with custom integrations and analytics

**Infrastructure Update - Action Required by June 9, 2025**

We are updating the list of IP addresses used by our webhook service as part of our ongoing efforts to enhance infrastructure security and reliability.

**What's Changing:**
- A new set of IP addresses will be introduced for webhook traffic
- Current IP addresses will be deprecated and stop working after June 9, 2025

**Action Required:**
Update your firewall or allowlist configurations to include the new IP addresses before June 9, 2025 to ensure uninterrupted webhook delivery.

## New IP Addresses by Region

    **Region**: Asia Pacific (Singapore)
```
52.77.130.167
54.251.77.74
54.255.59.189
18.142.212.217
```
    **Region**: Europe (Frankfurt)
```
3.127.106.141
3.65.238.41
3.65.52.7
3.77.135.138
```
    **Region**: North Virginia (US East)
```
52.70.191.115
100.24.154.219
52.44.28.213
52.72.76.90
```

**Need Help?** If you have questions or need assistance with the IP address update, contact our support team at [support@social.plus](mailto:support@social.plus) or submit a request through the [social.plus Help Center](https://help.social.plus).

## Overview

Webhook Events provide a powerful way to extend social.plus functionality by receiving real-time triggers from the platform. When enabled, events from your Chat and Social SDK are forwarded to your system instantly, enabling custom integrations and automation.

    Store webhook events to build custom analytics dashboards and track user engagement patterns
    Build automated message moderation and user management systems with instant event notifications
    Create custom search and personalization features based on real-time user activity data
    Integrate with external systems and build custom workflows triggered by platform events

## How Webhooks Work

**Webhook vs Traditional API**: Unlike traditional APIs where your application makes requests to receive responses, webhooks are "reverse APIs" where social.plus initiates communication by sending data to your system as soon as events occur.

### Event-Driven Architecture

    **Real-Time Delivery**
    - Events are triggered instantly when actions occur in your social.plus application
    - HTTP POST payloads sent to your configured webhook URLs
    - Near-real-time delivery for immediate response capabilities

    **Event Types**
    - User actions (posts, comments, reactions)
    - Chat messages and channel events
    - Community and social interactions
    - Moderation and safety events
    **Performance Considerations**
    - All webhook requests timeout in 1.5 seconds
    - Your webhook endpoint must respond within this interval
    - System should return HTTP 200 status with empty JSON response

    **Reliability Features**
    - Automatic retry mechanisms for failed deliveries
    - Signature verification for security
    - Scalable infrastructure for high-volume events

## Setup and Configuration

    Submit a request through our [support team](mailto:support@social.plus) to enable webhooks (currently in Private Beta). Processing takes approximately 5 business days.
    Admin users can create and manage webhooks in the admin panel:
    - Add webhook URLs for event delivery
    - Configure event types and filters
    - Set up authentication and security
    Build your webhook endpoint to:
    - Accept HTTP POST requests
    - Verify webhook signatures
    - Process events and respond within 1.5 seconds
    Test your webhook implementation and monitor delivery success rates and response times

### Configuration Limits

    **Maximum 10 webhooks per network**

    Recommended to keep webhook count reasonable for optimal performance and management
    **1.5 second timeout**

    Ensure your webhook endpoint responds quickly to prevent request timeouts and delivery failures

## Security and Authentication

### Signature Verification

**Security Requirement**: Always verify the `x-amity-signature` header before processing webhook events to prevent request forgery and ensure data integrity.

    ### Delivery Headers

    All webhook HTTP POST requests include these headers:

    | Header | Description |
    |--------|-------------|
    | `x-amity-signature` | HMAC Base64 digest of the response body using SHA-256 hash function |
    | `User-Agent` | Identifies the webhook delivery system |
    | `Content-Type` | Always `application/json` |
    | `Content-Length` | Size of the JSON payload |

    ### Backward Compatibility

    **Legacy Header**: You may receive duplicate requests with `x-eko-signature` header for backward compatibility. You can safely ignore these requests and only process events with `x-amity-signature`.

    **Migration Approach**
    - Process events with `x-amity-signature` header
    - Ignore duplicate events with `x-eko-signature`
    - Update your systems to use the new signature format

## Available Events

**Complete Event Reference**: For a full list of available webhook events and their detailed payload structures, please check our [API Reference documentation](../../api-reference/).

### Event Categories

    **Channel Events**
    - `channel.didCreate` - New channel created
    - `channel.didUpdate` - Channel settings updated

    **Message Events**
    - `message.didCreate` - New message sent
    - `message.didUpdate` - Message edited
    - `message.didDelete` - Message deleted
    - `message.didFlag` - Message flagged for moderation
    **Post Events**
    - `v3.post.didCreate` - New post published
    - `v3.post.didUpdate` - Post edited
    - `v3.post.didDelete` - Post deleted
    - `v3.post.didAddReaction` - Reaction added to post

    **Comment Events**
    - `v3.comment.didCreate` - New comment added
    - `v3.comment.didUpdate` - Comment edited
    - `v3.comment.didDelete` - Comment deleted
    **User Actions**
    - `user.didCreate` - New user registered
    - `user.didUpdate` - User profile updated
    - `follow.didCreate` - User followed another user
    - `v3.community.didJoin` - User joined community

    **Moderation Events**
    - `user.didFlag` - User reported/flagged
    - `moderation.didBan` - User banned after sending a message that matches the blocklist

## Best Practices

    **Always Verify Signatures**
    - Implement signature verification for all webhooks
    - Use constant-time comparison to prevent timing attacks
    - Keep webhook secrets secure and rotate regularly
    - Log suspicious or invalid requests
    **Optimize Response Times**
    - Respond within 1.5 seconds to prevent timeouts
    - Process events asynchronously when possible
    - Implement proper error handling and logging
    - Monitor webhook performance and delivery rates
    **Handle Failures Gracefully**
    - Implement retry logic for failed processing
    - Handle duplicate events appropriately
    - Store events for replay in case of system failures
    - Monitor webhook health and alert on issues
    **Design for Scale**
    - Use queues for high-volume event processing
    - Implement rate limiting and backpressure handling
    - Scale webhook endpoints horizontally
    - Cache frequently accessed data

## Troubleshooting

    **Webhook Not Receiving Events**
    - Verify webhook URL is accessible from social.plus servers
    - Check firewall rules allow traffic from social.plus IP addresses
    - Ensure webhook endpoint responds with HTTP 200 status
    - Verify webhook is properly configured in admin panel

    **Signature Verification Failures**
    - Confirm you're using the correct webhook secret
    - Verify signature calculation matches expected format
    - Check for character encoding issues in payload
    - Ensure raw request body is used for signature verification
    **Timeout Problems**
    - Optimize webhook handler for sub-1.5 second response
    - Move heavy processing to background jobs
    - Implement proper database connection pooling
    - Add monitoring and alerting for response times

    **High Volume Handling**
    - Implement event queuing and batch processing
    - Scale webhook endpoints horizontally
    - Use caching for frequently accessed data
    - Consider implementing backpressure mechanisms
    **Testing Webhooks**
    - Use tools like ngrok for local development testing
    - Implement comprehensive logging for webhook events
    - Test with different event types and payloads
    - Monitor webhook delivery success rates

    **Monitoring and Alerts**
    - Set up alerts for webhook failures
    - Monitor response times and error rates
    - Log all webhook events for debugging
    - Implement health checks for webhook endpoints

**Getting Started**: Start with a simple webhook handler that logs all events, then gradually add processing logic for specific event types relevant to your use case.

---

### [Pre-Hook Events](https://learn.social.plus/analytics-and-moderation/social+-apis-and-services/pre-hook-event)

> Implement custom moderation and control workflows with real-time event interception and processing

Gain granular control over user actions with pre-hook events that allow you to intercept, validate, and modify user interactions before they're processed. Perfect for implementing custom moderation rules, content filtering, and access control policies.

    Intercept user actions in real-time before they're processed
    Build custom validation and moderation logic tailored to your needs
    Receive events via webhooks and respond with custom actions
    Complete list of interceptable events and their data

## Overview

Pre-hook events enable you to create sophisticated moderation and control systems by intercepting user actions before they're executed. This allows for:

    - **Content Filtering**: Analyze and modify content before publication
    - **User Behavior Control**: Restrict access based on custom criteria
    - **Real-time Validation**: Validate data against business rules
    - **Automated Responses**: Implement graduated response systems

    - **Spam Prevention**: Block suspicious posting patterns
    - **Content Enhancement**: Auto-correct or enrich user content
    - **Access Control**: Implement channel-specific permission systems
    - **Analytics Injection**: Add tracking data to user actions

**Enterprise Feature**: Pre-hook events are available for customers on the Max plan. Contact our sales team to upgrade your plan.

## How It Works

Pre-hook events create a validation layer between user actions and their execution:

```mermaid
graph TB
    A[User Action] --> B[Pre-Hook Event Triggered]
    B --> C[Webhook Called]
    C --> D{Your Custom Logic}

    D -->|Allow| E[Action Proceeds]
    D -->|Deny| F[Action Blocked]
    D -->|Modify| G[Modified Action Proceeds]
    D -->|Timeout| H[Default Action Applied]

    E --> I[Normal Flow Continues]
    F --> J[Error Response to User]
    G --> I
    H --> K[Fallback Behavior]

    style E fill:#e8f5e8
    style F fill:#ffebee
    style G fill:#e3f2fd
    style H fill:#fff3e0
```

### Response Types

Your webhook endpoint must respond with one of these actions:

```json
{ "action": "allow" }
```
    Allow the action to proceed without modification.

```json
{
  "action": "allow",
  "data": {
    "modified_field": "new_value"
  }
}
```
    Allow the action but modify the data before processing.

```json
{
  "action": "deny",
  "message": "Action denied: Custom reason"
}
```
    Block the action and return an error message to the user.

## Getting Started

    Configure pre-hook events through the [Network Settings API](https://api-docs.amity.co/#/Network%20Setting/get_api_v3_network_settings_prehook).

    Create an HTTPS endpoint to receive and process pre-hook events.

    Specify which events you want to intercept and process.

    Test your webhook with sample events and monitor response times.

### Configuration

```json Enable Pre-Hook Events
PUT /api/v3/network/settings/prehook

{
  "enabled": true,
  "callbackUrl": "https://your-app.com/webhooks/prehook",
  "defaultAction": "allow",
  "events": [
    "message.shouldCreate",
    "message.shouldUpdate",
    "post.shouldCreate"
  ]
}
```

```json Get Current Configuration
GET /api/v3/network/settings/prehook

Response:
{
  "enabled": true,
  "callbackUrl": "https://your-app.com/webhooks/prehook",
  "defaultAction": "allow",
  "timeout": 3000,
  "events": ["message.shouldCreate"]
}
```

```javascript Signature Verification
const crypto = require('crypto');

function verifySignature(payload, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(payload))
    .digest('hex');

  return signature === expectedSignature;
}

// Verify incoming webhook
if (!verifySignature(payload, headers['x-signature'], secretKey)) {
  return { status: 401, body: 'Invalid signature' };
}
```

```python Python Verification
import hmac
import hashlib
import json

def verify_signature(payload, signature, secret_key):
  expected_signature = hmac.new(
    secret_key.encode(),
    json.dumps(payload).encode(),
    hashlib.sha256
  ).hexdigest()

  return signature == expected_signature
```


## Supported Events

    | Event | Triggered When | Available Data |
    |-------|----------------|----------------|
    | `message.shouldCreate` | User sends a message | Message content, channel ID, sender |
    | `message.shouldUpdate` | User edits a message | Updated content, original message |
    | `message.shouldFlag` | User flags a message | Message data, flag reason |
    | `message.shouldUnflag` | User removes flag | Message data, flag count |

    **Example Payload:**
```json
{
  "eventName": "message.shouldCreate",
  "data": {
    "text": "Hello world!",
    "channelId": "ch_123",
    "attachments": [],
    "metadata": {}
  },
  "actor": {
    "_id": "user_456",
    "userId": "user_456"
  }
}
```

    | Event | Triggered When | Available Data |
    |-------|----------------|----------------|
    | `channel.shouldCreate` | User creates channel | Channel data, creator |
    | `channel.shouldJoin` | User joins channel | Channel ID, user data |
    | `channel.shouldLeave` | User leaves channel | Channel ID, user data |
    | `channel.shouldUpdate` | Channel is updated | Updated channel data |

    **Example Payload:**
```json
{
  "eventName": "channel.shouldJoin",
  "data": {
    "channelId": "ch_123",
    "channelType": "live",
    "metadata": {}
  },
  "actor": {
    "_id": "user_456",
    "userId": "user_456"
  }
}
```

    | Event | Triggered When | Available Data |
    |-------|----------------|----------------|
    | `post.shouldCreate` | User creates post | Post content, community |
    | `post.shouldUpdate` | User edits post | Updated content |
    | `post.shouldDelete` | User deletes post | Post ID, deletion reason |
    | `post.shouldFlag` | User flags post | Post data, flag details |

    **Example Payload:**
```json
{
  "eventName": "post.shouldCreate",
  "data": {
    "text": "Check out this amazing feature!",
    "communityId": "comm_789",
    "attachments": [
      {
        "type": "image",
        "url": "https://example.com/image.jpg"
      }
    ]
  },
  "actor": {
    "_id": "user_456",
    "userId": "user_456"
  }
}
```

## Best Practices

    - **Fast Response Times**: Keep webhook processing under 2 seconds
    - **Fail-Safe Design**: Default to "allow" on errors to prevent user disruption
    - **Async Processing**: For complex logic, respond quickly and process asynchronously
    - **Monitoring**: Track webhook response times and error rates
    - **Retry Logic**: Implement exponential backoff for external service calls

    - **Signature Verification**: Always verify webhook signatures
    - **HTTPS Only**: Use secure HTTPS endpoints for webhook URLs
    - **Input Validation**: Validate all incoming event data
    - **Rate Limiting**: Implement rate limiting on your webhook endpoint
    - **Logging**: Log all events for debugging and audit purposes

    - **Clear Error Messages**: Provide helpful feedback when denying actions
    - **Consistent Policies**: Apply rules consistently across all users
    - **Graceful Degradation**: Handle service outages gracefully
    - **Documentation**: Document your custom rules for transparency
    - **Appeal Process**: Provide ways for users to appeal automated decisions

## Troubleshooting

    **Timeout Errors**
    - Ensure webhook responds within 3 seconds
    - Implement async processing for complex operations
    - Use caching for frequently accessed data

    **Invalid Signatures**
    - Verify webhook URL configuration
    - Check secret key configuration
    - Ensure payload is parsed correctly

    **Unexpected Behavior**
    - Check default action configuration
    - Verify event type filtering
    - Review webhook response format

    **Local Testing**
```bash
# Use ngrok for local webhook testing
ngrok http 3000

# Update webhook URL in console
curl -X PUT "https://api.social.plus/api/v3/network/settings/prehook" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"callbackUrl": "https://your-ngrok-url.ngrok.io/webhook"}'
```

    **Monitoring Tools**
    - Set up alerts for webhook failures
    - Monitor response time metrics
    - Track action distribution (allow/deny/modify)
    - Use structured logging for better debugging

**Production Considerations**: Always test pre-hook events thoroughly in a staging environment before deploying to production. Failed or slow webhook responses can impact user experience.

---

### [User Last Activity Report](https://learn.social.plus/analytics-and-moderation/social+-apis-and-services/generate-user-last-activity-report)

> Export per-user last read & write timestamps to identify inactive accounts and drive re‑engagement or cleanup actions

## Overview

The User Last Activity Report provides the most recent timestamps of key actions (read + write) per user. Administrators use it to:

- Identify inactive / dormant accounts
- Drive re‑engagement campaigns (email / push)
- Plan archival or deletion workflows (e.g., GDPR cleanup)
- Validate growth & retention metrics against real interaction

	Requires an **admin session**. These endpoints are for server / internal tooling only—never expose admin credentials to clients.

## When To Use

Use this report when you need a lightweight snapshot of user activity recency rather than full behavioral analytics. For richer metrics (MAU/DAU, content engagement) see the broader **Analytics APIs** in the <a href="/analytics-and-moderation/social+-apis-and-services/README">API Overview</a>.


## Access & Permissions

- Admin credentials (admin token) required in Authorization header
- Scoped to your network / application only
- Rate limits apply (avoid high-frequency polling—prefer scheduled exports)
- **Minimum 5,000 users required** in your application to generate the report

	Do not embed admin token logic in front-end code. Generate and process reports using a secure backend or internal admin tool.

	**User Count Requirement**: Your application must have at least 5,000 users to generate the User Last Activity Report. If your application has fewer users, the report generation will not be available.

## Export Flow

		Submit credentials to obtain an authenticated admin session (token-based).
		Call the report endpoint. Response will return in CSV format.
		Using the CSV output to trigger re‑engagement or cleanup workflows (bulk user delete API).

## API Contract (High-Level)

| Aspect | Value |
|--------|-------|
| Method | GET |
| Path | `/api/v1/reports/user-last-activity` |
| Auth | Admin token |
| Format | CSV |

	Prefer cursor-based pagination (if available) for large networks instead of increasing page size.

### Request

	See complete request/response schemas, parameters, and examples. This API only accepts admin token as authorization.

## Interpreting Results

The report returns a CSV with the following columns:

| Column | Description |
|--------|-------------|
| `user_id` | Internal user identifier |
| `user_public_id` | Public-facing user ID |
| `display_name` | User's display name |
| `last_active_utc` | Most recent activity timestamp (UTC) |

### Activity Patterns

| Scenario | Interpretation | Suggested Action |
|----------|----------------|------------------|
| `last_active_utc` is null | Newly created / never logged in | Onboarding reminder |
| `last_active_utc` < 30 days ago | Active user | Continue regular engagement |
| `last_active_utc` 30-90 days ago | At-risk user | Re-engagement campaign |
| `last_active_utc` ≥ 90 days ago | Dormant account | Re‑engagement or archival workflow |

## Automation Ideas

		Export weekly, filter users with `last_active_utc` older than threshold, send personalized email or push, measure reactivation rate.
		Flag accounts inactive > 180 days for soft archival. After notice period, proceed with deletion respecting compliance rules.
		Use the CSV output directly with the [Bulk User Delete API](/api-reference/user/create-bulk-user-delete-job) to clean up inactive accounts. The API accepts the CSV format from this report, making it seamless to process dormant users at scale while maintaining audit trails.
		Detect sudden stop in activity of high‑value users—trigger internal review or outreach.

## Troubleshooting

| Issue | Possible Cause | Fix |
|-------|----------------|-----|
| 401 / Unauthorized | Missing / expired admin cookie | Re-authenticate and resend request |
| Report not available | Application has fewer than 5,000 users | Wait until your application reaches 5,000 users minimum |
| Empty dataset | Filters defaulting to restrictive scope (if any) | Remove params / verify user activity exists |
| Missing columns | Feature disabled / retention policy | Confirm configuration; adapt parsing |
| Slow export | Large dataset without pagination | Use pagination or request CSV streaming |

	Always log the raw HTTP status + response headers for diagnostics. Store processed data separately from raw export for reproducibility.

## Related


---

If you have questions, contact support at <a href="mailto:support@social.plus">support@social.plus</a>.

## Overview & Reference

### [Home](https://learn.social.plus/index)

> Welcome to the social.plus documentation

<div className="hero-section">
  <div className="hero-content">
    <div className="hero-text">
      <h1 className="hero-title">Build with social.plus</h1>
      <p className="hero-description">
        Get started with social.plus SDKs, UIKits, and APIs to integrate powerful social features into
        your application - fast, flexible, and built for scale.
      </p>
    </div>

    <div className="search-container">
      <div className="search-box" id="custom-search-trigger" onclick="console.log('DIRECT CLICK DETECTED'); triggerSearch();">
        <span className="search-icon">🔍</span>
        <input type="text" placeholder="Search..." className="search-input" readOnly />
        <span className="search-shortcut">⌘K</span>
      </div>
    </div>

    <script dangerouslySetInnerHTML={{__html: `
      console.log('Script is loading...');

      window.triggerSearch = function() {
        console.log('triggerSearch called!');

        // Method 1: Try to find and examine all buttons first
        const allButtons = Array.from(document.querySelectorAll('button'));
        console.log('All buttons on page:', allButtons.map(b => ({
          element: b,
          text: b.textContent?.trim(),
          ariaLabel: b.getAttribute('aria-label'),
          className: b.className,
          id: b.id,
          dataset: Object.assign({}, b.dataset)
        })));

        // Method 2: Try to find search in different ways
        const searchCandidates = [
          document.querySelector('button[aria-label*="Search"]'),
          document.querySelector('button[aria-label*="search"]'),
          document.querySelector('.DocSearch-Button'),
          document.querySelector('[data-search]'),
          document.querySelector('[role="search"] button'),
          document.querySelector('input[type="search"]'),
          ...allButtons.filter(b =>
            b.textContent?.toLowerCase().includes('search') ||
            b.getAttribute('aria-label')?.toLowerCase().includes('search') ||
            b.className.toLowerCase().includes('search')
          )
        ].filter(Boolean);

        console.log('Search candidates found:', searchCandidates);

        // Method 3: Try to trigger via keyboard event to different targets
        const targets = [document, window, document.body, document.documentElement];
        const events = ['keydown', 'keypress', 'keyup'];

        for (const target of targets) {
          for (const eventType of events) {
            const event = new KeyboardEvent(eventType, {
              key: 'k',
              code: 'KeyK',
              keyCode: 75,
              which: 75,
              metaKey: true,
              ctrlKey: false,
              bubbles: true,
              cancelable: true,
              composed: true
            });

            try {
              console.log(\`Dispatching \${eventType} to\`, target);
              target.dispatchEvent(event);
            } catch (e) {
              console.error(\`Error dispatching \${eventType}:\`, e);
            }
          }
        }

        // Method 4: Try clicking the most likely search candidate
        if (searchCandidates.length > 0) {
          console.log('Attempting to click first search candidate:', searchCandidates[0]);
          try {
            searchCandidates[0].click();
          } catch (e) {
            console.error('Error clicking search candidate:', e);
          }
        }

        // Method 5: Check for Mintlify-specific globals
        console.log('Window globals check:');
        console.log('window.mintlify:', window.mintlify);
        console.log('window.docsearch:', window.docsearch);
        console.log('window.DocSearch:', window.DocSearch);
        console.log('window.algolia:', window.algolia);
      };

      // Also set up click handler via JavaScript
      function setupSearch() {
        console.log('Setting up search handler...');
        const searchBox = document.getElementById('custom-search-trigger');
        if (searchBox) {
          console.log('Found search box, adding event listener');
          searchBox.addEventListener('click', window.triggerSearch);
          searchBox.style.cursor = 'pointer';
        } else {
          console.log('Search box not found!');
        }
      }

      // Try multiple times to set up
      if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', setupSearch);
      } else {
        setupSearch();
      }

      setTimeout(setupSearch, 100);
      setTimeout(setupSearch, 500);
      setTimeout(setupSearch, 1000);

      console.log('Script setup complete');
    `}} />

  <div className="cards-section">
      Integrate social.plus with platform-specific SDKs for auth, real-time events, data, and
      core services.
      Use prebuilt UI components for feeds, profiles, groups, chat, and live streaming features.
      Explore complete API docs with endpoints, parameters, auth methods, and response formats.
      Manage apps, regions, billing, usage, and account settings from one centralized platform.
      Monitor data, configure settings, and manage moderation across your social.plus applications.
      Analyze chat, community, and live stream data to track engagement and platform performance.
  </div>

  </div>
</div>

---

### [social.plus SDK](https://learn.social.plus/social-plus-sdk/overview)

> Build custom social, chat, and supported video experiences with the social.plus SDK

![SDK Dark Pn](/images/SDK-Dark.png)

The social.plus SDK gives developers client-side building blocks for custom social, chat, and supported video experiences. Use it when you want to design your own UI while relying on social.plus for managed social infrastructure such as feeds, communities, messaging, moderation, files, realtime updates, and platform-specific SDK integrations.

## Choose Your Approach

**Not sure which social.plus solution fits your needs?** Here's how to decide:

    title="SDK - Custom Control"
    icon="code"
    href="/social-plus-sdk/getting-started/overview"
  >
    **Build Custom Experiences** ⭐ You are here
    - Unique user interface requirements
    - Custom user flows and interactions
    - Complete design freedom
    - Integrate with existing apps

    title="UIKit - Quick Launch"
    icon="palette"
    href="/uikit/overview"
  >
    **Pre-built UI Components**
    - Need to launch quickly (weeks not months)
    - Standard social app layouts
    - Minimal to moderate customization
    - Perfect for MVPs and rapid prototyping

    title="API - Maximum Flexibility"
    icon="server"
    href="/api-reference/introduction"
  >
    **Direct API Integration**
    - Server-to-server communication
    - Custom backend integration
    - Non-standard platforms
    - Advanced technical requirements

  **Perfect for:** Custom social platforms, unique user experiences, existing app integration, and when you need complete control over the user interface and user flows.

## How to Use This Section

    **Start with Guides** — step-by-step walkthroughs that take you from zero to working feature, with links back to SDK reference at every step.
    **You're in the right place** — the SDK docs cover setup, core concepts, and feature-specific implementation details.

---

## Quick Start

Get up and running with social.plus SDK in minutes:

    Set up social.plus SDK for your platform with our step-by-step installation guides
    Configure user authentication and API keys for secure access

## Core Features

### Social Features

Build comprehensive social experiences with our feature-rich social modules:

    Dynamic feeds, posts, comments, reactions, and content discovery
    Real-time messaging, channels, DMs, and advanced chat features
    Create and manage communities, spaces, and user groups

  Social interaction and story capabilities are consolidated under the sections below.
    Follow/unfollow, block/unblock, and social graph features
    Posts, comments, stories, moderation and media tools
    Ephemeral story creation, retrieval, analytics and management

### Video & Streaming

Video broadcasting and playback capabilities:

    Live streaming workflows with room-based broadcasting
    Broadcasting workflows with room, co-host, and live viewing guides

    Playback guides for viewer experiences where video features are supported

## Platform Support

social.plus provides client SDKs and setup guides for iOS, Android, TypeScript/JavaScript, and Flutter:

    **Native iOS & Android**

    - Swift for iOS
    - Kotlin/Java for Android
    - Full platform integration
    **Flutter & React Native Guidance**

    - Flutter SDK for iOS and Android apps
    - TypeScript SDK guidance for React Native where supported
    - Platform-specific setup and behavior notes

    **TypeScript/JavaScript**

    - TypeScript/JavaScript SDK
    - Modern web app integration
    - Web video features where supported by the video SDK guides

## Why Choose social.plus SDK?

    - **Managed Features**: Build on SDK APIs for posts, comments, chat, files, users, and communities
    - **Platform Setup Guides**: Start with iOS, Android, TypeScript, or Flutter quick starts
    - **Composable Modules**: Combine social, chat, realtime, moderation, and media features as needed
    - **Managed Infrastructure**: social.plus hosts the backend services behind SDK features
    - **Realtime-Capable Features**: Live collections and realtime events are available for supported resources
    - **Media Handling**: File, image, and video guides cover upload and playback workflows
    - **Shared Concepts**: Core ideas such as users, channels, communities, posts, and moderation carry across SDKs
    - **Platform-Specific APIs**: Each SDK uses native language patterns and documented setup requirements
    - **Versioned Changelogs**: Platform changelogs help teams plan SDK upgrades
    - **Admin Controls**: Console and server-side API flows support privileged operations
    - **Moderation Tools**: Role-based permissions, reporting, ban, mute, and content workflows are available across supported areas
    - **Data Boundaries**: Keep identity and private account data in your system while sending social profile fields the SDK needs
    - **Support Channels**: Use support email, docs, and community resources when you need help

## Use Cases

social.plus SDK powers diverse applications across industries:

    Build the next generation of social platforms with advanced features like Stories, live streaming, and community management.
    Create engaging gaming experiences with clan chat, live streaming, tournaments, and player interactions.
    Enable collaborative learning with discussion forums, live classes, study groups, and peer-to-peer interaction.
    Build internal communication tools, team collaboration platforms, and customer engagement solutions.
    Empower content creators with monetization tools, fan engagement features, and live streaming capabilities.
    Add social features to shopping experiences with reviews, recommendations, and community-driven commerce.

## Release Notes

Stay up-to-date with the latest SDK features, improvements, and bug fixes:

    Latest updates and releases for iOS SDK
    Latest updates and releases for Android SDK
    Latest updates and releases for Web SDK
    Latest updates and releases for Flutter SDK

## Additional Resources

    Complete API documentation with endpoints, parameters, and examples
    Join our developer community for support, tips, and best practices
    Contribute to our repositories, report issues, and access UIKit projects

---

  **Need Help?**

  Our developer success team is here to help you build amazing social experiences. Reach out through our [support email](mailto:support@social.plus) or join our [developer forum](https://forum.social.plus/) for peer support and best practices.

---

### [Feature Matrix](https://learn.social.plus/feature-matrix)

> Feature availability and platform support across SDK and UIKit.

# Feature Matrix

A comprehensive overview of feature availability and platform support across **SDK** and **UIKit**.
Use the tabs within each section to compare coverage between the two.


**Availability** indicates whether a feature is available, planned, or not yet available.
For individual platforms, ✅ means supported and **—** means not yet supported.


## Discovery


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Find Communities / Group Profiles | Available | ✅ | ✅ | ✅ | ✅ |
| Find User Profiles | Available | ✅ | ✅ | ✅ | ✅ |
| Intelligent Search | Available | ✅ | ✅ | ✅ | — |
| Community Discovery & Suggestions | Available | ✅ | ✅ | ✅ | ✅ |
| Community Category Discovery | Available | ✅ | ✅ | ✅ | ✅ |
| Event Discovery | Available | ✅ | ✅ | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Find Communities / Group Profiles | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Find User Profiles | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Intelligent Search | Not Available | — | — | ✅ | — | — |
| Community Discovery & Suggestions | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Community Category Discovery | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Event Discovery | Available | ✅ | ✅ | ✅ | — | — |


## Activity Feeds


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Following (Global) Feeds | Available | ✅ | ✅ | ✅ | ✅ |
| For You Feeds | Available | ✅ | ✅ | ✅ | — |
| Community Feeds | Available | ✅ | ✅ | ✅ | ✅ |
| User Feeds | Available | ✅ | ✅ | ✅ | ✅ |
| Story Feeds | Available | ✅ | ✅ | ✅ | ✅ |
| Clips Feed (Short Form Videos) | Available | ✅ | ✅ | ✅ | ✅ |
| Live Stream Feeds ('Live' Rings) | Available | ✅ | ✅ | ✅ | — |
| Event Feeds (Upcoming & Past Events) | Available | ✅ | ✅ | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Following (Global) Feeds | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| For You Feeds | Available | ✅ | ✅ | ✅ | — | — |
| Community Feeds | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| User Feeds | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Story Feeds | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Clips Feed (Short Form Videos) | Available | ✅ | ✅ | ✅ | — | — |
| Live Stream Feeds ('Live' Rings) | Available | ✅ | ✅ | ✅ | — | — |
| Event Feeds (Upcoming & Past Events) | Available | ✅ | ✅ | ✅ | — | — |


## Feed Management


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Custom Ranking | Available | ✅ | ✅ | ✅ | ✅ |
| Chronological Ranking | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Custom Ranking | Not Available | — | — | — | — | — |
| Chronological Ranking | Available | ✅ | ✅ | ✅ | ✅ | ✅ |


## Post Types


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Text Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Image Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Video Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Audio Posts | Available | ✅ | ✅ | ✅ | — |
| Poll Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Clips (Short Form Videos) | Available | ✅ | ✅ | ✅ | ✅ |
| Live Stream Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Custom Posts | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Text Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Image Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Video Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Audio Posts | Not Available | — | — | — | — | — |
| Poll Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Clips (Short Form Videos) | Available | ✅ | ✅ | ✅ | — | — |
| Live Stream Posts | Available | ✅ | ✅ | ✅ | ✅ | — |
| Custom Posts | Not Available | — | — | — | — | — |


## Post Composition


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Post Titles | Available | ✅ | ✅ | ✅ | — |
| Post Hashtags | Available | ✅ | ✅ | ✅ | — |
| Text to Hyperlinks (Web Desktop only) *(Note: Mobile UI Kits support rendering only)* | Available | — | — | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Post Titles | Available | ✅ | ✅ | ✅ | — | — |
| Post Hashtags | Available | ✅ | ✅ | ✅ | — | — |
| Text to Hyperlinks (Web Desktop only) *(Note: Mobile UI Kits support rendering only)* | Available | — | — | ✅ | — | — |


## Posting Permissions (Community Posts Only)


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Admin-Only Posting *(Note: Console only)* | Not Available | — | — | — | — |
| Posts Requires Approval | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Admin-Only Posting *(Note: Console only)* | Not Available | — | — | — | — | — |
| Posts Requires Approval | Available | ✅ | ✅ | ✅ | ✅ | ✅ |


## Stories


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Story Feed - Following (Global Feed); Community Feed | Available | ✅ | ✅ | ✅ | ✅ |
| Community Stories | Available | ✅ | ✅ | ✅ | ✅ |
| User Stories | Not Available | — | — | — | — |
| Image Stories | Available | ✅ | ✅ | ✅ | ✅ |
| Video Stories | Available | ✅ | ✅ | ✅ | ✅ |
| Story Stickers / Polls / Text Overlay | Not Available | — | — | — | — |
| Comment & React on Stories | Available | ✅ | ✅ | ✅ | ✅ |
| Report Stories | Not Available | — | — | — | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Story Feed - Following (Global Feed); Community Feed | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Community Stories | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| User Stories | Not Available | — | — | — | — | — |
| Image Stories | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Video Stories | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Story Stickers / Polls / Text Overlay | Not Available | — | — | — | — | — |
| Comment & React on Stories | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report Stories | Not Available | — | — | — | — | — |


## Comments & Reactions


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Single-Level Comments | Available | ✅ | ✅ | ✅ | ✅ |
| Multi-Level Comments | Available | ✅ | ✅ | ✅ | — |
| GIF Comments | Not Available | — | — | — | — |
| Comment Ranking | Not Available | — | — | — | — |
| Multiple Reactions | Available | ✅ | ✅ | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Single-Level Comments | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Multi-Level Comments | Available | ✅ | ✅ | ✅ | — | — |
| GIF Comments | Not Available | — | — | — | — | — |
| Comment Ranking | Not Available | — | — | — | — | — |
| Multiple Reactions | Available | ✅ | ✅ | ✅ | — | — |


## Live Stream Creation


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Community Live Streams | Available | ✅ | ✅ | ✅ | ✅ |
| User Live Streams | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Community Live Streams | Available | ✅ | ✅ | ✅ | ✅ | — |
| User Live Streams | Available | ✅ | ✅ | ✅ | ✅ | — |


## Live Stream Capabilities


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Watching Now Count | Available | ✅ | ✅ | ✅ | — |
| Co-Host Live Streams *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — |
| Live Chat during Stream *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — |
| Read-Only Chat *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — |
| Live Reactions *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — |
| Pin Message in Livestream Chat *(Note: Community Streams Only)* | Planned | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Watching Now Count | Available | ✅ | ✅ | ✅ | — | — |
| Co-Host Live Streams *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — | — |
| Live Chat during Stream *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — | — |
| Read-Only Chat *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — | — |
| Live Reactions *(Note: Community Streams Only)* | Available | ✅ | ✅ | ✅ | — | — |
| Pin Message in Livestream Chat *(Note: Community Streams Only)* |  | ✅ | ✅ | ✅ | ✅ | ✅ |


## Events


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Create Events | Available | ✅ | ✅ | ✅ | — |
| Event RSVP | Available | ✅ | ✅ | ✅ | — |
| Attendee List | Available | ✅ | ✅ | ✅ | — |
| Event Notifications | Available | ✅ | ✅ | ✅ | — |
| Event Discussions | Available | ✅ | ✅ | ✅ | — |
| Sharing Events | Not Available | — | — | — | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Create Events | Available | ✅ | ✅ | ✅ | — | — |
| Event RSVP | Available | ✅ | ✅ | ✅ | — | — |
| Attendee List | Available | ✅ | ✅ | ✅ | — | — |
| Event Notifications | Available | ✅ | ✅ | ✅ | — | — |
| Event Discussions | Available | ✅ | ✅ | ✅ | — | — |
| Sharing Events | Not Available | — | — | — | — | — |


## Content Sharing & Management


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Post Scheduling *(Note: Console only)* | Not Available | — | — | — | — |
| Story Scheduling *(Note: Console only)* | Not Available | — | — | — | — |
| Link Previews | Available | ✅ | ✅ | ✅ | ✅ |
| Deep Linking for Sharing (Posts, Community Profile, User Profile, Live Streams) *(Note: Console only)* | Not Available | — | — | — | — |
| Post & Comment as Brand *(Note: Console only; UI Kit supports rendering)* | Not Available | — | — | — | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Post Scheduling *(Note: Console only)* | Not Available | — | — | — | — | — |
| Story Scheduling *(Note: Console only)* | Not Available | — | — | — | — | — |
| Link Previews | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Deep Linking for Sharing (Posts, Community Profile, User Profile, Live Streams) *(Note: Console only)* | Not Available | — | — | — | — | — |
| Post & Comment as Brand *(Note: Console only; UI Kit supports rendering)* | Not Available | — | — | — | — | — |


## Notifications


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Push Notifications | Available | ✅ | ✅ | ✅ | ✅ |
| Notification Tray | Available | ✅ | ✅ | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Push Notifications | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Notification Tray | Available | ✅ | ✅ | ✅ | ✅ | — |


## Users


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| User Profiles | Available | ✅ | ✅ | ✅ | ✅ |
| User Tags *(Note: Console only)* | Not Available | — | — | — | — |
| User Media Gallery | Available | ✅ | ✅ | ✅ | ✅ |
| Brand Accounts *(Note: Console only; UI Kit supports rendering brand users and posts by these accounts)* | Not Available | — | — | — | — |
| "Moderator" User Badges | Available | ✅ | ✅ | ✅ | ✅ |
| Follow User | Available | ✅ | ✅ | ✅ | ✅ |
| Follow Request Approval | Available | ✅ | ✅ | ✅ | ✅ |
| Recommended Follows | Not Available | — | — | — | — |
| Block User | Available | ✅ | ✅ | ✅ | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| User Profiles | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| User Tags *(Note: Console only)* | Not Available | — | — | — | — | — |
| User Media Gallery | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Brand Accounts *(Note: Console only; UI Kit supports rendering brand users and posts by these accounts)* | Not Available | — | — | — | — | — |
| "Moderator" User Badges | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Follow User | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Follow Request Approval | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Recommended Follows | Not Available | — | — | — | — | — |
| Block User | Available | ✅ | ✅ | ✅ | ✅ | — |


## Communities


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| "Official" Community Badges | Available | ✅ | ✅ | ✅ | ✅ |
| Public Communities | Available | ✅ | ✅ | ✅ | ✅ |
| Hidden Private Communities | Available | ✅ | ✅ | ✅ | ✅ |
| Discoverable Private Communities | Available | ✅ | ✅ | ✅ | — |
| Membership Requires Moderator Approval | Available | ✅ | ✅ | ✅ | — |
| Community Media Gallery | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| "Official" Community Badges | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Public Communities | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Hidden Private Communities | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Discoverable Private Communities | Available | ✅ | ✅ | ✅ | — | — |
| Membership Requires Moderator Approval | Available | ✅ | ✅ | ✅ | — | — |
| Community Media Gallery | Available | ✅ | ✅ | ✅ | ✅ | ✅ |


## Moderation


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Report Posts | Available | ✅ | ✅ | ✅ | ✅ |
| Report Comments | Available | ✅ | ✅ | ✅ | ✅ |
| Report User | Available | ✅ | ✅ | ✅ | ✅ |
| Report Posts & Comments with Pre-Defined Reasons | Available | ✅ | ✅ | ✅ | — |
| Report Live Stream Chat | Available | ✅ | ✅ | ✅ | — |
| Lock Comments | Not Available | — | — | — | — |
| Hide Posts | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Report Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report Comments | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report User | Available | ✅ | ✅ | ✅ | ✅ | ✅ |
| Report Posts & Comments with Pre-Defined Reasons | Available | ✅ | ✅ | ✅ | — | — |
| Report Live Stream Chat | Available | ✅ | ✅ | ✅ | — | — |
| Lock Comments | Not Available | — | — | — | — | — |
| Hide Posts | Available | ✅ | ✅ | ✅ | ✅ | ✅ |


## Commerce


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Product Tagging in Posts | Available | ✅ | ✅ | — | — |
| Product Tagging in Comments | Not Available | — | — | — | — |
| Product Tagging in Live Streams | Available | ✅ | ✅ | — | — |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Product Tagging in Posts | Available | ✅ | ✅ | ✅ | — | — |
| Product Tagging in Comments | Not Available | — | — | — | — | — |
| Product Tagging in Live Streams | Available | ✅ | ✅ | ✅ | — | — |


## Sponsored Content


| Feature | Availability | Android | iOS | TS | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Native Posts | Available | ✅ | ✅ | ✅ | — |
| Native Comments | Available | ✅ | ✅ | ✅ | — |
| Native Stories | Available | ✅ | ✅ | ✅ | ✅ |


| Feature | Availability | Android | iOS | Web | RN | Flutter |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| Native Posts | Available | ✅ | ✅ | ✅ | — | — |
| Native Comments | Available | ✅ | ✅ | ✅ | — | — |
| Native Stories | Available | ✅ | ✅ | ✅ | ✅ | ✅ |

---

### [Technical FAQ](https://learn.social.plus/social-plus-sdk/technical-faq)

> Explore our Technical FAQ for quick answers to common questions about social.plus products. Get troubleshooting tips, best practices, and insights to optimize your technical experience.

Central, living knowledge base for developers integrating <strong>social.plus</strong>. Use the quick navigation, browser find (⌘/Ctrl + F), or your docs site search to jump to relevant answers. Each category groups focused, implementation‑level questions gathered from support & community discussions.

## Quick Navigation

## Using This FAQ

Looking for a question that is not here? Use the <strong>Developer Forum</strong> anchor in the SDK navigation to open community discussions or submit a new thread.

## API

    To create a large number of users, use the session registration endpoint: <a href="https://api-docs.amity.co/#/Session/post_api_v4_sessions">Register a session</a>. Script the call over your user list (respecting rate limits) to establish accounts.
    This question is answered under the <strong>Console</strong> section ("Where can I get my admin token?"). See <a href="#console">Console &raquo; Admin token</a>.
    API list endpoints return a <code>paging.next</code> token. Pass it back as the <code>options[token]</code> (or documented query param) to fetch the next slice.
    <br/><br/>
    Example response:
```json
{
  "paging": { "next": "eyJza2lwIjoyMCwibGltaXQiOjEwfQ==" }
}
```
    Example request:
    <pre><code>curl --location --globoff 'https://api.sg.amity.co/api/v3/communities?filter=all&sortBy=lastCreated&options[token]=eyJza2lwIjoxMCwibGltaXQiOjEwfQ%3D%3D' \\
  --header 'accept: application/json' \\
  --header 'Authorization: Bearer xxx'</code></pre>
    Use the blocklist records endpoint:
```bash
curl --location 'https://api.sg.amity.co/api/v3/blacklist/records' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{
    "regexs": ["word1", "word2", "word3"],
    "isMatchExactWord": true
}'
```
    Set <code>isMatchExactWord</code> to <code>true</code> for exact term blocking or <code>false</code> for substring / regex style matches. API Ref: <a href="https://api-docs.amity.co/#/Moderation/post_api_v3_blocklists">Moderation &raquo; Blocklists</a>.
    Update social network settings via: <a href="https://api-docs.amity.co/#/Network%20Setting/put_api_v3_network_settings_social">PUT /network-settings/social</a>
```bash
curl --location --request PUT 'https://api.sg.amity.co/api/v3/network-settings/social' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"isFollowWithRequestEnabled": false}'
```
    Append <code>?size=full</code> to the file download URL. Sizes: <code>small</code> | <code>medium</code> | <code>large</code> | <code>full</code>.
    <br/>Example: <code>.../files/{fileId}/download?size=full</code>
    The SDK auto-manages refresh / access tokens. When using raw REST, simply request a new session (register session) instead of manually rotating a refresh token.
    Auth tokens (secure mode) are valid 10 minutes. See: <a href="https://docs.amity.co/analytics-and-moderation/console/settings/security#secure-mode">Secure Mode docs</a>. Obtain a fresh one server-side when expiring, then call Session create.
    Filter with <code>filter=member</code> on communities endpoint:
```bash
curl --location 'https://apix.sg.amity.co/api/v3/communities?filter=member&sortBy=lastCreated&options[limit]=100' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
```
    1. Get new auth token:
```bash
curl --location 'https://api.sg.amity.co/api/v3/authentication/token?userId=Amity' \
  --header 'accept: application/json' \
  --header 'x-server-key: xxx'
```
    2. Exchange via Session API:
```bash
curl --location 'https://apix.sg.amity.co/api/v4/sessions' \
  --header 'accept: application/json' \
  --header 'x-api-key: xxx' \
  --header 'Content-Type: application/json' \
  --data '{"userId":"Amity","deviceId":"test","authToken":"xxx"}'
```
    Use the Authentication token endpoint then register session. Docs: <a href="https://api-docs.amity.co/#/Authentication/get_api_v3_authentication_token">Authentication</a>. For context see Security page.
    No direct "my reacted posts" endpoint. Query reactions (<a href="https://api-docs.amity.co/#/Reaction/get_api_v3_reactions">Reactions list</a>) and filter client-side for your <code>userId</code> per target post.
    Send only the <code>metadata</code> field in a user update body; unspecified fields remain unchanged.
```bash
curl --location --request PUT 'https://api.eu.amity.co/api/v2/users' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"userId":"Test","metadata":{"tier":"gold"}}'
```
    Iterate: list posts (community / user feeds) then call delete for each (<a href="https://api-docs.amity.co/#/Post%20v4/delete_api_v4_posts__postId">Delete Post v4</a>). Build an idempotent script with backoff; respect rate limits.
    Use <a href="https://api-docs.amity.co/#/File/post_api_v4_files">POST /files</a> then attach returned fileId when creating the post/message referencing audio.
```bash
curl --location --globoff 'https://apix.sg.amity.co/api/v3/communities/COMMUNITY_ID/users?memberships[]=member&roles[]=moderator&options[limit]=10' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
```
    Not supported: upload endpoints expect file data (multipart / direct). Fetch remote file server-side then re-upload if needed.
    Creating a new session with the same <code>deviceId</code> invalidates the old access token. Use stable per-device identifiers; avoid reusing one id across multiple concurrent logins.
    To receive real-time event notifications, register a webhook by supplying a callback URL in the social.plus Console. Once registered, the platform will deliver event data via HTTP POST requests to the specified URL whenever supported events occur (e.g., users added to a channel, messages created, users joining, or posts being flagged).

    Event names follow a structured format, such as:
    <code>"event": "channel.didAddUsers"</code>

    For the full list of supported webhook events and payload details, refer to the <a href="https://learn.social.plus/api-reference/webhook-event/channel-users-added-webhook">documentation</a>.
    Our API rate limit is 100 requests per 5 seconds per user (<code>userId</code>).
    This means the limit is shared across all devices for the same user. For example, if one user is logged in on multiple devices, all requests from those devices are counted together under the same limit.

    If the limit is exceeded, the API will return a rate limit error (e.g., HTTP 429).

    To handle high-volume traffic, we recommend implementing throttling, retry with backoff, batching, and caching to ensure smooth and reliable performance.
    Via Console: Navigate to Moderation → AI Content Moderation and set confidence levels per category.
    In case you want to autojoin users to a community, we recommend using the "Invitation" API, as you can use your admin token in order to add new users into a community and only incurr in only one MAU.

***

## Social and Chat

    <p><code>targetType</code> identifies feed scope (<code>user</code> | <code>community</code>); <code>targetId</code> is the userId or communityId. Together they scope post queries. See SDK docs: https://docs.amity.co/amity-sdk/social/posts/query-post</p>
    Engagement-based sort is only available on global feed. Community feeds support <code>lastCreated</code> and <code>firstCreated</code> ordering. Docs: https://docs.amity.co/amity-sdk/social/posts/query-post
    API: add <code>isDeleted=false</code> param.
```bash
curl --location 'https://api.sg.amity.co/api/v3/communities?filter=all&isDeleted=false' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
```
    SDK: set <code>includeDeleted</code> (or <code>includeDelete</code>) flag false. Docs: https://docs.amity.co/amity-sdk/social/communities/query-communities
    Only the current authenticated user can list their joined communities (<code>filter=member</code>). Privacy prevents enumerating others' memberships.
```bash
curl --location 'https://api.sg.amity.co/api/v3/communities?filter=member' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
```
    Standard page size is 20. Use <code>paging.next</code> (API) or <code>nextPage()</code> (SDK live collections) to iterate. See Live Objects & Collections docs.
    API (Add roles):
```bash
curl --location 'https://api.sg.amity.co/api/v4/communities/COMMUNITY_ID/users/roles' \
  --header 'accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxx' \
  --data '{"roles":["community-moderator"],"userIds":["test"]}'
```
    Console path: Community > Members > (⋮) beside user > Change user role.
    <img src=".gitbook/assets/Screenshot 2566-12-21 at 22.53.59.png" alt="Change user role screenshot" data-size="original" />
    Use SDK moderation APIs or <a href="https://api-docs.amity.co/#/Community/delete_api_v3_communities__communityId__users">Delete community users</a> endpoint.
    Delete via API (<a href="https://api-docs.amity.co/#/Community/delete_api_v3_communities__communityId_">delete community</a>) or close in Console: Communities > select > Settings > Close Community.
    <img src=".gitbook/assets/Screenshot 2566-12-21 at 15.59.45.png" alt="Close community screenshot" data-size="original" />
    Auto-join starter communities immediately after user creation (call Join Community API) so their feed contains initial posts.
    Lightweight extensible key/value storage for custom attributes (e.g. user tier). Not for large blobs or high-write analytics fields.
    User has no joined communities and follows no users. Ensure onboarding joins at least one community or recommends follows.
    Formats: JPG, PNG. Max size: 1 GB. Up to 10 images per post. UIKit v4 auto-converts unsupported formats (e.g. HEIC) client-side.
    Formats: 3gp, avi, f4v, flv, m4v, mov, mp4, ogv, 3g2, wmv, vob, webm, mkv. Max 1 GB, ≤ 2 hours, ≤ 10 videos/post. HEVC/HDR converted in UIKit v4.
    Provide only auth token to SDK during login; SDK handles session/access token internally. Docs: user creation page.
    Global feed may use custom ranking (engagement, freshness blend). Contact support to adjust configuration. See Custom Post Ranking docs.
    Call <code>queryCommunities(&#123; filter: 'membership' &#125;)</code>. Docs: /social/communities/query-communities.
    Construct download URL: <code>https://api.{region}.amity.co/api/v3/files/{fileId}</code>. Retrieve fileId from message/post objects via SDK.
    Customize RecentChat component: on mount select first channel when list populated (example previously shown) to avoid blank panel.
    Use conversation channel creation endpoint in idempotent mode (or SDK convenience) which returns existing if already present.
    Append repeated <code>tags[]=</code> query params.
```bash
curl --location --globoff 'https://api.sg.amity.co/api/v4/posts?targetId=COMMUNITY_ID&targetType=community&sortBy=lastCreated&tags[]=tag1&tags[]=tag2' \
  --header 'accept: application/json' \
  --header 'Authorization: Bearer xxx'
```
    Not supported; comments are fetched by post. Store needed mappings externally if user-centric aggregation required.
    Configure who can join and what they can do.<br/>
    First, set your community or network membership mode (open, request/approval, or invite‑only) so users either join freely or require approval/invites.<br/>
    Then, define role types (e.g. admin, moderator, member, guest) and assign them to users to control permissions like posting, moderating, and managing settings.<br/>
    Review these settings regularly to match your business rules and compliance needs.
    AI is used to evaluate the livestream going on and based on the defined confidence levels, if the content is considered as not adequate it will be automatically terminated. More details about how our AI Livestream moderation works can be found <a href="https://learn.social.plus/analytics-and-moderation/console/moderation/livestream-moderation#livestream-moderation ">here</a>.
    Yes, you can search for chat messages by calling the following <a href="https://api.docs.social.plus/#tag/message/get/api/v2/search/messages">API</a>. At the same time, we do have this feature available in our Flutter SDK.

***

## UIKits and SDKs

    Ensure ALL of:
    <ul>
      <li>Production APNs cert or key uploaded (Sandbox & Production) and not expired</li>
      <li>App capability: Push Notifications enabled</li>
      <li>Correct <code>app_id</code> matches certificate</li>
      <li>Running on real device (not simulator) and production/TestFlight build when testing prod cert</li>
      <li>User granted notification permission & device not in Do Not Disturb / Focus</li>
      <li>APNs key also uploaded to Firebase if using FCM bridge (<a href="https://firebase.google.com/docs/cloud-messaging/ios/client#upload_your_apns_authentication_key">docs</a>)</li>
    </ul>
    Docs: certificate setup & register/unregister pages.
    Not supported. Ship with bundled Realm version aligned to SDK. See iOS SDK & UIKit changelogs for compatibility matrix.
    Upload APNs (.p12 or key) selecting "Apple Push Notification service SSL (Sandbox & Production)" so a single cert covers both.
    Not recommended / unsupported. Use a package manager (npm, Yarn, pnpm) for versioned SDK distribution.
    Query the users you blocked with `getBlockedUsers()` / `getAllBlockedUsers()`. To read the reverse direction — users who blocked you — use `getBlockingUsers()` / `getAllBlockingUsers()`. Docs: [Manage Blocked Users](/social-plus-sdk/social/user-relationship/blocking/manage-blocked-users) and [Users Who Blocked You](/social-plus-sdk/social/user-relationship/blocking/manage-blocking-users).
    Call SDK mark-read API or start/stop reading subchannel utilities (unread-count docs). Ensures backend updates unread counters.
    Poll post type not yet supported in current Flutter SDK (only video/image/file). Track changelog for availability.
    The SDK provides two methods:<br/>
        •        Search Users — Find users by displayName (min 3 characters), ranked by relevance<br/>
        •        Query Users — Retrieve users with sorting (displayName, firstCreated, lastCreated)<br/>

    <a href="https://learn.social.plus/social-plus-sdk/core-concepts/user-management/user-operations/search-and-query-users">Full documentation</a>
    1. Create keys/certs in Apple Developer
      * In Apple Developer account, create an APNs Auth Key (.p8) with Push Notifications enabled.
      * Note the Key ID, Team ID, and download the .p8 file.
    2. Configure your backend / social.plus console
        * Go to your project’s Notifications → Apple (iOS) page.
        * Upload the .p8 file, fill in Key ID, Team ID, and Bundle ID, then click Activate.
    3. Enable push in Xcode
        * Open your app target → Signing & Capabilities.
        * Add Push Notifications and (if needed) Background Modes → Remote notifications.
        * Make sure you use a provisioning profile that includes push.
    4. Request permission and get APNs token
        * In your app, ask for notification permission on first launch (UNUserNotificationCenter).
        * Implement application(_:didRegisterForRemoteNotificationsWithDeviceToken:) to get the APNs device token.
    5. Register token with your SDK
        * Native iOS: pass the APNs token via `client.registerPushNotification(withDeviceToken:)` (iOS SDK API — not available in the TypeScript SDK).
        * React Native: pass the token as `fcmToken={apnsToken}` to `AmityUiKitProvider`; `@amityco/ts-sdk` does not expose a client-side push registration API.
    6.  Test real production push notifications.<br/>
        * Install a TestFlight (release) build on a physical iPhone (push notifications are not supported on simulators).
        * Trigger a real notification from your production backend or console, and verify that it is successfully delivered and displayed on the device.
    Metadata in posts and comments is an optional Object field for storing additional custom properties. To configure it correctly:

    Pass metadata as a JSON object (e.g; "key": "value") when creating or updating posts/comments.
    Metadata patching is allowed for all post types via the patch <a href="https://learn.social.plus/api-reference/post/patch-post-data-and-metadata"> post data and metadata API</a> using set/delete operations.
    There is no strict schema, it accepts arbitrary key-value pairs for your custom needs.
    The Social plus Portal is your organization-level management platform where you create and manage applications, handle billing, and control team access. Each application lives in its own Console, where you configure settings, moderate content, manage users, and grab your API key for integration.
    iOS (UIKit):

    * Add AmitySDK and AmityUIKit4 via Swift Package Manager in Xcode.

    * Link to your app target and initialize in AppDelegate.

    Android (UIKit):

    * Add Amity SDK and UIKit dependencies in your Gradle files.

    * Initialize SDK in your Application class.
    Visitor Secure Mode is also available for UIKit. We will publish documentation about this soon. In the meantime, please contact us if you would like to use it.
    Currently our stories feature is based on communities, which means that user can create stories but they need to be directed to a specific community. <br/>
    More details about our story features can be found <a href="https://learn.social.plus/social-plus-sdk/social/content-management/stories/overview">here</a>.
    The SocialPlus SDK supports real-time updates through its built-in real-time event system. This system maintains persistent connectivity to deliver live updates such as new posts, comments, reactions, notifications, and membership changes. If you are using the SDK directly, developers subscribe to the relevant real-time event topics (for example communities, posts, comments, or user updates). Once subscribed, the SDK automatically keeps the observed objects and collections synchronized. If you are using UIKit, this real-time functionality is already integrated for the supported features, so no additional implementation is required.<br/>
    More details about the real-time event model can be found <a href="https://learn.social.plus/social-plus-sdk/core-concepts/realtime-communication/realtime-events/overview">here</a>.
    Our open soure UIKits are fully customisable, so you can change any part of them. You can select between multiple components and based on them get the right version you are looking for. The idea of these UIKits is to help you accelerate implementation, making it easir to have our features available.

***

## Poll

    Call Get Poll Answer endpoint to retrieve voters (userIds) for specific answerId. Ref: API docs.
    Not supported: create either a poll OR other attachment types, not combined.
    Not directly. Use Portal: My Dashboard > Posts and filter type=Poll. (Console UI lacks poll list.)
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 13.49.24.png" alt="Poll posts screenshot" data-size="original" />

***

## Console

    Console: Settings &gt; Admin Users &gt; (cog icon). Screenshot below.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 14.50.43 1.png" alt="Admin token screenshot" data-size="original" />
    Admin user creates others: Settings &gt; Admin Users &gt; Create New Admin (top right) then share credentials securely.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 14.56.55.png" alt="Create admin screenshot" data-size="original" />
    Only portal owner initially. Use "+ Add new certificate" button in Push Notification section.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 15.13.36.png" alt="Add certificate screenshot" data-size="original" />
    User option fetches user feed posts only; not a cross-community aggregation by userId.
    Console: Settings &gt; Security tab shows API key and region endpoint.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 15.15.33.png" alt="Security tab screenshot" data-size="original" />
    Performed by super admin; user-level self-service not provided.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 11.53.57.png" alt="Password change screenshot" data-size="original" />
    Hidden by design (privacy / noise). See Channel Characteristics docs for rationale.
    Only one active push certificate per platform allowed simultaneously.

***

## Portal

    Portal: Create Application button (top right). Use distinct apps per environment to isolate data & config.
    <img src=".gitbook/assets/Screenshot 2566-12-08 at 18.13.22.png" alt="Create application screenshot" data-size="original" />
    In-place upgrade unavailable; create new application with desired plan, migrate, then retire old one.
    Portal: Manage Payment tab &gt; update Organization Name.
    <img src=".gitbook/assets/Screenshot 2567-09-24 at 15.16.06.png" alt="Manage payment screenshot" data-size="original" />
    The social.plus Portal does not support deleting applications once created, an app remains in your list permanently. You can only rename existing apps to keep things organized, and if you're nearing the 50-app cap, contact support to request a limit increase.

***

## Alternative solutions for unsupported features

    Store array of postIds in user metadata (e.g. <code>favorites</code>). On profile render, fetch posts by those IDs.
    Add <code>metadata.verified=true</code> (or role) on user; frontend displays badge based on flag.
    New post with metadata.originalPostID referencing source. On display, fetch original, render nested.
    Subscribe to webhook (post flagged) then trigger email via external service. See Real-time Events & WebhookEvent docs.
    Store pinned postId in community metadata (e.g. <code>pinPostID</code>) and prepend when rendering feed if present.
    UI hide non-admin button (weak) OR enforce via Pre-Hook Event (Max package) to reject non-admin create attempts.
    Client filter after fetching OR use search/posts (beta) filtering by type then show results.
    Capture duration client-side after record; store in message metadata; display using stored value.
    Use Search Post API with <code>postedUserId</code> param (beta feature) to filter.
    GIF upload is <a href="https://learn.social.plus/social-plus-sdk/technical-faq#gif-support">not</a> natively supported by Social plus currently. As a workaround, GIFs can be uploaded via the Upload File API, and clients can customize the UI rendering on their end to display them.

***

## Beta features

    Use webhook events backend -> push service to send notifications (posts/comments). Reference WebhookEvent list.
    Only indexes posts created after feature enablement; earlier posts excluded.
    Include <code>hashtagList</code> in content search query.
```json
{
  "hashtagList": ["#tags1", "#tags2", "#tags3"]
}
```
    Subscribe to follow create / follow request webhooks, then dispatch notification to target user.

***

## Frequent error types: Definition

    Occurs when SDK calls made before session established. Wait until session state == <code>established</code> (listen to session state changes) before repository operations.
    Use the <code>paging.next</code> (or previous) token from prior response. Do not reuse stale/modified tokens.
    Queue actions until login promise resolves; avoid concurrent login + API operations.
    More than 100 calls per user within 5s. Debounce, batch, or add exponential backoff; remove accidental loops.
    Triggered by image moderation threshold. Adjust confidence level or disable temporarily in Settings &gt; Image Moderation.
    Link moderation allow list enforced. Add domain to Allow list or disable link moderation.

***

## General

    Permanent. Delete user API cannot be undone.
    Iterate list of users meeting inactivity criteria then call DELETE user API (example with flags). Irreversible.
    User cannot authenticate; removed from channels; messages deleted (cache may persist until refresh); social content intact.
    Per active WebSocket/tab. Background/inactive tabs may auto-disconnect reducing CCU.
    No native dark theme; customize via open-source UIKit theming.
    Contact support (support.asc@amity.co) to remove.
    Registered but no connections in the month being measured (historic register date irrelevant).
    Social: https://www.amity.co/social/uikit#figma  | Chat: https://www.amity.co/chat/uikit#figma
    Achieved via multiple applications; strict data isolation per app.
    Not supported; must upload through social.plus SDK/API to store & moderate.
    Not exposed; metrics available per application (Dashboard/Console). Use Portal Dashboard Guide for details.
    Backend stores plain text (security). Implement client-side markup (e.g. markdown) and render safely.
    GIF upload not supported currently.
    You can extract at any point your data by calling our APIs:<a href="https://api.docs.social.plus/#description/using-social-apis.">#description/using-social-apis</a>.<br/>
    In case you want some built-in reports that contain some of the most recent data and metrics, you can call our 1st party data API: <a href="https://api.docs.social.plus/#tag/admin/get/api/v1/reports/1p/download.">#tag/admin/get/api/v1/reports/1p/download.</a> <br/>
    To see further detail, please access here: <a href="https://learn.social.plus/api-reference/admin/get-first-party-data-export#get-first-party-data-export">#get-first-party-data-export</a>
    We recommend keeping your SDK/UIKit updated to the latest version whenever possible. However, if you are not encountering any bugs or do not require new features that are supported by new version of SDK/UIKit, an immediate update may not be strictly necessary.

***

## Dashboard

    Users who view content without active engagement (posting/commenting/reactions).
    Dashboard &gt; Channels section &gt; "New Messages by Day" widget.
    <img src=".gitbook/assets/Screenshot 2567-03-22 at 12.19.36.png" alt="New messages widget screenshot" data-size="original" />

---

### [Developer Forum](https://learn.social.plus/social-plus-sdk/developer-forum)

> Use the social.plus Developer Forum and support resources when SDK docs do not answer your integration question.

The Developer Forum is the right place to ask integration questions, report documentation gaps, and share implementation context that does not fit into a single docs page.

  Keep SDK questions specific to platform, SDK version, feature area, expected behavior, and actual behavior. That makes the answer useful for both your team and future readers.

## When to Use It

| Situation | Best next step |
| --- | --- |
| You need help choosing an SDK feature path | Start with the relevant SDK overview, then post your target platform and product goal if the choice is still unclear. |
| A snippet or page seems wrong | Link the docs page, include the SDK version, and share the smallest reproducible code shape. |
| Runtime behavior differs from the docs | Include platform, SDK version, region, entity IDs where safe, timestamps, and any error codes. |
| You are asking for a new capability | Explain the user scenario, scale, launch timeline, and fallback you are considering. |
| A service appears degraded | Check the status page before opening an implementation thread. |

## Before You Post

    Check the feature page, platform notes, and changelog for your SDK.
    Include the SDK platform, package version, app platform version, and region.
    State whether you are using SDK, UIKit, REST API, or a mixed approach.
    Keep secrets, tokens, API keys, and private user data out of the post.

## Useful Links

    Ask implementation questions and share documentation feedback.
    Check service availability before debugging an integration issue.
    Discuss commercial fit, plans, or procurement questions.

## Related Docs

    Check common SDK integration answers before opening a thread.
    Review platform release notes when behavior changed after an upgrade.

---

### [Chat Data Model Reference](https://learn.social.plus/api-reference/chat-data-model)

> Core chat and messaging entities, fields, relationships, and data import guidance for engineers working with the social.plus API

The chat module provides real-time messaging through **channels** (group chats, direct conversations, broadcasts). Users join channels as **channel users**, exchange **messages** within **message feeds** (threads), and can attach media, reactions, and mentions.

Channels are the top-level container. Each channel has one or more **message feeds** (threads), and each feed contains **messages** ordered by a monotonically increasing `segment`. Messages support threading via a self-referential `parentId`.

**Who is this for?** This reference describes the core chat server data model. It's essential for data import, analytics integration, and understanding API response structures. For social entities (User, Community, Post, Comment, etc.), see the [Social Data Model Reference](/api-reference/social-data-model).

    6 core entities with full field definitions, types, and relationship mappings
    Message threading, channel–community linking, and feed structure
    Enum values and 8 practical data import guidelines

## Conventions

| Convention            | Description                                                                                                                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Triple-ID pattern** | Most entities expose three IDs: a primary `{entity}Id`, a `{entity}PublicId` (stable external identifier), and a `{entity}InternalId` (database-level reference). For joins, prefer public IDs. |
| **Soft delete**       | Nearly every entity has an `isDeleted` boolean. Deleted records remain in the database with `isDeleted: true`. Filter these out unless you specifically need deletion history.                  |
| **Timestamps**        | `createdAt` and `updatedAt` (ISO 8601 date-time) are present on all entities. Some also have `editedAt`.                                                                                        |
| **Metadata**          | A freeform `metadata` object is available on most entities for custom fields.                                                                                                                   |
| **Flagging**          | `flagCount` (number of reports) and `hashFlag` (bloom-filter structure) track moderation state on messages. Channels bubble up flags via `hasFlaggedMessage`.                                   |

## Entity-Relationship Diagram

The following diagram shows the core entities and their relationships in the chat module.

```mermaid placement="top-left" actions={true}
erDiagram
    User {
        string userId PK
    }
    Community {
        string communityId PK
        string channelId FK
    }
    Channel {
        string channelId PK
        string avatarFileId FK
    }
    ChannelUser {
        string userId FK
        string channelId FK
    }
    MessageFeed {
        string messageFeedId PK
        string channelId FK
        string creatorId FK
    }
    Message {
        string messageId PK
        string messageFeedId FK
        string parentId FK
        string creatorId FK
    }
    Reaction {
        string reactionId PK
        string userId FK
        string referenceId FK
    }
    File {
        string fileId PK
    }
    Room {
        string roomId PK
    }

    %% === Relationships ===

    Community ||--o| Channel : "backed by (1:1)"
    Channel ||--o{ ChannelUser : "has members"
    User ||--o{ ChannelUser : "joins channels"
    Channel ||--o{ MessageFeed : "contains feeds"
    MessageFeed ||--o{ Message : "contains messages"
    User ||--o{ Message : "creates"
    Message ||--o{ Message : "parent → replies"
    Message }o--o| File : "attaches media"
    Message ||--o{ Reaction : "receives reactions"
    User ||--o{ Reaction : "creates"
    Channel }o--o| File : "avatar"
    Room }o--o| Channel : "live chat"
```

## Entity Reference

    A chat room, conversation, or group. Channels are the top-level container for messaging. Every community has a 1:1 backing channel. Channels can be standard (open), private, direct conversations, broadcast, community-backed, or live (attached to a room).

    | Field                          | Type      | Description                                                                        |
    | ------------------------------ | --------- | ---------------------------------------------------------------------------------- |
    | `channelId`                    | string    | **Primary key.** Public channel identifier.                                        |
    | `channelInternalId`            | string    | Internal database identifier.                                                      |
    | `channelPublicId`              | string    | Public identifier (same as `channelId`).                                           |
    | `type`                         | enum      | `standard` \| `private` \| `conversation` \| `broadcast` \| `community` \| `live`. |
    | `displayName`                  | string    | Channel display name.                                                              |
    | `isDistinct`                   | boolean   | If true, reuses existing channel for the same user set (conversations).            |
    | `tags`                         | string[]  | Tags for filtering/categorization.                                                 |
    | `metadata`                     | object    | Arbitrary custom fields.                                                           |
    | `avatarFileId`                 | string    | FK → File. Channel avatar image.                                                   |
    | `lastActivity`                 | date-time | Timestamp of last activity (message, event, etc.).                                 |
    | `memberCount`                  | integer   | _(Computed)_ Number of members.                                                    |
    | `messageCount`                 | integer   | _(Computed)_ Number of messages.                                                   |
    | `moderatorMemberCount`         | integer   | Count of moderator members.                                                        |
    | `isPublic`                     | boolean   | Whether channel is publicly listed.                                                |
    | `notificationMode`             | enum      | `default` \| `silent` \| `subscribe`.                                              |
    | `isMuted`                      | boolean   | _(Computed)_ Whether the channel is currently muted (based on `muteTimeout`).      |
    | `muteTimeout`                  | date-time | When the channel-level mute expires.                                               |
    | `isRateLimited`                | boolean   | _(Computed)_ Whether rate limiting is active (based on `rateLimitTimeout`).        |
    | `rateLimit`                    | number    | Maximum messages per rate limit window.                                            |
    | `rateLimitWindow`              | number    | Rate limit window in milliseconds.                                                 |
    | `rateLimitTimeout`             | date-time | When the current rate limit expires.                                               |
    | `messageAutoDeleteEnabled`     | boolean   | Whether auto-delete by flag threshold is enabled.                                  |
    | `autoDeleteMessageByFlagLimit` | number    | Flag count threshold for auto-deletion.                                            |
    | `messagePreviewId`             | string    | _(Computed)_ ID of the latest message preview.                                     |
    | `pinnedMessage`                | object    | The channel's single pinned message (`live` channels only). `null` when nothing is pinned. Carries the message body plus `pinnedBy` and `pinnedAt`. |
    | `attachedTo`                   | object    | Linked resources: `{postId, videoStreamId, roomId}`.                               |
    | `isDeleted`                    | boolean   | Soft-delete flag.                                                                  |
    | `createdAt`                    | date-time | Creation timestamp.                                                                |
    | `updatedAt`                    | date-time | Last update timestamp.                                                             |

    **Relationships:**
    - `1:1` → Community (community-type channels back a community; see [Channel ↔ Community Relationship](#channel--community-relationship))
    - `1:N` → ChannelUser (members)
    - `1:N` → MessageFeed (message threads within the channel)
    - `0:1` → Room (live-type channels are attached to a room via `attachedTo.roomId`)
    - `0:1` → File (avatar via `avatarFileId`)

```mermaid placement="top-left" actions={true}
erDiagram
    Community ||--o| Channel : "backed by (1:1)"
    Channel ||--o{ ChannelUser : "has members"
    Channel ||--o{ MessageFeed : "contains feeds"
    Room }o--o| Channel : "live chat"
    Channel }o--o| File : "avatar"
```

    The **join entity** between User and Channel. Represents a user's membership, roles, and read state within a channel.

    | Field                  | Type      | Description                                       |
    | ---------------------- | --------- | ------------------------------------------------- |
    | `userId`               | string    | FK → User. User's public ID.                      |
    | `userInternalId`       | string    | User's internal ID.                               |
    | `userPublicId`         | string    | User's public ID.                                 |
    | `channelId`            | string    | FK → Channel. Channel's public ID.                |
    | `channelInternalId`    | string    | Channel's internal ID.                            |
    | `channelPublicId`      | string    | Channel's public ID.                              |
    | `membership`           | enum      | `none` \| `member` \| `banned`.                   |
    | `roles`                | string[]  | Role public IDs assigned within this channel.     |
    | `permissions`          | string[]  | Resolved permissions from roles.                  |
    | `isBanned`             | boolean   | _(Computed)_ `true` when `membership = "banned"`. |
    | `isMuted`              | boolean   | _(Computed)_ `true` when `muteTimeout > now`.     |
    | `muteTimeout`          | date-time | When the user-level mute expires in this channel. |
    | `readToSegment`        | number    | Last-read message segment (read cursor).          |
    | `lastMentionedSegment` | number    | Segment of last @mention for this user.           |
    | `lastActivity`         | date-time | User's last activity in the channel.              |
    | `createdAt`            | date-time | Record creation timestamp.                        |
    | `updatedAt`            | date-time | Last update timestamp.                            |

    **Relationships:**
    - `N:1` → User
    - `N:1` → Channel
    - Composite key: (`userId`, `channelId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ ChannelUser : "joins channels"
    Channel ||--o{ ChannelUser : "has members"
```

    A message within a channel. Messages belong to a MessageFeed and support threading (replies). Each message is stored as its own document.

    | Field             | Type      | Description                                                                            |
    | ----------------- | --------- | -------------------------------------------------------------------------------------- |
    | `messageId`       | string    | **Primary key.** Internal message ID.                                                  |
    | `publicId`        | string    | Public-facing message ID.                                                              |
    | `channelId`       | string    | FK → Channel. Channel this message belongs to.                                         |
    | `channelPublicId` | string    | Channel's public ID.                                                                   |
    | `messageFeedId`   | string    | FK → MessageFeed. The feed/thread containing this message.                             |
    | `parentId`        | string    | FK → Message (self). Parent message ID for replies. `null` for top-level messages.     |
    | `creatorId`       | string    | FK → User. Creator's internal ID.                                                      |
    | `creatorPublicId` | string    | Creator's public ID.                                                                   |
    | `dataType`        | enum      | `text` \| `image` \| `video` \| `file` \| `audio` \| `custom` \| `json` \| `imagemap`. |
    | `data`            | object    | Message payload. For media types, includes `fileId` and optionally `thumbnailFileId`.  |
    | `segment`         | number    | Ordering position within the feed.                                                     |
    | `tags`            | string[]  | Tags associated with this message.                                                     |
    | `metadata`        | object    | Arbitrary custom fields.                                                               |
    | `mentionedUsers`  | array     | Mentioned users: `[{type: "user"\|"channel", userIds: [...]}]`.                        |
    | `childCount`      | integer   | Number of direct replies.                                                              |
    | `reactions`       | object    | Map of `reactionName → count`.                                                         |
    | `reactionCount`   | integer   | Total reaction count.                                                                  |
    | `myReactions`     | string[]  | Current user's reaction names.                                                         |
    | `flagCount`       | integer   | Number of moderation reports.                                                          |
    | `hashFlag`        | object    | _(Computed)_ Bloom-filter flag structure.                                              |
    | `editedAt`        | date-time | Last content edit timestamp.                                                           |
    | `isDeleted`       | boolean   | Soft-delete flag.                                                                      |
    | `createdAt`       | date-time | Creation timestamp.                                                                    |
    | `updatedAt`       | date-time | Last update timestamp.                                                                 |

    **Threading model:** See [Message Threading Model](#message-threading-model) below for details on how replies work.

    **Relationships:**
    - `N:1` → User (creator via `creatorId`)
    - `N:1` → Channel (via `channelId`)
    - `N:1` → MessageFeed (via `messageFeedId`)
    - `1:N` → Message (replies via `parentId`, self-referential)
    - `1:N` → Reaction (via `reaction.referenceId` where `referenceType = "message"`)
    - `0:1` → File (attachment via `data.fileId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Message : "creates"
    MessageFeed ||--o{ Message : "contains"
    Message ||--o{ Message : "parent has replies"
    Message ||--o{ Reaction : "receives"
    Message }o--o| File : "attaches media"
```

    A message thread/feed within a channel. Each channel has one or more message feeds. The feed tracks the latest message and provides a message preview for UI display.

    | Field                  | Type      | Description                                                                                      |
    | ---------------------- | --------- | ------------------------------------------------------------------------------------------------ |
    | `messageFeedId`        | string    | **Primary key.**                                                                                 |
    | `channelId`            | string    | FK → Channel. The channel this feed belongs to.                                                  |
    | `channelPublicId`      | string    | Channel's public ID.                                                                             |
    | `channelType`          | enum      | Channel type: `standard` \| `private` \| `conversation` \| `broadcast` \| `community` \| `live`. |
    | `name`                 | string    | Feed display name.                                                                               |
    | `creatorId`            | string    | FK → User. Feed creator's internal ID.                                                           |
    | `creatorPublicId`      | string    | Creator's public ID.                                                                             |
    | `lastMessageId`        | string    | FK → Message. Most recent message.                                                               |
    | `lastMessageTimestamp` | date-time | Timestamp of the most recent message.                                                            |
    | `messagePreviewId`     | string    | _(Computed)_ ID of the preview message.                                                          |
    | `childCount`           | integer   | Number of messages in this feed.                                                                 |
    | `isDeleted`            | boolean   | Soft-delete flag.                                                                                |
    | `editedAt`             | date-time | Last metadata edit timestamp.                                                                    |
    | `createdAt`            | date-time | Creation timestamp.                                                                              |
    | `updatedAt`            | date-time | Last update timestamp.                                                                           |

    **Relationships:**
    - `N:1` → Channel (via `channelId`)
    - `N:1` → User (creator via `creatorId`)
    - `1:N` → Message (messages reference feed via `messageFeedId`)

```mermaid placement="top-left" actions={true}
erDiagram
    Channel ||--o{ MessageFeed : "contains feeds"
    User ||--o{ MessageFeed : "creates"
    MessageFeed ||--o{ Message : "contains messages"
```

    Tracks reactions (likes, love, etc.) on messages. **Each reaction is stored as its own document** — one document per user-reaction-reference combination. Reactions use a **polymorphic reference** that supports multiple content types across both chat and social modules.

    | Field            | Type      | Description                                                                           |
    | ---------------- | --------- | ------------------------------------------------------------------------------------- |
    | `reactionId`     | string    | **Primary key.** Unique reaction instance ID.                                         |
    | `reactionName`   | string    | Freeform name, e.g., `"like"`, `"love"`, `"wow"`.                                     |
    | `userId`         | string    | FK → User. Who reacted.                                                      |
    | `userInternalId` | string    | Reactor's internal ID.                                                                |
    | `referenceId`    | string    | FK → Message (in chat context). The content being reacted to.                         |
    | `referenceType`  | enum      | `post` \| `comment` \| `story` \| `message`. For chat, this is always `message`.      |
    | `createdAt`      | date-time | When the reaction was added.                                                          |
    | `updatedAt`      | date-time | When the reaction was last updated.                                                   |

    Reaction names are **freeform strings**, not a fixed enum. The `reactions` field on Message aggregates these as `{reactionName: count}`. The same Reaction entity is shared across both social and chat modules — only the `referenceType` differs.

    **Relationships:**
    - `N:1` → Message (when `referenceType = "message"`)
    - `N:1` → User (via `userId`)

```mermaid placement="top-left" actions={true}
erDiagram
    Message ||--o{ Reaction : "receives (referenceType=message)"
    User ||--o{ Reaction : "creates"
```

    An uploaded media file (image, video, audio, or generic file). Files are referenced by messages and channels via `fileId`. The File entity is shared across both social and chat modules.

    | Field                  | Type      | Description                                                                                                                                                           |
    | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `fileId`               | string    | **Primary key.** Cloud storage key.                                                                                                                                   |
    | `fileUrl`              | string    | HTTP download URL.                                                                                                                                                    |
    | `type`                 | enum      | `image` \| `file` \| `video` \| `audio` \| `clip`.                                                                                                                    |
    | `accessType`           | enum      | `public` (open download) \| `network` (requires authentication).                                                                                                      |
    | `altText`              | string    | Alternative text (max 180 chars).                                                                                                                                     |
    | `feedType`             | string    | Feed type associated with this file.                                                                                                                                  |
    | `status`               | enum      | `uploaded` \| `transcoding` \| `transcoded` \| `transcodeFailed`. Processing status (mainly for video/audio).                                                         |
    | `isDeleted`            | boolean   | Soft-delete flag.                                                                                                                                                     |
    | `videoUrl`             | object    | Video URLs by resolution: `{1080p, 720p, 480p, 360p, original}`. Present for video files.                                                                             |
    | `attributes.name`      | string    | Original file name.                                                                                                                                                   |
    | `attributes.extension` | string    | File extension/format.                                                                                                                                                |
    | `attributes.size`      | number    | File size in bytes.                                                                                                                                                   |
    | `attributes.mimeType`  | string    | MIME type.                                                                                                                                                            |
    | `attributes.metadata`  | object    | _(Schemaless)_ Additional metadata. May contain `width`, `height`, `exif`, `gps` if set by the uploading client, but these sub-fields are not enforced by the schema. |
    | `createdAt`            | date-time | Upload timestamp.                                                                                                                                                     |
    | `updatedAt`            | date-time | Last update timestamp.                                                                                                                                                |

    **Relationships:**
    Referenced by: Message (`data.fileId`, `data.thumbnailFileId`), Channel (`avatarFileId`).

```mermaid placement="top-left" actions={true}
erDiagram
    Message }o--o| File : "attaches media"
    Channel }o--o| File : "avatar"
```

## Message Threading Model

Messages support single-level threading within a message feed:

```mermaid placement="top-left" actions={true}
graph TD
    MF["<b>MessageFeed</b><br/>messageFeedId"]
    A["<b>Message A</b><br/>parentId = null<br/>segment = 1"]
    A1["<b>Reply A1</b><br/>parentId = A<br/>segment = 2"]
    A2["<b>Reply A2</b><br/>parentId = A<br/>segment = 3"]
    B["<b>Message B</b><br/>parentId = null<br/>segment = 4"]
    C["<b>Message C</b><br/>parentId = null<br/>segment = 5"]
    C1["<b>Reply C1</b><br/>parentId = C<br/>segment = 6"]

    MF --> A
    MF --> B
    MF --> C
    A --> A1
    A --> A2
    C --> C1

    style MF fill:#e1f5fe,stroke:#0288d1
    style A fill:#e8f5e9,stroke:#388e3c
    style B fill:#e8f5e9,stroke:#388e3c
    style C fill:#e8f5e9,stroke:#388e3c
    style A1 fill:#fff3e0,stroke:#f57c00
    style A2 fill:#fff3e0,stroke:#f57c00
    style C1 fill:#fff3e0,stroke:#f57c00
```

    **Top-level messages** have `parentId = null`. They belong directly to the feed.
    **Replies** have `parentId` set to the parent message's ID.
    `childCount` on each message tracks its direct reply count.
    Messages are ordered by `segment` within their feed (monotonically increasing). All messages (top-level and replies) live in the same feed and share the same segment counter.

### Reconstructing Threads

1. Query messages by `messageFeedId`.
2. Top-level messages: `parentId = null`.
3. Group replies by `parentId`.
4. Order all messages by `segment`.

## Channel ↔ Community Relationship

Every community in the social module has a 1:1 backing channel with `type = "community"`. This relationship connects the social and chat modules:

```mermaid placement="top-left" actions={true}
graph LR
    COM["<b>Community</b><br/>communityId"]
    CH["<b>Channel</b><br/>channelId<br/>type = community"]

    COM -- "community.channelId = channel.channelId" --> CH

    style COM fill:#e8f5e9,stroke:#388e3c
    style CH fill:#e1f5fe,stroke:#0288d1
```

**Cross-module linking:** The Community entity stores a `channelId` foreign key pointing to its backing channel. Community-type channels inherit the community's membership — a user who is a community member is also a channel member. When importing data that spans both modules, ensure the Community's `channelId` FK is correctly linked.

## Key Enums Reference

  | Enum                         | Values                                                                  | Used By                     |
  | ---------------------------- | ----------------------------------------------------------------------- | --------------------------- |
  | **Channel.type**             | `standard`, `private`, `conversation`, `broadcast`, `community`, `live` | Channel `.type`             |
  | **Channel.notificationMode** | `default`, `silent`, `subscribe`                                        | Channel `.notificationMode` |
  | **ChannelUser.membership**   | `none`, `member`, `banned`                                              | ChannelUser `.membership`   |
  | **Message.dataType**         | `text`, `image`, `video`, `file`, `audio`, `custom`, `json`, `imagemap` | Message `.dataType`         |
  | **Reaction.referenceType**   | `post`, `comment`, `story`, `message`                                   | Reaction `.referenceType`   |

## Data Import Tips

    Most entities expose three IDs (`channelId`, `channelPublicId`, `channelInternalId`). For joining data across entities, **use the public ID** — these are the values used in foreign key references. Internal IDs are database-level identifiers and may not appear in all API responses.

    Every community has a 1:1 backing channel (with `type = "community"`). When importing both communities and channels, ensure corresponding records are linked. The community stores a `channelId` foreign key.

    Messages within a feed are ordered by `segment` (a monotonically increasing integer). **Preserve segment ordering** during import to maintain correct message sequence. Each feed maintains its own independent segment counter.

    The ChannelUser entity uses a composite key of (`userId`, `channelId`). When importing, deduplicate on **both** fields to avoid creating duplicate membership records.

    Several fields are derived at read time and should **not** be imported as stored values:

    - `Channel.isMuted` — derived from `muteTimeout > now`.
    - `Channel.isRateLimited` — derived from `rateLimitTimeout > now`.
    - `Channel.memberCount` / `messageCount` — aggregated from related records.
    - `ChannelUser.isBanned` — derived from `membership = "banned"`.
    - `ChannelUser.isMuted` — derived from `muteTimeout > now`.
    - `Message.myReactions` — derived per-request for the current user.
    - `MessageFeed.messagePreviewId` — derived from latest message.

    Soft-deleted records have `isDeleted: true`. **Exclude these by default** for analytics unless you need deletion history.

    Message reactions follow the same model as social reactions (see [Social Data Model Reference](/api-reference/social-data-model)). Each reaction is stored as a separate document with `referenceType = "message"` and `referenceId` pointing to the message. The `reactions` object on Message provides pre-aggregated `{name: count}` maps.

    To get only top-level messages (not replies), filter by `parentId = null`. To reconstruct threads, group replies by `parentId` and order by `segment`. See [Message Threading Model](#message-threading-model) for the full pattern.

## Related Topics

    Core social entities — User, Community, Post, Comment, Reaction, and more
    Server-to-server API capabilities, authentication methods, and getting started guide
    Client-side SDK implementation for channels, messaging, and real-time chat features

---

### [Social Data Model Reference](https://learn.social.plus/api-reference/social-data-model)

> Core social entities, fields, relationships, polymorphic patterns, and data import guidance for engineers working with the social.plus API

The social module is built around a set of interconnected entities that model a social network: **users** create and join **communities**, publish **posts** and **stories**, leave **comments**, add **reactions**, and **follow** each other. Content is organized through **feeds**, and media is managed via **files**.

**Who is this for?** This reference describes the core server data model. It's essential for data import, analytics integration, and understanding API response structures.

    13 core entities with full field definitions, types, and relationship mappings
    Polymorphic join patterns, post composition, comment threading, and feed system
    Comprehensive enum values and 10 practical data import guidelines

## Conventions

| Convention            | Description                                                                                                                                                                                                    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Triple-ID pattern** | Most entities expose three IDs: a primary `{entity}Id`, a `{entity}PublicId` (stable external identifier), and a `{entity}InternalId` (database-level reference). For joins, prefer `userId` / `userPublicId`. |
| **Soft delete**       | Nearly every entity has an `isDeleted` boolean. Deleted records remain in the database with `isDeleted: true`. Filter these out unless you specifically need deletion history.                                 |
| **Timestamps**        | `createdAt` and `updatedAt` (ISO 8601 date-time) are present on all entities. Some also have `editedAt`.                                                                                                       |
| **Metadata**          | A freeform `metadata` object is available on most entities for custom fields.                                                                                                                                  |
| **Flagging**          | `flagCount` (number of reports) and `hashFlag` (bloom-filter structure) track moderation state. Parent entities bubble up flags via `hasFlaggedComment`, `hasFlaggedPost`, `hasFlaggedChildren`.               |

## Entity-Relationship Diagram

The following diagram shows the core entities and their relationships in the social module.

```mermaid placement="top-left" actions={true}
erDiagram
    User {
        string userId PK
        string avatarFileId FK
    }
    Community {
        string communityId PK
        string channelId FK
        string userId FK
    }
    CommunityCategory {
        string categoryId PK
    }
    CommunityUser {
        string userId FK
        string communityId FK
    }
    Post {
        string postId PK
        string parentPostId FK
        string postedUserId FK
        string targetId FK
        string feedId FK
    }
    Comment {
        string commentId PK
        string userId FK
        string parentId FK
        string referenceId FK
    }
    Reaction {
        string reactionId PK
        string userId FK
        string referenceId FK
    }
    Follow {
        string from FK
        string to FK
    }
    Feed {
        string feedId PK
        string targetId FK
    }
    Poll {
        string pollId PK
        string userId FK
    }
    Story {
        string storyId PK
        string creatorId FK
        string targetId FK
    }
    File {
        string fileId PK
    }
    Room {
        string roomId PK
        string createdBy FK
        string targetId FK
        string parentRoomId FK
    }

    %% === Relationships ===

    User ||--o{ CommunityUser : "joins"
    Community ||--o{ CommunityUser : "has members"
    Community }o--o{ CommunityCategory : "tagged with"

    User ||--o{ Post : "creates"
    Community ||--o{ Post : "contains"
    Post ||--o{ Post : "parent → children"

    User ||--o{ Comment : "creates"
    Post ||--o{ Comment : "has comments"
    Story ||--o{ Comment : "has comments"
    Comment ||--o{ Comment : "parent → replies"

    Post ||--o{ Reaction : "receives"
    Comment ||--o{ Reaction : "receives"
    Story ||--o{ Reaction : "receives"
    User ||--o{ Reaction : "creates"

    User ||--o{ Follow : "follows from"
    User ||--o{ Follow : "followed to"

    Community ||--o{ Feed : "owns"
    User ||--o{ Feed : "owns"
    Feed ||--o{ Post : "contains"

    User ||--o{ Poll : "creates"
    Post ||--o| Poll : "embeds"

    User ||--o{ Story : "creates"
    Community ||--o{ Story : "contains"

    User ||--o{ Room : "creates"
    Community ||--o{ Room : "hosts"
    Post ||--o| Room : "embeds"
    Room ||--o{ Room : "parent has children"

    Post }o--o{ File : "attaches media"
    Comment }o--o{ File : "attaches media"
    Story }o--o{ File : "attaches media"
    Room }o--o| File : "thumbnail"
```

## Entity Reference

    A registered user within the network. Users can create content, join communities, follow others, and react to content.

    | Field             | Type      | Description                                                   |
    | ----------------- | --------- | ------------------------------------------------------------- |
    | `userId`          | string    | **Primary key.** Unique user identifier.                      |
    | `userPublicId`    | string    | Stable public identifier (v3+).                               |
    | `userInternalId`  | string    | Internal database identifier (v3+).                           |
    | `displayName`     | string    | Display name.                                                 |
    | `profileHandle`   | string    | Unique handle (v3+).                                          |
    | `description`     | string    | User bio (v3+).                                               |
    | `avatarFileId`    | string    | FK → File. Avatar image.                             |
    | `avatarCustomUrl` | string    | External avatar URL (v3+).                                    |
    | `roles`           | string[]  | Role IDs assigned to this user.                               |
    | `permissions`     | string[]  | Resolved permissions (v3+).                                   |
    | `flagCount`       | integer   | Number of moderation reports.                                 |
    | `hashFlag`        | object    | Bloom-filter flag structure.                                  |
    | `metadata`        | object    | Custom fields.                                                |
    | `isGlobalBan`     | boolean   | Whether user is globally banned (v3+).                        |
    | `isGlobalMuted`   | boolean   | _(Computed)_ `true` when `globalMuteTimeout > now` (v3+).     |
    | `globalMuteTimeout` | date-time | When the global mute expires; a far-future date means no expiry. Admin-only — returned with `includeModerationDetails`. |
    | `isBrand`         | boolean   | Whether user is a brand account (v3+).                        |
    | `tags`            | array     | Tag assignments: `[{tagId: "...", assignedAt: "..."}]` (v3+). |
    | `isDeleted`       | boolean   | Soft-delete flag.                                             |
    | `createdAt`       | date-time | Creation timestamp.                                           |
    | `updatedAt`       | date-time | Last update timestamp.                                        |

    **Relationships:**
    - `1:N` → Post (as `postedUserId`)
    - `1:N` → Comment (as `userId`)
    - `1:N` → Story (as `creatorId`)
    - `1:N` → Poll (as `userId`)
    - `M:N` → Community (via CommunityUser join)
    - `1:N` → Follow (as `from` or `to`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Post : "creates"
    User ||--o{ Comment : "creates"
    User ||--o{ Story : "creates"
    User ||--o{ Poll : "creates"
    User ||--o{ CommunityUser : "joins communities"
    User ||--o{ Follow : "follows / followed"
    User ||--o{ Reaction : "creates"
```

    A group or space where users gather, share posts, and interact. Every community has a backing channel (1:1) and can be associated with categories.

    **Direct DB queries:** Several community fields (`displayName`, `tags`, `metadata`, `avatarFileId`, `categoryIds`, `hasFlaggedComment`, `hasFlaggedPost`, `notificationMode`) are actually stored on the backing **Channel** document, not on the Community document itself. The API serializer merges both into a single response.

    | Field                        | Type      | Description                                                 |
    | ---------------------------- | --------- | ----------------------------------------------------------- |
    | `communityId`                | string    | **Primary key.**                                            |
    | `channelId`                  | string    | FK → Channel. 1:1 backing channel.                          |
    | `userId`                     | string    | FK → User. Creator.                                |
    | `userPublicId`               | string    | Creator's public ID.                                        |
    | `userInternalId`             | string    | Creator's internal ID.                                      |
    | `displayName`                | string    | Community display name.                                     |
    | `description`                | string    | Community description.                                      |
    | `avatarFileId`               | string    | FK → File. Avatar image.                           |
    | `isOfficial`                 | boolean   | Official community flag.                                    |
    | `isPublic`                   | boolean   | Public visibility.                                          |
    | `isDiscoverable`             | boolean   | Whether private community appears in search.                |
    | `onlyAdminCanPost`           | boolean   | Restrict posting to admins.                                 |
    | `needApprovalOnPostCreation` | boolean   | Posts require review before publishing.                     |
    | `requiresJoinApproval`       | boolean   | Members need admin approval to join.                        |
    | `allowCommentInStory`        | boolean   | Allow comments on stories.                                  |
    | `categoryIds`                | string[]  | FK → CommunityCategory. Many-to-many. |
    | `tags`                       | string[]  | Searchable tags.                                            |
    | `metadata`                   | object    | Custom fields.                                              |
    | `postsCount`                 | integer   | Total post count.                                           |
    | `membersCount`               | integer   | Total member count.                                         |
    | `moderatorMemberCount`       | integer   | Moderator count.                                            |
    | `hasFlaggedComment`          | boolean   | Contains reported comments.                                 |
    | `hasFlaggedPost`             | boolean   | Contains reported posts.                                    |
    | `notificationMode`           | enum      | `default` \| `silent` \| `subscribe`.                       |
    | `type`                       | enum      | `default` \| `event`.                                       |
    | `eventId`                    | string    | FK → Event. Present when `type = "event"`.                  |
    | `isJoined`                   | boolean   | _(Computed)_ Whether the requesting user is a member.       |
    | `isDeleted`                  | boolean   | Soft-delete flag.                                           |
    | `createdAt`                  | date-time | Creation timestamp.                                         |
    | `updatedAt`                  | date-time | Last update timestamp.                                      |

    **Relationships:**
    - `1:1` → Channel (every community has a backing channel)
    - `M:N` → CommunityCategory (via `categoryIds[]`)
    - `1:N` → CommunityUser (members)
    - `1:N` → Post (via polymorphic `targetId` where `targetType = "community"`)
    - `1:N` → Story (via polymorphic `targetId` where `targetType = "community"`)
    - `1:N` → Feed (via polymorphic `targetId` where `targetType = "community"`)

```mermaid placement="top-left" actions={true}
erDiagram
    Community ||--o| Channel : "backed by (1:1)"
    Community }o--o{ CommunityCategory : "tagged with"
    Community ||--o{ CommunityUser : "has members"
    Community ||--o{ Post : "contains (targetType=community)"
    Community ||--o{ Story : "contains (targetType=community)"
    Community ||--o{ Feed : "owns (targetType=community)"
```

    A label/tag that can be associated with communities. Communities reference categories via `categoryIds[]` (many-to-many).

    | Field          | Type      | Description                          |
    | -------------- | --------- | ------------------------------------ |
    | `categoryId`   | string    | **Primary key.**                     |
    | `name`         | string    | Display name.                        |
    | `metadata`     | object    | Custom fields.                       |
    | `avatarFileId` | string    | FK → File. Category avatar. |
    | `isDeleted`    | boolean   | Soft-delete flag.                    |
    | `createdAt`    | date-time | Creation timestamp.                  |
    | `updatedAt`    | date-time | Last update timestamp.               |

    **Relationships:**
    - `M:N` → Community (referenced by `community.categoryIds[]`)

```mermaid placement="top-left" actions={true}
erDiagram
    Community }o--o{ CommunityCategory : "tagged with categories"
```

    The **join entity** between User and Community. Represents a user's membership, roles, and status within a community.

    | Field                 | Type      | Description                                    |
    | --------------------- | --------- | ---------------------------------------------- |
    | `userId`              | string    | FK → User.                            |
    | `userPublicId`        | string    | User's public ID.                              |
    | `userInternalId`      | string    | User's internal ID.                            |
    | `communityId`         | string    | FK → Community.                  |
    | `channelId`           | string    | FK → Channel. The community's backing channel. |
    | `communityMembership` | enum      | `none` \| `member` \| `banned`.                |
    | `notMemberReason`     | string    | Reason user is not a member.                   |
    | `isBanned`            | boolean   | Ban status.                                    |
    | `roles`               | string[]  | Community-specific role IDs.                   |
    | `permissions`         | string[]  | Resolved permissions within this community.    |
    | `lastActivity`        | date-time | Last activity in community.                    |
    | `createdAt`           | date-time | Record creation timestamp.                     |
    | `updatedAt`           | date-time | Last update timestamp.                         |

    **Relationships:**
    - `N:1` → User
    - `N:1` → Community
    - Composite key: (`userId`, `communityId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ CommunityUser : "joins as member"
    Community ||--o{ CommunityUser : "has members"
```

    The primary content unit. Posts can target a community or a user's profile feed. Posts support a **parent–child composition** model where a single logical post (e.g., a gallery) is a parent with child posts for each attachment. See [Post Composition Model](#post-composition-model-parentchild-posts).

    | Field                   | Type      | Description                                                                                                    |
    | ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
    | `postId`                | string    | **Primary key.**                                                                                               |
    | `parentPostId`          | string    | FK → Post (self). Parent post ID for child posts. `null` for top-level posts.                                  |
    | `postedUserId`          | string    | FK → User. Creator.                                                                                   |
    | `postedUserPublicId`    | string    | Creator's public ID.                                                                                           |
    | `postedUserInternalId`  | string    | Creator's internal ID.                                                                                         |
    | `targetId`              | string    | FK → Community or User. **Polymorphic target.**                                                                |
    | `targetPublicId`        | string    | Target's public ID.                                                                                            |
    | `targetInternalId`      | string    | Target's internal ID.                                                                                          |
    | `targetType`            | enum      | `user` \| `community` \| `content`. Determines what `targetId` points to.                                      |
    | `dataType`              | enum      | `text` \| `image` \| `file` \| `video` \| `liveStream` \| `audio` \| `poll` \| `clip` \| `room`. Content type. |
    | `data`                  | object    | Content payload. Fields vary by `dataType` — see below.                                                        |
    | `data.title`            | string    | Post title (max 150 chars).                                                                                    |
    | `data.text`             | string    | Post body text.                                                                                                |
    | `data.fileId`           | string    | FK → File. Image/file attachment.                                                     |
    | `data.thumbnailFileId`  | string    | FK → File. Video thumbnail.                                                                                    |
    | `data.videoFileId`      | object    | Video file IDs by quality: `{original, low, medium, high}`.                                                    |
    | `data.streamId`         | string    | FK → VideoStream. For live stream posts.                                                                       |
    | `data.imageDisplayMode` | enum      | `fit` \| `fill`. How image is displayed.                                                                       |
    | `data.roomId`           | string    | FK → Room. For room posts.                                                                                     |
    | `metadata`              | object    | Custom fields.                                                                                                 |
    | `children`              | string[]  | IDs of child posts.                                                                                            |
    | `childrenNumber`        | integer   | Count of child posts.                                                                                          |
    | `comments`              | string[]  | IDs of comments.                                                                                               |
    | `commentsCount`         | integer   | Total comment count.                                                                                           |
    | `reactions`             | object    | Map of `reactionName → count` (e.g., `{"like": 5}`).                                                           |
    | `reactionsCount`        | integer   | Total reaction count.                                                                                          |
    | `myReactions`           | string[]  | Current user's reaction names.                                                                                 |
    | `feedId`                | string    | FK → Feed. Which feed this post belongs to.                                                           |
    | `tags`                  | string[]  | Up to 5 tags (max 24 chars each).                                                                              |
    | `hashtags`              | string[]  | Up to 30 hashtags (max 100 chars each).                                                                        |
    | `mentionees`            | array     | Mentioned users: `[{type: "user", userIds: [...]}]`.                                                           |
    | `impression`            | integer   | Non-unique view count.                                                                                         |
    | `reach`                 | integer   | Unique view count.                                                                                             |
    | `structureType`         | enum      | Derived type — see [StructureType enum](#key-enums-reference).                                                 |
    | `flagCount`             | integer   | Report count.                                                                                                  |
    | `hashFlag`              | object    | Bloom-filter flag.                                                                                             |
    | `hasFlaggedComment`     | boolean   | Contains reported comments.                                                                                    |
    | `hasFlaggedChildren`    | boolean   | Contains reported child posts.                                                                                 |
    | `approved`              | boolean   | Whether the post is approved for global feed.                                                                  |
    | `isDiscoverable`        | boolean   | Whether the post is discoverable.                                                                              |
    | `sequenceNumber`        | integer   | Ordering sequence within feed.                                                                                 |
    | `publisherId`           | string    | FK → User. Publisher (may differ from poster in moderated flows).                                              |
    | `publisherPublicId`     | string    | Publisher's public ID.                                                                                         |
    | `eventId`               | string    | FK → Event. Room/event reference (optional).                                                                   |
    | `links`                 | array     | Link preview data extracted from post content.                                                                 |
    | `editedAt`              | date-time | Last content edit timestamp.                                                                                   |
    | `isDeleted`             | boolean   | Soft-delete flag.                                                                                              |
    | `createdAt`             | date-time | Creation timestamp.                                                                                            |
    | `updatedAt`             | date-time | Last update timestamp.                                                                                         |

    **Relationships:**
    - `N:1` → User (creator via `postedUserId`)
    - `N:1` → Community or User (via `targetId` + `targetType`)
    - `1:N` → Post (children via `parentPostId`, self-referential)
    - `1:N` → Comment (via `comment.referenceId` where `referenceType = "post"`)
    - `1:N` → Reaction (via `reaction.referenceId` where `referenceType = "post"`)
    - `N:1` → Feed (via `feedId`)
    - `0:1` → Poll (via `data.pollId` when created as poll post)
    - `0:N` → File (attachments via child posts or `data.fileId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Post : "creates"
    Community ||--o{ Post : "contains (targetType=community)"
    Post ||--o{ Post : "parent has children"
    Post ||--o{ Comment : "has comments"
    Post ||--o{ Reaction : "receives (referenceType=post)"
    Feed ||--o{ Post : "contains"
    Post ||--o| Poll : "embeds"
    Post }o--o{ File : "attaches media"
```

    A comment attached to a Post or Story. Comments support **two-level threading** — see [Comment Threading Model](#comment-threading-model).

    | Field               | Type      | Description                                                                                 |
    | ------------------- | --------- | ------------------------------------------------------------------------------------------- |
    | `commentId`         | string    | **Primary key.**                                                                            |
    | `userId`            | string    | FK → User. Creator.                                                                |
    | `userPublicId`      | string    | Creator's public ID.                                                                        |
    | `userInternalId`    | string    | Creator's internal ID.                                                                      |
    | `parentId`          | string    | FK → Comment (self). Direct parent for replies. `null` for top-level.                       |
    | `rootId`            | string    | FK → Comment (self). Thread root comment. `null` for top-level.                             |
    | `referenceId`       | string    | FK → Post or Story. **Polymorphic**. The content this comment is on.                        |
    | `referenceType`     | enum      | `post` \| `content` \| `story`. What `referenceId` points to.                               |
    | `targetId`          | string    | _(Computed)_ FK → Community or User. Derived from `path` at serialization time.             |
    | `targetType`        | enum      | _(Computed)_ `community` \| `user` \| `content`. Derived from `path` at serialization time. |
    | `dataType`          | string    | _(Deprecated)_ Type of comment — fixed as `"text"` in newer SDKs.                           |
    | `dataTypes`         | string[]  | Content types: `text` \| `image` \| `video`. A comment can contain multiple types.          |
    | `data`              | object    | Comment body content.                                                                       |
    | `metadata`          | object    | Custom fields.                                                                              |
    | `attachments`       | array     | Media attachments — `[{type: "image"\|"video", fileId: "..."}]`.                            |
    | `children`          | string[]  | IDs of reply comments.                                                                      |
    | `childrenNumber`    | integer   | Reply count.                                                                                |
    | `reactions`         | object    | Map of `reactionName → count`.                                                              |
    | `reactionsCount`    | integer   | Total reaction count.                                                                       |
    | `myReactions`       | string[]  | Current user's reaction names.                                                              |
    | `mentionees`        | array     | Mentioned users: `[{type: "user", userIds: [...]}]`.                                        |
    | `segmentNumber`     | integer   | Ordering segment.                                                                           |
    | `flagCount`         | integer   | Report count.                                                                               |
    | `hashFlag`          | object    | Bloom-filter flag.                                                                          |
    | `publisherPublicId` | string    | Publisher's public ID (may differ from commenter).                                          |
    | `links`             | array     | Link preview data extracted from comment content.                                           |
    | `editedAt`          | date-time | Last edit timestamp.                                                                        |
    | `isDeleted`         | boolean   | Soft-delete flag.                                                                           |
    | `createdAt`         | date-time | Creation timestamp.                                                                         |
    | `updatedAt`         | date-time | Last update timestamp.                                                                      |

    **Relationships:**
    - `N:1` → User (creator via `userId`)
    - `N:1` → Post or Story (via `referenceId` + `referenceType`)
    - `1:N` → Comment (replies via `parentId`, self-referential)
    - `N:1` → Comment (root thread via `rootId`)
    - `1:N` → Reaction (via `reaction.referenceId` where `referenceType = "comment"`)
    - `0:N` → File (via `attachments[].fileId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Comment : "creates"
    Post ||--o{ Comment : "has comments (referenceType=post)"
    Story ||--o{ Comment : "has comments (referenceType=story)"
    Comment ||--o{ Comment : "parent has replies"
    Comment ||--o{ Reaction : "receives (referenceType=comment)"
    Comment }o--o{ File : "attaches media"
```

    Tracks reactions (likes, love, etc.) on content. **Each reaction is stored as its own document** — one document per user-reaction-reference combination. Reactions use a **polymorphic reference** to support multiple content types.

    | Field            | Type      | Description                                                                           |
    | ---------------- | --------- | ------------------------------------------------------------------------------------- |
    | `reactionId`     | string    | **Primary key.** Unique reaction instance ID.                                         |
    | `reactionName`   | string    | Freeform name, e.g., `"like"`, `"love"`, `"wow"`.                                     |
    | `userId`         | string    | FK → User. Who reacted.                                                      |
    | `userInternalId` | string    | Reactor's internal ID.                                                                |
    | `referenceId`    | string    | FK → Post, Comment, Story, or Message. The content being reacted to.                  |
    | `referenceType`  | enum      | `post` \| `comment` \| `story` \| `message`. Determines what `referenceId` points to. |
    | `createdAt`      | date-time | When the reaction was added.                                                          |
    | `updatedAt`      | date-time | When the reaction was last updated.                                                   |

    Reaction names are **freeform strings**, not a fixed enum. The `reactions` field on Post/Comment/Story aggregates these as `{reactionName: count}`.

    **Aggregated view:** When querying reactions for a reference, the API returns an aggregated `reactors[]` array grouped by reference. Each entry contains `reactionId`, `reactionName`, `userId`, and `createdAt`.

    **Relationships:**
    - `N:1` → Post (when `referenceType = "post"`)
    - `N:1` → Comment (when `referenceType = "comment"`)
    - `N:1` → Story (when `referenceType = "story"`)
    - `N:1` → Message (when `referenceType = "message"`)
    - `N:1` → User (via `userId`)

```mermaid placement="top-left" actions={true}
erDiagram
    Post ||--o{ Reaction : "receives (referenceType=post)"
    Comment ||--o{ Reaction : "receives (referenceType=comment)"
    Story ||--o{ Reaction : "receives (referenceType=story)"
    User ||--o{ Reaction : "creates"
```

    A user-to-user follow relationship. Supports request-based following with status tracking.

    | Field                | Type      | Description                                                  |
    | -------------------- | --------- | ------------------------------------------------------------ |
    | `from`               | string    | FK → User. The follower's user ID.                  |
    | `fromUserPublicId`   | string    | Follower's public ID.                                        |
    | `fromUserInternalId` | string    | Follower's internal ID.                                      |
    | `to`                 | string    | FK → User. The followed user's ID.                  |
    | `toUserPublicId`     | string    | Followed user's public ID.                                   |
    | `toUserInternalId`   | string    | Followed user's internal ID.                                 |
    | `status`             | enum      | `pending` \| `accepted` \| `none` \| `deleted` \| `blocked`. |
    | `createdAt`          | date-time | When the follow was initiated.                               |
    | `updatedAt`          | date-time | Last status change.                                          |

    **FollowCount** (separate aggregation entity):

    | Field            | Type    | Description                     |
    | ---------------- | ------- | ------------------------------- |
    | `userId`         | string  | FK → User.                      |
    | `followerCount`  | integer | Number of followers.            |
    | `followingCount` | integer | Number of users being followed. |
    | `pendingCount`   | integer | Pending follow requests.        |

    **Relationships:**
    - `N:1` → User (from — the follower)
    - `N:1` → User (to — the followed)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Follow : "follows from"
    User ||--o{ Follow : "followed to"
```

    A container that groups posts for a specific target (community or user). Each target can have up to three feed types that represent different stages of the post approval workflow.

    | Field        | Type      | Description                                                                         |
    | ------------ | --------- | ----------------------------------------------------------------------------------- |
    | `feedId`     | string    | **Primary key.**                                                                    |
    | `targetId`   | string    | FK → Community or User. **Polymorphic owner.**                                      |
    | `targetType` | enum      | `community` \| `user`.                                                              |
    | `feedType`   | enum      | `published` (main feed) \| `reviewing` (pending approval) \| `declined` (rejected). |
    | `postCount`  | integer   | Number of posts in this feed.                                                       |
    | `createdAt`  | date-time | Creation timestamp.                                                                 |
    | `updatedAt`  | date-time | Last update timestamp.                                                              |

    **Relationships:**
    - `N:1` → Community (when `targetType = "community"`)
    - `N:1` → User (when `targetType = "user"`)
    - `1:N` → Post (posts reference feed via `post.feedId`)

```mermaid placement="top-left" actions={true}
erDiagram
    Community ||--o{ Feed : "owns (targetType=community)"
    User ||--o{ Feed : "owns (targetType=user)"
    Feed ||--o{ Post : "contains posts"
```

    A poll embedded within a post. Polls have a question with up to 10 answers and can be open or closed.

    | Field            | Type      | Description                                                        |
    | ---------------- | --------- | ------------------------------------------------------------------ |
    | `pollId`         | string    | **Primary key.**                                                   |
    | `userId`         | string    | FK → User. Creator.                                       |
    | `userPublicId`   | string    | Creator's public ID.                                               |
    | `userInternalId` | string    | Creator's internal ID.                                             |
    | `title`          | string    | Poll title (max 150 chars).                                        |
    | `question`       | string    | Poll question text.                                                |
    | `answerType`     | enum      | `single` \| `multiple`. Whether user can pick one or many answers. |
    | `answers`        | array     | Up to 10 answers — see Answer below.                               |
    | `status`         | enum      | `open` (default) \| `closed`.                                      |
    | `closedAt`       | string    | When the poll was/should be closed.                                |
    | `closedIn`       | number    | Auto-close duration.                                               |
    | `isVoted`        | boolean   | _(Computed)_ Whether current user has voted.                       |
    | `isDeleted`      | boolean   | Soft-delete flag.                                                  |
    | `createdAt`      | date-time | Creation timestamp.                                                |
    | `updatedAt`      | date-time | Last update timestamp.                                             |

    **Answer** (nested object):

    | Field           | Type    | Description                                             |
    | --------------- | ------- | ------------------------------------------------------- |
    | `id`            | string  | Option ID.                                              |
    | `dataType`      | enum    | `text` \| `image`.                                      |
    | `data`          | string  | Answer text.                                            |
    | `fileId`        | string  | FK → File. Required when `dataType = "image"`. |
    | `voteCount`     | number  | Number of votes.                                        |
    | `isVotedByUser` | boolean | Whether current user voted for this option.             |

    **UsersAnswered** (vote tracking):

    | Field       | Type     | Description                      |
    | ----------- | -------- | -------------------------------- |
    | `userId`    | string   | FK → User.                       |
    | `pollId`    | string   | FK → Poll.                       |
    | `answerIds` | string[] | Which answers the user selected. |

    **Relationships:**
    - `N:1` → User (creator)
    - `1:1` → Post (poll is embedded via `post.data.pollId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Poll : "creates"
    Post ||--o| Poll : "embeds (data.pollId)"
```

    A live video streaming session. Rooms support **direct streaming** (single host via RTMP/SRT) or **co-host** mode (multi-participant via WebRTC). Rooms are surfaced in the social feed via Posts with `dataType = "room"` and `data.roomId`. They have a lifecycle (idle → live → ended/recorded) and can optionally attach a live chat channel.

    | Field                   | Type      | Description                                                                                         |
    | ----------------------- | --------- | --------------------------------------------------------------------------------------------------- |
    | `roomId`                | string    | **Primary key.**                                                                                    |
    | `type`                  | enum      | `directStreaming` \| `coHosts`.                                                                     |
    | `status`                | enum      | `idle` \| `live` \| `waitingReconnect` \| `ended` \| `recorded` \| `terminated` \| `error`.         |
    | `title`                 | string    | Room title (max 1000 chars).                                                                        |
    | `description`           | string    | Room description (max 5000 chars).                                                                  |
    | `createdBy`             | string    | FK → User. Creator's public ID.                                                            |
    | `creatorInternalId`     | string    | Creator's internal ID.                                                                              |
    | `targetType`            | enum      | `community`. Where the room is hosted.                                                              |
    | `targetId`              | string    | FK → Community. Target community ID.                                                  |
    | `referenceType`         | enum      | `post`. The entity this room is linked to.                                                          |
    | `referenceId`           | string    | FK → Post. The post embedding this room.                                                   |
    | `thumbnailFileId`       | string    | FK → File. Thumbnail image.                                                                |
    | `participants`          | array     | Participants: `[{userId, userInternalId, type: "host"\|"coHost", canManageProductTags?}]`.          |
    | `liveChatEnabled`       | boolean   | Whether live chat is enabled.                                                                       |
    | `liveChannelId`         | string    | FK → Channel. Attached live chat channel's public ID.                                               |
    | `parentRoomId`          | string    | FK → Room (self). Parent room for multi-stream layouts.                                             |
    | `childRoomIds`          | string[]  | Child room IDs for multi-stream layouts.                                                            |
    | `metadata`              | object    | Custom fields.                                                                                      |
    | `durationSeconds`       | number    | Stream duration in seconds.                                                                         |
    | `liveAt`                | date-time | When the room went live.                                                                            |
    | `endedAt`               | date-time | When the room ended.                                                                                |
    | `recordedAt`            | date-time | When the recording became available.                                                                |
    | `livePlaybackUrl`       | string    | _(Computed)_ HLS playback URL. Only present for non-banned users while room is live.                |
    | `liveThumbnailUrl`      | string    | _(Computed)_ Live thumbnail URL. Same access conditions as `livePlaybackUrl`.                       |
    | `liveResolution`        | object    | _(Computed)_ Resolution while live: `{aspectRatio, width, height}`.                                 |
    | `recordedResolution`    | object    | _(Computed)_ Resolution of the recorded stream: `{aspectRatio, width, height}`.                     |
    | `recordedPlaybackInfos` | array     | _(Computed)_ Recorded playback: `[{url, thumbnailUrl}]`. Only for non-banned users after recording. |
    | `isDeleted`             | boolean   | Soft-delete flag.                                                                                   |
    | `deletedAt`             | date-time | Deletion timestamp.                                                                                 |
    | `deletedBy`             | string    | FK → User. Who deleted the room.                                                                    |
    | `createdAt`             | date-time | Creation timestamp.                                                                                 |
    | `updatedAt`             | date-time | Last update timestamp.                                                                              |

    **Relationships:**
    - `N:1` → User (creator via `createdBy`)
    - `N:1` → Community (via `targetId` where `targetType = "community"`)
    - `1:1` → Post (room is embedded via `post.data.roomId`; room references back via `referenceId`)
    - `1:N` → Room (children via `parentRoomId`, self-referential)
    - `0:1` → File (thumbnail via `thumbnailFileId`)
    - `0:1` → Channel (live chat via `liveChannelId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Room : "creates"
    Community ||--o{ Room : "hosts (targetType=community)"
    Post ||--o| Room : "embeds (data.roomId)"
    Room ||--o{ Room : "parent has children"
    Room }o--o| File : "thumbnail"
```

    Ephemeral content with an expiration time. Stories can target a user's profile or a community.

    | Field                   | Type      | Description                                                   |
    | ----------------------- | --------- | ------------------------------------------------------------- |
    | `storyId`               | string    | **Primary key.**                                              |
    | `creatorId`             | string    | FK → User (internal ID). Creator.                    |
    | `creatorPublicId`       | string    | Creator's public ID.                                          |
    | `targetId`              | string    | FK → Community or User (internal ID). **Polymorphic target.** |
    | `targetPublicId`        | string    | Target's public ID.                                           |
    | `targetType`            | enum      | `user` \| `community`.                                        |
    | `dataType`              | enum      | `text` \| `image` \| `video`.                                 |
    | `data`                  | object    | Story content — see below.                                    |
    | `data.text`             | string    | Text content.                                                 |
    | `data.fileId`           | string    | FK → File. Image file.                               |
    | `data.imageDisplayMode` | enum      | `fit` \| `fill`. How image is displayed.                      |
    | `data.thumbnailFileId`  | string    | FK → File. Video thumbnail.                                   |
    | `data.videoFileId`      | object    | Video files by quality: `{original, low, medium, high}`.      |
    | `items`                 | array     | Story overlays. Currently supports hyperlink items (max 10).  |
    | `metadata`              | object    | Custom fields.                                                |
    | `expiresAt`             | date-time | When the story expires (configurable, 1–1440 minutes).        |
    | `reactions`             | object    | Map of `reactionName → count`.                                |
    | `reactionsCount`        | integer   | Total reaction count.                                         |
    | `myReactions`           | string[]  | Current user's reaction names.                                |
    | `commentsCount`         | integer   | Comment count.                                                |
    | `hasFlaggedComment`     | boolean   | Contains reported comments.                                   |
    | `mentionedUsers`        | array     | Mentioned users/channels.                                     |
    | `impression`            | integer   | Non-unique view count.                                        |
    | `reach`                 | integer   | Unique view count.                                            |
    | `flagCount`             | integer   | Report count.                                                 |
    | `hashFlag`              | object    | Bloom-filter flag structure.                                  |
    | `comments`              | array     | Comment data for this story.                                  |
    | `referenceId`           | string    | Optional reference ID.                                        |
    | `isDeleted`             | boolean   | Soft-delete flag.                                             |
    | `createdAt`             | date-time | Creation timestamp.                                           |
    | `updatedAt`             | date-time | Last update timestamp.                                        |

    **StoryTarget** (aggregated ring state):

    | Field                    | Type      | Description                                   |
    | ------------------------ | --------- | --------------------------------------------- |
    | `targetId`               | string    | FK → Community or User.                       |
    | `targetPublicId`         | string    | Target's public ID.                           |
    | `targetType`             | enum      | `community` \| `user`.                        |
    | `lastStoryExpiresAt`     | date-time | Expiry of the latest active story.            |
    | `lastStorySeenExpiresAt` | date-time | Expiry of the latest story the user has seen. |
    | `targetUpdatedAt`        | date-time | When the target was last updated.             |

    **Relationships:**
    - `N:1` → User (creator via `creatorId`)
    - `N:1` → Community (when `targetType = "community"`)
    - `N:1` → User (when `targetType = "user"`)
    - `1:N` → Comment (via `comment.referenceId` where `referenceType = "story"`)
    - `1:N` → Reaction (via `reaction.referenceId` where `referenceType = "story"`)
    - `0:N` → File (via `data.fileId`, `data.thumbnailFileId`)

```mermaid placement="top-left" actions={true}
erDiagram
    User ||--o{ Story : "creates"
    Community ||--o{ Story : "contains (targetType=community)"
    Story ||--o{ Comment : "has comments (referenceType=story)"
    Story ||--o{ Reaction : "receives (referenceType=story)"
    Story }o--o{ File : "attaches media"
```

    An uploaded media file (image, video, audio, or generic file). Files are referenced by other entities via `fileId`.

    | Field                  | Type      | Description                                                                                                                                                           |
    | ---------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `fileId`               | string    | **Primary key.** Cloud storage key.                                                                                                                                   |
    | `fileUrl`              | string    | HTTP download URL.                                                                                                                                                    |
    | `type`                 | enum      | `image` \| `file` \| `video` \| `audio` \| `clip`.                                                                                                                    |
    | `accessType`           | enum      | `public` (open download) \| `network` (requires authentication).                                                                                                      |
    | `altText`              | string    | Alternative text (max 180 chars).                                                                                                                                     |
    | `feedType`             | string    | Feed type associated with this file.                                                                                                                                  |
    | `status`               | enum      | `uploaded` \| `transcoding` \| `transcoded` \| `transcodeFailed`. Processing status (mainly for video/audio).                                                         |
    | `isDeleted`            | boolean   | Soft-delete flag.                                                                                                                                                     |
    | `videoUrl`             | object    | Video URLs by resolution: `{1080p, 720p, 480p, 360p, original}`. Present for video files.                                                                             |
    | `attributes.name`      | string    | Original file name.                                                                                                                                                   |
    | `attributes.extension` | string    | File extension/format.                                                                                                                                                |
    | `attributes.size`      | number    | File size in bytes.                                                                                                                                                   |
    | `attributes.mimeType`  | string    | MIME type.                                                                                                                                                            |
    | `attributes.metadata`  | object    | _(Schemaless)_ Additional metadata. May contain `width`, `height`, `exif`, `gps` if set by the uploading client, but these sub-fields are not enforced by the schema. |
    | `createdAt`            | date-time | Upload timestamp.                                                                                                                                                     |
    | `updatedAt`            | date-time | Last update timestamp.                                                                                                                                                |

    **Relationships:**
    Referenced by: Post (`data.fileId`, child post attachments), Comment (`attachments[].fileId`), Story (`data.fileId`), User (`avatarFileId`), Community (`avatarFileId`), CommunityCategory (`avatarFileId`), Poll answers (`answers[].fileId`).

```mermaid placement="top-left" actions={true}
erDiagram
    Post }o--o{ File : "attaches media"
    Comment }o--o{ File : "attaches media"
    Story }o--o{ File : "attaches media"
    Room }o--o| File : "thumbnail"
    User }o--o| File : "avatar"
    Community }o--o| File : "avatar"
```

## Polymorphic Reference Patterns

Two polymorphic foreign key patterns are used throughout the data model. Understanding these is critical for correct data joins.

**Critical for data integration:** Misunderstanding these patterns is the most common source of join errors. Always check both the ID and its accompanying type field.

    Used to associate content with its **owner/container**.

    | Entity      | Possible `targetType` values   | Interpretation                                                  |
    | ----------- | ------------------------------ | --------------------------------------------------------------- |
    | **Post**    | `user`, `community`, `content` | Where the post was published — a user's profile or a community. |
    | **Comment** | `community`, `user`, `content` | The context of the referenced content.                          |
    | **Story**   | `user`, `community`            | Where the story was published.                                  |
    | **Feed**    | `community`, `user`            | The owner of the feed.                                          |

    **How to join:**
```
IF targetType = "community" THEN targetId → community.communityId
IF targetType = "user"      THEN targetId → user.userId
```

    Used to associate an entity with the **specific content** it relates to.

    | Entity       | Possible `referenceType` values       | Interpretation                          |
    | ------------ | ------------------------------------- | --------------------------------------- |
    | **Comment**  | `post`, `content`, `story`            | The content the comment is attached to. |
    | **Reaction** | `post`, `comment`, `story`, `message` | The content the reaction is on.         |

    **How to join:**
```
IF referenceType = "post"    THEN referenceId → post.postId
IF referenceType = "comment" THEN referenceId → comment.commentId
IF referenceType = "story"   THEN referenceId → story.storyId
IF referenceType = "message" THEN referenceId → message.messageId
```

## Post Composition Model (Parent–Child Posts)

Posts use a **parent–child composition** pattern to represent multi-attachment content (e.g., image galleries, mixed-media posts).

```mermaid placement="top-left" actions={true}
graph TD
    Parent["<b>Parent Post</b><br/>postId: post_abc<br/>parentPostId: null<br/>data.text: My gallery<br/>children: [child1, child2, child3]<br/>structureType: mixed"]
    Child1["<b>Child Post 1</b><br/>parentPostId: post_abc<br/>dataType: image<br/>data.fileId: file_001"]
    Child2["<b>Child Post 2</b><br/>parentPostId: post_abc<br/>dataType: video<br/>data.videoFileId: file_002"]
    Child3["<b>Child Post 3</b><br/>parentPostId: post_abc<br/>dataType: image<br/>data.fileId: file_003"]

    Parent -->|"children[]"| Child1
    Parent -->|"children[]"| Child2
    Parent -->|"children[]"| Child3
```

    A **top-level post** has `parentPostId = null`.
    A **child post** has `parentPostId` pointing to the parent's `postId`.
    The parent post holds `children[]` (array of child post IDs) and `childrenNumber`.
    Each child post holds a single attachment (one `fileId` or `videoFileId` per child).
    The `structureType` field on the parent indicates the derived type: `image`, `video`, `file`, `text`, etc. if all children are the same type, or `mixed` if children have different data types.
    When querying posts, **filter by `parentPostId = null`** to get only top-level posts. Then load `children[]` to get attachments.

## Comment Threading Model

Comments support **two-level threading** using `parentId` and `rootId`.

```mermaid placement="top-left" actions={true}
graph TD
    Post["<b>Post</b> (or Story)<br/>referenceId target"]
    A["<b>Comment A</b><br/>parentId: null<br/>rootId: null<br/>referenceId: postId"]
    B["<b>Comment B</b><br/>parentId: A<br/>rootId: A"]
    C["<b>Comment C</b><br/>parentId: A<br/>rootId: A"]
    D["<b>Comment D</b><br/>parentId: B<br/>rootId: A"]

    Post --> A
    A --> B
    A --> C
    B --> D
```

    **Top-level comments** have `referenceId` → Post/Story, `parentId = null`, `rootId = null`.
    **Replies** set `parentId` to the direct parent comment and `rootId` to the thread root.
    All replies in a thread share the same `rootId`, regardless of nesting depth.
    Parent comments track replies via `children[]` (array of child comment IDs) and `childrenNumber`.
    Comments reference their parent content (Post or Story) via `referenceId` + `referenceType`.

## Feed System

Feeds organize posts for a specific target. Each community or user can have up to **three feed types** representing the post approval workflow:

| Feed Type   | Description                                                                         |
| ----------- | ----------------------------------------------------------------------------------- |
| `published` | The main, publicly visible feed. Posts are live.                                    |
| `reviewing` | Posts pending review/approval (when `community.needApprovalOnPostCreation = true`). |
| `declined`  | Posts rejected during the review process.                                           |

### Feed Endpoints

    Posts published in a specific community. Filtered by `targetType = "community"`.
    Posts published on a specific user's profile. Filtered by `targetType = "user"`.
    Aggregated feed across communities and users. Configurable per network.
    Posts from users the current user follows.

### Post → Feed Mapping

- Every post has a `feedId` pointing to the Feed it belongs to.
- The Feed's `targetId` + `targetType` tells you which community or user owns it.
- To find all published posts in a community: find the Feed where `targetId = communityId`, `targetType = "community"`, `feedType = "published"`, then query posts by that `feedId`.

## Key Enums Reference

  | Enum                           | Values                                                                                   | Used By                                   |
  | ------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------- |
  | **CommunityMembership**        | `none`, `member`, `banned`                                                               | CommunityUser `.communityMembership`      |
  | **Community.type**             | `default`, `event`                                                                       | Community `.type`                         |
  | **Community.notificationMode** | `default`, `silent`, `subscribe`                                                         | Community `.notificationMode`             |
  | **Post.targetType**            | `user`, `community`, `content`                                                           | Post `.targetType`, Comment `.targetType` |
  | **Post.dataType**              | `text`, `image`, `file`, `video`, `liveStream`, `audio`, `poll`, `clip`, `room`          | Post `.dataType`                          |
  | **StructureType**              | `file`, `image`, `video`, `audio`, `text`, `liveStream`, `poll`, `clip`, `room`, `mixed` | Post `.structureType`                     |
  | **Comment.referenceType**      | `post`, `content`, `story`                                                               | Comment `.referenceType`                  |
  | **Comment.dataTypes**          | `text`, `image`, `video`                                                                 | Comment `.dataTypes[]`                    |
  | **Reaction.referenceType**     | `post`, `comment`, `story`, `message`                                                    | Reaction `.referenceType`                 |
  | **Follow.status**              | `pending`, `accepted`, `none`, `deleted`, `blocked`                                      | Follow `.status`                          |
  | **Feed.feedType**              | `published`, `reviewing`, `declined`                                                     | Feed `.feedType`                          |
  | **Feed.targetType**            | `community`, `user`                                                                      | Feed `.targetType`                        |
  | **Story.dataType**             | `text`, `image`, `video`                                                                 | Story `.dataType`                         |
  | **Story.targetType**           | `user`, `community`                                                                      | Story `.targetType`                       |
  | **File.type**                  | `image`, `file`, `video`, `audio`, `clip`                                                | File `.type`                              |
  | **File.accessType**            | `public`, `network`                                                                      | File `.accessType`                        |
  | **File.status**                | `uploaded`, `transcoding`, `transcoded`, `transcodeFailed`                               | File `.status`                            |
  | **Poll.answerType**            | `single`, `multiple`                                                                     | Poll `.answerType`                        |
  | **Room.type**                  | `directStreaming`, `coHosts`                                                             | Room `.type`                              |
  | **Room.status**                | `idle`, `live`, `waitingReconnect`, `ended`, `recorded`, `terminated`, `error`           | Room `.status`                            |
  | **Room.participantType**       | `host`, `coHost`                                                                         | Room `.participants[].type`               |
  | **Room.targetType**            | `community`                                                                              | Room `.targetType`                        |
  | **Room.referenceType**         | `post`                                                                                   | Room `.referenceType`                     |

## Data Import Tips

    Most entities expose three IDs (`userId`, `userPublicId`, `userInternalId`). For joining data across entities, **use `userId` or the corresponding public ID** — these are the values used in foreign key references. Internal IDs are database-level identifiers and may not appear in all API responses.

    Always check `targetType` + `targetId` on posts:
    - `targetType = "community"` → the post belongs to a community; join on `targetId = community.communityId`.
    - `targetType = "user"` → the post is on a user's profile feed; join on `targetId = user.userId`.

    Reaction names (e.g., `"like"`, `"love"`, `"wow"`) are **freeform strings**, not a fixed enum. When aggregating, group by `reactionName`. The `reactions` object on Post/Comment/Story already provides `{name: count}` aggregations.

    A poll is created as part of a post. The post's `data` object will contain a `pollId` during creation. To join: `Post.data.pollId → Poll.pollId`. Not all posts have polls — only those with `structureType = "poll"` or where `data.pollId` exists.

    Stories have an `expiresAt` timestamp. To query only **active stories**, filter where `expiresAt > NOW()`. Expiry duration is configurable per network (1–1440 minutes). Expired stories remain in the database but are no longer shown in story rings.

    Soft-deleted records have `isDeleted: true`. **Exclude these by default** for analytics unless you need deletion history. Posts also support permanent (hard) deletes — these records are removed entirely.

    When querying posts via feeds, pay attention to `feedType`:
    - `published` → live, visible posts (this is what you want for most analytics).
    - `reviewing` → posts awaiting approval.
    - `declined` → rejected posts.

    To avoid double-counting in analytics, **filter by `parentPostId = null`** when counting top-level posts. Child posts are attachments/media within a parent post, not standalone content.

    To get only top-level comments (not replies), filter by `parentId = null`. To reconstruct full threads, group by `rootId`.

    A user's relationship with a community is captured in the CommunityUser join entity. Check `communityMembership`:
    - `member` → active member.
    - `banned` → banned from the community.
    - `none` → not a member.

## Related Topics

    Server-to-server API capabilities, authentication methods, and getting started guide
    Real-time event notifications for content, user, and moderation events
    Client-side SDK implementation for social features, posts, communities, and more

## SDK Changelogs

### [Android](https://learn.social.plus/social-plus-sdk/changelogs/android-sdk-changelog)

> This page contains an overview of all relevant changes made to the Android SDK

Compatibility rows on this page are checked against the matching Android SDK Git tags in `Amity-Social-Cloud-SDK-Android`. Pre-release alpha tags are not listed here unless promoted into the public SDK changelog.

  ## 🚀 New Features

  #### Comment Approval for Communities

  A community can now require review before a new comment is visible. While a comment is pending, only its author, the community's reviewers, and network admins can see it. It stays out of public comment lists and comment counts until a reviewer approves it. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review).

  - **Turn it on:** `isCommentReviewEnabled(true)` on `AmityCommunityCreator.Builder` or `AmityCommunityUpdate.Builder` when you create or update the community. Read it back with `AmityCommunity.isCommentReviewEnabled()`.
  - **Approval status:** `AmityComment.getApprovalStatus()` returns `AmityCommentApprovalStatus` (`PENDING`, `APPROVED`, `REJECTED`).
  - **Create without a local copy:** `.isOptimistic(false)` on the comment creator builder skips the local comment, so the comment you get back carries the server's approval status. The default, `true`, keeps today's behavior.
  - **Review queue:** `AmityCommentRepository.getCommentReviewQueue(communityId)` returns a builder for the community's pending comments. Narrow it to one post or a date range with `.post(postId)`, `.startDate()`, `.endDate()`, and `.timeZone()`.
  - **Approve or decline:** `AmityCommentRepository.approveComment(commentId)` and `declineComment(commentId, reason)`. Declining deletes the comment. The optional `reason` (at most 250 characters) is kept for the moderation record only.
  - **Permission:** reviewers need `AmityPermission.REVIEW_COMMUNITY_COMMENT`.
  - **Editing while pending:** `AmitySocialSettings.isAllowEditCommentWhenReviewingEnabled()` tells you whether an author may edit a pending comment.
  - **Realtime:** an approved comment appears as soon as it is approved, through the `comment.approved` event. A declined comment arrives as a deletion.

  #### Curated Content

  Fetch the posts selected for a topic configured in the Console, and build your own discovery surface around them. A pool is one bounded, ranked result with no pagination, and the SDK keeps the server's order. See [Topic-based Content Discovery](/social-plus-sdk/social/discovery-engagement/feed/curated-content).

  - **Fetch a pool:** `AmityCoreClient.newCuratedContentRepository().getPool(topicId, limit)` returns `Single<AmityCuratedContentPool>`. `limit` must be between 1 and 100.
  - **Analytics:** `AmityCuratedContentTopic.analytics()` provides `markAsViewed()`, `markPostAsViewed(postId)`, and `markPostClick(postId)`.

  #### Pin Message in Live Channels

  Pin one message in a live channel so it stays visible above the chat. Pinning a new message replaces the current pin. The server clears the pin when the message is deleted or its author is banned from the channel or globally. See [Pin and Unpin Messages](/social-plus-sdk/chat/messaging-features/messages/pin-message).

  - **Pin and unpin:** `AmityMessageRepository.pinMessage(messageId)` and `unpinMessage(messageId)`.
  - **Read the pin:** `AmityChannel.getPinnedMessage()` returns the current `AmityPinnedMessage`, or `null` when nothing is pinned.
  - **Permission:** `AmityPermission.PIN_MESSAGE`. Channel moderators, and livestream hosts and co-hosts, have it by default.
  - **Realtime:** the channel `Flowable` emits on every pin and unpin, driven by the `channel.messagePinned` and `channel.messageUnpinned` events.

  ## ✨ Improvements

  - `AmityPost.getLocalCommentCount()` now takes an optional `includePending` flag. By default, the count leaves out the current user's own comments that are still awaiting approval. Pass `true` to include them.

  ## 🐞 Bug Fixes

  - Fixed `AmityRoomStatus` falling back to `IDLE` for a room terminated by moderation. A terminated room now surfaces as `AmityRoomStatus.TERMINATED`.
  - Fixed a member's channel role change (`channel.roleAdded` / `channel.roleRemoved`) not reaching the client until the app was restarted, which could leave a stale pin permission.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### Configurable Search Fields

  Added an opt-in `searchBy` option to user search (and channel-member search) so you can restrict which fields the keyword is matched against.

  - New enum `AmitySearchUserBy` (`DISPLAY_NAME`, `PROFILE_HANDLE`, `USER_ID`) in `com.amity.socialcloud.sdk.model.core.search`.
  - New builder method `AmityUserSearch.Builder.searchBy(List<AmitySearchUserBy>)`.
  - Omitting `searchBy` keeps the existing default matching, so existing integrations are unaffected.

  #### Video Rotation & Dimensions

  Video rotation and dimensions are now exposed, and `getVideoUrl` no longer hangs.

  #### Live Viewer Count Configuration

  Added `getLiveViewerCountConfig` to `AmityCoreClient`.

  #### v4 Sessions

  `loginWithAccessToken` now verifies the access token against v4 sessions and persists the caller's user type from the login response.

  ## ✨ Improvements

  - Capped the MQTT v5 session expiry at 1800s.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### Channel Moderation Permissions

  Added the `BAN_USER_FROM_CHANNEL` and `MUTE_USER_INSIDE_CHANNEL` permissions for per-channel moderation.

  ## ✨ Improvements

  - Cleaned up the channel ban/mute permission set — retired unused names and added missing ones.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### Event Posts

  Added event-post support: an event shared to a community feed is delivered as a post (post `dataType` `event`), resolves through `EventRepository`, and renders alongside regular posts. `event.isOriginPublic` is exposed for visibility handling.

  ## 🐞 Bug Fixes

  - Fixed locally-created chat messages being assigned the wrong segment and missing their channel id.
  - Fixed a failed send incorrectly determining the next message segment.
  - Fixed the sender's own message not being marked read on some paths.
  - Removed unused RTMP dependencies that broke 16 KB page-size alignment.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🐞 Bug Fixes

  - Improved real-time (MQTT) connection resilience: a transient failure on the first connect no longer stops real-time, and logout / token expiry now stops a client still retrying its first connect.
  - Fixed session handling so a failed token renewal is recoverable and the session stays alive through renewal.
  - Fixed chat-list message previews: previews now persist in step with their channel rows and fall back to the channel's current row when a snapshot is missing.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🐞 Bug Fixes

  - Fixed channel unread tracking to mark read against the channel id rather than the sub-channel id.
  - Fixed the local read position being lost when `membership.readToSegment` is stale.
  - Excluded left and deleted channels from the channel unread total.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### Report User with Reason

  Added the ability to report a user with a report type, behavior reason, and comment, plus report/unflag actions on the user list.

  #### Exclude Own Events

  Added an `excludeOwnEvents` parameter to event queries so the current user's own events can be filtered out.

  #### Event Target Community Avatar

  Added the community avatar to an event's target community.

  ## ✨ Improvements

  - Migrated the MQTT client from protocol v3 to v5.
  - Removed the transitive `AD_ID` permission from the FCM push module.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### For You Feed

  Added the personalized **For You** feed. Query it with `AmitySocialClient.newFeedRepository().getForYouFeed()` (a live collection), and the network setting via `AmityCoreClient.getForYouFeedSetting()`. When the feature is not enabled for the network, the collection surfaces the typed `AmityForYouFeedDisabledError`.

  #### Bidirectional Block Visibility

  Added the reverse direction of the blocking model: `getBlockingUsers()` (live collection) and `getAllBlockingUsers()` (one-shot list) return the users who have blocked the current user. Blocking a user when already at the per-network cap now returns the typed `MAX_BLOCKED_USERS_REACHED` error.

  #### Chat Search

  Added `searchChannels` and `searchMessages` to `AmityChannelRepository` for searching across channels and messages.

  #### Channel Archiving

  Added `archiveChannel`, `unarchiveChannel`, and `getArchivedChannelIds` to `AmityChannelRepository`, backed by a new local table for reactive archive/unarchive updates.

  #### Typed Shareable Links

  Added a typed shareable-link API using `AmitySharableContentType`, so links can be generated for a content type without relying on raw pattern keys.

  #### Channel Notification Mode

  Added `notificationMode` support to the channel update API.

  ## ✨ Improvements

  - Improved chat message loading and reload performance.

  ## 🐞 Bug Fixes

  - Fixed community member permissions not updating.
  - Fixed group member additions not reflecting in the member list.
  - Fixed nested room moderation not being parsed or persisted from the room payload.
  - Fixed queued message jobs never failing while offline — they now fail immediately.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## 🚀 New Features

  #### `invalidateCache` for Feed Queries

  Added `invalidateCache(true)` option to `AmityFeedRepository.getCommunityFeed()` and `AmityPostRepository.getPosts()` queries. When set, the cache is cleared **before** the first page fetch so the live collection starts from fresh server data.

  #### Community Tag Filtering

  Added `tags` filter to `getCommunities()` queries. Pass a list of tags to narrow results to communities matching all specified tags.

  #### Visitor Daily Usage Limit

  Added detection for the visitor daily read quota (100 req/day, error code `400323`). When a visitor exceeds this limit, the SDK detects the error in the global interceptor and emits an event via `AmityCoreClient.getVisitorUsageLimitEvents(): Flowable<AmityVisitorUsageLimitEvent>`.

  ## 🐞 Bug Fixes

  - Fixed event post local filtering by adding `eventId` to post objects.
  - Fixed SQLCipher incompatibility with Room 2.8.1 by upgrading SQLCipher from 4.6.1 to 4.9.0.
  - Fixed malformed XML in community and global post list menu resource files.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |
      | SQLCipher | 4.9.0 |


  ## ✨ Improvements

  - Removed unnecessary `READ_EXTERNAL_STORAGE` and `WRITE_EXTERNAL_STORAGE` permissions from SDK manifests for Google Play compliance on Android 13\+.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## ✨ Improvements

  - Added exponential backoff retry mechanism for MQTT topic subscriptions to improve real-time connection stability.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Raised Compile and Target SDK to 36

  Bump `compileSdkVersion` and `targetSdkVersion` to 36 to support the latest Android platform APIs.

  ## 🐞 Bug Fixes

  - Fixed an MQTT reconnect loop that prevented the client from properly exiting the reconnection cycle.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🐞 Bug Fixes

  - Fixed event post local filtering by adding `eventId` to post objects.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🐞 Bug Fixes

  - Optimize insert transaction when resolving reaction update event.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Live Thumbnail and Resolution in AmityRoom

  Add `liveThumbnailUrl`, `liveResolution`, and `recordedResolution` fields to `AmityRoom` to expose server-generated thumbnail and stream resolution data.

  #### Link Detection in Comments

  Add link detection support to comment create/update APIs, enabling automatic link parsing in comment text.

  #### Root Comment and Latest Comment ID in Query

  Add `rootId` and `latestCommentId` fields to the comment query API for improved comment threading and navigation.

  #### Page Size for Get Comments

  Add `pageSize` parameter to `getComments` API for more granular control over comment pagination.

  ## 🐞 Bug Fixes

  - Fixed posts going missing after paging REFRESH.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.4.2 |
      | Firebase IID | 21.1.0 |
      | Firebase Messaging | 23.0.0 |
      | Gradle Plugin | 8.6.1 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT Client | 1.3.1-beta01 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Product Tagging in Posts

  Introduce `AmityProduct` and `AmityProductTag` models with product search API, enabling users to tag up to 20 products per post via text mentions and per-media tags. Supports creating and updating posts with product tags.

  #### Livestream Product Tagging

  Introduce product management APIs for livestream(Room) post — tag, pin, and remove products across all broadcast phases.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 23 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Get All Blocked Users

  Introduce `getAllBlockedUsers()` on `AmityUserRepository` — returns the full list of blocked users (up to 100) as a non-paginated, one-shot `Single<List<AmityUser>>` with a 5-minute TTL cache.

  #### Excluding Roles in Community Member Queries

  Add `excludingRoles` parameter to `AmityCommunityMembershipQuery.Builder` and `AmityCommunityMemberSearch.Builder`. Members holding any of the specified roles are excluded from the live collection result.

  #### Time-Bounded Post Pagination

  Add `untilAt` parameter to `getPosts`, `getCommunityFeed`, and `getUserFeed` query builders. When provided, the SDK stops fetching and collecting posts beyond the given datetime boundary.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Authentication

  Introduce an ability to login with a pre-fetched `accessToken`.

  #### Comment Count

  Introduce a local calculated comment count based on incoming real-time events.

  #### Community Post Query by Tags

  Introduce an ability to community posts with matching tags.

  #### Livestream Analytics

  Introduce `AmityRoomAnalytics` for the purpose of tracking watch minute.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Livestream Post With Room

  Introduce Room service, an upgrade and a replacement for`stream`.

  #### Event Scheduling

  Introduce Event service, enabling event scheduling.

  #### Community Member Query

  Introduce `lastJoin` sorting option.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Mixed Attachments Post

  - Support `mixed` structure post where a post can contains multiple datatypes such as image, video, file, and audio.

  #### Audio Content Support

  - Support audio file upload.
  - Introduce `audio` dataType for post.

  ## 🚨 Compatibility Changes

  #### Support 16 KB page sizes

  - Kotlin version upgrade to 2.2.0
  - Bumped minSDKVersion to 24

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Public Access

  - Added `loginAsVisitor()` function, enables user to interact as a visitor.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.21 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Child stream

  - Support child stream creation where a child stream can be linked to a parent stream.

  #### Poll

  - Added `unvotePoll()` function, enables user to update poll answer.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.21 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### PII detection

  - Added detected PII data to post, comment, and message.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.21 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Hashtag

  - Support adding hashtag to a post.
  - Support post search by hashtag.

  #### User feed

  - Support new sources of posts on user feed. `feedSources` can be selected on user feed query.

  #### Post title

  - Support optional `title` on post creation.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.21 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |


  ## 🚀 New Features

  #### Clip Post

  - Added `AmityFileRepository.uploadClip()` — upload short video clips.
  - Added `AmityPostRepository.createClipPost()` — create a post containing a clip.
  - Added `dataTypes` parameter to `getGlobalFeed()` for filtering feed content types.

  #### Livestream Chat & Reaction

  - Added `createLiveChannel(streamId)` — create a Live channel by Stream ID.
  - Added `createLiveReaction()` — send live reactions during livestreams.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Android Paging Data Library | 3.2.0 |
      | Firebase Messaging | 23.0.0 |
      | Gson | 2.9.0 |
      | HiveMQ MQTT client | 1.3.1-beta01 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.21 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

---

### [Flutter](https://learn.social.plus/social-plus-sdk/changelogs/flutter-sdk-changelog)

> This page contains an overview of all relevant changes made to the Flutter SDK

This page is generated from the Flutter SDK source changelog in `Amity-Social-Cloud-SDK-Flutter-Internal/CHANGELOG.md`. Entries preserve the source release wording and omit dates where the source changelog does not provide one.


  ## 🚀 New Features

  - Feat: Intelligent post search and intelligent community search (ported from the Android SDK).
  - Feat: Network-level story creation setting (`allowAllUserToCreateStory`).

  ## 🐞 Bug Fixes

  - Fix: Persist story targets so the seen state survives a restart; order the global story ring newest-first; forward the paging token when the global ring is in SMART mode.
  - Fix: Surface an approved post in the community feed immediately.
  - Fix: Community keyword search no longer returns unrelated communities.
  - Fix: Keep optimistic (unsynced) messages visible on the first page of a new conversation.
  - Fix: Keep the analytics event syncer alive through transient errors, and ensure live-collection `dispose()` completes.


- Fix: community list cross-contamination - CommunityObserveListUseCase changed from singleton to factory so each filter/sort combination gets its own StreamController


- Fix: community list sort instability during loadNext() - 3 compounding bugs fixed:
  - Sort comparator typo (`a.position` vs `a.position`) in paging ID adapter
  - Paging IDs saved one-at-a-time (N Hive watch events per page) -> now batch-saved
  - `_onChanges()` called without await allowing concurrent executions -> serialised with _inFlight queue


- Fix: community LiveCollection `avatarImage` always null - replaced broken unawaited forEach with `Future.wait` map


- Fix: post live object `children` never emits - images/videos always empty on live stream
- Fix: LiveCollection double emit causing UI flicker on every feed update


- Chore: Improve MQTT connection stabilities after app is reopened


- Fix: Fix inconsistent reaction when receive event through RTE
- Fix: Racing condition on channel Live Collection when receive new message


- Chore: Improve MQTT connection stabilities
- Fix: Fix optimistic update issue on story reaction
- Fix: Handle nullable user object when compose domain object


- Fix: Fix channel livecollection not updating on receiving new value


- Fix: Fix user property in follow


- Fix: Fix search message returning empty value


- Fix: Fix user avatar is missing when get user by id


- Fix: Error when calling getStream


- Fix: Incorrect global story target filtering


- Fix: Handle edge case for story filtering.


- Fix: Story targets now properly filtered to exclude expired stories.


- Fix: Include missing user information in reaction object


- Fix: Upgrade freezed package to latest version


- Fix: SDK throws null exception when logout


- Fix: Fix error on ChannelObserveTotalUnreadUseCase


- Feat: Create messages with custom JSON data payloads - `createCustomMessage()`
- Feat: Update existing custom messages with new data - `editCustomMessage()`
- Feat: Search messages across channels with advanced filters - `searchMessage()`
- Feat: Search channels by name with type and membership filters - `searchChannels()`
- Feat: Retrieve list of archived channel IDs - `getArchivedChannelIds()`


- Fix: Fix missing avatar url for current user object


- Feat: Introduce getMyMembership api on community object
- Fix: Fix null data in community object


- Fix: Add user matchType param


- Fix: Fix invalid session state when token expired


- Fix: Expose AccessTokenRenewal to public


- Fix: Fail to renew token
- Feat: Support channel get total unreads


- Fix: Fail to fetch community members
- Fix: Filter replies from First-level comments


- Feat: Update dependency version


- Feat: Add ability to flag message with reasons
- Feat: Performance improvements for live collections


- Feat: Create channel with users
- Feat: Add isPublic, moderatorCount and notificationMode for AmityChannel
- Feat: Add Channel member livecollection on search and query member.
- Fix: Reaction issue after mqtt event


- Fix: Get reaction return error on calling pagingData


- Fix: Get followings/followers api not return value as expected.


- Fix: Remove displaying log on null data


- Fix: Story data field is not updated properly


- Fix: Resolved issue where posts were duplicating after being edited


- Feat: Update file path of locally created message
- Feat: Included audio and video metadata


- Fix: Clear SDK related data in Hive database when logging out instead of deleting all Hive database data from device


- Feat: Ability to Archive/unarchive a channel
- Feat: Query archived channel
- Feat: Filter excluded archived channels from channel query


- Feat: post & comment as a brand
- Feat: urls in post & comment contents are highlighted now
- Feat: supported see more functionality if the content is too long in post & comment


- Breaking Change: Removed AmityRegionalSocketEndpoint from AmityCoreClientOption.
- Deprecate: Deprecated newGetMessages(String subchannelId), newCreateMessage(String subchannelId) API in MessageRepository.
- Feat: Introduced getMessages(String subchannelId) and createMessage(String subchannelId) API in MessageRepository.


- Fix: Fix issues when fetch following/follower user by getPagingData()


- Fix: Fix issue where message, follower and following is not updated in live collection


- Fix: Fix random crash when logout


- Feat: Update Community membership Live Collection to support RTE
- Feat: Introduce Following / Follower Live Collection
- Feat: Introduce User RTE
- Feat: Introduce Message Preview on channel object


- Feat: Introduce poll object as Linked object in post object


- Fix: Resolve inconsistent token renewal module


- Fix: Activate token watcher to do access token renewal automatically
- Fix: Fix race condition inside login api business logic


- Chore: Protected internal function inside Live Collection


- Feat: Change login api to session v5
- Feat: Introduce ability to renew access token automatically
- Feat: Accept session handler when login to handle access token renewal with auth token


- Fix: Address invalid exception when logging in offline
- Fix: Resolve issue with broken emoji messages received via MQTT


- Feat: Introduce Global featured posts
- Fix: Improve stability on MQTT reconnection
- Fix: Fix fail to fetch channels


- Feat: Update Reaction Live Collection to support RTE
- Fix: Handle null event name on reactor response


- Feat: Introduce SubChannel Repository in ChatClient


- Fix: Fix Comment Live Collection doesn't emit data when client doesn't specify isDeleted on query builder
- Fix: Fix Pinned post Live Collection doesn't emit data


- Feat: Update Comment Live Collection to use Query Stream
- Fix: Fix null channel.defaultSubChannelId


- Fix: Ensure service locator ready when setup SDK client


- Feat: Channel Live Object
- Feat: Message Live Object
- Feat: Message Live Collection
- Feat: User Live Object
- Feat: User Live Collection
- Feat: User Notification Setting
- Feat: Channel Notification Setting
- Feat: Introduce Video Message


- Feat: Expose default subchannelId for channel object
- Deprecate: Channel creation with custom channelId


- Fix: Fix reaction missing when receive post event through RTE


- Fix: Exclude deleted posts from global feed and custom post ranking Live Collection


- Feat: Introduce Subchannel
- Feat: Migrate Message to MessageV5
- Feat: Support auto subscribe to smartfeed RTE
- Feat: Introduce Channel Real-Time Events
- Feat: Introduce Subchannel Real-Time Events
- Fix: Fix MQTT connection stability on iOS devices


- Feat: Introduce ability to observe client session state
- Feat: Introduce ability to observe Live Collection loading state
- Feat: Post Live Collection
- Feat: Global feed Live Collection
- Feat: Custom ranking global feed Live Collection
- Feat: Pinned post Live Collection


- Fix: Fix invalid story reaction count


- Fix: Handle story issues


- Feat: Channel Live Collection
- Fix: Fix inconsistent behavior of Community Live Collection
- Feat: Support retain previous session after re-open the app


- Fix: Community live collection page size issue.


- Feat: Introduce 'includeDeleted' options to Channel Membership Query and Search, Community Membership Query and Search api.


- Fix:  Handle spamming unexpected error log from nullable objects.
- Chore: Config Dio to do JSON Parser on the background thread.


- Fix: Post Content being null after added or removing reaction from the Custom Post.


- Fix: Community live collection return wrong order when query with displayName filter.


- Feat: Ability to create and update custom post.


- Fix: Getting comment relies in the query comments.


- Feat: Add creator property as AmityUser to AmityReaction.


- Fix: PostedCommunityMember is always null.


- Feat: Global Story Target Added
- Feat: Story can be marked as view by AmityStory.analytics().markAsSeen()
- Feat: Story can be marked as Linked Clicked by AmityStory.analytics().markLinkAsClicked()
- Feat: Reached user for the AmityStory can be fetched.
- Feat: Story RTE Subscription added.
- Feat: Urls can be validated now by using AmityCoreClient().validateUrls(urls)
- Feat: Texts can be validated now by using AmityCoreClient().validateTexts(texts)


- Feat: Comment on Story added added
- Feat: Reply to Comment on Story has been added
- Feat: Reaction on Story  has been added
- Feat: Reaction to comment on Story  has been added
- Feat: Story Traget Live collection has been added (Get Story Targets by tragets)
- Feat: Story Traget Live Object has been added (Get Story Target by traget)


- Feat: Comment Live collection have been added
- Feat: Comment Live object has been added
- Feat: Reaction Live collection has been added
- Feat: Poll Live object has been added
- Feat: Community Live object has been added
- Feat: Community Live collection has been added
- Feat: Ability to create post with livestream id


- Fix: Handle spamming unexpected error log from nullable objects.


- Fix: Error of FeedType missmatched while creating the video story. Added ability to add FeedType while uploading video file.


- Fix: Handle spamming unexpected error log from nullable objects.


- Feat: The post count for a community can be fetched on the basis of AmityFeedType by using AmityCommunity.getPostCount.


- Feat: Video Story can be created using AmitySocialClient.newStoryRepository().createVideoStory.
- Feat: Image Story can be created using AmitySocialClient.newStoryRepository().createImageStory.
- Feat: StoryLiveCollection can be used to observe Active stories.


- Feat: Added Post Impression, now post can be marked as read using amityPost.analytics().markPostAsViewed(). Likewise post impression and reach can be get by using amityPost.impression and amityPost.reach
- Upgrade: Upgraded dart version from ">=2.15.1 <4.0.0" to ">=3.0.0 <4.0.0"
- Upgrade: Upgraded the dependencies except Socket as amity backend currently works on socket v2
- Fix: AmityFeedType filter not working on post live collection


- Feat: Post Live Object can be used by AmitySocialClient.newPostRepository().live.getPost(postId)
- Feat: Post Live collection have been added
- Feat: Now user can get category by AmitySocialClient.newCommunityRepository().getCategory(categoryId)
- Feat: Now user can get global feed custom ranking by AmitySocialClient.newFeedRepository().getCustomRankingGlobalFeed()


- Feat: Upgraded, Upgradable libraries that would not cuase breaking changes
- Refactor: AmitySocialClient.newCommunityRepository().getCurentUserRoles is depercated in favor of AmitySocialClient.newCommunityRepository().getCurrentUserRoles
- Fix: Crash when getting current user roles for community
- Fix: Crash when getting reations of post


- Upgrade: amity_sdk_version


- Fix: Exception when scrolling through the posts
- Feat: Auto Subscribe to the the network


- Feat: Added Support for getting live and recorded streams
- Feat: Configuration for AmityVideoPlayer added as well


- Fix: Width and Height coming null for video


- Feat: Added tags option when creating new message
- Fix: removed flaggedByMe in favour of isFlaggedByme for users


- Feat: Added comminity user rolers in comments
- Fix: Now video upload give back the upload progress


- fix: File is now optional so in case if file for a post is deleted it will return nulll instead of crashing


- fix: Get Post by ID not working


- fix: DataType Filter is now working on user and community feeds


- fix: Member can be removed from community and live channel
- fix: iOS can not receive notifications
- feat: Updated Dio to version 5


- feat: Added create comment with Image
- feat: Added query comment with Image
- refactor: align function signature and namespace for Core module
- refactor: align function signature and namespace for Social module
- refactor: align function signature and namespace for Chat module


- feat: Added user block/unblock
- feat: Added get blocked users
- fix: resolve issue with create commetn(Update comment count in post)


- feat: Added RTE event for Post topic
- feat: Added RTE event for Comment topic
- feat: Added RTE event for Channel topic
- feat: Added RTE event for Community topic


- feat: File uploading progress
- feat: Image uploading progress
- BREAKING FEAT: Updated Future Upload public API to Stream Upload API


- fix: resolve issue with community query delete flag


- feat: Community user search by keyword
- feat: Mention user in post creation
- feat: Mention user in comment creation
- fix: resolve issue with flag update


- feat: Global user search
- feat: Comunity User Search
- feat: Global user search sorting
- fix: Added amityuser avatar file in compose usecase


- feat: User mention in channel message
- feat: Channel mention in channel message
- feat: Channel message mention helper
- feat: Channel member search
- feat: isFlaggedByMe check for user
- fix: handled null check in live stream post


- feat: Reply to channel message
- feat: Flag/Unflag channel message
- feat: Flag/Unflag channel message sender
- feat: Add/Remove tags on channel message
- feat: Mute/Unmute channel from client side
- fix: Added Amity Object extension method for reporting message and user


- fix: Resolve issue Amity Message Update Query Builder


- feat: Channel Message Query & Filter
- feat: Channel Message Update
- feat: Channel Message Delete
- fix: Add tags support in v4/post query


- feat: Create/Update Channel
- feat: Mute/Unmute Channel Member
- feat: Ban/Unban Channel Member
- fix: Amity post my reaction after reaction update


- feat: Channel Member Add/Remove roles and permission
- feat: Check user perssion for channel
- fix: Channel Query filere validation


- feat: Channel Member Query
- fix: Update listner method for AmityChannelMember model


- feat: Channel Query
- feat: Get Channel By Id
- fix: resolve issue with Message RTE payload


- feat: Create image/file message
- feat: Channel repo setup
- feat: Join/Leave channel
- feat: Add/Remove message reactions
- feat: Message reactions query
- fix: change live collection stream to stream controller
- fix: Error handling in live collection


- feat: Create and Query Chat Message
- feat: Chat Message Live Collection
- feat: Foundation for Chat SDK


- feat: Flag/Unflag post and comment
- feat: init socket.io client
- feat: Bloom filter for hashflag functionlity


- feat: CRUD Poll Post
- feat: Close Poll Post
- feat: Vote Poll Post
- fix: resolve the issue with Global Ban flag


- feat: Post Query Reaction
- feat: Comment/Nested Comment Query Reaction
- fix: Blank Custom Avatar Url
- fix: Blank Unfollow Response
- refactor: Optimize import & public api doc


- fix: GET post api issue


- feat: follow/unfollow functionlity
- feat: accept/denied pending follow request functionlity
- feat: Query user follower/following
- fix: login issue without display name
- fix: nested comment loading issue


- feat: Community Post Review feature
- feat: Query community by tag
- feat: add tags in community
- feat: add recommend and trending communities in public repo
- feat: Add Community Category in Create & Update Community
- fix: data type filtering in get post API
- fix: resolve edge case with page controller blank token
- fix: resolve issue with multiple post in community feed
- fix: updated post query for v4 api


- fix: null category ID in Community Category hive entiry
- fix: resolve edge case with page controller blank token


- chore: enable the lint core and analyze the code


- fix: community category causes data corruption
- fix: post metadata is unable to update


- feat: Add Metadata in post, comment and community
- feat: Streams for Post, Comment, Community and Community Member
- feat: Community CRUD and Query
- feat: Community Member CRUD and Query
- feat: Community Member Roles & Permissions
- feat: Community feed query
- feat: Add/Remove Post and Comment reactions
- fix: resolve memory leak issue in post and comment object


- feat: Comment CRUD and Query
- fix: get_it instance issue


- docs: updated the README file
- docs: updated the LICENSE file


- feat: added example for Amity Core client setup and login
- fix: updated plugin to null safety
- fix: update the code according to flutter analyze


- docs: updated the README file

---

### [iOS](https://learn.social.plus/social-plus-sdk/changelogs/ios-sdk-changelog)

> This page contains an overview of all relevant changes made to the iOS SDK

**Xcode forward compatibility restored in SDK 8.0.0**

  The Xcode 26 compatibility issue caused by **RealmSwift** binaries has been fully resolved in **SDK 8.0.0**. The cache layer has been migrated from Realm to **Core Data**, eliminating the Realm dependency entirely and restoring forward compatibility across Xcode versions. We recommend upgrading to 8.0.0 or later to remove any Xcode version constraints from your project.

  See the [iOS SDK v8 Migration Guide](/social-plus-sdk/changelogs/ios-sdk-v8-migration-guide) for full upgrade instructions.

  ## 🚀 New Features

  #### Comment Approval for Communities

  A community can now require review before a new comment is visible. While a comment is pending, only its author, the community's reviewers, and network admins can see it. It stays out of public comment lists and comment counts until a reviewer approves it. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review).

  - **Turn it on:** `AmityCommunityDataBuilder.setNeedApprovalOnCommentCreation(_:)` on create or update. Read it back with `AmityCommunity.isCommentReviewEnabled`.
  - **Approval status:** `AmityComment.approvalStatus` is an `AmityCommentApprovalStatus` (`pending`, `approved`, `rejected`).
  - **Create without a local copy:** `AmityCommentCreateOptions(isOptimistic: false)` skips the local comment, so the comment you get back carries the server's approval status. The default, `true`, keeps today's behavior.
  - **Review queue:** `AmityCommentRepository.getCommentReviewQueue(with:)` returns the community's pending comments as an `AmityCollection<AmityComment>`. Narrow it to one post or a date range with `AmityCommentReviewQueueQueryOptions`.
  - **Approve or decline:** `AmityCommentRepository.approveComment(withId:)` and `declineComment(withId:reason:)`. Declining deletes the comment. The optional `reason` (at most 250 characters) is kept for the moderation record only.
  - **Permission:** reviewers need `AmityPermission.reviewCommunityComment`.
  - **Editing while pending:** `AmitySocialSettings.isAllowEditCommentWhenReviewingEnabled` tells you whether an author may edit a pending comment.
  - **Realtime:** an approved comment appears as soon as it is approved, through the `comment.approved` event. A declined comment arrives as a deletion.

  #### Curated Content

  Fetch the posts selected for a topic configured in the Console, and build your own discovery surface around them. A pool is one bounded, ranked result with no pagination, and the SDK keeps the server's order. See [Topic-based Content Discovery](/social-plus-sdk/social/discovery-engagement/feed/curated-content).

  - **Fetch a pool:** `AmityCuratedContentRepository.getPool(topicId:limit:)` is an `async throws` call that returns an `AmityCuratedContentPool`. `limit` must be between 1 and 100.
  - **Analytics:** `AmityCuratedContentTopic.analytics` (`AmityCuratedContentAnalytics`) provides `markAsViewed()`, `markPostAsViewed(postId:)`, and `markPostClick(postId:)`.

  #### Pin Message in Live Channels

  Pin one message in a live channel so it stays visible above the chat. Pinning a new message replaces the current pin. The server clears the pin when the message is deleted or its author is banned from the channel or globally. See [Pin and Unpin Messages](/social-plus-sdk/chat/messaging-features/messages/pin-message).

  - **Pin and unpin:** `AmityMessageRepository.pinMessage(withId:)` and `unpinMessage(withId:)`.
  - **Read the pin:** `AmityChannel.pinnedMessage` holds the current pinned message, or `nil` when nothing is pinned.
  - **Permission:** `AmityPermission.pinMessage`. Channel moderators, and livestream hosts and co-hosts, have it by default. Channel role changes now update a member's permissions in real time, so a promoted or demoted member's pin permission changes immediately.
  - **Realtime:** the observed `AmityChannel` updates on every pin and unpin, driven by the `channel.messagePinned` and `channel.messageUnpinned` events.

  #### Typed Network Activity Observation

  Added `AmityClient.observeNetworkActivities(_:)`, a typed observer that supports multiple observers and replaces the previous single-slot callback. It returns a cancellable `AmityNetworkActivityToken` and delivers `AmityNetworkActivity` records for HTTP, upload, download, and MQTT traffic. Each record is labeled with an `AmityNetworkActivityType` and carries real timings and byte counts. The previous `observeNetworkActivities((URLRequest?, HTTPURLResponse?, Data?) -> Void)` overload is deprecated but still works.

  ## ✨ Improvements

  - Added `AmityPost.getLocalCommentCount(includePending:)`. By default, the count leaves out the current user's own comments that are still awaiting approval. Pass `true` to include them. `AmityPost.localCommentCount` is now deprecated and equals `getLocalCommentCount(includePending: true)`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Configurable Search Fields

  Added a search user type and a `searchBy` option to control which fields user search matches.

  #### Livestream Viewer Configuration

  Added livestream viewer configuration.

  #### v4 Sessions

  Updated the `loginWithAccessToken` API endpoint to use v4 sessions.

  ## 🐞 Bug Fixes

  - Fixed the avatar relationship not clearing when `avatarFileId` is emptied.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Event Posts

  Added event-post support: an event shared to a community feed is delivered as a post (post `dataType` `event`), resolves through the event repository, and renders alongside regular posts.

  ## 🐞 Bug Fixes

  - Fixed a notification-tray seen-state issue.
  - Fixed staging regressions.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed permission values to match the backend.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed the query stream retaining objects that have left their context.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed the query stream reactor incorrectly processing items from a foreign entity.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed channel unread-count handling and channel data persistence.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Report User

  Updated the report-user API to report a user profile with a reason.

  ## ✨ Improvements

  - Dropped the MQTT will message as part of the MQTT protocol alignment.

  ## 🐞 Bug Fixes

  - Fixed `getArchivedChannels()` to fetch and persist the channel list.
  - Fixed the sort order of the archived chats list.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed issues with channel archiving.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### For You Feed

  Added the personalized **For You** feed. Query it with `getForYouFeed()` and gate the surface on the network setting so the feed only renders when For You is enabled for the network.

  #### Bidirectional Block Visibility

  Added the reverse direction of the blocking model — the ability to read the users who have blocked the current user, alongside the existing blocked-user list.

  #### Shareable Link Configuration API

  Updated the shareable-link configuration API with a typed `AmitySharableContentType`, so links can be generated per content type (post, community, user, livestream, event) via `isEnabled(_:)` and `generateLink(_:referenceId:)`.

  ## 🐞 Bug Fixes

  - Fixed a message reaction bug.
  - Fixed event community being lost when the payload omits it.
  - Fixed a notification-tray item "seen" state issue.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed a SIGSEGV crash in `PostCommentCountEngine`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Community Tag Filtering

  Added `tags` parameter to `AmityCommunityQueryOptions`. Pass a list of tags to `getCommunities()` to narrow results to communities matching all specified tags.

  #### Visitor Daily Usage Limit

  Added detection for the visitor daily read quota (100 req/day, error code `400323`). When a visitor exceeds this limit, the SDK detects the error and emits an event via `AmityClient.getVisitorUsageLimitEvents() -> AnyPublisher<AmityVisitorUsageLimitEvent, Never>`.

  ## 🐞 Bug Fixes

  - Fixed event bus observation not being torn down during `AmityClient` initialization, causing stale observers.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed a crash when SDK APIs are called before `AmityClient` is set up.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed analytic data sync issue in the SDK.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed stale session data issue after secure logout.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed issue where `mentionees` value becomes empty when multiple posts contain the same mentioned user.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4.1 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🐞 Bug Fixes

  - Fixed issue where users couldn't RSVP to some events.
  - Made timestamp properties `createdAt` and `updatedAt` non-optional for some models.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4.1 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Core Data-Powered Cache Layer

  Migrate the SDK's local cache from Realm to **Core Data**, eliminating the Realm and RealmSwift dependencies. This fully restores Xcode forward compatibility — no more per-Xcode-version SDK variants are required.

  ## 🚨 Breaking Changes

  #### Realm Dependency Removed

  Realm and RealmSwift are no longer bundled with or required by the SDK. Remove these libraries from your project's dependencies when upgrading to 8.0.0.

  See the [iOS SDK v8 Migration Guide](/social-plus-sdk/changelogs/ios-sdk-v8-migration-guide) for a full list of breaking changes, renamed APIs, and upgrade steps.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 26.4.1\+ |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Starscream | 3.1.1 |


  ## 🚀 New Features

  #### Auto-Retry for MQTT Topic Subscriptions

  Add an automatic retry mechanism for MQTT topic subscriptions, improving connection resilience when subscriptions fail due to transient network issues.

  ## 🐞 Bug Fixes

  - Fixed `AmityCollection` for posts emitting redundant updates when the underlying data had not changed.

  #### Specific Xcode support

  26.4 =\> 7.19.1

  26.4.1 =\> 7.19.1-xcode26.4.1

  26.3 =\> 7.19.1-xcode26.3

  26.2 =\> 7.19.1-xcode26.2

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 26.4 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 20.0.3 |
      | Realm Swift | 20.0.3 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Live Thumbnail and Resolution in AmityRoom

  Add `liveThumbnailUrl`, `liveResolution`, and `recordedResolution` fields to `AmityRoom` to expose server-generated thumbnail and stream resolution data.

  #### Link Detection in Comments

  Add link detection support to comment create/update APIs, enabling automatic link parsing in comment text.

  #### Root Comment and Latest Comment ID in Query

  Add `rootId` and `latestCommentId` fields to the comment query API for improved comment threading and navigation.

  #### Page Size for Get Comments

  Add `pageSize` parameter to `getComments` API for more granular control over comment pagination.

  #### Specific Xcode support

  26.4 =\> 7.19.0

  26.3=\> 7.19.0-xcode26.3

  26.2 =\> 7.19.0-xcode26.2

  ## 🐞 Bug Fixes

  - Fixed `LiveCollection` observation not being removed when an error occurs on loading the next page.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 26.4 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 20.0.3 |
      | Realm Swift | 20.0.3 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Product Tagging in Posts

  Introduce `AmityProduct` and `AmityProductTag` models with product search API, enabling users to tag up to 20 products per post via text mentions and per-media tags. Supports creating and updating posts with product tags.

  #### Livestream Product Tagging

  Introduce product management APIs for livestream(Room) post — tag, pin, and remove products across all broadcast phases.

  #### Specific Xcode support

  26.3 =\> 7.18.1

  16.x =\> 7.18.1-xcode16.4

  26.2 =\> 7.18.1-xcode26.2

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Get All Blocked Users

  Introduce `getAllBlockedUsers(completion:)` on `AmityUserRepository` — returns the full list of blocked users (up to 100) as a non-paginated, one-shot async result with a 5-minute TTL cache.

  #### Excluding Roles in Community Member Queries

  Add `excludingRoles` parameter to `getMembers()` and `searchMembers()`. Members holding any of the specified roles are excluded from the live collection result.

  #### Time-Bounded Post Pagination

  Add `untilAt` parameter to `getPosts`, `getCommunityFeed`, and `getUserFeed` queries. When provided, the SDK stops fetching and collecting posts beyond the given datetime boundary.

  #### Specific Xcode support

  26.2 =\> 7.17.0

  16.x =\> 7.17.0-xcode16.4

  26.1 =\> 7.17.0-xcode26.1\
  \
  26.3 =\> 7.17.0-xcode26.3

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Thread Safety

  All of CRUD API, AmityObject and AmityCollection API are now safe to be called from any actors.

  #### Authentication

  Introduce an ability to login with a pre-fetched `accessToken`.

  #### Comment Count

  Introduce a local calculated comment count based on incoming real-time events.

  #### Community Post Query by Tags

  Introduce an ability to community posts with matching tags.

  #### Specific Xcode support

  26.2 =\> 7.15.0

  16.x =\> 7.15.0-xcode16.4

  26.1 =\> 7.15.0-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Thread safety

  - Introduce two new static initializer method in AmityClient to initialize client safely in any thread

```text
AmityClient.setup(apiKey: String, region: AmityRegion) async throws -> AmityClient
AmityClient.setup(apiKey: String, endpoint: AmityEndpoint) async throws -> AmityClient
```

  - Mark AmityClient as @unchecked Sendable

  #### Specific Xcode support

  26.2 =\> 7.14.1-beta4

  16.x =\> 7.14.1-beta4-xcode16.4

  26.1 =\> 7.14.1-beta4-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Livestream analytics

  Introduce `AmityRoomAnalytics` for the purpose of tracking watch minute

  #### Specific Xcode support

  26.2 =\> 7.15.0

  16.x =\> 7.15.0-xcode16.4

  26.1 =\> 7.15.0-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Thread safety

  - Enable LiveObject/Collection to be initialized from any actors
  - Ensure thread safety on AmityClient props and functions.

  #### Specific Xcode support

  26.2 =\> 7.14.1-beta3

  16.x =\> 7.14.1-beta3-xcode16.4

  26.1 =\> 7.14.1-beta3-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Thread safety

  - Ensure thread safety on topic subscription.

  #### Specific Xcode support

  26.2 =\> 7.14.1-beta2

  16.x =\> 7.14.1-beta2-xcode16.4

  26.1 =\> 7.14.1-beta2-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Thread safety

  - Enable CRUD functions to called from any actors
  - Ensure public model(except AmityClient) properties are thread-safe.

  #### Specific Xcode support

  26.2 =\> 7.14.1-beta1

  16.x =\> 7.14.1-beta1-xcode16.4

  26.1 =\> 7.14.1-beta1-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Livestream Post with Room

  Introduce Room service, an upgrade and a replacement for`stream`

  #### Event

  Introduce Event service, enabling event scheduling

  #### Community Member Query

  Introduce `lastJoin` sorting option

  #### Specific Xcode support

  26.1 =\> 7.14.0

  16.x =\> 7.14.0-xcode16.4

  26.2 =\> 7.14.0-xcode26.2

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚨 Compatibility Changes

  #### Xcode 26.1 support

  - The binary is now built with Xcode 26.1, ensuring compatibility with Xcode 26.1 and later. The minimum toolchain version is now Xcode 26.1. Earlier Xcode versions are no longer supported.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 26.1 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚨 Compatibility Changes

  #### Xcode 26 support

  - The binary is now built with Xcode 26, ensuring compatibility with Xcode 26 and later. The minimum toolchain version is now Xcode 26. Earlier Xcode versions are no longer supported.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Alamofire | 5.7.1 |
      | CocoaAsyncSocket | 7.6.5 - Hash: 2129f84 |
      | CocoaMQTT | 3.1.1 - Hash: 2731e27 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |
      | Starscream | 3.1.1 |

  ## 🚀 New Features

  #### Mixed Attachments Post

  - Support `mixed` structure post where a post can contains multiple datatypes such as image, video, file, and audio.

  #### Audio Content Support

  - Support audio file upload.
  - Introduce `audio` dataType for post.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.0\+ |

      | Library | Version |
      | :-- | :-- |
      | Realm | 10.54.5 |
      | Realm Swift | 10.54.5 |

  ## 🚀 New Features

  #### Public Access

  - Added `loginAsVisitor()` function, enables user to interact as a visitor.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.0\+ |

      | Library | Version |
      | :-- | :-- |
      | Realm | 10.54.5 |
      | Realm Swift | 10.54.5 |

  ## 🚀 New Features

  #### Child stream

  - Support child stream creation where a child stream can be linked to a parent stream.

  #### Poll

  - Added `unvotePoll()` function, enables user to update poll answer.

  #### Preview members

  - Added `getPreviewMembers()` on `AmityChannel`, enables access upto 4 members of converation and community channel.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.0\+ |

      | Library | Version |
      | :-- | :-- |
      | Realm | 10.54.5 |
      | Realm Swift | 10.54.5 |

  ## 🚀 New Features

  #### PII detection

  - Added detected PII data to post, comment, and message.

  #### Hashtag

  - Support adding hashtag to a post.
  - Support post search by hashtag.

  #### User feed

  - Support new sources of posts on user feed. `feedSources` can be selected on user.

  #### Post title

  - Support optional `title` on post creation.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.0 |
      | Xcode | 16.0\+ |

      | Library | Version |
      | :-- | :-- |
      | Realm | 10.49.3 |
      | Realm Swift | 10.49.3 |

---

### [iOS SDK v7 → v8 Migration Guide](https://learn.social.plus/social-plus-sdk/changelogs/ios-sdk-v8-migration-guide)

> A complete guide to all breaking changes, renamed APIs, and new features when upgrading the iOS SDK from v7 to v8.

**Xcode 26 compatibility is fully restored in v8.** The cache layer has been migrated from Realm to Core Data, eliminating all Realm dependencies and removing the need for per-Xcode-version SDK variants.

  Code blocks in this migration guide compare v7 and v8 shapes. v7 snippets intentionally reference removed APIs; use the v8 snippets for new code.

## What changed in v8

SDK v8 is a major release focused on three goals:

1. **Remove Realm** — the cache layer is now powered by Core Data, restoring Xcode forward compatibility and removing a heavyweight dependency from your project.
2. **Modernise the API surface** — constructors, async methods, and model objects follow consistent, Swift-idiomatic patterns.
3. **Expand product tagging and room capabilities** — new APIs for product tags, room management, and co-host permissions.

---

## Installation

### SDK

Realm and RealmSwift are no longer required as of v8.

| Method | Steps |
| :----- | :---- |
| **Swift Package Manager** | No changes needed. Install using the v8 release tag. Realm is not installed by default. |
| **Manual (xcframework)** | Remove `Realm.xcframework` and `RealmSwift.xcframework` from your project. Embed the new `AmitySDK.xcframework` as usual. |

**Minimum iOS target:** 14.0

### UIKit

| Method | Steps |
| :----- | :---- |
| **Swift Package Manager** | No changes needed. Install using the v8 UIKit release tag. |
| **Manual (xcframework)** | Remove `Realm.xcframework` and `RealmSwift.xcframework`. Embed the new `AmitySDK.xcframework` as usual. |
| **Open Source** | `Realm.xcframework` and `RealmSwift.xcframework` are no longer installed through the `SharedFrameworks` Package.swift file. |

**Minimum iOS target:** 14.0

---

## Global breaking changes

These patterns apply across the **entire SDK**. Per-class sections below only document changes beyond these rules.

### 1. Client removed from constructors

All repositories and managers no longer accept an `AmityClient` parameter. The SDK manages the client internally.


{/* doc-as-test: skip (migration comparison includes v7 APIs removed from current SDK) */}
```swift
// v7
let repo = AmityMessageRepository(client: client)
let mod  = AmityCommunityModeration(client: client, andCommunity: communityId)

// v8
let repo = AmityMessageRepository()
let mod  = AmityCommunityModeration(communityId: communityId)
```


### 2. Mutating methods return `Void`

Methods that previously returned `Bool` to indicate success now return `Void`. A successful call means success; any failure throws an error.


{/* doc-as-test: skip (migration comparison includes v7 APIs removed from current SDK) */}
```swift
// v7
let success = try await repo.softDeleteMessage(withId: id) // Bool

// v8
try await repo.softDeleteMessage(withId: id) // Void — throws on failure
```


### 3. Completion handlers replaced with async/await

Use async/await directly instead of callback-based completion handlers when enabling features or reading settings.


{/* doc-as-test: skip (migration comparison includes v7 APIs removed from current SDK) */}
```swift
// v7
manager.enable(completion: { error in ... })
let _ = manager.getSettings(completion: { settings in ... })

// v8
try await manager.enable()
let settings = try await manager.getSettings()
```


### 4. Model objects are immutable value snapshots

- `model` and `client` properties removed from all model classes.
- All properties changed from `var` to `let`. Exceptions are noted per class.
- Timestamp properties (`createdAt`, `updatedAt`, `editedAt`, etc.) changed from `Date` to `Date?`.

### 5. `AmityCollection` observe callback signature changed

`AmityCollectionChange` has been removed. The callback no longer delivers per-change index information.


{/* doc-as-test: skip (migration comparison includes v7 APIs removed from current SDK) */}
```swift
// v7
collection.observe { collection, change, error in ... }

// v8
collection.observe { collection, error in ... }
```


---

## Renamed classes

| v7 | v8 |
| :- | :- |
| `AmityChannelQuery` | `AmityChannelQueryOptions` |
| `AmityChannelUpdateBuilder` | `AmityChannelUpdateOptions` |
| `AmityCommunityChannelBuilder` | `AmityCommunityChannelCreateOptions` |
| `AmityConversationChannelBuilder` | `AmityConversationChannelCreateOptions` |
| `AmityDefaultChannelBuilder` | `AmityDefaultChannelCreateOptions` |
| `AmityLiveChannelBuilder` | `AmityLiveChannelCreateOptions` |
| `AmityRawFile` | `AmityFile` |
| `AmityUserUpdateBuilder` | `AmityUserUpdateOptions` |

---

## New classes

| Class | Description |
| :---- | :---------- |
| `AmityFile` | Replaces `AmityRawFile`. Adds `fileUrl`, `altText`, `feedType`, `status`, `videoUrl`, `attributes`. |
| `AmityMetadataMapper` | Replaces the deprecated `AmityMentionMapper`. Supports both mentions and hashtags. |
| `AmityTextProductTag` | A product tag embedded in post text: `productId`, `product`, `index`, `length`. |
| `AmityMediaProductTag` | A product tag attached to a media item: `productId`, `product`. |
| `AmityAttachmentProductTags` | Container for per-attachment product tags when creating or editing posts. |
| `AmityProduct` | New product model: `productId`, `productName`, `productUrl`, `status`, `price`, `currency`, `thumbnailUrl`, etc. |
| `AmityProductCatalogueSetting` | Product catalogue setting from the server: `enabled: Bool`. |
| `AmityRoomResolution` | Stream resolution info for a room: `aspectRatio`, `width`, `height`. |

---

## Removed APIs

| Class | Removed | Replacement |
| :---- | :------ | :---------- |
| `AmityCollection` | `count()` | `snapshots.count` |
| `AmityCollection` | `object(at:)` | `snapshots[index]` |
| `AmityCollection` | `allObjects()` | `snapshots` |
| `AmityChannel` | `getPreviewMembers()` | `previewMembers` property |
| `AmityCollectionChange` | Entire class | — |
| `AmityAdImage` | Entire class | — |
| `AmityUserRepository` | `userRelationship` property | Instantiate `AmityUserRelationship()` directly |

---

## Per-class changes

Only changes **beyond** the global breaking changes are listed here.


    | Change | Details |
    | :----- | :------ |
    | `currentMembership` renamed | → `currentMember: AmityChannelMember?` |
    | `previewMembers` added | `[AmityChannelMember]` — replaces the removed `getPreviewMembers()` method |
    | `attachedToPost`, `attachedToStream` removed | No replacement |
    | `attachedToRoom` | Now externally read-only (`public private(set) var`) |

    Init signature changed: `init(channelId: String)` — no client parameter.

    Init signature changed: `init(channelId: String)` — no client parameter.

    - Init signature changed: `init(channelId: String)`
    - `getSettings()` return type is now `AmityChannelNotificationSettings`

    All options must now be provided at initialisation rather than mutated after the fact.


    {/* doc-as-test: skip (migration comparison includes v7 APIs removed from current SDK) */}
```swift
// v7 — mutate after init
let query = AmityChannelQuery()
query.types = [...]

// v8 — configure at init
let options = AmityChannelQueryOptions(
    types: [...],
    filter: .all,
    includingTags: [],
    excludingTags: [],
    includeDeleted: false
)
```


    | Method | Change |
    | :----- | :----- |
    | `getChannels(with:)` | Parameter type: `AmityChannelQuery` → `AmityChannelQueryOptions` |
    | `createChannel(with:)` | Parameter type: `AmityChannelBuilder` → `AmityChannelCreateOptions` |
    | `editChannel(with:)` | Parameter type: `AmityChannelUpdateBuilder` → `AmityChannelUpdateOptions` |

    `editUser(_:)` parameter type changed: `AmityUserUpdateBuilder` → `AmityUserUpdateOptions`

    - `links: [AmityLink]` added
    - `isInvalidated` removed

    `links: [AmityLink]?` added.

    `pageSize: Int = 20` added.

    `links: [AmityLink]?` added.

    - `user: AmityUser?` added (the community creator/owner)
    - `event` property removed

    - Init signature changed: `init(communityId: String)`
    - `getMembers(...)` and `searchMembers(...)` gain `excludingRoles: [String] = []`

    Init signature changed: `init(communityId: String)` — no client parameter.

    Init signature changed: `init(communityId: String)`

    | v7 | v8 |
    | :- | :- |
    | `enable(for events:completion:)` | `enable(events:) async throws` |
    | `disable(completion:)` | `disable() async throws` |
    | `getSettingsWithCompletion(_:)` | `getSettings() async throws -> AmityCommunityNotificationSettings` |

    | v7 | v8 |
    | :- | :- |
    | `deleteCommunity(withId:completion:)` | `deleteCommunity(withId:) async throws` |
    | `joinCommunity(withId:) async throws -> Bool` | No longer deprecated. Returns `Void`. |
    | `leaveCommunity(withId:) async throws -> Bool` | Returns `Void`. |

    | v7 | v8 | Notes |
    | :- | :- | :---- |
    | `getMyFeedSorted(feedSources:dataTypes:by sortBy:...)` | `getMyFeed(feedSources:dataTypes:sortBy:...)` | Renamed; `by sortBy:` label removed |
    | `getUserFeed(...)` | `getUserFeed(...)` | Added `untilAt: Date?` |
    | `getCommunityFeed(...)` | `getCommunityFeed(...)` | Added `untilAt: Date?` |

    `getFile(fileId:)` return type changed: `AmityRawFile` → `AmityFile`

    **Typo fixed:** `tartgetId` → `targetId`. Update all call sites.

    `setVideoStreamId(_:)` is deprecated. Use `setRoomId(_:)` instead.

    Still available but deprecated. Migrate to `AmityMetadataMapper`.

    | Deprecated | Replacement |
    | :--------- | :---------- |
    | `AmityMentionMapper.mentions(fromMetadata:)` | `AmityMetadataMapper.mentions(fromMetadata:)` |
    | `AmityMentionMapper.metadata(from:)` | `AmityMetadataMapper.metadata(mentions:hashtags:)` |

    `AmityMetadataMapper` also adds `hashtags(fromMetadata:) -> [AmityHashtag]`.

    | v7 | v8 |
    | :- | :- |
    | `deleteFailedMessages(completion:)` | `deleteFailedMessages() async throws` |
    | `setTags(messageId:tags:completion:)` | `setTags(messageId:tags:) async throws` |
    | `flagMessage(withId:) async throws -> Bool` | No longer deprecated. Returns `Void`. |

    - `postData` type renamed: `AmityPost.Data` → `AmityPost.PostData`
    - `pinnedProductId: String?` added
    - `eventId: String?` added
    - `isInvalidated` removed
    - Remaining mutable properties: `postData`, `analytics`, `syncState`, `mentionees`, `links`

    `untilAt: Date?` added.

    All `createXxxPost(...)` and `editPost(...)` methods gain:
    - `productTags: [AmityTextProductTag]?`
    - `attachmentProductTags: AmityAttachmentProductTags?` (where applicable)

    Additional changes:

    | Change | Details |
    | :----- | :------ |
    | `flagPost(withId:)` deprecated variant removed | Use `flagPost(withId:reason:) async throws` |
    | `createRoomPost(...)` added | Dedicated method for room/co-host posts using `AmityRoomPostBuilder` |
    | `pinProduct(postId:productId:) async throws -> AmityPost` added | Pin a product to a post |
    | `unpinProduct(postId:) async throws -> AmityPost` added | Remove the pinned product from a post |
    | `updateProductTags(postId:productTags:) async throws -> AmityPost` added | Update media product tags on a post |

    - `thumbnail: AmityImageData?` added
    - `liveThumbnailUrl: String?` added
    - `liveResolution: AmityRoomResolution?` added
    - `recordedResolution: AmityRoomResolution?` added
    - `isInvalidated` removed
    - `channel` and `post` are now externally read-only (`public private(set) var`)

    `canManageProductTags: Bool` added.

    Init signature changed: `init(roomId: String)` — no client parameter.

    New method: `updateCohostPermissions(roomId:cohostId:canManageProductTags:) async throws -> AmityRoom`

    `disposeStream(withId:completion:)` → `disposeStream(withId:) async throws -> AmityStream`

    Init gains new parameters: `init(channelId:isDeleted:excludeDefaultSubChannel:)` — both new parameters default to `false`.

    - `isBanned` removed
    - Added: `internalId: String`, `permissions: [String]`, `path: String`, `blockedAt: Date?`, `avatar: AmityImageData?`

    - `enable(for modules:)` returns `Void`
    - `disableAllNotifications()` returns `Void`

    - `follow(withUserId:)`, `unfollow(withUserId:)`, `acceptMyFollower(withUserId:)`, `declineMyFollower(withUserId:)` — return type changed from `(Bool, AmityFollowResponse)` to `AmityFollowResponse`
    - `blockUser(userId:)` and `unblockUser(userId:)` are now `@MainActor`

    **Typo fixed:** `tartgetId` → `targetId`. Update all call sites.

---

### [TypeScript](https://learn.social.plus/social-plus-sdk/changelogs/web-sdk-changelog)

> This page contains an overview of all relevant changes made to the TypeScript SDK

This page is checked against `@amityco/ts-sdk` package metadata and the TypeScript SDK source changelog in `AmityTypescriptSDK/CHANGELOG.md`.

  ## 🚀 New Features

  #### Comment Approval for Communities

  A community can now require review before a new comment is visible. While a comment is pending, only its author, the community's reviewers, and network admins can see it. It stays out of public comment lists and comment counts until a reviewer approves it. See [Comment Review](/social-plus-sdk/social/content-management/comments/moderation/comment-review).

  - **Turn it on:** set `needApprovalOnCommentCreation` when you create or update the community.
  - **Approval status:** `comment.approvalStatus` is `pending`, `approved`, or `rejected`.
  - **Create without a local copy:** `CommentRepository.createComment(bundle, false)` skips the local comment, so the comment you get back carries the server's approval status. The default, `true`, keeps today's behavior.
  - **Review queue:** `CommentRepository.getCommentReviewQueue` returns the community's pending comments. Narrow it to one post or a date range.
  - **Approve or decline:** `CommentRepository.approveComment` and `declineComment`. Declining deletes the comment. The optional `reason` (at most 250 characters) is kept for the moderation record only.
  - **Permission:** reviewers need `ReviewCommunityCommentPermission`.
  - **Editing while pending:** `Client.getSocialSettings()` returns `isAllowEditCommentWhenReviewingEnabled`, which tells you whether an author may edit a pending comment.
  - **Realtime:** an approved comment appears as soon as it is approved, through the `comment.approved` event. Subscribe with `CommentRepository.onCommentApproved`. A declined comment arrives as a deletion.

  #### Curated Content

  Fetch the posts selected for a topic configured in the Console, and build your own discovery surface around them. A pool is one bounded, ranked result with no pagination, and the SDK keeps the server's order. See [Topic-based Content Discovery](/social-plus-sdk/social/discovery-engagement/feed/curated-content).

  - **Fetch a pool:** `CuratedContentRepository.getPool(topicId, limit?)` returns a promise of the pool: the topic plus its ranked posts. `limit` must be between 1 and 100.
  - **Analytics:** `topic.analytics` provides `markAsViewed()`, `markPostAsViewed(postId)`, and `markPostClick(postId)`.

  #### Pin Message in Live Channels

  Pin one message in a live channel so it stays visible above the chat. Pinning a new message replaces the current pin. The server clears the pin when the message is deleted or its author is banned from the channel or globally. See [Pin and Unpin Messages](/social-plus-sdk/chat/messaging-features/messages/pin-message).

  - **Pin and unpin:** `MessageRepository.pinMessage` and `unpinMessage`.
  - **Read the pin:** `channel.pinnedMessage` holds the current pinned message, or `null` when nothing is pinned.
  - **Permission:** `PinMessagePermission`. Channel moderators, and livestream hosts and co-hosts, have it by default.
  - **Realtime:** `ChannelRepository.getChannel` emits on every pin and unpin, driven by the `channel.messagePinned` and `channel.messageUnpinned` events. `ChannelRepository.onChannelMessagePinned` and `onChannelMessageUnpinned` are also available as separate callbacks.

  #### Local Event on Channel Creation

  `createChannel` now fires a local `channel.created` event right after a successful create. A newly created channel appears immediately in a running `ChannelRepository.getChannels` query, instead of waiting for its first message.

  ## ✨ Improvements

  - Added `post.getLocalCommentCount(includePending)`. By default, the count leaves out the current user's own comments that are still awaiting approval. Pass `true` to include them. `post.localCommentCount` is now deprecated and equals `getLocalCommentCount(true)`.

  ## 🐞 Bug Fixes

  - Fixed a member's channel role change (`channel.roleAdded` / `channel.roleRemoved`) not updating `ChannelRepository.getChannel`, which could leave a stale pin permission.
  - Fixed a globally banned user's session staying active when the realtime ban event was missed. The next API call now terminates the session and notifies `onClientBanned`.
  - Fixed a deleted message's text lingering in the channel list preview when the preview setting excludes deleted messages.
  - Fixed `message.creator.avatar` always resolving to `undefined` even though the type declared it.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🐞 Bug Fixes

  - Fixed a crash from an unhandled MQTT CONNACK timeout error arriving on a connection that had already been discarded.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### v4 Sessions

  Migrated `loginWithAccessToken` to v4 sessions.

  #### Skip Token Renewal for Banned Users

  Token renewal is now skipped for globally banned users.

  ## 🐞 Bug Fixes

  - No longer builds a cache key from an id the payload left null.
  - Capped the MQTT v5 session expiry at 1800s.
  - Typed the video file metadata.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## ✨ Improvements

  - Maintenance release published as part of the 28 August coordinated release. No new functional changes since 7.25.0.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Report User with Reason

  Added the ability to report a user with a reason.

  ## ✨ Improvements

  - Upgraded the MQTT client to protocol v5.

  ## 🐞 Bug Fixes

  - Added an `excludeOwnEvents` query parameter to event queries.
  - Fixed the message preview not updating in real time on edit.
  - Added `actorUserId` to co-host data.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🐞 Bug Fixes

  - Fixed the `liveChatEnabled` field type on the room (live) object.
  - Fixed the community avatar not resolving for stories.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### For You Feed

  Added a personalized **For You** feed. New APIs let you fetch the recommended feed and read its network-level setting, and the feed reports a "caught up" state once the user has seen all available recommendations.

  #### Notification Settings

  Added APIs to read and update user notification settings.

  #### Chat Settings API

  Added a chat settings API for configuring channel and messaging behavior.

  #### Channel Search Live Collection

  Added a live collection for searching channels, so search results stay in sync as data changes.

  #### Enhanced User Blocking

  A new API to list all users blocking the current user, a public auto-subscription enum, and a dedicated error code emitted when the maximum number of blocked users is reached.

  #### Shareable Link Configuration

  Updated the `getShareableLinkConfiguration` schema.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Visitor Daily Usage Limit

  Added detection for the visitor daily read quota (100 req/day, error code `400323` — `ServerError.VISITOR_USAGE_LIMIT_EXCEEDED`). The SDK detects this error in the Axios response interceptor and emits an  `visitorUsageLimitReached` event. Subscribe via `onVisitorUsageLimitReached(callback)`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Optimistic Comment Creation

  - Added optimistic comment creation support — comments now appear instantly in the UI before server confirmation, improving perceived performance.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## ✨ Improvements

  - Improved MQTT connection retry mechanism for better real-time messaging stability.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🐞 Bug Fixes

  - Fixed incorrect unread count increment for live channels, which caused `getTotalUnreadCount` to return inaccurate results.
  - Fixed incorrect local `commentsCount` increment.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Get All Blocked Users

  Introduce `getAllBlockedUsers()` on `UserRepository` — returns the full list of blocked users (up to 100) as a non-paginated, one-shot `Promise<Amity.User[]>` with a 5-minute TTL cache.

  #### Excluding Roles in Community Member Queries

  Add `excludingRoles` parameter to `getMembers()` and `searchMembers()` query params. Members holding any of the specified roles are excluded from the live collection result.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Live Thumbnail and Resolution in AmityRoom

  Add `liveThumbnailUrl`, `liveResolution`, and `recordedResolution` fields to `AmityRoom` to expose server-generated thumbnail and stream resolution data.

  #### Link Detection in Comments

  Add link detection support to comment create/update APIs, enabling automatic link parsing in comment text.

  #### Root Comment and Latest Comment ID in Query

  Add `rootId` and `latestCommentId` fields to the comment query API for improved comment threading and navigation.

  #### Page Size for Get Comments

  Add `pageSize` parameter to `getComments` API for more granular control over comment pagination.

  ## 🐞 Bug Fixes

  - Fixed posts going missing after paging REFRESH.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Product Tagging in Posts

  Introduce product tagging support in posts — tag products in post text via `@` trigger and per-media. Includes product search and create/update post with product tags.

  #### Livestream Product Tagging

  Introduce product management in livestream(Room) post — tag, pin, and remove products across broadcast phases.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### User Search

  Introduced a new `searchBy` param in `searchUsersByDisplayName` API providing additional search options.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Authentication

  Introduce an ability to login with a pre-fetched `accessToken`.

  #### Comment Count

  Introduce a local calculated comment count based on incoming real-time events.

  #### Community Post Query by Tags

  Introduce an ability to community posts with matching tags.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Livestream Analytics

  Introduce `AmityRoomAnalytics` for the purpose of tracking watch minute

  #### Session Termination Reason

  Introduce `reason` when client goes into `termianted` state

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Livestream Post With Room

  Introduce Room service, an upgrade and a replacement for`stream`

  #### Event Scheduling

  Introduce Event service, enabling event scheduling

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Mixed Attachments Post

  - Support `mixed` structure post where a post can contains multiple datatypes such as image, video, file, and audio.

  #### Audio Content Support

  - Support audio file upload.
  - Introduce `audio` dataType for post.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Public Access

  - Added `loginAsVisitor()` function, enables user to interact as a visitor.
  - Added `loginAsBot()` function, enables SEO bot to crawl through public data.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

  ## 🚀 New Features

  #### Child stream

  - Support child stream creation where a child stream can be linked to a parent stream.

  #### Poll

  - Added `unvotePoll()` function, enables user to update poll answer.

  #### Preview members

  - Added `getPreviewMembers()` on `AmityChannel`, enables access upto 4 members of converation and community channel.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>=v12 |
      | NPM | \>=v6 |

## UIKit Changelogs

### [Android](https://learn.social.plus/uikit/changelogs/android-uikit-changelog)

> On this page, you will find an overview of all relevant changes to the social.plus UIKit

## 🚀 New Features

  #### Discovery Widget

  Added `AmityDiscoveryWidgetComponent`, an embeddable, read-only carousel of the posts selected for a topic configured in the Console. Place it on a page or screen you own, outside the social feed. See [Discovery Widget](/uikit/components/social/discovery-widget).

  - **Parameters:** `topicId` (required), `showHeader` (default `true`), `minVisibilityThreshold` (default `3`; values below 1 are treated as 1), and `onCardClick`.
  - **Platform parameters:** `modifier` and `pageScope`.
  - **Content:** text, image, video, clip, and poll posts. Livestream and room posts are not shown.
  - **Visibility:** the widget renders nothing, and takes no space, when fewer supported posts than `minVisibilityThreshold` are available or the request fails.
  - **Layout:** adapts to the available width, from a compact swipeable strip to an expanded carousel.
  - **Card taps:** there is no default destination. Handle a tap with `onCardClick`, or override `AmityDiscoveryWidgetComponentBehavior.goToDestination` for app-wide handling. `onCardClick` takes precedence.
  - **Customization:** component IDs `discovery_widget_component` and `discovery_widget_post_card_component`.

  #### Pinned Messages in Livestream Chat

  Hosts, co-hosts, moderators, and anyone with the `PIN_MESSAGE` permission can pin a message from the livestream chat message ⋮ menu. The pinned message shows as a banner above the chat for every viewer, and a long message expands on tap. See [Pinned Messages](/uikit/components/social/livestream#pinned-messages).

  - **Unpin:** from the banner or from the message menu.
  - **Permission changes:** the pin controls appear or disappear as soon as a user's permission changes mid-stream.
  - **Customization:** `*/livestream_chat_feed/pinned_message_banner`, `*/livestream_chat_feed/pin_message_button`, and `*/livestream_chat_feed/unpin_message_button`.

  ## ✨ Improvements

  - Moderation controls are now gated on the permission each action requires instead of on the user's role name, so a custom role with the right permission gets the same controls as a built-in moderator. This covers deleting a message or comment, muting, banning, editing channel or community settings, promoting and demoting members, and editing an event.
  - The chat media viewer can now save videos, not just images. Downloads use the file's direct download endpoint instead of the transcoded stream, and the save survives dismissing the viewer mid-transfer.
  - Upgraded the social.plus SDK dependency to 7.27.1.

  ## 🐞 Bug Fixes

  - Fixed tapping an @mention in a chat message doing nothing. Mentions now route through `AmityMessageBubbleBehavior.onMentionUserTap`, including on the expanded "See more" message page.
  - Fixed the conversation header opening a blank full-screen avatar viewer for a peer with no avatar photo; the header's avatar tap is now also customizable, through `AmityChatPageBehavior.onAvatarTap`.
  - Fixed the live chat message list and pinned message banner staying on screen over the keyboard instead of hiding while the user types.
  - Fixed a terminated live stream sometimes leaving the host without a "stream terminated" alert before landing on the post.
  - Reverted the 4.26.0 change that restricted chat mention search to display-name matches; results can again include profile-handle and user-ID matches.
  - Fixed the group chat name field, and the edit-profile name field, accepting line breaks.
  - Fixed post text being truncated with "See more" even when it fully fit the card.
  - Fixed the poll, livestream, and clip options in the create-post menu, including on the event detail page, ignoring the `excludes` configuration.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.27.1 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Picture-in-Picture

  Added Picture-in-Picture for live and recorded livestream playback, so the stream keeps playing in a floating window when the viewer backgrounds the app or navigates elsewhere.

  #### Media Carousel

  Posts with two or more images or videos now render as a swipeable media carousel, in both the feed and the composer preview.

  #### Livestream Viewer Count

  The livestream viewer count is now shown based on your network configuration.

  #### Customizable Chat Taps

  Chat mention taps and avatar taps are now reachable through behavior overrides, so you can route them to your own screens.

  #### Pinned & Featured Post Badges

  Pinned and featured posts now render a read-only badge in the feed. Pinning and featuring are managed in the Console; UIKit displays the state.

  ## ✨ Improvements

  - Adopted the SDK's new `searchBy` capability for more accurate user search — results now match display names, so user-ID-only matches no longer appear. The same applies to @mention search in chat, posts, and comments.
  - Upgraded the social.plus SDK dependency to 7.26.0.

  ## 🐞 Bug Fixes

  - Fixed the media carousel resetting to the first frame on a feed reload and keeping its state consistent.
  - Refined the product tag badge (anchored it to the media, and fixed its glyph and empty variant).
  - Retry a failed media upload on tap and on reconnect.
  - Added playback time and a playable source to the composer video player.
  - Restored the live chat height on the room host page.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.26.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Customizable Chat Taps

  Chat mention taps and avatar taps are now reachable through behavior overrides, so you can route them to your own screens. Backported to the 4.25.x line.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.25.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency to 7.25.0.
  - The community Notifications setting is now hidden when notifications aren't available for the community, matching iOS.

  ## 🐞 Bug Fixes

  - Promote/demote is now gated on the `EDIT_COMMUNITY_USER` permission.
  - Channel mute and ban now respect the permissions the channel role actually grants.
  - Open the clip viewer directly from the For You feed.
  - Hide "Post event to feed" from non-members.
  - Added a Cancel button to the content-review notice.
  - Removed the underline on the inline "see more".
  - Fixed the default community thumbnail being tinted with the primary color.
  - Fixed a crash when opening a community that has pinned posts.
  - Sentence-cased the Explore Community button.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.25.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## ✨ Improvements

  - The SDK version, UIKit version, and commit hash are now logged on `setup()` for easier diagnostics.

  ## 🐞 Bug Fixes

  - Group (channel) member actions are now each gated on their own permission instead of a single shared moderator check.
  - Changed the add-member permission to `ADD_CHANNEL_USER`.
  - Fixed tapping Explore to scroll to the Communities section.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.4 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Event Posts

  Added event posts — share an event to the community feed, where it renders as an event post card that opens the event on tap.

  ## 🐞 Bug Fixes

  - Fixed the livestream reaction bar translucency not painting.
  - Show the full bio in the About field, matching iOS.
  - Fixed the story order on the community profile page.
  - Fixed spacing and icon color on the clip and story comment sheets.
  - Titled the upcoming events page "Upcoming events".
  - Fixed the clip like count being read from the wrong post.
  - Leave the community profile automatically when its community is closed.
  - Keep cached messages on a refresh error, matching iOS.
  - Fixed the official badge on the livestream and story view pages.
  - Gave each feed's pull-to-refresh indicator its own state.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.4 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Fixed poll votes not registering when made from the radio button or checkbox.
  - Standardized disabled action buttons to use the primary color at 30% opacity.
  - Adjusted the unread notification row to the primary color at 20% opacity.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.3 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Post Composer Placeholder & Reaction Styling

  Added placeholder text to the post composer and configurable reaction text color.

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency to 7.24.2.
  - Moved chat unread tracking to the membership-based pipeline.
  - Addressed Google Play unsafe-API / Device & Network Abuse policy violations.

  ## 🐞 Bug Fixes

  - Fixed livestream chat actions sending the wrong user id.
  - Fixed the collapsed community header blur across API levels.
  - Fixed the "Happening Now" event cover being squeezed.
  - Fixed the story header layout for long advertiser names.
  - Fixed the story viewer badge, view count, and audio scrim.
  - Fixed the story share-to title, photo/video switch button, and photo-preview close button.
  - Fixed the livestream thumbnail button fill.
  - Gated the add-member button on the `ADD_COMMUNITY_USER` permission.
  - Resolved custom user avatars (`avatarCustomUrl`) on the remaining chat pages.
  - Fixed the "Copy profile link" and "Share to" actions not showing reliably.
  - Fixed search keyword highlighting to exclude the surrounding spaces.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.2 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## ✨ Improvements

  - Prevented notification tray unread-indicator sync timing racing condition against actual TTL.

  ## 🐞 Bug Fixes

  - Fixed the community menu not showing to joined members on the expanded community header.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Chat Design Refresh

  Rolled out the new chat design system across chat atoms, pages, and elements, with updated colors and components.

  #### Group Message Moderation

  Group moderators can now delete other members' messages.

  #### Exclude Own Events

  The Events explore feed now excludes the current user's own events.

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency to 7.24.0.

  ## 🐞 Bug Fixes

  - Fixed the timestamp display in 24-hour format.
  - Fixed the chat home back-button position, moderator badge background, and missing avatars on the chat list.
  - Fixed the back button on the social home page.
  - Fixed the chat video player UI.
  - Fixed the chat list shimmer and shimmer color on the archive page.
  - Disabled tapping a null avatar and showed the sender name on deleted message bubbles.
  - Prevented the media viewer from opening when a scroll starts on an image or video message.
  - Fixed the rejected-send toast copy and icon.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.24.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Live Player Controls

  Added tap-to-reveal player controls, a live pause state.

  ## 🐞 Bug Fixes

  - Fixed co-host rejoin connection and stale LiveKit state on reconnect.
  - Fixed the default reaction and a crash on livestream events.
  - Fixed product-tagging UI issues and showed staged products on the create-room page opened from an event.
  - Fixed the live player recovering from a black screen after returning from the background.
  - Fixed the default avatar preview for users with no avatar.
  - Fixed incorrect fallback display name appearing on group chats.
  - Fixed an "unarchived" error toast shown on a successful unarchive.
  - Added an optional back slot to the chat home header, removed the community ranking number, and aligned the search back icon.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.23.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Fixed users being unable to post a video.
  - Fixed community moderator status not updating after promote/demote.
  - Fixed the edit-profile save button being overlapped by the system navigation bar.
  - Fixed the draft clip page being overlapped by the status bar.
  - Fixed the wrong image count on the image viewer.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.23.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### For You Feed

  Added the personalized **For You** feed surface, backed by the SDK's For You feed APIs.

  ## ✨ Improvements

  - Read-only livestreams now show a read-only message to visitors and non-members.
  - Post link previews now use server-provided metadata instead of client-side HTML scraping.

  ## 🐞 Bug Fixes

  - Fixed the comment compose bar save button color.
  - Fixed the product tag badge color.
  - Fixed co-host name display and the co-host actions sheet on name tap.
  - Fixed the community profile flashing during state changes (such as accepting an invitation).
  - Fixed the clip bottom sheet background and clip caption placeholder.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.23.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Custom Avatar URL Support

  Added support for `avatarCustomUrl`, allowing avatars to be loaded from a custom image URL instead of an uploaded social.plus avatar.

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency to 7.22.1, which recovers from a broken `EkoDatabase` v13 migration that could crash the app on launch.

  ## 🐞 Bug Fixes

  - Fixed UI configuration not being applied correctly to clips and events.
  - Fixed the create event button being shown to non-members of a community.
  - Fixed text and color theming across multiple screens in dark mode.
  - Fixed dialog theme and radio button styling.
  - Fixed empty-feed color and several alignment issues.
  - Fixed community members not refreshing after adding or removing a member.
  - Fixed a race condition when applying the divider theme.
  - Fixed a parent modifier being incorrectly inherited by all child elements.
  - Fixed the media bottom sheet height during post creation and excessive bottom padding in the video player.
  - Fixed the create-community icon color and hint text.
  - Fixed clip page theming and the create-clip button position.
  - Fixed a crash caused by a negative layout height in the reply message bubble.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.22.1 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Visitor Usage Limit Page

  Added `AmityVisitorUsageLimitPage`, a full-screen error shown when a visitor exceeds their daily read quota. Two new `AmityGlobalBehavior` overrides let you customise the experience:

  - `handleVisitorUsageLimitReached()` — replace the default full-page error with your own UI
  - `handleVisitorUsageLimitSignIn()` — replace the default sign-in toast with navigation to your own sign-in screen

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency to 7.22.1, which recovers from a broken `EkoDatabase` v13 migration that could crash the app on launch.

  ## 🐞 Bug Fixes

  - Fixed Level 1 comment not expanding when tapped.
  - Fixed missing unavailable-page UI when a livestream post is deleted or null.
  - Fixed missing string resource `amity_social_empty_state_empty_feed_no_posts`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.22.1 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Localization Support

  All UI strings are now externalised into string resource files, enabling custom translations and runtime language switching. Developers can add any language by providing translated string resource files without modifying application code. See the [Localization guide](/uikit/customization/localization) for setup instructions and platform-specific details.

  ## 🐞 Bug Fixes

  - Fixed RSVP'd users missing the menu button to access add-to-calendar action.
  - Fixed L2 comments not expanding directly when clicking "view replies" on L1 comments.
  - Fixed event date format display issues.
  - Fixed save/cancel edited comment behavior.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.21.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Fixed the in-app WebView proceeding past SSL certificate errors; invalid or untrusted certificates are now blocked instead of being loaded.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.21.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## ✨ Improvements

  - Upgraded social.plus SDK dependency to 7.21.0.
  - Removed legacy `READ_EXTERNAL_STORAGE` and `WRITE_EXTERNAL_STORAGE` permission gates from post creation, livestream, clip, and chat audio workflows for Android 13\+ Google Play compliance.

  ## 🐞 Bug Fixes

  - Fixed `CAMERA` permission check in `AmityNoPermissionPage` which was incorrectly referencing the removed `READ_EXTERNAL_STORAGE` permission.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.21.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Added `elementId` to user profile UI to support hiding via `config.json`.
  - Fixed missing community object for community context.
  - Fixed options menu visibility on user video feeds.
  - Fixed cursor issue on post composer.
  - Fixed post item design on feed.
  - Fixed edit video post issues.
  - Fixed edit image post page failing to load images.
  - Fixed touch area for image poll post item.
  - Migrated Compose BOM to version 2025.11.01.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.3 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2025.11.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Bluetooth Remote & Hardware Key Support for Livestream Start

  Pressing a paired Bluetooth remote shutter or the device's hardware volume key now starts a livestream, consistent with how these controls trigger the camera shutter in the native camera app.

  #### Profile Moderation Notification

  Users are now notified when their profile has been moderated (reset by the system).

  ## 🐞 Bug Fixes

  - Fixed incorrect default avatar placeholder size.
  - Fixed live ring not appearing.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 36 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.3 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2024.12.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Product Tag Click Handlers in Global Behavior

  Add `onPostProductTagClick` and `onLivestreamProductTagClick` callbacks in `AmityGlobalBehavior`, enabling custom handling of product tag interactions in posts and livestreams.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2024.12.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Multi-Level Reply Rendering

  Add multi-level reply rendering with optimistic reply support.

  #### Expand Replies with Load More

  Add expand replies with load more support.

  #### URL/Hyperlink Text in Comments

  Add URL/hyperlink text support in comments.

  #### Portrait Livestream Thumbnail Placeholder

  Add portrait livestream thumbnail placeholder.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.18.0 |
      | Android Paging Data Library | 3.4.2 |
      | Camera2 | 1.5.1 |
      | Coil | 3.0.0 |
      | Compose BOM | 2024.12.01 |
      | Compose Paging Data | 3.4.2 |
      | Glide | 4.12.0 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.7.0 |
      | Kotlin-std-lib | 2.2.0 |
      | Media 3 | 1.1.0 |
      | OKHTTP3 | 4.11.0 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.8.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Product Tagging in Posts

  Support product tagging in post composer — tag products via `@` text mention or per-media tag button with up to 20 products per post. Tagged products display as a list below post content.

  #### Livestream Product Tagging

  Support product management in livestreams — hosts and co-hosts can tag, pin, and remove products during broadcasts. Viewers browse tagged products via a scrollable overlay with real-time pinned product display.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Fixed touch area on image poll option

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Livestream analytics

  Viewers watching sessions are captured automatically on UIKit

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Event Scheduling

  Introduce Event scheduling with functionalities such as RSVP, reminders, discussion, and livestreaming

  #### Co-Streaming

  Introduce an ability to invite a viewer to co-stream a livestream session for livestram in communities

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Applied defensive handling of config parsing

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Post structure compatibility

  - Ensure UIKit only query for posts that can be rendered.

  ## 🚨 Compatibility Changes

  #### Support 16 KB page sizes

  - Kotlin version upgrade to 2.2.0
  - Bumped minSDKVersion to 24

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 24 |
      | targetSDKVersion | 35 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.9.0 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 2.2.0 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Public Access

  - Support visitor access.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.10.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.8.10 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.22 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🐞 Bug Fixes

  - Incorrect video rendering on clip feed

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.9.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.8.10 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.22 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Image Poll Post

  - Poll post now support having images as options.
  - Add an ability update poll answer.

  #### Post title

  - Post can now be created with an optinal title.

  #### Hashtag

  - Add hashtag support on Post.
  - Enable Post search by hashtag.

  #### Reaction Options

  - Add Multiple reaction options support.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.9.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.8.10 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.22 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

  ## 🚀 New Features

  #### Livestream chat & reactions

  - Introduce an ability to chat in a community's livestream.
  - Introduce an ability to send reaction in a community's livestream.

  #### Clip post

  - Introduce an ability create and view a clip post (vertically scrolling video).

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | minSDKVersion | 21 |
      | targetSDKVersion | 34 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.6.0 |
      | Android Paging Data Library | 3.2.1 |
      | Camera2 | 1.2.2 |
      | Compose BOM | 2024.12.01 |
      | Gson | 2.8.10 |
      | HiveMQ mqtt client | 1.3.1 |
      | Kotlin-coroutines | 1.6.4 |
      | Kotlin-std-lib | 1.8.22 |
      | Media3 | 1.1.0 |
      | OKHTTP3 | 4.9.2 |
      | Retrofit2 | 2.9.0 |
      | Room | 2.5.1 |
      | RxJava3 | 3.1.5 |

---

### [Flutter](https://learn.social.plus/uikit/changelogs/flutter-uikit-changelog)

> On this page, you will find an overview of all relevant changes to the social.plus UIKit

## 🚀 New Features

  #### Semantic Color Tokens and Dark Theme for Chat

  The Flutter UIKit now resolves Chat colors through the same semantic color tokens as the Android UIKit. Set them per mode under `theme.light` and `theme.dark` in `config.json`, and scope them with the `page_id/component_id/element_id` cascade. See [Component Styling](/uikit/customization/component-styling#supported-theme-tokens).

  - Chat list, chat room, and chat search follow the token set in both light and dark themes.
  - Social features are unchanged and keep resolving through the existing core colors.

  ## 🐞 Bug Fixes

  - Chat list: colors, the create-chat menu, the new group page, member permissions, profile pictures, the no-results icon, the group profile, the deleted-user row, and toasts now match the design in both themes.
  - Chat room: reaction colors now mark your own reaction; the iOS keyboard, action sheet, and error alert follow the UIKit theme; the mention list and `@All` row, failed-message badge, compose box, and report sheets match the design; the Report → Others sheet no longer shows an error screen.
  - Chat room loading: the reaction sheet no longer loads forever, and the link preview and message skeletons match the design.
  - Chat search: only the matched text is highlighted, and the search bar opens a dark keyboard in dark mode.
  - The media viewer close button and the unreport icon render without extra backgrounds.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.44.0  |


  ## 🐞 Bug Fixes

  - Fixed the community profile page flashing due to two scroll listeners disagreeing.
  - Hide the image count when viewing a single image.
  - Fixed the follow-error alert rendering as a stuck grey page.
  - Only show the pending banner for posts the viewer can see.
  - Story: keep the community story ring after viewing, resolve the story-create setting reliably and gate community create affordances on it, and open on the first unseen segment.
  - Search: drop superseded results, stop a second search hanging, and correct keyword highlighting.
  - Post: fixed a header crash on a user-targeted post; members can now interact from search (with a sign-in toast for non-members).
  - Mounted the toast host in the base pages so every page can show toasts.
  - Community: show a discard dialog instead of a grey screen on back.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.44.0  |


  ## 🚀 New Features

  #### Runtime Theme Switching

  Added `setPreferredTheme`, a public API to switch the UIKit theme (light / dark / system default) at runtime. See [Set Preferred Theme](/uikit/customization/set-preferred-theme).

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.7  |


  ## ✨ Improvements

  - Switched chat media selection to the native Android Photo Picker and removed the `wechat_assets_picker` dependency.

  ## 🐞 Bug Fixes

  - Fixed the 1:1 chat header not resolving from cache (now retries).
  - Fixed the first message not appearing in a brand-new direct chat.
  - Fixed the chat loading toast leaking across screens.
  - Fixed member lookup and message-listener attachment during chat initialization.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.7  |


  ## 🚀 New Features

  #### Chat Media Picker Improvements
  Replaced the previous media picker with `AssetPicker` for a more reliable experience, added `mediaAttachmentLimit` parameter to `AmityMessageComposer`, and improved picker theming with UIKit primary color support.

  ## 🐞 Bug Fixes
  - Fixed post creation button visibility — now correctly hidden when only admins can create posts and the current user is not a moderator.
  - Fixed pending post banner not appearing after creating a post in a community.
  - Fixed link preview image not stretching to full width.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed photo picker launching failure on Android 14+ when limited media access is granted.
  - Fixed keyboard dismiss and flickering issue when a message is sent in chat.
  - Fixed moderator unable to delete member's post in a community.
  - Improved media permission handling on Android 14+ to correctly detect limited access and use Android Photo Picker when appropriate.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed video thumbnail not appearing immediately after creating a video post.
  - Fixed my communities display issue.
  - Fixed success toast not showing when deleting a post in post detail page.
  - Fixed toast not showing when post is created with blocked words or URLs.
  - Upgraded `chewie` video player package from 1.3.4 to 1.13.0.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed camera permission handling in chat message camera screen — now properly reinitializes camera on app resume after settings grant.
  - Fixed microphone permission denial handling in message camera screen.
  - Fixed permission dialog loop by ignoring inactive lifecycle state during permission requests.
  - Added `CAMERA` and `RECORD_AUDIO` permissions to Android manifest.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed scrolling issue when entering chat page.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed keyboard focusing behaviour on chat

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed incorrect Dark theme color on alert dialog

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## ✨ Improvements
  - Upgrade thumbnail generation library

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed LiveCollection update on channel creation


      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed local validation for poll duration.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed message search not working for some users.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes
  - Fixed local validation for poll duration.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🚀 New Features
  #### Chat customization
  - Introduced feature toggles for user actions.
  - Introduced overridable user avatar tap event.

  ## 🐞 Bug Fixes
  - Fixed the inability to create image message from gallery selection.
  - Fixed missing localization keys on chat module.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🚀 New Features
  #### Support 16 KB page sizes
  - Bumped Flutter version to `3.35.6`.

  ## 🐞 Bug Fixes
  - Fixed incorrect camera rotation on some Android devices.
  - Fixed disappearing text when mention suggestions is dismissed.

      | Config         | Version |
      | :------------- | :------ |
      | Flutter        | 3.35.6  |


  ## 🐞 Bug Fixes

  #### HEIF Image Support

  - Introduce automatic image conversion before actual image upload for post creation.

  #### Image Viewer

  - Correct image viewport to display full-screen behind image counter.

  ## 🐞 Bug Fixes

  #### Story

  - Improve story feature stability.

  ## 🚀 New Features

  #### Chat Search

  - Support channel and message search.

  #### Message features

  - Support Link preview and User mention on message.

  ## 🚀 New Features

  #### Chat

  - Introduce Community and Conversation chat.

---

### [iOS](https://learn.social.plus/uikit/changelogs/ios-uikit-changelog)

> On this page, you will find an overview of all relevant changes to the social.plus UIKit

**Xcode forward compatibility restored in UIKit 4.19.0**

  The Xcode 26 compatibility issue caused by **RealmSwift** binaries has been fully resolved in **UIKit 4.19.0**. The UIKit now integrates with **AmitySDK v8.0.0**, which has migrated its cache layer from Realm to Core Data. Realm and RealmSwift are no longer required, and Xcode forward compatibility is fully restored. We recommend upgrading to 4.19.0 or later to remove any Xcode version constraints from your project.

  See the [iOS SDK v8 Migration Guide](/social-plus-sdk/changelogs/ios-sdk-v8-migration-guide) for installation changes, including UIKit-specific steps.

  ## 🚀 New Features

  #### Discovery Widget

  Added `AmityDiscoveryWidgetComponent`, an embeddable, read-only carousel of the posts selected for a topic configured in the Console. Place it on a page or screen you own, outside the social feed. See [Discovery Widget](/uikit/components/social/discovery-widget).

  - **Parameters:** `topicId` (required), `showHeader` (default `true`), `minVisibilityThreshold` (default `3`; values below 1 are treated as 1), and `onCardClick`.
  - **Platform parameters:** `pageId`.
  - **Content:** text, image, video, clip, and poll posts. Livestream and room posts are not shown.
  - **Visibility:** the widget renders nothing, and takes no space, when fewer supported posts than `minVisibilityThreshold` are available or the request fails.
  - **Layout:** adapts to the available width, from a compact swipeable strip to an expanded carousel.
  - **Card taps:** there is no default destination. Handle a tap with `onCardClick`, or override `AmityDiscoveryWidgetComponentBehavior.goToDestination` for app-wide handling. `onCardClick` takes precedence.
  - **Customization:** component IDs `discovery_widget_component` and `discovery_widget_post_card_component`.
  - **Host container:** give the widget wrap-content or a minimum height, and do not place it inside a horizontally scrolling parent.

  #### Pinned Messages in Livestream Chat

  Hosts, co-hosts, moderators, and anyone with the `PIN_MESSAGE` permission can pin a message from the livestream chat message ⋮ menu. The pinned message shows as a banner above the chat for every viewer, and a long message expands on tap. See [Pinned Messages](/uikit/components/social/livestream#pinned-messages).

  - **Unpin:** from the banner or from the message menu.
  - **Permission changes:** the pin controls appear or disappear as soon as a user's permission changes mid-stream.
  - **Customization:** `*/livestream_chat_feed/pinned_message_banner`. The pin and unpin menu items are not customizable on iOS.

  ## ✨ Improvements

  - Moderation controls are now gated on the permission each action requires instead of on the user's role name, so a custom role with the right permission gets the same controls as a built-in moderator. This covers message delete, mute, group settings, member actions, banned members, mention-all, community settings and profile actions, pending-post review, post-menu actions, story management, and event edit, and the gates follow permission changes in real time.

  ## 🐞 Bug Fixes

  - Fixed video download and playback in chat using swapped URLs — downloading a video previously saved the streamed playback asset, and playback used the download asset.
  - Fixed the post, poll, and livestream options in an event's create-post menu ignoring the `excludes` configuration.
  - Fixed toast messages appearing in the wrong position on livestream, post detail, and story surfaces; toasts now sit above the bottom bar.
  - Fixed Picture-in-Picture starting automatically while a livestream chat sheet (message actions, moderation, share, or menu) was open.
  - Fixed the post-creation button state after removing a failed media attachment.
  - Fixed the media carousel not remembering its current index after a manual swipe.
  - Fixed the product tag icon missing in the post composer's media viewer.
  - Fixed empty-state rendering in the community add-member and invite-member pages.
  - Fixed the group name field not wrapping to a new line, and its placeholder rendering in the value text color instead of the placeholder color.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | AmitySDK | 8.8.0 |

  ## 🚀 New Features

  #### Picture-in-Picture

  Added Picture-in-Picture for live and recorded livestream playback, so the stream keeps playing in a floating window when the viewer backgrounds the app or navigates elsewhere.

  #### Media Carousel

  Posts with two or more images or videos now render as a swipeable media carousel, in both the feed and the composer preview.

  #### Livestream Viewer Count

  The livestream viewer count is now shown based on your network configuration.

  #### Customizable Chat Taps

  Chat mention taps and avatar taps are now reachable through behavior overrides, so you can route them to your own screens.

  ## ✨ Improvements

  - Adopted the SDK's new `searchBy` capability for more accurate user search — results now match display names, so user-ID-only matches no longer appear. The same applies to @mention search in posts and comments.

  ## 🐞 Bug Fixes

  - Fixed the media carousel index not resetting after a feed refresh.
  - Fixed channel avatar parsing on chat pages.
  - Prevented Picture-in-Picture from activating on the report-reason screen and while a bottom sheet is open on a livestream.
  - Chat links now follow the existing link-opening behavior.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | AmitySDK | 8.7.0 |

  ## 🚀 New Features

  #### Event Posts

  Added event posts — share an event to the community feed, where it renders as an event post card that opens the event on tap.

  ## 🐞 Bug Fixes

  - Fixed the notification unread red-dot issue.
  - Fixed the Explore Community button.
  - Excluded the product tag on event posts.
  - Fixed the avatar placeholder color and assorted color issues.
  - Fixed staging regressions.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.6.0 |

  ## 🐞 Bug Fixes

  - Fixed the Explore Community button to open the Communities / Explore tab.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.4 |

  ## 🐞 Bug Fixes

  - Fixed news-feed pull-to-refresh: no more empty-page/skeleton flash, the featured post no longer disappears mid-refresh, and live updates resume after a refresh error.
  - Fixed tapping a user avatar opening a blank screen.
  - Sorted the community list by display name.
  - Fixed permissions on the About tab.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.4 |

  ## 🐞 Bug Fixes

  - Fixed avatars and images hosted on external (non-Amity) CDNs failing to load — the image loader now retries once without the `Authorization` header when the host rejects the bearer token.
  - Fixed the selected tab color ignoring your configured primary color; tab bars now use the theme's primary color instead of the highlight color.
  - Fixed the notification tray item color and the disabled-button color in the post and comment composers.
  - Aligned assorted surfaces with the web UIKit for visual consistency.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.3 |

  ## 🐞 Bug Fixes

  - Fixed the notification tray showing the wrong user's avatar.
  - Resolved custom user avatars (`avatarCustomUrl`) on the remaining chat pages.
  - Removed the redundant overflow menu button on the group chat page.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.2 |

  ## ✨ Improvements

  - Prevented notification tray unread-indicator sync timing racing condition against actual TTL.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.1 |

  ## 🚀 New Features

  #### Chat Design Refresh

  Migrated the Chat UIKit to the new design system.

  #### Event Created Notification

  Added a "created event" item to the notification tray.

  ## 🐞 Bug Fixes

  - Fixed large image preview decoding.
  - Fixed avatar rendering on profiles.
  - Fixed tapping a comment on a clip not navigating to the post detail.
  - Fixed several chat regressions.
  - Increased the touch area of the chat back button and added a navigation handler.
  - Fixed push notification registration.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.5.0 |

  ## 🚀 New Features

  #### Live Player Controls

  Added tap-to-reveal player controls, a live pause state.

  ## 🐞 Bug Fixes

  - Fixed the chat back button not working when there was no navigation stack, and added an optional back button to the chat list.
  - Fixed a discussion livestream being published as an event's recorded stream.
  - Fixed the livestream not keeping its current state when switching between background and foreground.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.4.0 |

  ## 🚀 New Features

  #### For You Feed

  Added the personalized **For You** feed, gated by the network's For You feed configuration.

  #### Event Shareable Links

  Added shareable event links to the event detail experience.

  ## 🚨 Compatibility Changes

  - Removed the deprecated v3 modules.

  ## 🐞 Bug Fixes

  - Fixed clickable links not working on posts.
  - Fixed read-only livestreams for guests and non-members.
  - Fixed the toast type and icon.
  - Fixed a moderator being unable to delete an event.
  - Fixed co-host name display and layout.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.3.0 |

  ## 🚀 New Features

  - Support avatar rendering from custom avatar URL(`avatarCustomUrl`)

  ## 🐞 Bug Fixes

  - Fixed the poll "see results / see more options" label color and standardized the vote button styling on the poll post view.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.2.1 |

  ## 🐞 Bug Fixes

  - Fixed permission check before showing the add button on the community membership page.
  - Fixed members list not refreshing immediately after a member is added or removed.
  - Fixed follow button text on the user profile page.
  - Fixed clip action behavior callback not being triggered when tapping the clip feed.
  - Added element IDs for events and clips in the newsfeed, and for creation buttons on the community and user profile pages.

  ## 🚨 Compatibility Changes

  - Deprecated `AmityLivestreamBehavior`.
  - Deprecated `goToCreateCommunityPage(context:)` on `AmitySocialHomeTopNavigationComponentBehavior`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.2.1 |

  ## 🐞 Bug Fixes

  - Fixed permission check before showing the add button on the community membership page.
  - Fixed members list not refreshing immediately after a member is added or removed.
  - Fixed dark theme colors in the notification tray.
  - Fixed follow button text on the user profile page.
  - Fixed clip action behavior not being triggered when tapping the clip feed.
  - Added element IDs for events and clips in the newsfeed, and for creation buttons on the community and user profile pages.

  ## 🚨 Compatibility Changes

  - Deprecated `AmityLivestreamBehavior`.
  - Deprecated `goToCreateCommunityPage(context:)` on `AmitySocialHomeTopNavigationComponentBehavior`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.2.1 |

  ## 🚀 New Features

  #### Visitor Usage Limit Page

  Added `AmityVisitorUsageLimitPage` , a full-screen error shown when a visitor exceeds their daily read quota. Two new `AmityGlobalBehavior` overrides let you customise the experience:

  - `handleVisitorUsageLimitReached()` — replace the default full-page error with your own UI
  - `handleVisitorUsageLimitSignIn()` — replace the default sign-in toast with navigation to your own sign-in screen

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.2.0 |

  ## 🐞 Bug Fixes

  - Fixed analytic data sync issue in the underlying SDK.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.1.3 |

  ## 🐞 Bug Fixes

  - Fixed stale session data issue after secure logout in the underlying SDK.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.1.2 |

  ## 🚀 New Features

  #### Localization in Social Features

  All UI strings are now externalised into string resource files, enabling custom translations and runtime language switching. Developers can add any language by providing translated resource files without modifying application code. See the [Localization guide](/uikit/customization/localization) for setup instructions and platform-specific details.

  ## 🐞 Bug Fixes

  - Fixed post mentioned user issue.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0\+ |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.1.1 |

  ## 🚀 New Features

  #### Integrated with AmitySDK v8.1.0

  UIKit now integrates with **AmitySDK v8.1.0**.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.3 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.1.0 |

  ## 🚀 New Features

  #### Migrated to AmitySDK v8.0.0 — Realm Removed

  UIKit now integrates with **AmitySDK v8.0.0**. The Realm and RealmSwift dependency has been removed — `Realm.xcframework` and `RealmSwift.xcframework` are no longer installed through the `SharedFrameworks` Package.swift file. No public UIKit APIs have changed; only the installation steps differ.

  See the [iOS SDK v8 Migration Guide](/social-plus-sdk/changelogs/ios-sdk-v8-migration-guide) for updated installation instructions.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4.1\+ |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 8.0.0 |

  ## 🚀 New Features

  #### Bluetooth Remote & Hardware Key Support for Livestream Start

  Pressing a paired Bluetooth remote shutter or the device's hardware volume key now starts a livestream, consistent with how these controls trigger the camera shutter in the native camera app.

  ## 🐞 Bug Fixes

  - Fixed a crash in `AmityNewsfeedComponent`.

  #### Specific Xcode support

  26.4.1 =\> 4.18.3-xcode26.4.1 26.4 =\> 4.18.3-xcode26.4 26.3 =\> 4.18.3-xcode26.3

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4.1 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.1 |
      | Realm | 20.0.3 |
      | Realm Swift | 20.0.3 |

  ## 🚀 New Features

  #### Product Tag Click Handlers in Global Behavior

  Add `onPostProductTagClick(context:)` and `onLivestreamProductTagClick(context:)` callbacks in `AmityGlobalBehavior`, enabling custom handling of product tag interactions in posts and livestreams.

  #### External Bundle Icon Support in Config File

  Config file now supports loading icons from an external bundle, allowing greater flexibility for custom icon assets.

  #### Specific Xcode support

  26.4 =\> 4.18.1

  26.3 =\> 4.18.1-xcode26.3

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.0 |
      | Realm | 20.0.3 |
      | Realm Swift | 20.0.3 |

  ## 🚀 New Features

  #### Multi-Level Reply Rendering

  Add multi-level reply rendering with optimistic reply support.

  #### Expand Replies with Load More

  Add expand replies with load more support.

  #### URL/Hyperlink Text in Comments

  Add URL/hyperlink text support in comments.

  #### Portrait Livestream Thumbnail Placeholder

  Add portrait livestream thumbnail placeholder.

  #### Specific Xcode support

  26.4 =\> 4.18.0

  26.3 =\> 4.18.0-xcode26.3

  26.2 =\> 4.18.0-xcode26.2

  ## 🐞 Bug Fixes

  - Fixed various UI bugs.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.4 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.19.0 |
      | Realm | 20.0.3 |
      | Realm Swift | 20.0.3 |

  ## 🚀 New Features

  #### Product Tagging in Posts

  Support product tagging in post composer — tag products via `@` text mention or per-media tag button with up to 20 products per post. Tagged products display as a list below post content.

  #### Livestream Product Tagging

  Support product management in livestreams — hosts and co-hosts can tag, pin, and remove products during broadcasts. Viewers browse tagged products via a scrollable overlay with real-time pinned product display.

  #### Specific Xcode support

  26.3 =\> 4.17.0-beta05

  16.x =\> 4.17.0-beta05-xcode16.4

  26.2 =\> 4.17.0-beta05-xcode26.2

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.x - 26.3 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🐞 Bug Fixes

  - Fixed poll options failed to expand.

  #### Specific Xcode support

  26.3 =\> 4.16.6

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.x - 26.3 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚀 New Features

  #### Support External Config File

  - Introduced `AmityUIKit4Manager.setConfigFile(filePath: String)` to be able to load config file from application level.

  ## 🐞 Bug Fixes

  - Fixed incorrect camera exporsure on Story creation.

  #### Specific Xcode support

  26.2 =\> 4.17.0-beta03

  16.x =\> 4.17.0-beta03-xcode16.4

  26.1 =\> 4.17.0-beta03-xcode26.1

  26.3 =\> 4.17.0-beta03-xcode26.4

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.x - 26.3 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚀 New Features

  #### Livestream analytics

  Viewers watching sessions are captured automatically on UIKit

  #### Specific Xcode support

  26.2 =\> 4.17.0-beta02

  16.x =\> 4.17.0-beta02-xcode16.4

  26.1 =\> 4.17.0-beta02-xcode26.1

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.x - 26.3 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚀 New Features

  #### Event Scheduling

  Introduce Event scheduling with functionalities such as RSVP, reminders, discussion, and livestreaming

  #### Co-Streaming

  Introduce an ability to invite a viewer to co-stream a livestream session for livestram in communities

  #### Specific Xcode support

  26.1 =\> 4.17.0-beta01

  16.x =\> 4.17.0-beta01-xcode16.4

  26.2 =\> 4.17.0-beta01-xcode26.2

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.x - 26.2 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚨 Compatibility Changes

  #### Xcode 26.1 support

  - The binary is now built with Xcode 26.1, ensuring compatibility with Xcode 26.1 and later. The minimum toolchain version is now Xcode 26.1. Earlier Xcode versions are no longer supported.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.1 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.13.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚨 Compatibility Changes

  #### Xcode 26 support

  - The binary is now built with Xcode 26, ensuring compatibility with Xcode 26 and later. The minimum toolchain version is now Xcode 26. Earlier Xcode versions are no longer supported.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 26.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.12.0 |
      | Realm | 10.54.6 |
      | Realm Swift | 10.54.6 |

  ## 🚀 New Features

  #### Post structure compatibility

  - Ensure UIKit only query for posts that can be rendered.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.11.0 |
      | Realm | 10.54.5 |
      | Realm Swift | 10.54.5 |

  ## 🚀 New Features

  #### Public Access

  - Support visitor access.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.10.0 |
      | Realm | 10.49.3 |
      | Realm Swift | 10.49.3 |

  ## 🚀 New Features

  #### Image Poll Post

  - Poll post now support having images as options.
  - Add an ability update poll answer.

  #### Post title

  - Post can now be created with an optinal title.

  #### Hashtag

  - Add hashtag support on Post.
  - Enable Post search by hashtag.

  #### Reaction Options

  - Add Multiple reaction options support.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.10.0 |
      | Realm | 10.49.3 |
      | Realm Swift | 10.49.3 |

  ## 🚀 New Features

  #### Livestream chat & reactions

  - Introduce an ability to chat in a community's livestream.
  - Introduce an ability to send reaction in a community's livestream.

  #### Clip post

  - Introduce an ability create and view a clip post (vertically scrolling video).

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 14.0 |
      | Xcode | 16.0 |

      | Library | Version |
      | :-- | :-- |
      | Amity-Social-Cloud-SDK | 7.00.0 |
      | Realm | 10.49.3 |
      | Realm Swift | 10.49.3 |

---

### [React Native](https://learn.social.plus/uikit/changelogs/react-native-uikit-changelog)

> On this page, you will find an overview of all relevant changes to the social.plus UIKit

## 🚀 New Features

  #### Standalone Chat Pages

  All 16 chat pages are now exported from the package root under the same names as the Web UIKit, so you can render any one of them inside `AmityPageRenderer`. For example, render `<AmityChatPage channelId="..." />` to open a conversation straight from a push notification. Each page that takes input exports a `<PageName>Props` type, such as `AmityChatPageProps`. From a rendered page, users can still move on to the other chat pages. See [Chat Components](/uikit/components/chat/overview#quick-start-example).

  #### Localization API

  `AmityUiKitProvider` takes a `localization` prop (`localeBundle`, `overrides`, `localeMap`), the same shape as the Web UIKit. `useLocale` and `useString` are exported from the package root. When you pass a `localeMap`, the UIKit picks a bundle from the device language. Without one, chat stays in English as before. See [Localization](/uikit/customization/localization).

  ## ✨ Improvements

  - Removed the built-in Thai string bundle. English is the only built-in language, as on the other platforms. Add Thai or any other language with your own bundle through `localization`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 19 |
      | React Native | ≥ 0.82 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.1.20 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 36 |
      | buildToolsVersion | 36.0.0 |

  ## 🚀 New Features

  #### Chat UIKit

  The React Native UIKit now includes in-app messaging. Render the new `AmityUiKitChat` entry point inside `AmityUiKitProvider` to mount the chat experience. It needs no extra package. See [Add Chat](/uikit/getting-started/installation#add-chat).

  - **Chat list**: browse, search, and archive conversations, with unread and mention badges.
  - **One-to-one and group chats**: send text, images, and videos, reply to messages, mention members, and see link previews.
  - **Message actions**: react, copy, edit, delete (with confirmation), report, and save photos or videos to the gallery. Failed messages can be resent from the message bubble.
  - **Search**: find chats and messages from the chat list, and jump straight to a matching message.
  - **Group management**: create groups, edit the group name and avatar, add and remove members, and manage banned users.
  - **Moderation**: moderators can delete any message. Users can report, unreport, and block other users. Chats with blocked users are hidden from search.
  - **Notifications**: chat notification settings, plus a banner when push notifications have been disabled by an admin.
  - Brand and moderator badges are shown throughout chat.

  #### Chat Navigation Behaviors

  Handle avatar and @mention taps in your own app through `AmityChatPageBehavior` and `AmityMessageBubbleBehavior`. See [Message Bubble Behavior](/uikit/components/chat/conversation-chat#message-bubble-behavior).

  ## ✨ Improvements

  - Bottom sheets across the UIKit now open, resize, and drag more smoothly.
  - Chat strings ship in English. The package has no API to change them until 4.3.1 — see [Localization](/uikit/customization/localization).
  - Upgraded the social.plus SDK dependency (`@amityco/ts-sdk-react-native`) to `^7.28.0`.

  ## 🚨 Compatibility Changes

  - **iOS:** add `NSPhotoLibraryAddUsageDescription` to your app's `Info.plist` before upgrading. Saving a photo or video from chat asks iOS for permission to add to the photo library, and iOS terminates an app that asks without this key.
  - **Android:** declare `WRITE_EXTERNAL_STORAGE` with `android:maxSdkVersion="28"` in your app's `AndroidManifest.xml`. Android 9 and below need it to save to the gallery; without it, saving always fails with a permission error.
  - **New peer dependencies:** `react-native-reanimated` `~4.3.4`, `react-native-worklets` `~0.8.3`, and `@react-native-camera-roll/camera-roll` `^7.10.2`. Add `'react-native-worklets/plugin'` as the **last** plugin in your app's `babel.config.js`.
  - `@react-native-community/netinfo` must now be `>=11.5.0`. `react-native-netinfo` is no longer required.

  See [Installation](/uikit/getting-started/installation) for the full setup.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 19 |
      | React Native | ≥ 0.82 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.1.20 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 36 |
      | buildToolsVersion | 36.0.0 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk-react-native | ^7.28.0 |
      | react-native-reanimated | ~4.3.4 |
      | react-native-worklets | ~0.8.3 |
      | @react-native-camera-roll/camera-roll | ^7.10.2 |
      | @react-native-community/netinfo | ≥ 11.5.0 |

  ## 🚀 New Features

  #### Media Carousel

  Posts with two or more images or videos now render as a swipeable media carousel, in both the feed and the composer preview.

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency (`@amityco/ts-sdk-react-native`) to 7.27.0.

  ## 🐞 Bug Fixes

  - Media carousel: reset to the first frame on a feed reload and when the feed regains focus, and keep the index in range when frames are removed.
  - Post composer: fixed media upload failures, per-item gating and retry, stable media identity for de-duplication, and edit-mode media resolution.
  - Media viewer: carry the sound setting across carousel frames, and inset the header by the top safe area.
  - Stopped showing the default avatar as a video thumbnail.
  - Fixed the carousel play icon and the video frame ratio.
  - Gate pending-post accept/decline and the author banner on the community moderator role.
  - Reject an offline upload up front instead of leaving it pending.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | 19 |
      | React Native | 0.82.1 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk-react-native | 7.27.0 |

  ## 🚀 New Features

  #### Visitor Mode

  Added visitor mode with enhanced daily usage-limit handling, including a `VisitorUsageLimit` page exported from the public API. Non-members now see an engagement bar with gated like and comment actions that prompt a sign-in toast.

  #### Login Configuration

  Added support for applying login behavior from configuration.

  ## ✨ Improvements

  - Upgraded the social.plus SDK dependency (`@amityco/ts-sdk-react-native`) to 7.23.0.

  ## 🐞 Bug Fixes
  - Show action controls on story comments.
  - Fixed the tab navigation and divider showing when Explore is the only tab.
  - Fixed long user profile descriptions overflowing on iOS.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | 19 |
      | React Native | 0.82.1 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed image upload failing in the post composer.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | 19 |
      | React Native | 0.82.1 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🚀 New Features

  #### React Native UIKit v4.0.0 — General Availability

  The React Native UIKit v4 is now generally available, graduating from the release-candidate series to a stable release. This release ships the refreshed v4 component architecture, live streaming powered by LiveKit, deep linking and push notification support, notification settings, and user profile screens.

  #### Post Link Validation

  Added link validation in the post composer, preventing invalid URLs from being submitted.

  ## ✨ Improvements

  - Switched Android post video playback to HLS streaming for more reliable playback.
  - Added video compression for stories to reduce upload size.

  ## 🐞 Bug Fixes

  - Fixed an Android story crash caused by oversized camera capture, by capping the video capture resolution.
  - Fixed black story footer and draft background, and the incorrect delete (trash) icon color.
  - Fixed a duplicate live badge appearing on the Android livestream player.
  - Fixed Android poll duration not updating when tapped.
  - Fixed reply count not being pluralized in comment "view more" labels.
  - Fixed a nested "view replies" affordance incorrectly appearing in the reply list.
  - Fixed long brand user names overflowing their layout.
  - Fixed avatar tap not navigating to the user profile.
  - Fixed post menu share options being shown to non-members.
  - Fixed mentioning members of a private community.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | 19 |
      | React Native | 0.82.1 |
      | Node.js | ≥ 20 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed story ring incorrectly showing when the user has no active stories.
  - Fixed incorrect permission check blocking story creation.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed livestream player displaying in wrong aspect ratio.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed user search being case-sensitive by adding `matchType` set to `partial` for search queries.
  - Fixed community search crash caused by duplicate keys and undefined slice operation.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed page re-rendering issue during pagination on social home page.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed story comment behavior to align with community settings.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed custom avatar URL not displaying correctly for followings and followers.
  - Fixed performance issues on social home page.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed incorrect permission check on create Post button.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## Breaking Behaviour

  - User search result contains only displayname matches.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed Comment composer appears behind the keyboard.
  - Fixed Post header not fully visible when navigating to Post details

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🚀 New Features

  - Upgraded Livestream service

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed incorrect participant count when there is a single poll vote.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fixed nested navigation issue by upgrading navigation lib.
  - Fixed `absolute` import issue by migrating to `relative` import internally.

  ## 🚨 Compatibility Changes

  #### RN 0.8x Compatibility

  - Replaced `react-native-create-thumbnail` with `react-native-compressor` for local video thumbnail generation.
  - Removed unused`react-native-rsa-native` dependency.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🚀 New Features

  #### Community feature parity

  - Introduce key community features; Profile, Settings, Membership, Pending Posts, Featured/Pinned Posts.

  ## 🚨 Compatibility Changes

  #### Support 16 KB page sizes

  - Bumped React Native version to 0.77

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.77 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 2.0.21 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🚀 New Features

  - Support Redux store isolation, enables isolation of storage between UIKit and application.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 16 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.8.0 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.4 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 34 |
      | buildToolsVersion | 34.0.0 |

  ## 🚨  Dependency Changes

  #### React Native New Architecture

  - Bumped React Native version to `0.76.9`

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | React Native | ≥ 0.76 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.9.25 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 15.1 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 35 |
      | buildToolsVersion | 35.0.0 |

  ## 🐞 Bug Fixes

  - Fix global feed content loading.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.8.0 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.4 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 34 |
      | buildToolsVersion | 34.0.0 |

  ## 🚀 New Features

  #### Post Engagement

  - Introduce new post engagement component.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.8.0 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.4 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 34 |
      | buildToolsVersion | 34.0.0 |

  ## 🚀 New Features

  #### Story

  - Support rendering stories on newsfeed.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.8.0 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.4 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 34 |
      | buildToolsVersion | 34.0.0 |

  ## 🚀 New Features

  #### Poll post

  - Support poll post rendering and poll post creation.

  ## 🚨  Dependency Changes

  - Added new peer dependency: `@react-native-community/datetimepicker` (v7.1.0)

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | React | ≥ 18 |
      | Node.js | ≥ 18 |
      | NPM | ≥ 6 |
      | Yarn | ≥ 1.22.15 |
      | JDK | ≥ 17.0.10 |
      | Kotlin | 1.8.0 |

      | Config | Version |
      | :-- | :-- |
      | Minimum Target | 13.4 |

      | Config | Version |
      | :-- | :-- |
      | minSdkVersion | 24 |
      | compileSdkVersion | 34 |
      | buildToolsVersion | 34.0.0 |

---

### [Web (React)](https://learn.social.plus/uikit/changelogs/web-uikit-changelog)

> On this page, you will find an overview of all relevant changes to the social.plus UIKit

## 🚀 New Features

  #### Discovery Widget

  Added `AmityDiscoveryWidgetComponent`, an embeddable, read-only carousel of the posts selected for a topic configured in the Console. Place it on a page or screen you own, outside the social feed. See [Discovery Widget](/uikit/components/social/discovery-widget).

  - **Parameters:** `topicId` (required), `showHeader` (default `true`), `minVisibilityThreshold` (default `3`; values below 1 are treated as 1), and `onCardClick`.
  - **Platform parameters:** `pageId`.
  - **Content:** text, image, video, clip, and poll posts. Livestream and room posts are not shown.
  - **Visibility:** the widget renders nothing, and takes no space, when fewer supported posts than `minVisibilityThreshold` are available or the request fails.
  - **Layout:** adapts to the available width, from a compact swipeable strip to an expanded carousel.
  - **Card taps:** there is no default destination. Handle a tap with `onCardClick`, or override `AmityDiscoveryWidgetComponentBehavior.goToDestination` for app-wide handling. `onCardClick` takes precedence.
  - **Customization:** component IDs `discovery_widget_component` and `discovery_widget_post_card_component`.

  #### Pinned Messages in Livestream Chat

  Hosts, co-hosts, moderators, and anyone with the `PIN_MESSAGE` permission can pin a message from the livestream chat message ⋮ menu. The pinned message shows as a banner above the chat for every viewer, and a long message expands on tap. See [Pinned Messages](/uikit/components/social/livestream#pinned-messages).

  - **Unpin:** from the banner or from the message menu.
  - **Permission changes:** the pin controls appear or disappear as soon as a user's permission changes mid-stream.
  - **Customization:** `*/livestream_chat_feed/pinned_message_banner`, `*/livestream_chat_feed/pin_message_button`, and `*/livestream_chat_feed/unpin_message_button`.

  ## ✨ Improvements

  - The full-screen video and clip viewer now streams through the same adaptive HLS player used elsewhere in the UIKit, replacing its separate custom video implementation.
  - Upgraded `@amityco/ts-sdk` to 7.28.0.

  ## 🐞 Bug Fixes

  - Fixed a pending comment in a community that requires comment approval appearing as published before it was approved; the composer now shows an "awaiting review" notice instead.
  - Fixed tapping an @mention or an avatar in chat not opening the user's profile, including from the channel header.
  - Fixed the reply band not being clickable, the reply-quote width and header gap, the new-message pill, the reaction-list skeleton rows, the failed-message sheet icons, and long reaction-list names not truncating.
  - Fixed the chat group name wrapping instead of truncating with an ellipsis.
  - Fixed the community profile menu checking moderator membership instead of the `EDIT_COMMUNITY` permission. A custom role with that permission now gets the same options as a built-in moderator.
  - Fixed the public-community icon rendering filled instead of outlined.
  - Fixed a globally banned user not being removed from an active livestream session immediately.
  - Fixed missing customization exclude keys for the livestream/create-post button, the media feed tabs, and the user-profile create button.
  - Fixed chat media downloads saving the video file with an incorrect URL and extension.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.28.0 |

  ## 🚀 New Features

  #### Media Carousel

  Posts with two or more images or videos now render as a swipeable media carousel, in both the feed and the composer preview.

  ## ✨ Improvements

  - Adopted the SDK's new `searchBy` capability for more accurate user search — results now match display names, so user-ID-only matches no longer appear.

  ## 🐞 Bug Fixes

  - Gate moderation actions by permission.
  - Auto-retry a failed media upload.
  - Show the terminated and ended-livestream screens instead of a broken player.
  - Invite member: hide the default user list, and add a no-users-available state and a search placeholder.
  - Fixed the blocked-user header padding and size, the single-line group name, the comment placeholder, and the camera video-capture option.
  - Hide the product tag when product tags are disabled.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.27.0 |

  ## 🐞 Bug Fixes

  - Fixed the post title not rendering on the post-review page.
  - Restored the invite-co-host button style, and fixed the livestream moderator badge updating on role change.
  - Fixed the brand badge on pending posts and the invitation banner.
  - Show the review modal when editing an event post in an admin-review community; hide "Post event to feed" for non-community-members.
  - Fixed the host being unable to see their own event on the community event tab.
  - Fixed page headers and empty states for blocked users, pending invitations, and follow requests.
  - Fixed clip composer/see-more styling and the deleted-clip view on reaction.
  - Fixed the notification highlight color and reply-comment profile navigation.
  - Fixed post/poll placeholder copy and the story "shared" toast.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.26.0 |

  ## 🐞 Bug Fixes

  - Fixed member-management permissions.
  - Fixed a failed image poll.
  - Fixed the custom-role promote/demote option.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.25.0 |

  ## 🚀 New Features

  #### Group Message Moderation

  Moderators can now delete other members' messages.

  #### Exclude Own Events

  The Explore and "Happening Now" event surfaces now exclude the current user's own events.

  ## ✨ Improvements

  - Upgraded `@amityco/ts-sdk` to 7.25.0.
  - Added an archived-chat loading skeleton.

  ## 🐞 Bug Fixes

  - Fixed the co-host badge persisting on leave and missing after rejoin.
  - Fixed the report reason not supporting multiline input and the unreport (flag-slash) icon.
  - Fixed a muted co-host not being unmuted on accept.
  - Fixed the inline error shown for oversize uploads.
  - Fixed the fullscreen video player and the message menu position.
  - Hid the 1:1 notification setting.
  - Fixed the "see more" page title, toast copy, and RSVP reset.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.25.0 |

  ## 🚀 New Features

  #### Live Player Controls

  Added tap-to-reveal player controls, a live pause state.

  ## 🐞 Bug Fixes

  - Fixed read-only streamer behavior on livestreams.
  - Fixed the story default avatar not resolving.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.24.0 |

  ## 🚀 New Features

  #### For You Feed

  Added the personalized **For You** feed, gated by network-level configuration, with the option to default the social home to the For You feed.

  #### Shareable Event Links

  Added the ability to share event links, including a copy-link action in the event share menu.

  #### Color Token

  Upgraded color token placements to better fit dark theming colors

  ## 🐞 Bug Fixes

  - Fixed non-members receiving incorrect toast when reporting a post.
  - Fixed the clip comment list showing all comments instead of the relevant thread.
  - Fixed pending posts not being shown.
  - Fixed assorted icon and color issues, including the create-community camera icon, disabled vote button opacity, and empty-feed text.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

      | Library | Version |
      | :-- | :-- |
      | @amityco/ts-sdk | 7.23.0 |

  ## 🐞 Bug Fixes

  - Fixed embedded UIKit components (such as the comment tray) scrolling the host page to the top on mount. The popup scroll lock is now only applied and restored around an actual open → close cycle.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🐞 Bug Fixes

  - Fixed broadcaster portrait livestream not displaying in the correct orientation.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🐞 Bug Fixes

  - Fixed input focus being lost while typing in form fields.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Visitor Usage Limit Page

  Added `VisitorUsageLimitPage` , a full-screen error shown when a visitor exceeds their daily read quota. Two new `AmityGlobalBehavior` overrides let you customise the experience:

  - `handleVisitorUsageLimitReached()` — replace the default full-page error with your own UI
  - `handleVisitorUsageLimitSignIn()` — replace the default sign-in toast with navigation to your own sign-in screen

  ## 🐞 Bug Fixes

  - Fixed livestream chat not connecting to the correct community for event-linked livestreams.
  - Fixed localization not applied to the edit post form.
  - Fixed incorrect permission check causing unintended post action restrictions.
  - Fixed cohost invite handling when the referenced post is hidden.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🐞 Bug Fixes

  - Fixed mention item click not responding when selected from the suggestion list.
  - Fixed mention trigger input not activating the suggestion popover correctly.
  - Fixed missing `displayName` prop in user-facing components.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Social Localization

  All UI strings are now externalised into string resource files, enabling custom translations and runtime language switching. Developers can add any language by providing translated resource files without modifying application code. See the [Localization guide](/uikit/customization/localization) for setup instructions and platform-specific details.

  ## 🐞 Bug Fixes

  - Fixed create comment failing silently due to incorrect option handling.
  - Fixed deleted reply tag still appearing in comment threads.
  - Fixed missing auto link preview on posts.
  - Fixed visitor toast notification behavior.
  - Fixed clip menu click handling.

  ## ✨ Improvements

  - Upgraded `@amityco/ts-sdk` dependency to `>=7.21.0`.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  - Version 4.15 Stable release

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🐞 Bug Fixes

  - Fixed the livestream badge on the user profile feed overlapping the header when scrolling on mobile.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Product Tag Click Handlers in Global Behavior

  Add `onPostProductTagClick` and `onLivestreamProductTagClick` callbacks in `AmityGlobalBehavior`, enabling custom handling of product tag interactions in posts and livestreams.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Multi-Level Reply Rendering

  Add multi-level reply rendering with optimistic reply support.

  #### Expand Replies with Load More

  Add expand replies with load more support.

  #### URL/Hyperlink Text in Comments

  Add URL/hyperlink text support in comments.

  #### Portrait Livestream Thumbnail Placeholder

  Add portrait livestream thumbnail placeholder.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Product Tagging in Posts

  Support product tagging in post composer — tag products via `@` text mention or per-media tag button with up to 20 products per post. Tagged products display as a list below post content.

  #### Livestream Product Tagging

  Support product management in livestreams — hosts and co-hosts can tag, pin, and remove products during broadcasts. Viewers browse tagged products via a scrollable overlay with real-time pinned product display.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  - Fallback to `SocoalHomePage` when there's no page left in the stack.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🐞 Bug Fixes

  - Fixed channel creation modal crash

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Livestream Analytics

  Viewers watching sessions are captured automatically on UIKit

  ## 🐞 Bug Fixes

  - Fixed toast notification positioning
  - Fixed UI interaction issues (focus, z-index, navigation)
  - Fixed content and link handling

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Event Scheduling

  Introduce Event scheduling with functionalities such as RSVP, reminders, discussion, and livestreaming

  #### Co-Streaming

  Introduce an ability to invite a viewer to co-stream a livestream session for livestram in communities

  #### Livestream Creation

  Support Livestream creation in desktop mode

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Public Access

  - Support visitor and bot access.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Post structure compatibility

  - Ensure UIKit only query for posts that can be rendered.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Public Access

  - Support visitor and bot access.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Image Poll Post

  - Poll post now support having images as options.
  - Add an ability update poll answer.

  #### Post title

  - Post can now be created with an optinal title.

  #### Hashtag

  - Add hashtag support on Post.
  - Enable Post search by hashtag.

  #### Reaction Options

  - Add Multiple reaction options support.

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

  ## 🚀 New Features

  #### Livestream chat & reactions

  - Introduce an ability to chat in a community's livestream.
  - Introduce an ability to send reaction in a community's livestream.

  #### Clip post

  - Introduce an ability create and view a clip post (vertically scrolling video).

  ## 🧩 Compatibility

      | Config | Version |
      | :-- | :-- |
      | NodeJS | \>= v16 |
      | PNPM | \>= v8 |
      | React | \>= v18 |

## AI

### [AI at social.plus](https://learn.social.plus/ai/overview)

> Engagement infrastructure for the AI era — answers from your first-party data, docs your coding tools can read, and guardrails for AI agents building on social.plus.

social.plus is the engagement infrastructure behind consumer apps — and every interaction it powers generates [first-party data](/ai/first-party-data) and insight your business owns. AI turns both into leverage. Teams ask their own data questions in the AI apps they already use, and AI coding agents build on the platform with the same grounding a senior integrator would have.

## Three products

    Ask questions about your first-party data in plain language, from the AI apps your team already uses.
    Give your AI coding tool direct access to the social.plus docs while it helps you implement SDK features.
    Guardrails for AI coding agents building social.plus features — evaluate, build, and verify with confidence.

## Which one do you need?

| You want to… | Use |
|---|---|
| Answers from your first-party data, in plain language | [Agentry](/ai/agentry/overview) |
| SDK docs, inside your coding tools | [Documentation MCP Server](/ai/docs-mcp-server) |
| AI agents that build social.plus features — verified | [Vise](/ai/vise/overview) |

They compose: build with Vise, keep the docs server connected in every editor, and give marketing and community teams Agentry for the questions that used to become dashboard requests.

## Engagement, insight, intelligence

- **Your data answers back.** Agentry turns the first-party data your app already generates — posts, comments, reactions, users, communities — into a conversation. Read-only, scoped to your own network, authorized by your admins.
- **The docs meet your tools where they are.** The documentation MCP server is a public, no-auth endpoint any MCP-capable tool can read, so assistants cite canonical guidance instead of guessing.
- **Building is verifiable.** Vise gives coding agents the project knowledge and verification steps to implement features that pass review, not just compile.

Owned engagement compounds: the experiences you power create the data, the data powers the answers, and the answers sharpen what you build next. Start with [your first-party data](/ai/first-party-data) — what it is, and why it's yours.

---

### [Your first-party data](https://learn.social.plus/ai/first-party-data)

> Every interaction your app powers is data you own — the foundation everything in the AI tab builds on.

First-party data is the engagement your own app generates: every post, comment, and reaction happens on infrastructure you run, under your brand, with your users' consent to you — not to a platform in between. That makes it yours in the way that matters: you decide who can see it, question it, and build on it.

That's the difference between owning an audience and renting one. On social networks and ad platforms, your community's activity belongs to the platform — you see it through their windows, on their terms, and the signal you can take with you shrinks every year as third-party cookies and tracking identifiers disappear. Engagement that runs on social.plus works the other way around: the community lives in your app, so the data it generates accrues to you.

## What your app generates

Every social.plus feature produces first-party signal as a side effect of people using it:

| Interaction | The signal you own |
|---|---|
| Posts and stories | What your users create, where, and how often |
| Comments and replies | Where conversation actually happens |
| Reactions | What resonates, at the lightest level of effort |
| Community membership | Which spaces grow, which go quiet |
| Users and profiles | Who participates, and how participation spreads |
| Events and live streams | What people show up for |

None of this requires instrumentation or a tracking pixel — it's the product working. The moment your community is active, the data exists.

## You stay in control

Ownership means nothing without control, so every path to this data runs through you:

- **Access is granted, never assumed.** [Agentry](/ai/agentry/overview) connections exist only because an administrator issued a connect code or credential, each one is scoped to a single network, and any of them can be revoked without touching the rest — see [Manage access](/ai/agentry/manage-access).
- **Asking is read-only.** AI apps connected through Agentry can question your engagement data; nothing in that path writes, moderates, or administers anything.
- **The data is portable.** It's your data, so you can take it with you — raw, through APIs, not just through dashboards.

## Three ways to put it to work

    Agentry answers plain-language questions from your first-party data, in ChatGPT, Claude, or any AI app your team uses.
    Console analytics turn the same data into dashboards — engagement, growth, and community health at a glance.
    The first-party data export API delivers built-in reports of your most recent data and metrics, ready for your own warehouse or BI stack.

Owned engagement compounds: the experiences you power create the data, the data powers the answers, and the answers sharpen what you build next.

---

### [Agentry](https://learn.social.plus/ai/agentry/overview)

> Ask questions about your first-party data in plain language — in ChatGPT, Claude, and other AI apps.

Agentry is how brands use social.plus in the AI-native era. Every post, comment, and reaction your app generates is [first-party data](/ai/first-party-data) — a signal about what your users care about and how they behave. Agentry puts that data to work where your team already is: ask in plain English from ChatGPT, Claude, or any AI app, and get back a clear summary plus the underlying data, ready to tabulate, chart, or drill into with follow-up questions.

  <img src="/images/ai/agentry-demo.svg" alt="Agentry answering 'How did engagement change this month?' with a summary and weekly engagement chart" />

  Agentry is in **preview**. If the Agentry page in your Console says it isn't enabled, contact support to turn it on.

## What you can ask

Agentry reasons over your network's engagement activity — posts, comments, reactions, stories, events, users, and communities — as counts, trends, comparisons, cohorts, and rankings across roughly the last 90 days. If a question combines those ingredients — *what happened, measured how, over which period, compared to what* — Agentry can usually answer it.

Simple questions work — *how many users were active yesterday?* — and so do the analyses your team actually runs:

- **Campaign readouts** — *Did engagement lift after last week's launch?* See a campaign's impact the moment you ask.
- **Audience understanding** — *Which communities and member cohorts grew the most this month?* Know where growth comes from.
- **Content strategy** — *Which content formats drive the most engagement?* Double down on what works.
- **Community health** — *How is activity trending versus last month, and where is conversation concentrating?* Walk into the review with numbers in hand.
- **Trendspotting** — *Which communities saw the biggest spike in conversation this week?* Catch momentum while it's still building.
- **Projections** — *At the current pace, how many active users will we end the month with?* Simple forward reads from the trends in your data.

Answers arrive ready for your AI app to work with — it can chart the numbers, explain what they mean, and dig into the details when you ask a follow-up.

Out of scope, by design: activity older than the data window, anything outside your own network, and acting on your app — Agentry answers questions; it doesn't post, moderate, or administer.

## How it works

- **Read-only by design.** Agentry answers questions by reading your analytics data. It never posts, modifies, or deletes anything in your app.
- **Your data stays yours.** Each connection is scoped to your own network's data and authorized by your administrator from the Console. Admins see every connection and can remove any of them at any time.
- **Fresh, bounded data.** Activity data covers roughly the last 90 days and refreshes daily.
- **Self-contained questions.** Each question is answered on its own, so include the context that matters — time ranges, baselines, comparisons. AI apps handle this naturally when you ask follow-ups in the same conversation.

## Get started

    Link ChatGPT, Claude, Claude Code, Cursor, or any MCP-capable app to Agentry.
    Generate connect codes, issue credentials, and control who can ask — from the Console.

---

### [Connect your AI app](https://learn.social.plus/ai/agentry/connect)

> Link ChatGPT, Claude, Claude Code, Cursor, or any MCP-capable app to Agentry.

There are two ways to connect, matching the two sections of the Console's Agentry page:

- **Via AI app** — install Agentry from your AI app's own directory and authorize it with a **connect code**. No URLs or secrets to copy. Best for ChatGPT and Claude users.
- **Via MCP** — point an MCP client (Claude Code, Cursor, or any custom MCP-capable app) at the Agentry MCP server and authenticate with a **connector credential** (client ID + secret).

Either way, your administrator provides what you need from **Console → Settings → Agentry** — see [Manage access](/ai/agentry/manage-access).

## Via AI app

  <img src="/images/ai/agentry-connect-flow.svg" alt="Three steps: install social.plus Agentry from your AI app's directory, authorize with a connect code, then ask" />

        Ask your admin for a connect code, or generate one yourself in Console → Settings → Agentry (super admin). Codes are single-use and short-lived, so get one just before you connect.
        In Claude, open **Customize** in the sidebar and choose the **Connectors** tab. Select **+**, choose **Browse connectors**, and search for **social.plus Agentry** — or open the listing directly at [social.plus/agentry/claude](https://social.plus/agentry/claude).
        Choose **Connect**. A social.plus page asks for your connect code — paste it and approve access.
        Start a chat and ask about your data. Claude calls Agentry and answers from your first-party data.
        Ask your admin for a connect code, or generate one yourself in Console → Settings → Agentry (super admin).
        In ChatGPT, browse the app directory and search for **social.plus Agentry** — or open the listing directly at [social.plus/agentry/chatgpt](https://social.plus/agentry/chatgpt) — then choose **Install**.
        ChatGPT opens a social.plus page asking for your connect code — paste it and approve access.
        Ask about your data in any chat. ChatGPT calls Agentry and answers from your first-party data.

## Via MCP

Each guide uses the same **MCP server URL** (shown on the Console's Agentry page) plus a connector credential your admin creates there. The credential type must match your client — the create dialog offers **Claude (web connector)**, **Native / CLI**, and **Custom redirect URL**.

        In the Console, create a **Claude (web connector)** credential and copy its Client ID and Client Secret — the secret is shown only once.
        In Claude, open **Customize → Connectors** (Organization settings → Connectors on Team and Enterprise plans), select **+**, and choose **Add custom connector**.
        Paste the MCP server URL. Open **Advanced settings** and paste the Client ID and Client Secret.
        Choose **Add**, then **Connect**, and approve access.
        In the Console, create a **Native / CLI** credential and copy its Client ID and Client Secret.
        The Console's Claude Code tab shows the exact command with the MCP URL and your Client ID filled in. The bare `--client-secret` flag prompts for the secret (or reads `MCP_CLIENT_SECRET` from the environment).
        On first connect, approve access in the browser tab that opens.
        In the Console, create a **Native / CLI** credential and copy its Client ID and Client Secret.
        Add Agentry to your Cursor `mcp.json` using the snippet shown on the Console's Cursor tab, filling in the Client ID and Client Secret. Cursor also supports referencing environment variables with its `env:` prefix instead of pasting the secret.
        On first connect, approve access in the browser tab Cursor opens.
    Any MCP-capable app connects the same way: point it at the MCP server URL and authenticate with a connector credential. This is also the right path for **AI agents in agentic workflows** — the credential outlives any one session, so after a one-time authorization approval, an autonomous agent keeps its access through normal token refresh.

        For an app that runs its own OAuth callback, your admin should create the credential with a **Custom redirect URL**; local and CLI tools use a **Native / CLI** credential (loopback redirect).
        In your AI app, open its MCP or custom-connector settings, add a new server, and paste the MCP server URL.
        When prompted, authenticate with the Client ID and Client Secret and approve access. Your app then discovers Agentry's tools and can ask about your first-party data.

## Troubleshooting

- **The connect code is rejected.** Codes are single-use and expire — generate a fresh one and retry.
- **The app connected but answers stopped.** An admin may have removed the connection; reconnect with a new code, or a new sign-in for credential-based clients.
- **Wrong or empty answers about old activity.** Questions beyond the roughly 90-day data window can't be answered from Agentry's data.

---

### [Manage access](https://learn.social.plus/ai/agentry/manage-access)

> Control who can ask about your first-party data — connect codes, connector credentials, and connected apps in the Console.

Everything about Agentry access lives in **Console → Settings → Agentry**, available to super admins. The page has two sections matching the two ways apps connect:

- **Via AI app** — connect codes and the connected-apps list, for directory-installed apps like ChatGPT and Claude.
- **Via MCP** — connector credentials and connected clients, for MCP tools like Claude Code and Cursor.

  If the page says Agentry isn't enabled, contact support to turn it on.

## How access works

Agentry has **read-only** access to your network's data: the only thing any connection can do is ask questions of your first-party engagement data. Who gets to ask is entirely in your hands — every connection exists because a super admin issued a connect code or a credential, every connection is listed, and any of them can be removed at any time without affecting the others.

## Via AI app

### Connect codes

A connect code links one application sign-in to your network's data.

    Choose **Generate connect code**. Enter a **label** — who or what the code is for (for example, "Alice — marketing"). The label is required: it is copied onto the resulting connection and is the only thing that tells connections apart, because every user of the same AI app shares one app identity.
    Pick the scopes the code grants (for example, *Read your engagement data*). A code must grant at least one thing.
    The code is shown **once** — copy it immediately. Codes are single-use and expire (the exact expiry is shown when you generate one). If a code is lost or goes unused, generate another.

### Connected apps

The **Connected apps** table lists every application currently linked to your data — its label, the application, its verified origin, and when it connected.

- **Remove** signs that application out; it stops being able to answer questions within about 15 minutes. Every other connected app keeps working.
- A removed app can reconnect later with a new connect code.

## Via MCP

### Connector credentials

A connector credential is a Client ID + Client Secret an MCP client uses to sign in. When creating one, pick the client type that matches how the client handles OAuth:

| Client type | For | Redirect behavior |
|---|---|---|
| **Claude (web connector)** | Claude.ai custom connectors | Claude's hosted callback |
| **Native / CLI** | Claude Code, Cursor, other local tools | Loopback redirect (ephemeral local port) |
| **Custom redirect URL** | Apps running their own OAuth callback | Your URL — https, or http only for `127.0.0.1`, `localhost`, `[::1]`; no fragment or embedded credentials |

The client secret is shown **once** at creation — copy it then. Treat the pair like an API key: whoever holds it can connect as that credential.

- **Revoke credential** stops every connection using it, permanently. Use it to rotate a leaked secret or off-board a tool.

### Connected clients

The **Connected clients** table shows sessions currently signed in with your credentials. Removing one ends that session — within about 15 minutes — **without revoking the credential**, so anyone else using the same credential is unaffected, and the client can sign in again.

## Choosing between codes and credentials

| | Connect code | Connector credential |
|---|---|---|
| Best for | Directory apps (ChatGPT, Claude) and one-person grants | MCP dev tools, AI agents in agentic workflows, and long-lived integrations |
| Sharing | Never — single-use, one person, labeled | The pair can serve a tool's users, at the cost of coarser control |
| Removal | Per connection, others unaffected | Per session (keep credential) or per credential (cut everything on it) |

## Security notes

- Agentry connections can only **read your first-party engagement data** — there is no scope that writes, moderates, or administers anything.
- Access is network-scoped end to end: a connection to your network cannot see any other network's data.
- Removal takes effect within about 15 minutes of the change.

---

### [Documentation MCP Server](https://learn.social.plus/ai/docs-mcp-server)

> Connect AI coding tools to the social.plus documentation MCP server.

The social.plus documentation MCP server lets AI coding tools read the public social.plus documentation directly while they help you implement SDK features.

Use it when you want an assistant to answer implementation questions, find the right SDK guide, or cite canonical docs while working in your editor.

  MCP support varies by AI tool and version. If your tool does not support remote MCP servers yet, use the docs pages directly or connect through a tool-specific MCP configuration when available.

## MCP endpoint

```text
https://learn.social.plus/mcp
```

The public docs MCP server:

- uses the hosted social.plus documentation as its source of truth
- does not require authentication
- is intended for documentation lookup and guidance
- returns structured tool results to the connected AI assistant

  Step-by-step setup for Claude, VS Code, and Cursor.

## Typical workflow

    Add `https://learn.social.plus/mcp` to your AI tool's MCP settings.
    Ask about a specific SDK task, such as setting up authentication, creating posts, querying feeds, configuring notifications, or using Live Objects and Live Collections.
    The assistant can call the MCP server to search social.plus docs and read the relevant pages.
    Check that the assistant cites the correct docs and asks for missing project-specific inputs instead of inventing values.

## Example prompts

```text
How do I initialize the TypeScript SDK for the EU region?
```

```text
Show me the docs for creating a text post in a community.
```

```text
What should I check before implementing push notification registration?
```

```text
How should I clean up a Live Collection subscription in React?
```

## What this MCP server is for

The public docs MCP server is best for:

- finding canonical social.plus documentation pages
- answering SDK implementation questions with docs context
- helping AI tools avoid outdated or guessed API usage
- giving assistants a consistent source of truth across editors

It is not a replacement for your app's local validation, build, test, or security review process.

When an agent is **editing your app**, use [Vise](/ai/vise/overview): install it, add its skill to your agent, and it guides the coding loop and checks the generated integration before you call it done. For handoff and release review, it can also compare SDK assurance and verifiable Integration Passports without claiming human approval. Vise can run as a [local MCP server](/ai/vise/mcp-server).

## Related docs

    Install and initialize social.plus SDKs for your platform.
    Learn how user login, session renewal, and regional configuration work.
    Create, query, edit, and moderate social posts.
    Use realtime data patterns safely in your app lifecycle.

---

### [Installation](https://learn.social.plus/ai/docs-mcp-installation)

> Set up the social.plus documentation MCP server in Claude, VS Code, or Cursor.

Every tool connects to the same endpoint — no authentication required:

```text
https://learn.social.plus/mcp
```

## Connect your tool

    ### Claude.ai (web)

    Connect via the Connectors UI in Claude's settings — no config file needed.

        Go to [claude.ai](https://claude.ai) and click your avatar → **Settings**.
        In the left sidebar choose **Customize**, then click **Connectors**.
        Click **Add custom connector** and paste the MCP server URL:
```
https://learn.social.plus/mcp
```
        Save. Claude will confirm the connection.

      <img src="/images/ai/claude-web-add-connector.png" alt="Add custom connector dialog" />

    ### Claude Desktop (app)

    Edit the JSON config file to register the MCP server.

        **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

        **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

        Create the file if it doesn't exist yet.
```json
{
  "mcpServers": {
    "social-plus": {
      "url": "https://learn.social.plus/mcp",
      "transport": "sse"
    }
  }
}
```
        Quit and reopen the app. You should see **social-plus** listed under MCP servers in the toolbar.

      <img src="/images/ai/claude-desktop-mcp-connected.png" alt="Claude Desktop showing social-plus MCP connected" />
    Requires **VS Code 1.99+** with the **GitHub Copilot** extension.

        Press `⌘⇧P` (macOS) or `Ctrl+Shift+P` (Windows/Linux) and run **Preferences: Open User Settings (JSON)**.
        Paste the following at the top level of your `settings.json`:
```json
{
  "mcp": {
    "servers": {
      "social-plus": {
        "type": "sse",
        "url": "https://learn.social.plus/mcp"
      }
    }
  }
}
```
        Open Copilot Chat (`⌘I`), switch to **Agent** mode, and run `@social-plus` — the tool list should appear.

      <img src="/images/ai/vscode-mcp-connected.png" alt="VS Code Copilot Chat showing social-plus MCP tools" />
        Press `⌘,` (macOS) or `Ctrl+,` (Windows/Linux) to open Settings. Navigate to **Features → MCP**.
        Click **Add new MCP server**. Enter:
        - **Name:** `social-plus`
        - **Type:** `SSE`
        - **URL:** `https://learn.social.plus/mcp`

        Click **Save**.
        The server should show as **Enabled** in the MCP list. You can now reference it in Cursor's AI chat.

      <img src="/images/ai/cursor-mcp-enabled.png" alt="Cursor MCP settings showing social-plus enabled" />

    You can also edit `.cursor/mcp.json` directly in your project root:

```json
{
  "mcpServers": {
    "social-plus": {
      "url": "https://learn.social.plus/mcp",
      "transport": "sse"
    }
  }
}
```

---

### [Vise](https://learn.social.plus/ai/vise/overview)

> Give your AI coding agent a grounded, verifiable workflow for building social.plus features.

Vise helps AI coding agents integrate social.plus without guessing SDK APIs or stopping at code that merely looks finished. You ask for a feed, chat, communities, stories, or another product outcome; the agent plans, implements, checks, and explains the work.

After setup, you talk to your agent—not to Vise.

  <img src="/images/ai/vise-demo.svg" alt="Vise guiding a coding agent: plan from docs, checks for SDK usage, lifecycle, completeness and project validation, ending in an honest handoff" />

When you return to an existing project, `vise status . --format human` is the read-only front door. It routes the agent to one of three jobs—finish the build, assess a Day-2 change, or prepare release review—while keeping compliance, runtime proof, SDK assurance, organization policy, advisory review, Passport verification, and human approval as separate claims.

## Get started

  Vise requires Node.js 20 or newer.

```sh
npm install -g @amityco/social-plus-vise
```
```sh
vise install-skill --target claude     # Claude Code
vise install-skill --target cursor .   # Cursor
vise install-skill --target vscode .   # VS Code
vise install-skill --target copilot .  # GitHub Copilot
vise install-skill --target codex      # OpenAI Codex
```

    For another agent, use `vise print-skill` and paste the result into its instructions.
```text
Add a social feed to this app using social.plus.
```

    Your agent inspects the app and asks for decisions such as region, target screen, identity source, and feature scope before editing.

## What to expect

1. **A grounded plan.** The agent uses real social.plus documentation and SDK facts.
2. **Implementation with checks.** Vise checks SDK usage, lifecycle behavior, feature completeness, and the project's own validation commands.
3. **An honest handoff.** The result says what passed, what still needs a decision, whether the intended surface worked at runtime, and who owns the smallest next action.

The contract and evidence live in `sp-vise/` so reviewers and CI can reproduce the result after the conversation ends. See [How Vise works](/ai/vise/how-it-works) for the complete loop and result states.

  **Preview release.** Vise provides strong guardrails for AI-assisted integration, but it does not replace code review, product QA, security review, or a real launch on your tenant data.

  Vise runs locally and does not upload your source code, file contents, or search queries. The hosted [docs MCP server](/ai/docs-mcp-server) is different: it helps assistants search the documentation, while Vise guides and validates work inside your project.

## Choose your next step

    Review a grounded plan without changing code or using credentials.
    Compare a prebuilt UIKit surface with a custom SDK experience.
    Add a feature, diagnose a problem, or upgrade the SDK safely.
    Protect current and previously completed social.plus features.
    Prepare a verifiable handoff without confusing readiness with approval.
    Understand the loop, evidence, and result states.

---

### [Try Vise in 15 minutes](https://learn.social.plus/ai/vise/evaluate)

> Let your agent plan a real social.plus integration without credentials or code changes.

Use a clean branch or disposable copy of a real app. This walkthrough stops after planning so you can evaluate the workflow safely.

  Vise requires Node.js 20 or newer. It runs locally; your coding agent follows its own data policy.

```sh
npm install -g @amityco/social-plus-vise
vise install-skill --target claude  # or: cursor . / vscode . / copilot . / codex
```
    Pick the example closest to your situation. The outputs below show the expected shape; the details should come from your app.

        **Input**

```text
Using Vise, plan how you'd add a social feed to this app with social.plus.
Don't change code yet. Show me the plan and the decisions you need from me.
```

        **Representative output**

```text
App detected: the concrete web or mobile app and its platform
Recommended path: UIKit or custom SDK UI, with a reason
Open decisions: region, target screen, feed source, feature scope
Relevant docs: cited social.plus setup and feed guidance
Files changed: none
```
        **Input**

```text
We already use social.plus for a feed. Using Vise, plan how to add
comments to the existing post detail experience. Preserve the feed,
and don't change code yet.
```

        **Representative output**

```text
Existing surface: feed and post detail flow
Change impact: comments belong to the selected post
Preserve: current feed behavior and earlier evidence
Open decisions: replies, reactions, moderation, target route
Files changed: none
```
        **Input**

```text
Using Vise, investigate why the feed is missing from the selected
Community detail page. Show me the intended journey, likely gap, and
smallest safe repair plan. Don't change code yet.
```

        **Representative output**

```text
Intended journey: selected community -> detail page -> community feed
Current evidence: route, target source, and relevant implementation
Likely gap: implementation mismatch or stale/missing runtime proof
Next step: bounded repair and the checks that must be refreshed
Files changed: none
```
    Look for four things:

    - the correct app and platform were identified
    - the plan cites real social.plus capabilities and documentation
    - region, target screen, data source, and other product choices appear as questions rather than guesses
    - the response confirms that no files were changed
    For this evaluation, the plan and decision list are the deliverable. Do not answer the questions until you want the agent to begin implementation.

This exercise shows that Vise works with your agent and codebase. It does not prove that an integration has been built, passes project checks, or works with your credentials and tenant data.

## Continue

    Compare UIKit with a custom SDK experience.
    Add, diagnose, or upgrade an existing social.plus app.
    Understand the full implementation and validation loop.

---

### [Choose how to build your social experience](https://learn.social.plus/ai/vise/choose-integration-path)

> Decide whether to launch with a prebuilt UIKit surface or build a differentiated experience directly on the social.plus SDK.

Before your agent writes code, choose how much of the experience your app needs to own. Vise can inspect your project and recommend a path, but you make the final product decision.

## Ask your agent for a recommendation

```text
Using Vise, inspect this app and recommend whether this feature should use
social.plus UIKit or a custom UI built on the SDK. Explain the tradeoffs for
our existing design system and target screen. Don't change code yet.
```

## Compare the two paths

| Consideration | UIKit | Custom SDK UI |
| --- | --- | --- |
| Best fit | A standard feed, chat, community, or story experience | A differentiated layout, workflow, or interaction model |
| Fastest route | Yes — start from prebuilt social.plus screens | No — your app owns the presentation and behavior |
| Design control | Theme and customize within UIKit's supported levels | Full control through your app's components and design system |
| SDK responsibility | Mostly configuration and app-owned integration boundaries | Your app owns SDK queries, lifecycle, state, and UI behavior |
| Ongoing maintenance | Follow UIKit releases and supported extension points | Maintain the complete app-owned implementation |

Choose **UIKit** when the desired experience is close to a standard social surface and speed matters most. Choose a **custom SDK UI** when the interaction itself differentiates your product or must fit an established app-specific workflow.

  A mixed approach is possible, but it should be an explicit architecture decision. Do not start with UIKit and quietly replace standard behavior with raw SDK calls during implementation.

## Decisions to make before implementation

Whichever path you choose, expect your agent to confirm:

- the feature and capabilities that are in scope
- the screen or route where it belongs
- the social.plus region and identity source
- where the feed, community, channel, or other target comes from
- the design constraints and runtime environment the finished work must satisfy

Once those decisions are clear, ask the agent to record the agreed outcome and begin implementation.

## Continue with your chosen path

    Use a prebuilt UIKit surface with the lightest customization that fits.
    Build a differentiated, app-owned experience directly on the SDK.

---

### [Launch a standard social experience](https://learn.social.plus/ai/vise/uikit-quickstart)

> Ask your agent to launch a prebuilt social.plus UIKit surface with the lightest customization that fits.

Choose this path when you want a standard social surface live quickly — a community feed, chat, stories — using social.plus UIKit's prebuilt screens, themed to your brand.

## What to ask

```text
Use social.plus UIKit to launch a standard community feed in this app.
Recommend the lowest customization level that fits our design system,
and don't hand-roll standard surfaces from SDK primitives.
```

## What your agent will ask you

The usual product questions — platform, screen or route, region, identity — plus one that's specific to UIKit:

- **How much to customize.** The agent recommends the lightest level that fits your design system: theming and dynamic UI, component styling, localization, behavior overrides, or fork-and-extend as a last resort. You confirm the choice; it's recorded with the rest of the plan.

## Staying on the UIKit path

The skill keeps the agent honest about the boundary. Once UIKit is the chosen route, UIKit's installation, provider, behavior, and customization guidance is the implementation source — the agent shouldn't quietly rebuild a standard feed from raw SDK calls. Mixing in direct SDK code is reserved for behavior that's genuinely differentiated for your app.

## What "done" looks like

Vise validates everything your app owns — SDK setup and region, authentication, configuration, and your project's own build, lint, and test checks. What it can't see inside prebuilt UIKit internals it won't claim to have verified. A themed UIKit screen still deserves product QA and a real launch before you ship it.

## Related

    Compare UIKit with a custom SDK experience.
    Need a differentiated experience? Build directly on the SDK.

---

### [Build a custom social experience](https://learn.social.plus/ai/vise/sdk-custom-ui)

> Ask your agent for a differentiated social.plus experience built directly on the SDK and owned by your app.

Choose this path when the feature needs your own layout, workflow, or interaction model — UI your app owns, built directly on the social.plus SDK.

## What to ask

```text
Add a social feed to this app using the social.plus SDK. Keep the UI
consistent with the existing design system, and ask me about any missing
scope, target, route, region, or identity decisions before editing.
```

## What your agent will ask you

Expect questions before any code changes. Typical ones for an app-owned surface:

- **Region** — which social.plus region your app runs in.
- **Where it lives** — the screen or route that hosts the new surface.
- **Where data comes from** — the feed or community target: from a route, app state, user selection, SDK discovery, or a create flow. Vise won't let the agent hard-code an invented ID.
- **Scope** — which post types, composer options, comments, reactions, and moderation behavior are in or out.

  Don't paste API keys or server-issued tokens into the chat. Point the agent at your app's ignored environment/configuration pattern instead.

## What "done" looks like

Before the agent calls this finished, Vise holds it to:

- Real SDK APIs — actual types and field names, not remembered ones.
- The platform lifecycle — realtime data subscriptions and cleanup, pagination, session renewal, and user switching handled correctly.
- The whole feature — loading, empty, and error states, not just the happy path.
- Recorded decisions — your scope answers are part of the contract, so a reviewer can see what was agreed.

Then run the app and look at it. Passing checks prove the code is right; only a real launch proves the screen mounts, authenticates, and fills with your tenant's data. Your agent can assess that launch and record it as runtime evidence — or record an explicit waiver if no device is available.

## Related

    Compare custom SDK ownership with a prebuilt UIKit surface.
    Prefer a prebuilt surface? Launch with UIKit instead.

---

### [Maintain an existing integration](https://learn.social.plus/ai/vise/brownfield-day2)

> Add a feature, diagnose a problem, or upgrade the SDK without losing confidence in the social.plus experiences that already work.

Use this path when the app already has social.plus. Start with the outcome or symptom; your agent chooses the Vise workflow.

  Ask the agent to start with `vise status . --format human`. It reads the current lifecycle state without running project sensors or changing files, then routes unchanged work, a Day-2 change, or a release handoff to the smallest next action.

    Ask for the new behavior and name what must keep working:

```text
We already use social.plus for the feed. Using Vise, add comments to the
existing post detail screen. Preserve the current feed behavior and show
me the impact and product questions before changing code.
```

    Expect a short assessment of the existing surface, the new scope, affected files and evidence, and any product decisions still missing.
    Describe what the user sees, where it happens, and what should happen instead:

```text
Using Vise, diagnose why the feed is missing from the selected Community
detail page. Show me the likely gap and the smallest safe repair before
changing code.
```

    The agent should compare the intended route and data target with the current source and evidence, then separate the repair from the checks that need to be refreshed.
    Ask for the version and feature impact before changing dependencies:

```text
Using Vise, assess the social.plus SDK upgrade in this app. Explain the
current and target version boundary, affected features, and validation
plan before changing dependencies or source code.
```

    Vise checks the declaration and supported lockfile resolution. It reports the assurance boundary honestly rather than treating a version range as proof of compatibility.

## Protect what already works

Before editing, the agent should identify the existing feature, route, data target, and evidence that could be affected.

If the integration predates Vise, pre-existing findings can be recorded as a baseline so the new change is judged on its own work. The baseline never excuses the requested outcome or anything the change introduces.

If earlier features were built with Vise, they stay recorded and re-verifiable. Ask the agent to report earlier-feature drift separately from the current work.

If a support incident or dogfood miss reveals a reusable blind spot, a reviewed `incident-protection` learning record can bind a sanitized finding fixture, clean control, and exact verification evidence. It stays local, never uploads customer source, and does not edit rules or change readiness automatically.

## What "done" looks like

The handoff should state:

- what behavior and scope changed
- whether every earlier completed feature still holds
- which project build, lint, typecheck, test, and SDK smoke checks ran
- whether changed user-visible surfaces have fresh runtime proof or an explicit waiver
- which advisory findings or product decisions remain open

```sh
# Route the current lifecycle job without changing the project
vise status . --format human

# Assess a planned change
vise impact . --format human

# Attach a reported symptom
vise impact . --symptom "Feed is missing from Community detail" --format human

# Inspect the installed SDK boundary
vise sdk-release . --format human

# Protect current and previously completed features in CI
vise check . --ci

# Preview a reviewed incident-to-protection record without writing
vise learning record . --kind incident-protection \
  --evidence <repo-relative-input.json> --no-write
```

  See the [command reference](/ai/vise/cli-reference) for baseline, evidence, and per-feature options.

## Related

    Protect current and earlier social.plus features after the handoff.
    Turn the completed change into a reviewable release candidate.

---

### [Keep integrations verified in CI](https://learn.social.plus/ai/vise/ci-verification)

> Make the same Vise contract and evidence that guided implementation protect current and previously completed social.plus features in CI.

After the first integration is green, keep it verifiable after the coding-agent conversation ends. Commit the `sp-vise/` folder with the application, then run Vise as a read-only CI gate.

## What the CI gate protects

The gate checks more than the feature currently being edited:

- the active integration still matches its recorded scope
- deterministic SDK and platform requirements still pass
- required evidence and project sensors are present and current, including any retained runtime receipt
- accepted organization policy remains current, authentic, and inside its lifecycle and trust boundaries
- every previously completed Vise feature still holds against the current code

This matters when a later change passes for one surface but quietly breaks an earlier feed, comments, community, or chat experience.

## Add the gate

Install the same Vise version your team uses for local work, then run:

```sh
vise check . --ci
```

Keep the command read-only in CI. Changes to contracts, attestations, baselines, runtime waivers, or policy selections should be deliberate reviewable changes made before the pipeline runs.

For a more diagnostic pipeline, verify retained runtime evidence or the repository policy source in separate read-only steps before the composed gate:

```sh
vise smoke verify . \
  --evidence sp-vise/evidence/runtime-smoke/<surface>.json
vise policy status . --ci
vise check . --ci
```

## Read the outcome

- **Green:** the active work and all recorded completed features still hold.
- **Active failure:** the current integration, required evidence, or project validation needs attention.
- **Earlier-feature drift:** the active work passes, but a previously completed surface no longer does.
- **Release review required:** when Passport comparison is enabled, the compliance checks pass but a person still needs to review the candidate's release evidence.
- **Policy review required or blocked:** the accepted policy source changed or crossed a lifecycle, signing-key, or rotation boundary; Vise returns the exact owner instead of accepting a successor automatically.

Link the CI output to the changed application code and committed `sp-vise/` evidence so reviewers can reproduce the result locally.

  MCP `check_compliance` returns the same compliance result and exit code with an additive `customerOperations` summary for build, Day-2, and release routing. The summary does not run sensors, write files, or turn advisory findings into a gate.

  Teams using Integration Passports can add the same release comparison used during human review:

```sh
vise check . --ci \
  --from-passport <approved-passport.json> \
  --to-passport <candidate-passport.json>
```

  A `ready` result supports human release review; it does not record approval. See the [command reference](/ai/vise/cli-reference) for exact exit codes and trust-policy options.

## Related

    Understand result states and which ones need human input.
    Review the candidate evidence without confusing readiness with approval.

---

### [Review and release an integration](https://learn.social.plus/ai/vise/release-assurance)

> Review what changed, what proves it, and which decisions remain human before release.

A green Vise result is ready for human review; it is not a release approval.

Start with the lifecycle summary so the reviewer sees the smallest missing action without collapsing independent claims:

```sh
vise status . --format human
```

## Ask for a release handoff

```text
Using Vise, prepare this social.plus change for release review. Summarize
what changed, the SDK boundary, evidence, regressions or waivers, and the
decisions a person still needs to make. Do not claim human approval.
```

If your team has an approved Vise handoff, provide it so the candidate can be compared with that known point.

## What the reviewer should receive

1. **What changed?** The accepted feature scope, placement, target, source, and dependency changes.
2. **What proves it?** Automatic checks, project sensors, attestations, and a source/build/route/target-bound runtime receipt—or clearly disclosed waivers.
3. **What moved?** SDK knowledge and fact depth, organization policy, evidence freshness, residual risk, or previously completed behavior that differs from the accepted candidate.
4. **What remains human?** Product QA, security review, risk acceptance, and release approval.

An optional **Integration Passport** packages the candidate's intent and evidence into verifiable claims so another reviewer can detect changed or stale material.

A verified runtime receipt proves that its retained evidence still matches the recorded build and surface; it does not prove visual quality, every SDK behavior, or release approval. Organization Policy Operations likewise identifies accepted, changed, expired, superseded, or revoked policy and routes the exact owner without accepting an update automatically.

## Read the decision

| Decision | Meaning | Human action |
| --- | --- | --- |
| `ready` | No blocking automated regression was found | Complete normal product, security, and release review |
| `review-required` | Valid evidence contains SDK, policy, lifecycle, or provenance movement | Review the disclosed changes and owners |
| `blocked` | Required evidence, policy, or trusted provenance is missing | Resolve the named blocker and prepare a new candidate |

Vise never records or impersonates human approval.

  Policy Packs can declare approved SDK ranges and required evidence. Trust envelopes can authenticate a reviewed Passport or Policy Pack across teams or CI systems. A valid signature proves provenance, not integration correctness.

```sh
vise policy status . --ci --format human
vise sdk-release . --format human
vise smoke verify . \
  --evidence sp-vise/evidence/runtime-smoke/<surface>.json
vise passport . --write
vise passport verify . --format human
vise passport compare . \
  --from <approved-passport.json> \
  --to <candidate-passport.json> \
  --format human
```

  Policy status exits `0` for `ready`, `12` for `review-required`, and `13` for `blocked`. Accepting a reviewed repository policy source is a separate CLI-only write with `vise policy accept`; its receipt proves the recording action, not release approval.

  See the [command reference](/ai/vise/cli-reference) for policy, trust, and CI options.

Keep the candidate Passport and comparison when used, the committed `sp-vise/` evidence, CI output, applicable policy files, and the approval recorded by your own release process.

## Related

    Reproduce the checks in the release pipeline.
    Understand result states and their human-review boundary.

---

### [How Vise works](https://learn.social.plus/ai/vise/how-it-works)

> How a feature request becomes a grounded plan, checked code, reviewable evidence, and a clear next action.

Vise gives an AI coding agent a repeatable social.plus integration loop. You describe the outcome, answer the product decisions only your team can make, and review the result.

## From request to evidence

```mermaid
flowchart LR
  A[Ask for an outcome] --> B[Inspect and plan]
  B --> C[Confirm decisions]
  C --> D[Implement and check]
  D -->|Needs work| D
  D --> E[Run project checks]
  E --> F[Record evidence]
  F --> G[Human review]
```

On resumed work, `vise status` reads the current evidence first and routes the agent to the relevant build, Day-2, or release-review step. It does not run project sensors or change the existing compliance result.

1. **Inspect and plan.** The agent identifies the app surface, reads social.plus documentation and SDK facts, and asks instead of guessing.
2. **Confirm decisions.** Vise records the feature, placement, data target, selected capabilities, and definition of done.
3. **Implement and check.** The agent validates real SDK usage, platform lifecycle, and feature completeness while it works.
4. **Run project checks.** The app's build, lint, typecheck, tests, and SDK smoke checks run when available.
5. **Record evidence.** The result explains what passed, what still needs work, and whether the intended surface worked at runtime.

## Read the result

Ask your agent to separate the outcome into what passed, what it will fix, and what needs your decision.

| Result | What happens next |
| --- | --- |
| `green` | Review the feature through your normal product process |
| `deterministic-failures` or `completeness-gap` | The agent fixes the code or finishes the agreed scope |
| `selected-capability-failures` | Finish the selected capability or explicitly remove it from scope |
| `blocked` | Answer the named product or project question |
| `needs-attestation` | Review evidence for correct architecture the automatic check cannot see |
| `contract-drift` | Confirm the changed intent or restore the implementation |
| `runtime-proof-waived` | Accept the explicit waiver or request a real launch |
| `engagement-drift` | Reopen the earlier feature or explicitly accept the change |

`no-platform` means Vise did not find a supported app surface. Confirm that the agent is working in the correct package before concluding that there is nothing to validate.

## What the evidence means

The contract, check results, attestations, and runtime receipts live in `sp-vise/`. Commit that folder with the application so review and CI do not depend on an agent transcript.

Evidence can prove an automatic check passed, explain architecture a static rule cannot follow, or show that a specific surface mounted and loaded data at its recorded route and target.

It does not replace product QA, security review, or human release approval. User-visible work still needs a real launch or an honest recorded waiver.

| Claim | What Vise can establish | What remains separate |
| --- | --- | --- |
| Compliance | Recorded scope, deterministic SDK/platform checks, and earlier-feature drift | Product and security judgment |
| Project sensors | The detected build, lint, typecheck, test, or SDK-smoke command result | Tests that were unavailable or not selected |
| Runtime receipt | Retained source, build, runner, route, target, artifact, and Passport lineage still match | Visual quality and unobserved SDK semantics |
| SDK assurance | Exact extracted symbols, models, capability anchors, provenance, freshness, and fact-depth state | Compatibility beyond the reviewed evidence |
| Organization policy | Accepted source, lifecycle, trust-key state, update impact, and responsible owner | Policy acceptance and release approval |
| Passport and advisory review | Digest-bound handoff claims and disclosed movement | The human decision to ship |

## Related

    Add, diagnose, or upgrade without losing earlier evidence.
    Carry the same contract and evidence into the pipeline.
    Look up the full command surface when operating Vise directly.
    Expose Vise's local tools to an MCP-capable coding host.

---

### [Run Vise as an MCP server](https://learn.social.plus/ai/vise/mcp-server)

> Expose Vise's local tools to Claude Code, Cursor, Codex, and VS Code over MCP.

Vise ships an MCP adapter, so any MCP-capable host can call Vise's tools — inspect, plan, assess Day-2 impact, check SDK and organization-policy boundaries, verify runtime receipts, compose Passports, validate, run sensors, and look up docs — directly during the coding loop. Start it with:

```sh
vise mcp
```

This runs a local **stdio** MCP server. You normally don't run it by hand; you register the command in your host's MCP configuration and the host launches it for you.

  This is different from the hosted **docs** MCP server at `https://learn.social.plus/mcp` ([overview](/ai/docs-mcp-server)). That one is remote (SSE) and only reads documentation. The Vise MCP server runs **locally** and exposes Vise's validation and planning tools against the repository you're working in. You can use both at once.

## Prerequisites

Install Vise so the `vise` command is on your `PATH`:

```sh
npm install -g @amityco/social-plus-vise
vise doctor
```

If you prefer not to install globally, replace the command below with `npx` and args `["-y", "-p", "@amityco/social-plus-vise", "vise", "mcp"]`.

## Configure your host

    Add a project-scoped `.mcp.json` in your repository root:

```json
{
  "mcpServers": {
    "social-plus-vise": {
      "command": "vise",
      "args": ["mcp"]
    }
  }
}
```
    Add `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "social-plus-vise": {
      "command": "vise",
      "args": ["mcp"]
    }
  }
}
```
    Add `.vscode/mcp.json` in your project (VS Code uses a `servers` key):

```json
{
  "servers": {
    "social-plus-vise": {
      "command": "vise",
      "args": ["mcp"]
    }
  }
}
```
    Add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.social-plus-vise]
command = "vise"
args = ["mcp"]
```

Restart or reload the host after editing its configuration, then confirm `social-plus-vise` appears as an available MCP server.

## What it exposes

The Vise MCP tools mirror the [CLI commands](/ai/vise/cli-reference), named in snake_case. The ones you'll use most:

| Tool | Mirrors | Purpose |
| --- | --- | --- |
| `inspect_project` | `vise inspect` | Detect platform, surfaces, sensors, and complete-scan coverage |
| `impact_project` | `vise impact` | Explain Day-2 change impact, evidence freshness, reported cross-surface symptoms, and the smallest safe next actions without editing |
| `analyze_sdk_release` | `vise sdk-release` | Explain exact-snapshot SDK assurance or diff two extracted SDK surface snapshots |
| `plan_integration` | `vise plan` | Grounded plan with docs citations and intake |
| `init_compliance` | `vise init` | Write the `sp-vise/` contract |
| `check_compliance` | `vise check` + lifecycle summary | Validate the code against the contract and add the same `customerOperations` build, Day-2, and release routing returned by CLI `vise status` |
| `assess_policy_operations` | `vise policy status` | Read the repository policy source, lifecycle and trust state, deterministic update impact, and exact owner routing |
| `verify_runtime_receipt` | `vise smoke verify` | Verify retained source/build/runner/surface/artifact/Passport bindings without relaunching the app |
| `generate_integration_passport` | `vise passport` | Compose a digest-bound, sanitized integration handoff; read-only unless writing is explicit |
| `verify_integration_passport` | `vise passport verify` | Recompute Passport claims and local evidence hashes without repairing the project |
| `compare_integration_passports` | `vise passport compare` | Compare handoffs and compose the Governed Release Review decision |
| `verify_trust_envelope` | `vise trust verify` | Authenticate a Passport or Policy Pack envelope against an explicit local trust policy |
| `run_sensors` | `vise run-sensors` | Run detected build, lint, typecheck, and smoke checks; explicitly included sensor names must match |
| `get_sdk_facts` | `vise sdk-facts` | Read grounded SDK surface facts |
| `search_docs` / `get_doc_page` | `vise search-docs` / `vise get-doc-page` | Find and read social.plus docs |
| `debug_issue` | `vise debug` | Diagnose an SDK-specific runtime failure |
| `attest_rule` / `explain_rule` | `vise attest` / `vise explain` | Record evidence and read rule guidance |
| `record_learning` / `show_learning` | `vise learning record` / `vise learning show` | Record and read local-only, advisory learning and Outcome Evidence |

`check_compliance` keeps its established compliance fields and exit code; `customerOperations` is additive and read-only. It does not run sensors, write files, gate on advisory findings, or infer human approval.

Signing trust envelopes, accepting an organization policy source, and installing Managed Placements are intentionally CLI-only. An MCP host can verify an envelope or assess policy, but Vise does not expose private-key signing or controlled policy acceptance through MCP.

## Skill or MCP?

The [skill](/ai/vise/overview#get-started) and the MCP server are complementary:

- The **skill** teaches the agent *when* to inspect, plan, fetch docs, validate, and attest.
- The **MCP server** exposes the *tools* the agent calls to do it.

For MCP-capable hosts, install the skill **and** register the MCP server. On hosts without MCP support, install the skill and let the agent call the `vise` CLI directly.

## Related

    Install Vise and run your first integration.
    The governed loop and how to read a check result.
    The full command set behind these tools.
    Connect an AI tool to the hosted documentation MCP server.

---

### [Command reference](https://learn.social.plus/ai/vise/cli-reference)

> For reviewers and CI — the commands behind the skill, and the ones you run to verify recorded evidence.

Day to day, you don't need this page: your agent runs these commands through the [skill](/ai/vise/overview#get-started). It exists for the moments a human drives Vise directly — reviewing recorded evidence, gating a release in CI, or peeking under the hood. For the complete list and every flag, run `vise --help` or `vise <command> --help`. Most agent-facing commands have an [MCP tool equivalent](/ai/vise/mcp-server#what-it-exposes) in snake_case; trust signing and Managed Placement installation are intentionally CLI-only.

  Most commands take a project path (default: the current directory) and read or write state under `sp-vise/`. The ones reviewers reach for most: `vise impact`, `vise status`, `vise check --ci`, and `vise passport`.

## Explore and plan

| Command | Purpose |
| --- | --- |
| `vise explore "<request>"` | Map a request to what social.plus offers — no project or API key needed |
| `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors, and bounded scan coverage. An incomplete scan cannot initialize or produce a green check; select the concrete app surface in a large monorepo |
| `vise plan [path] --request "..."` | Grounded implementation plan with intake questions and docs citations (`--summary` for a compact view) |
| `vise init [path] --request "..." --answer key=value` | Write the `sp-vise/` compliance contract once blocking intake is answered. Reviewed organization policy, signed-policy trust, and aggregate measurement intent can be accepted with `--policy-pack`, `--trust-policy`, and `--measurement-plan`. Initializing a different outcome records the previous engagement to `sp-vise/engagements/` first; replacing a **green** engagement asks for `--supersede-engagement` |

For broad requests that span several surfaces (feed + chat + profile), Vise sequences them:

| Command | Purpose |
| --- | --- |
| `vise workplan next [path] --request "..."` | Print the next uncompleted surface and its focused commands |
| `vise workplan status [path] --request "..."` | Show the sequence and which surfaces are done |
| `vise workplan complete [path] --request "..." --surface <id>` | Record a green-checked surface with snapshot evidence |
| `vise workplan trim [path] --request "..." --surface <id> --reason "..."` | Deliberately omit a companion surface and re-arm blueprint confirmation so the changed journey is reviewed |

## Day-2 and release assurance

| Command | Purpose |
| --- | --- |
| `vise status [path]` | Read-only lifecycle front door for build, Day-2 change, and release review. Keeps compliance, runtime, SDK, policy, advisory, Passport, and human-approval claims separate; reports owners and the smallest next actions without running sensors, writing files, or changing the compliance exit code |
| `vise impact [path] [--symptom "..."]` | Read-only Day-2 planner. Compare the project with recorded intent, lifecycle state, SDK declarations, policy, and evidence; classify evidence as preserved, stale, missing, or unknown; and return the smallest safe recovery sequence. A symptom can authorize a bounded repair when recorded cross-surface intent and current source confirm the gap |
| `vise sdk-release [path]` | Explain whether detected SDK declarations and supported lockfile resolutions match Vise's exact extraction-grounded snapshots, reviewed knowledge, and five-platform fact-depth contract. `meets-target`, `target-gap`, `regressed`, and `unknown` stay explicit; it does not fetch registries, edit dependencies, or infer semantic compatibility from semver |
| `vise sdk-release --from-surface-dir <before> --to-surface-dir <after>` | Diff two SDK surface snapshots for symbol, model-field, capability, and affected-rule changes |
| `vise policy status [path] [--source <manifest>] [--ci]` | Read-only organization-policy source, lifecycle, trust-key rotation/revocation, deterministic update impact, and exact owner routing. CI exits `0`, `12`, or `13` for `ready`, `review-required`, or `blocked` |
| `vise policy accept [path] --source <manifest> --recorded-by <identity> --reason "..."` | CLI-only explicit write: pin the exact reviewed source and Policy Pack digests and write an audit receipt. It never rewrites policy inputs, manages keys, or asserts release approval |
| `vise passport [path] [--write]` | Compose sanitized accepted intent, lifecycle, SDK assurance, evidence hashes, runtime state, residual risk, and replay commands into digest-bound claims. Read-only unless `--write` is explicit |
| `vise passport verify [path] [--passport <path>]` | Recompute Passport claims and local evidence states without rerunning or repairing the project |
| `vise passport compare [path] --from <before> --to <after>` | Compare two valid Passports and compose a Governed Release Review result: `ready`, `review-required`, or `blocked` |
| `vise trust sign [path] ...` | CLI-only explicit write: wrap a reviewed Passport or Policy Pack in an Ed25519 envelope using an external private key that Vise does not retain |
| `vise trust verify [path] --envelope <path> --trust-policy <path>` | Authenticate envelope integrity, issuer/key authorization, artifact type, audience, and validity. Signature validity does not replace Passport or Policy Pack semantic validation |

See [Review and release an integration](/ai/vise/release-assurance) for the recommended handoff flow.

## Validate and verify

| Command | Purpose |
| --- | --- |
| `vise check [path]` | Validate the code against the recorded contract |
| `vise check [path] --ci` | Read-only release gate for the active contract and every recorded engagement; exits `11` when active work is green but completed work drifted |
| `vise check [path] --ci --from-passport <before> --to-passport <after>` | Add Governed Release Review to an otherwise unchanged compliance gate. Existing compliance codes take precedence; otherwise-green compliance exits `12` when release evidence is `review-required` or `blocked`. Add `--trust-policy` when both inputs are signed envelopes |
| `vise check [path] --new-only` | Gate only on *rule findings* introduced since the baseline — the outcome's completeness checklist and selected capabilities always gate (they are the engagement's deliverables) |
| `vise check [path] --allow-proof-waiver` | Accept an honest `runtime-proof-waived` result as passing |
| `vise check [path] --engagement <outcome>` | Re-verify one previously completed engagement against the current rules and code (exit `11` on drift, `0` when it still holds) |
| `vise check [path] --all-engagements` | The normal check plus re-verification of every recorded engagement; exit `11` means your current work is green but a previously finished surface drifted |
| `vise validate [path]` | Run the deterministic validators only (no attestation comparison) |
| `vise explain <ruleId>` | Print a rule's rationale, evidence requirements, and remediation |

See [Read the result](/ai/vise/how-it-works#read-the-result) for what each state means.

## Evidence

| Command | Purpose |
| --- | --- |
| `vise baseline [path]` | Snapshot pre-existing rule findings so `--new-only` can exclude them. Record it right after `vise init`, before writing code; the feature you asked for is never baselined — it still has to be built |
| `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record that a rule is satisfied through architecture the check can't see |
| `vise sync [path]` | Persist deterministic-pass evidence after a green check |
| `vise smoke declare [path] --surface <id> [--route <route>] [--target-type <type>]` | Declare the exact runtime collection surface and, when applicable, its route and SDK target |
| `vise smoke [path] --log <file> [--surface <id> ...] [--receipt-context <json>]` | Assess normalized runtime markers and write independent per-surface receipts. Marker surface, route, and target must match the declaration; strict receipt context additionally binds source, build, runner, artifacts, and prior Passport lineage |
| `vise smoke verify [path] --evidence <scoped-runtime-smoke.json>` | Read-only receipt verification without relaunching the app; distinguishes `absent`, `stale`, `tampered`, `failed`, and `passed` |
| `vise smoke waive [path] --reason "..." --mode declined\|deviceless` | Record an auditable runtime-proof waiver |

## Engagement history

| Command | Purpose |
| --- | --- |
| `vise engagement init [path] --tier <tier> --customer-id <id> --scope <outcome,...>` | Record the contractual broad-social engagement scope, with optional target date, reviewer, and evidence-upload consent |
| `vise engagement show [path]` | Read the recorded engagement-scope artifact |

## Project sensors

| Command | Purpose |
| --- | --- |
| `vise run-sensors [path] [--dry-run] [--include "<sensor name>"]` | Run detected project build, lint, typecheck, test, and SDK-smoke commands. An explicit `--include` must match a detected sensor or the command fails; captured output is bounded, and timed-out sensors terminate their descendant processes |

## Docs and SDK facts

| Command | Purpose |
| --- | --- |
| `vise search-docs "<query>"` | Search social.plus docs for relevant pages |
| `vise get-doc-page <path>` | Fetch a specific doc page by path |
| `vise sdk-facts --platform <platform>` | Read bundled SDK surface facts (`--capability`, `--format json`) |
| `vise debug [path] --error "..."` | Diagnose an SDK-specific runtime failure |
| `vise placements plan [path] --placement <id> --package-source <local-path>` | Plan explicitly selected Managed Placement host and slot governance without writing |
| `vise placements add [path] --placement <id> --package-source <local-path> [--dry-run\|--apply]` | Preview by default, or explicitly install the pre-launch private host from a local/file source. Vise never guesses a slot coordinate |
| `vise placements validate [path] [--placement <id>]` | Validate one host initialization, explicit slot/context evidence, secret hygiene, and sidecar drift |

## Experience planning and outcome evidence (advisory)

| Command | Purpose |
| --- | --- |
| `vise creative [path] --request "..."` | Produce an Engagement Intelligence brief with candidate experiences, rationale, tradeoffs, and review gaps |
| `vise creative accept [path] --variant <id\|none> ...` | Record an explicit, reasoned selection or catalog gap |
| `vise ux-harness [path]` | Generate advisory UX expectations from the selected variant |
| `vise experience compile [path]` | Compile the selected variant into implementation artifacts |
| `vise experience sensors [path]` | Write the advisory experience sensor framework |
| `vise experience-report [path]` | Write a dimensioned advisory experience review |
| `vise learning record [path]` | Record a local-only learning event or reviewed aggregate Outcome Evidence |
| `vise learning record [path] --kind incident-protection --evidence <input.json> [--no-write]` | Preview or record a reviewed, sanitized incident bound to distinct finding/clean fixtures and exact evidence. It never executes replay, uploads source, edits protection, or changes readiness |
| `vise learning show [path]` | Read the local learning summary and non-causal advisory deltas |

These commands do not upload customer data, assign a calibrated score, change recommendations automatically, or affect `vise check` exit codes.

## Design (advisory)

| Command | Purpose |
| --- | --- |
| `vise design extract <prototype>` | Extract a graded design contract from an HTML/CSS prototype (`--from-project` to derive from your own tokens) |
| `vise design check [path]` | Advisory token-conformance report, including computed WCAG for the brand palette |
| `vise design preview [path]` | Write a self-contained visual review for human or VLM judgment |

## Skill and MCP

| Command | Purpose |
| --- | --- |
| `vise install-skill --target <host>` | Install the bundled skill (`claude`, `cursor`, `vscode`, `copilot`, `codex`) |
| `vise print-skill` | Print the skill markdown to stdout |
| `vise mcp` | Start the local [MCP server](/ai/vise/mcp-server) |
| `vise doctor` | Verify the install — version, path, docs source |

## Related

    The loop behind these commands and how to read results.
    The MCP tool equivalents of these commands.