Add Telegram icon

autogpt_platform/backend/backend/blocks/telegram/__init__.py

@@ -0,0 +1 @@
+# Telegram Bot blocks for AutoGPT Platform

autogpt_platform/backend/backend/blocks/telegram/_api.py

@@ -0,0 +1,159 @@
+"""
+Telegram Bot API helper functions.
+
+Provides utilities for making authenticated requests to the Telegram Bot API.
+"""
+
+import logging
+from io import BytesIO
+from typing import Any, Optional
+
+from backend.data.model import APIKeyCredentials
+from backend.util.request import Requests
+
+logger = logging.getLogger(__name__)
+
+TELEGRAM_API_BASE = "https://api.telegram.org"
+
+
+class TelegramAPIException(Exception):
+    """Exception raised for Telegram API errors."""
+
+    def __init__(self, message: str, error_code: int = 0):
+        super().__init__(message)
+        self.error_code = error_code
+
+
+def get_bot_api_url(bot_token: str, method: str) -> str:
+    """Construct Telegram Bot API URL for a method."""
+    return f"{TELEGRAM_API_BASE}/bot{bot_token}/{method}"
+
+
+def get_file_url(bot_token: str, file_path: str) -> str:
+    """Construct Telegram file download URL."""
+    return f"{TELEGRAM_API_BASE}/file/bot{bot_token}/{file_path}"
+
+
+async def call_telegram_api(
+    credentials: APIKeyCredentials,
+    method: str,
+    data: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    """
+    Make a request to the Telegram Bot API.
+
+    Args:
+        credentials: Bot token credentials
+        method: API method name (e.g., "sendMessage", "getFile")
+        data: Request parameters
+
+    Returns:
+        API response result
+
+    Raises:
+        TelegramAPIException: If the API returns an error
+    """
+    token = credentials.api_key.get_secret_value()
+    url = get_bot_api_url(token, method)
+
+    response = await Requests().post(url, json=data or {})
+    result = response.json()
+
+    if not result.get("ok"):
+        error_code = result.get("error_code", 0)
+        description = result.get("description", "Unknown error")
+        raise TelegramAPIException(description, error_code)
+
+    return result.get("result", {})
+
+
+async def call_telegram_api_with_file(
+    credentials: APIKeyCredentials,
+    method: str,
+    file_field: str,
+    file_data: bytes,
+    filename: str,
+    content_type: str,
+    data: Optional[dict[str, Any]] = None,
+) -> dict[str, Any]:
+    """
+    Make a multipart/form-data request to the Telegram Bot API with a file upload.
+
+    Args:
+        credentials: Bot token credentials
+        method: API method name (e.g., "sendPhoto", "sendVoice")
+        file_field: Form field name for the file (e.g., "photo", "voice")
+        file_data: Raw file bytes
+        filename: Filename for the upload
+        content_type: MIME type of the file
+        data: Additional form parameters
+
+    Returns:
+        API response result
+
+    Raises:
+        TelegramAPIException: If the API returns an error
+    """
+    token = credentials.api_key.get_secret_value()
+    url = get_bot_api_url(token, method)
+
+    files = [(file_field, (filename, BytesIO(file_data), content_type))]
+
+    response = await Requests().post(url, files=files, data=data or {})
+    result = response.json()
+
+    if not result.get("ok"):
+        error_code = result.get("error_code", 0)
+        description = result.get("description", "Unknown error")
+        raise TelegramAPIException(description, error_code)
+
+    return result.get("result", {})
+
+
+async def get_file_info(credentials: APIKeyCredentials, file_id: str) -> dict[str, Any]:
+    """
+    Get file information from Telegram.
+
+    Args:
+        credentials: Bot token credentials
+        file_id: Telegram file_id from message
+
+    Returns:
+        File info dict containing file_id, file_unique_id, file_size, file_path
+    """
+    return await call_telegram_api(credentials, "getFile", {"file_id": file_id})
+
+
+async def get_file_download_url(credentials: APIKeyCredentials, file_id: str) -> str:
+    """
+    Get the download URL for a Telegram file.
+
+    Args:
+        credentials: Bot token credentials
+        file_id: Telegram file_id from message
+
+    Returns:
+        Full download URL
+    """
+    token = credentials.api_key.get_secret_value()
+    result = await get_file_info(credentials, file_id)
+    file_path = result.get("file_path")
+    if not file_path:
+        raise TelegramAPIException("No file_path returned from getFile")
+    return get_file_url(token, file_path)
+
+
+async def download_telegram_file(credentials: APIKeyCredentials, file_id: str) -> bytes:
+    """
+    Download a file from Telegram servers.
+
+    Args:
+        credentials: Bot token credentials
+        file_id: Telegram file_id
+
+    Returns:
+        File content as bytes
+    """
+    url = await get_file_download_url(credentials, file_id)
+    response = await Requests().get(url)
+    return response.content

autogpt_platform/backend/backend/blocks/telegram/_auth.py

@@ -0,0 +1,43 @@
+"""
+Telegram Bot credentials handling.
+
+Telegram bots use an API key (bot token) obtained from @BotFather.
+"""
+
+from typing import Literal
+
+from pydantic import SecretStr
+
+from backend.data.model import APIKeyCredentials, CredentialsField, CredentialsMetaInput
+from backend.integrations.providers import ProviderName
+
+# Bot token credentials (API key style)
+TelegramCredentials = APIKeyCredentials
+TelegramCredentialsInput = CredentialsMetaInput[
+    Literal[ProviderName.TELEGRAM], Literal["api_key"]
+]
+
+
+def TelegramCredentialsField() -> TelegramCredentialsInput:
+    """Creates a Telegram bot token credentials field."""
+    return CredentialsField(
+        description="Telegram Bot API token from @BotFather. "
+        "Create a bot at https://t.me/BotFather to get your token."
+    )
+
+
+# Test credentials for unit tests
+TEST_CREDENTIALS = APIKeyCredentials(
+    id="01234567-89ab-cdef-0123-456789abcdef",
+    provider="telegram",
+    api_key=SecretStr("test_telegram_bot_token"),
+    title="Mock Telegram Bot Token",
+    expires_at=None,
+)
+
+TEST_CREDENTIALS_INPUT = {
+    "provider": TEST_CREDENTIALS.provider,
+    "id": TEST_CREDENTIALS.id,
+    "type": TEST_CREDENTIALS.type,
+    "title": TEST_CREDENTIALS.title,
+}

autogpt_platform/backend/backend/blocks/telegram/triggers.py

@@ -0,0 +1,352 @@
+"""
+Telegram trigger blocks for receiving messages via webhooks.
+"""
+
+import logging
+
+from pydantic import BaseModel
+
+from backend.data.block import (
+    Block,
+    BlockCategory,
+    BlockOutput,
+    BlockSchemaInput,
+    BlockSchemaOutput,
+    BlockWebhookConfig,
+)
+from backend.data.model import SchemaField
+from backend.integrations.providers import ProviderName
+from backend.integrations.webhooks.telegram import TelegramWebhookType
+
+from ._auth import (
+    TEST_CREDENTIALS,
+    TEST_CREDENTIALS_INPUT,
+    TelegramCredentialsField,
+    TelegramCredentialsInput,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# Example payload for testing
+EXAMPLE_MESSAGE_PAYLOAD = {
+    "update_id": 123456789,
+    "message": {
+        "message_id": 1,
+        "from": {
+            "id": 12345678,
+            "is_bot": False,
+            "first_name": "John",
+            "last_name": "Doe",
+            "username": "johndoe",
+            "language_code": "en",
+        },
+        "chat": {
+            "id": 12345678,
+            "first_name": "John",
+            "last_name": "Doe",
+            "username": "johndoe",
+            "type": "private",
+        },
+        "date": 1234567890,
+        "text": "Hello, bot!",
+    },
+}
+
+
+class TelegramTriggerBase:
+    """Base class for Telegram trigger blocks."""
+
+    class Input(BlockSchemaInput):
+        credentials: TelegramCredentialsInput = TelegramCredentialsField()
+        payload: dict = SchemaField(hidden=True, default_factory=dict)
+
+
+class TelegramMessageTriggerBlock(TelegramTriggerBase, Block):
+    """
+    Triggers when a message is received by your Telegram bot.
+
+    Supports text, photos, voice messages, and audio files.
+    Connect the outputs to other blocks to process messages and send responses.
+    """
+
+    class Input(TelegramTriggerBase.Input):
+        class EventsFilter(BaseModel):
+            """Filter for message types to receive."""
+
+            text: bool = True
+            photo: bool = False
+            voice: bool = False
+            audio: bool = False
+            document: bool = False
+            video: bool = False
+
+        events: EventsFilter = SchemaField(
+            title="Message Types", description="Types of messages to receive"
+        )
+
+    class Output(BlockSchemaOutput):
+        payload: dict = SchemaField(
+            description="The complete webhook payload from Telegram"
+        )
+        chat_id: int = SchemaField(
+            description="The chat ID where the message was received. "
+            "Use this to send replies."
+        )
+        message_id: int = SchemaField(description="The unique message ID")
+        user_id: int = SchemaField(description="The user ID who sent the message")
+        username: str = SchemaField(description="Username of the sender (may be empty)")
+        first_name: str = SchemaField(description="First name of the sender")
+        event: str = SchemaField(
+            description="The message type (text, photo, voice, audio, etc.)"
+        )
+        text: str = SchemaField(
+            description="Text content of the message (for text messages)"
+        )
+        photo_file_id: str = SchemaField(
+            description="File ID of the photo (for photo messages). "
+            "Use GetTelegramFileBlock to download."
+        )
+        voice_file_id: str = SchemaField(
+            description="File ID of the voice message (for voice messages). "
+            "Use GetTelegramFileBlock to download."
+        )
+        audio_file_id: str = SchemaField(
+            description="File ID of the audio file (for audio messages). "
+            "Use GetTelegramFileBlock to download."
+        )
+        file_id: str = SchemaField(
+            description="File ID for document/video messages. "
+            "Use GetTelegramFileBlock to download."
+        )
+        file_name: str = SchemaField(
+            description="Original filename (for document/audio messages)"
+        )
+        caption: str = SchemaField(description="Caption for media messages")
+
+    def __init__(self):
+        super().__init__(
+            id="4435e4e0-df6e-4301-8f35-ad70b12fc9ec",
+            description="Triggers when a message is received by your Telegram bot. "
+            "Supports text, photos, voice messages, and audio files.",
+            categories={BlockCategory.SOCIAL},
+            input_schema=TelegramMessageTriggerBlock.Input,
+            output_schema=TelegramMessageTriggerBlock.Output,
+            webhook_config=BlockWebhookConfig(
+                provider=ProviderName.TELEGRAM,
+                webhook_type=TelegramWebhookType.BOT,
+                resource_format="bot",
+                event_filter_input="events",
+                event_format="message.{event}",
+            ),
+            test_input={
+                "events": {"text": True, "photo": True},
+                "credentials": TEST_CREDENTIALS_INPUT,
+                "payload": EXAMPLE_MESSAGE_PAYLOAD,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("payload", EXAMPLE_MESSAGE_PAYLOAD),
+                ("chat_id", 12345678),
+                ("message_id", 1),
+                ("user_id", 12345678),
+                ("username", "johndoe"),
+                ("first_name", "John"),
+                ("event", "text"),
+                ("text", "Hello, bot!"),
+                ("photo_file_id", ""),
+                ("voice_file_id", ""),
+                ("audio_file_id", ""),
+                ("file_id", ""),
+                ("file_name", ""),
+                ("caption", ""),
+            ],
+        )
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        payload = input_data.payload
+        message = payload.get("message", {})
+
+        # Extract common fields
+        chat = message.get("chat", {})
+        sender = message.get("from", {})
+
+        yield "payload", payload
+        yield "chat_id", chat.get("id", 0)
+        yield "message_id", message.get("message_id", 0)
+        yield "user_id", sender.get("id", 0)
+        yield "username", sender.get("username", "")
+        yield "first_name", sender.get("first_name", "")
+
+        # Determine message type and extract content
+        if "text" in message:
+            yield "event", "text"
+            yield "text", message.get("text", "")
+            yield "photo_file_id", ""
+            yield "voice_file_id", ""
+            yield "audio_file_id", ""
+            yield "file_id", ""
+            yield "file_name", ""
+            yield "caption", ""
+        elif "photo" in message:
+            # Get the largest photo (last in array)
+            photos = message.get("photo", [])
+            photo_fid = photos[-1]["file_id"] if photos else ""
+            yield "event", "photo"
+            yield "text", ""
+            yield "photo_file_id", photo_fid
+            yield "voice_file_id", ""
+            yield "audio_file_id", ""
+            yield "file_id", ""
+            yield "file_name", ""
+            yield "caption", message.get("caption", "")
+        elif "voice" in message:
+            voice = message.get("voice", {})
+            yield "event", "voice"
+            yield "text", ""
+            yield "photo_file_id", ""
+            yield "voice_file_id", voice.get("file_id", "")
+            yield "audio_file_id", ""
+            yield "file_id", ""
+            yield "file_name", ""
+            yield "caption", message.get("caption", "")
+        elif "audio" in message:
+            audio = message.get("audio", {})
+            yield "event", "audio"
+            yield "text", ""
+            yield "photo_file_id", ""
+            yield "voice_file_id", ""
+            yield "audio_file_id", audio.get("file_id", "")
+            yield "file_id", ""
+            yield "file_name", audio.get("file_name", "")
+            yield "caption", message.get("caption", "")
+        elif "document" in message:
+            document = message.get("document", {})
+            yield "event", "document"
+            yield "text", ""
+            yield "photo_file_id", ""
+            yield "voice_file_id", ""
+            yield "audio_file_id", ""
+            yield "file_id", document.get("file_id", "")
+            yield "file_name", document.get("file_name", "")
+            yield "caption", message.get("caption", "")
+        elif "video" in message:
+            video = message.get("video", {})
+            yield "event", "video"
+            yield "text", ""
+            yield "photo_file_id", ""
+            yield "voice_file_id", ""
+            yield "audio_file_id", ""
+            yield "file_id", video.get("file_id", "")
+            yield "file_name", video.get("file_name", "")
+            yield "caption", message.get("caption", "")
+        else:
+            yield "event", "other"
+            yield "text", ""
+            yield "photo_file_id", ""
+            yield "voice_file_id", ""
+            yield "audio_file_id", ""
+            yield "file_id", ""
+            yield "file_name", ""
+            yield "caption", ""
+
+
+# Example payload for reaction trigger testing
+EXAMPLE_REACTION_PAYLOAD = {
+    "update_id": 123456790,
+    "message_reaction": {
+        "chat": {
+            "id": 12345678,
+            "first_name": "John",
+            "last_name": "Doe",
+            "username": "johndoe",
+            "type": "private",
+        },
+        "message_id": 42,
+        "user": {
+            "id": 12345678,
+            "is_bot": False,
+            "first_name": "John",
+            "username": "johndoe",
+        },
+        "date": 1234567890,
+        "new_reaction": [{"type": "emoji", "emoji": "👍"}],
+        "old_reaction": [],
+    },
+}
+
+
+class TelegramMessageReactionTriggerBlock(TelegramTriggerBase, Block):
+    """
+    Triggers when a reaction to a message is changed.
+
+    Works automatically in private chats. In group chats, the bot must be
+    an administrator to receive reaction updates.
+    """
+
+    class Input(TelegramTriggerBase.Input):
+        pass
+
+    class Output(BlockSchemaOutput):
+        payload: dict = SchemaField(
+            description="The complete webhook payload from Telegram"
+        )
+        chat_id: int = SchemaField(
+            description="The chat ID where the reaction occurred"
+        )
+        message_id: int = SchemaField(description="The message ID that was reacted to")
+        user_id: int = SchemaField(description="The user ID who changed the reaction")
+        username: str = SchemaField(description="Username of the user (may be empty)")
+        new_reactions: list = SchemaField(
+            description="List of new reactions on the message"
+        )
+        old_reactions: list = SchemaField(
+            description="List of previous reactions on the message"
+        )
+
+    def __init__(self):
+        super().__init__(
+            id="82525328-9368-4966-8f0c-cd78e80181fd",
+            description="Triggers when a reaction to a message is changed. "
+            "Works in private chats automatically. "
+            "In groups, the bot must be an administrator.",
+            categories={BlockCategory.SOCIAL},
+            input_schema=TelegramMessageReactionTriggerBlock.Input,
+            output_schema=TelegramMessageReactionTriggerBlock.Output,
+            webhook_config=BlockWebhookConfig(
+                provider=ProviderName.TELEGRAM,
+                webhook_type=TelegramWebhookType.BOT,
+                resource_format="bot",
+                event_filter_input="",
+                event_format="message_reaction",
+            ),
+            test_input={
+                "credentials": TEST_CREDENTIALS_INPUT,
+                "payload": EXAMPLE_REACTION_PAYLOAD,
+            },
+            test_credentials=TEST_CREDENTIALS,
+            test_output=[
+                ("payload", EXAMPLE_REACTION_PAYLOAD),
+                ("chat_id", 12345678),
+                ("message_id", 42),
+                ("user_id", 12345678),
+                ("username", "johndoe"),
+                ("new_reactions", [{"type": "emoji", "emoji": "👍"}]),
+                ("old_reactions", []),
+            ],
+        )
+
+    async def run(self, input_data: Input, **kwargs) -> BlockOutput:
+        payload = input_data.payload
+        reaction = payload.get("message_reaction", {})
+
+        chat = reaction.get("chat", {})
+        user = reaction.get("user", {})
+
+        yield "payload", payload
+        yield "chat_id", chat.get("id", 0)
+        yield "message_id", reaction.get("message_id", 0)
+        yield "user_id", user.get("id", 0)
+        yield "username", user.get("username", "")
+        yield "new_reactions", reaction.get("new_reaction", [])
+        yield "old_reactions", reaction.get("old_reaction", [])

autogpt_platform/backend/backend/integrations/providers.py

@@ -46,6 +46,7 @@ class ProviderName(str, Enum):
     SLANT3D = "slant3d"
     SMARTLEAD = "smartlead"
     SMTP = "smtp"
+    TELEGRAM = "telegram"
     TWITTER = "twitter"
     TODOIST = "todoist"
     UNREAL_SPEECH = "unreal_speech"

autogpt_platform/backend/backend/integrations/webhooks/__init__.py

@@ -15,6 +15,7 @@ def load_webhook_managers() -> dict["ProviderName", type["BaseWebhooksManager"]]
     from .compass import CompassWebhookManager
     from .github import GithubWebhooksManager
     from .slant3d import Slant3DWebhooksManager
+    from .telegram import TelegramWebhooksManager
 
     webhook_managers.update(
         {
@@ -23,6 +24,7 @@ def load_webhook_managers() -> dict["ProviderName", type["BaseWebhooksManager"]]
                 CompassWebhookManager,
                 GithubWebhooksManager,
                 Slant3DWebhooksManager,
+                TelegramWebhooksManager,
             ]
         }
     )

autogpt_platform/backend/backend/integrations/webhooks/telegram.py

@@ -0,0 +1,166 @@
+"""
+Telegram Bot API Webhooks Manager.
+
+Handles webhook registration and validation for Telegram bots.
+"""
+
+import logging
+
+from fastapi import HTTPException, Request
+from strenum import StrEnum
+
+from backend.data import integrations
+from backend.data.model import APIKeyCredentials, Credentials
+from backend.integrations.providers import ProviderName
+from backend.util.request import Requests
+
+from ._base import BaseWebhooksManager
+
+logger = logging.getLogger(__name__)
+
+
+class TelegramWebhookType(StrEnum):
+    BOT = "bot"
+
+
+class TelegramWebhooksManager(BaseWebhooksManager[TelegramWebhookType]):
+    """
+    Manages Telegram bot webhooks.
+
+    Telegram webhooks are registered via the setWebhook API method.
+    Incoming requests are validated using the secret_token header.
+    """
+
+    PROVIDER_NAME = ProviderName.TELEGRAM
+    WebhookType = TelegramWebhookType
+
+    TELEGRAM_API_BASE = "https://api.telegram.org"
+
+    @classmethod
+    async def validate_payload(
+        cls,
+        webhook: integrations.Webhook,
+        request: Request,
+        credentials: Credentials | None,
+    ) -> tuple[dict, str]:
+        """
+        Validates incoming Telegram webhook request.
+
+        Telegram sends X-Telegram-Bot-Api-Secret-Token header when secret_token
+        was set in setWebhook call.
+
+        Returns:
+            tuple: (payload dict, event_type string)
+        """
+        # Verify secret token header
+        secret_header = request.headers.get("X-Telegram-Bot-Api-Secret-Token")
+        if not secret_header or secret_header != webhook.secret:
+            raise HTTPException(
+                status_code=403,
+                detail="Invalid or missing X-Telegram-Bot-Api-Secret-Token",
+            )
+
+        payload = await request.json()
+
+        # Determine event type based on update content
+        # Telegram updates can contain: message, edited_message,
+        # channel_post, callback_query, etc.
+        if "message" in payload:
+            message = payload["message"]
+            if "text" in message:
+                event_type = "message.text"
+            elif "photo" in message:
+                event_type = "message.photo"
+            elif "voice" in message:
+                event_type = "message.voice"
+            elif "audio" in message:
+                event_type = "message.audio"
+            elif "document" in message:
+                event_type = "message.document"
+            elif "video" in message:
+                event_type = "message.video"
+            else:
+                event_type = "message.other"
+        elif "edited_message" in payload:
+            event_type = "edited_message"
+        elif "message_reaction" in payload:
+            event_type = "message_reaction"
+        elif "callback_query" in payload:
+            event_type = "callback_query"
+        else:
+            event_type = "unknown"
+
+        return payload, event_type
+
+    async def _register_webhook(
+        self,
+        credentials: Credentials,
+        webhook_type: TelegramWebhookType,
+        resource: str,
+        events: list[str],
+        ingress_url: str,
+        secret: str,
+    ) -> tuple[str, dict]:
+        """
+        Register webhook with Telegram using setWebhook API.
+
+        Args:
+            credentials: Bot token credentials
+            webhook_type: Type of webhook (always BOT for Telegram)
+            resource: Resource identifier (unused for Telegram, bots are global)
+            events: Events to subscribe to
+            ingress_url: URL to receive webhook payloads
+            secret: Secret token for request validation
+
+        Returns:
+            tuple: (provider_webhook_id, config dict)
+        """
+        if not isinstance(credentials, APIKeyCredentials):
+            raise ValueError("API key (bot token) is required for Telegram webhooks")
+
+        token = credentials.api_key.get_secret_value()
+        url = f"{self.TELEGRAM_API_BASE}/bot{token}/setWebhook"
+
+        # Telegram setWebhook parameters
+        webhook_data = {
+            "url": ingress_url,
+            "secret_token": secret,
+            "allowed_updates": ["message", "edited_message", "message_reaction"],
+        }
+
+        response = await Requests().post(url, json=webhook_data)
+        result = response.json()
+
+        if not result.get("ok"):
+            error_desc = result.get("description", "Unknown error")
+            raise ValueError(f"Failed to set Telegram webhook: {error_desc}")
+
+        # Telegram doesn't return a webhook ID, use empty string
+        config = {
+            "url": ingress_url,
+            "allowed_updates": webhook_data["allowed_updates"],
+        }
+
+        return "", config
+
+    async def _deregister_webhook(
+        self, webhook: integrations.Webhook, credentials: Credentials
+    ) -> None:
+        """
+        Deregister webhook by calling setWebhook with empty URL.
+
+        This removes the webhook from Telegram's servers.
+        """
+        if not isinstance(credentials, APIKeyCredentials):
+            raise ValueError("API key (bot token) is required for Telegram webhooks")
+
+        token = credentials.api_key.get_secret_value()
+        url = f"{self.TELEGRAM_API_BASE}/bot{token}/setWebhook"
+
+        # Setting empty URL removes the webhook
+        response = await Requests().post(url, json={"url": ""})
+        result = response.json()
+
+        if not result.get("ok"):
+            error_desc = result.get("description", "Unknown error")
+            logger.warning(f"Failed to deregister Telegram webhook: {error_desc}")