Skip to content

Telegram Flow

Telegram Flow

Seamless integration with Telegram for bot messaging, broadcasting, and interactive communication.

How to Use

Input Requirements

To configure the Telegram bot, you need:

  • Bot Token: Get from BotFather on Telegram
  • Mode Selection: Choose Polling, Broadcast, or both
  • Chat ID: Optional specific chat/group ID
  • Message Content: Text, images, or documents to send

Configuration Modes

Polling Mode (Trigger Starting Point)

Purpose: Listen for incoming messages and act as a trigger for other flows

Configuration:

  • ✅ Polling: Enabled
  • ❌ Broadcast: Disabled

Behavior:

  • Acts as trigger starting point for workflows
  • Listens for user messages and commands
  • All trigger flows need to be subscribed to this
  • Responds to incoming messages automatically

Use When: You want the bot to respond to user messages

Broadcast Mode (Send Messages to Groups)

Purpose: Send messages to multiple users or groups

Configuration:

  • ❌ Polling: Disabled
  • ✅ Broadcast: Enabled

Behavior:

  • Sends messages to configured groups/channels
  • One-way communication (send only)
  • Good for announcements and notifications
  • Can reach multiple recipients at once

Important:

  • Chat ID and broadcast option don't work together
  • Whichever group or chat ID you want to use, they must do /start to start the bot first
  • Bot needs to be activated in each chat/group before broadcasting

Use When: You want to send alerts, news, or updates to groups

Combined Mode (Both Polling & Broadcast)

Configuration:

  • ✅ Polling: Enabled
  • ✅ Broadcast: Enabled

Behavior:

  • Can both receive and send messages
  • Full bidirectional communication
  • Responds to users AND sends broadcasts

Important: If you have multiple Telegram nodes, only ONE should have polling enabled to avoid bot conflicts

Chat ID Configuration

Default Behavior

Without specific Chat ID, the bot uses default settings

Specific Chat ID

Configuration: Set Chat ID in the options Command: /chatId telegram Purpose: Send messages to a specific chat or group

Important Limitations:

  • Chat ID and broadcast option don't work together
  • Choose either specific Chat ID OR broadcast mode, not both
  • For broadcast mode, recipients must /start the bot first

Example:

  • Chat ID: 123456789 (send to specific user)
  • Chat ID: -987654321 (send to specific group)

Setup Requirements:

  • User or group must send /start to the bot before receiving messages
  • Bot must be added to groups and activated

Configuration Examples

Customer Support Bot (Polling Mode)

Settings:

  • ✅ Polling: ON
  • ❌ Broadcast: OFF
  • Chat ID: (empty - responds to anyone)

Behavior: Responds to customer questions automatically

News Broadcaster (Broadcast Mode)

Settings:

  • ❌ Polling: OFF
  • ✅ Broadcast: ON
  • Chat ID: (empty - don't set specific Chat ID)

Behavior:

  • Sends crypto news updates to subscribed users/groups
  • Recipients must have sent /start to the bot first

Community Manager Bot (Combined Mode)

Settings:

  • ✅ Polling: ON
  • ✅ Broadcast: ON
  • Chat ID: (empty - broadcast doesn't work with specific Chat ID)

Behavior:

  • Answers questions from anyone who messages the bot
  • Sends announcements to all users who have sent /start

Private Assistant (Specific Chat ID)

Settings:

  • ✅ Polling: ON
  • ❌ Broadcast: OFF
  • Chat ID: 123456789 (your personal chat)

Behavior: Personal bot that only talks to you

Input Format

Send messages in natural language:

Example inputs:
  • "Send price alert to crypto group"
  • "Respond to user questions about DeFi"
  • "Broadcast daily market summary"
  • "Send notification to admin chat"

Output Format

Various message types supported:

  • Text Messages: Plain text responses
  • Rich Messages: Formatted text with Markdown
  • Images: Charts, graphs, screenshots
  • Documents: PDFs, reports, files
  • Buttons: Interactive keyboards and menus

Use Cases

Community Management

  • Answer member questions
  • Send announcements
  • Moderate discussions
  • Share updates

Trading Alerts

  • Price notifications
  • Market analysis
  • Trading signals
  • Portfolio updates

Customer Support

  • 24/7 automated responses
  • Help documentation
  • Issue escalation
  • User onboarding

News & Updates

  • Market news
  • Protocol updates
  • Event notifications
  • Research reports

Bot Conflict Prevention

Problem: Multiple Telegram bots with polling enabled can conflict

Solution:

  • Use only ONE Telegram node with Polling enabled
  • Other Telegram nodes should have Polling disabled
  • Each bot token should be unique

Example Setup:

  • Bot 1: Polling ON, Broadcast OFF (handles incoming messages)
  • Bot 2: Polling OFF, Broadcast ON (sends announcements)

Technical Details

Installation

npm install @skynetxbt/flow-telegram

Dependencies

  • @skynetxbt/core - Core framework functionality
  • node-telegram-bot-api - Telegram Bot API wrapper
  • axios - HTTP client for API calls

Configuration

Environment Variables

# Required
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
 
# Optional
TELEGRAM_CHAT_ID=default_chat_id
TELEGRAM_BROADCAST_ENABLED=true
TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook

Basic Setup

import { TelegramFlow } from "@skynetxbt/flow-telegram";
 
const telegramFlow = new TelegramFlow({
  telegramConfig: {
    bottoken: process.env.TELEGRAM_BOT_TOKEN!,
    isbroadcast: true,
    helpMessage: "Welcome to SkynetXBT Bot! Use /help for commands.",
    chatId: process.env.TELEGRAM_CHAT_ID
  }
});

Usage

Basic Message Sending

const result = await telegramFlow.execute({
  agentId: { generation: 0, familyCode: "bot", serialNumber: "001" },
  userPublicKey: "user123",
  message: "Hello from SkynetXBT!",
  variables: {
    chatId: "123456789",
    messageType: "text"
  }
});

Broadcast Messaging

// Send to all subscribed users
await telegramFlow.execute({
  agentId: { generation: 0, familyCode: "broadcast", serialNumber: "001" },
  userPublicKey: "admin",
  message: "🚀 New DeFi opportunity detected! Check out the latest yields.",
  variables: {
    broadcast: true,
    messageType: "announcement"
  }
});

Interactive Commands

// Handle user commands
await telegramFlow.execute({
  agentId: { generation: 0, familyCode: "command", serialNumber: "001" },
  userPublicKey: "user123",
  message: "/portfolio",
  variables: {
    chatId: "123456789",
    command: "portfolio",
    userId: "user123"
  }
});

Configuration Options

TelegramConfig Interface

interface TelegramConfig {
  bottoken: string;           // Bot token from BotFather
  isbroadcast?: boolean;      // Enable broadcast functionality
  helpMessage?: string;       // Custom help message
  chatId?: string;           // Default chat ID
  webhookUrl?: string;       // Webhook URL for updates
  allowedUsers?: string[];   // Whitelist of allowed users
  adminUsers?: string[];     // List of admin users
  rateLimitWindow?: number;  // Rate limiting window (ms)
  rateLimitMax?: number;     // Max requests per window
}

Message Types

Text Messages

await telegramFlow.execute({
  agentId: { generation: 0, familyCode: "text", serialNumber: "001" },
  userPublicKey: "user123",
  message: "Your portfolio balance is $1,234.56",
  variables: {
    chatId: "123456789",
    messageType: "text"
  }
});

Rich Messages with Formatting

await telegramFlow.execute({
  agentId: { generation: 0, familyCode: "rich", serialNumber: "001" },
  userPublicKey: "user123",
  message: `
*Portfolio Summary*
📊 Total Value: $1,234.56
📈 24h Change: +5.67%
🔥 Top Performer: ETH (+12.3%)
 
_Last updated: ${new Date().toLocaleString()}_
  `,
  variables: {
    chatId: "123456789",
    messageType: "markdown",
    parseMode: "Markdown"
  }
});
Next Steps: