createRoom method
- 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:
-
The
m.room.create
event itself. Must be the first event in the room. -
An
m.room.member
event for the creator to join the room. This is needed so the remaining events can be sent. -
A default
m.room.power_levels
event. Overridden by thepower_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 ofm.room.power_levels
, so is not listed explicitly.Note: For
trusted_private_chat
, the users specified in theinvite
parameter SHOULD also be appended toadditional_creators
by the server, per thecreation_content
parameter.If the room's version is 12 or higher, the power level for sending
m.room.tombstone
events MUST explicitly be higher thanstate_default
. For example, set to 150 instead of 100. -
An
m.room.canonical_alias
event ifroom_alias_name
is given. -
Events set by the
preset
. Currently these are them.room.join_rules
,m.room.history_visibility
, andm.room.guest_access
state events. -
Events listed in
initial_state
, in the order that they are listed. -
Events implied by
name
andtopic
(m.room.name
andm.room.topic
state events). -
Invite events implied by
invite
andinvite_3pid
(m.room.member
withmembership: invite
andm.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;
}