🛡️ Secure chat transfer from Telegram to TrueConf

Looking for a secure messenger without service restrictions? Transfer your Telegram chats to TrueConf in just a few clicks. Migration is supported only for on-premises deployments of TrueConf Server / TrueConf Enterprise.

English / Русский

Caution

These instructions apply to TrueConf Server version 5.5.3 or later.
If you are using an earlier version, update the server first.

🚀 Quick start

Migration consists of six steps. The full flow is shown below without extra details so that you can understand where you are in the process and how much remains to be done.

Prepare the environment — Telegram Desktop, TrueConf Server, Python 3.11+. → Introduction
Export the chat from Telegram in JSON format. → Telegram chat export
Download and start the migration tool. → Installation and first launch
Configure the connection to TrueConf Server and, optionally, a Telegram bot for automatic participant detection. → Connections tab
Match chat participants with their TrueConf IDs. If users do not exist on the server yet, register them. The procedure depends on whether you use LDAP. → Users tab
Start the migration and get a copy of the chat in TrueConf. → Chat migration

Tip

If any term below is unclear, check the Terms section before searching for it elsewhere.

📖 Terms

Term	Meaning
TrueConf ID	A user login in TrueConf Server, similar to a username.
LDAP	A mode where users and passwords are stored outside TrueConf Server in a corporate directory such as Active Directory. If you have never configured LDAP, you are probably not using it.
Registry	A mode where users and passwords are stored directly on TrueConf Server, without an external directory.
access_token	An API access key. The migration tool needs it to register users on your behalf.
OAuth application	A way to issue a temporary access token with limited permissions to the migration tool. This is safer than using a permanent administrator token.

Introduction

To migrate chats successfully, first:

Install Telegram Desktop.
Deploy TrueConf Server version 5.5.3 or later:
- for Windows (video guide);
- for Linux: Debian, CentOS.

Tip

This open-source solution migrates chats without preserving the original message date and time as the actual send time. If this is critical for you, contact technical support for assistance.

Telegram chat export

After installing and signing in to Telegram Desktop, you will be able to access all your chats.

Tip

If you are an organization administrator and do not have access to the target conversations, you can ask any chat participant to export the history instead of you.

To export the history:

Open the chat and click the button with three dots in the chat header:
Select Export chat history in the menu.
In the export settings window:
- select the media types you need;
- set a size limit for files;
- choose JSON as the format;
- specify the save path or keep the default Downloads/Telegram Desktop/ directory;
- configure the date range, for example from the first message to the current date, or from 01.02.2022 12:00 to 03.03.2023 19:00, etc.
Click Export.

The chat will start being saved with the selected settings. You can close this window if it gets in your way.

Caution

Wait until the operation is fully completed. If you selected a date range and can already see that the messages have been exported, do not cancel the process to avoid file corruption.

Installation and first launch

On the repository main page, click Code → Download ZIP.
Unpack the archive to any directory on your PC.

Python

Python 3.11 or later is required to run the scripts.

Windows — download it from the official website.
Linux and macOS — Python is usually preinstalled.

Check your version with this command:

> python --version
Python 3.12.4

Important

If the version is lower than 3.11, update Python; otherwise, the script will not start.

Environment setup

Create a virtual environment and install the dependencies, preferably using uv:

uv sync

Starting the application

Run the software from the terminal:

uv run main.py

A window will open:

Select or drag and drop the export folder into the highlighted area.

Migration setup

Connections tab

TrueConf Server settings:
- server address: domain name or IP address;
- web port used for the HTTPS connection, 443 by default;
- SSL certificate verification: enabled for trusted certificates and disabled for self-signed certificates;
- access token from Web → Security. It is required only for user registration when you have a new installation without user accounts.
Telegram bot settings (optional, but recommended for chats with many participants).

These settings are used to automatically obtain the @username and real name of each Telegram chat participant, which simplifies matching them with existing TrueConf IDs.
1. Create a bot via BotFather and enter its token in the BotFather token field.
2. Add the bot to the chat and grant it administrator permissions.
3. Use @userinfobot to find the chat ID and enter it in the corresponding field.

Tip

The Apply button saves the settings, so you can prepare for chat migration over an extended period of time.

Chat tab

On the Chat tab, specify the following settings:

Chat parameters

Specify:

the name of the new chat;
the chat owner, preferably a TrueConf ID. This user must be listed in the table on the Users tab;
the chat type. For a group with topics, or a forum-style structure, select Supergroup and specify the Topic template.

Caution

Do not change the values of the {topic} or {supergroup} placeholders. You can define your own format, for example by swapping them as {supergroup} | {topic} or by removing {supergroup}. By default, the subgroup name will look like this: Topic name | Chat name.

Migration options

Voice message conversion

