Telegram Sink

The Telegram sink allows your workflows to be triggered by messages sent to a Telegram bot. It supports both long polling (local) and webhook (remote) modes.

How It Works

Local Mode (Long Polling)

When running the desktop app, Flow-Like uses Telegram’s getUpdates API to poll for new messages:

┌──────────────┐     getUpdates      ┌──────────────┐
│   Flow-Like  │◄───────────────────►│   Telegram   │
│   Desktop    │     (polling)       │    Servers   │
└──────────────┘                     └──────────────┘

Advantages:

• Works behind firewalls/NAT
• No public URL required
• Simple setup

Limitations:

• Slight delay due to polling interval
• Must keep the app running

Remote Mode (Webhook)

When deployed to a server, Telegram sends updates directly via webhook:

┌──────────────┐                     ┌──────────────┐
│   Flow-Like  │◄────────────────────│   Telegram   │
│    Server    │     (webhook)       │    Servers   │
└──────────────┘                     └──────────────┘

Advantages:

• Instant message delivery
• More efficient (no polling)
• Works 24/7

Endpoint Format (Remote)

POST /sink/trigger/telegram/{event_id}

Configuration Options

Field	Type	Description	Required
token	string	Bot token from @BotFather	Yes
webhook_secret	string	Secret token for webhook verification	Recommended
bot_name	string	Display name for the bot	No
respond_to_mentions	boolean	Respond to @mentions in groups	No
respond_to_private	boolean	Respond to private messages	No
command_prefix	string	Command prefix (default: /)	No
chat_whitelist	string[]	Only accept from these chat IDs	No
chat_blacklist	string[]	Ignore these chat IDs	No

Setting Up a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
4. Paste the token in the Flow-Like configuration

Webhook Setup (Remote Mode)

1. Configure the Webhook Secret

Generate a secret token (64 hex characters recommended):

openssl rand -hex 32

Save this in the webhook_secret field of your event configuration.

2. Get Your Webhook URL

The URL format is:

https://your-domain.com/sink/trigger/telegram/{event_id}

3. Register the Webhook with Telegram

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/sink/trigger/telegram/evt_abc123",
    "secret_token": "your-webhook-secret"
  }'

4. Verify the Webhook

Check that it’s registered:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"

Switching Between Modes

To Switch to Local Mode

If you previously set a webhook and want to use local polling:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook"

To Switch to Remote Mode

Set the webhook as described above.

Security

Webhook Secret Token

Telegram sends the secret token in the X-Telegram-Bot-Api-Secret-Token header. Flow-Like verifies this header matches your configured secret.

IP Verification

In production, Flow-Like verifies that webhook requests come from Telegram’s IP ranges:

• 149.154.160.0/20
• 91.108.4.0/22

This verification is disabled in development mode (when API_BASE_URL contains localhost).

Payload Format

Telegram sends updates in this format:

{
  "update_id": 123456789,
  "message": {
    "message_id": 1,
    "from": {
      "id": 123456,
      "first_name": "John",
      "username": "johndoe"
    },
    "chat": {
      "id": 123456,
      "type": "private"
    },
    "date": 1234567890,
    "text": "/start hello"
  }
}

Chat Filtering

Whitelist Mode

Only process messages from specific chats:

{
  "chat_whitelist": ["123456789", "-100987654321"]
}

Blacklist Mode

Ignore messages from specific chats:

{
  "chat_blacklist": ["-100spam_group"]
}

Response Format

The sink returns a response immediately to acknowledge receipt:

{
  "triggered": true,
  "run_id": "run_xyz123",
  "message": "Webhook received and processing"
}

The actual workflow execution happens asynchronously.

Error Handling

Status Code	Description
200 OK	Webhook received, execution dispatched
401 Unauthorized	Invalid or missing secret token
403 Forbidden	Request from non-Telegram IP
404 Not Found	No matching sink found

Best Practices

1. Always use a webhook secret in production
2. Set up chat filtering to prevent abuse
3. Use private groups for sensitive workflows
4. Monitor bot usage through Telegram’s BotFather stats
5. Keep the bot token secure - never commit it to version control