# jabagram
A lightweight and fast, full-featured bridge between XMPP and Telegram. Was
originally written for personal use, so may not be very flexible in
configuration.
<p align="center" width="100%">
<img width="35%" src="https://github.com/ventureoo/jabagram/assets/92667539/91646d1d-bee8-40e0-ad9a-071d2d4431b9">
<img width="35%" src="https://github.com/ventureoo/jabagram/assets/92667539/1d74e64f-541d-4aa2-8913-2f43fcf06182">
</p>
## Features
This bridge has the following features and supports all the basic capabilities:
- [x] Lightweight and asynchronous, with support for adding new chats in runtime, without config editing
- [x] Unlike other bridges, it doesn't require hosting your own XMPP server
- [x] Forwarding between multiple pairs of chats at once instance (see below for usage)
- [x] Forwarding of plain text messages
- [x] Forwarding of attachments (videos, images, audio, etc)
- [x] Stickers (from Telegram -> XMPP)
- [x] Native replies to messages in Telegram
- [x] Round-trip message edit changes
- [x] Forwards events between bridged chats, such as mebmers join/exit, etc.
## Installation
### With pip
Jabagram stable releases can now be installed via pip. This is the recommended
way if you don't want to use Docker or unable to install jabagram dependencies
to your system paths.
```
pip install --user jabagram
```
You can also install in a virtual environment if you don't want to clutter your
system with all the jabagram dependencies.
### Manual
When manually installing to make the bridge work, you need to use Python 3.10+,
and install all the dependencies specified in the ``requirements.txt``(slixmpp,
aiohttp) file:
```
git clone https://github.com/ventureoo/jabagram
cd jabagram
pip install -r requirements.txt
```
## Deploy
Before you start the bridge, you need to do some basic configuration. An
example configuration is given in the form of the file ``config.example.ini``.
Rename it to ``config.ini`` and specify the following data:
1) Create a bot in Telegram via @botfather on behalf of which messages will be
forwarded and specify its token in the ``token`` field of the ``[telegram]``
section.
2) Create an XMPP account on behalf of which the bridge will forward messages
in MUC rooms, specify its JID (login) and password in the ``login`` and
``password`` fields in the ``[xmpp]`` section respectively.
3) Come up with a secret key that will be used when linking new Telegram and
XMPP chats. This key must be passed as a reason to invite a bot in XMPP to the
MUC room, otherwise the bot will not accept the invitation. This is a security
measure if you don't want your bridge instance to be used to bind other chats.
Otherwise, leave this field blank.
4) If you have done everything correctly, the bridge should start without
errors or exceptions and will create a database ``jabagram.db`` inside data
folder, which will store information about the "bound" chats in Telegram and XMPP.
See Usage further below.
An example of a config file that is given as ``config.example.ini``:
```
# Telegram bot token, get it from @botfather
[telegram]
token=XXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
# Login and password from the bot account in XMPP
[xmpp]
login=your_xmpp_user@example.org
password=YoUr_SEcReT_PaSs
# The secret key specified in the user's invitation to the MUC for linking two
# chats. PLEASE change it from the default key if you don't want your bridge
# instance to be used by whoever you want. Otherwise, leave it blank.
[general]
key=SUxvdmVYTVBQ
# Further on is the service messages that are sent by a bot
[messages.missing_muc_jid]
line = Please specify the MUC address of room you want to pair with this Telegram chat.
[messages.invalid_jid]
line = You have specified an incorrect room JID. Please try again.
[messages.queueing_message]
line.1 = Specified room has been successfully placed on the queue.
line.2 = Please invite this {} bot to your XMPP room, and as the reason for the invitation specify the secret key that is specified in bot's config or ask the owner of this bridge instance for it.
line.3 = If you have specified an incorrect room address, simply repeat
line.4 = the pair command (/jabagram) with the corrected address.
[messages.unbridge_telegram]
line.1 = This chat was automatically unbridged due to a bot kick in XMPP.
line.2 = If you want to bridge it again, invite this bot to this chat again and use the /jabagram command.
[messages.unbridge_xmpp]
line.1 = This chat was automatically unbridged due to a bot kick in Telegram.
```
### Via Docker
You can also use Docker to deploy the bridge. Here you don't need to
pre-install dependencies on the host system, just build a container image:
```
git clone https://github.com/ventureoo/
cd jabagram
docker build -t jabagram .
```
The following command is used to start it:
```
docker run --restart always -d --name jabagram -v "$(pwd)/data:/app/data:rw" jabagram
```
Note about the ``-v`` key. It specifies that the database file be stored
outside the container environment, i.e. on your host system. The ``--restart``
option is needed if you want the bridge to automatically restart on critical
errors or when your system is powered on.
## Usage
Once you have successfully started your own bridge instance or found an
existing one, you can perform chat binding using the following algorithm:
1. Invite your bot to the Telegram chat you want to bridge.
2. Run the ``/jabagram`` command with the MUC address of the room you want to
bridge.
1. If the address was entered incorrectly, simply repeat the command with
the corrected address.
3. The bot will queue your chats and then wait for you to invite the bot into
the XMPP room.
4. Invite the XMPP bot into the room and as a reason, specify the secret key
that you previously specified in the config or received from the admin of an
existing instance. For example, in the Gajim client, this is done with the
command: ``/invite <XMPP_JID> <SECRET_KEY>``
5. Once the bot successfully joins an XMPP room, messages should be sent
between your room and the chat room in Telegram.
If you want to "unbridge" chats, just kick the bot from your Telegram chat or
XMPP room. It will automatically remove the entry from the database. Note that
losing the ``./data/jabagram.db`` file will unbridge all chats and you will need to
re-bridge them.
To re-bridge chats follow the steps above.
### Limitations
This bridge has some limitation that will probably never be properly fixed.
#### OMEMO encryption
This bridge cannot forward messages that have been encrypted using OMEMO or
OpenPGP. This will never be implemented because:
1) slixmpp does not support encryption via OMEMO
2) Forwarding encrypted messages is probably a bad idea in the first place, you
are actually passing the body of your message unencrypted to the Telegram API,
it will be visible to all Telegram chat members to see it. Which calls into
question the whole point of encrypting messages.
#### Deleting messages
Bridge cannot delete a forwarded message in XMPP if it has been deleted in
Telegram. The Telegram API doesn't allow the bot to receive any updates about
deleted messages, so this simply can't be implemented. In the case of XMPP,
message deletion is a feature that can only be implemented on the client side,
not at the protocol or XEP level. Use editing of message with a stub as a
workaround.
#### Animated stickers from Telegram
Telegram has a proprietary format for animated stickers that probably can't be
properly previewed by XMPP clients. The bridge will not forward them to XMPP
because they cannot be properly rendered in any XMPP client.
#### Forwarding private messages
Sorry, but at the moment I only want to support forwarding messages from group
chats or MUCs. But this may be implemented in the future.
#### Mobile XMPP clients don't show nicknames set by the bot in MUC
Some mobile clients like Conversations and Blabber don't show nicknames in MUC
for users you have in your contacts [1]. Please, after inviting a bot to XMPP,
make sure you remove it from your contacts, otherwise it will not accept
Telegram sender nicknames for you.
[1] - https://github.com/iNPUTmice/Conversations/commit/ef1429c9a6983c101da41a277bd9353374dc89e7
## License
Licensed under GPL 3.0. If you'd like to help with improvements or fixes to this shitty code, I'd be happy to consider your patches ;D
## Feedback
If you have any issues with how the bridge works/is configured, please use
"Discussions" tab on the GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "jabagram",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Vasiliy Stelmachenok <ventureo@yandex.ru>",
"keywords": "asyncio, bridge, telegram, xmpp",
"author": null,
"author_email": "Vasiliy Stelmachenok <ventureo@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/5f/93/07f78bb20013fadabda77882f08df925d355b9cd8f6cfea35b7e7254a167/jabagram-1.0.0.tar.gz",
"platform": null,
"description": "# jabagram\n\nA lightweight and fast, full-featured bridge between XMPP and Telegram. Was\noriginally written for personal use, so may not be very flexible in\nconfiguration.\n\n<p align=\"center\" width=\"100%\">\n<img width=\"35%\" src=\"https://github.com/ventureoo/jabagram/assets/92667539/91646d1d-bee8-40e0-ad9a-071d2d4431b9\"> \n<img width=\"35%\" src=\"https://github.com/ventureoo/jabagram/assets/92667539/1d74e64f-541d-4aa2-8913-2f43fcf06182\"> \n</p>\n\n## Features\n\nThis bridge has the following features and supports all the basic capabilities:\n\n- [x] Lightweight and asynchronous, with support for adding new chats in runtime, without config editing\n- [x] Unlike other bridges, it doesn't require hosting your own XMPP server\n- [x] Forwarding between multiple pairs of chats at once instance (see below for usage)\n- [x] Forwarding of plain text messages\n- [x] Forwarding of attachments (videos, images, audio, etc)\n- [x] Stickers (from Telegram -> XMPP)\n- [x] Native replies to messages in Telegram\n- [x] Round-trip message edit changes\n- [x] Forwards events between bridged chats, such as mebmers join/exit, etc.\n\n\n## Installation\n\n### With pip\n\nJabagram stable releases can now be installed via pip. This is the recommended\nway if you don't want to use Docker or unable to install jabagram dependencies\nto your system paths.\n\n```\npip install --user jabagram\n```\n\nYou can also install in a virtual environment if you don't want to clutter your\nsystem with all the jabagram dependencies.\n\n### Manual\n\nWhen manually installing to make the bridge work, you need to use Python 3.10+,\nand install all the dependencies specified in the ``requirements.txt``(slixmpp,\naiohttp) file:\n\n```\ngit clone https://github.com/ventureoo/jabagram\ncd jabagram\npip install -r requirements.txt\n```\n\n## Deploy\n\nBefore you start the bridge, you need to do some basic configuration. An\nexample configuration is given in the form of the file ``config.example.ini``.\nRename it to ``config.ini`` and specify the following data:\n\n1) Create a bot in Telegram via @botfather on behalf of which messages will be\nforwarded and specify its token in the ``token`` field of the ``[telegram]``\nsection.\n2) Create an XMPP account on behalf of which the bridge will forward messages\nin MUC rooms, specify its JID (login) and password in the ``login`` and\n``password`` fields in the ``[xmpp]`` section respectively.\n3) Come up with a secret key that will be used when linking new Telegram and\nXMPP chats. This key must be passed as a reason to invite a bot in XMPP to the\nMUC room, otherwise the bot will not accept the invitation. This is a security\nmeasure if you don't want your bridge instance to be used to bind other chats.\nOtherwise, leave this field blank.\n4) If you have done everything correctly, the bridge should start without\nerrors or exceptions and will create a database ``jabagram.db`` inside data\nfolder, which will store information about the \"bound\" chats in Telegram and XMPP.\nSee Usage further below.\n\nAn example of a config file that is given as ``config.example.ini``:\n\n```\n# Telegram bot token, get it from @botfather\n[telegram]\ntoken=XXXXXXXXXX:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n\n# Login and password from the bot account in XMPP\n[xmpp]\nlogin=your_xmpp_user@example.org\npassword=YoUr_SEcReT_PaSs\n\n# The secret key specified in the user's invitation to the MUC for linking two\n# chats. PLEASE change it from the default key if you don't want your bridge\n# instance to be used by whoever you want. Otherwise, leave it blank.\n[general]\nkey=SUxvdmVYTVBQ\n\n# Further on is the service messages that are sent by a bot\n[messages.missing_muc_jid]\nline = Please specify the MUC address of room you want to pair with this Telegram chat.\n\n[messages.invalid_jid]\nline = You have specified an incorrect room JID. Please try again.\n\n[messages.queueing_message]\nline.1 = Specified room has been successfully placed on the queue.\nline.2 = Please invite this {} bot to your XMPP room, and as the reason for the invitation specify the secret key that is specified in bot's config or ask the owner of this bridge instance for it.\nline.3 = If you have specified an incorrect room address, simply repeat\nline.4 = the pair command (/jabagram) with the corrected address.\n\n[messages.unbridge_telegram]\nline.1 = This chat was automatically unbridged due to a bot kick in XMPP.\nline.2 = If you want to bridge it again, invite this bot to this chat again and use the /jabagram command.\n\n[messages.unbridge_xmpp]\nline.1 = This chat was automatically unbridged due to a bot kick in Telegram.\n```\n\n### Via Docker\n\nYou can also use Docker to deploy the bridge. Here you don't need to\npre-install dependencies on the host system, just build a container image:\n\n```\ngit clone https://github.com/ventureoo/\ncd jabagram\ndocker build -t jabagram .\n```\n\nThe following command is used to start it:\n\n```\ndocker run --restart always -d --name jabagram -v \"$(pwd)/data:/app/data:rw\" jabagram\n```\n\nNote about the ``-v`` key. It specifies that the database file be stored\noutside the container environment, i.e. on your host system. The ``--restart``\noption is needed if you want the bridge to automatically restart on critical\nerrors or when your system is powered on.\n\n## Usage\n\nOnce you have successfully started your own bridge instance or found an\nexisting one, you can perform chat binding using the following algorithm:\n\n1. Invite your bot to the Telegram chat you want to bridge.\n2. Run the ``/jabagram`` command with the MUC address of the room you want to\n bridge.\n 1. If the address was entered incorrectly, simply repeat the command with\n the corrected address.\n3. The bot will queue your chats and then wait for you to invite the bot into\n the XMPP room.\n4. Invite the XMPP bot into the room and as a reason, specify the secret key\n that you previously specified in the config or received from the admin of an\n existing instance. For example, in the Gajim client, this is done with the\n command: ``/invite <XMPP_JID> <SECRET_KEY>``\n5. Once the bot successfully joins an XMPP room, messages should be sent\n between your room and the chat room in Telegram.\n\nIf you want to \"unbridge\" chats, just kick the bot from your Telegram chat or\nXMPP room. It will automatically remove the entry from the database. Note that\nlosing the ``./data/jabagram.db`` file will unbridge all chats and you will need to\nre-bridge them.\n\nTo re-bridge chats follow the steps above.\n\n### Limitations\n\nThis bridge has some limitation that will probably never be properly fixed.\n\n#### OMEMO encryption\n\nThis bridge cannot forward messages that have been encrypted using OMEMO or\nOpenPGP. This will never be implemented because:\n\n1) slixmpp does not support encryption via OMEMO \n2) Forwarding encrypted messages is probably a bad idea in the first place, you\nare actually passing the body of your message unencrypted to the Telegram API,\nit will be visible to all Telegram chat members to see it. Which calls into\nquestion the whole point of encrypting messages.\n\n#### Deleting messages\n\nBridge cannot delete a forwarded message in XMPP if it has been deleted in\nTelegram. The Telegram API doesn't allow the bot to receive any updates about\ndeleted messages, so this simply can't be implemented. In the case of XMPP,\nmessage deletion is a feature that can only be implemented on the client side,\nnot at the protocol or XEP level. Use editing of message with a stub as a\nworkaround.\n\n#### Animated stickers from Telegram\n\nTelegram has a proprietary format for animated stickers that probably can't be\nproperly previewed by XMPP clients. The bridge will not forward them to XMPP\nbecause they cannot be properly rendered in any XMPP client.\n\n#### Forwarding private messages\n\nSorry, but at the moment I only want to support forwarding messages from group\nchats or MUCs. But this may be implemented in the future.\n\n#### Mobile XMPP clients don't show nicknames set by the bot in MUC\n\nSome mobile clients like Conversations and Blabber don't show nicknames in MUC\nfor users you have in your contacts [1]. Please, after inviting a bot to XMPP,\nmake sure you remove it from your contacts, otherwise it will not accept\nTelegram sender nicknames for you.\n\n[1] - https://github.com/iNPUTmice/Conversations/commit/ef1429c9a6983c101da41a277bd9353374dc89e7\n\n## License\n\nLicensed under GPL 3.0. If you'd like to help with improvements or fixes to this shitty code, I'd be happy to consider your patches ;D\n\n## Feedback\n\nIf you have any issues with how the bridge works/is configured, please use\n\"Discussions\" tab on the GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "Fully functional bridge between Telegram and XMPP",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/ventureoo/jabagram/issues",
"Homepage": "https://github.com/ventureoo/jabagram",
"Repository": "https://github.com/ventureoo/jabagram.git"
},
"split_keywords": [
"asyncio",
" bridge",
" telegram",
" xmpp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed26251b4800ddaff099e37565c31a725b2a5ede21e2741775312789549c0365",
"md5": "acef03f7812a93fd9a04128b0fbfb3d4",
"sha256": "cf08f802f4fab1b4591ec8c1cb9d9589b6dab8d99d377c006abfcc27fd209a1f"
},
"downloads": -1,
"filename": "jabagram-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acef03f7812a93fd9a04128b0fbfb3d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 36755,
"upload_time": "2025-01-08T13:11:22",
"upload_time_iso_8601": "2025-01-08T13:11:22.538666Z",
"url": "https://files.pythonhosted.org/packages/ed/26/251b4800ddaff099e37565c31a725b2a5ede21e2741775312789549c0365/jabagram-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5f9307f78bb20013fadabda77882f08df925d355b9cd8f6cfea35b7e7254a167",
"md5": "c3683eaeda430d2787a0e1d7120e80e2",
"sha256": "1512fb66e4f05489a3bbba17b244194fc82f4d6fcb52c1f490269fb514914361"
},
"downloads": -1,
"filename": "jabagram-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c3683eaeda430d2787a0e1d7120e80e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 31526,
"upload_time": "2025-01-08T13:11:25",
"upload_time_iso_8601": "2025-01-08T13:11:25.440362Z",
"url": "https://files.pythonhosted.org/packages/5f/93/07f78bb20013fadabda77882f08df925d355b9cd8f6cfea35b7e7254a167/jabagram-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 13:11:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ventureoo",
"github_project": "jabagram",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiohttp",
"specs": []
},
{
"name": "slixmpp",
"specs": []
},
{
"name": "unidecode",
"specs": []
}
],
"lcname": "jabagram"
}
JSON
