aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md51
1 files changed, 32 insertions, 19 deletions
diff --git a/README.md b/README.md
index 92bb76f..d87e403 100644
--- a/README.md
+++ b/README.md
@@ -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:
```