= How to set up Matrix with purple-matrix =

{{{#!wiki caution
Note that as of [[https://github.com/matrix-org/purple-matrix/commit/a6522bb3986c332f7c3cbe3c4aa8e6945d6307ac|April 11, 2022]] purple-matrix is unmaintained and lacks [[https://github.com/matrix-org/purple-matrix/issues/18|support for end-to-end encryption]].
}}}

It is possible to communicate with matrix on bitlbee via libpurple and purple-matrix

== Building and Installing ==

=== Ubuntu packages ===

Pre-built binaries are available for Ubuntu since version 17.04 (Zesty Zapus). You should be able to install them giving the following commands in a terminal window:

{{{
$ sudo apt update
$ sudo apt install purple-matrix
}}}

=== ArchLinux package ===

There package [[https://aur.archlinux.org/packages/purple-matrix-git|purple-matrix-git]] is available for Archlinux in AUR. 
The package works with [[https://aur.archlinux.org/packages/bitlbee-libpurple-git|bitlbee-libpurple-git]] and perhaps [[https://aur.archlinux.org/packages/bitlbee-libpurple|bitlbee-libpurple]] too.


=== OpenBSD package ===

A package is available in ports, however, make sure you have installed the bitlbee-libpurple flavor first. To install, enter in a terminal:

{{{
# pkg_add purple-matrix
}}}

=== Building from source ===

Building the plugin from source you will need development headers/libraries for the following:

    libpurple 2.x [libpurple-dev]
    libjson-glib [libjson-glib-dev]
    libglib [libglib-dev (or libglib2.0-dev on Ubuntu 16.04 xenial)]
    libhttp_parser [libhttp-parser-dev].

You should then be able to:

{{{
$ git clone https://github.com/matrix-org/purple-matrix.git
$ cd purple-matrix
$ make
$ sudo make install
}}}


== Usage ==

Add the account with:
{{{
> account add matrix <user_id or user localpart> <password>
> account matrix set home_server <home_server>
> account matrix on
}}}

Example:
{{{
> account add matrix @username:example.com password
> account matrix set home_server https://matrix.example.com/
> account matrix on
}}}


== Known Issues ==

=== No support for encryption ===

No support for encrypted messages. '''Chat messages are always sent unencrypted. Incoming encrypted messages are silently dropped!''' See Github issue [[https://github.com/matrix-org/purple-matrix/issues/18|#18]].

=== Homeserver Port ===
If the homeserver you're connecting to requires a custom port, login will fail. See Github issue [[https://github.com/matrix-org/purple-matrix/issues/115|#115]]

=== Human friendly chatroom names ===
chat names in matrix-purple are identified by ID in bitlbee and not with human friendly names, see GitHub issue [[https://github.com/matrix-org/purple-matrix/issues/55|#55]]

=== No SSO Support ===
See Github issue [[https://github.com/matrix-org/purple-matrix/issues/107|#107]]
(!!!)