# Strands Telegram
[](https://pypi.org/project/strands-telegram/)
[](https://pypi.org/project/strands-telegram/)
[](https://opensource.org/licenses/MIT)
**Comprehensive Telegram Bot API integration for Strands Agents**
A complete Telegram Bot API tool that provides seamless integration with Strands Agents, supporting all major Telegram Bot API operations with full flexibility and rich features.
## 🚀 Features
### 📨 **Message Operations**
- **Text Messages**: Send rich text with HTML/Markdown formatting
- **Media Support**: Photos, videos, audio, documents, voice messages
- **Interactive Elements**: Polls, dice games, location sharing, contact cards
- **Message Management**: Edit, delete, forward, copy, pin/unpin messages
### 🎮 **Interactive Features**
- **Inline Keyboards**: Create interactive button menus
- **Custom Keyboards**: Reply keyboards with custom layouts
- **Callback Queries**: Handle button press events
- **Rich Media**: Stickers, animations, and multimedia content
### 👥 **Group & Channel Management**
- **User Management**: Kick, ban, unban, promote users
- **Permissions**: Set chat permissions and restrictions
- **Administration**: Manage chat settings, photos, descriptions
- **Member Info**: Get chat members, administrators, and statistics
### 🔧 **Bot Management**
- **Webhook Support**: Set up and manage webhooks
- **Bot Information**: Get bot details and configuration
- **Updates Handling**: Retrieve and process bot updates
- **File Operations**: Upload, download, and manage files
## 📦 Installation
```bash
pip install strands-telegram
```
## 🤖 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 import telegram
# Create agent with Telegram tool
agent = Agent(tools=[telegram])
# Send a message
agent.tool.telegram(
action="send_message",
chat_id="@username",
text="Hello from Strands! 🚀"
)
```
### Environment Setup
```bash
# Set your Telegram Bot Token (get from @BotFather)
export TELEGRAM_BOT_TOKEN="your_bot_token_here"
```
### Advanced Examples
#### Interactive Keyboard
```python
# Send message with inline keyboard
agent.tool.telegram(
action="send_message",
chat_id="123456789",
text="Choose an option:",
inline_keyboard=[
[{"text": "Option 1", "callback_data": "opt1"}],
[{"text": "Option 2", "callback_data": "opt2"}]
]
)
```
#### Send Photo with Caption
```python
# Send photo from local file
agent.tool.telegram(
action="send_photo",
chat_id="123456789",
file_path="/path/to/photo.jpg",
text="Check out this amazing photo! 📸"
)
# Send photo from URL
agent.tool.telegram(
action="send_photo",
chat_id="123456789",
file_url="https://example.com/photo.jpg",
text="Photo from the web 🌐"
)
```
#### Create Poll
```python
# Create a poll
agent.tool.telegram(
action="send_poll",
chat_id="123456789",
question="What's your favorite Strands feature?",
options=["AI Tools", "Multi-agent", "Workflows", "All of them!"]
)
```
#### Group Management
```python
# Promote user to admin
agent.tool.telegram(
action="promote_chat_member",
chat_id="-100123456789",
user_id=987654321
)
# Set chat permissions
agent.tool.telegram(
action="set_chat_permissions",
chat_id="-100123456789",
permissions={
"can_send_messages": True,
"can_send_media_messages": False
}
)
```
## 📋 Supported Actions
### Message Operations
- `send_message` - Send text messages
- `send_photo` - Send photos
- `send_video` - Send videos
- `send_audio` - Send audio files
- `send_document` - Send documents
- `send_voice` - Send voice messages
- `send_sticker` - Send stickers
- `send_location` - Send location coordinates
- `send_contact` - Send contact information
- `send_poll` - Create polls
- `send_dice` - Send dice animations
### Message Management
- `edit_message` - Edit message text
- `delete_message` - Delete messages
- `forward_message` - Forward messages
- `copy_message` - Copy messages
- `pin_message` - Pin messages
- `unpin_message` - Unpin messages
### Bot Information
- `get_me` - Get bot information
- `get_updates` - Get bot updates
- `get_chat` - Get chat information
- `get_chat_member` - Get chat member info
- `get_chat_administrators` - Get chat administrators
### Webhook Management
- `set_webhook` - Set webhook URL
- `delete_webhook` - Delete webhook
- `get_webhook_info` - Get webhook information
### Group/Channel Management
- `kick_chat_member` - Remove members
- `unban_chat_member` - Unban members
- `restrict_chat_member` - Restrict members
- `promote_chat_member` - Promote to admin
- `set_chat_permissions` - Set permissions
- `set_chat_title` - Change chat title
- `set_chat_description` - Set description
- `leave_chat` - Leave chat
### File Operations
- `get_file` - Get file information
- `download_file` - Download files
## 🔒 Security & Best Practices
### Token Security
- **Never hardcode tokens** in your code
- **Use environment variables** for bot tokens
- **Rotate tokens regularly** for production use
### Error Handling
The tool provides comprehensive error handling:
```python
result = agent.tool.telegram(action="send_message", chat_id="invalid", text="test")
if result["status"] == "error":
print(f"Error: {result['content'][0]['text']}")
```
### Rate Limiting
- Telegram has rate limits (30 messages/second to different chats)
- The tool handles basic rate limiting
- For high-volume bots, implement additional rate limiting
## 🌟 Integration with Strands Agents
This tool is designed to work seamlessly with Strands Agents:
```python
from strands import Agent
from strands_telegram import telegram
# Agent with Telegram capabilities
agent = Agent(
system_prompt="You are a helpful Telegram bot assistant.",
tools=[telegram]
)
# Agent can now use Telegram in conversations
response = agent("Send a welcome message to the user")
```
## 📚 API Reference
### telegram(action, **kwargs)
**Parameters:**
- `action` (str): The Telegram API action to perform
- `chat_id` (str|int): Target chat ID or username
- `text` (str): Message text content
- `parse_mode` (str): Text parsing mode (HTML, Markdown, MarkdownV2)
- `file_path` (str): Local file path for uploads
- `file_url` (str): URL for remote files
- `inline_keyboard` (List[List[Dict]]): Inline keyboard markup
- Additional parameters specific to each action
**Returns:**
- `Dict` with status and response content
## 🤝 Contributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
### Development Setup
```bash
git clone https://github.com/eraykeskinmac/strands-telegram
cd strands-telegram
pip install -e ".[dev]"
```
## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
## 🔗 Links
- [Strands Agents SDK](https://github.com/strands-agents/sdk-python)
- [Telegram Bot API](https://core.telegram.org/bots/api)
- [PyPI Package](https://pypi.org/project/strands-telegram/)
- [GitHub Repository](https://github.com/eraykeskinmac/strands-telegram)
## 📞 Support
- Create an issue on GitHub for bug reports
- Join our community discussions for questions
- Check the Strands Agents SDK documentation for integration help
---
**Made with ❤️ for the Strands Agents community**
Raw data
{
"_id": null,
"home_page": null,
"name": "strands-telegram",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "strands, agents, telegram, bot, api, ai, chatbot, messaging, automation, integration",
"author": null,
"author_email": "Strands Community <community@strandsagents.com>",
"download_url": "https://files.pythonhosted.org/packages/2c/c6/ab943288a12403a1e40ab47ba3309011935e605ac5db71ddad6509c393fa/strands_telegram-1.0.2.tar.gz",
"platform": null,
"description": "# Strands Telegram\n\n[](https://pypi.org/project/strands-telegram/)\n[](https://pypi.org/project/strands-telegram/)\n[](https://opensource.org/licenses/MIT)\n\n**Comprehensive Telegram Bot API integration for Strands Agents**\n\nA complete Telegram Bot API tool that provides seamless integration with Strands Agents, supporting all major Telegram Bot API operations with full flexibility and rich features.\n\n## \ud83d\ude80 Features\n\n### \ud83d\udce8 **Message Operations**\n- **Text Messages**: Send rich text with HTML/Markdown formatting\n- **Media Support**: Photos, videos, audio, documents, voice messages\n- **Interactive Elements**: Polls, dice games, location sharing, contact cards\n- **Message Management**: Edit, delete, forward, copy, pin/unpin messages\n\n### \ud83c\udfae **Interactive Features**\n- **Inline Keyboards**: Create interactive button menus\n- **Custom Keyboards**: Reply keyboards with custom layouts\n- **Callback Queries**: Handle button press events\n- **Rich Media**: Stickers, animations, and multimedia content\n\n### \ud83d\udc65 **Group & Channel Management**\n- **User Management**: Kick, ban, unban, promote users\n- **Permissions**: Set chat permissions and restrictions\n- **Administration**: Manage chat settings, photos, descriptions\n- **Member Info**: Get chat members, administrators, and statistics\n\n### \ud83d\udd27 **Bot Management**\n- **Webhook Support**: Set up and manage webhooks\n- **Bot Information**: Get bot details and configuration\n- **Updates Handling**: Retrieve and process bot updates\n- **File Operations**: Upload, download, and manage files\n\n## \ud83d\udce6 Installation\n\n```bash\npip install strands-telegram\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 import telegram\n\n# Create agent with Telegram tool\nagent = Agent(tools=[telegram])\n\n# Send a message\nagent.tool.telegram(\n action=\"send_message\",\n chat_id=\"@username\",\n text=\"Hello from Strands! \ud83d\ude80\"\n)\n```\n\n### Environment Setup\n\n```bash\n# Set your Telegram Bot Token (get from @BotFather)\nexport TELEGRAM_BOT_TOKEN=\"your_bot_token_here\"\n```\n\n### Advanced Examples\n\n#### Interactive Keyboard\n```python\n# Send message with inline keyboard\nagent.tool.telegram(\n action=\"send_message\",\n chat_id=\"123456789\",\n text=\"Choose an option:\",\n inline_keyboard=[\n [{\"text\": \"Option 1\", \"callback_data\": \"opt1\"}],\n [{\"text\": \"Option 2\", \"callback_data\": \"opt2\"}]\n ]\n)\n```\n\n#### Send Photo with Caption\n```python\n# Send photo from local file\nagent.tool.telegram(\n action=\"send_photo\",\n chat_id=\"123456789\",\n file_path=\"/path/to/photo.jpg\",\n text=\"Check out this amazing photo! \ud83d\udcf8\"\n)\n\n# Send photo from URL\nagent.tool.telegram(\n action=\"send_photo\",\n chat_id=\"123456789\",\n file_url=\"https://example.com/photo.jpg\",\n text=\"Photo from the web \ud83c\udf10\"\n)\n```\n\n#### Create Poll\n```python\n# Create a poll\nagent.tool.telegram(\n action=\"send_poll\",\n chat_id=\"123456789\",\n question=\"What's your favorite Strands feature?\",\n options=[\"AI Tools\", \"Multi-agent\", \"Workflows\", \"All of them!\"]\n)\n```\n\n#### Group Management\n```python\n# Promote user to admin\nagent.tool.telegram(\n action=\"promote_chat_member\",\n chat_id=\"-100123456789\",\n user_id=987654321\n)\n\n# Set chat permissions\nagent.tool.telegram(\n action=\"set_chat_permissions\",\n chat_id=\"-100123456789\",\n permissions={\n \"can_send_messages\": True,\n \"can_send_media_messages\": False\n }\n)\n```\n\n## \ud83d\udccb Supported Actions\n\n### Message Operations\n- `send_message` - Send text messages\n- `send_photo` - Send photos\n- `send_video` - Send videos \n- `send_audio` - Send audio files\n- `send_document` - Send documents\n- `send_voice` - Send voice messages\n- `send_sticker` - Send stickers\n- `send_location` - Send location coordinates\n- `send_contact` - Send contact information\n- `send_poll` - Create polls\n- `send_dice` - Send dice animations\n\n### Message Management\n- `edit_message` - Edit message text\n- `delete_message` - Delete messages\n- `forward_message` - Forward messages\n- `copy_message` - Copy messages\n- `pin_message` - Pin messages\n- `unpin_message` - Unpin messages\n\n### Bot Information\n- `get_me` - Get bot information\n- `get_updates` - Get bot updates\n- `get_chat` - Get chat information\n- `get_chat_member` - Get chat member info\n- `get_chat_administrators` - Get chat administrators\n\n### Webhook Management\n- `set_webhook` - Set webhook URL\n- `delete_webhook` - Delete webhook\n- `get_webhook_info` - Get webhook information\n\n### Group/Channel Management\n- `kick_chat_member` - Remove members\n- `unban_chat_member` - Unban members\n- `restrict_chat_member` - Restrict members\n- `promote_chat_member` - Promote to admin\n- `set_chat_permissions` - Set permissions\n- `set_chat_title` - Change chat title\n- `set_chat_description` - Set description\n- `leave_chat` - Leave chat\n\n### File Operations\n- `get_file` - Get file information\n- `download_file` - Download files\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\n### Error Handling\nThe tool provides comprehensive error handling:\n```python\nresult = agent.tool.telegram(action=\"send_message\", chat_id=\"invalid\", text=\"test\")\nif result[\"status\"] == \"error\":\n print(f\"Error: {result['content'][0]['text']}\")\n```\n\n### Rate Limiting\n- Telegram has rate limits (30 messages/second to different chats)\n- The tool handles basic rate limiting\n- For high-volume bots, implement additional rate limiting\n\n## \ud83c\udf1f Integration with Strands Agents\n\nThis tool is designed to work seamlessly with Strands Agents:\n\n```python\nfrom strands import Agent\nfrom strands_telegram import telegram\n\n# Agent with Telegram capabilities\nagent = Agent(\n system_prompt=\"You are a helpful Telegram bot assistant.\",\n tools=[telegram]\n)\n\n# Agent can now use Telegram in conversations\nresponse = agent(\"Send a welcome message to the user\")\n```\n\n## \ud83d\udcda API Reference\n\n### telegram(action, **kwargs)\n\n**Parameters:**\n- `action` (str): The Telegram API action to perform\n- `chat_id` (str|int): Target chat ID or username\n- `text` (str): Message text content \n- `parse_mode` (str): Text parsing mode (HTML, Markdown, MarkdownV2)\n- `file_path` (str): Local file path for uploads\n- `file_url` (str): URL for remote files\n- `inline_keyboard` (List[List[Dict]]): Inline keyboard markup\n- Additional parameters specific to each action\n\n**Returns:**\n- `Dict` with status and response content\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/eraykeskinmac/strands-telegram\ncd strands-telegram\npip install -e \".[dev]\"\n```\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 SDK](https://github.com/strands-agents/sdk-python)\n- [Telegram Bot API](https://core.telegram.org/bots/api)\n- [PyPI Package](https://pypi.org/project/strands-telegram/)\n- [GitHub Repository](https://github.com/eraykeskinmac/strands-telegram)\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 SDK documentation for integration help\n\n---\n\n**Made with \u2764\ufe0f for the Strands Agents community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Comprehensive Telegram Bot API integration for Strands Agents",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/eraykeskinmac/strands-telegram/issues",
"Changelog": "https://github.com/eraykeskinmac/strands-telegram/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/eraykeskinmac/strands-telegram#readme",
"Homepage": "https://github.com/eraykeskinmac/strands-telegram",
"Repository": "https://github.com/eraykeskinmac/strands-telegram.git"
},
"split_keywords": [
"strands",
" agents",
" telegram",
" bot",
" api",
" ai",
" chatbot",
" messaging",
" automation",
" integration"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "53b825c4ba4103db0a55a4f2f22f7dd1105034100b762f3c2f4e0dbb2138fade",
"md5": "f70e51086b92876347ba7a9e1008a712",
"sha256": "dc507abb43dec4f7dc6cf3ab591323c5f5869b94ca0a23b595c717b23e1bcc14"
},
"downloads": -1,
"filename": "strands_telegram-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f70e51086b92876347ba7a9e1008a712",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12038,
"upload_time": "2025-10-21T01:23:41",
"upload_time_iso_8601": "2025-10-21T01:23:41.238690Z",
"url": "https://files.pythonhosted.org/packages/53/b8/25c4ba4103db0a55a4f2f22f7dd1105034100b762f3c2f4e0dbb2138fade/strands_telegram-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cc6ab943288a12403a1e40ab47ba3309011935e605ac5db71ddad6509c393fa",
"md5": "cc686dbfff26c913d6feefee5694051f",
"sha256": "02bce7446daed39520bc847d2e31ba8ce795ab4ad170f72192744fa4dff10392"
},
"downloads": -1,
"filename": "strands_telegram-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "cc686dbfff26c913d6feefee5694051f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16876,
"upload_time": "2025-10-21T01:23:42",
"upload_time_iso_8601": "2025-10-21T01:23:42.667730Z",
"url": "https://files.pythonhosted.org/packages/2c/c6/ab943288a12403a1e40ab47ba3309011935e605ac5db71ddad6509c393fa/strands_telegram-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 01:23:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eraykeskinmac",
"github_project": "strands-telegram",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "strands-telegram"
}
JSON
