diff --git a/.github/workflows/development.yml b/.github/workflows/development.yml
index b6b4626670..e5e39701bf 100644
--- a/.github/workflows/development.yml
+++ b/.github/workflows/development.yml
@@ -1,5 +1,13 @@
name: Development
-on: [push, pull_request]
+on:
+ push:
+ paths-ignore:
+ - 'docs/**'
+ - 'README.md'
+ pull_request:
+ paths-ignore:
+ - 'docs/**'
+ - 'README.md'
jobs:
lint:
name: golangci-lint
diff --git a/README.md b/README.md
index 03298c622c..4adeb01f8e 100644
--- a/README.md
+++ b/README.md
@@ -4,357 +4,59 @@
**A simple chat bridge**
-Letting people be where they want to be.
-Bridges between a growing number of protocols. Click below to demo or join the development chat.
-
-
-
-[Discord][mb-discord] |
-[Gitter][mb-gitter] |
-[IRC][mb-irc] |
-[Keybase][mb-keybase] |
-[Matrix][mb-matrix] |
-[Mattermost][mb-mattermost] |
-[MSTeams][mb-msteams] |
-[Rocket.Chat][mb-rocketchat] |
-[Slack][mb-slack] |
-[Telegram][mb-telegram] |
-[Twitch][mb-twitch] |
-[WhatsApp][mb-whatsapp] |
-[XMPP][mb-xmpp] |
-[Zulip][mb-zulip] |
-And more...
-
+Letting people be where they want to be with the magic of [interoperability](https://en.wikipedia.org/wiki/Interoperability).
---
[](https://github.com/42wim/matterbridge/releases/latest)
-[](https://codeclimate.com/github/42wim/matterbridge/maintainability)
-[](https://codeclimate.com/github/42wim/matterbridge/test_coverage)
-
-
-
-
-
-**Note:** Mattermost isn't required to run matterbridge.
-
-
- 
-
-
+---
-# Table of Contents
+
-- [matterbridge](#matterbridge)
-- [Table of Contents](#table-of-contents)
- - [Features](#features)
- - [Natively supported](#natively-supported)
- - [3rd party via matterbridge api](#3rd-party-via-matterbridge-api)
- - [API](#api)
- - [Chat with us](#chat-with-us)
- - [Screenshots](#screenshots)
- - [Installing / upgrading](#installing--upgrading)
- - [Binaries](#binaries)
- - [Packages](#packages)
- - [Building](#building)
- - [Building with whatsapp (beta) multidevice support](#building-with-whatsapp-beta-multidevice-support)
- - [Configuration](#configuration)
- - [Basic configuration](#basic-configuration)
- - [Settings](#settings)
- - [Advanced configuration](#advanced-configuration)
- - [Examples](#examples)
- - [Bridge mattermost (off-topic) - irc (#testing)](#bridge-mattermost-off-topic---irc-testing)
- - [Bridge slack (#general) - discord (general)](#bridge-slack-general---discord-general)
- - [Running](#running)
- - [Docker](#docker)
- - [Systemd](#systemd)
- - [Changelog](#changelog)
- - [FAQ](#faq)
- - [Related projects](#related-projects)
- - [Articles / Tutorials](#articles--tutorials)
- - [Thanks](#thanks)
+matterbridge is a solution to connect users on different platforms/protocols, allowing them to chat in the best conditions possible. Despite the name, Mattermost isn't required to run matterbridge.
## Features
-- [Support bridging between any protocols](https://github.com/42wim/matterbridge/wiki/Features#support-bridging-between-any-protocols)
-- [Support multiple gateways(bridges) for your protocols](https://github.com/42wim/matterbridge/wiki/Features#support-multiple-gatewaysbridges-for-your-protocols)
-- [Message edits and deletes](https://github.com/42wim/matterbridge/wiki/Features#message-edits-and-deletes)
-- Preserves threading when possible
-- [Attachment / files handling](https://github.com/42wim/matterbridge/wiki/Features#attachment--files-handling)
-- [Username and avatar spoofing](https://github.com/42wim/matterbridge/wiki/Features#username-and-avatar-spoofing)
-- [Private groups](https://github.com/42wim/matterbridge/wiki/Features#private-groups)
-- [API](https://github.com/42wim/matterbridge/wiki/Features#api)
-
-### Natively supported
-
-- [Discord](https://discordapp.com)
-- [Gitter](https://gitter.im)
-- [Harmony](https://harmonyapp.io)
-- [IRC](http://www.mirc.com/servers.html)
-- [Keybase](https://keybase.io)
-- [Matrix](https://matrix.org)
-- [Mattermost](https://github.com/mattermost/mattermost-server/)
-- [Microsoft Teams](https://teams.microsoft.com)
-- [Mumble](https://www.mumble.info/)
-- [Nextcloud Talk](https://nextcloud.com/talk/)
-- [Rocket.chat](https://rocket.chat)
-- [Slack](https://slack.com)
-- [Ssh-chat](https://github.com/shazow/ssh-chat)
-- ~~[Steam](https://store.steampowered.com/)~~
- - Not supported anymore, see [here](https://github.com/Philipp15b/go-steam/issues/94) for more info.
-- [Telegram](https://telegram.org)
-- [Twitch](https://twitch.tv)
-- [VK](https://vk.com/)
-- [WhatsApp](https://www.whatsapp.com/)
- - Whatsapp legacy is natively supported
- - Whatsapp multidevice beta is natively supported but you need to build yourself, see [here](#building-with-whatsapp-beta-multidevice-support)
-- [XMPP](https://xmpp.org)
-- [Zulip](https://zulipchat.com)
-
-### 3rd party via matterbridge api
-
-- [Delta Chat](https://github.com/deltachat-bot/matterdelta)
-- [Minecraft](https://github.com/raws/mattercraft)
-- [Minecraft](https://gitlab.com/Programie/MatterBukkit)
-
-#### Past 3rd party projects
-- [Discourse](https://github.com/DeclanHoare/matterbabble)
-- [Facebook messenger](https://github.com/powerjungle/fbridge-asyncio)
-- [Facebook messenger](https://github.com/VictorNine/fbridge)
-- [Minecraft](https://github.com/elytra/MatterLink)
-- [Reddit](https://github.com/bonehurtingjuice/mattereddit)
-- [MatterAMXX](https://github.com/andrewlindberg/MatterAMXX): [Counter-Strike, half-life and more](https://forums.alliedmods.net/showthread.php?t=319430)
-- [Vintage Story](https://github.com/NikkyAI/vs-matterbridge)
-- [Ultima Online Emulator](https://github.com/kuoushi/ServUO-Matterbridge)
-- [Teamspeak](https://github.com/Archeb/ts-matterbridge)
-
-
-### API
-
-The API is basic at the moment.
-More info and examples on the [wiki](https://github.com/42wim/matterbridge/wiki/Api).
-
-Used by the projects below. Feel free to make a PR to add your project to this list.
-
-- [MatterLink](https://github.com/elytra/MatterLink) (Matterbridge link for Minecraft Forge server chat, archived)
-- [MatterCraft](https://github.com/raws/mattercraft) (Matterbridge link for Minecraft Forge server chat)
-- [MatterBukkit](https://gitlab.com/Programie/MatterBukkit) (Matterbridge link for Minecraft Bukkit/Spigot server chat)
-- [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot)
-- [Mattereddit](https://github.com/bonehurtingjuice/mattereddit) (Reddit chat support)
-- [fbridge-asyncio](https://github.com/powerjungle/fbridge-asyncio) (Facebook messenger support)
-- [fbridge](https://github.com/VictorNine/fbridge) (Facebook messenger support)
-- [matterbabble](https://github.com/DeclanHoare/matterbabble) (Discourse support)
-- [MatterAMXX](https://forums.alliedmods.net/showthread.php?t=319430) (Counter-Strike, half-life and more via AMXX mod)
-- [Vintage Story](https://github.com/NikkyAI/vs-matterbridge)
-- [ServUO-matterbridge](https://github.com/kuoushi/ServUO-Matterbridge) (A matterbridge connector for ServUO servers)
-- [ts-matterbridge](https://github.com/Archeb/ts-matterbridge) (Integrate teamspeak chat with matterbridge)
-- [beerchat](https://github.com/mt-mods/beerchat) (Matterbridge link for minetest)
-
-## Chat with us
-
-Questions or want to test on your favorite platform? Join below:
-
-- [Discord][mb-discord]
-- [Gitter][mb-gitter]
-- [IRC][mb-irc]
-- [Keybase][mb-keybase]
-- [Matrix][mb-matrix]
-- [Mattermost][mb-mattermost]
-- [Rocket.Chat][mb-rocketchat]
-- [Slack][mb-slack]
-- [Telegram][mb-telegram]
-- [Twitch][mb-twitch]
-- [XMPP][mb-xmpp] (matterbridge@conference.jabber.de)
-- [Zulip][mb-zulip]
-
-## Screenshots
-
-See
-
-## Installing / upgrading
-
-### Binaries
-
-- Latest stable release [v1.26.0](https://github.com/42wim/matterbridge/releases/latest)
-- Development releases (follows master) can be downloaded [here](https://github.com/42wim/matterbridge/actions) selecting the latest green build and then artifacts.
-
-To install or upgrade just download the latest [binary](https://github.com/42wim/matterbridge/releases/latest). On \*nix platforms you may need to make the binary executable - you can do this by running `chmod a+x` on the binary (example: `chmod a+x matterbridge-1.24.1-linux-64bit`). After downloading (and making the binary executable, if necessary), follow the instructions on the [howto](https://github.com/42wim/matterbridge/wiki/How-to-create-your-config) for a step by step walkthrough for creating your configuration.
-
-### Packages
-
-- [Overview](https://repology.org/metapackage/matterbridge/versions)
-- [snap](https://snapcraft.io/matterbridge)
-- [scoop](https://github.com/42wim/scoop-bucket)
-
-## Building
-
-Most people just want to use binaries, you can find those [here](https://github.com/42wim/matterbridge/releases/latest)
-
-If you really want to build from source, follow these instructions:
-Go 1.18+ is required. Make sure you have [Go](https://golang.org/doc/install) properly installed.
-
-Building the binary with **all** the bridges enabled needs about 3GB RAM to compile.
-You can reduce this memory requirement to 0,5GB RAM by adding the `nomsteams` tag if you don't need/use the Microsoft Teams bridge.
-
-Matterbridge can be build without gcc/c-compiler: If you're running on windows first run `set CGO_ENABLED=0` on other platforms you prepend `CGO_ENABLED=0` to the `go build` command. (eg `CGO_ENABLED=0 go install github.com/42wim/matterbridge`)
-
-To install the latest stable run:
-
-```bash
-go install github.com/42wim/matterbridge
-```
-
-To install the latest dev run:
+Many features are available, but not all of them are supported on all protocols:
-```bash
-go install github.com/42wim/matterbridge@master
-```
+- [x] Bridge many rooms from supported protocols
+- [x] Message threads/topics, and replies
+- [x] Attachments, file uploads, and inline images
+- [x] Transparent bridging with spoofed usernames and avatars
+- [x] Private groups
-To install the latest stable run without msteams or zulip bridge:
+**The complete and up-to-date list of supported protocols is in [docs/protocols/](docs/protocols/).** Additionally, we have an [API for 3rd party integration](https://github.com/42wim/matterbridge/wiki/Features#api) if you'd like to add a custom bridge without implementing it in this codebase.
-```bash
-go install -tags nomsteams,nozulip github.com/42wim/matterbridge
-```
+
-You should now have matterbridge binary in the ~/go/bin directory:
+## Getting started with matterbridge
-```bash
-$ ls ~/go/bin/
-matterbridge
-```
+Get matterbridge up-and-running in a few minutes in 3 simple steps:
-## Building with whatsapp (beta) multidevice support
+- [Setting up matterbridge](docs/setup.md) (see [docs/compiling.md](docs/compiling.md) for compiling from source)
+- [Configuring matterbridge](docs/config.md)
+- [Running matterbridge](docs/running.md) (CLI or as a systemd service)
-Because the library we use for Whatsapp multidevice support includes a GPL3 library we can not provide you binaries.
-(as this would require the Matterbridge to change it license to GPL)
+## Documentation
-Matterbridge can be build without gcc/c-compiler: If you're running on windows first run `set CGO_ENABLED=0` on other platforms you prepend `CGO_ENABLED=0` to the `go build` command. (eg `CGO_ENABLED=0 go install github.com/42wim/matterbridge`)
+See [docs/](docs/) folder in this repository.
-So this means you have to build it yourself using the instructions below:
+## Contributing
-```bash
-go install -tags whatsappmulti github.com/42wim/matterbridge@master
-```
+This project is licensed under the Apache License 2.0. A copy can be found in the [LICENSE](LICENSE) file in this repository.
-If you're low on memory and don't need msteams:
+You are welcome to submit pull requests, report bugs and request new features. matterbridge is a volunteer-run project and you are expected to behave with respect for the maintainers and other users. In particular, harassment and hate speech are not welcome.
-```bash
-go install -tags nomsteams,whatsappmulti github.com/42wim/matterbridge@master
-```
+For more development guidelines, see [docs/development/](docs/development/).
-You should now have matterbridge binary in the ~/go/bin directory:
+### Chat with us
-```bash
-$ ls ~/go/bin/
-matterbridge
-```
+Questions or want to test on your favorite platform? Join us on:
-## Configuration
-
-### Basic configuration
-
-See [howto](https://github.com/42wim/matterbridge/wiki/How-to-create-your-config) for a step by step walkthrough for creating your configuration.
-
-### Settings
-
-All possible [settings](https://github.com/42wim/matterbridge/wiki/Settings) for each bridge.
-
-### Advanced configuration
-
-- [matterbridge.toml.sample](https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample) for documentation and an example.
-
-### Examples
-
-#### Bridge mattermost (off-topic) - irc (#testing)
-
-```toml
-[irc]
- [irc.libera]
- Server="irc.libera.chat:6667"
- Nick="yourbotname"
-
-[mattermost]
- [mattermost.work]
- Server="yourmattermostserver.tld"
- Team="yourteam"
- Login="yourlogin"
- Password="yourpass"
- PrefixMessagesWithNick=true
- RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
-
-[[gateway]]
-name="mygateway"
-enable=true
- [[gateway.inout]]
- account="irc.libera"
- channel="#testing"
-
- [[gateway.inout]]
- account="mattermost.work"
- channel="off-topic"
-```
-
-#### Bridge slack (#general) - discord (general)
-
-```toml
-[slack]
-[slack.test]
-Token="yourslacktoken"
-PrefixMessagesWithNick=true
-
-[discord]
-[discord.test]
-Token="yourdiscordtoken"
-Server="yourdiscordservername"
-
-[general]
-RemoteNickFormat="[{PROTOCOL}/{BRIDGE}] <{NICK}> "
-
-[[gateway]]
- name = "mygateway"
- enable=true
-
- [[gateway.inout]]
- account = "discord.test"
- channel="general"
-
- [[gateway.inout]]
- account ="slack.test"
- channel = "general"
-```
-
-## Running
-
-See [howto](https://github.com/42wim/matterbridge/wiki/How-to-create-your-config) for a step by step walkthrough for creating your configuration.
-
-```bash
-Usage of ./matterbridge:
- -conf string
- config file (default "matterbridge.toml")
- -debug
- enable debug
- -gops
- enable gops agent
- -version
- show version
-```
-
-### Docker
-
-Please take a look at the [Docker Wiki page](https://github.com/42wim/matterbridge/wiki/Deploy:-Docker) for more information.
-
-### Systemd
-
-Please take a look at the [Service Files page](https://github.com/42wim/matterbridge/wiki/Service-files) for more information.
-
-## Changelog
-
-See [changelog.md](https://github.com/42wim/matterbridge/blob/master/changelog.md)
-
-## FAQ
-
-See [FAQ](https://github.com/42wim/matterbridge/wiki/FAQ)
+- federated networks: [Gitter][mb-gitter], [Jabber/XMPP][mb-xmpp], [Matrix][mb-matrix]
+- non-free centralized networks: [Discord][mb-discord], [Keybase][mb-keybase], [Slack][mb-slack], [Telegram][mb-telegram], [Twitch][mb-twitch]
+- self-hostable centralized networks: [IRC][mb-irc], [Mattermost][mb-mattermost], [Rocket.Chat][mb-rocketchat], [Zulip][mb-zulip]
## Related projects
@@ -362,69 +64,12 @@ See [FAQ](https://github.com/42wim/matterbridge/wiki/FAQ)
- [matterbridge autoconfig](https://github.com/patcon/matterbridge-autoconfig)
- [matterbridge config viewer](https://github.com/patcon/matterbridge-heroku-viewer)
- [matterbridge-heroku](https://github.com/cadecairos/matterbridge-heroku)
-- [mattereddit](https://github.com/bonehurtingjuice/mattereddit)
-- [matterlink](https://github.com/elytra/MatterLink)
- [mattermost-plugin](https://github.com/matterbridge/mattermost-plugin) - Run matterbridge as a plugin in mattermost
-- [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot)
-- [fbridge](https://github.com/VictorNine/fbridge) (Facebook messenger support)
- [isla](https://github.com/alphachung/isla) (Bot for Discord-Telegram groups used alongside matterbridge)
-- [matterbabble](https://github.com/DeclanHoare/matterbabble) (Connect Discourse threads to Matterbridge)
-- [nextcloud talk](https://github.com/nextcloud/talk_matterbridge) (Integrates matterbridge in Nextcloud Talk)
-- [mattercraft](https://github.com/raws/mattercraft) (Minecraft bridge)
-- [vs-matterbridge](https://github.com/NikkyAI/vs-matterbridge) (Vintage Story bridge)
-- [ServUO-matterbridge](https://github.com/kuoushi/ServUO-Matterbridge) (A matterbridge connector for ServUO servers)
-- [ts-matterbridge](https://github.com/Archeb/ts-matterbridge) (Integrate teamspeak chat with matterbridge)
-
-## Articles / Tutorials
-
-- [matterbridge on kubernetes](https://medium.freecodecamp.org/using-kubernetes-to-deploy-a-chat-gateway-or-when-technology-works-like-its-supposed-to-a169a8cd69a3)
--
--
--
--
--
--
--
--
--
--
-- Youtube: [whatsapp - telegram bridging](https://www.youtube.com/watch?v=W-VXISoKtNc)
## Thanks
-This project is supported by:
-
-
- 
-
-
-
-Matterbridge wouldn't exist without these libraries:
-
-- discord -
-- echo -
-- gops -
-- gozulipbot -
-- gumble -
-- harmony -
-- irc -
-- keybase -
-- matrix -
-- mattermost -
-- msgraph.go -
-- mumble -
-- nctalk -
-- rocketchat -
-- slack -
-- sshchat -
-- steam -
-- telegram -
-- tengo -
-- vk -
-- whatsapp -
-- whatsapp -
-- xmpp -
-- zulip -
+Matterbridge wouldn't exist without amazing libraries, without [@42wim](https://github.com/42wim) who started the project, and without the 100+ contributors who participated in this adventure. See [docs/credits.md](docs/credits.md) for more complete credits.
@@ -440,5 +85,6 @@ Matterbridge wouldn't exist without these libraries:
[mb-telegram]: https://t.me/Matterbridge
[mb-twitch]: https://www.twitch.tv/matterbridge
[mb-whatsapp]: https://www.whatsapp.com/
-[mb-xmpp]: https://inverse.chat/
+[mb-xmpp]: xmpp:matterbridge@conference.jabber.de?join
[mb-zulip]: https://matterbridge.zulipchat.com/register/
+
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 0000000000..b0a24e4df3
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,84 @@
+# Matterbridge FAQ
+
+## Can matterbridge relay group messages between public chats on different platforms?
+
+Yes, that's precisely what matterbridge is for.
+
+## Does matterbridge support private chatrooms too?
+
+Yes, but actual support depends on the platform.
+
+## Can matterbridge be used to send private messages between users?
+
+No, that is currently unsupported at the moment. See tracking issue [#191](https://github.com/42wim/matterbridge/issues/191).
+
+## Message being skipped
+
+(From https://github.com/42wim/matterbridge/discussions/1566)
+
+Matterbridge does not relay messages from the user account that it is logged in as. Make sure it has its own account.
+
+
+ * [Support bridging between any protocols](#support-bridging-between-any-protocols)
+ * [Support multiple gateways(bridges) for your protocols](#support-multiple-gatewaysbridges-for-your-protocols)
+ * [Message edits and deletes](#message-edits-and-deletes)
+ * [Attachment / files handling](#attachment--files-handling)
+ * [Username and avatar spoofing](#username-and-avatar-spoofing)
+ * [Private groups](#private-groups)
+ * [API](#api)
+
+# Support bridging between any protocols
+Supported protocols are Discord, Gitter, IRC, Mattermost, Matrix, RocketChat, Slack, Steam, Telegram, XMPP (and our own rest API)
+You can bridge between any (number) protocols. Even the same protocol!
+
+For example you can bridge Discord, Gitter, Matrix and Slack.
+A message typed in Slack will be shown in Discord, Gitter and Matrix (and the other way around)
+
+Follow the steps in [[How-to-create-your-config]]
+
+# Support multiple gateways(bridges) for your protocols
+A gateway here is a collection of protocols that you want to bridge.
+
+For example you want to bridge the channel "community" on discord, mattermost and slack.
+But you also want to bridge the channel "development" on discord, mattermost and slack.
+
+To create the setup above you'll have to create 2 gateways.
+
+See Gateway Config Advanced TODO
+# Message edits and deletes
+* Support incoming and outgoing edits and deletes: Discord, Mattermost, Slack, Matrix and Telegram.
+* Support only incoming edits: Gitter. (gitter API doesn't support outgoing edits)
+* Support only incoming edits/deletes: RocketChat
+* Support only edits: XMPP
+* Support no deletes or edits: IRC, Steam(NR)
+
+NR = Not researched
+
+# Attachment / files handling
+The logic is: Public links > Native file upload > External mediaserver > Private links
+
+This means that bridges:
+- will receive the "public link" from protocols that have links to files without authentication (Gitter, IRC, Discord)
+- that support native file uploads (Discord,Matrix,Mattermost,Slack,Telegram,Rocketchat) will receive a uploaded copy of the file from protocols that have links to files with authentication (Matrix, Mattermost, Slack, Telegram)
+- that do NOT support native file uploads (Gitter, IRC, Steam, XMPP) will receive the "public link" from your "external mediaserver" from protocols that have links to files with authentication (Matrix, Mattermost, Slack, Telegram). (If you have configured an "external mediaserver")
+- that do NOT support native file uploads (Gitter, IRC, Steam, XMPP) will receive the "private link" from protocols that have links to files with authentication (Matrix, Mattermost, Slack, Telegram). (If you have not configured an "external mediaserver")
+
+
+For example if you bridge between slack and discord:
+
+When you upload a file to slack. The link you get from slack needs authentication, so matterbridge downloads this file and reuploads it to the destination bridge Discord (which support native file uploads). If you upload a file to discord, matterbridge will just sent the link to slack (because the discord links are public and don't need authentication)
+
+# Username and avatar spoofing
+Username spoofing (so it looks like the remote users) only works with webhooks for Discord, Mattermost, Slack.
+Matterbridge reads avatars from Discord, Gitter, Mattermost and Slack but can only send them to Discord, Mattermost and Slack when webhooks are enabled. (Gitter doesn't allow avatar changes).
+
+To have avatars from mattermost visible on the other bridges, you'll have to use the external mediaserver setup. This is because avatar images from mattermost aren't publicly visible when not logged into mattermost. This means we need to download the avatar images, and upload them to the public mediaserver, and use this (now public) avatar URL in the messages sent to another bridge, eg slack.
+
+See webhook in advanced for specific bridge information TODO
+
+# Private groups
+Private groups are supported for Mattermost and Slack
+
+# API
+See [[Api]]
+
diff --git a/docs/advanced/mediaserver.md b/docs/advanced/mediaserver.md
new file mode 100644
index 0000000000..921277d67c
--- /dev/null
+++ b/docs/advanced/mediaserver.md
@@ -0,0 +1,79 @@
+Matterbridge is not going to implement it's own "mediaserver" instead we make use of other tools that are good at this sort of stuff.
+This mediaserver will be used to upload media to services that don't have support for uploading images/video/files.
+At this moment this is xmpp, gitter and irc
+
+There are 2 options to set this up:
+* You already have a webserver running
+ * Matterbridge runs on the same server see [local download](#use-local-download)
+ * Matterbridge runs on another server. If the webserver is using caddy, see [caddy](#use-remote-upload)
+* You don't have a webserver running
+ * See [caddy](#use-remote-upload)
+
+# Use remote upload
+## Caddy
+In this case we're using caddy for upload/downloading media.
+Caddy has automatic https support, so I'm going to describe this for https only.
+
+
+### caddy install / configuration
+Go to https://caddyserver.com/download
+Enable `http.upload` as plugin
+
+Make sure the process you're running caddy with has read/write access to `/var/www/upload/`
+
+Sample Caddyfile
+```
+yourserver.com:443 {
+ log stdout
+ root /var/www/upload/
+ browse
+ basicauth /web/upload a_user a_password
+ upload /upload {
+ to "/var/www/upload/"
+ }
+}
+```
+### matterbridge configuration
+configuration needs to happen in `[general]`
+```
+[general]
+MediaServerUpload="https://a_user:a_password@yourserver.com/upload"
+MediaServerDownload="https://yourserver.com/"
+```
+
+# Use local download
+In this case we're using matterbridge to download to a local path your webserver has read access to and matterbridge has write access to.
+Matterbridge is running on this same server.
+
+## matterbridge configuration
+
+In this example the local path matterbridge has write access to is `/var/www/matterbridge`
+
+Your server (apache, nginx, ...) exposes this on `http://yourserver.com/matterbridge` (nginx, apache configuration is out of scope)
+
+configuration needs to happen in `[general]`
+```
+[general]
+MediaDownloadPath="/var/www/matterbridge"
+MediaServerDownload="https://yourserver.com/matterbridge"
+```
+
+When using the local download configuration, matterbridge does not clean up any of the content it downloads to the Mediaserver path.
+## Sidenote
+If you run into issues with the amount of storage available, then it is advised to do an automated cleanup which is to be done externally (i.e. via cron). An example of a clean up script and two examples of cron jobs are provided below. These represent the minimal amount of effort needed to handle this and don't take into account any ability to customize much.
+
+cleanup.sh:
+```
+#!/bin/bash
+find /path/to/matterbridge/media -mindepth 1 -mtime +30 -delete
+```
+
+This will delete all downloaded content that is more than 30 days old (but not the media directory itself, due to the use of `-mindepth 1`). You should adjust the path and the max age to suit your own needs. It may be helpful to look at the [`find` manual page](https://www.gnu.org/software/findutils/manual/html_node/find_html/index.html).
+
+To run the script as the user running matterbridge, execute `crontab -e` and add the following line to the bottom of the file:
+```
+@daily /path/to/cleanup.sh
+```
+
+If you want to run it as root, you probably shouldn't (fix your file permissions instead). However, you can add the script to /etc/cron.daily:
+`cp /path/to/cleanup.sh /etc/cron.daily`. This will execute it daily automatically in most Redhat and Debian based Linux distros.
\ No newline at end of file
diff --git a/docs/advanced/tengo.md b/docs/advanced/tengo.md
new file mode 100644
index 0000000000..9ca74f07dc
--- /dev/null
+++ b/docs/advanced/tengo.md
@@ -0,0 +1,84 @@
+Tengo can be used for advanced scripting in matterbridge, you can modify incoming and outgoing messages.
+
+You can also use it to modify the `{TENGO}` parameter in the `RemoteNickFormat`.
+
+```
+[tengo]
+InMessage="yourscript.tengo"
+OutMessage="yourotherscript.tengo"
+RemoteNickFormat="remotenickformat.tengo"
+```
+
+More information about tengo on: https://github.com/d5/tengo/blob/master/docs/tutorial.md and https://github.com/d5/tengo/blob/master/docs/stdlib.md
+
+FIXME: Document support for [dropping messages](https://github.com/42wim/matterbridge/pull/1272).
+
+## InMessage
+
+InMessage allows you to specify the location of a tengo (https://github.com/d5/tengo/) script.
+This script will receive every incoming message and can be used to modify the Username and the Text of that message.
+
+The script will have the following global variables: \
+to modify: `msgUsername` and `msgText` \
+to read: `msgChannel` and `msgAccount`
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+Example script can be found in https://github.com/42wim/matterbridge/tree/master/gateway/bench.tengo
+and https://github.com/42wim/matterbridge/tree/master/contrib/example.tengo
+
+The example below will check if the text contains blah and if so, it'll replace the text and the username of that message.
+```
+text := import("text")
+if text.re_match("blah",msgText) {
+ msgText="replaced by this"
+ msgUsername="fakeuser"
+}
+```
+
+`InMessage="example.tengo"`
+
+## OutMessage
+
+OutMessage allows you to specify the location of the script that will be invoked on each message being sent to a bridge and can be used to modify the Username and the Text of that message.
+
+The script will have the following global variables: \
+read-only: \
+`inAccount`, `inProtocol`, `inChannel`, `inGateway`, `inEvent` \
+`outAccount`, `outProtocol`, `outChannel`, `outGateway`, `outEvent` \
+
+read-write: \
+`msgText`, `msgUsername`
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+The default script in
+is compiled in and will be executed if no script is specified.
+
+`OutMessage="example.tengo"`
+
+## RemoteNickFormat
+
+RemoteNickFormat allows you to specify the location of a tengo (https://github.com/d5/tengo/) script.
+
+The script will have the following global variables: \
+to modify: `result` \
+to read: `channel`, `bridge`, `gateway`, `protocol`, `nick`
+
+The result will be set in `{TENGO}` in the RemoteNickFormat key of every bridge where `{TENGO}` is specified
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+Example script can be found in
+
+`RemoteNickFormat="remotenickformat.tengo"`
+
+## More information
+
+You can find more tengo examples/info here:
+-
+-
+-
+-
+
+The tengo documentation can be found here:
\ No newline at end of file
diff --git a/docs/advanced/tengo_settings.md b/docs/advanced/tengo_settings.md
new file mode 100644
index 0000000000..9e5b452610
--- /dev/null
+++ b/docs/advanced/tengo_settings.md
@@ -0,0 +1,78 @@
+# Tengo
+More information about tengo on: https://github.com/d5/tengo/blob/master/docs/tutorial.md and https://github.com/d5/tengo/blob/master/docs/stdlib.md
+
+FIXME: Document support for [dropping messages](https://github.com/42wim/matterbridge/pull/1272).
+
+## InMessage
+InMessage allows you to specify the location of a tengo (https://github.com/d5/tengo/) script.
+This script will receive every incoming message and can be used to modify the Username and the Text of that message.
+The script will have the following global variables: \
+to modify: `msgUsername` and `msgText` \
+to read: `msgChannel` and `msgAccount`
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+Example script can be found in https://github.com/42wim/matterbridge/tree/master/gateway/bench.tengo
+and https://github.com/42wim/matterbridge/tree/master/contrib/example.tengo
+
+The example below will check if the text contains blah and if so, it'll replace the text and the username of that message.
+```
+text := import("text")
+if text.re_match("blah",msgText) {
+ msgText="replaced by this"
+ msgUsername="fakeuser"
+}
+```
+
+Setting: OPTIONAL, RELOADABLE \
+Format: string
+Example:
+
+`InMessage="example.tengo"`
+
+## OutMessage
+OutMessage allows you to specify the location of the script that
+will be invoked on each message being sent to a bridge and can be used to modify the Username
+and the Text of that message.
+
+The script will have the following global variables:
+read-only:
+`inAccount`, `inProtocol`, `inChannel`, `inGateway`, `inEvent`
+`outAccount`, `outProtocol`, `outChannel`, `outGateway`, `outEvent`
+
+read-write:
+`msgText`, `msgUsername`
+
+Notice: `msgUsername` is already formatted by [RemoteNickFormat](https://github.com/42wim/matterbridge/wiki/Settings#remotenickformat) at this point.
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+The default script in https://github.com/42wim/matterbridge/tree/master/internal/tengo/outmessage.tengo
+is compiled in and will be executed if no script is specified.
+
+**Tengo scripts on a docker instance**
+Place your scripts in `/etc/matterbridge` on the container and reference them with `OutMessage="/etc/matterbridge/example.tengo"`
+
+Setting: OPTIONAL, RELOADABLE \
+Format: string
+Example:
+
+`OutMessage="example.tengo"`
+
+## RemoteNickFormat
+RemoteNickFormat allows you to specify the location of a tengo (https://github.com/d5/tengo/) script.
+The script will have the following global variables: \
+to modify: `result` \
+to read: `channel`, `bridge`, `gateway`, `protocol`, `nick`
+
+The result will be set in `{TENGO}` in the RemoteNickFormat key of every bridge where `{TENGO}` is specified
+
+The script is reloaded on every message, so you can modify the script on the fly.
+
+Example script can be found in https://github.com/42wim/matterbridge/tree/master/contrib/remotenickformat.tengo
+
+Setting: OPTIONAL, RELOADABLE \
+Format: string \
+Example:
+
+`RemoteNickFormat="remotenickformat.tengo"`
diff --git a/docs/api/README.md b/docs/api/README.md
new file mode 100644
index 0000000000..99aeeb606e
--- /dev/null
+++ b/docs/api/README.md
@@ -0,0 +1,160 @@
+# Matterbridge API
+
+If you'd like to develop your bridge in a different language than go, or if you
+need to interface with a system which can only perform outgoing connections,
+the matterbridge API is here.
+
+> [!TIP]
+> For detailed information about API settings, see [settings.md](settings.md)
+
+## OpenAPI specification
+
+Matterbridge API spec can be found on https://app.swaggerhub.com/apis-docs/matterbridge/matterbridge-api/0.1.0-oas3
+
+## Example discord/gitter/api gateway
+
+This example creates a gateway containing 3 bridges: discord,gitter and api.
+The API will listen on localhost port 4242.
+
+### Configure matterbridge.toml
+
+This is based on the example in https://github.com/42wim/matterbridge/wiki/How-to-create-your-config
+
+We first add the API account configuration to this example, this makes the API listen on localhost port 4242 with a buffer of 1000 messages and the nicks we receive will look like "{nick}".
+
+```toml
+[api.myapi]
+BindAddress="127.0.0.1:4242"
+Buffer=1000
+RemoteNickFormat="{NICK}"
+```
+
+Next we add the API gateway configuration, this make sure that we receive the messages from the other bridges and we can sent them.
+
+```toml
+[[gateway.inout]]
+account="api.myapi"
+channel="api"
+```
+
+The full example
+
+```toml
+[discord.mydiscord]
+Token="MTk4NjIyNDgzNDcdOTI1MjQ4.Cl2FMZ.ZnCjm1XVW7vRze4b7Cq4se7kKWs-abD"
+Server="myserver"
+
+[gitter.mygitter]
+Token="319fda1761c6875739a489b6772daf2ace4b95d0"
+
+[api.myapi]
+BindAddress="127.0.0.1:4242"
+Buffer=1000
+RemoteNickFormat="{NICK}"
+
+[[gateway]]
+name="gateway1"
+enable=true
+
+[[gateway.inout]]
+account="discord.mydiscord"
+channel="general"
+
+[[gateway.inout]]
+account="gitter.mygitter"
+channel="42wim/mygreatproject"
+
+[[gateway.inout]]
+account="api.myapi"
+channel="api"
+```
+
+### Get the messages from the buffer (GET /api/messages)
+
+If we now type a "test" message in our "general" channel on discord, we get the following result
+
+```bash
+$ curl http://localhost:4242/api/messages
+```
+
+
+```json
+[
+ {
+ "text": "test",
+ "channel": "general",
+ "username": "wim",
+ "userid": "227183123686215680",
+ "avatar": "https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg",
+ "account": "discord.mydiscord",
+ "event": "",
+ "protocol": "",
+ "gateway": "gateway1",
+ "parent_id": "",
+ "timestamp": "2019-01-09T22:37:18.647108348+01:00",
+ "id": "",
+ "Extra": null
+ }
+]
+```
+
+After we got this message (and we didn't type anything else), the buffer will be empty and doing a curl will now give an empty result
+
+```bash
+$ curl http://localhost:4242/api/messages
+```
+
+```json
+[]
+```
+
+### Stream messages (GET /api/stream)
+
+If we now type a "test" message in our "general" channel on discord, we get the following result
+
+```bash
+$ curl http://localhost:4242/api/stream
+```
+
+```json
+{"text":"","channel":"","username":"","userid":"","avatar":"","account":"","event":"api_connected","protocol":"","gateway":"","parent_id":"","timestamp":"2019-01-09T22:48:33.398737344+01:00","id":"","Extra":null}
+{"text":"test","channel":"general","username":"wim","userid":"227183123686215680","avatar":"https://cdn.discordapp.com/avatars/227183947686215680/bd0e6c7fe63274597a4684884891b79d.jpg","account":"discord.mydiscord","event":"","protocol":"","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:48:42.506629373+01:00","id":"","Extra":null}
+```
+
+At connect you first get a `api_connected` event, then you'll get a http stream of json messages
+
+### Send message (POST /api/message)
+
+We now post a `test` message from `randomuser` to the gateway `gateway1`
+
+Every bridge on the gateway (gitter and discord) will now receive this message.
+
+```bash
+curl -XPOST -H 'Content-Type: application/json' -d '{"text":"test","username":"randomuser","gateway":"gateway1"}' http://localhost:4242/api/message
+```
+
+```json
+{"text":"test","channel":"api","username":"randomuser","userid":"","avatar":"","account":"api.local","event":"","protocol":"api","gateway":"gateway1","parent_id":"","timestamp":"2019-01-09T22:53:51.618575236+01:00","id":"","Extra":null}
+```
+
+## Security
+You can also protect the API with a token by adding a `token` option to your api account configuration.
+
+```toml
+[api.myapi]
+BindAddress="127.0.0.1:4242"
+Buffer=1000
+RemoteNickFormat="{NICK}"
+Token="verys3cret"
+```
+If you now want to sent a message with curl you'll have to add a `Authorization: Bearer ` header
+
+```bash
+curl -H "Authorization: Bearer verys3cret" http://localhost:4242/api/stream
+```
+
+## Projects using the API
+
+* [MatterLink](https://github.com/elytra/MatterLink) (Matterbridge link for Minecraft Server chat)
+* [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot)
+* [Mattereddit](https://github.com/bonehurtingjuice/mattereddit) (Reddit chat support)
diff --git a/docs/api/settings.md b/docs/api/settings.md
new file mode 100644
index 0000000000..b1ca2a74e5
--- /dev/null
+++ b/docs/api/settings.md
@@ -0,0 +1,40 @@
+# Matterbridge API settings
+
+> [!TIP]
+> This page contains the details about matterbridge API settings. More general information about the matterbridge API can be found in [README.md](README.md).
+
+## BindAddress
+
+Address to listen on for API
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ BindAddress="127.0.0.1:4242"
+ ```
+
+## Buffer
+
+Amount of messages to keep in memory
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *int*
+- Default: *10*
+- Example:
+ ```toml
+ Buffer=1000
+ ```
+
+## Token
+
+HTTP Bearer token used for authentication. If unset, no authentication
+will be applied at all and anyone who can reach the API will be able
+to control your matterbridge instance.
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *string*
+- Example:
+ ```toml
+ Token="mytoken"
+ ```
diff --git a/docs/compiling.md b/docs/compiling.md
new file mode 100644
index 0000000000..d3b5d42c0c
--- /dev/null
+++ b/docs/compiling.md
@@ -0,0 +1,62 @@
+# Building from source
+
+This page documents how to build matterbridge from source. If you're looking for ready-to-use executables, head over to [setup.md].
+
+If you really want to build from source, follow these instructions:
+Go 1.18+ is required. Make sure you have [Go](https://golang.org/doc/install) properly installed.
+
+Building the binary with **all** the bridges enabled needs about 3GB RAM to compile.
+You can reduce this memory requirement to 0,5GB RAM by adding the `nomsteams` tag if you don't need/use the Microsoft Teams bridge.
+
+Matterbridge can be build without gcc/c-compiler: If you're running on windows first run `set CGO_ENABLED=0` on other platforms you prepend `CGO_ENABLED=0` to the `go build` command. (eg `CGO_ENABLED=0 go install github.com/42wim/matterbridge`)
+
+To install the latest stable run:
+
+```bash
+go install github.com/42wim/matterbridge
+```
+
+To install the latest dev run:
+
+```bash
+go install github.com/42wim/matterbridge@master
+```
+
+To install the latest stable run without msteams or zulip bridge:
+
+```bash
+go install -tags nomsteams,nozulip github.com/42wim/matterbridge
+```
+
+You should now have matterbridge binary in the ~/go/bin directory:
+
+```bash
+$ ls ~/go/bin/
+matterbridge
+```
+
+## Building with whatsapp (beta) multidevice support
+
+Because the library we use for Whatsapp multidevice support includes a GPL3 library we can not provide you binaries.
+(as this would require the Matterbridge to change it license to GPL)
+
+Matterbridge can be build without gcc/c-compiler: If you're running on windows first run `set CGO_ENABLED=0` on other platforms you prepend `CGO_ENABLED=0` to the `go build` command. (eg `CGO_ENABLED=0 go install github.com/42wim/matterbridge`)
+
+So this means you have to build it yourself using the instructions below:
+
+```bash
+go install -tags whatsappmulti github.com/42wim/matterbridge@master
+```
+
+If you're low on memory and don't need msteams:
+
+```bash
+go install -tags nomsteams,whatsappmulti github.com/42wim/matterbridge@master
+```
+
+You should now have matterbridge binary in the ~/go/bin directory:
+
+```bash
+$ ls ~/go/bin/
+matterbridge
+```
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 0000000000..5daec44abe
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,120 @@
+# Configuring matterbridge
+
+> [!WARNING]
+> This page explains the basic concepts for configuring matterbridge, and gives a very simple example.
+> For more complete configuration options refer to:
+> - [settings.md](settings.md) for global settings
+> - [protocols/](protocols/) documentation folder for protocol-specific settings
+> - [advanced/](advanced/) documentation folder for advanced settings, such as Tengo scripting and media servers (TODO: rewrite those docs)
+
+## Concepts
+
+matterbridge configuration makes use of a few concepts:
+
+- a `protocol` is a way to reach a certain chat server ; some protocols support multiple servers (eg. IRC/XMPP/Matrix), while others don't (eg. Discord/Telegram/Whatsapp)
+- an `account` is a way for your matterbridge bot to reach a specific server (usually with a username/psasword or an API token)
+- a `channel` is a chatroom on a specific server
+- a `gateway` is a virtual room that aggregates several channels to relay messages between them with your matterbridge bot
+
+### Protocols
+
+Protocols are ways for matterbridge to connect to a network/platform. The list of supported protocols, and supported features for that protocol, is available in [protocols/](protocols/).
+
+### Accounts
+
+An account allows the bot to connect to a certain server using a protocol. Your matterbridge bot may have different accounts (and identities) on the same protocol, for example being connected with two different Discord accounts. In the case of self-hosted centralized protocols such as IRC or Mattermost, it may even be required to have different accounts on different servers in order to reach all the chatrooms you'd like to bridge.
+
+> [!TIP]
+> For documentation on how to create an account on specific protocols for your bot, refer to specific protocols docs in [protocols/](protocols/).
+
+A basic account configuration looks like this:
+
+```toml
+# Telegram has only one server (no need to specify the address),
+# does not have usernames/passwords for bots (only API tokens)
+# and does not allow to configure the bot name.
+[telegram.myaccount]
+Token="MySecretBotToken"
+```
+
+As explained, you can have different identities on the same network/protocol:
+
+```toml
+# An IRC server (or as IRC people call it, an "IRC network") supports
+# authentication by username/password.
+[irc.libera]
+Server="irc.libera.chat:6667"
+Nick="yourliberaaccount"
+NickServPassword="yourpassword"
+[irc.geeknode]
+Server="irc.geeknode.org:6667"
+Nick="yourgeeknodeaccount"
+NickServPassword="yourpassword"
+```
+
+Some protocols allow configuring the bot's name, others don't.
+
+> [!NOTE]
+> Some servers (such as Telegram) don't allow the account to have two connections at once. In that case, it's only possible to connect a single matterbridge instance to the account (at a given moment), and running a different bot on the same account is not possible.
+
+### Channels
+
+Channels are specific chatrooms on a certain network. For example, `#matterbridge` on `irc.libera.chat`, or `matterbridge@conference.jabber.de`.
+That's where the humans meet and chat, and that's where we want the matterbridge bot to go to relay messages.
+
+Depending on the protocol, channels may be represented by a name (such as `#matterbridge` or `matterbridge` in the previous example), or by a numeric identifier (like `0213809218`).
+
+### Gateways
+
+Gateways are a matterbridge-specific concept. They are not what is known as gateways in [Jabber/XMPP](https://joinjabber.org/tutorials/gateways/) or bridges in [Jabber/XMPP](https://joinjabber.org/tutorials/bridges/) or [Matrix](https://matrix.org/ecosystem/bridges/).
+
+Gateways are simple configuration to link different channels together, and let matterbridge know how to relay messages. They have two basic settings: `name` (for logging), and `enable` (`true` or `false`). Then gateway have an `inout` list of `account`/`channel` to bridge together:
+
+```toml
+[[gateway]]
+name="mygateway"
+enable=true
+
+[[gateway.inout]]
+account="irc.libera"
+channel="#testing"
+
+[[gateway.inout]]
+account="irc.geeknode"
+channel="#testingheretoo"
+```
+
+The gateway configuration reuses previous configured accounts, adding a specific channel on that account's server.
+
+From this simple example, you can:
+
+- add a new channel to the same bridged discussion, by adding a new `[[gateway.inout]]` section
+- add an entirely new discussion bridging other channels, by creating a new `[[gateway]]` section, with the corresponding `[[gateway.inout]]` sections
+
+## Basic configuration
+
+Taking the example from the previous section, a full valid configuration file (except for ommitted bot passwords), would be:
+
+```toml
+[irc.libera]
+Server="irc.libera.chat:6667"
+Nick="yourliberaaccount"
+NickServPassword="yourpassword"
+
+[irc.geeknode]
+Server="irc.geeknode.org:6667"
+Nick="yourgeeknodeaccount"
+NickServPassword="yourpassword"
+
+[[gateway]]
+name="mygateway"
+enable=true
+
+[[gateway.inout]]
+account="irc.libera"
+channel="#testing"
+
+[[gateway.inout]]
+account="irc.geeknode"
+channel="#testingheretoo"
+```
diff --git a/docs/credits.md b/docs/credits.md
new file mode 100644
index 0000000000..db0be0a9a5
--- /dev/null
+++ b/docs/credits.md
@@ -0,0 +1,30 @@
+# Credits
+
+Huge thanks to @42wim (https://42.be) for starting the project back in 2015 and maintaining it over the years.
+
+Matterbridge wouldn't exist without these libraries:
+
+- discord -
+- echo -
+- gops -
+- gozulipbot -
+- gumble -
+- harmony -
+- irc -
+- keybase -
+- matrix -
+- mattermost -
+- msgraph.go -
+- mumble -
+- nctalk -
+- rocketchat -
+- slack -
+- sshchat -
+- steam -
+- telegram -
+- tengo -
+- vk -
+- whatsapp -
+- whatsapp -
+- xmpp -
+- zulip -
diff --git a/docs/development/README.md b/docs/development/README.md
new file mode 100644
index 0000000000..d0a77c9965
--- /dev/null
+++ b/docs/development/README.md
@@ -0,0 +1,19 @@
+# Development guide
+
+In this folder, you will find information about contributing code to matterbridge.
+
+## Building from source
+
+See [../compiling.md](../compiling.md).
+
+## Implementing a new protocol backend
+
+See [protocol.md](protocol.md).
+
+## General pull-request guidelines
+
+When submitting a PR, it's expected that:
+
+- you have successfully run `go fmt` on the codebase
+- you have successfully run `golangci-lint` on the codebase
+- you have updated the corresponding bridge/protocol docs in `docs/protocols`
diff --git a/docs/development/protocol.md b/docs/development/protocol.md
new file mode 100644
index 0000000000..a5278247e9
--- /dev/null
+++ b/docs/development/protocol.md
@@ -0,0 +1,74 @@
+# Implementing a new protocol
+
+This guide explains how to create a new protocol backend to support a new gateway/bridge in matterbridge.
+
+## Step-by step list
+
+- [ ] Create a new catalog in [`/bridge` folder](https://github.com/42wim/matterbridge/tree/master/bridge) and a main file named after the bridge you are creating, such as `whatsapp.go`
+- [ ] Implement a [`Bridger` interface](https://github.com/42wim/matterbridge/blob/2cfd880cdb0df29771bf8f31df8d990ab897889d/bridge/bridge.go#L11-L16)
+- [ ] [`gitter`](https://github.com/42wim/matterbridge/blob/master/bridge/gitter/gitter.go) is a relatively simple bridge that you might use as a reference to adapt
+- [ ] Mention your bridge exists in [`/gateway/bridgemap/bridgemap.go`](https://github.com/42wim/matterbridge/blob/master/gateway/bridgemap/bridgemap.go)
+- [ ] Divide functionality in several files, as it is done for [slack](https://github.com/42wim/matterbridge/tree/master/bridge)
+ - `yourbridge.go` with main struct and implementation of the `Bridger` interface
+ - `handlers.go` with handling messages incoming to Bridge
+ - `helpers.go` for all the misc functions and helpers
+- [ ] Minimal set of features is sending and receiving text messages working.
+- [ ] Documentation
+ - [ ] Add a [sample configuration](https://github.com/42wim/matterbridge/commit/6372d599b1ca2497aa49142d10496f345041b678#diff-0fcc5f77f08a4f4106d2da34c4dcd133) of your bridge to `matterbridge.toml.sample` and explain all the custom options
+ - [ ] Add your bridge to README
+ - [ ] Document all exported functions
+- [ ] Run `golint` and `goimports` and clean the code
+- [ ] Run `go mod vendor` to pull in all the vendor code
+- [ ] Send a PR
+
+## Features
+
+Below is a feature list that you might copy to your issue.
+
+Features:
+- [ ] Connect to external service
+- [ ] Get all active chats
+- [ ] Check if chosen channels exist externally
+- [ ] Connect to chosen channel
+- [ ] Show nicknames in external service
+- [ ] Show nicknames in relayed messages
+- [ ] Test if multiple channels are working
+- [ ] Show profile pictures from your bridge in relayed messages
+- [ ] Show profile picture in your bridge
+- [ ] Handle reply/thread messages
+- [ ] Handle deletes
+- [ ] Handle edits
+- [ ] Handle notifications
+- [ ] Create a channel if it doesn't exist
+- [ ] Sync channel metadata (name, topic, etc.)
+- [ ] Document settings in `matterbridge.toml.sample`
+- [ ] Document bridge in README
+- [ ] Explain setting up the bridge process for users in the wiki
+- [ ] Add screenshots from your bridge in the wiki
+- [ ] Document code
+
+Handle messages
+- [ ] text from the bridge
+- [ ] text to the bridge
+- [ ] image
+- [ ] audio
+- [ ] video
+- [ ] contacts?
+- [ ] any other?
+
+
+## FAQ
+
+**How can I set the default RemoteNickFormat for a protocol so users don't have to do it in a config file?**
+
+@42wim?
+
+**Why on Slack I see bot name instead of remote username?**
+
+Check if you:
+- [ ] did set `Message.Username` on the message being relayed
+- [ ] did set `RemoteNickFormat` in config file
+
+**Sending message to the bridge don't work**
+
+- [ ] Channels must match. While sending the message to the bridge make sure that you set the `config.Message.Channel` field to channel as it is mentioned in the config file.
\ No newline at end of file
diff --git a/docs/protocols/README.md b/docs/protocols/README.md
new file mode 100644
index 0000000000..1f962b404f
--- /dev/null
+++ b/docs/protocols/README.md
@@ -0,0 +1,130 @@
+# Supported protocols
+
+Matterbridge supports many protocols, although not all of them support all features. Here's a list of officially-maintained and 3rd-party-maintained networks for matterbridge.
+
+## Natively supported
+
+- [Discord](https://discordapp.com)
+ - Matterbridge docs:
+ - [discord docs](discord/)
+ - [discord settings](discord/settings.md)
+ - Channel format:
+ - by name: `channel_name` (without the leading `#`)
+ - by ID: `ID:channel_id`
+- [IRC](http://www.mirc.com/servers.html)
+ - Matterbridge docs:
+ - [irc docs](irc/)
+ - [irc settings](irc/settings.md)
+ - Channel format: `#channel_name` (it's all lowercase, and don't forget the leading `#`)
+- [Jabber](https://joinjabber.org/) is the same as XMPP
+ - Matterbridge docs:
+ - [xmpp docs](xmpp/)
+ - [xmpp settings](xmpp/settings.md)
+ - Channel format: `channel_name` (for `channel_name@muc.server.org` where `muc.server.org` has been configured as `Muc` for the corresponding xmpp account)
+- [Keybase](https://keybase.io)
+ - Matterbridge [keybase docs](keybase/)
+ - Channel format: `channel_name` (without the leading `#`), or `general` if your team doesn't have multiple channels
+- [Matrix](https://matrix.org)
+ - Matterbridge docs:
+ - [matrix docs](matrix/)
+ - [matrix settings](matrix/settings.md)
+ - Channel format: `#channel_name:server.org`
+- [Mattermost](https://github.com/mattermost/mattermost-server/)
+ - Matterbridge docs:
+ - [matterbridge docs](matterbridge/)
+ - [matterbridge settings](matterbridge/settings.md)
+ - Channel format:
+ - by name: `channel_name` as seen in the URL `https://yourmattermostserver/yourteam/channels/channel_name`
+ - by ID: `ID:channel_id`
+- [Microsoft Teams](https://teams.microsoft.com)
+ - Matterbridge [msteams docs](msteams/)
+ - Channel format: `19:82caxx@thread.skype` as seen in the URL `?threadId=19:82caxx@thread.skype`
+- [Mumble](https://www.mumble.info/)
+ - Matterbridge [mumble docs](mumble/)
+ - Channel format: `channel_id` as seen in the channel's `Edit` window
+- [Nextcloud Talk](https://nextcloud.com/talk/)
+ - Matterbridge [nctalk docs](nctalk/)
+ - Channel format: `channel_id` as seen at the end of URL (eg. `xs25tz5y`)
+- [Rocket.chat](https://rocket.chat)
+ - Matterbridge docs:
+ - [rocketchat docs](rocketchat/)
+ - [rocketchat settings](rocketchat/settings.md)
+ - Channel format: `#channel_name` (don't forget the leading `#`, even on private channels)
+- [Slack](https://slack.com)
+ - Matterbridge docs:
+ - [slack docs](slack/)
+ - [slack settings](slack/settings.md)
+ - Channel format:
+ - by name: `channel_name` (without the leading `#`)
+ - by ID: `ID:channel_id` (does not work with webhooks!)
+- [Ssh-chat](https://github.com/shazow/ssh-chat)
+ - Matterbridge [sshchat docs](sshchat/)
+ - Channel format: Only a single `sshchat` channel is supported
+- [Telegram](https://telegram.org)
+ - Matterbridge docs:
+ - [telegram docs](telegram/)
+ - [telegram settings](telegram/settings.md)
+ - Channel format:
+ - for channels/groups: `-channel_id` where `channel_id` is a large number (see FAQ)
+ - for forum topics (sub-groups): `-100channel_id/topic_id` (see FAQ), except the first `General` topic which is `-100channel_id` (**not** `-100channel_id/1`)
+- [Twitch](https://twitch.tv)
+ - Matterbridge [twitch docs](twitch/)
+ - Channel format: `#channel_name` (it's all lowercase, and don't forget the leading `#`)
+- [VK](https://vk.com/)
+ - Matterbridge [vk docs](vk/)
+ - Channel format: `channel_id` (see FAQ)
+- [WhatsApp](https://www.whatsapp.com/)
+ - Matterbridge docs:
+ - [whatsapp docs](whatsapp/)
+ - [whatsapp settings](whatsapp/settings.md)
+ - Channel format:
+ - by JID: `channel_id@g.us` (if `Channel=""`, matterbridge will list all channels known to the bot)
+ - by name: `channel_name` (**not recommended**, and matterbridge will warn you against it because group names can change over time)
+- [XMPP](https://xmpp.org)
+ - Matterbridge docs:
+ - [xmpp docs](xmpp/)
+ - [xmpp settings](xmpp/settings.md)
+ - Channel format: `channel_name` (for `channel_name@muc.server.org` where `muc.server.org` has been configured as `Muc` for the corresponding xmpp account)
+- [Zulip](https://zulipchat.com)
+ - Matterbridge docs:
+ - [zulip docs](zulip/)
+ - [zulip settings](zulip/settings.md)
+ - Channel format: `stream/topic:channel_name` (where `channel_name` has no leading `#`)
+
+## Dropped official support
+
+- [Gitter](https://gitter.im)
+ - Has moved to matrix protocol
+- [Harmony](https://harmonyapp.io)
+ - Does not exist anymore?
+
+- [Steam](https://store.steampowered.com/)
+ - Not supported anymore, see [here](https://github.com/Philipp15b/go-steam/issues/94) for more info.
+
+## 3rd party via matterbridge api
+
+- [Delta Chat](https://github.com/deltachat-bot/matterdelta)
+- [Minecraft](https://github.com/raws/mattercraft)
+- [Minecraft](https://gitlab.com/Programie/MatterBukkit)
+- [MatterLink](https://github.com/elytra/MatterLink) (Matterbridge link for Minecraft Forge server chat, archived)
+- [MatterCraft](https://github.com/raws/mattercraft) (Matterbridge link for Minecraft Forge server chat)
+- [MatterBukkit](https://gitlab.com/Programie/MatterBukkit) (Matterbridge link for Minecraft Bukkit/Spigot server chat)
+- [pyCord](https://github.com/NikkyAI/pyCord) (crossplatform chatbot)
+- [Mattereddit](https://github.com/bonehurtingjuice/mattereddit) (Reddit chat support)
+- [ServUO-matterbridge](https://github.com/kuoushi/ServUO-Matterbridge) (A matterbridge connector for ServUO servers)
+- [beerchat](https://github.com/mt-mods/beerchat) (Matterbridge link for minetest)
+- [nextcloud talk](https://github.com/nextcloud/talk_matterbridge) (Integrates matterbridge in Nextcloud Talk)
+
+
+### Past 3rd party projects
+
+- [Discourse](https://github.com/DeclanHoare/matterbabble)
+- [Facebook messenger](https://github.com/powerjungle/fbridge-asyncio)
+- [Facebook messenger](https://github.com/VictorNine/fbridge)
+- [Minecraft](https://github.com/elytra/MatterLink)
+- [Reddit](https://github.com/bonehurtingjuice/mattereddit)
+- [MatterAMXX](https://github.com/andrewlindberg/MatterAMXX): [Counter-Strike, half-life and more](https://forums.alliedmods.net/showthread.php?t=319430)
+- [Vintage Story](https://github.com/NikkyAI/vs-matterbridge) (last commit: February 4th 2021)
+- [Ultima Online Emulator](https://github.com/kuoushi/ServUO-Matterbridge)
+- [Teamspeak](https://github.com/Archeb/ts-matterbridge)
+- [ts-matterbridge](https://github.com/Archeb/ts-matterbridge) (Integrate teamspeak chat with matterbridge) (archived September 25th 2022)
diff --git a/docs/protocols/discord/README.md b/docs/protocols/discord/README.md
new file mode 100644
index 0000000000..cb4d978e02
--- /dev/null
+++ b/docs/protocols/discord/README.md
@@ -0,0 +1,131 @@
+# Discord
+
+- Status: ???
+- Maintainers: ???
+- Features: ???
+
+## Configuration
+
+> [!TIP]
+> For detailed information about discord settings, see [settings.md](settings.md)
+
+**Basic configuration example:**
+
+```toml
+[discord]
+[discord.mydiscord]
+RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
+Token="######"
+Server="name or uid of guild"
+AutoWebhooks=true
+# Map threads from other bridges on discord replies
+PreserveThreading=true
+```
+
+## FAQ
+
+### How to create a discord bot token for matterbridge?
+
+See [account.md](account.md).
+
+### Username/avatar spoofing
+
+[Creating a message](https://discordapp.com/developers/docs/resources/channel#create-message) via a user's API token (the basic configuration above) only lets Matterbridge post with the user/avatar that generated the token. But [executing a webhook](https://discordapp.com/developers/docs/resources/webhook#execute-webhook) can set any username and avatar URL.
+
+If you grant the bot the "Manage Webhooks" permission, it will automatically load and create webhooks in every bridged channel. You can even grant that permission on specific channels, if you don't want to give it global permission.
+
+1. Server Settings -> Roles
+2. Select your app's role (see [here](https://support.discord.com/hc/en-us/articles/206029707-How-do-I-set-up-Permissions-) for more info about how to create roles)
+3. Grant "Manage Webhooks"
+
+Then, just provide `AutoWebhooks=true` for the Discord account settings, as shown below:
+
+```toml
+[discord]
+ [discord.mydiscord]
+ Token="######"
+ Server="Wumpus Technologies Inc."
+ AutoWebhooks=true
+```
+
+
+If you would like to create webhooks yourself, instead of letting the bot manage them, follow these instructions.
+
+1. On Discord, go to Server Settings, then Integrations, then Webhooks -> "Create Webhook"
+2. Specify the name and channel, and copy the resulting webhook URL
+3. Paste in your gateway as `WebhookURL="https://discordapp.com/api/webhooks/529689699999999999/Da-H4RRY_P0-kjdsknkfgfjghf`
+
+Specify a webhook per channel:
+
+```toml
+[[gateway]]
+name="testing"
+enable=true
+
+[[gateway.inout]]
+account="slack.myworkspace"
+channel="testing"
+
+[[gateway.inout]]
+account="discord.myserver"
+channel="testing"
+
+ # Specify options for this gateway link
+ [gateway.inout.options]
+ WebhookURL="https://discordapp.com/api/webhooks/thing1/thing2"
+```
+
+
(personal account) | Legacy
(dedicated account) |
+|---|:---:|:---:|:---:|
+| Bridge Type | `slack` | `slack-legacy` | `slack-legacy` |
+| Token prefix | `xoxb-` | `xoxp-` | `xoxp-` |
+| Supported | ✅ | | ✅ |
+| 1. Auto-join channels | | ✅ | ✅ |
+| 3. Uses separate integration slot | :x: | | |
+| 4. User's outgoing messages relayed | ✅ | | ✅ |
+| 5. File uploads show as from... | bot | you | dedicated user |# Slack
+
+## Messages come from Slack API tester
+Did you set `RemoteNickFormat`?
+Try adding `RemoteNickFormat="<{NICK}>"`
+
+## Messages from other bots aren't getting relayed
+
+If you're using `WebhookURL` in your Slack configuration, this is normal.
+If you only have `Token` configuration, this could be a bug. Please open an issue.
diff --git a/docs/protocols/slack/account.md b/docs/protocols/slack/account.md
new file mode 100644
index 0000000000..1dfbee5b2f
--- /dev/null
+++ b/docs/protocols/slack/account.md
@@ -0,0 +1,105 @@
+# A Matterbridge integration for your Slack Workspace
+
+### Contents
+
+[Bot-based Setup](#bot-based-setup)
+[Legacy Setup](#legacy-setup)
+[Issues](#issues)
+
+---
+
+# Bot-based Setup
+Slack's model for bot users and other third-party integrations revolves around Slack Apps. They have been around for a while and are the only and default way of integrating services like Matterbridge going forward.
+
+Slack Docs: [Bot user tokens](https://api.slack.com/docs/token-types#bot)
+
+## Create the **classic** Slack App
+> **It's important that you create a "Slack App (Classic)". Don't use the "Create New App" button, and don't opt in to the "granular permissions" feature.**
+
+1. Navigate to Slack's ["Your Apps" page](https://api.slack.com/apps) and log into an account that has administrative permissions over the Slack Workspace (server) that you want to sync with Matterbridge.
+
+ 
+
+2. Use [_**THIS LINK**_](https://api.slack.com/apps?new_classic_app=1) to create a "Slack App (Classic)". Choose any name for your app and select the desired workspace, and then submit. :warning: _**USE THE LINK AND DON'T CLICK THE "Create New App" BUTTON**_.
+
+ 
+
+3. Navigate to the "App Home" page via the menu on the left. Click "Add Legacy Bot User", fill in the bot's details, and submit.
+
+ 
+
+## Grant scopes and install the Slack App
+
+You'll need to give your new Slack App (Classic), and thus the bot, the right permissions on your Slack Workspace.
+
+1. Click "OAuth & Permissions" in the menu on the left, and scroll down to the "Scopes" section. Don't click the prominent "Update Scopes" button. Instead, click "Add an OAuth Scope".
+
+ 
+
+2. Add the following permission scopes to your app:
+ * Modify your public channels (`channels:write`)
+ * Send messages as \ (`chat:write:bot`)
+ * Send messages as user (`chat:write:user`)
+ * Access user’s profile and workspace profile fields (`users.profile:read`)
+
+ 
+
+3. Scroll to the top of the same "OAuth & Permissions" page and click on the "Install to Workspace" (or "Reinstall to Workspace") button:
+
+ 
+
+Confirm that the authorizations you just added are OK:
+
+ 
+
+4. Once the App has been installed, the top of the `OAuth & Permissions` page will show two tokens: a "User OAuth Token" starting with `xoxp-...` and a "Bot User OAuth Token" starting with `xoxb-...`. You will need to use the second in your Matterbridge configuration:
+
+ 
+
+## Invite the bot to channels synced with Matterbridge
+
+The only thing that remains now is to set up the newly created bot on the Slack Workspace itself.
+
+1. On your Slack server you need to add the newly created bot to the relevant channels. Simply use the `/invite @` command in the chatbox.
+
+ 
+
+2. Repeat the invite process for each channel that Matterbridge needs to sync. :warning: Also, don't forget to do this in the future when you want to sync more channels.
+
+Now you are all set to go. Just configure and start your Matterbridge instance and see the messages flowing.
+
+ 
+
+
+# Legacy setup
+
+Update: 2020-04-03 - this setup is not working anymore. (See https://github.com/42wim/matterbridge/issues/964#issuecomment-607629250)
+
+🛑 This setup is not recommended and will disappear in future versions of Matterbridge. Please use it only if you are absolutely sure that you can not use the normal setup. Legacy tokens are, as their name indicates, a legacy feature and Slack can in the future **deprecate them at short notice** as they have a weak security model and **give access to a wide-range of privileged actions**. Always store your token securely!
+
+Slack Docs: [Legacy tokens](https://api.slack.com/docs/token-types#legacy)
+
+***
+
+In order to use this setup your channel configuration should use the `slack-legacy` setup instead of `slack`:
+```toml
+[slack-legacy]
+[slack-legacy.myslack]
+Token="xoxp-123456789-mytoken"
+```
+
+Steps to follow:
+1. First create a dedicated user (a new account specifically for the bot) in Slack.
+
+2. Next log in as this user and go to [the legacy tokens page](https://api.slack.com/custom-integrations/legacy-tokens) and click "Create token" for your team and your new user.
+ 
+ The token will look something like ```xoxp-123456789-LowerAndUPpercase```.
+
+3. Use the obtained token in your configuration file for the channel setup as in the example above.
+
+# Issues
+
+If you get the message: `ERROR slack: Connection failed "not_allowed_token_type" &errors.errorString{s:"not_allowed_token_type"}`
+
+For more information look at https://github.com/slackapi/node-slack-sdk/issues/921#issuecomment-570662540 and https://github.com/nlopes/slack/issues/654 and our issue https://github.com/42wim/matterbridge/issues/964
+
diff --git a/docs/protocols/slack/settings.md b/docs/protocols/slack/settings.md
new file mode 100644
index 0000000000..05c5d0c68a
--- /dev/null
+++ b/docs/protocols/slack/settings.md
@@ -0,0 +1,117 @@
+# Slack settings
+
+> [!TIP]
+> This page contains the details about slack settings. More general information about slack support in matterbridge can be found in [README.md](README.md).
+
+## Debug
+
+Extra slack specific debug info, warning this generates a lot of output.
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ Debug=true
+ ```
+
+## PreserveThreading
+
+Opportunistically preserve threaded replies between Slack channels.
+This only works if the parent message is still in the cache.
+Cache is flushed between restarts.
+Note: Not currently working on gateways with mixed bridges of
+both slack and slack-legacy type. Context in issue #624.
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ PreserveThreading=true
+ ```
+
+## ShowUserTyping
+
+Enable showing "user_typing" events from across gateway when available.
+Protip: Set your bot/user's "Full Name" to be "Someone (over chat bridge)",
+and so the message will say "Someone (over chat bridge) is typing".
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ ShowUserTyping=true
+ ```
+
+## SyncTopic
+
+Enable to sync topic/purpose changes from other bridges
+Only works syncing topic changes from slack bridge for now
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ SyncTopic=true
+ ```
+
+## Token
+
+Token to connect with the Slack API
+
+- Setting: **REQUIRED** (when not using webhooks)
+- Format: *string*
+- Example:
+ ```toml
+ Token="yourslacktoken"
+ ```
+
+### IconURL
+
+> [!WARNING]
+> NOT RECOMMENDED TO USE INCOMING/OUTGOING WEBHOOK.
+> USE DEDICATED BOT USER WHEN POSSIBLE!
+
+Icon that will be showed in slack.
+The string "{NICK}" (case sensitive) will be replaced by the actual nick / username.
+The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge.
+The string "{LABEL}" (case sensitive) will be replaced by label= field of the sending bridge.
+The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge.
+
+- Setting: **OPTIONAL**
+- Format: *string*
+- Example:
+ ```toml
+ IconURL="https://robohash.org/{NICK}.png?size=48x48"
+ ```
+
+### WebhookBindAddress
+
+> [!WARNING]
+> NOT RECOMMENDED TO USE INCOMING/OUTGOING WEBHOOK.
+> USE DEDICATED BOT USER WHEN POSSIBLE!
+
+Address to listen on for outgoing webhook requests from slack.
+See account settings - integrations - outgoing webhooks on slack
+
+- Setting: **OPTIONAL**
+- Format: *string*
+- Example:
+ ```toml
+ WebhookBindAddress="0.0.0.0:9999"
+ ```
+
+### WebhookURL
+
+> [!WARNING]
+> NOT RECOMMENDED TO USE INCOMING/OUTGOING WEBHOOK.
+> USE DEDICATED BOT USER WHEN POSSIBLE!
+
+Url is your incoming webhook url as specified in slack.
+See account settings - integrations - incoming webhooks on slack
+
+- Setting: **OPTIONAL**
+- Format: *string*
+- Example:
+ ```toml
+ WebhookURL="https://hooks.slack.com/services/yourhook"
+ ```
diff --git a/docs/protocols/sshchat/README.md b/docs/protocols/sshchat/README.md
new file mode 100644
index 0000000000..095a8463e2
--- /dev/null
+++ b/docs/protocols/sshchat/README.md
@@ -0,0 +1,17 @@
+# SSHChat
+
+- Status: ???
+- Maintainers: ???
+- Features: ???
+
+> [!WARNING]
+> In the gateway setup you should set channel to "sshchat" in order for things to work properly.
+
+**Basic configuration example:**
+
+```toml
+[sshchat.mychat]
+Server="address:port" # eg "localhost:2022" or "1.2.3.4:22"
+Nick="matterbridge"
+RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
+```
diff --git a/docs/protocols/telegram/README.md b/docs/protocols/telegram/README.md
new file mode 100644
index 0000000000..316e58d07b
--- /dev/null
+++ b/docs/protocols/telegram/README.md
@@ -0,0 +1,123 @@
+# Telegram
+
+- Status: Working
+- Maintainers: @selfhoster1312
+- Features: ???
+
+## Configuration
+
+> [!TIP]
+> For detailed information about telegram settings, see [settings.md](settings.md)
+
+**Basic configuration example:**
+
+```toml
+[telegram.mytelegram]
+Token="Yourtokenhere"
+RemoteNickFormat="({PROTOCOL}) {NICK} "
+MessageFormat="HTMLNick"
+```
+
+## FAQ
+
+### How to get a token for my bot?
+
+See [account.md](account.md)
+
+### How to retrieve my Telegram chat ID?
+
+> [!WARNING]
+> So-called topics in "forums" have a different address format! See
+> dedicated FAQ answer about this.
+
+To retrive your ChatId, you can:
+
+- post `/chatId` in the Telegram chat, and the bot will reply the ID
+- from a desktop computer, navigate to your channel, and copy the numbers at the end of the URL
+- look for `Channel:"-XXXXXXX"` in `config.Message` in matterbridge debug log (where `-XXXXXXX` is your ChatId)
+
+### Does matterbridge support Telegram channels?
+
+"Channels" in telegram are read-only chatrooms where only admin can post. Adding a bot to a channel requires giving it administrator rights. If you feel comfortable doing that, please report if it works.
+
+### Why can't I invite my bot into my channel?
+
+As of September 2025, the Telegram web interface is bugged and will silently error when trying to invite a bot into a (read-only) channel as an ordinary member.
+
+Maybe adding it as an administrator directly works. Adding it from the mobile application works (it will prompt to make the bot administrator instead).
+
+### Limitations
+
+- The Telegram API does not report any changes **when messages are deleted** so Matterbridge is unable to remove any bridged messages after they've been sent (This will render many common spam solutions useless). Use regexp with the `IgnoreMessages=` field to remove any common spam messages. # Telegram
+
+### Matterbridge is not relaying messages from Telegram
+
+See
+* https://core.telegram.org/bots#privacy-mode
+* https://github.com/yagop/node-telegram-bot-api/issues/174#issuecomment-244632667
+
+If your bot is not getting messages:
+
+Disable privacy mode with @Botfather.
+
+* Go to [BotFather](https://t.me/botfather) send /setprivacy.
+* Select the username of the bot.
+* Select Disable.
+* Kick bot from chat if it's already in it.
+* Invite bot to chat.
+
+The order is important.
+
+### Matterbridge is not relay messages from other bots
+
+> Bots talking to each other could potentially get stuck in unwelcome loops. To avoid this, we decided that bots will not be able to see messages from other bots regardless of mode.
+
+https://core.telegram.org/bots/faq#why-doesn-39t-my-bot-see-messages-from-other-bots
+
+### Matterbridge is not relaying images/stickers/files from Telegram
+
+Because images/stickers/files are from non-public url's, you'll need to setup a [mediaserver](Mediaserver-setup-(advanced))
+
+### Matterbridge is not relaying messages to Telegram
+
+Did you enable `MessageFormat="HTML"` in your config?
+You could be sending invalid HTML. Set it to `MessageFormat=""`
+
+More info in https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample#L836-L838
+
+### Matterbridge is not deleting messages from Telegram to other bridges
+
+Telegram doesn't has "deleted messages" metadata, so we don't know which messages are deleted.
+
+### Users are shown as "unknown user"
+
+Telegram channels will always return unknown users. Telegram groups will show usernames if possible
+
+### How to use MediaConvertTgs with lottie?
+
+This requires the external dependency `lottie`, which can be installed like this:
+`pip install lottie cairosvg`
+https://github.com/42wim/matterbridge/issues/874
+
+Note that if you insist on using an ancient Python version like 3.5, the pip installation is slightly more complicated. Matterbridge expects `lottie_convert.py` to be in your `$PATH`; if that's not already the case, try putting this into your `~/.profile`:
+```
+PATH=$HOME/.local/bin:$PATH
+export PATH
+```
+
+If you encounter bugs with this, try to extract the Telegram sticker file and run lottie on it like this:
+`lottie_convert.py --input-format lottie file_1234_tgs.webp myoutput.webp`
+This might give you additional information about what's going on.
+
+### How to join a topic in a Telegram forum?
+
+What telegram calls a forum is a chatroom which has been split into several sub-rooms, much like a so-called Discord server or a Matrix space.
+
+Each topic then has a `message_thread_id` which is visible from the web interface after the usual ChatId. For example, you may see in your URL `/-XXXXXX/Y` where `-XXXXXX` is your ChatId and `Y` is the topic ID.
+
+Specifically when using topics (not normal groups), you need to add `100` between the `-` and the usual ChatId. For example, `-XXXXXX` becomes `-100XXXXXX`. Then you need to add the topic ID, like so: `-100XXXXXXX/Y`.
+
+> [!WARNING]
+> **The first topic created is an exception and should not have `/Y` added to the Channel configuration in your gateway. For this topic only, use `-100XXXXXX`.**
+
+This `100` magic number is to our knowledge not documented in the Telegram Bot API docs, but [has been observed in the wild](https://stackoverflow.com/questions/32423837/telegram-bot-how-to-get-a-group-chat-id) and has cost one matterbridge contributor more than their fair share of mental health points.
diff --git a/docs/protocols/telegram/account.md b/docs/protocols/telegram/account.md
new file mode 100644
index 0000000000..cb80047aff
--- /dev/null
+++ b/docs/protocols/telegram/account.md
@@ -0,0 +1,162 @@
+TODO: is this information up to date?
+
+See [here](https://core.telegram.org/bots#6-botfather) and [here](https://www.linkedin.com/pulse/telegram-bots-beginners-marco-frau).
+
+**Sequence within a BotFather chat:**
+
+> **You**: /setprivacy
+>
+> **BotFather**: Choose a bot to change group messages settings.
+>
+> **You**: @your_name_bot
+>
+> **BotFather**: 'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
+>
+> - 'Disable' - your bot will receive all messages that people send to groups.
+> - Current status is: ENABLED
+>
+> **You**: Disable
+>
+> **BotFather**: Success! The new status is: DISABLED. /help
+
+
+(copied from [this stack overflow answer](https://stackoverflow.com/a/45441585))
+
+
+## Tutorial
+
+This basic example will guide you through getting started on your first Telegram bridge.
+
+- Create your bot and retrieve your API token.
+- Make sure to disable privacy mode.
+- Add the bot to your Telegram group
+- Set up the Matterbridge configuration.
+
+### 1. Speak to the BotFather.
+
+Message the [BotFather](https://t.me/BotFather) bot and run the `/newbot` command to get started. Once you pick a name it will provide you with a `token` used to access the HTTP API.
+
+**Disable bot privacy**
+
+> **You**: /setprivacy
+>
+> **BotFather**: Choose a bot to change group messages settings.
+>
+> **You**: @your_name_bot
+>
+> **BotFather**: 'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username.
+>
+> - 'Disable' - your bot will receive all messages that people send to groups.
+> - Current status is: ENABLED
+>
+> **You**: Disable
+>
+> **BotFather**: Success! The new status is: DISABLED. /help
+
+Now add this newly created bot to the Telegram chat you're trying to bridge.
+
+### 2. Add your config to Matterbridge.
+
+Here is an example gateway bridging `Discord`<>`Telegram` which should be placed in your `matterbridge.toml` (or equivalent)
+
+```toml
+# /
+# SERVERS
+# /
+[telegram]
+ [telegram.mytelegram]
+ Token="your_token_from_botfather"
+ RemoteNickFormat="<{NICK}> " # How your message will be formatted when bridged.
+ MessageFormat="HTMLNick :"
+ QuoteFormat="{MESSAGE} (re @{QUOTENICK}: {QUOTEMESSAGE})"
+ QuoteLengthLimit=46 # Truncuate long quotes to prevent spammy bridged messages
+ IgnoreMessages="^/" # Don't bridge bot commands (as the responses will not be bridged)
+
+# /
+# GATEWAYS
+# /
+[[gateway]]
+name="YourUniqueGateWayName"
+enable=true
+
+ [[gateway.inout]]
+ account="telegram.mytelegram"
+ channel="-100xxx"
+
+ [[gateway.inout]]
+ account="discord.mydiscord"
+ channel="channel-name"
+```
+
+> See all possible settings [here](https://github.com/42wim/matterbridge/wiki/Settings#telegram)
+
+The easiest way to retrieve your channel id is to navigate to https://web.telegram.org/ and simply copy the numbers at the end of the hyperlink into the `xxx` position in the example snippet above.
+
+
+To add more nodes to this bridge, you simply need to add additional `[[gateway.inout]]` fields.
+
+Make sure to test your config with the `-debug` flag after each change.
+
+### Limitations
+
+- The Telegram API does not report any changes **when messages are deleted** so Matterbridge is unable to remove any bridged messages after they've been sent (This will render many common spam solutions useless). Use regexp with the `IgnoreMessages=` field to remove any common spam messages. # Telegram
+
+## Matterbridge is not relaying messages from Telegram
+
+See
+* https://core.telegram.org/bots#privacy-mode
+* https://github.com/yagop/node-telegram-bot-api/issues/174#issuecomment-244632667
+
+If your bot is not getting messages:
+
+Disable privacy mode with @Botfather.
+
+* Go to [BotFather](https://t.me/botfather) send /setprivacy.
+* Select the username of the bot.
+* Select Disable.
+* Kick bot from chat if it's already in it.
+* Invite bot to chat.
+
+The order is important.
+
+## Matterbridge is not relay messages from other bots
+
+> Bots talking to each other could potentially get stuck in unwelcome loops. To avoid this, we decided that bots will not be able to see messages from other bots regardless of mode.
+
+https://core.telegram.org/bots/faq#why-doesn-39t-my-bot-see-messages-from-other-bots
+
+## Matterbridge is not relaying images/stickers/files from Telegram
+
+Because images/stickers/files are from non-public url's, you'll need to setup a [mediaserver](Mediaserver-setup-(advanced))
+
+## Matterbridge is not relaying messages to Telegram
+
+Did you enable `MessageFormat="HTML"` in your config?
+You could be sending invalid HTML. Set it to `MessageFormat=""`
+
+More info in https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample#L836-L838
+
+## Matterbridge is not deleting messages from Telegram to other bridges
+
+Telegram doesn't has "deleted messages" metadata, so we don't know which messages are deleted.
+
+## Users are shown as "unknown user"
+
+Telegram channels will always return unknown users. Telegram groups will show usernames if possible
+
+## How to use MediaConvertTgs with lottie?
+
+This requires the external dependency `lottie`, which can be installed like this:
+`pip install lottie cairosvg`
+https://github.com/42wim/matterbridge/issues/874
+
+Note that if you insist on using an ancient Python version like 3.5, the pip installation is slightly more complicated. Matterbridge expects `lottie_convert.py` to be in your `$PATH`; if that's not already the case, try putting this into your `~/.profile`:
+```
+PATH=$HOME/.local/bin:$PATH
+export PATH
+```
+
+If you encounter bugs with this, try to extract the Telegram sticker file and run lottie on it like this:
+`lottie_convert.py --input-format lottie file_1234_tgs.webp myoutput.webp`
+This might give you additional information about what's going on.
+
diff --git a/docs/protocols/telegram/settings.md b/docs/protocols/telegram/settings.md
new file mode 100644
index 0000000000..4ccabf49b2
--- /dev/null
+++ b/docs/protocols/telegram/settings.md
@@ -0,0 +1,131 @@
+# Telegram settings
+
+> [!TIP]
+> This page contains the details about telegram settings. More general information about telegram support in matterbridge can be found in [README.md](README.md).
+
+## MediaConvertTgs
+
+Convert Tgs (Telegram animated sticker) images to some other file format before upload. See FAQ for setup instructions.
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *string*
+- Possible values:
+ - `"png"` (still-image)
+ - `"webp"` (animated webp)
+- Example:
+ ```toml
+ MediaConvertTgs="png"
+ ```
+
+## MediaConvertWebPToPNG
+
+Convert WebP images to PNG before upload to the media server or other bridges (for compatibility).
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ MediaConvertWebPToPNG=true
+ ```
+
+## MessageFormat
+
+TODO: is this only for outgoing messages?
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *string*
+- Possible values:
+ - [`"HTML"`](https://core.telegram.org/bots/api#html-style)
+ - [`"Markdown"`](https://core.telegram.org/bots/api#markdown-style). Deprecated, does not display links with underscores `_` correctly.
+ - [`"MarkdownV2"`](https://core.telegram.org/bots/api#markdownv2-style)
+ - `"HTMLNick"`. This only allows HTML for the nick, the message itself will be html-escaped.
+- Default: `""`
+- Example:
+ ```toml
+ MessageFormat="MarkdownV2"
+ ```
+
+## QuoteDisable
+
+Disable quoted/reply messages
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ QuoteDisable=true
+ ```
+
+## QuoteFormat
+
+Format quoted/reply messages
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *string*
+- Default: `"{MESSAGE} (re @{QUOTENICK}: {QUOTEMESSAGE})"`
+- Example:
+ ```toml
+ QuoteFormat="{@{QUOTENICK}, {MESSAGE}}"
+ ```
+
+## QuoteLengthLimit
+
+Limits {QUOTEMESSAGE} into integer characters specified in this.
+
+TODO: does this cut graphemes or bytes?
+
+- Setting: **OPTIONAL**
+- Format: *int*
+- Example:
+ ```toml
+ QuoteLengthLimit=46
+ ```
+
+## DisableWebPagePreview
+
+Disables link previews for links in messages
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ DisableWebPagePreview=true
+ ```
+
+## Token
+
+Token to connect with telegram API.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Token="Yourtokenhere"
+ ```
+
+## UseFirstName
+
+If enabled use the "First Name" as username. If this is empty use the Username
+If disabled use the "Username" as username. If this is empty use the First Name
+If all names are empty, username will be "unknown"
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ UseFirstName=true
+ ```
+
+## UseInsecureURL
+
+> [!WARNING]
+> If enabled this will relay GIF/stickers/documents and other attachments as URLs
+> Those URLs will contain your bot-token. This may not be what you want.
+> For now there is no secure way to relay GIF/stickers/documents without seeing your token.
+
+- Setting: **OPTIONAL**, **RELOADABLE**
+- Format: *boolean*
+- Example:
+ ```toml
+ UseInsecureURL=true
+ ```
diff --git a/docs/protocols/twitch/README.md b/docs/protocols/twitch/README.md
new file mode 100644
index 0000000000..a999941e1f
--- /dev/null
+++ b/docs/protocols/twitch/README.md
@@ -0,0 +1,37 @@
+# Twitch
+
+- Status: ???
+- Maintainers: ???
+- Features: ???
+
+## Configuration
+
+> [!WARNING]
+> Twitch gets A LOT OF messages in almost any chatroom and this will be an
+> issue for other bridges that will ratelimit/ban you.
+> So be sure to do this only in rooms with not much users
+
+> [!WARNING]
+> To relay messages to Twitch, The Twitch user will require mod powers
+> for the channel/streamer specified in the gateway settings.
+
+**Basic configuration example:**
+
+```toml
+[irc.twitch]
+RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
+Nick="yournick"
+Password="oauth:yourtoken"
+Server="irc.chat.twitch.tv:6697"
+UseTLS=true
+```
+
+## FAQ
+
+### How to get a Twitch OAuth token for my matterbridge bot?
+
+> [!WARNING]
+> The service we recommend strongly recommends against using it for more than
+> development/testing purposes.
+
+[Twitch Token Generator](https://twitchtokengenerator.com/) can generate OAuth tokens on demand for your bots.
diff --git a/docs/protocols/vk/README.md b/docs/protocols/vk/README.md
new file mode 100644
index 0000000000..53c2b3886b
--- /dev/null
+++ b/docs/protocols/vk/README.md
@@ -0,0 +1,34 @@
+# VK
+
+- Status: ???
+- Maintainers: ???
+- Features: ???
+
+## Configuration
+
+**Basic configuration example:**
+
+```toml
+[vk.myvk]
+# Access token
+Token="Yourtokenhere"
+```
+
+## FAQ
+
+### How to create an Access Token for my matterbridge bot?
+
+1. Create new Community
+2. Manage > API Usage > Create Token
+3. Select scope as in the screenshot
+
+
+
+4. Enable longpoll at version 5.126 and enable Message received event
+
+
+
+
+## How to get channel ID for vk for my matterbridge bot?
+
+Start matterbridge in debug mode, then send a message in the chat where the bot is. Look for the chat's `PeerID` (usually a number that starts from `2000000000`).
diff --git a/docs/protocols/whatsapp/README.md b/docs/protocols/whatsapp/README.md
new file mode 100644
index 0000000000..9b26c41288
--- /dev/null
+++ b/docs/protocols/whatsapp/README.md
@@ -0,0 +1,57 @@
+# Whatsapp
+
+- Status: ???
+- Maintainers: ???
+- Features: ???
+
+## Configuration
+
+> [!TIP]
+> For detailed information about whatsapp settings, see [settings.md](settings.md)
+
+**Basic configuration example:**
+
+```toml
+[whatsapp.mywhatsapp]
+RemoteNickFormat="[{PROTOCOL}] @{NICK}: "
+# Get a disposable SIM card
+Number="+48111222333"
+# See FAQ
+SessionFile="session-48111222333.gob"
+# If your terminal uses a light color scheme, uncommebt below
+#QrOnWhiteTerminal=true
+```
+
+## FAQ
+
+### What is the QR-code about?
+
+The QR-Code is created by matterbridge on the terminal: It's the way WhatsApp authenticates any WA-Web session (which the bridge is using). At startup, matterbridge will prompt a QR-code for about 1 minute that you have to scan from your WA-instance (on your phone or android-VM). To scan it, go to Settings > WhatsApp Web in your WA client (if you run a VM, you may need to connect your webcam, or make a virtual one, see link above):
+
+
+
+### How to set the WA-channel in the configuration file of matterbridge?
+
+To setup a gateway between two protocols in matterbridge, you need to specify a channel for WA that should be bridged. The chat/group titles you see in WA won't work (e.g. from the screenshot above, "Test" won't work). Fortunately, matterbridge will complain about improper channel names and suggest the correct ones to you. In my case, it was a string of mainly numbers including the phone number of who created the group chat. Maybe there is a way to get this out of WA?
+(Currently, the WA example config does not explain this at all; it doesn't even mention the gateway part.)
+
+### How to set a nice channel name?
+
+Use `tengo`:
+
+Save below snippet as `myremotenickformat.tengo`
+```
+if channel == "48111222333-1549986983@g.us" {
+ result = "[CfP #Code for Pakistan] @"+nick
+}
+```
+Add `RemoteNickFormat="{TENGO}"` to the specific bridge
+
+and add the following in matterbridge.toml
+
+```
+[tengo]
+RemoteNickFormat="myremotenickformat.tengo"
+```
+
+For context see: https://github.com/42wim/matterbridge/issues/725
diff --git a/docs/protocols/whatsapp/settings.md b/docs/protocols/whatsapp/settings.md
new file mode 100644
index 0000000000..474292e97a
--- /dev/null
+++ b/docs/protocols/whatsapp/settings.md
@@ -0,0 +1,42 @@
+# WhatsApp settings
+
+> [!TIP]
+> This page contains the details about whatsapp settings. More general information about whatsapp support in matterbridge can be found in [README.md](README.md).
+
+## Number
+
+Number you will use as a relay bot. Tip: Get some disposable sim card, don't rely on your own number.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Number="+48111222333"
+ ```
+
+## QrOnWhiteTerminal
+
+If your terminal is white we need to invert QR code in order for it to be scanned properly
+
+- Setting: **OPTIONAL**
+- Format: *boolean*
+- Example:
+ ```toml
+ QrOnWhiteTerminal=true
+ ```
+
+## SessionFile
+
+First time that you login you will need to scan QR code, then credentials will
+be saved in a session file. If you do not set a `SessionFile`, you will need
+to scan your QR code on every restart.
+
+Unless this option is set, the Whatsapp login session is stored only in memory
+until restarting matterbridge.
+
+- Setting: **OPTIONAL**
+- Format: *string*
+- Example:
+ ```toml
+ SessionFile="session-48111222333.gob"
+ ```
diff --git a/docs/protocols/xmpp/README.md b/docs/protocols/xmpp/README.md
new file mode 100644
index 0000000000..59d6b61194
--- /dev/null
+++ b/docs/protocols/xmpp/README.md
@@ -0,0 +1,31 @@
+# XMPP
+
+- Status: Working
+- Maintainers: @poVoq, @selfhoster1312
+- Features:
+ - attachments: incoming/outgoing
+
+> [!NOTE]
+> XMPP (the protocol) is also known as Jabber (the open federation). These
+> two terms are used interchangeably. To learn more about Jabber/XMPP,
+> see [joinjabber.org](https://joinjabber.org/).
+
+> [!WARNING]
+> **Create a dedicated user first. It will not relay messages from yourself if you use your account**
+
+## Configuration
+
+> [!TIP]
+> For detailed information about xmpp settings, see [settings.md](settings.md)
+
+**Basic configuration example:**
+
+```toml
+[xmpp.myxmpp]
+RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
+Server="jabber.example.com:5222"
+Jid="user@example.com"
+Password="yourpass"
+Muc="conference.jabber.example.com"
+Nick="xmppbot"
+```
diff --git a/docs/protocols/xmpp/settings.md b/docs/protocols/xmpp/settings.md
new file mode 100644
index 0000000000..5b8ff067cc
--- /dev/null
+++ b/docs/protocols/xmpp/settings.md
@@ -0,0 +1,83 @@
+# XMPP settings
+
+> [!TIP]
+> This page contains the details about xmpp settings. More general information about xmpp support in matterbridge can be found in [README.md](README.md).
+
+> [!NOTE]
+> XMPP (the protocol) is also known as Jabber (the open federation). These
+> two terms are used interchangeably. To learn more about Jabber/XMPP,
+> see [joinjabber.org](https://joinjabber.org/).
+
+## Jid
+
+Jabber Identifier, the XMPP login for matterbridge's account.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Jid="user@example.com"
+ ```
+
+## MUC
+
+The Multi User Chat (MUC) server where the bot will find the defined gateway
+channels. At the moment, bridging a room on a different MUC requires creating
+a separate account entry in the configuration.
+
+TODO: test if a matterbridge instance can be connected to the same account
+ with two configurations at the same time; this is allowed by XMPP
+ protocol but requires matterbridge to behave properly in terms
+ of XMPP protocol
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Muc="conference.jabber.example.com"
+ ```
+
+## Nick
+
+Your nick in the rooms
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Nick="xmppbot"
+ ```
+
+## NoTLS
+
+Enable this to make an insecure plaintext connection to your xmpp server.
+This is usually not permitted by XMPP servers even on localhost.
+
+- Setting: **OPTIONAL**
+- Format: *boolean*
+- Example:
+ ```toml
+ NoTLS=true
+ ```
+
+## Password
+
+Password for the Jid's account.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Password="yourpass"
+ ```
+
+## Server
+
+XMPP server to connect to.
+
+- Setting: **REQUIRED**
+- Format: *string* (hostname:port)
+- Example:
+ ```toml
+ Server="jabber.example.com:5222"
+ ```
diff --git a/docs/protocols/zulip/README.md b/docs/protocols/zulip/README.md
new file mode 100644
index 0000000000..8c19c89aaa
--- /dev/null
+++ b/docs/protocols/zulip/README.md
@@ -0,0 +1,38 @@
+# Zulip
+
+- Status: ???
+- Maintainers: ???
+- Features:
+ - attachments: no
+
+## Configuration
+
+> [!TIP]
+> For detailed information about zulip settings, see [settings.md](settings.md)
+
+> [!WARNING]
+> Don't forget to make sure that the streams you want to bridge exit and
+> are subscribed to by the new bot. Otherwise, things will break. You can
+> subscribe the bot using the stream's settings, under "Stream membership".
+
+**Basic configuration example:**
+
+```toml
+[zulip.myzulip]
+RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
+Token="Yourtokenhere"
+#Login is the Username of the bot you've got when creating the bot
+Login="yourbot-bot@yourserver.com"
+#The URL of your zulip server
+Server="https://yourserver.com"
+```
+
+## FAQ
+
+### How to generate the zulip token for my matterbridge bot?
+
+1. Navigate to Settings () -> Your bots -> Add a new bot.
+2. Select Generic for bot type, fill out the form and click on Create bot.
+3. Token is the API key, you've got when creating the bot
+
+
diff --git a/docs/protocols/zulip/settings.md b/docs/protocols/zulip/settings.md
new file mode 100644
index 0000000000..4be2ce4459
--- /dev/null
+++ b/docs/protocols/zulip/settings.md
@@ -0,0 +1,39 @@
+# Zulip settings
+
+> [!TIP]
+> This page contains the details about zulip settings. More general information about zulip support in matterbridge can be found in [README.md](README.md).
+
+## Login
+
+Username of the bot, normally called yourbot-bot@yourserver.zulipchat.com.
+
+See `username` in `Settings` → `Your bots`.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Login="yourbot-bot@yourserver.zulipchat.com"
+ ```
+
+## Server
+
+URL of your zulip instance.
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Server="https://yourserver.zulipchat.com"
+ ```
+
+## Token
+
+Zulip API token (called bot API key in `Settings` → `Your bots`).
+
+- Setting: **REQUIRED**
+- Format: *string*
+- Example:
+ ```toml
+ Token="Yourtokenhere"
+ ```
diff --git a/docs/running.md b/docs/running.md
new file mode 100644
index 0000000000..8b62d8fefb
--- /dev/null
+++ b/docs/running.md
@@ -0,0 +1,84 @@
+# Running matterbridge
+
+This page is about running matterbridge from CLI, or as a service. For setup, see [setup.md](setup.md). For configuration, see [config.md](config.md).
+
+## Command-line
+
+```bash
+Usage of ./matterbridge:
+ -conf string
+ config file (default "matterbridge.toml")
+ -debug
+ enable debug
+ -gops
+ enable gops agent
+ -version
+ show version
+```
+
+## docker-compose image
+
+From the directory where you have your configuration `matterbridge.toml`, create a file named `docker-compose.yml`:
+
+```yml
+version: '3.7'
+services:
+ matterbridge:
+ image: 42wim/matterbridge:stable
+ restart: unless-stopped
+ volumes:
+ - ./matterbridge.toml:/etc/matterbridge/matterbridge.toml:ro
+# command: -debug
+```
+
+Afterwards, start the container with `docker-compose up -d`.
+
+# Service integrations
+
+## systemd
+
+A sample systemd unit to run matterbridge in the background, restarting if necessary.
+
+`/etc/systemd/system/matterbridge.service`, remember to correct `ExecStart=` and `User=`
+
+```dosini
+[Unit]
+Description=Matterbridge daemon
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/path/to/your/matterbridge/binary -conf /path/to/your/matterbridge.toml
+Restart=always
+RestartSec=5s
+User=matterbridge
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Reload systemd with `sudo systemctl daemon-reload`, enable on system start and now with `sudo systemctl enable --now matterbridge.service`
+
+## OpenRC
+
+A sample OpenRC service to run matterbridge in the background.
+
+/etc/init.d/matterbridge
+```sh
+#!/sbin/openrc-run
+# Copyright 2021-2022 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+command=/usr/bin/matterbridge
+command_args="-conf ${MATTERBRIDGE_CONF:-/etc/matterbridge/matterbridge.toml} ${MATTERBRIDGE_ARGS}"
+command_user="mattermost:mattermost"
+pidfile="/run/${RC_SVCNAME}.pid"
+command_background=1
+
+depend() {
+ need net
+}
+```
+Enable with `sudo rc-update add matterbridge default`
+
+Start with `sudo rc-service matterbridge start`
diff --git a/docs/settings.md b/docs/settings.md
new file mode 100644
index 0000000000..51e005d028
--- /dev/null
+++ b/docs/settings.md
@@ -0,0 +1,258 @@
+# Settings
+
+On this page you will find information about global matterbridge settings. Most of these settings can be applied to specific gateways, and those marked **GENERAL** can be placed in the `[general]` configuration dictionary for setting it across all gateways.
+
+> [!TIP]
+> Settings specific to a certain protocol can be found in the corresponding folder in the
+> [protocols/](protocols/) documentation folder. API settings for can be found in the
+> [api/](api/) documentation folder.
+
+# Info
+
+* **OPTIONAL:** this setting isn't enabled by default.
+* **RELOADABLE:** this setting can be reloaded by editing the configuration. No restart of matterbridge is required.
+* **ALL:** this setting is usable with all bridges.
+* **GENERAL:** this setting can be also set under `[general]` which means it's active for all bridges.
+
+# Shared
+Only settings which have the `ALL` setting are usable for all bridges.
+
+## EditDisable
+Disable sending of edits to other bridges
+
+Setting: OPTIONAL, RELOADABLE \
+Format: boolean \
+Example: enable it
+
+`EditDisable=true`
+
+## EditSuffix
+Message to be appended to every edited message
+
+Setting: OPTIONAL, RELOADABLE \
+Format: string \
+Example:
+
+`EditSuffix=" (edited)"`
+
+## IgnoreMessages
+Messages you want to ignore.\
+Messages matching these regexp will be ignored and not sent to other bridges.\
+See https://regex-golang.appspot.com/assets/html/index.html for more regex info.
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: space seperated regex string \
+Example: ignores messages starting with ~~ or messages containing badword
+
+`IgnoreMessages="^~~ badword"`
+
+## IgnoreNicks
+Nicks you want to ignore.\
+Messages from those users will not be sent to other bridges.
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: space seperated regex string \
+Example: ignore messages from ircspammer1 and ircspammer2
+
+`IgnoreNicks="ircspammer1 ircspammer2"`
+
+## Label
+Extra label that can be used in the `RemoteNickFormat`
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: string \
+Example: add the label `mychat`
+
+`Label="mychat"`
+
+## PrefixMessagesWithNick
+Whether to prefix messages from other bridges to with the sender's nick.
+Useful if username overrides for incoming webhooks isn't enabled.
+ If you set PrefixMessagesWithNick to true, each message
+from other bridges will by default be prefixed by "bridge-" + nick. You can,
+however, modify how the messages appear, by setting (and modifying) `RemoteNickFormat`
+
+Setting: OPTIONAL, RELOADABLE \
+Format: boolean \
+Example:
+
+`PrefixMessagesWithNick=true`
+
+
+## RemoteNickFormat
+Defines how remote users appear on this bridge. \
+The string "{NICK}" (case sensitive) will be replaced by the actual nick / username. \
+The string "{BRIDGE}" (case sensitive) will be replaced by the sending bridge. \
+The string "{LABEL}" (case sensitive) will be replaced by label= field of the sending bridge. \
+The string "{PROTOCOL}" (case sensitive) will be replaced by the protocol used by the bridge. \
+The string "{GATEWAY}" (case sensitive) will be replaced by the origin gateway name that is replicating the message. \
+The string "{CHANNEL}" (case sensitive) will be replaced by the origin channel name used by the bridge. \
+The string "{TENGO}" (case sensitive) will be replaced by the output of the RemoteNickFormat script under `[tengo]` \
+The string "{NOPINGNICK}" (case sensitive) will be replaced by the actual nick / username, but with a ZWSP inside the nick, so the irc user with the same nick won't get pinged. See https://github.com/42wim/matterbridge/issues/175 for more information
+
+Setting: OPTIONAL, RELOADABLE, GENERAL, ALL \
+Format: string \
+Example: add PROTOCOL and NICK
+
+`RemoteNickFormat="[{PROTOCOL}] <{NICK}> "`
+
+## ReplaceMessages
+Messages you want to replace. \
+It replaces outgoing messages from the bridge. \
+So you need to place it by the sending bridge definition.\
+Regular expressions supported.
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: [ ["from1","to1"],["from2","to2"] ] \
+Example: this replaces cat => dog and sleep => awake
+
+`ReplaceMessages=[ ["cat","dog"], ["sleep","awake"] ]`
+
+## ReplaceNicks
+Nicks you want to replace. \
+See `ReplaceMessages` for syntax
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: [ ["from1","to1"],["from2","to2"] ] \
+Example: this replaces user-- => user
+
+`ReplaceNicks=[ ["user--","user"] ]`
+
+## ShowJoinPart
+Enable to show users joins/parts from other bridges \
+Currently works for messages from the following bridges: irc, mattermost, slack
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: boolean \
+Example: enable it
+
+`ShowJoinPart=true`
+
+## ShowTopicChange
+Enable to show topic changes from other bridges. \
+Only works hiding/show topic changes from slack bridge for now.
+
+Setting: OPTIONAL, RELOADABLE, ALL \
+Format: boolean \
+Example: enable it
+
+`ShowTopicChange=true`
+
+## SkipTLSVerify
+Enable to not verify the certificate on your server.
+e.g. when using selfsigned certificates
+
+Setting: OPTIONAL \
+Format: boolean \
+Example: enable it
+
+`SkipTLSVerify=true`
+
+## StripNick
+StripNick only allows alphanumerical nicks. See https://github.com/42wim/matterbridge/issues/285
+It will strip other characters from the nick
+
+Setting: OPTIONAL, RELOADABLE, GENERAL, ALL \
+Format: boolean \
+Example: enable it
+
+`StripNick=true`
+
+## UseLocalAvatar
+
+UseLocalAvatar specifies source bridges for which an avatar should be 'guessed' when an incoming message has no avatar. This works by comparing the username of the message to an existing Discord user, and using the avatar of the Discord user. (Substitute "Discord" with another platform, if used on another platform.)
+
+On Discord, this only works if `WebhookURL` is set (AND the message has no avatar).
+
+At the moment, this setting is only available for Discord.
+
+Setting: OPTIONAL, RELOADABLE
+Format: `["gateway.account1", "gateway.account2", "gateway"]`
+Example: `["irc"]` - this example will guess the avatar coming from the `irc` platform
+
+# General
+
+Configuration that can be set under `[general]`
+
+## IgnoreFailureOnStart
+Allows you to ignore failing bridges on startup.
+Matterbridge will disable the failed bridge and continue with the other ones. \
+Context: https://github.com/42wim/matterbridge/issues/455
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: boolean \
+Example: enable it
+
+`IgnoreFailureOnStart=true`
+
+## LogFile
+
+LogFile defines the location of a file to write logs into, rather than stdout.
+Logging will still happen on stdout if the file cannot be open for #writing, or if the value is empty.
+Note that the log won't roll, so you might want to use logrotate(8) with this feature.
+
+Setting: OPTIONAL, GENERAL \
+Format: string \
+Example:
+
+`LogFile="/var/log/matterbridge.log"`
+
+## MediaDownloadBlacklist
+Allows you to blacklist specific files from being downloaded.
+Filenames matching these regexp will not be download/uploaded to the mediaserver. \
+You can use regex for this, see https://regex-golang.appspot.com/assets/html/index.html for more regex info
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: string array \
+Example: do not upload html and htm extension
+
+`MediaDownloadBlacklist=[".html$",".htm$"]`
+
+## MediaDownloadPath
+MediaDownloadPath is the filesystem path where the media file will be placed, instead of uploaded, for if Matterbridge has write access to the directory your webserver is serving. \
+It is an alternative to MediaServerUpload.
+More information https://github.com/42wim/matterbridge/wiki/Mediaserver-setup-%28advanced%29
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: string \
+Example:
+
+`MediaDownloadPath="/srv/http/yourserver.com/public/download"`
+
+## MediaDownloadSize
+Maximum size in bytes matterbridge will download for use with (`MediaServerUpload` and `MediaDownloadPath`)
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: int \
+Default: 10000000 (1 megabyte) \
+Example:
+
+`MediaDownloadSize=1000000`
+
+
+## MediaServerDownload
+The MediaServerDownload will be used so that bridges without native uploading support:
+gitter, irc and xmpp will be shown links to the files on MediaServerDownload
+More information https://github.com/42wim/matterbridge/wiki/Mediaserver-setup-%28advanced%29
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: string \
+Example:
+
+`MediaServerDownload="https://youserver.com/download"`
+
+
+## MediaServerUpload
+Used for uploading images/files/video to a remote "mediaserver" (a webserver like caddy for example). \
+When configured images/files uploaded on bridges like mattermost, slack, telegram will be
+downloaded and uploaded again to MediaServerUpload URL.
+More information https://github.com/42wim/matterbridge/wiki/Mediaserver-setup-%28advanced%29
+
+Setting: OPTIONAL, RELOADABLE, GENERAL \
+Format: string \
+Example:
+
+`MediaServerUpload="https://user:pass@yourserver.com/upload"`
+
+## RemoteNickFormat
+See [RemoteNickFormat](#RemoteNickFormat)
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 0000000000..94b6c90a93
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,22 @@
+# Installing / upgrading matterbridge
+
+## Binaries
+
+- Latest stable release [v1.26.0](https://github.com/42wim/matterbridge/releases/latest)
+- Development releases (follows master) can be downloaded [here](https://github.com/42wim/matterbridge/actions) selecting the latest green build and then artifacts.
+
+To install or upgrade just download the latest [binary](https://github.com/42wim/matterbridge/releases/latest). On \*nix platforms you may need to make the binary executable - you can do this by running `chmod a+x` on the binary (example: `chmod a+x matterbridge-1.24.1-linux-64bit`). After downloading (and making the binary executable, if necessary), follow the instructions on the [howto](https://github.com/42wim/matterbridge/wiki/How-to-create-your-config) for a step by step walkthrough for creating your configuration.
+
+## Packages
+
+- [Overview](https://repology.org/metapackage/matterbridge/versions)
+- [snap](https://snapcraft.io/matterbridge)
+- [scoop](https://github.com/42wim/scoop-bucket)
+
+## Compiling from source
+
+See [compiling.md].
+
+## Getting started
+
+Now that matterbridge is setup, head over to [configuration.md] to find out how to get started.
diff --git a/docs/tutorials.md b/docs/tutorials.md
new file mode 100644
index 0000000000..f13d098c5f
--- /dev/null
+++ b/docs/tutorials.md
@@ -0,0 +1,14 @@
+# Tutorials for matterbridge
+
+- [matterbridge on kubernetes](https://medium.freecodecamp.org/using-kubernetes-to-deploy-a-chat-gateway-or-when-technology-works-like-its-supposed-to-a169a8cd69a3)
+-
+-
+-
+-
+-
+-
+-
+-
+-
+-
+- Youtube: [whatsapp - telegram bridging](https://www.youtube.com/watch?v=W-VXISoKtNc)