TrueConf does not support the ogg format used by Telegram. Voice messages can be automatically converted to mp4 video with a cover image, which can be replaced with your own. This allows users to play them through the built-in TrueConf viewer. The export source and the original recording time will be added in the bottom-right corner of the cover image.

Important

🧩 FFmpeg must be installed and added to PATH, with drawtext filter support. Before enabling this feature, check whether your system is ready:

uv run check_ffmpeg.py

If the check passes successfully (FFmpeg OK ✅), you can enable conversion in the settings.

Animated sticker conversion

Animated Telegram stickers are stored in .tgs format, which is a Lottie animation archive. They can be converted to webp, a format supported by TrueConf. If conversion is disabled, such messages will be sent as regular emoji.

Important

🧩 Relevant only if you want to enable sticker conversion. Conversion requires system libraries. If you do not need this feature, you can skip this step.

Installation on Windows (Cairo library required)

Install MSYS2, then:

Update the packages:
```
pacman -Syu
```
If the console eventually shows a message similar to warn: terminate MSYS2 without returning to shell and check for updates again, restart the terminal and run the command again.
Install the library:
```
pacman -S mingw-w64-x86_64-cairo
```

Message date and time

This version of the program does not send messages with their original Telegram timestamp. All messages are sent with the time when the script is running. If the original time is critical for you, there are two options:

enable the checkbox, configure the time zone and caption — then a text caption such as Sent: 01.09.2025 14:10:00 +0300 will be added to each message;
contact TrueConf technical support for assistance.

Users tab

For each Telegram ID, specify the correct TrueConf ID, or login. The Password and Display name columns are needed only when registering new users on the server. The @username and Telegram name columns are filled in automatically when using Telegram bot integration by clicking .

Warning

Automatic completion requires access to Telegram servers. If you see an error, check whether your network access tools are enabled.

If users do not exist on TrueConf Server yet, they need to be registered. The registration method depends on your situation:

flowchart TD
    A{Do you have a new server?} -->|Yes| B[User registration]
    A -->|No| C{Do you use LDAP?}
    C -->|No| E[Token via web page for each participant]
    C -->|Yes| D{"Can you switch to Registry?<br/>(server restart required)"}
    D -->|Yes| B
    D -->|No| E

New server with no users yet → User registration in TrueConf Server.
The server has already been used and LDAP is not used → you do not know users' passwords, so registration will not help. Go directly to Obtaining a token for chat API authorization.
LDAP is used and you can restart the server and temporarily switch to Registry → Configured infrastructure when using LDAP.
LDAP is used and switching to Registry is not possible → Obtaining a token for chat API authorization.

User registration in TrueConf Server

Note

This section applies to two cases: (1) you have a new server with no users yet, or (2) you use LDAP and have already switched the server to Registry as described in Configured infrastructure. If neither case applies to you, use Obtaining a token for chat API authorization.

To migrate chats from Telegram to TrueConf, every chat participant must be registered in TrueConf Server. Registration is performed directly on the Users tab:

Specify the TrueConf ID, display name, and email domain for each user.
To speed up the process, set a common password for all users in the Registration password field.
Obtain an API access_token for TrueConf Server in one of two ways:

Method A. From the control panel. Go to Web → Security and copy the API token.

Caution

This token does not expire, grants access to the entire server API, and must be stored as an administrator secret.

Method B. Via an OAuth application (recommended). Create an OAuth application, grant only the required permissions, and send a request to https://domain.name/api/v4/token to exchange the client_id and client_secret for an access_token.

Note

An OAuth token is valid for 1 hour by default, which is safer for migration scenarios.

Insert the token into the Access token (for user registration) field on the Connections tab and click Apply.
Click the registration button in the upper-right corner.

For each user, you will receive one of the following statuses:

✅ Successfully added
⚠️ User already exists
🔴 Error

Configured infrastructure when using LDAP

If your infrastructure uses LDAP, the key question is whether you can restart the server to temporarily switch it from LDAP to Registry.

Tip

A token obtained via the HTML page is valid for 1 month. For a small chat, roughly up to 20 people, manually collecting tokens is usually easier. However, the more participants there are, the higher the risk: while several people are slow to send their tokens to the administrator, tokens from others may expire, and the migration may get stuck. Therefore, for large chats with several hundred participants, switching to Registry is almost always faster and more reliable.

If a restart is possible, perform the migration outside business hours by temporarily switching TrueConf Server from LDAP to Registry.

Procedure:

Set a common password for all users in the Registration password field.
Specify the correct TrueConf ID for each user, or Telegram ID.
Outside business hours, temporarily switch TrueConf Server from LDAP mode to Registry mode without automatic account migration. This is important: if existing LDAP accounts are automatically migrated to Registry, registration in step 4 will simply return “user already exists” and will not set the password.

Caution

The TrueConf ID specified during Registry registration must exactly match the user's TrueConf ID in LDAP. Otherwise, after switching back to LDAP, these will be two different users, and migrated messages will be linked to the wrong account.

Register users on the server as described in User registration in TrueConf Server.
Run the chat migration.
After the migration has been completed successfully, switch the server back to LDAP.

If switching to Registry is not possible even temporarily, use the next section.

Obtaining a token for chat API authorization

Note

🧩 This section is needed in two cases: (1) you use LDAP and switching to Registry is not possible, or (2) the server has already been used without LDAP, which means users are not new and set their passwords themselves.

A Token is required for chat API authorization. Usually, it is obtained by sending a POST request with the login and password of a TrueConf Server account. See the documentation. However, in both cases described above, the administrator does not know the user's password: with LDAP, authentication is performed through the domain, and on a server that has already been used without LDAP, users set their passwords themselves during registration. Asking employees for their account passwords is unsafe.

That is why the TrueConf team prepared an HTML page that allows each user to obtain a token independently without sharing their password with the administrator.

Step 1. Place the page on the TrueConf web server

Copy the chatbot folder:

Windows (PowerShell):

Copy-Item -Path "D:\chatbot" -Destination "C:\Program Files\TrueConf Server\httpconf\site" -Recurse

Linux:

sudo cp ~/chatbot /opt/trueconf/server/srv/site/

Restart the TrueConf Web Manager service:

Windows (PowerShell):

Restart-Service -Name "TrueConf Web Manager"

Linux:

sudo systemctl restart trueconf-web

Caution

When TrueConf Server is updated, the chatbot directory will be deleted from the server. Repeat step 1 after an update if necessary.

Step 2. Ask each participant to obtain a token

Open https://server.address/chatbot/en/index.html in a browser.
Enter the TrueConf ID and password, then click Get token.
Copy or download the generated token and send it to the administrator.

Step 3. Add the tokens to the application

Fill in the Token column in the Users section for each participant.

Important

Make sure that each token is inserted into the row of the user it actually belongs to. Otherwise, messages may be migrated under the wrong identity.

After all participants' tokens have been added, proceed to chat migration.

Chat migration

Save the settings by clicking Apply. After that, the Start migration button will become active.
Click Start migration.

Warning

For chats of the group, supergroup, and channel types, a new chat instance will be created every time the migration is started.

If the migration is completed successfully, a copy of the Telegram chat will appear in TrueConf:

🎬 Watch the video on YouTube

❓ Troubleshooting

Problem	What to check
Error when automatically filling in @username	There is no connection to Telegram servers: check your network access tools.
User registration returns `🔴 Error`	Check that the `access_token` is valid (OAuth tokens are valid for 1 hour) and that the TrueConf ID has no typos.
Voice messages are not converted	Run `uv run check_ffmpeg.py` — FFmpeg must be in PATH and support the `drawtext` filter.
Stickers are not converted	Check whether the Cairo system library is installed (Windows). See the sticker conversion section.
Messages are migrated under the wrong user	Check that the token in the Token column is linked to the correct participant row.

If the problem persists, contact TrueConf technical support.

Name		Name	Last commit message	Last commit date
assets		assets
chatbot		chatbot
cover		cover
docs		docs
locales		locales
.gitignore		.gitignore
README-ru.md		README-ru.md
README.md		README.md
add_users_to_server.py		add_users_to_server.py
build_chat.py		build_chat.py
check_ffmpeg.py		check_ffmpeg.py
config.toml		config.toml
delete_users_from_server.py		delete_users_from_server.py
localization.py		localization.py
main.py		main.py
parse_users.py		parse_users.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Uh oh!

Repository files navigation

🛡️ Secure chat transfer from Telegram to TrueConf

🚀 Quick start

📖 Terms

Introduction

Telegram chat export

Installation and first launch

Python

Environment setup

Starting the application

Migration setup

Connections tab

Chat tab

Chat parameters

Migration options

Voice message conversion

Animated sticker conversion

Message date and time

Users tab

User registration in TrueConf Server

Configured infrastructure when using LDAP

Obtaining a token for chat API authorization

Chat migration

❓ Troubleshooting

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🛡️ Secure chat transfer from Telegram to TrueConf

🚀 Quick start

📖 Terms

Introduction

Telegram chat export

Installation and first launch

Python

Environment setup

Starting the application

Migration setup

Connections tab

Chat tab

Chat parameters

Migration options

Voice message conversion

Animated sticker conversion

Message date and time

Users tab

User registration in TrueConf Server

Configured infrastructure when using LDAP

Obtaining a token for chat API authorization

Chat migration

❓ Troubleshooting

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages