Telegram Piece for ActivePieces

Generic Telegram Bot integration for ActivePieces. This piece provides building blocks for receiving and sending messages through Telegram Bot API, designed to be reusable for any use case (not just SKAI Agents).

Features

• Webhook-based message reception - Automatic webhook management
• Secure signature verification - Optional secret token validation
• All message types supported - Text, photos, videos, audio, documents, voice messages
• Rich message sending - Support for text formatting (Markdown, HTML), replies
• Clean API - Simple trigger and action for common use cases

Setup

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the instructions:
   • Choose a name for your bot (e.g., "My Awesome Bot")
   • Choose a username (must end with 'bot', e.g., "my_awesome_bot")
4. BotFather will send you a Bot Token
5. Copy the token (format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Security Note:

• Keep your bot token secure
• Anyone with the token can control your bot
• You can revoke and regenerate tokens via @BotFather using /token

2. Optional: Configure Bot Commands

1. Send /setcommands to @BotFather
2. Select your bot
3. Define commands users can use (e.g., /start, /help)

3. Add Bot to ActivePieces

1. Create a new flow in ActivePieces
2. Add the "Telegram - New Message" trigger
3. Paste your Bot Token
4. The webhook will be registered automatically when you enable the flow

Components

Trigger: New Telegram Message

Purpose: Receives messages sent to your Telegram bot in real-time

Configuration:

• Bot Token (required): Your Telegram bot token from @BotFather
• Verify Webhook Signature (optional): Enable to verify webhook authenticity (recommended for production)

Automatic Webhook Management:

• Webhook is registered with Telegram when you enable the flow
• Webhook is deleted when you disable the flow
• Secret token is generated and stored automatically for signature verification

Output Format:

{
  "chatId": 123456789,
  "messageId": 1234,
  "text": "Hello! How can you help me?",
  "type": "text",
  "from": {
    "id": 123456789,
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "language_code": "en"
  },
  "chat": {
    "id": 123456789,
    "type": "private",
    "username": "johndoe"
  },
  "date": 1642511234,
  "rawPayload": { /* Full Telegram update object */ }
}

Message Types Supported:

• text: Plain text messages
• photo: Images (with optional captions)
• video: Videos (with optional captions)
• audio: Audio files
• document: Files/documents (with optional captions)
• voice: Voice messages

For media messages, additional fields are included:

{
  "type": "photo",
  "text": "Photo caption or [Photo]",
  "photo": [
    {
      "fileId": "AgACAgIAAxkBAAI...",
      "fileUniqueId": "AQADQ4cxGzM...",
      "width": 1280,
      "height": 720,
      "fileSize": 123456
    }
  ],
  "caption": "Photo caption"
}

Action: Send Message

Purpose: Send a text message through your Telegram bot

Configuration:

• Bot Token (required): Your Telegram bot token
• Chat ID (required): The chat ID to send the message to (typically from trigger output)
• Message (required): The message text to send
• Parse Mode (optional): Text formatting
  • Plain Text (default)
  • Markdown
  • MarkdownV2
  • HTML
• Reply to Message ID (optional): Make the message a reply to a specific message

Output:

{
  "success": true,
  "messageId": 5678,
  "chatId": 123456789,
  "timestamp": 1642511234,
  "sentText": "Your message text"
}

Examples:

Basic Text Message:

{
  chatId: {{trigger.chatId}},
  text: "Hello! Thanks for your message."
}

Reply to Original Message:

{
  chatId: {{trigger.chatId}},
  text: "I received your message!",
  replyToMessageId: {{trigger.messageId}}
}

Markdown Formatting:

{
  chatId: {{trigger.chatId}},
  text: "*Bold text* _italic text_ [link](https://example.com)",
  parseMode: "Markdown"
}

HTML Formatting:

{
  chatId: {{trigger.chatId}},
  text: "<b>Bold</b> <i>italic</i> <a href='https://example.com'>link</a>",
  parseMode: "HTML"
}

Usage Examples

Simple Echo Bot

Flow:

1. Trigger: Telegram - New Message
2. Action: Telegram - Send Message
   • Chat ID: {{trigger.chatId}}
   • Message: You said: {{trigger.text}}

Bot with Reply

Flow:

1. Trigger: Telegram - New Message
2. Action: Telegram - Send Message
   • Chat ID: {{trigger.chatId}}
   • Message: Received your message!
   • Reply to Message ID: {{trigger.messageId}}

Integration with SKAI Agents

For AI-powered responses using SKAI Agents, combine this piece with the SKAI Adapters piece:

Flow:

1. Trigger: Telegram - New Message
2. Action: SKAI Adapters - Telegram → SKAI Agent
   • Telegram Message: {{trigger}}
   • Agent: [Select your SKAI agent]
   • Environment: Production/Development
3. Action: SKAI Adapters - SKAI → Telegram
   • SKAI Response: {{step2}}
   • Reply to Original: true
4. Action: Telegram - Send Message
   • Chat ID: {{step3.chatId}}
   • Message: {{step3.text}}
   • Reply to Message ID: {{step3.replyToMessageId}}

This setup transforms Telegram messages to a generic format, processes them with SKAI Agents, and sends AI-generated responses back.

Working with Media Messages

When users send media (photos, videos, documents), the trigger output includes file information:

// Check message type
if (trigger.type === "photo") {
  // Access photo information
  const largestPhoto = trigger.photo[trigger.photo.length - 1];
  const fileId = largestPhoto.fileId;
  const caption = trigger.caption || "[No caption]";

  // To download the file, you would need to:
  // 1. Call Telegram's getFile API with the fileId
  // 2. Download from https://api.telegram.org/file/bot<TOKEN>/<file_path>
}

Note: This piece provides the fileId which can be used to download files via Telegram Bot API. File downloading is not built into the basic send/receive actions to keep them simple and reusable.

Troubleshooting

Webhook not receiving messages

1. Check bot token: Make sure the token is correct and the bot exists
2. Test the bot: Send a message to your bot on Telegram
3. Check flow status: Ensure the flow is enabled in ActivePieces
4. Verify webhook: The webhook is registered when you enable the flow
5. Check logs: Look for webhook registration confirmation in the flow logs

Signature verification failing

1. Disable verification temporarily: Uncheck "Verify Webhook Signature" to test
2. Regenerate webhook: Disable and re-enable the flow to generate a new secret token
3. Check for proxies: Some proxies might modify headers

Message not sending

1. Check chatId: Make sure you're using the correct chat ID from the trigger
2. Verify bot permissions: Ensure the bot hasn't been blocked by the user
3. Check parse mode: If using Markdown/HTML, ensure formatting is valid
4. Review error logs: Look at the action output for specific error messages

Bot not responding in groups

1. Privacy mode: By default, bots in groups only see messages that:
   • Start with / (commands)
   • Are replies to the bot's messages
   • Mention the bot (@botusername)
2. Disable privacy mode:
   • Send /setprivacy to @BotFather
   • Select your bot
   • Choose "Disable"
   • Add the bot to the group again

Telegram Bot API Reference

For advanced features not covered by this piece, refer to:

• Telegram Bot API Documentation
• Formatting Options
• Available Update Types

Architecture

This piece follows a modular design:

• Generic piece (skai-telegram): Handles Telegram Bot API communication

  • Can be used for any Telegram bot use case
  • Simple trigger/action for receiving and sending messages

• SKAI adapter (skai-adapters): Transforms between Telegram and SKAI format

  • Platform-agnostic message transformation
  • Integration with SKAI Agents API
  • Can be extended to support more platforms

This separation allows the Telegram piece to be reused in non-SKAI contexts (CRM integrations, notifications, custom workflows, etc.)

Development

Building the Piece

npx nx build pieces-skai-telegram

Project Structure

packages/pieces/custom/skai-telegram/
├── src/
│   ├── index.ts                          # Piece definition
│   ├── lib/
│   │   ├── auth/
│   │   │   └── telegram.auth.ts          # Bot token authentication
│   │   ├── common/
│   │   │   ├── webhook-manager.ts        # Webhook registration/cleanup
│   │   │   ├── signature-verifier.ts     # Secret token verification
│   │   │   └── types.ts                  # TypeScript interfaces
│   │   ├── triggers/
│   │   │   └── new-message.ts            # New message webhook trigger
│   │   └── actions/
│   │       └── send-message.ts           # Send message action
│   └── package.json
└── README.md

Security Considerations

1. Keep bot token secure - Never commit tokens to version control
2. Enable signature verification - Recommended for production deployments
3. Validate chat IDs - Ensure you're only responding to authorized chats
4. Rate limiting - Telegram has rate limits; implement queuing for high-volume bots
5. User privacy - Don't log sensitive user information

License

This piece is part of the ActivePieces ecosystem. See the main repository for license information.

Support

For issues and questions:

• Check the TESTING_GUIDE.md for testing instructions
• Review the MULTI_PLATFORM_MESSAGING_ARCHITECTURE.md for architecture details
• File issues in the ActivePieces repository