createRoom method

Future<String> createRoom({
  1. Map<String, Object?>? creationContent,
  2. List<StateEvent>? initialState,
  3. List<String>? invite,
  4. List<Invite3pid>? invite3pid,
  5. bool? isDirect,
  6. String? name,
  7. Map<String, Object?>? powerLevelContentOverride,
  8. CreateRoomPreset? preset,
  9. String? roomAliasName,
  10. String? roomVersion,
  11. String? topic,
  12. 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. Overridden by the power_level_content_override parameter.

    In room versions 1 through 11, the room creator (and not other members) will be given permission to send state events.

    In room versions 12 and later, the room creator is given infinite power level and cannot be specified in the users field of m.room.power_levels, so is not listed explicitly.

    Note: For trusted_private_chat, the users specified in the invite parameter SHOULD also be appended to additional_creators by the server, per the creation_content parameter.

    If the room's version is 12 or higher, the power level for sending m.room.tombstone events MUST explicitly be higher than state_default. For example, set to 150 instead of 100.

  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 or implied by behaviour of 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.

When using the trusted_private_chat preset, the server SHOULD combine additional_creators specified here and the invite array into the eventual m.room.create event's additional_creators, deduplicating between the two parameters.

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 for the room. This overwrites any m.room.name event in initial_state.

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 with a text/plain mimetype will be sent into the room to indicate the topic for the room. This overwrites any m.room.topic event in initial_state.

visibility The room's visibility in the server's published room directory. Defaults to private.

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;
}