Rooms Overview

Rooms provide an advanced broadcasting infrastructure that enables interactive live streaming with co-hosting capabilities. This page covers the core concepts, data models, and architecture of the room system.

Overview

The Room feature extends traditional livestreaming by supporting collaborative broadcasting where multiple users can participate as co-hosts. Rooms handle video/audio synchronization, participant management, and provide comprehensive moderation controls.

Key Features

Co-Hosting

Multiple broadcasters in one stream

Invite co-hosts to join the broadcast
Real-time audio/video synchronization
Host and co-host role management
Participant limit controls

Room Types

Flexible streaming architectures

Co-Hosts: Multiple broadcasters with LiveKit
Parent-child room relationships
Isolated or linked chat channels

Lifecycle Management

Complete room state handling

Idle → Live → Ended lifecycle
Waiting for reconnection states
Live viewing and recorded playback
Automatic cleanup

Moderation & Safety

AI-powered content moderation

Real-time content flagging
Automatic termination rules
Moderation label tracking
Stream safety controls

Room Types

Co-Hosts Room

Multi-participant broadcasting using LiveKit infrastructure: Characteristics:

Multiple simultaneous broadcasters
Real-time audio/video mixing
Interactive participant management
Requires LiveKit tokens for each participant

Use Cases:

Panel discussions
Interviews and Q&A sessions
Collaborative workshops
Multi-host shows

Room Lifecycle

Status	Description	Actions Available
Idle	Room created but not broadcasting	Start stream, invite co-hosts, delete room
Live	Room is actively broadcasting	Stop stream, invite/remove co-hosts, moderate content
Waiting Reconnect	Temporary disconnection	Auto-reconnect, manual stop
Ended	Broadcast finished	View recording, delete room
Recorded	Recording available	Playback, download, delete

Status Flow

Creation → Idle: Room created, awaiting first broadcast
Idle → Live: Broadcaster starts streaming
Live → Waiting Reconnect: Temporary disconnection (automatic)
Waiting Reconnect → Live: Reconnection successful
Live → Ended: Broadcast stopped (manual or automatic)
Ended → Recorded: Recording processing complete

Room Participants

Participants represent users who can broadcast in the room:

// AmityRoomParticipant structure
struct AmityRoomParticipant {
    let type: AmityRoomParticipantType  // .host, .coHost, .unknown
    let userId: String
    let userInternalId: String?
    let user: AmityUser?  // Linked user object
}

enum AmityRoomParticipantType {
    case host      // Creator of the room, full control
    case coHost    // Invited broadcaster, limited controls
    case unknown   // Unknown participant type
}

Participant Roles:

Role	Description	Permissions
Host	Creator of the room	Full control, invite/remove co-hosts, end stream
Co-Host	Invited broadcaster	Broadcast audio/video, leave stream
Viewer	Watching the stream	View only (not a room participant)

For detailed co-host invitation and management workflows, see Co-Host Management.

Room Targets

Rooms can be created for different contexts:

Community Room

// Community target
let target = AmityRoomTarget(
    type: .community,
    communityId: "community-123",
    community: community  // Linked AmityCommunity object
)

Broadcast to a specific community’s audience.

User Room

// User target
let target = AmityRoomTarget(
    type: .user,
    userId: "user-123",
    user: user  // Linked AmityUser object
)

Broadcast to user’s timeline followers.

Room References

Link rooms to other content types: Supported References:

Community: Room associated with community content
User: Room on user’s timeline
Event: Room linked to a scheduled event

struct AmityRoomReference {
    let referenceType: AmityRoomReferenceType  // .community, .user, .event
    let referenceId: String
}

Channel Integration

Rooms can have integrated live chat channels for viewer interaction. Channels must be manually created after the livestream post is created.

// Channel properties on AmityRoom
let channelEnabled: Bool      // Indicates room supports live chat
let channelId: String?        // Set after channel is created
let channel: AmityChannel?    // Linked channel object

Channel Features:

Live chat during broadcast
Host/Co-host badges
Moderation tools
Message history

Manual Channel Creation Required: Channels are not automatically created. You must create the channel after the post is created, passing both postId and roomId. See Create Room - Room with Live Chat Channel for the complete workflow.

Moderation System

AI-powered moderation monitors room content in real-time:

struct AmityRoomModeration {
    let moderationId: String
    let roomId: String
    let flagLabels: [AmityRoomModerationLabel]
    let terminateLabels: [AmityRoomModerationLabel]
    let createdAt: Date
    let updatedAt: Date
}

struct AmityRoomModerationLabel {
    let category: String  // e.g., "violence", "nudity", "hate_speech"
    let detectedAt: Date
}

Flag Labels: Content detected but stream continues Terminate Labels: Content causes automatic stream termination

