CAI-TG (Character.AI Telegram Bridge)

This script acts as a functional bridge connecting a Telegram bot to a Character.AI persona. Built using Python, aiogram, and PyCharacterAI, it allows you to communicate seamlessly with your favorite CAI characters straight from Telegram text and voice messages.

It features a native cross-platform GUI built with PyQt6 that lets you manage multiple character profiles, edit tokens easily, and monitor the bot's live standard output with syntax highlighting!

Features

• Profile Manager GUI: Easily switch between multiple character configurations (saved in the profiles/ directory) without touching code.
• Bundled Executables: Don't worry about installing Python or dependencies, just download the latest release from the Releases page and run the executable. (or use start.py to run the script with Python).
• Text & Voice Chat: Send your Character messages and receive text responses with occasional voice replies, if the voice ID is provided (you also can set the probability of voice replies in the GUI).
• Chat Management: Use straightforward Telegram commands to manage your ongoing CAI session.
• Persistent State: The bot dynamically creates or resumes chat sessions.
• Persona Context: Apply optional user Persona IDs to provide context directly to the Character.
• Secured Access: The bot is strictly locked to your personal Telegram User ID to prevent unauthorized users from chatting with it or leaking your session keys.
• Enhanced privacy: Toggle streamer mode to hide sensitive information from logs (tokens, chat IDs, messages etc.).
• Auto-update: The script will automatically check for updates from the GitHub repository and notify you if there are any updates available to download.
• Notification system: The bot will notify you if there are any updates available, if the bot is shut down, restored or if there are any other important events.
• Token extraction: Experimental feature: The script now can extract tokens and IDs from HAR files generated by the browser (Caution: it may not work for all users, use different browser like Firefox).
• Status command: Check /status command in your bot to see current session status, it will display basic things such as: current CAI character, persona, voice, session (chat ID), etc.

Setup & Launching

You do NOT need to manually install dependencies or manually create .env files. The project includes a universal start.py bootstrapper that handles everything automatically, and we also have prebuilt executables for Windows, Linux and macOS on the Releases page.

Install the script:

You have a few ways to install this script:

1. Git: Run this command in your terminal or command prompt (requires Git installed)

   git clone https://github.com/malichevsky/cai-tg.git

2. Download: Download the script by pressing the Code button on the GitHub page and selecting Download ZIP.

3. GitHub Releases: You can download the latest release from the Releases page.

Run the Universal Launcher:

python3 start.py

(Use python start.py on Windows)

This script will:

1. Automatically create an isolated virtual environment (.venv)
2. Install all required dependencies from requirements.txt quietly
3. Launch the native Desktop Interface

Using the GUI

Once the GUI opens:

1. First Launch: It will prompt you to create your first Profile. Pick a recognizable name for your character.
2. Settings: Switch to the Settings tab. Fill in your tokens. You can click the [?] help icons next to each field to get a detailed tutorial on where to find your Telegram Token, Character.AI Token, etc.
3. Hit Save Settings.
4. Click ▶ Start Bot. Switch to the Console tab to watch the live colorized event logs!

Having a question?

Before asking a question in the issues, we advice you to visit out FAQ page: FAQ, there you can find answers to the most common questions. And if you still haven't found an answer to your question, feel free to create an issue on the GitHub repository: Issues. Make sure to include:

• A detailed description of the problem
• The steps to reproduce the issue
• Any error messages or logs (screenshots are welcome)
• Your operating system and Python version

Any other suggestions, help, discussions or feature requests are also welcome, we are open to any feedback!

Useful Telegram Commands

While chatting with your bot on Telegram, you can use these commands to manage the CAI connection:

• /start — Retrieve the character's initial greeting or resume message.
• /retry — Re-roll the character's last reply 🔄
• /undo — Delete the last exchange 🗑
• /pin — Pin the character's last reply 📌
• /pins — List all pinned messages in the current CAI chat.
• /history — Display the last 10 messages.
• /persona — Display your active persona ID 🎭
• /status — Display current status of the bot 📊
• /reset — Forcefully start a brand-new chat.
• /help — Display the list of all commands.

Credits

cai-tg is built using the following amazing open-source libraries, without them, it wouldn't be possible to create this project. We thank the authors of these libraries for their great work:

• aiogram
• PyCharacterAI
• PyQt6
• rich

To-do

• Add notification system for updates, bot shutdowns, restores and other events instead of sending as a Telegram message.
• Add automated way to extract tokens and IDs from specific files (probably HAR files).
• Add support to recognize voice messages sent from user and reply with voice messages.
• Add support to recognize images sent from user and reply with images. (can stickers be recognized as images?)
• Add support for multiple characters.
• Support for Android devices??
• Fix /persona command because right now it produces an error. It should display the current persona ID.
• Battle "hey, i'm back" when user sends /start commmand while having existing chat.
• Maybe some new languages?
• [~] /status command to display current status of the bot from Telegram. Replace IDs with actual information in the status message. (e.g. Character name instead of character ID)
• Add white theme for GUI and console, automatically switching between light and dark themes depending on the system settings.