# Room

## RoomService API

Get the roomService object through a login session

```kotlin
val roomService = session.roomService()
```

### **Create a one-on-one private chat room**

Establishes a private chat room between two users.

```kotlin
suspend fun createDirectRoom(otherUserId: String): String
```

**Input parameter:**

| Name        | Type   | Description                 | Required |
| ----------- | ------ | --------------------------- | -------- |
| otherUserId | string | ID of the other participant | true     |

**Output parameter:**

| Type   | Description         | Required |
| ------ | ------------------- | -------- |
| string | ID of the chat room | true     |

### **Create a general chat room**

```kotlin
suspend fun createRoom(createRoomParams: CreateRoomParams): String
```

**Input parameter:**

| Name             | Type             | Description                  | Required |
| ---------------- | ---------------- | ---------------------------- | -------- |
| createRoomParams | CreateRoomParams | Parameters for room creation | true     |

**CreateRoomParams:**

| Name           | Type             | Description                    |
| -------------- | ---------------- | ------------------------------ |
| name           | string           | Name of the room               |
| topic          | string           | Topic of the room              |
| avatarUri      | Uri              | URI for room avatar            |
| invitedUserIds | string array     | IDs of users to invite         |
| preset         | CreateRoomPreset | Specific room privacy settings |

**CreateRoomPreset:**

| Value                          | Description                                 |
| ------------------------------ | ------------------------------------------- |
| PRESET\_PUBLIC\_CHAT           | Public room, joinable without an invitation |
| PRESET\_PRIVATE\_CHAT          | Private room, joinable by invitation only   |
| PRESET\_TRUSTED\_PRIVATE\_CHAT | Private room, intended for one-on-one chats |

**Output parameter:**

| Type   | Description | Required |
| ------ | ----------- | -------- |
| string | Room ID     | true     |

### **Join a room**

Join an existing room.

```kotlin
suspend fun joinRoom(
            roomId: String,
            reason: String? = null,
            viaServers: List<String> = emptyList()
    )
```

**Input parameter:**

| Name       | Type         | Description           | Required |
| ---------- | ------------ | --------------------- | -------- |
| roomId     | string       | Room ID               | true     |
| reason     | string       | Reason for joining    | false    |
| viaServers | string array | array of node domains | false    |

**Output parameter:**

| Type   | Description | Required |
| ------ | ----------- | -------- |
| string | Room ID     | true     |

### **Leave a room**

Leave an existing room.

```kotlin
suspend fun leaveRoom(roomId: String, reason: String? = null)
```

**Input parameter:**

| Name   | Type   | Description        | Required |
| ------ | ------ | ------------------ | -------- |
| roomId | string | Room ID            | true     |
| reason | string | Reason for leaving | false    |

**Output parameter:** None

### Create a private chat Room with a wallet address

If a room already exists, it returns the existing room ID. If no room exists, a new room is created.

```kotlin
suspend fun createDmByWalletAddress(address: String): String
```

**Input Parameter:**

| Name    | Type   | Description                  | Required |
| ------- | ------ | ---------------------------- | -------- |
| address | String | Target user's wallet address | true     |

**Output parameter:**

| Type   | Description    | Required |
| ------ | -------------- | -------- |
| String | ID of the room | true     |

### Delete a Room

This method allows the room owner to delete a room. Optional deletion reason can be provided.

```kotlin
suspend fun deleteRoom(roomId: String, reason: String? = null)
```

**Input Parameter:**

| Name   | Type   | Description         | Required |
| ------ | ------ | ------------------- | -------- |
| roomId | String | ID of the room      | True     |
| reason | String | Reason for deletion | False    |

**Output parameter:** None

### **Hide Room**

Hides a room from the room list. The room will automatically reappear when a new message is received.

```kotlin
suspend fun hideRoom(roomId: String)
```

**Input Parameter:**

| Name   | Type   | Description | Required |
| ------ | ------ | ----------- | -------- |
| roomId | string | Room ID     | true     |

**Output Parameter:** None

### **Show Room**

Makes a previously hidden room visible again.

```kotlin
suspend fun showRoom(roomId: String)
```

**Input Parameter:**

| Name   | Type   | Description | Required |
| ------ | ------ | ----------- | -------- |
| roomId | string | Room ID     | true     |

**Output Parameter:** None

### **Get Private Chat Room**

Gets the existing private chat room with a specified user.

```kotlin
fun getExistingDirectRoomWithUser(otherUserId: String): String?
```

**Input Parameter:**

| Name        | Type   | Description          | Required |
| ----------- | ------ | -------------------- | -------- |
| otherUserId | string | Private chat user ID | true     |

**Output Parameter:**

| Type   | Description          | Required |
| ------ | -------------------- | -------- |
| string | Private chat room ID | false    |

***

## RoomPushRuleService API

Get RoomPushRuleService object via Room object

```kotlin
val roomPushRuleService = room.roomPushRuleService()
```

### **Set Room Notification State**

Modify the notification settings for a room.

```kotlin
suspend fun setRoomNotificationState(roomNotificationState: RoomNotificationState)
```

**Input parameter:**

| Name                  | Type                  | Description        | Required |
| --------------------- | --------------------- | ------------------ | -------- |
| roomNotificationState | RoomNotificationState | Notification state | true     |

**RoomNotificationState values：**