Automatic Termination: When terminate-level content is detected, the room status changes to “ended” automatically and cannot be restarted.

Parent-Child Room Relationships

Rooms can have hierarchical relationships for complex streaming scenarios:

// Parent-child properties on AmityRoom
let parentRoomId: String?
let parentRoom: AmityRoom?       // Linked parent room
let childRoomIds: [String]       // Array of child room IDs

Use Cases:

Breakout sessions from main room
Multi-language streams
Regional broadcasts

Room Data Model

Complete room object structure:

interface AmityRoom {
  roomId: string;
  type: AmityRoomType; // "coHosts"
  
  // Target
  targetType: string;
  targetId: string;
  target: AmityRoomTarget;
  
  // Reference
  referenceType: string;
  referenceId: string;
  reference: AmityRoomReference;
  
  // Content
  title: string;
  description?: string;
  thumbnailFileId?: string;
  
  // Status
  status: AmityRoomStatus;
  
  // Participants
  participants: AmityRoomParticipant[];
  
  // Channel
  channelEnabled: boolean;
  channelId?: string;
  channel?: AmityChannel;
  
  // Streaming
  livePlaybackUrl?: string;
  durationSeconds?: number;
  
  // Relationships
  parentRoomId?: string;
  parentRoom?: AmityRoom;
  childRoomIds: string[];
  
  // Creator
  creatorId: string;
  creator?: AmityUser;
  
  // Timestamps
  createdAt: string;
  updatedAt?: string;
  liveAt?: string;
  endedAt?: string;
  recordedAt?: string;
  
  // Deletion
  isDeleted: boolean;
  deletedAt?: string;
  deletedById?: string;
  deletedBy?: AmityUser;
  
  // Moderation
  moderation?: AmityRoomModeration;
  
  // Custom data
  metadata?: Record<string, any>;
}

Integration with Posts

Rooms are linked to posts for social distribution. See Room Posts for detailed post creation.

// Create room post
const post = await postRepository.createPost({
  dataType: PostContentType.ROOM,
  targetType: 'community',
  targetId: 'community-123',
  data: {
    text: 'Join us live!',
    roomId: room.roomId,
    title: room.title
  }
});

// Access room from post
console.log(post.data.room.status); // "live"
console.log(post.data.room.livePlaybackUrl);

Best Practices

Room Setup

Configure rooms appropriately for your use case:

Use Co-Hosts type for interactive sessions
Enable channels for viewer interaction
Set clear titles and descriptions
Upload thumbnails before going live
Configure participant limits

Co-Host Coordination

Manage co-hosts effectively:

Invite co-hosts before going live
Set clear moderation rules
Monitor participant count
Have backup hosts ready
Test audio/video before live

Moderation

Implement safety measures:

Review moderation labels regularly
Have moderation guidelines
Monitor flag labels proactively
Respond to violations quickly
Keep logs of moderation events

Performance

Optimize streaming performance:

Test network bandwidth
Use appropriate video quality
Monitor connection stability
Have reconnection strategies
Clean up ended rooms

Next Steps

Create Room

Set up new rooms for broadcasting

Start Broadcasting

Connect to LiveKit and go live

Co-Host Management

Invite and manage co-hosts

Live Viewing

Watch live streams in real-time

Recorded Playback

Play back recorded streams

Manage Rooms

Query, update, and control rooms

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Support

Rooms Overview

Rooms Overview

Overview

Key Features

Co-Hosting

Room Types

Lifecycle Management

Moderation & Safety

Room Types

Co-Hosts Room

Room Lifecycle

Status Flow

Room Participants

Room Targets

Community Room

User Room

Room References

Channel Integration

Moderation System

Parent-Child Room Relationships

Room Data Model

Integration with Posts

Best Practices

Next Steps

Create Room

Start Broadcasting

Co-Host Management

Live Viewing

Recorded Playback

Manage Rooms

Powered by

Getting Started

Fundamentals

Social

Chat

Video

Release Notes

Support

​Rooms Overview

​Overview

​Key Features

Co-Hosting

Room Types

Lifecycle Management

Moderation & Safety

​Room Types

​Co-Hosts Room

​Room Lifecycle

​Status Flow

​Room Participants

​Room Targets

​Community Room

​User Room

​Room References

​Channel Integration

​Moderation System

​Parent-Child Room Relationships

​Room Data Model

​Integration with Posts

​Best Practices

​Next Steps

Create Room

Start Broadcasting

Co-Host Management

Live Viewing

Recorded Playback

Manage Rooms

Rooms Overview

Overview

Key Features

Room Types

Co-Hosts Room

Room Lifecycle

Status Flow

Room Participants

Room Targets

Community Room

User Room

Room References

Channel Integration

Moderation System

Parent-Child Room Relationships

Room Data Model

Integration with Posts

Best Practices

Next Steps