diff options
| -rw-r--r-- | README.md | 51 |
1 files changed, 32 insertions, 19 deletions
@@ -7,19 +7,23 @@ conversations in Matrix in a uniform view. Basically, Matrix becomes your everything chat client! **WARNING** Easybridge is still very experimental and crashes sometimes. -Also, the Facebook Messenger backend might get you rate-limited on login -attempts if you restart the bridge too often, which will lock you out of -your Facebook account asking you to recover your account and change your password. -See below for information on how to avoid this situation. + +Current backend status: + +- IRC: text messages only (private messages and public channels). Has bugs, most notably: messages will be duplicated if several users connect to the same channel. +- XMPP: text messages only (private chat and MUCs), no backlog, no avatars, no file transfer. +- Mattermost: in quite good shape. Private & group conversations with text messages and attachments (images or other files). Handles retrieving of message backlog, user avatars and room avatars from the server. +- Facebook messenger: in quite good shape, handles private messages and groups, text messages, attachments, stickers, profile pictures (low res only), backlog. Sometimes disconnects from the server and messages stop arriving. Current features: - Backends: IRC, XMPP, Mattermost, Facebook Messenger (more to come) -- Private messages and group/chat room messages +- Handles private chats (one-to-one conversations) as well as group chats (sometimes called channels, multi-user chats, or chat rooms) - Automatic setup of Matrix rooms that bridge to outside rooms - Room name and topic synchronization (partially) -- Images and file transfers (Mattermost backend) -- Avatar and room pictures (Mattermost backend, one-way only) +- Images and file transfers (Mattermost and FB Messenger backends) +- Avatar and room pictures (Mattermost backend and FB Messenger backends, one-way only) +- Retrieving old messages / missed messages when backend was disconnected (Mattermost and FB Messenger) - Web interface for setting up accounts so that new accounts can be easily added and you don't have to type your credentials in a clear-text Matrix room - Credentials are stored encrypted in the database using users' Matrix passwords @@ -28,28 +32,34 @@ There is lot to do! See the issues if you want to join us on this project. A Docker image is provided on the [Docker hub](https://hub.docker.com/r/lxpz/easybridge_amd64). -Easybridge takes a single command line argument, `-config <filename>`, which is the -path to its config file (defaults to `./config.json`). -The configuration file is a JSON file whose contents is described in the following section. - Easybridge is licensed under the terms of the GPLv3. ## Building Easybridge -Easybridge requires go 1.13 or later. +Easybridge requires go 1.13 or later. The Facebook Messenger backend requires Python 3 and the `fbchat` library (tested with v1.9.6). To build Easybridge, clone this repository outside of your `$GOPATH`. Then, run `make` in the root of the repo. -## Configuring Easybridge +## Operating Easybridge Easybridge acts as a Matrix application service: in this regard, it requires a registration file to be added to your homeserver. It uses a database to store configuration and state information, which can be any backend supported by [Gorm](https://gorm.io). +Easybridge takes a single command line argument, `-config <filename>`, which is the +path to its config file (defaults to `./config.json`). +The configuration file is a JSON file whose contents is described in the following section. + +If the config file does not exist, a template will be created. +A template appservice registration file will also be created if necessary. + + +## Configurating Easybridge + Easybridge is configured using a single JSON configuration file, which contains a dictionnary whose keys are the following: @@ -77,13 +87,16 @@ a dictionnary whose keys are the following: ## Facebook Messenger alternative login procedure -The default login proedure for the Messenger backend is to log in with your email and password each time -Easybridge starts. Unfortunately, if Easybridge restarts too often, this will get you rate limited on login -attempts quite rapidly. To bypass this issue, the Messenger backend provides the ability to login -using a *client pickle*, i.e. a serialized client that contains all of the cookies obtained during a single -initial login procedure, so that further logins are not required any longer. +The default login procedure for the Messenger backend is to log in with your email and password. +Unfortunately, if this login procedure happenned to often, you would get rate limited on login +attempts quite rapidly. +To bypass this issue, once sucessfully logged in Easybridge will store a *client pickle* in your account +configuration, i.e. a blob that contains your Facebook cookies so that the username+password procedure +doesn't need to be repeated everytime Easybridge restarts. -To use this method, **do not enter your password in Easybridge when configuring the Messenger backend**. +If the automated username+password procedure fails, the user can generate a client pickle from the +command line and use that in the configuration instead of entering a username and a password. +To use this method, **do not enter your password in Easybridge when configuring the Messenger backend (only enter your email address)**. Generate your client pickle by running the following command: ``` |