# Strands Telegram Listener
[](https://badge.fury.io/py/strands-telegram-listener)
[](https://opensource.org/licenses/MIT)
**Real-time Telegram message processing with AI-powered responses for Strands Agents**
A powerful background Telegram message processor that provides seamless real-time messaging capabilities with intelligent AI responses, event storage, and comprehensive message handling for Strands Agents.
## 🚀 Features
### 🎧 **Real-Time Message Processing**
- **Long Polling**: Efficient real-time message retrieval from Telegram
- **Background Processing**: Non-blocking message handling in separate threads
- **Auto-Reply Mode**: AI-powered automatic responses to incoming messages
- **Message Filtering**: Smart filtering to avoid processing own messages
- **Event Storage**: Persistent message history in JSONL format
### 🤖 **AI-Powered Responses**
- **Strands Agent Integration**: Seamless AI response generation
- **Context Awareness**: Maintains conversation context across messages
- **Intelligent Processing**: Advanced message understanding and response
- **Multi-Modal Support**: Text, media, and interactive message handling
### 📊 **Event Management**
- **Persistent Storage**: JSONL-based event logging for history
- **Real-Time Monitoring**: Live status updates and metrics
- **Event Retrieval**: Access to recent message history
- **Thread-Safe Operations**: Concurrent message processing
### 🔧 **Advanced Configuration**
- **Environment-Based Setup**: Easy configuration via environment variables
- **Trigger Keywords**: Optional keyword-based activation
- **Auto-Reply Control**: Toggle automatic responses on/off
- **Listen-Only Mode**: Process messages without responding
- **Comprehensive Logging**: Detailed operation logs
## 📦 Installation
```bash
pip install strands-telegram-listener
```
## 🤖 Bot Setup
Before using this tool, you need to create a Telegram bot and get an API token:
### 1. Create a Telegram Bot
1. **Open Telegram** and search for `@BotFather`
2. **Start a chat** with BotFather by clicking `/start`
3. **Create new bot** with `/newbot` command
4. **Choose a name** for your bot (e.g., "My Awesome Bot")
5. **Choose a username** for your bot (must end with "bot", e.g., "myawesomebot")
6. **Save the token** - BotFather will give you a token like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`
### 2. Configure Bot Settings (Optional)
You can customize your bot using BotFather commands:
- `/setdescription` - Set bot description
- `/setcommands` - Set bot commands menu
- `/setprivacy` - Enable/disable privacy mode for groups
- `/setjoingroups` - Allow bot to be added to groups
### 3. Get Your Bot Token
The token from BotFather is your `TELEGRAM_BOT_TOKEN`. Keep it secure!
### 4. Set Environment Variable
```bash
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
```
### 📚 Official Documentation
- **Telegram Bots Guide:** https://core.telegram.org/bots
- **Telegram Bot API:** https://core.telegram.org/bots/api
- **Full Telegram API:** https://core.telegram.org/api
## 🛠️ Usage
### Quick Start
```python
from strands import Agent
from strands_telegram_listener import telegram_listener
# Create agent with Telegram listener
agent = Agent(tools=[telegram_listener])
# Start listening for messages
agent.tool.telegram_listener(action="start")
# Check listener status
agent.tool.telegram_listener(action="status")
# Get recent events
agent.tool.telegram_listener(action="get_recent_events", count=10)
# Stop listening
agent.tool.telegram_listener(action="stop")
```
### Environment Setup
```bash
# Required: Set your Telegram Bot Token (get from @BotFather)
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
# Optional: Enable automatic AI responses
export STRANDS_TELEGRAM_AUTO_REPLY="true"
# Optional: Only process messages containing this tag
export STRANDS_TELEGRAM_LISTEN_ONLY_TAG="@mybot"
# Optional: Number of events to retrieve by default
export TELEGRAM_DEFAULT_EVENT_COUNT="20"
```
### Advanced Examples
#### Auto-Reply Bot
```python
import os
from strands import Agent
from strands_telegram_listener import telegram_listener
# Enable auto-reply mode
os.environ["STRANDS_TELEGRAM_AUTO_REPLY"] = "true"
# Create intelligent bot agent
agent = Agent(
system_prompt="""
You are a helpful Telegram bot assistant.
Respond concisely and helpfully to user messages.
Use appropriate emojis and Telegram formatting.
""",
tools=[telegram_listener]
)
# Start listening - bot will automatically respond to messages
agent.tool.telegram_listener(action="start")
print("🤖 AI Bot is now listening and responding!")
```
#### Monitoring Bot
```python
from strands import Agent
from strands_telegram_listener import telegram_listener
# Create monitoring agent (no auto-reply)
agent = Agent(tools=[telegram_listener])
# Start listening in monitor-only mode
agent.tool.telegram_listener(action="start")
# Check status periodically
import time
while True:
status = agent.tool.telegram_listener(action="status")
print(f"Bot Status: {status}")
# Get recent messages
events = agent.tool.telegram_listener(action="get_recent_events", count=5)
print(f"Recent Events: {events}")
time.sleep(60) # Check every minute
```
#### Selective Listening
```python
import os
from strands import Agent
from strands_telegram_listener import telegram_listener
# Only process messages containing specific tag
os.environ["STRANDS_TELEGRAM_LISTEN_ONLY_TAG"] = "#support"
agent = Agent(
system_prompt="You are a customer support bot. Handle support requests professionally.",
tools=[telegram_listener]
)
# Bot will only respond to messages containing "#support"
agent.tool.telegram_listener(action="start")
```
## 📋 Available Actions
### Core Operations
- `start` - Begin listening for Telegram messages in background
- `stop` - Stop the message listener
- `status` - Get current listener status and configuration
- `get_recent_events` - Retrieve recent events from storage
### Status Information
The status action returns comprehensive information:
```json
{
"running": true,
"bot_info": {
"id": 123456789,
"is_bot": true,
"first_name": "MyBot",
"username": "my_bot"
},
"last_update_id": 123456,
"events_file": "/path/to/telegram_events/events.jsonl",
"auto_reply": "true",
"listen_only_tag": "None"
}
```
## 🔒 Security & Best Practices
### Token Security
- **Never hardcode tokens** in your code
- **Use environment variables** for bot tokens
- **Rotate tokens regularly** for production use
- **Monitor bot permissions** and access logs
### Message Processing
- **Own Message Filtering**: Automatically ignores bot's own messages
- **Duplicate Prevention**: Handles message de-duplication
- **Error Recovery**: Robust error handling with automatic retries
- **Rate Limiting**: Respects Telegram's rate limits
### Production Deployment
```python
# Production configuration example
import os
import logging
from strands import Agent
from strands_telegram_listener import telegram_listener
# Configure logging
logging.basicConfig(level=logging.INFO)
# Production environment variables
os.environ["TELEGRAM_BOT_TOKEN"] = "your_production_token"
os.environ["STRANDS_TELEGRAM_AUTO_REPLY"] = "true"
os.environ["TELEGRAM_DEFAULT_EVENT_COUNT"] = "50"
# Create production agent
agent = Agent(
system_prompt="""
Production Telegram Bot Assistant.
- Respond professionally and helpfully
- Handle errors gracefully
- Log important interactions
- Maintain conversation context
""",
tools=[telegram_listener]
)
# Start with error handling
try:
result = agent.tool.telegram_listener(action="start")
print(f"✅ Production bot started: {result}")
except Exception as e:
print(f"❌ Failed to start bot: {e}")
```
## 🎯 Integration Patterns
### With strands-telegram Package
```python
from strands import Agent
from strands_telegram import telegram
from strands_telegram_listener import telegram_listener
# Agent with both tools
agent = Agent(
system_prompt="You are a comprehensive Telegram bot with full API access.",
tools=[telegram, telegram_listener]
)
# Start listening
agent.tool.telegram_listener(action="start")
# Bot can now both listen and actively send messages
# The listener will automatically use the telegram tool for responses
```
### Custom Message Processing
```python
from strands import Agent
from strands_telegram_listener import telegram_listener
class CustomTelegramAgent(Agent):
def process_telegram_message(self, message_data):
"""Custom message processing logic."""
# Your custom processing here
user = message_data.get("from", {})
text = message_data.get("text", "")
# Process with AI
response = self(f"User {user.get('first_name', 'User')} says: {text}")
# Return response for auto-reply
return str(response)
agent = CustomTelegramAgent(tools=[telegram_listener])
agent.tool.telegram_listener(action="start")
```
## 📊 Event Storage Format
Events are stored in JSONL format at `./telegram_events/events.jsonl`:
```json
{
"event_type": "telegram_update",
"payload": {
"update_id": 123456,
"message": {
"message_id": 789,
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"username": "johndoe"
},
"chat": {
"id": 987654321,
"first_name": "John",
"username": "johndoe",
"type": "private"
},
"date": 1697723456,
"text": "Hello bot!"
}
},
"timestamp": 1697723456.789,
"update_id": 123456
}
```
## 🔧 Configuration Reference
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `TELEGRAM_BOT_TOKEN` | ✅ Yes | - | Bot token from @BotFather |
| `STRANDS_TELEGRAM_AUTO_REPLY` | ❌ No | `false` | Enable automatic AI responses |
| `STRANDS_TELEGRAM_LISTEN_ONLY_TAG` | ❌ No | - | Only process messages with this tag |
| `TELEGRAM_DEFAULT_EVENT_COUNT` | ❌ No | `20` | Default number of events to retrieve |
### Bot Configuration
#### Get Bot Token
1. Message [@BotFather](https://t.me/BotFather) on Telegram
2. Use `/newbot` command to create a new bot
3. Follow instructions to set bot name and username
4. Copy the provided bot token
5. Set as `TELEGRAM_BOT_TOKEN` environment variable
#### Bot Permissions
Ensure your bot has appropriate permissions:
- **Send Messages**: Required for auto-reply
- **Read Messages**: Required for message processing
- **Manage Groups**: If using in groups (optional)
## 🤝 Contributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
### Development Setup
```bash
git clone https://github.com/yourusername/strands-telegram-listener
cd strands-telegram-listener
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=strands_telegram_listener
# Run specific test
pytest tests/test_telegram_listener.py::TestTelegramListener::test_start_listener
```
## 📚 API Reference
### telegram_listener(action, count=20, agent=None)
**Parameters:**
- `action` (str): The action to perform
- `"start"`: Begin listening for messages
- `"stop"`: Stop the listener
- `"status"`: Get listener status
- `"get_recent_events"`: Retrieve recent events
- `count` (int): Number of events to retrieve (for get_recent_events)
- `agent` (Agent): Strands agent instance (auto-provided)
**Returns:**
- `str`: Status message or event data based on the action
## 🔗 Related Packages
- **[strands-telegram](https://pypi.org/project/strands-telegram/)**: Complete Telegram Bot API tool
- **[strands](https://pypi.org/project/strands/)**: Core Strands Agents framework
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 🔗 Links
- [Strands Agents Documentation](https://strandsagents.com)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [PyPI Package](https://pypi.org/project/strands-telegram-listener/)
- [GitHub Repository](https://github.com/yourusername/strands-telegram-listener)
## 📞 Support
- Create an issue on GitHub for bug reports
- Join our community discussions for questions
- Check the Strands Agents documentation for integration help
---
**Made with ❤️ for the Strands Agents community**
Raw data
{
"_id": null,
"home_page": null,
"name": "strands-telegram-listener",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "strands, agents, telegram, bot, listener, ai, realtime, messaging, automation, background, polling, events",
"author": null,
"author_email": "Strands Community <community@strandsagents.com>",
"download_url": "https://files.pythonhosted.org/packages/75/fc/3c39fc6cff562ac73616d6c694b544a140b4e44103acdb80cb4313c349ec/strands_telegram_listener-1.0.0.tar.gz",
"platform": null,
"description": "# Strands Telegram Listener\n\n[](https://badge.fury.io/py/strands-telegram-listener)\n[](https://opensource.org/licenses/MIT)\n\n**Real-time Telegram message processing with AI-powered responses for Strands Agents**\n\nA powerful background Telegram message processor that provides seamless real-time messaging capabilities with intelligent AI responses, event storage, and comprehensive message handling for Strands Agents.\n\n## \ud83d\ude80 Features\n\n### \ud83c\udfa7 **Real-Time Message Processing**\n- **Long Polling**: Efficient real-time message retrieval from Telegram\n- **Background Processing**: Non-blocking message handling in separate threads\n- **Auto-Reply Mode**: AI-powered automatic responses to incoming messages\n- **Message Filtering**: Smart filtering to avoid processing own messages\n- **Event Storage**: Persistent message history in JSONL format\n\n### \ud83e\udd16 **AI-Powered Responses**\n- **Strands Agent Integration**: Seamless AI response generation\n- **Context Awareness**: Maintains conversation context across messages\n- **Intelligent Processing**: Advanced message understanding and response\n- **Multi-Modal Support**: Text, media, and interactive message handling\n\n### \ud83d\udcca **Event Management**\n- **Persistent Storage**: JSONL-based event logging for history\n- **Real-Time Monitoring**: Live status updates and metrics\n- **Event Retrieval**: Access to recent message history\n- **Thread-Safe Operations**: Concurrent message processing\n\n### \ud83d\udd27 **Advanced Configuration**\n- **Environment-Based Setup**: Easy configuration via environment variables\n- **Trigger Keywords**: Optional keyword-based activation\n- **Auto-Reply Control**: Toggle automatic responses on/off\n- **Listen-Only Mode**: Process messages without responding\n- **Comprehensive Logging**: Detailed operation logs\n\n## \ud83d\udce6 Installation\n\n```bash\npip install strands-telegram-listener\n```\n\n## \ud83e\udd16 Bot Setup\n\nBefore using this tool, you need to create a Telegram bot and get an API token:\n\n### 1. Create a Telegram Bot\n\n1. **Open Telegram** and search for `@BotFather`\n2. **Start a chat** with BotFather by clicking `/start`\n3. **Create new bot** with `/newbot` command\n4. **Choose a name** for your bot (e.g., \"My Awesome Bot\")\n5. **Choose a username** for your bot (must end with \"bot\", e.g., \"myawesomebot\")\n6. **Save the token** - BotFather will give you a token like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`\n\n### 2. Configure Bot Settings (Optional)\n\nYou can customize your bot using BotFather commands:\n- `/setdescription` - Set bot description\n- `/setcommands` - Set bot commands menu\n- `/setprivacy` - Enable/disable privacy mode for groups\n- `/setjoingroups` - Allow bot to be added to groups\n\n### 3. Get Your Bot Token\n\nThe token from BotFather is your `TELEGRAM_BOT_TOKEN`. Keep it secure!\n\n### 4. Set Environment Variable\n\n```bash\nexport TELEGRAM_BOT_TOKEN=\"your_bot_token_here\"\n```\n\n### \ud83d\udcda Official Documentation\n\n- **Telegram Bots Guide:** https://core.telegram.org/bots\n- **Telegram Bot API:** https://core.telegram.org/bots/api \n- **Full Telegram API:** https://core.telegram.org/api\n\n## \ud83d\udee0\ufe0f Usage\n\n### Quick Start\n\n```python\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\n# Create agent with Telegram listener\nagent = Agent(tools=[telegram_listener])\n\n# Start listening for messages\nagent.tool.telegram_listener(action=\"start\")\n\n# Check listener status\nagent.tool.telegram_listener(action=\"status\")\n\n# Get recent events\nagent.tool.telegram_listener(action=\"get_recent_events\", count=10)\n\n# Stop listening\nagent.tool.telegram_listener(action=\"stop\")\n```\n\n### Environment Setup\n\n```bash\n# Required: Set your Telegram Bot Token (get from @BotFather)\nexport TELEGRAM_BOT_TOKEN=\"your_bot_token_here\"\n\n# Optional: Enable automatic AI responses\nexport STRANDS_TELEGRAM_AUTO_REPLY=\"true\"\n\n# Optional: Only process messages containing this tag\nexport STRANDS_TELEGRAM_LISTEN_ONLY_TAG=\"@mybot\"\n\n# Optional: Number of events to retrieve by default\nexport TELEGRAM_DEFAULT_EVENT_COUNT=\"20\"\n```\n\n### Advanced Examples\n\n#### Auto-Reply Bot\n```python\nimport os\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\n# Enable auto-reply mode\nos.environ[\"STRANDS_TELEGRAM_AUTO_REPLY\"] = \"true\"\n\n# Create intelligent bot agent\nagent = Agent(\n system_prompt=\"\"\"\n You are a helpful Telegram bot assistant. \n Respond concisely and helpfully to user messages.\n Use appropriate emojis and Telegram formatting.\n \"\"\",\n tools=[telegram_listener]\n)\n\n# Start listening - bot will automatically respond to messages\nagent.tool.telegram_listener(action=\"start\")\nprint(\"\ud83e\udd16 AI Bot is now listening and responding!\")\n```\n\n#### Monitoring Bot\n```python\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\n# Create monitoring agent (no auto-reply)\nagent = Agent(tools=[telegram_listener])\n\n# Start listening in monitor-only mode\nagent.tool.telegram_listener(action=\"start\")\n\n# Check status periodically\nimport time\nwhile True:\n status = agent.tool.telegram_listener(action=\"status\")\n print(f\"Bot Status: {status}\")\n \n # Get recent messages\n events = agent.tool.telegram_listener(action=\"get_recent_events\", count=5)\n print(f\"Recent Events: {events}\")\n \n time.sleep(60) # Check every minute\n```\n\n#### Selective Listening\n```python\nimport os\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\n# Only process messages containing specific tag\nos.environ[\"STRANDS_TELEGRAM_LISTEN_ONLY_TAG\"] = \"#support\"\n\nagent = Agent(\n system_prompt=\"You are a customer support bot. Handle support requests professionally.\",\n tools=[telegram_listener]\n)\n\n# Bot will only respond to messages containing \"#support\"\nagent.tool.telegram_listener(action=\"start\")\n```\n\n## \ud83d\udccb Available Actions\n\n### Core Operations\n- `start` - Begin listening for Telegram messages in background\n- `stop` - Stop the message listener\n- `status` - Get current listener status and configuration \n- `get_recent_events` - Retrieve recent events from storage\n\n### Status Information\nThe status action returns comprehensive information:\n```json\n{\n \"running\": true,\n \"bot_info\": {\n \"id\": 123456789,\n \"is_bot\": true,\n \"first_name\": \"MyBot\",\n \"username\": \"my_bot\"\n },\n \"last_update_id\": 123456,\n \"events_file\": \"/path/to/telegram_events/events.jsonl\",\n \"auto_reply\": \"true\",\n \"listen_only_tag\": \"None\"\n}\n```\n\n## \ud83d\udd12 Security & Best Practices\n\n### Token Security\n- **Never hardcode tokens** in your code\n- **Use environment variables** for bot tokens\n- **Rotate tokens regularly** for production use\n- **Monitor bot permissions** and access logs\n\n### Message Processing\n- **Own Message Filtering**: Automatically ignores bot's own messages\n- **Duplicate Prevention**: Handles message de-duplication\n- **Error Recovery**: Robust error handling with automatic retries\n- **Rate Limiting**: Respects Telegram's rate limits\n\n### Production Deployment\n```python\n# Production configuration example\nimport os\nimport logging\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\n# Configure logging\nlogging.basicConfig(level=logging.INFO)\n\n# Production environment variables\nos.environ[\"TELEGRAM_BOT_TOKEN\"] = \"your_production_token\"\nos.environ[\"STRANDS_TELEGRAM_AUTO_REPLY\"] = \"true\"\nos.environ[\"TELEGRAM_DEFAULT_EVENT_COUNT\"] = \"50\"\n\n# Create production agent\nagent = Agent(\n system_prompt=\"\"\"\n Production Telegram Bot Assistant.\n - Respond professionally and helpfully\n - Handle errors gracefully\n - Log important interactions\n - Maintain conversation context\n \"\"\",\n tools=[telegram_listener]\n)\n\n# Start with error handling\ntry:\n result = agent.tool.telegram_listener(action=\"start\")\n print(f\"\u2705 Production bot started: {result}\")\nexcept Exception as e:\n print(f\"\u274c Failed to start bot: {e}\")\n```\n\n## \ud83c\udfaf Integration Patterns\n\n### With strands-telegram Package\n```python\nfrom strands import Agent\nfrom strands_telegram import telegram\nfrom strands_telegram_listener import telegram_listener\n\n# Agent with both tools\nagent = Agent(\n system_prompt=\"You are a comprehensive Telegram bot with full API access.\",\n tools=[telegram, telegram_listener]\n)\n\n# Start listening\nagent.tool.telegram_listener(action=\"start\")\n\n# Bot can now both listen and actively send messages\n# The listener will automatically use the telegram tool for responses\n```\n\n### Custom Message Processing\n```python\nfrom strands import Agent\nfrom strands_telegram_listener import telegram_listener\n\nclass CustomTelegramAgent(Agent):\n def process_telegram_message(self, message_data):\n \"\"\"Custom message processing logic.\"\"\"\n # Your custom processing here\n user = message_data.get(\"from\", {})\n text = message_data.get(\"text\", \"\")\n \n # Process with AI\n response = self(f\"User {user.get('first_name', 'User')} says: {text}\")\n \n # Return response for auto-reply\n return str(response)\n\nagent = CustomTelegramAgent(tools=[telegram_listener])\nagent.tool.telegram_listener(action=\"start\")\n```\n\n## \ud83d\udcca Event Storage Format\n\nEvents are stored in JSONL format at `./telegram_events/events.jsonl`:\n\n```json\n{\n \"event_type\": \"telegram_update\",\n \"payload\": {\n \"update_id\": 123456,\n \"message\": {\n \"message_id\": 789,\n \"from\": {\n \"id\": 987654321,\n \"is_bot\": false,\n \"first_name\": \"John\",\n \"username\": \"johndoe\"\n },\n \"chat\": {\n \"id\": 987654321,\n \"first_name\": \"John\",\n \"username\": \"johndoe\",\n \"type\": \"private\"\n },\n \"date\": 1697723456,\n \"text\": \"Hello bot!\"\n }\n },\n \"timestamp\": 1697723456.789,\n \"update_id\": 123456\n}\n```\n\n## \ud83d\udd27 Configuration Reference\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `TELEGRAM_BOT_TOKEN` | \u2705 Yes | - | Bot token from @BotFather |\n| `STRANDS_TELEGRAM_AUTO_REPLY` | \u274c No | `false` | Enable automatic AI responses |\n| `STRANDS_TELEGRAM_LISTEN_ONLY_TAG` | \u274c No | - | Only process messages with this tag |\n| `TELEGRAM_DEFAULT_EVENT_COUNT` | \u274c No | `20` | Default number of events to retrieve |\n\n### Bot Configuration\n\n#### Get Bot Token\n1. Message [@BotFather](https://t.me/BotFather) on Telegram\n2. Use `/newbot` command to create a new bot\n3. Follow instructions to set bot name and username\n4. Copy the provided bot token\n5. Set as `TELEGRAM_BOT_TOKEN` environment variable\n\n#### Bot Permissions\nEnsure your bot has appropriate permissions:\n- **Send Messages**: Required for auto-reply\n- **Read Messages**: Required for message processing\n- **Manage Groups**: If using in groups (optional)\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit issues, feature requests, or pull requests.\n\n### Development Setup\n```bash\ngit clone https://github.com/yourusername/strands-telegram-listener\ncd strands-telegram-listener\npip install -e \".[dev]\"\n```\n\n### Running Tests\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=strands_telegram_listener\n\n# Run specific test\npytest tests/test_telegram_listener.py::TestTelegramListener::test_start_listener\n```\n\n## \ud83d\udcda API Reference\n\n### telegram_listener(action, count=20, agent=None)\n\n**Parameters:**\n- `action` (str): The action to perform\n - `\"start\"`: Begin listening for messages\n - `\"stop\"`: Stop the listener\n - `\"status\"`: Get listener status\n - `\"get_recent_events\"`: Retrieve recent events\n- `count` (int): Number of events to retrieve (for get_recent_events)\n- `agent` (Agent): Strands agent instance (auto-provided)\n\n**Returns:**\n- `str`: Status message or event data based on the action\n\n## \ud83d\udd17 Related Packages\n\n- **[strands-telegram](https://pypi.org/project/strands-telegram/)**: Complete Telegram Bot API tool\n- **[strands](https://pypi.org/project/strands/)**: Core Strands Agents framework\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## \ud83d\udd17 Links\n\n- [Strands Agents Documentation](https://strandsagents.com)\n- [Telegram Bot API](https://core.telegram.org/bots/api)\n- [PyPI Package](https://pypi.org/project/strands-telegram-listener/)\n- [GitHub Repository](https://github.com/yourusername/strands-telegram-listener)\n\n## \ud83d\udcde Support\n\n- Create an issue on GitHub for bug reports\n- Join our community discussions for questions\n- Check the Strands Agents documentation for integration help\n\n---\n\n**Made with \u2764\ufe0f for the Strands Agents community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Real-time Telegram message processing with AI-powered responses for Strands Agents",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/strands-agents/strands-telegram-listener/issues",
"Changelog": "https://github.com/strands-agents/strands-telegram-listener/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/strands-agents/strands-telegram-listener#readme",
"Homepage": "https://github.com/strands-agents/strands-telegram-listener",
"Repository": "https://github.com/strands-agents/strands-telegram-listener.git"
},
"split_keywords": [
"strands",
" agents",
" telegram",
" bot",
" listener",
" ai",
" realtime",
" messaging",
" automation",
" background",
" polling",
" events"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15076d1e883917993ee10dc241d7ab68cc1cba3e725fbf2b8a0effd689adce4c",
"md5": "dcaabfa7fe5b1d7802e3c17fc0a69ea6",
"sha256": "d6183e9957248a769a68ff421cc6a8e638d84eed70bfccf9f31869e7dca7f4fa"
},
"downloads": -1,
"filename": "strands_telegram_listener-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dcaabfa7fe5b1d7802e3c17fc0a69ea6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13442,
"upload_time": "2025-10-20T02:21:26",
"upload_time_iso_8601": "2025-10-20T02:21:26.320838Z",
"url": "https://files.pythonhosted.org/packages/15/07/6d1e883917993ee10dc241d7ab68cc1cba3e725fbf2b8a0effd689adce4c/strands_telegram_listener-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "75fc3c39fc6cff562ac73616d6c694b544a140b4e44103acdb80cb4313c349ec",
"md5": "bb81d9f564310f014b444719d4109b96",
"sha256": "4a175403ac5e4850cbe97e900191d975f22a8c9590bb058c815b3798b8926b59"
},
"downloads": -1,
"filename": "strands_telegram_listener-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bb81d9f564310f014b444719d4109b96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19132,
"upload_time": "2025-10-20T02:21:27",
"upload_time_iso_8601": "2025-10-20T02:21:27.745947Z",
"url": "https://files.pythonhosted.org/packages/75/fc/3c39fc6cff562ac73616d6c694b544a140b4e44103acdb80cb4313c349ec/strands_telegram_listener-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 02:21:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "strands-agents",
"github_project": "strands-telegram-listener",
"github_not_found": true,
"lcname": "strands-telegram-listener"
}
JSON
