From 55114eea01d1c32ad546f524db9e4bcb3edff841 Mon Sep 17 00:00:00 2001 From: Wim Date: Sun, 14 Apr 2019 23:35:04 +0200 Subject: [PATCH] Add settings document --- Home.md | 11 +- How-to-create-your-config.md | 2 + Settings.md | 1286 ++++++++++++++++++++++++++++++++++ 3 files changed, 1295 insertions(+), 4 deletions(-) create mode 100644 Settings.md diff --git a/Home.md b/Home.md index cdfaa1d..07fbbe9 100644 --- a/Home.md +++ b/Home.md @@ -1,5 +1,11 @@ Welcome to the matterbridge wiki! +### Create your config +Some simple steps to create your configuration: [[How-to-create-your-config]] + +### Settings +All possible [[Settings]] + ### FAQ The [[FAQ]] @@ -9,10 +15,7 @@ See [[Api]] ### Features [[Features]] -### Create your config -Some simple steps to create your configuration: [[How-to-create-your-config]] - ### Screenshots Screenshots matrix/gitter/slack/discord/mattermost/irc ![](https://i.snag.gy/kKs309.jpg) -![](https://user-images.githubusercontent.com/849975/52647227-9c3a5300-2ee4-11e9-9c57-ea096473aba8.png) \ No newline at end of file +![](https://user-images.githubusercontent.com/849975/52647227-9c3a5300-2ee4-11e9-9c57-ea096473aba8.png) diff --git a/How-to-create-your-config.md b/How-to-create-your-config.md index 8847c50..dd09fc2 100644 --- a/How-to-create-your-config.md +++ b/How-to-create-your-config.md @@ -102,3 +102,5 @@ Run matterbridge ./matterbridge -conf matterbridge.toml ``` +### Step 8 optional +Look at more advanced [[Settings]] that you can add to your bridges. diff --git a/Settings.md b/Settings.md new file mode 100644 index 0000000..c06ed63 --- /dev/null +++ b/Settings.md @@ -0,0 +1,1286 @@ + + +- [Info](#info) +- [Shared](#shared) + - [EditDisable](#editdisable) + - [EditSuffix](#editsuffix) + - [IgnoreMessages](#ignoremessages) + - [IgnoreNicks](#ignorenicks) + - [Label](#label) + - [PrefixMessagesWithNick](#prefixmessageswithnick) + - [RemoteNickFormat](#remotenickformat) + - [ReplaceMessages](#replacemessages) + - [ReplaceNicks](#replacenicks) + - [ShowJoinPart](#showjoinpart) + - [ShowTopicChange](#showtopicchange) + - [SkipTLSVerify](#skiptlsverify) + - [StripNick](#stripnick) +- [General](#general) + - [IgnoreFailureOnStart](#ignorefailureonstart) + - [MediaDownloadBlacklist](#mediadownloadblacklist) + - [MediaDownloadPath](#mediadownloadpath) + - [MediaDownloadSize](#mediadownloadsize) + - [MediaServerDownload](#mediaserverdownload) + - [MediaServerUpload](#mediaserverupload) + - [RemoteNickFormat](#remotenickformat-1) +- [API](#api) + - [BindAddress *](#bindaddress-) + - [Buffer](#buffer) + - [Token](#token) +- [Discord](#discord) + - [Server *](#server-) + - [Token *](#token-) + - [ShowEmbeds](#showembeds) + - [UseUserName](#useusername) + - [UseDiscriminator](#usediscriminator) + - [WebhookURL](#webhookurl) + - [EditDisable](#editdisable-1) + - [EditSuffix](#editsuffix-1) +- [Gitter](#gitter) + - [Token *](#token--1) +- [IRC](#irc) + - [Charset](#charset) + - [ColorNicks](#colornicks) + - [MessageDelay](#messagedelay) + - [MessageLength](#messagelength) + - [MessageQueue](#messagequeue) + - [MessageSplit](#messagesplit) + - [Nick *](#nick-) + - [NickServNick](#nickservnick) + - [NickServPassword](#nickservpassword) + - [NickServUsername](#nickservusername) + - [NoSendJoinPart](#nosendjoinpart) + - [Password](#password) + - [RejoinDelay](#rejoindelay) + - [RunCommands](#runcommands) + - [Server *](#server--1) + - [SkipTLSVerify](#skiptlsverify-1) + - [UseSASL](#usesasl) + - [UseTLS](#usetls) +- [Matrix](#matrix) + - [Login *](#login-) + - [NoHomeServerSuffix](#nohomeserversuffix) + - [Password *](#password-) + - [PrefixMessagesWithNick](#prefixmessageswithnick-1) + - [Server *](#server--2) +- [Mattermost](#mattermost) + - [EditDisable](#editdisable-2) + - [EditSuffix](#editsuffix-2) + - [Login *](#login--1) + - [NoTLS](#notls) + - [Password *](#password--1) + - [Server *](#server--3) + - [Team *](#team-) + - [Token](#token-1) + - [Webhook options](#webhook-options) + - [WebhookURL](#webhookurl-1) + - [WebhookBindAddress](#webhookbindaddress) + - [IconURL](#iconurl) + - [PrefixMessagesWithNick](#prefixmessageswithnick-2) +- [RocketChat](#rocketchat) + - [Login *](#login--2) + - [Password *](#password--2) + - [Server *](#server--4) + - [SkipTLSVerify](#skiptlsverify-2) + - [Webhook options](#webhook-options-1) + - [WebhookBindAddress](#webhookbindaddress-1) + - [Nick](#nick) + - [WebhookURL](#webhookurl-2) +- [Slack](#slack) + - [Debug](#debug) + - [EditDisable](#editdisable-3) + - [EditSuffix](#editsuffix-3) + - [PrefixMessagesWithNick](#prefixmessageswithnick-3) + - [PreserveThreading](#preservethreading) + - [ShowUserTyping](#showusertyping) + - [SyncTopic](#synctopic) + - [Token *](#token--2) + - [Webhook options](#webhook-options-2) + - [IconURL](#iconurl-1) + - [WebhookBindAddress](#webhookbindaddress-2) + - [WebhookURL](#webhookurl-3) +- [Steam](#steam) + - [Authcode](#authcode) + - [Login *](#login--3) + - [Password *](#password--3) + - [PrefixMessagesWitNick](#prefixmessageswitnick) +- [Telegram](#telegram) + - [EditDisable](#editdisable-4) + - [EditSuffix](#editsuffix-4) + - [MediaConvertWebPToPNG](#mediaconvertwebptopng) + - [MessageFormat](#messageformat) + - [QuoteDisable](#quotedisable) + - [QuoteFormat](#quoteformat) + - [Token *](#token--3) + - [UseFirstName](#usefirstname) + - [UseInsecureURL](#useinsecureurl) +- [Tengo](#tengo) + - [Message](#message) + - [RemoteNickFormat](#remotenickformat-2) +- [Whatsapp](#whatsapp) + - [Number *](#number-) + - [QrOnWhiteTerminal](#qronwhiteterminal) + - [SessionFile](#sessionfile) +- [XMPP](#xmpp) + - [Jid *](#jid-) + - [MUC *](#muc-) + - [Nick *](#nick--1) + - [Password *](#password--4) + - [Server *](#server--5) + - [SkipTLSVerify](#skiptlsverify-3) +- [Zulip](#zulip) + - [Login *](#login--4) + - [Server *](#server--6) + - [Token *](#token--4) + + + +# 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. + +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` + +# 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` + + +## 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-%5Badvanced%5D + +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-%5Badvanced%5D + +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-%5Badvanced%5D + +Setting: OPTIONAL, RELOADABLE, GENERAL \ +Format: string \ +Example: + +`MediaServerUpload="https://user:pass@yourserver.com/upload"` + +## RemoteNickFormat +See [RemoteNickFormat](#RemoteNickFormat) + +# API +More info on https://github.com/42wim/matterbridge/wiki/Api + +## BindAddress * +Address to listen on for API + +Setting: REQUIRED \ +Format: string \ +Example: + +`BindAddress="127.0.0.1:4242"` + +## Buffer +Amount of messages to keep in memory + +Setting: OPTIONAL, RELOADABLE \ +Format: int \ +Default: 10 \ +Example: + +`Buffer=1000` + +## Token +Bearer token used for authentication +`curl -H "Authorization: Bearer token" http://localhost:4242/api/messages` +no authorization if token is empty + +Setting: OPTIONAL, RELOADABLE \ +Format: string \ +Example: + +`Token="mytoken"` + +# Discord +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Discord-(basic) + +## Server * +Name or uid of your server/guild + +Setting: REQUIRED \ +Format: string \ +Example: + +`Server="yourservername"` + +## Token * +Token to connect with Discord API +You can get your token by following the instructions on +https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token +If you want roles/groups mentions to be shown with names instead of ID, you'll need to give your bot the "Manage Roles" permission. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Token="Yourtokenhere"` + +## ShowEmbeds +Shows title, description and URL of embedded messages (sent by other bots) + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: + +`ShowEmbeds=true` + +## UseUserName +Shows the username instead of the server nickname + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: + +`UseUserName=true` + +## UseDiscriminator +Show `#xxxx` discriminator with `UseUserName` + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: + +`UseDiscriminator=true` + +## WebhookURL +Specify WebhookURL. If given, will relay messages using the Webhook, which gives a better look to messages. +This only works if you have one discord channel, if you have multiple discord channels you'll have to specify it in the gateway config + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookURL="Yourwebhooktokenhere"` + +## EditDisable + +See [EditDisable](#EditDisable) + +## EditSuffix + +See [EditSuffix](#EditSuffix) + + +# Gitter +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Gitter-(basic) + +## Token * +Token to connect with Gitter API. \ +You can get your token by going to https://developer.gitter.im/docs/welcome and SIGN IN. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Token="Yourtokenhere"` + +# IRC + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-IRC-(basic) + +## Charset +If you know your charset, you can specify it manually. \ +Otherwise it tries to detect this automatically. Select one below \ + "iso-8859-2:1987", "iso-8859-9:1989", "866", "latin9", "iso-8859-10:1992", "iso-ir-109", "hebrew", + "cp932", "iso-8859-15", "cp437", "utf-16be", "iso-8859-3:1988", "windows-1251", "utf16", "latin6", + "latin3", "iso-8859-1:1987", "iso-8859-9", "utf-16le", "big5", "cp819", "asmo-708", "utf-8", + "ibm437", "iso-ir-157", "iso-ir-144", "latin4", "850", "iso-8859-5", "iso-8859-5:1988", "l3", + "windows-31j", "utf8", "iso-8859-3", "437", "greek", "iso-8859-8", "l6", "l9-iso-8859-15", + "iso-8859-2", "latin2", "iso-ir-100", "iso-8859-6", "arabic", "iso-ir-148", "us-ascii", "x-sjis", + "utf16be", "iso-8859-8:1988", "utf16le", "l4", "utf-16", "iso-ir-138", "iso-8859-7", "iso-8859-7:1987", + "windows-1252", "l2", "koi8-r", "iso8859-1", "latin1", "ecma-114", "iso-ir-110", "elot-928", + "iso-ir-126", "iso-8859-1", "iso-ir-127", "cp850", "cyrillic", "greek8", "windows-1250", "iso-latin-1", + "l5", "ibm866", "cp866", "ms-kanji", "ibm850", "ecma-118", "iso-ir-101", "ibm819", "l1", "iso-8859-6:1987", + "latin5", "ascii", "sjis", "iso-8859-10", "iso-8859-4", "iso-8859-4:1988", "shift-jis + The select charset will be converted to utf-8 when sent to other bridges. + +Setting: OPTIONAL \ +Format: string \ +Example: + +`Charset="utf-8"` + +## ColorNicks +ColorNicks will show each nickname in a different color. +Only works in IRC right now. + +Setting: OPTIONAL, RELOADABLE \ +Format: bool \ +Example: enable it + +`ColorNicks=true` + + +## MessageDelay +Flood control. +Delay in milliseconds between each message send to the IRC server. + +Setting: OPTIONAL, RELOADABLE \ +Default: 1300 \ +Format: int \ +Example: + +`MessageDelay=1300` + +## MessageLength +Maximum length of message sent to irc server. If it exceeds +`` will be add to the message. + +Setting: OPTIONAL, RELOADABLE \ +Default: 400 \ +Format: int \ +Example: + +`MessageLength=400` + +## MessageQueue +Maximum amount of messages to hold in queue. If queue is full +messages will be dropped. +`` will be add to the message that fills the queue. + +Setting: OPTIONAL, RELOADABLE \ +Default: 30 \ +Format: int \ +Example: + +`MessageQueue=30` + +## MessageSplit +Split messages on `MessageLength` instead of showing the `` +WARNING: this could lead to flooding + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: enable it + +`MessageSplit=true` + +## Nick * +Your nick on irc. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Nick="matterbot"` + +## NickServNick +If you registered your bot with a service like Nickserv on freenode. \ +Also being used when `UseSASL=true` \ +Note: if you want do to quakenet auth, set NickServNick="Q@CServe.quakenet.org" + +Setting: OPTIONAL \ +Format: string \ +Example: On freenode nickserv is called nickserv + +`NickServNick="nickserv"` + +## NickServPassword +The password you use if you registered your bot with a service like Nickserv on freenode. \ +Also being used when `UseSASL=true` \ +Also see `NickServNick` + +Setting: OPTIONAL \ +Format: string \ +Example: + +`NickServPassword="secret"` + +## NickServUsername +Only used for quakenet auth. +See https://github.com/42wim/matterbridge/issues/263 for more info + +Setting: OPTIONAL \ +Format: string \ +Example: + +`NickServUsername="username"` + +## NoSendJoinPart +Do not send joins/parts to other bridges +Currently works for messages from the following bridges: irc, mattermost, slack + +Setting: OPTIONAL \ +Format: boolean \ +Example: enable it + +`NoSendJoinPart=true` + +## Password +Password for irc server (if necessary) + +Setting: OPTIONAL \ +Format: string (hostname:port) \ +Example: + +`Password="s3cret"` + +## RejoinDelay +Delay in seconds to rejoin a channel when kicked + +Setting: OPTIONAL, RELOADABLE \ +Default: 0 \ +Format: int \ +Example: + +`RejoinDelay=2` + +## RunCommands +RunCommands allows you to send RAW irc commands after connection + +Setting: OPTIONAL, RELOADABLE \ +Format: Array of strings \ +Example: Send user a hello message and send something to chanserv + +`RunCommands=["PRIVMSG user hello","PRIVMSG chanserv something"]` + +## Server * +irc server to connect to. + +Setting: REQUIRED \ +Format: string (hostname:port) \ +Example: + +`Server="irc.freenode.net:6667"` + + +## SkipTLSVerify +See [SkipTLSVerify](#SkipTLSVerify) + +## UseSASL +Enable SASL (PLAIN) authentication. (freenode requires this from eg AWS hosts) \ +It uses `NickServNick` and `NickServPassword` as login and password + +Setting: OPTIONAL \ +Format: boolean \ +Example: enable it + +`UseSASL=true` + +## UseTLS +Enable to use TLS connection to your irc server. + +Setting: OPTIONAL \ +Format: boolean \ +Example: enable it + +`UseTLS=true` + +# Matrix + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Matrix-(basic) + +## Login * +login of your bot. +Use a dedicated user for this and not your own! +Messages sent from this user will not be relayed to avoid loops. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Login="yourlogin"` + +## NoHomeServerSuffix +Whether to send the homeserver suffix. eg ":matrix.org" in @username:matrix.org +to other bridges, or only send "username".(true only sends username) + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: enable it + +`NoHomeServerSuffix=true` + +## Password * +password of your bot. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Password="yourpass"` + +## PrefixMessagesWithNick +See [PrefixMessagesWithNick](#PrefixMessagesWithNick) + +## Server * +Server is your homeserver (eg https://matrix.org) + +Setting: REQUIRED \ +Format: string \ +Example: + +`Server="https://matrix.org"` + + + +# Mattermost + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Mattermost-(basic) + +## EditDisable + +See [EditDisable](#EditDisable) + +## EditSuffix + +See [EditSuffix](#EditSuffix) + +## Login * +login of your bot. +Use a dedicated user for this and not your own! + +Setting: REQUIRED (when not using webhooks) \ +Format: string \ +Example: + +`Login="yourlogin"` + +## NoTLS +Enable this to make a http connection (instead of https) to your mattermost. + +Setting: OPTIONAL \ +Format: boolean \ +Example: enable it + +`NoTLS=true` + +## Password * +login of your bot. +Use a dedicated user for this and not your own! + +Setting: REQUIRED (when not using webhooks) \ +Format: string \ +Example: + +`Password="yourpass"` + +## Server * +The mattermost hostname. (do not prefix it with http or https) + +Setting: REQUIRED \ +Format: string \ +Example: + +`Server="yourmattermostserver.domain"` + +## Team * +Your team on mattermost. + +Setting: REQUIRED (when not using webhooks) \ +Format: string \ +Example: + +`Team="yourteam"` + +## Token +personal access token of the bot. \ +new feature since mattermost 4.1. See https://docs.mattermost.com/developer/personal-access-tokens.html \ +you can use token instead of login/password. + +Setting: OPTIONAL (when not using webhooks) \ +Format: string \ +Example: + +`Token="abcdefghijklm"` + + +## Webhook options +NOT RECOMMENDED TO USE INCOMING/OUTGOING WEBHOOK. USE DEDICATED BOT USER WHEN POSSIBLE! + +### WebhookURL +Url is your incoming webhook url as specified in mattermost. +See account settings - integrations - incoming webhooks on mattermost. +If specified, messages will be sent to mattermost using this URL + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookURL="https://yourdomain/hooks/yourhookkey"` + +### WebhookBindAddress +Address to listen on for outgoing webhook requests from mattermost. +See account settings - integrations - outgoing webhooks on mattermost. +If specified, messages will be received from mattermost on this ip:port +(this will only work if `WebhookURL` is also configured) + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookBindAddress="0.0.0.0:9999"` + +### IconURL +Icon that will be showed in mattermost. +This only works when `WebhookURL` is configured. + +Setting: OPTIONAL \ +Format: string \ +Example: + +`IconURL="http://youricon.png"` + + +## PrefixMessagesWithNick +See [PrefixMessagesWithNick](#PrefixMessagesWithNick) + +# RocketChat + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-RocketChat-(basic) + + +## Login * +login needs to be the login with email address! user@domain.com +Use a dedicated user for this and not your own! + +Setting: REQUIRED \ +Format: string \ +Example: + +`Login="yourlogin@domain.com"` + +## Password * + +Setting: REQUIRED \ +Format: string \ +Example: + +`Password="yourpass"` + +## Server * +The rocketchat hostname. (prefix it with http or https) + +Setting: REQUIRED \ +Format: string \ +Example: + +`Server="https://yourrocketchatserver.domain.com:443"` + +## SkipTLSVerify +See [SkipTLSVerify](#SkipTLSVerify) + +## Webhook options +USE DEDICATED BOT USER WHEN POSSIBLE! This allows you to use advanced features like message editing/deleting and uploads + +### WebhookBindAddress +Address to listen on for outgoing webhook requests from rocketchat. +See administration - integrations - new integration - outgoing webhook + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookBindAddress="0.0.0.0:9999"` + +### Nick +Your nick/username as specified in your incoming webhook "Post as" setting + +Setting: OPTIONAL \ +Format: string \ +Example: + +Nick="matterbot" + +### WebhookURL +Url is your incoming webhook url as specified in rocketchat +Read #https://rocket.chat/docs/administrator-guides/integrations/#how-to-create-a-new-incoming-webhook +See administration - integrations - new integration - incoming webhook + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookURL="https://yourdomain/hooks/yourhookkey"` + + +# Slack +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Slack-(basic) + +## Debug +Extra slack specific debug info, warning this generates a lot of output. + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: Enable it + +`Debug=true` + + +## EditDisable +See [EditDisable](#EditDisable) + +## EditSuffix +See [EditSuffix](#EditSuffix) + +## PrefixMessagesWithNick +See [PrefixMessagesWithNick](#PrefixMessagesWithNick) + +## 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: Enable it + +`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: Enable it + +`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: Enable it + +`SyncTopic=true` + +## Token * +Token to connect with the Slack API \ + +Setting: REQUIRED (when not using webhooks) \ +Format: string \ +Example: + +`Token="yourslacktoken"` + + +## Webhook options +NOT RECOMMENDED TO USE INCOMING/OUTGOING WEBHOOK. USE SLACK API AND DEDICATED BOT USER WHEN POSSIBLE! + +### IconURL +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: + +`IconURL="https://robohash.org/{NICK}.png?size=48x48"` + +### WebhookBindAddress +Address to listen on for outgoing webhook requests from slack. +See account settings - integrations - outgoing webhooks on slack + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookBindAddress="0.0.0.0:9999"` + +### WebhookURL +Url is your incoming webhook url as specified in slack. +See account settings - integrations - incoming webhooks on slack + +Setting: OPTIONAL \ +Format: string \ +Example: + +`WebhookURL="https://hooks.slack.com/services/yourhook"` + +# Steam + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Steam-(basic) + +## Authcode +steamguard mail authcode (not the 2FA code) + +Setting: OPTIONAL \ +Format: string \ +Example: + +`Authcode="ABCE12"` + +## Login * +login of your bot. +Use a dedicated user for this and not your own account! + +Setting: REQUIRED \ +Format: string \ +Example: + +`Login="yourlogin"` + +## Password * +password of your bot. + +Setting: REQUIRED \ +Format: string \ +Example: + +`Password="yourpass"` + +## PrefixMessagesWitNick +See [PrefixMessagesWithNick](#PrefixMessagesWithNick) + +# Telegram + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Telegram-(basic) + + +## EditDisable + +See [EditDisable](#EditDisable) + +## EditSuffix + +See [EditSuffix](#EditSuffix) + +## MediaConvertWebPToPNG +Convert WebP images to PNG before upload. +https://github.com/42wim/matterbridge/issues/398 + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: enable it + +`MediaConvertWebPToPNG=true` + +## MessageFormat +Supported formats are `HTML`, `Markdown` and `HTMLNick` +See https://core.telegram.org/bots/api#html-style +See https://core.telegram.org/bots/api#markdown-style +`HTMLNick` only allows HTML for the nick, the message itself will be html-escaped + +Setting: OPTIONAL, RELOADABLE \ +Format: string \ +Default: "" \ +Example: Send as markdown + +`MessageFormat="Markdown"` + +## QuoteDisable +Disable quoted/reply messages + +Setting: OPTIONAL, RELOADABLE \ +Format: boolean \ +Example: enable it + +`QuoteDisable=true` + +## QuoteFormat +Format quoted/reply messages + +Setting: OPTIONAL, RELOADABLE \ +Format: string \ +Default: `"{MESSAGE} (re @{QUOTENICK}: {QUOTEMESSAGE})"` \ +Example: + +`QuoteFormat="{MESSAGE} (re @{QUOTENICK}: {QUOTEMESSAGE})"` + +## Token * +Token to connect with telegram API +See https://core.telegram.org/bots#6-botfather and https://www.linkedin.com/pulse/telegram-bots-beginners-marco-frau + +Setting: REQUIRED \ +Format: string \ +Example: + +`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: enable it + +`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: enable it + +`UseInsecureURL=true` + +# 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 + +## Message +Message 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: + +`Message="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"` + +# Whatsapp + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Whatsapp-(basic) + +## 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: + +`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: enable it + +`QrOnWhiteTerminal=true` + +## SessionFile +First time that you login you will need to scan QR code, then credentials willl be saved in a session file +If you won't set SessionFile then you will need to scan QR code on every restart +Bby default the session is stored only in memory, till restarting matterbridge. + +Setting: OPTIONAL \ +Format: string \ +Example: + +`SessionFile="session-48111222333.gob"` + +# XMPP +Basic config on https://github.com/42wim/matterbridge/wiki/Section-XMPP-(basic) + +## Jid * +Jabber Identifier + +Setting: REQUIRED \ +Format: string \ +Example: + +`Jid="user@example.com"` + +## MUC * +Multi-user Chatroom + +Setting: REQUIRED \ +Format: string \ +Example: + +`Muc="conference.jabber.example.com"` + +## Nick * +Your nick in the rooms + +Setting: REQUIRED \ +Format: string \ +Example: + +`Nick="xmppbot"` + +## Password * +Password + +Setting: REQUIRED \ +Format: string \ +Example: + +`Password="yourpass"` + +## Server * +xmpp server to connect to. + +Setting: REQUIRED \ +Format: string (hostname:port) \ +Example: + +`Server="jabber.example.com:5222"` + +## SkipTLSVerify +See [SkipTLSVerify](#SkipTLSVerify) + +# Zulip + +Basic config on https://github.com/42wim/matterbridge/wiki/Section-Zulip-(basic) + + +## Login * +Username of the bot, normally called yourbot-bot@yourserver.zulipchat.com +See username in Settings - Your bots + +Setting: REQUIRED \ +Format: string \ +Example: + +`Login="yourbot-bot@yourserver.zulipchat.com"` + +## Server * +Servername of your zulip instance + +Setting: REQUIRED \ +Format: string \ +Example: + +`Server="https://yourserver.zulipchat.com"` + +## Token * +Token to connect with zulip API (called bot API key in Settings - Your bots) + +Setting: REQUIRED \ +Format: string \ +Example: + +`Token="Yourtokenhere"`