{"id":23719278,"url":"https://github.com/ifokeev/telegram-ai-agent","last_synced_at":"2025-09-03T20:33:06.942Z","repository":{"id":269419786,"uuid":"864450137","full_name":"ifokeev/telegram-ai-agent","owner":"ifokeev","description":"Telegram AI Agent: A powerful Python library for creating AI-powered Telegram bots","archived":false,"fork":false,"pushed_at":"2024-12-23T12:42:29.000Z","size":120,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-23T12:46:02.763Z","etag":null,"topics":["ai-agents","telegram","telegram-userbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ifokeev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-28T08:50:11.000Z","updated_at":"2024-12-23T12:42:33.000Z","dependencies_parsed_at":"2024-12-23T12:46:06.243Z","dependency_job_id":"9ac8310d-7fe5-4208-8c54-99b5b1d03b63","html_url":"https://github.com/ifokeev/telegram-ai-agent","commit_stats":null,"previous_names":["ifokeev/telegram-ai-agent"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ifokeev%2Ftelegram-ai-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ifokeev%2Ftelegram-ai-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ifokeev%2Ftelegram-ai-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ifokeev%2Ftelegram-ai-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ifokeev","download_url":"https://codeload.github.com/ifokeev/telegram-ai-agent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231918561,"owners_count":18445746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","telegram","telegram-userbot"],"created_at":"2024-12-30T21:48:46.319Z","updated_at":"2025-09-03T20:33:06.917Z","avatar_url":"https://github.com/ifokeev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram AI Agent Library\n\n[![PyPI version](https://badge.fury.io/py/telegram-ai-agent.svg)](https://badge.fury.io/py/telegram-ai-agent)\n[![Python Version](https://img.shields.io/pypi/pyversions/telegram-ai-agent.svg)](https://pypi.org/project/telegram-ai-agent/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI Downloads](https://static.pepy.tech/badge/telegram-ai-agent)](https://pepy.tech/projects/telegram-ai-agent)\n\nThis Python library provides a framework for creating AI-powered Telegram bots using the Telegram Core API and the [phi](https://github.com/phidatahq/phidata) library for AI integration.\n\n## Features\n\n- Secure authentication with Telegram servers\n- Inbound message processing with AI integration using [phi](https://github.com/phidatahq/phidata)\n- Outbound messaging capabilities\n- Chat history support for context-aware responses\n- Configurable proxy and timeout settings\n- Asynchronous operations using asyncio\n- Typing indicators for a more natural conversation flow\n- Function calling for AI-powered tools\n- Customizable logging\n- Streamlit UI for easy interaction with the agent\n\n## Installation\n\nYou can install the library directly from PyPI:\n\n```sh\npip install telegram-ai-agent\n```\n\n### Using Poetry\n\nIf you're using Poetry for dependency management:\n\n```sh\npoetry add telegram-ai-agent\n```\n\n### Install from source\n\n1. Clone the repository:\n   ```sh\n   git clone https://github.com/ifokeev/telegram-ai-agent.git\n   cd telegram-ai-agent\n   ```\n\n2. Using Poetry (recommended):\n   ```sh\n   poetry install\n   ```\n\n   This will create a virtual environment and install all dependencies automatically.\n\n3. Or using pip with a virtual environment:\n   ```sh\n   python -m venv .venv\n   source .venv/bin/activate  # On Windows, use `.venv\\Scripts\\activate`\n   pip install -e .\n   ```\n\nNote: Make sure you have Python 3.11 or higher installed on your system before proceeding with the installation.\n\n### Development Installation\n\nFor development purposes, install with additional dependencies:\n\n```sh\n# Using pip\npip install -e \".[dev]\"\n\n# Using Poetry\npoetry install --with dev\n```\n\nThis will install additional packages needed for development, such as:\n- pytest for testing\n- ruff for linting\n- black for code formatting\n- pre-commit hooks\n\n## Streamlit UI\n\nTo run the Streamlit UI, run the following command:\n\n```sh\nstreamlit run streamlit_app/Home.py\n```\n\nand navigate to `http://localhost:8501` in your web browser.\n\n### Video Tutorial\n\nWatch our video tutorial to learn how to use the Streamlit UI:\n\n[![Telegram AI Agent Streamlit UI Tutorial](https://img.youtube.com/vi/CxiQi1CnueE/0.jpg)](https://youtu.be/CxiQi1CnueE)\n\nThe video demonstrates:\n- Setting up your Telegram account\n- Managing AI assistants\n- Running and monitoring agents\n- Using the chat interface\n- Managing user segments and campaigns\n\nThis visual guide will help you get started with the Telegram AI Agent's user interface quickly and efficiently.\n\n## Configuration\n\nTo configure the Telegram AI Agent library, you need to set up environment variables. You can do this by either creating a `.env` file or copying from the provided `.env.example` file.\n\n### Option 1: Create a new .env file\n\n\nCreate a `.env` file in the root directory of your project with the following content:\n\n```\nTELEGRAM_API_ID=your_api_id_here\nTELEGRAM_API_HASH=your_api_hash_here\nTELEGRAM_PHONE_NUMBER=your_phone_number_here\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Optional: Proxy settings\n# PROXY_TYPE=socks5\n# PROXY_ADDR=1.1.1.1\n# PROXY_PORT=5555\n# PROXY_USERNAME=username\n# PROXY_PASSWORD=password\n\n```\n\nReplace the placeholder values with your actual Telegram API credentials and OpenAI API key.\n\n### Option 2: Copy from .env.example\n\nIf you prefer not to create a new file, you can copy the `.env.example` file to `.env` and modify the values as needed.\n\n## Usage\n\nHere's a basic example of how to use the Telegram AI Agent:\n\n```python\nimport asyncio\nimport logging\nfrom dotenv import load_dotenv\nimport os\nfrom telegram_ai_agent import TelegramAIAgent, TelegramConfig\nfrom telegram_ai_agent.utils import setup_logging\nfrom phi.assistant.assistant import Assistant\nfrom phi.llm.openai.chat import OpenAIChat\n\n# Load environment variables and setup logging\nload_dotenv()\nsetup_logging()\nlogger = logging.getLogger(__name__)\n\n# Optional: Load proxy settings if provided\nproxy = None\nif (\n    os.getenv(\"PROXY_TYPE\")\n    and os.getenv(\"PROXY_ADDR\")\n    and os.getenv(\"PROXY_PORT\")\n):\n    proxy = {\n        'proxy_type': os.getenv(\"PROXY_TYPE\"),  # socks5, socks4, or http\n        'addr': os.getenv(\"PROXY_ADDR\"),\n        'port': int(os.getenv(\"PROXY_PORT\")),\n        'rdns': True  # Use remote DNS resolution\n    }\n\n    # Add proxy authentication if provided\n    if os.getenv(\"PROXY_USERNAME\") and os.getenv(\"PROXY_PASSWORD\"):\n        proxy['username'] = os.getenv(\"PROXY_USERNAME\")\n        proxy['password'] = os.getenv(\"PROXY_PASSWORD\")\n\n# Create OpenAI assistant\nopenai_chat = OpenAIChat(api_key=os.getenv(\"OPENAI_API_KEY\"))\nassistant = Assistant(\n    llm=openai_chat,\n    run_id=\"telegram_ai_agent\",\n    description=\"Sales representative for a tech company\",\n    instructions=[\"You are a sales representative for a tech company. You are tasked with selling a product to the user.\"]\n)\n\n# Create Telegram configuration\ntelegram_config = TelegramConfig(\n    session_name=\"session_1\",\n    api_id=int(os.getenv(\"TELEGRAM_API_ID\")),\n    api_hash=os.getenv(\"TELEGRAM_API_HASH\")),\n    phone_number=os.getenv(\"TELEGRAM_PHONE_NUMBER\"),\n    proxy=proxy,\n    # Optional: Advanced settings\n    timeout=30,\n    set_typing=True,\n    typing_delay_factor=0.05,\n    typing_delay_max=30.0,\n    min_typing_speed=100.0,\n    max_typing_speed=200.0,\n    chat_history_limit=100,\n)\n\nasync def get_code():\n    return input(\"Enter the code you received: \")\n\nasync def get_password():\n    return input(\"Enter your password: \")\n\nasync def main():\n    try:\n        # Create and start the Telegram AI Agent\n        agent = TelegramAIAgent(\n            assistant,\n            telegram_config,\n            logger=logger,\n            code_callback=get_code,\n            twofa_password_callback=get_password,\n        )\n        # Run agent inbound processing until disconnected\n        await agent.run()\n    except Exception as e:\n        logger.error(f\"An error occurred: {str(e)}\")\n    finally:\n        if agent.session:\n            await agent.stop()\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nFor more detailed examples, check the `examples` directory.\n\n## Testing\n\nThis project uses pytest for unit testing. To run the tests, first install the development dependencies:\n\n```sh\npip install -e .[dev]\n```\n\nThen, you can run the tests using:\n\n```sh\npytest tests/\n```\n\nThe test suite includes unit tests for the `TelegramAIAgent` class, covering initialization, starting, stopping, sending messages, and processing incoming messages.\n\nTo add new tests or modify existing ones, check the `tests/test_agent.py` file.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fifokeev%2Ftelegram-ai-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fifokeev%2Ftelegram-ai-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fifokeev%2Ftelegram-ai-agent/lists"}