{"id":13716175,"url":"https://github.com/rgomez90/matrix-bot","last_synced_at":"2025-03-30T02:43:12.201Z","repository":{"id":60222264,"uuid":"541795255","full_name":"rgomez90/matrix-bot","owner":"rgomez90","description":"Simple python matrix bot based on Matrix-nio ","archived":false,"fork":false,"pushed_at":"2022-09-29T09:27:51.000Z","size":108,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-05T05:19:45.805Z","etag":null,"topics":["bot","matrix","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rgomez90.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-09-26T21:43:15.000Z","updated_at":"2023-03-08T03:02:54.000Z","dependencies_parsed_at":"2023-01-19T00:45:12.477Z","dependency_job_id":null,"html_url":"https://github.com/rgomez90/matrix-bot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgomez90%2Fmatrix-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgomez90%2Fmatrix-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgomez90%2Fmatrix-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rgomez90%2Fmatrix-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rgomez90","download_url":"https://codeload.github.com/rgomez90/matrix-bot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246269911,"owners_count":20750319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot","matrix","python"],"created_at":"2024-08-03T00:01:07.752Z","updated_at":"2025-03-30T02:43:12.185Z","avatar_url":"https://github.com/rgomez90.png","language":"Python","funding_links":[],"categories":["Libraries/Packages/Scripts"],"sub_categories":["Miscellaneous"],"readme":"# Matrix-bot\nThis is a bot for matrix based in [matrix-nio](https://github.com/poljar/matrix-nio) and [simple-matrix-bot-lib](https://github.com/i10b/simplematrixbotlib).\n\nThe bot can be changed or extended with more functionality.\n\n---\n\nAs for now the bot listens to new uploaded files and saves them to a predefined path.\n\nIf the uploaded file is a [quarto](https://quarto.org/) file with `.qmd` extension, a subprocess will be started to convert the file to PDF (via `quarto`) and post the output PDF back as a response to the message containing the source `qmd` file.\n\nOptionally, the bot can react to the source message, letting the user(s) know, if the conversion was successful or not.\n\nIf in the process an exception is thrown, the stderr of the executed command, will be posted to the channel.\n\n---\n\n## Installing\n\nThe bot installation is an easy process, but there are a few things we have to do to make it run properly.\n\nIn order to convert quarto files a valid installation of quarto and dependencies is need.\n\n### Bot Account\n\nNormally the bot will work under its own account, so first create in Matrix an account for our bot and save the credentials for later use to sign-in.\n\n### E2EE Support\n\nFor E2EE support, `python-olm` is needed, which requires the `libolm C library (version 3.x)`.\n\nFirst make sure you have 'libolm' installed.\n\nIf not installed, we need to install it. On Debian and Ubuntu one can use `apt-get` to install package `libolm-dev`. On Fedora one can use `dnf` to install package `libolm-devel`. On MacOS one can use brew to install package libolm. Make sure version 3 is installed.\n\nAfter checking `libolm` is successfully installed, we go on with the python dependencies.\n\n### Python dependencies\n\nFor the python dependencies we will make use of virtual environments and the file [requirements.txt](requirements.txt)\n\nTo install the python dependencies, first create a virtual environment\n\n```cmd\npython3 -m venv venv\n```\n\nActivate it\n```\n`./venv/bin/activate`\n```\n\nInstall dependencies\n```\npip install -r requirements.txt\n```\n\n## Configuration\nAs configuration the bot uses `config.json` which can be edited to match requirements (at least `matrix` section will be edited).\n\nThe files will be saved in a predefined folder, which can be set via `config.json` in `download_folder`.\n\n### Example config file\n\n```json\n{\n  \"command_prefix\": \"!c\",\n  \"matrix\": {\n    \"user\": \"bot\",\n    \"user_id\": \"@bot:example.com\",\n    \"password\": \"yourPassword\",\n    \"homeserver_url\": \"https://example.com\"\n  },\n  \"quarto_command\": \"quarto render\",\n  \"download_folder\": \"./downloads\",\n  \"whitelist_rooms\": [],\n  \"blacklist_rooms\": [],\n  \"reaction\": {\n    \"enabled\": \"True\",\n    \"ok_msg\": \"💚 Converted! ✅\",\n    \"error_msg\": \"❌ Error converting ❌\"\n  }\n}\n```\n\n### Settings\n\n| Setting | Description |\n|---------|-------------|\n| command-prefix | The prefix to use in messages which should be listened by the bot |\n|matrix.user| Matrix bot's username |\n|matrix.user_id| Matrix bot's userId (ex. @bot:example.com) |\n|matrix.password| Matrix bot's account password|\n|matrix.homeserver_url| Matrix Server URL|\n|download_folder| relative path from root of downloads folder |\n|blocklist_rooms| list of room-IDs to ignore for the bot |\n\n\n## Running the bot\n\nTo run the bot, first install it (see [Installation](##Installing)) and then from the root folder run `matrix-bot`\n\n### Session verification E2EE (needs an external element client web/browser)\nIn encrypted rooms in order to have access to encrypted messages and files, the bot's session has to be verified.\nA file `session.text` and a folder `crypto_store` will be created at start of the bot if not present, which will create a new (untrusted) device (so verification should be done again)\n\nTo verify a device, first run the bot a first time with correct credentials.\nAfter connecting the bot will response in the terminal with a `session-id` and a `fingerprint`\n\n**Example response**\n```\nConnected to https://example.com as @bot:example.com (GQNCMMKORY)\nThis bot's public fingerprint (\"Session key\") for one-sided verification is: jD1m e6gr WGFw ZrW9 f4mJ NqEP uFL+ ARQv JENu Dkuz aiA\n```\nThis will create an `unverified device` for the bot user, which should verified.\n\nTo verify this new device we login into a client (web/dekstop) using the bot's credentials.\n\nNow, let's check the list of verified and unverified devices. For this, go to `channel information` - `Users`\n\n![shot1](/docs/media/shot1.png)\n\nclick on the untrusted device (in this case `Bot Client using Simple-Matrix-Bot-Lib`) and click on `Manually verify by text`.\n\n![shot2](/docs/media/shot2.png)\n\nNow compare the session key from the bot terminal and the one from the client. Both should be the same. If so click in `Verify session`\n\nAfter verification the bot should be able to decrypt messages and files sent in the joined channels, as well as encrypting messages and files sent from the bot to the channel.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgomez90%2Fmatrix-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frgomez90%2Fmatrix-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frgomez90%2Fmatrix-bot/lists"}