Matrix¶
Matrix is an open standard for secure, decentralised, real-time communication. The matrix connector for opsdroid supports connecting to any matrix server and sending and receiving almost all supported events, including in end-to-end encrypted rooms.
Requirements¶
To use this connector you will need to have:
A Matrix account for the bot with a username (mxid) and password.
Know what your homeserver (matrix server URL) is.
Know the room alias (address) for the room (or rooms) you want the bot to join.
Configuration¶
A simple configuration looks like:
connectors:
matrix:
# Required
mxid: "@username:matrix.org"
password: "mypassword"
rooms:
'main': '#matrix:matrix.org'
# Optional
homeserver: "https://matrix.org"
nick: "Botty McBotface" # The nick will be set on startup
The connector can be configured with any number of rooms, each given a name. The first room should always be named “main” this room will be the one that messages will be sent to unless they are sent elsewhere.
The following code shows all the configuration options:
connectors:
matrix:
# Required
mxid: "@username:matrix.org"
password: "mypassword"
# A dictionary of rooms to connect to
# One of these have to be named 'main'
rooms:
'main': '#matrix:matrix.org'
'other': '#element-web:matrix.org'
# Optional
access_token: "the access token" # directly provide the access token, if provided mxid and password are not required, but homeserver is.
homeserver: "https://matrix.org"
nick: "Botty McBotface" # The nick will be set on startup
room_specific_nicks: False # Look up room specific nicknames of senders (expensive in large rooms)
device_name: "opsdroid"
enable_encryption: False
device_id: "opsdroid" # A unique string to use as an ID for a persistent opsdroid device
store_path: "path/to/store/" # Path to the directory where the matrix store will be saved
End to End Encryption¶
Note
mxid & password must be used for E2EE to work
To be able to use E2EE you need to have the ‘olm’ library installed, this is currently not available through pip, you can find it here, in most linux distributions or by using the opsdroid Docker images.
Note
Opsdroid >= v0.24.1 Docker image includes E2EE
Once olm is installed you need to install opsdroid with the connector_matrix_e2e
extra (by running pip install opsdroid[connector_matrix_e2e]
, this is not done by default as it required you to have already installed the olm library.
You also need to set the enable_encryption: True
configuration option to enable encryption.
The connector supports interacting with end to end encrypted rooms for which it will create a sqlite database to store the encryption keys into, where this database is kept can be configured with store_path
.
Currently there is no device verification implemented which means messages will be sent regardless of whether encrypted rooms have users with unverified devices.