| 1 | TODO: is this information up to date? |
| 2 | |
| 3 | See [here](https://core.telegram.org/bots#6-botfather) and [here](https://www.linkedin.com/pulse/telegram-bots-beginners-marco-frau). |
| 4 | |
| 5 | **Sequence within a BotFather chat:** |
| 6 | |
| 7 | > **You**: /setprivacy |
| 8 | > |
| 9 | > **BotFather**: Choose a bot to change group messages settings. |
| 10 | > |
| 11 | > **You**: @your_name_bot |
| 12 | > |
| 13 | > **BotFather**: 'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username. |
| 14 | > |
| 15 | > - 'Disable' - your bot will receive all messages that people send to groups. |
| 16 | > - Current status is: ENABLED |
| 17 | > |
| 18 | > **You**: Disable |
| 19 | > |
| 20 | > **BotFather**: Success! The new status is: DISABLED. /help |
| 21 | |
| 22 | |
| 23 | (copied from [this stack overflow answer](https://stackoverflow.com/a/45441585)) |
| 24 | |
| 25 | |
| 26 | ## Tutorial |
| 27 | |
| 28 | This basic example will guide you through getting started on your first Telegram bridge. |
| 29 | |
| 30 | - Create your bot and retrieve your API token. |
| 31 | - Make sure to disable privacy mode. |
| 32 | - Add the bot to your Telegram group |
| 33 | - Set up the Matterbridge configuration. |
| 34 | |
| 35 | ### 1. Speak to the BotFather. |
| 36 | |
| 37 | 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. |
| 38 | |
| 39 | **Disable bot privacy** |
| 40 | |
| 41 | > **You**: /setprivacy |
| 42 | > |
| 43 | > **BotFather**: Choose a bot to change group messages settings. |
| 44 | > |
| 45 | > **You**: @your_name_bot |
| 46 | > |
| 47 | > **BotFather**: 'Enable' - your bot will only receive messages that either start with the '/' symbol or mention the bot by username. |
| 48 | > |
| 49 | > - 'Disable' - your bot will receive all messages that people send to groups. |
| 50 | > - Current status is: ENABLED |
| 51 | > |
| 52 | > **You**: Disable |
| 53 | > |
| 54 | > **BotFather**: Success! The new status is: DISABLED. /help |
| 55 | |
| 56 | Now add this newly created bot to the Telegram chat you're trying to bridge. |
| 57 | |
| 58 | ### 2. Add your config to Matterbridge. |
| 59 | |
| 60 | Here is an example gateway bridging `Discord`<>`Telegram` which should be placed in your `matterbridge.toml` (or equivalent) |
| 61 | |
| 62 | ```toml |
| 63 | # / |
| 64 | # SERVERS |
| 65 | # / |
| 66 | [telegram] |
| 67 | [telegram.mytelegram] |
| 68 | Token="your_token_from_botfather" |
| 69 | RemoteNickFormat="<{NICK}> " # How your message will be formatted when bridged. |
| 70 | MessageFormat="HTMLNick :" |
| 71 | QuoteFormat="{MESSAGE} (re @{QUOTENICK}: {QUOTEMESSAGE})" |
| 72 | QuoteLengthLimit=46 # Truncuate long quotes to prevent spammy bridged messages |
| 73 | IgnoreMessages="^/" # Don't bridge bot commands (as the responses will not be bridged) |
| 74 | |
| 75 | # / |
| 76 | # GATEWAYS |
| 77 | # / |
| 78 | [[gateway]] |
| 79 | name="YourUniqueGateWayName" |
| 80 | enable=true |
| 81 | |
| 82 | [[gateway.inout]] |
| 83 | account="telegram.mytelegram" |
| 84 | channel="-100xxx" |
| 85 | |
| 86 | [[gateway.inout]] |
| 87 | account="discord.mydiscord" |
| 88 | channel="channel-name" |
| 89 | ``` |
| 90 | |
| 91 | > See all possible settings [here](https://github.com/42wim/matterbridge/wiki/Settings#telegram) |
| 92 | |
| 93 | 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. |
| 94 | |
| 95 | |
| 96 | To add more nodes to this bridge, you simply need to add additional `[[gateway.inout]]` fields. |
| 97 | |
| 98 | Make sure to test your config with the `-debug` flag after each change. |
| 99 | |
| 100 | ### Limitations |
| 101 | |
| 102 | - 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 |
| 103 | |
| 104 | ## Matterbridge is not relaying messages from Telegram |
| 105 | |
| 106 | See |
| 107 | * https://core.telegram.org/bots#privacy-mode |
| 108 | * https://github.com/yagop/node-telegram-bot-api/issues/174#issuecomment-244632667 |
| 109 | |
| 110 | If your bot is not getting messages: |
| 111 | |
| 112 | Disable privacy mode with @Botfather. |
| 113 | |
| 114 | * Go to [BotFather](https://t.me/botfather) send /setprivacy. |
| 115 | * Select the username of the bot. |
| 116 | * Select Disable. |
| 117 | * Kick bot from chat if it's already in it. |
| 118 | * Invite bot to chat. |
| 119 | |
| 120 | The order is important. |
| 121 | |
| 122 | ## Matterbridge is not relay messages from other bots |
| 123 | |
| 124 | > 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. |
| 125 | |
| 126 | https://core.telegram.org/bots/faq#why-doesn-39t-my-bot-see-messages-from-other-bots |
| 127 | |
| 128 | ## Matterbridge is not relaying images/stickers/files from Telegram |
| 129 | |
| 130 | Because images/stickers/files are from non-public url's, you'll need to setup a [mediaserver](Mediaserver-setup-(advanced)) |
| 131 | |
| 132 | ## Matterbridge is not relaying messages to Telegram |
| 133 | |
| 134 | Did you enable `MessageFormat="HTML"` in your config? |
| 135 | You could be sending invalid HTML. Set it to `MessageFormat=""` |
| 136 | |
| 137 | More info in https://github.com/42wim/matterbridge/blob/master/matterbridge.toml.sample#L836-L838 |
| 138 | |
| 139 | ## Matterbridge is not deleting messages from Telegram to other bridges |
| 140 | |
| 141 | Telegram doesn't has "deleted messages" metadata, so we don't know which messages are deleted. |
| 142 | |
| 143 | ## Users are shown as "unknown user" |
| 144 | |
| 145 | Telegram channels will always return unknown users. Telegram groups will show usernames if possible |
| 146 | |
| 147 | ## How to use MediaConvertTgs with lottie? |
| 148 | |
| 149 | This requires the external dependency `lottie`, which can be installed like this: |
| 150 | `pip install lottie cairosvg` |
| 151 | https://github.com/42wim/matterbridge/issues/874 |
| 152 | |
| 153 | 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`: |
| 154 | ``` |
| 155 | PATH=$HOME/.local/bin:$PATH |
| 156 | export PATH |
| 157 | ``` |
| 158 | |
| 159 | If you encounter bugs with this, try to extract the Telegram sticker file and run lottie on it like this: |
| 160 | `lottie_convert.py --input-format lottie file_1234_tgs.webp myoutput.webp` |
| 161 | This might give you additional information about what's going on. |
| 162 | |
| 163 | |
