Devdocs: https://github.com/safatshahin/devdocs/compare/main...MDL-76702-matrix-docs

When the communication subsystem is enabled,there is a communication plugin successfully configured, and the admin has allowed it; display the chat options in the course wide settings page.

Settings

Some initial settings for this are:

• Enable/disable setting for creating a room for this course.
• Room name: should default to course short name but be able to be updated by the teacher.

UX input will be required to determine how a teacher can check on the status of a room being created and if there are any errors. This is still TBD.

Room creation/updating/syncing based on configuration changes in Moodle should happen via an ad hoc task. These operations should be relatively instantaneous, but we don’t want them to block.

It will need to be determined what sort of room type we create in Matrix. Matrix supports both private and public rooms. It makes sense to initially create only private rooms, as this follows the pattern where a student in one course in Moodle cannot interact with students in another course.

User stories:

1. As a teacher I want to be able to enable or disable Matrix integration for my course from the general course settings. When enabled I expect a “room” in Matrix to be created asynchronously in the “background” for my course and students in my course with active enrolments to be invited to that room. So I can control how my students communicate in my course.
2. As a teacher I want to be able to set the Matrix room name for my course in the general course settings in Moodle. With a sensible name set by default. So I can customise the experience for my students.
3. As a teacher when my course has been configured to create a Matrix room for my course, I understand that there may be a delay in the room being created on the Matrix server. So I want a visual indication that allows me to check the creation status of the chat room for my course
4. As a teacher, when I explicitly configure a Matrix chat room from my Moodle course, I don’t want to be blocked from other actions while the chat room is being created for me in the background.
5. As a Student I want the Moodle course short name included in Matrix chat room name. Unless it has been overridden by my teacher. So I know which chat in Matrix relates to which of my courses.

Room Operations

The following sections show API calls for various rooms operations. The full documentation related to these can be found here: https://spec.matrix.org/v1.5/client-server-api/#rooms-1 

Create Room

Create a new room from scratch:

curl --header "Authorization: Bearer syt_YWRtaW4_MGZMsmjMJocVcXpZbEIV_0V1eZi" \

-XPOST -d '{"name":"newroom","topic":"room made by api","visibility":"public","preset":"public_chat","room_alias_name":"newroom","initial_state":[]}' \

"http://synapse:8008/_Matrix/client/r0/createRoom"

The response is like:

We’ll need to store both the room_id and room_alias in Moodle

A further example that sets up end to end encryption for a room:

curl 'https://synapse:8008/_matrix/client/r0/createRoom' -X POST -H 'Authorization: Bearer syt_YWRtaW4_KXUwoITuowupgGEIGNuK_4MLu3S'  -d '{"name":"curl room","topic":"curly topic","preset":"private_chat","visibility":"private","initial_state":\\\\{"type":"m.room.encryption","state_key":"","content":{"algorithm":"m.megolm.v1.aes-sha2"}}}'

Documentation specific to this process is here: https://spec.matrix.org/v1.5/client-server-api/#post_matrixclientv3createroom 

Update Room

Make changes to the room's details. Most room details can only be changed one at a time. For example changing a room name and topic are two separate API calls.

Changing a room topic:

curl 'https://synapse:8008/_matrix/client/r0/rooms/!IWCtGkszxDkBUrIsGg%3Asynapse/state/m.room.topic/' -X PUT -H 'Authorization: Bearer syt_YWRtaW4_KXUwoITuowupgGEIGNuK_4MLu3S' -d '{"topic":"the topic updated"}'

Changing room name:

curl 'https://synapse:8008/_matrix/client/r0/rooms/!IWCtGkszxDkBUrIsGg%3Asynapse/state/m.room.name/' -X PUT -H 'Authorization: Bearer syt_YWRtaW4_KXUwoITuowupgGEIGNuK_4MLu3S' -d '{"name":"new room name"}'

Setting room avatar:

This is a two part process. First the image to be used as the room avatar to Synapse. Next we need to set the avatar to the location of the image.

curl 'https://synapse:8008/_matrix/media/r0/upload?filename=imagename.png' -X POST -H 'Content-Type: image/png' -H 'Authorization: Bearer syt_YWRtaW4_KXUwoITuowupgGEIGNuK_4MLu3S' -d @/location/of/image/imagename.png

This will return the location of the saved image:

Next we update the avatar:

curl 'https://synapse:8008/_matrix/client/r0/rooms/!IWCtGkszxDkBUrIsGg%3Asynapse/state/m.room.avatar/' -X PUT -H 'Authorization: Bearer syt_YWRtaW4_KXUwoITuowupgGEIGNuK_4MLu3S' -d '{"url":"mxc://synapse/ThJDXaRGnpFUdIjlUyiqVICQ"}'

All of these types of actions are known as events (https://spec.matrix.org/v1.5/client-server-api/#events ).

They will return an event id.