createRoom method

Future<String> createRoom({ Map<String, Object?>? creationContent, List<StateEvent>? initialState, List<String>? invite, List<Invite3pid>? invite3pid, bool? isDirect, String? name, Map<String, Object?>? powerLevelContentOverride, CreateRoomPreset? preset, String? roomAliasName, String? roomVersion, String? topic, Visibility? visibility, })

Create a new room with various configuration options.

The server MUST apply the normal state resolution rules when creating the new room, including checking power levels for each event. It MUST apply the events implied by the request in the following order:

1. The m.room.create event itself. Must be the first event in the room.

2. An m.room.member event for the creator to join the room. This is needed so the remaining events can be sent.

3. A default m.room.power_levels event, giving the room creator (and not other members) permission to send state events. Overridden by the power_level_content_override parameter.

4. An m.room.canonical_alias event if room_alias_name is given.

5. Events set by the preset. Currently these are the m.room.join_rules, m.room.history_visibility, and m.room.guest_access state events.

6. Events listed in initial_state, in the order that they are listed.

7. Events implied by name and topic (m.room.name and m.room.topic state events).

8. Invite events implied by invite and invite_3pid (m.room.member with membership: invite and m.room.third_party_invite).

The available presets do the following with respect to room state:

Preset	join_rules	history_visibility	guest_access	Other
private_chat	invite	shared	can_join
trusted_private_chat	invite	shared	can_join	All invitees are given the same power level as the room creator.
public_chat	public	shared	forbidden

The server will create a m.room.create event in the room with the requesting user as the creator, alongside other keys provided in the creation_content.

creationContent Extra keys, such as m.federate, to be added to the content of the m.room.create event. The server will overwrite the following keys: creator, room_version. Future versions of the specification may allow the server to overwrite other keys.

initialState A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set.

Takes precedence over events set by preset, but gets overridden by name and topic keys.

invite A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room.

invite3pid A list of objects representing third-party IDs to invite into the room.

isDirect This flag makes the server set the is_direct flag on the m.room.member events sent to the users in invite and invite_3pid. See Direct Messaging for more information.

name If this is included, an m.room.name event will be sent into the room to indicate the name of the room. See Room Events for more information on m.room.name.

powerLevelContentOverride The power level content to override in the default power level event. This object is applied on top of the generated m.room.power_levels event content prior to it being sent to the room. Defaults to overriding nothing.

preset Convenience parameter for setting various default state events based on a preset.

If unspecified, the server should use the visibility to determine which preset to use. A visibility of public equates to a preset of public_chat and private visibility equates to a preset of private_chat.

roomAliasName The desired room alias local part. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the same homeserver which created the room. For example, if this was set to "foo" and sent to the homeserver "example.com" the complete room alias would be #foo:example.com.

The complete room alias will become the canonical alias for the room and an m.room.canonical_alias event will be sent into the room.

roomVersion The room version to set for the room. If not provided, the homeserver is to use its configured default. If provided, the homeserver will return a 400 error with the errcode M_UNSUPPORTED_ROOM_VERSION if it does not support the room version.

topic If this is included, an m.room.topic event will be sent into the room to indicate the topic for the room. See Room Events for more information on m.room.topic.

visibility A public visibility indicates that the room will be shown in the published room list. A private visibility will hide the room from the published room list. Rooms default to private visibility if this key is not included. NB: This should not be confused with join_rules which also uses the word public.

returns room_id: The created room's ID.

Implementation

Future<String> createRoom({
  Map<String, Object?>? creationContent,
  List<StateEvent>? initialState,
  List<String>? invite,
  List<Invite3pid>? invite3pid,
  bool? isDirect,
  String? name,
  Map<String, Object?>? powerLevelContentOverride,
  CreateRoomPreset? preset,
  String? roomAliasName,
  String? roomVersion,
  String? topic,
  Visibility? visibility,
}) async {
  final requestUri = Uri(path: '_matrix/client/v3/createRoom');
  final request = Request('POST', baseUri!.resolveUri(requestUri));
  request.headers['authorization'] = 'Bearer ${bearerToken!}';
  request.headers['content-type'] = 'application/json';
  request.bodyBytes = utf8.encode(
    jsonEncode({
      if (creationContent != null) 'creation_content': creationContent,
      if (initialState != null)
        'initial_state': initialState.map((v) => v.toJson()).toList(),
      if (invite != null) 'invite': invite.map((v) => v).toList(),
      if (invite3pid != null)
        'invite_3pid': invite3pid.map((v) => v.toJson()).toList(),
      if (isDirect != null) 'is_direct': isDirect,
      if (name != null) 'name': name,
      if (powerLevelContentOverride != null)
        'power_level_content_override': powerLevelContentOverride,
      if (preset != null) 'preset': preset.name,
      if (roomAliasName != null) 'room_alias_name': roomAliasName,
      if (roomVersion != null) 'room_version': roomVersion,
      if (topic != null) 'topic': topic,
      if (visibility != null) 'visibility': visibility.name,
    }),
  );
  final response = await httpClient.send(request);
  final responseBody = await response.stream.toBytes();
  if (response.statusCode != 200) unexpectedResponse(response, responseBody);
  final responseString = utf8.decode(responseBody);
  final json = jsonDecode(responseString);
  return json['room_id'] as String;
}