| Value          | Description              |
| -------------- | ------------------------ |
| ALL\_MESSAGES  | Notify for all messages  |
| MENTIONS\_ONLY | Notify only for mentions |
| MUTE           | Disable notifications    |

**Output parameter:** None

### **Get room notification state**

Get the current notification state of a room.

```kotlin
fun getLiveRoomNotificationState(): LiveData<RoomNotificationState>
```

**Input parameter:** None

**Output parameter:**

| Type                  | Description        | Required |
| --------------------- | ------------------ | -------- |
| RoomNotificationState | Notification state | true     |

***

## TagService API

Get TagService object via Room object

```kotlin
val tagService = room.tagService()
```

### **Add a room tag**

Add a tag to a room with optional order.

```kotlin
suspend fun addTag(tag: String, order: Double?)
```

**Input parameter:**

| Name  | Type   | Description                                                                          | Required |
| ----- | ------ | ------------------------------------------------------------------------------------ | -------- |
| tag   | string | Name of the tag                                                                      | true     |
| order | double | Room Position, assigned a value from 0 to 1; lower values indicates higher priority. | false    |

**Output parameter:** None

### **Delete a Tag**

Remove a tag from a room.

```kotlin
suspend fun deleteTag(tag: String)
```

**Input parameter:**

| Name | Type   | Description     | Required |
| ---- | ------ | --------------- | -------- |
| tag  | string | Name of the tag | true     |

**Output parameter:** None

***

## SendService API

Get SendService object via room object

```kotlin
val sendService = room.sendService()
```

### **Send a text message**

Send a text message to a room.

```kotlin
    fun sendTextMessage(
            text: CharSequence,
            msgType: String = MessageType.MSGTYPE_TEXT,
            autoMarkdown: Boolean = false,
            additionalContent: Content? = null,
    ): Cancelable
```

**Input parameter:**

| Name              | Type    | Description                                  | Required |
| ----------------- | ------- | -------------------------------------------- | -------- |
| text              | string  | The content of the message                   | true     |
| msgType           | string  | The type of message, default is text         | true     |
| autoMarkdown      | boolean | Enable Markdown formatting, default is false | true     |
| additionalContent | Content | Additional message content                   | false    |

**Output parameter:**

| Type       | Description         | Required |
| ---------- | ------------------- | -------- |
| Cancelable | A cancelable object | true     |

### **Send media file**

Send a media file to a room.

```kotlin
    fun sendMedia(
            attachment: ContentAttachmentData,
            compressBeforeSending: Boolean,
            roomIds: Set<String>,
            rootThreadEventId: String? = null,
            relatesTo: RelationDefaultContent? = null,
            additionalContent: Content? = null,
    ): Cancelable
```

**Input parameter:**

<table><thead><tr><th>Name</th><th width="100">Type</th><th width="341">Description</th><th>Required</th></tr></thead><tbody><tr><td>attachment</td><td>String</td><td>the media to send</td><td>true</td></tr><tr><td>compressBeforeSending</td><td>String</td><td>set to true to compress images before sending them</td><td>True</td></tr><tr><td>roomIds</td><td>String</td><td>set of roomIds to where the media will be sent. The current roomId will be add to this set if not present.</td><td>True</td></tr><tr><td>rootThreadEventId</td><td>String</td><td>when this param is not null, the Media will be sent in this specific thread</td><td>True</td></tr><tr><td>relatesTo</td><td>String</td><td>add a relation content to the media event</td><td>True</td></tr><tr><td>additionalContent</td><td>String</td><td>additional content to put in the event content</td><td>True</td></tr></tbody></table>

**Output parameter:**

| Type       | Description         | Required |
| ---------- | ------------------- | -------- |
| Cancelable | A cancelable object | true     |

***

## LocationSharingService API

Get LocationSharingService object via Room object

```kotlin
val locationSharingService = room.locationSharingService()
```

### **Send static location message**

Share a static location in a room.

```kotlin
suspend fun sendStaticLocation(latitude: Double, longitude: Double, uncertainty: Double?, isUserLocation: Boolean): Cancelable
```

**Input parameter:**

| Name           | Type    | Description                                                          | Required |
| -------------- | ------- | -------------------------------------------------------------------- | -------- |
| latitude       | double  | Latitude coordinate                                                  | true     |
| longitude      | double  | Longitude coordinate                                                 | true     |
| uncertainty    | double  | Location accuracy in meters                                          | false    |
| isUserLocation | boolean | Indicates if the location is the user's current or a pinned location | true     |

**Output parameter:**

| Type       | Description         | Required |
| ---------- | ------------------- | -------- |
| Cancelable | A cancelable object | true     |

### **Send live location message**

Share a live location update in a room.

```kotlin
suspend fun sendLiveLocation(beaconInfoEventId: String, latitude: Double, longitude: Double, uncertainty: Double?): Cancelable
```

**Input parameter:**

| Name              | Type   | Description                                     | Required |
| ----------------- | ------ | ----------------------------------------------- | -------- |
| beaconInfoEventId | string | Event ID of the initial beacon info state event | true     |
| latitude          | double | Latitude coordinate                             | true     |
| longitude         | double | Longitude coordinate                            | true     |
| uncertainty       | double | Location accuracy in meters                     | false    |

**Output parameter:**

| Type       | Description         | Required |
| ---------- | ------------------- | -------- |
| Cancelable | A cancelable object | true     |