Room

Room wraps a Matrix room and provides high-level helpers for sending messages of every type — plain text, Markdown, notices, files, images, audio, and video. It delegates unknown attribute access to the underlying MatrixRoom from matrix-nio.

from matrix import Bot, Context

bot = Bot()

@bot.command("announce")
async def announce(ctx: Context, *, message: str):
    await ctx.room.send_markdown(f"**Announcement:** {message}")

matrix.room.Room

Room(matrix_room, client)

Represents a Matrix room and provides methods to interact with it.

Source code in matrix/room.py

def __init__(self, matrix_room: MatrixRoom, client: AsyncClient) -> None:
    self._matrix_room: MatrixRoom = matrix_room
    self._client: AsyncClient = client

matrix_room property

matrix_room

Access to underlying MatrixRoom object.

client property

client

Access to the Matrix client.

name property

name

Room display name.

room_id property

room_id

Room ID.

display_name property

display_name

Room display name (alias for name).

topic property

topic

Room topic.

member_count property

member_count

Number of members in the room.

encrypted property

encrypted

Whether the room is encrypted.

get_state_event async

get_state_event(event_type, state_key='')

Source code in matrix/room.py

async def get_state_event(
    self, event_type: str, state_key: str = ""
) -> RoomGetStateEventResponse | RoomGetStateEventError:
    return await matrix_call(
        self._client.room_get_state_event(self.room_id, event_type, state_key),
        error_message=f"Failed to get state event for room {self._matrix_room.room_id}",
    )

send async

send(content=None, *, raw=False, notice=False, file=None)

Send a message to the room.

This is a convenience method that automatically routes to the appropriate send method based on the provided arguments. Supports text messages (with optional markdown formatting) and file uploads (including images, videos, and audio).

For detailed text message examples, see Room.send_text(). For detailed file upload examples, see Room.send_file().

Example

# Send a markdown-formatted text message
await room.send("Hello **world**!")

# Send a file
file = File(path="mxc://...", filename="document.pdf", mimetype="application/pdf")
await room.send(file=file)

# Send an image
image = Image(path="mxc://...", filename="photo.jpg", mimetype="image/jpeg", width=800, height=600)
await room.send(file=image)

Source code in matrix/room.py

async def send(
    self,
    content: str | None = None,
    *,
    raw: bool = False,
    notice: bool = False,
    file: File | None = None,
) -> Message:
    """Send a message to the room.

    This is a convenience method that automatically routes to the appropriate
    send method based on the provided arguments. Supports text messages (with
    optional markdown formatting) and file uploads (including images, videos, and audio).

    For detailed text message examples, see `Room.send_text()`.
    For detailed file upload examples, see `Room.send_file()`.

    ## Example

    ```python
    # Send a markdown-formatted text message
    await room.send("Hello **world**!")

    # Send a file
    file = File(path="mxc://...", filename="document.pdf", mimetype="application/pdf")
    await room.send(file=file)

    # Send an image
    image = Image(path="mxc://...", filename="photo.jpg", mimetype="image/jpeg", width=800, height=600)
    await room.send(file=image)
    ```
    """
    if content:
        return await self.send_text(content, raw=raw, notice=notice)

    if file:
        return await self.send_file(file)
    raise ValueError("You must provide content or file.")

send_text async

send_text(content, *, raw=False, notice=False, reply_to=None)

Send a text message to the room.

By default, messages are formatted using Markdown. You can send raw unformatted
text with `raw=True`, or send a notice message (typically used for bot status
updates) with `notice=True`. Use `reply_to` to create a threaded reply.

Example

# Send markdown-formatted message
await room.send_text("**Bold** and *italic* text")

# Send raw text without formatting
await room.send_text("This is plain text", raw=True)

# Send a notice message
await room.send_text("Bot restarted successfully", notice=True)

# Reply to another message
await room.send_text("Replying to you!", reply_to="$event_id")

Source code in matrix/room.py

