MAmatrix
Room creation

Create a new room

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:

Presetjoin_ruleshistory_visibilityguest_accessOther
private_chatinvitesharedcan_join
trusted_private_chatinvitesharedcan_joinAll invitees are given the same power level as the room creator.
public_chatpublicsharedforbidden

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.

post/_matrix/client/v3/createRoom

Request

Request body

creation_contentobject

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.

invitestring[]

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.

is_directboolean

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.

namestring

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.

power_level_content_overrideobject

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'private_chat' | 'public_chat' | 'trusted_private_chat'

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.

room_alias_namestring

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.

room_versionstring

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.

topicstring

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'public' | 'private'

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

Example request

{
  "creation_content": {
    "m.federate": false
  },
  "name": "The Grand Duke Pub",
  "preset": "public_chat",
  "room_alias_name": "thepub",
  "topic": "All about happy hour"
}

Response

Information about the newly created room.

room_idstring mx-room-id required

The created room's ID.

Changes

No recorded changes to this operation across all 1 revision of this API.