{"id":13624651,"url":"https://github.com/matrix-hacks/matrix-puppet-facebook","last_synced_at":"2026-01-16T19:23:12.549Z","repository":{"id":79169900,"uuid":"77879861","full_name":"matrix-hacks/matrix-puppet-facebook","owner":"matrix-hacks","description":"a puppetted facebook bridge","archived":false,"fork":false,"pushed_at":"2020-06-22T10:10:13.000Z","size":141,"stargazers_count":97,"open_issues_count":25,"forks_count":19,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-12-22T21:47:04.076Z","etag":null,"topics":["bridge","facebook","matrix"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-hacks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-03T03:12:06.000Z","updated_at":"2024-12-16T22:29:58.000Z","dependencies_parsed_at":"2023-05-20T06:15:50.324Z","dependency_job_id":null,"html_url":"https://github.com/matrix-hacks/matrix-puppet-facebook","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/matrix-hacks/matrix-puppet-facebook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-facebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-facebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-facebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-facebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-hacks","download_url":"https://codeload.github.com/matrix-hacks/matrix-puppet-facebook/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-hacks%2Fmatrix-puppet-facebook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28481680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["bridge","facebook","matrix"],"created_at":"2024-08-01T21:01:44.645Z","updated_at":"2026-01-16T19:23:12.518Z","avatar_url":"https://github.com/matrix-hacks.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Bridges"],"sub_categories":["Facebook"],"readme":"# matrix-puppet-facebook [![#matrix-puppet-bridge:matrix.org](https://img.shields.io/matrix/matrix-puppet-bridge:matrix.org.svg?label=%23matrix-puppet-bridge%3Amatrix.org\u0026logo=matrix\u0026server_fqdn=matrix.org)](https://matrix.to/#/#matrix-puppet-bridge:matrix.org)\n\nThis is a [puppetted Matrix bridge](https://github.com/matrix-hacks/matrix-puppet-bridge) for Facebook.\n\n## Features and limitations\n* The bridge lets you use a personal matrix homeserver, the bridge itself, and your matrix client as a Facebook messenger (chat) client. What your matrix user says is said by your facebook user, and what other facebook users say is said by \"ghost\" users in Matrix that represent them.\n* Only chat is bridged, not groups, pages or events.\nTo use the bridge, just wait until you receive a message from another facebook user, on facebook. The bridge, if it's properly configured, will create a room and a ghost user and that user acts as the other user, so you'll talk to them as if they were matrix users and they talk to your facebook user.\n* You can't initiate direct-messages.\n* History is not downloaded.\n* \"Facebook Protocol\" room it is created to show errors, and avalible facebook users.\n* Avatars for facebook users is download.\n\n## prerequisites\n\n- node.js: [nodejs.org: Installing Node.js via package manager](https://nodejs.org/en/download/package-manager/)\n- git\n- ffmpeg (optionnal: if not installed videos will only be shown as regular files on matrix client =\u003e no video preview)\n\n## installation\n\n```\ngit clone https://github.com/matrix-hacks/matrix-puppet-facebook\ncd matrix-puppet-facebook\nnpm install\n```\n\n## configure\n\nCreate and update config.json to match your setup:\n\n```\ncp config.sample.json ./config.json\nnano ./config.json\n```\n\n### login to facebook\n\n```\nnode login.js\n```\nThis prompts you for your Facebook username/password, logs in, and creates an appstate.json containing your login token. It will also prompt you about login approvals (i.e. 2FA) if you have them enabled on your Facebook account. Note this script may output some errors, but as long as appstate.json is written and works properly once you run the bridge, you can ignore them.\n\n### register the app service\n\nThis will generate a `facebook-registration.yaml` file: \n\n```\nnode index.js -r -u \"http://your-bridge-server:8090\"\n```\n\nNote: The 'registration' setting in the config.json needs to set to the path of this file. By default, it already is.\n\nMake sure that from the perspective of the homeserver, the url is correctly pointing to your bridge server. e.g. `url: 'http://your-bridge-server.example.org:8090'` and is reachable. If you use reverse proxy, you can use \"http://localhost:8090\".\n\nCopy this `facebook-registration.yaml` file to your home server:\n\n```\ncp facebook-registration.yaml /etc/matrix-synapse/\n```\n\nEdit your homeserver.yaml file and update the `app_service_config_files` with the path to the `facebook-registration.yaml` file:\n\n```\nnano /etc/matrix-synapse/homeserver.yaml\n```\n\nIt should look like this: \n\n```\napp_service_config_files: [\"/etc/matrix-synapse/facebook-registration.yaml\"]\n```\n\n## run the bridge\n\nIf you plan to run this program as a service, you can continue at the next section.\n\nLaunch the bridge with ```./start.sh``` (see \\* below for more details on this). This is a bash script, so it only works on linux / osx. If you're on windows, you'll need to take a look at the script and make an equivalent batch file. It should be very simple.\n\nRestart your Homeserver.\n\n## run as a service\n\nIf you use systemd you can run the bridge as a service, so it will start automatically on system boot.\n\nFirst edit the paths in the unit file:\n\n```\nnano matrix-puppet-facebook.service\n```\n\nMake sure the matrix-synapse user has write permissions to this directory.\n\nAfter editing enable the service: \n\n```\ncp ./matrix-puppet-facebook.service /etc/systemd/system\nsystemctl daemon-reload\nsystemctl enable matrix-puppet-facebook.service\nsystemctl start matrix-puppet-facebook.service\n```\n\nRestart your homeserver:\n\n```\nsystemctl restart matrix-synapse.service\n```\n\n## run in docker\n\nYou can also use the bridge with docker. Proceed with steps normally but instead of running script or service, compile the docker image:\n\n```\ndocker build -t matrix-puppet-facebook .\n```\n\nOf course you need working docker on your system.\n\nAfter that you can run the container:\n\n```\ndocker run -d --restart=always -p 8090:8090 matrix-puppet-facebook\n```\n\n-d is --detach (runs in background), --restart is needed for restarting bridge container when it quits \n(it does that every few hours), -p binds port 8090 in container to 8090 on host\n\nYou can verify that containers works by running:\n\n```\ndocker ps\n```\n\n## notes\n\n\\* Just to explain the reason for `start.sh`, facebook-chat-api contains a bug - https://github.com/Schmavery/facebook-chat-api/issues/555 that necessitates reconnecting to facebook periodically, otherwise message sending will start to fail after a couple of days. `start.sh` ensures that the process restarts properly any time it dies.\n\n### Error that can be ignored:\n * `Unable to load crypto module: crypto will be disabled: Error: global.Olm is not defined` is not needed. `matrix-js-sdk` internally, it will always warn if OLM is present or not, and unfortunately we can't tell it to not burp out that warning.\n\n## Discussion, Help and Support\n\nJoin us in the [![Matrix Puppet Bridge](https://user-images.githubusercontent.com/13843293/52007839-4b2f6580-24c7-11e9-9a6c-14d8fc0d0737.png)](https://matrix.to/#/#matrix-puppet-bridge:matrix.org) room\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-facebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-facebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-hacks%2Fmatrix-puppet-facebook/lists"}