async def send_text(
    self,
    content: str,
    *,
    raw: bool = False,
    notice: bool = False,
    reply_to: str | None = None,
) -> Message:
    """Send a text message to the room.

        By default, messages are formatted using Markdown. You can send raw unformatted
        text with `raw=True`, or send a notice message (typically used for bot status
        updates) with `notice=True`. Use `reply_to` to create a threaded reply.

    ## Example

    ```python
    # Send markdown-formatted message
    await room.send_text("**Bold** and *italic* text")

    # Send raw text without formatting
    await room.send_text("This is plain text", raw=True)

    # Send a notice message
    await room.send_text("Bot restarted successfully", notice=True)

    # Reply to another message
    await room.send_text("Replying to you!", reply_to="$event_id")
    ```
    """
    payload: TextContent

    if reply_to:
        payload = ReplyContent(content, reply_to_event_id=reply_to)
    elif notice:
        payload = NoticeContent(content)
    elif raw:
        payload = TextContent(content)
    else:
        payload = MarkdownMessage(content)

    return await self._send_payload(payload)

send_file async

send_file(file)

Send a file, image, video, or audio to the room.

Accepts any File object or its subclasses (Image, Video, Audio). The file must be uploaded to the Matrix content repository before sending. Use the room's client upload method to get the MXC URI.

The method automatically detects the file type and sends it with the appropriate Matrix message type (m.file, m.image, m.video, or m.audio).

For more information on the upload method, see the matrix-nio documentation: https://matrix-nio.readthedocs.io/en/latest/nio.html#nio.AsyncClient.upload

Example

import os

# Send a document
file_path = "document.pdf"
file_size = os.path.getsize(file_path)

with open(file_path, "rb") as f:
    resp, _ = await room.client.upload(
        f,
        content_type="application/pdf",
        filesize=file_size
    )

file = File(
    path=resp.content_uri,
    filename="document.pdf",
    mimetype="application/pdf"
)
await room.send_file(file)

# Send an image
from PIL import Image as PILImage

image_path = "photo.jpg"

with PILImage.open(image_path) as img:
    width, height = img.size

file_size = os.path.getsize(image_path)

with open(image_path, "rb") as f:
    resp, _ = await room.client.upload(
        f,
        content_type="image/jpeg",
        filesize=file_size
    )

image = Image(
    path=resp.content_uri,
    filename="photo.jpg",
    mimetype="image/jpeg",
    width=width,
    height=height
)
await room.send_file(image)

# Send a video
import cv2

video_path = "video.mp4"

cap = cv2.VideoCapture(video_path)
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
fps = cap.get(cv2.CAP_PROP_FPS)
frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
duration = int((frame_count / fps) * 1000)
cap.release()

file_size = os.path.getsize(video_path)

with open(video_path, "rb") as f:
    resp, _ = await room.client.upload(
        f,
        content_type="video/mp4",
        filesize=file_size
    )

video = Video(
    path=resp.content_uri,
    filename="video.mp4",
    mimetype="video/mp4",
    width=width,
    height=height,
    duration=duration
)
await room.send_file(video)

# Send audio
audio_path = "audio.mp3"
file_size = os.path.getsize(audio_path)

with open(audio_path, "rb") as f:
    resp, _ = await room.client.upload(
        f,
        content_type="audio/mpeg",
        filesize=file_size
    )

audio = Audio(
    path=resp.content_uri,
    filename="audio.mp3",
    mimetype="audio/mpeg",
    duration=180000  # 3 minutes in milliseconds
)
await room.send_file(audio)

Source code in matrix/room.py

async def send_file(self, file: File) -> Message:
    """Send a file, image, video, or audio to the room.

    Accepts any File object or its subclasses (Image, Video, Audio). The file must
    be uploaded to the Matrix content repository before sending. Use the room's
    client upload method to get the MXC URI.

    The method automatically detects the file type and sends it with the appropriate
    Matrix message type (m.file, m.image, m.video, or m.audio).

    For more information on the upload method, see the matrix-nio documentation:
    https://matrix-nio.readthedocs.io/en/latest/nio.html#nio.AsyncClient.upload

    ## Example

    ```python
    import os

    # Send a document
    file_path = "document.pdf"
    file_size = os.path.getsize(file_path)

    with open(file_path, "rb") as f:
        resp, _ = await room.client.upload(
            f,
            content_type="application/pdf",
            filesize=file_size
        )

    file = File(
        path=resp.content_uri,
        filename="document.pdf",
        mimetype="application/pdf"
    )
    await room.send_file(file)

    # Send an image
    from PIL import Image as PILImage

    image_path = "photo.jpg"

    with PILImage.open(image_path) as img:
        width, height = img.size

    file_size = os.path.getsize(image_path)

    with open(image_path, "rb") as f:
        resp, _ = await room.client.upload(
            f,
            content_type="image/jpeg",
            filesize=file_size
        )

    image = Image(
        path=resp.content_uri,
        filename="photo.jpg",
        mimetype="image/jpeg",
        width=width,
        height=height
    )
    await room.send_file(image)

    # Send a video
    import cv2

    video_path = "video.mp4"

    cap = cv2.VideoCapture(video_path)
    width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
    height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
    fps = cap.get(cv2.CAP_PROP_FPS)
    frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
    duration = int((frame_count / fps) * 1000)
    cap.release()

    file_size = os.path.getsize(video_path)

    with open(video_path, "rb") as f:
        resp, _ = await room.client.upload(
            f,
            content_type="video/mp4",
            filesize=file_size
        )

    video = Video(
        path=resp.content_uri,
        filename="video.mp4",
        mimetype="video/mp4",
        width=width,
        height=height,
        duration=duration
    )
    await room.send_file(video)

    # Send audio
    audio_path = "audio.mp3"
    file_size = os.path.getsize(audio_path)

    with open(audio_path, "rb") as f:
        resp, _ = await room.client.upload(
            f,
            content_type="audio/mpeg",
            filesize=file_size
        )

    audio = Audio(
        path=resp.content_uri,
        filename="audio.mp3",
        mimetype="audio/mpeg",
        duration=180000  # 3 minutes in milliseconds
    )
    await room.send_file(audio)
    ```
    """
    payload: FileContent

    match file:
        case Image():
            payload = ImageContent(
                filename=file.filename,
                url=file.path,
                mimetype=file.mimetype,
                height=file.height,
                width=file.width,
            )
        case Audio():
            payload = AudioContent(
                filename=file.filename,
                url=file.path,
                mimetype=file.mimetype,
                duration=file.duration,
            )
        case Video():
            payload = VideoContent(
                filename=file.filename,
                url=file.path,
                mimetype=file.mimetype,
                height=file.height,
                width=file.width,
                duration=file.duration,
            )
        case _:
            payload = FileContent(
                filename=file.filename, url=file.path, mimetype=file.mimetype
            )

    return await self._send_payload(payload)

fetch_event async

fetch_event(event_id)

Fetch a Matrix event by its ID.

Example

    event = await room.fetch_event("$event_id:matrix.org")
    print(event.sender)

Source code in matrix/room.py

async def fetch_event(self, event_id: str) -> Event:
    """Fetch a Matrix event by its ID.

    ## Example
    ```python
        event = await room.fetch_event("$event_id:matrix.org")
        print(event.sender)
    ```
    """
    response = await matrix_call(
        self.client.room_get_event(room_id=self.room_id, event_id=event_id),
        error_message="Failed to get event",
    )
    return response.event

fetch_message async

fetch_message(event_id)

Fetch a Message by its event ID.

Example

    message = await room.fetch_message("$event_id:matrix.org")
    message.reply("hello world")

Source code in matrix/room.py

async def fetch_message(self, event_id: str) -> Message:
    """Fetch a Message by its event ID.

    ## Example
    ```python
        message = await room.fetch_message("$event_id:matrix.org")
        message.reply("hello world")
    ```
    """
    event = await self.fetch_event(event_id)
    return Message(
        room=self,
        event=event,
        client=self.client,
    )

mark_as_read async

mark_as_read(event_id)

Send a read receipt for the given event.

Signals to other clients that the bot has read up to this event. Useful for bots that process messages silently without sending a reply.

Example

@bot.event
async def on_message(room: Room, event: Event):
    await room.mark_as_read(event.event_id)

Source code in matrix/room.py

async def mark_as_read(self, event_id: str) -> None:
    """Send a read receipt for the given event.

    Signals to other clients that the bot has read up to this event. Useful
    for bots that process messages silently without sending a reply.

    ## Example

    ```python
    @bot.event
    async def on_message(room: Room, event: Event):
        await room.mark_as_read(event.event_id)
    ```
    """
    await matrix_call(
        self.client.room_read_markers(
            room_id=self.room_id,
            fully_read_event=event_id,
            read_event=event_id,
        ),
        error_message="Failed to mark as read",
    )

invite_user async

invite_user(user_id)

Invite a user to the room.

The bot must have permission to invite users to the room. The user will receive an invitation that they can accept or decline.

Example

# Invite a user by their Matrix ID
await room.invite_user("@alice:example.com")

Source code in matrix/room.py

async def invite_user(self, user_id: str) -> None:
    """Invite a user to the room.

    The bot must have permission to invite users to the room. The user will
    receive an invitation that they can accept or decline.

    ## Example

    ```python
    # Invite a user by their Matrix ID
    await room.invite_user("@alice:example.com")
    ```
    """
    await matrix_call(
        self.client.room_invite(room_id=self.room_id, user_id=user_id),
        error_message="Failed to invite user",
    )

ban_user async

ban_user(user_id, reason=None)

Ban a user from the room.

The bot must have permission to ban users. Banned users cannot rejoin the room until they are unbanned. Optionally provide a reason for the ban.

Example

# Ban a user without a reason
await room.ban_user("@spammer:example.com")

# Ban a user with a reason
await room.ban_user("@spammer:example.com", reason="Spam and harassment")

Source code in matrix/room.py

async def ban_user(self, user_id: str, reason: str | None = None) -> None:
    """Ban a user from the room.

    The bot must have permission to ban users. Banned users cannot rejoin
    the room until they are unbanned. Optionally provide a reason for the ban.

    ## Example

    ```python
    # Ban a user without a reason
    await room.ban_user("@spammer:example.com")

    # Ban a user with a reason
    await room.ban_user("@spammer:example.com", reason="Spam and harassment")
    ```
    """
    await matrix_call(
        self.client.room_ban(room_id=self.room_id, user_id=user_id, reason=reason),
        error_message="Failed to ban user",
    )

unban_user async

unban_user(user_id)

Unban a user from the room.

The bot must have permission to unban users. This removes the ban, allowing the user to rejoin the room if invited or if the room is public.

Example

# Unban a previously banned user
await room.unban_user("@alice:example.com")

Source code in matrix/room.py

async def unban_user(self, user_id: str) -> None:
    """Unban a user from the room.

    The bot must have permission to unban users. This removes the ban,
    allowing the user to rejoin the room if invited or if the room is public.

    ## Example

    ```python
    # Unban a previously banned user
    await room.unban_user("@alice:example.com")
    ```
    """
    await matrix_call(
        self.client.room_unban(room_id=self.room_id, user_id=user_id),
        error_message="Failed to unban user",
    )

kick_user async

kick_user(user_id, reason=None)

Kick a user from the room.

The bot must have permission to kick users. Unlike banning, kicked users can rejoin the room if they have an invite or if the room is public. Optionally provide a reason for the kick.

Example

# Kick a user without a reason
await room.kick_user("@troublemaker:example.com")

# Kick a user with a reason
await room.kick_user("@troublemaker:example.com", reason="Violating room rules")

Source code in matrix/room.py

async def kick_user(self, user_id: str, reason: str | None = None) -> None:
    """Kick a user from the room.

    The bot must have permission to kick users. Unlike banning, kicked users
    can rejoin the room if they have an invite or if the room is public.
    Optionally provide a reason for the kick.

    ## Example

    ```python
    # Kick a user without a reason
    await room.kick_user("@troublemaker:example.com")

    # Kick a user with a reason
    await room.kick_user("@troublemaker:example.com", reason="Violating room rules")
    ```
    """
    await matrix_call(
        self.client.room_kick(room_id=self.room_id, user_id=user_id, reason=reason),
        error_message="Failed to kick user",
    )

get_members async

get_members()

Fetch the list of user IDs currently joined to the room.

This queries the Matrix server directly for the current membership, which may include members not yet reflected in local room state.

Example

members = await room.get_members()
print(f"{len(members)} members: {', '.join(members)}")

Source code in matrix/room.py

async def get_members(self) -> list[str]:
    """Fetch the list of user IDs currently joined to the room.

    This queries the Matrix server directly for the current membership,
    which may include members not yet reflected in local room state.

    ## Example

    ```python
    members = await room.get_members()
    print(f"{len(members)} members: {', '.join(members)}")
    ```
    """
    response = await matrix_call(
        self.client.joined_members(self.room_id),
        error_message="Failed to get members",
    )
    return [member.user_id for member in response.members]