Telegram Action Block

The Telegram Action Block enables seamless integration with Telegram, allowing you to send automated messages to users, groups, or channels. This block supports rich formatting, variable integration, and real-time notifications, making it ideal for alerts, updates, and customer engagement within your workflows.

Key Features

• Multi-Chat Support: Send messages to individual users, groups, or channels.
• Rich Formatting: Use Markdown or HTML for styled messages.
• Variable Integration: Incorporate workflow variables for dynamic content.
• Bot Authentication: Securely connect using Telegram bot tokens.
• Real-Time Delivery: Ensure instant message delivery.
• Flexible Chat Types: Support private chats, groups, and public/private channels.

Bot Setup

Creating a Telegram Bot

1. Contact @BotFather:

   • Open Telegram and search for @BotFather.
   • Start a conversation and send the /newbot command.

2. Configure Your Bot:

   /newbot
   Name: My Workflow Bot
   Username: @MyWorkflowBot

3. Obtain Bot Token:

   • @BotFather will provide a unique token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz).
   • Store the token securely.

4. Optional Settings:

   • Use /setprivacy to adjust privacy settings.
   • Use /setcommands to define bot commands.
   • Use /setdescription to set a bot description.

Authentication

Configure the Telegram Action Block with your bot credentials:

• Credential Name: A descriptive name for the bot (e.g., "Workflow Bot").
• Bot Token: The unique token provided by @BotFather.

Configuration

Basic Settings

• Chat ID: Specify the recipient (user, group, or channel).

  User: 123456789
  Group: -987654321
  Channel: @MyChannel or -1001234567890
• Message: Define content with variable support.

  Hello {{userName}}! Your order #{{orderNumber}} is confirmed.
• Parse Mode: Select formatting style:
  • Markdown: For *bold*, _italic_, and `code`.
  • HTML: For <b>bold</b>, <i>italic</i>, and <code>code</code>.

Chat ID Types

User Chat IDs

{
  "chatId": "123456789", // Positive number for users
  "purpose": "Direct notifications or personal alerts"
}

Group Chat IDs

{
  "chatId": "-987654321", // Negative number for groups
  "purpose": "Team updates or group notifications"
}

Channel IDs

{
  "chatId": "@MyChannel", // Public channel username
  "chatId": "-1001234567890", // Channel ID for public/private channels
  "purpose": "Broadcast announcements or updates"
}

Message Formatting

Markdown Format

Basic Formatting:

*Bold text*
_Italic text_
`Inline code`

Advanced Formatting:

📢 *System Update*
 
• Status: *{{systemStatus}}*
• Duration: _{{maintenanceDuration}}_
• Details: `{{updateDetails}}`
 
[Learn More](https://docs.example.com)

HTML Format

Basic Formatting:

<b>Bold text</b>
<i>Italic text</i>
<code>Inline code</code>

Advanced Formatting:

<b>System Alert</b><br>
<i>Service:</i> <code>{{serviceName}}</code><br>
<i>Status:</i> <b>{{status}}</b><br>
<i>Time:</i> {{timestamp}}<br>
<a href="https://status.example.com">Check Status</a>

Use Cases

System Alerts

{
  "chatId": "-987654321", // DevOps group
  "message": `
🚨 *ALERT: System Issue*
 
Server: *{{serverName}}*
Issue: *{{issueDescription}}*
Severity: *{{severity}}*
 
Time: {{timestamp}}
  `,
  "parseMode": "Markdown"
}

Order Notifications

{
  "chatId": "{{customerChatId}}",
  "message": `
🎉 *Order Confirmed*
 
Hi {{customerName}},
 
• Order ID: *{{orderId}}*
• Total: ${{orderTotal}}
• Delivery: {{deliveryDate}}
 
[Track Order]({{trackingUrl}})
  `,
  "parseMode": "Markdown"
}

Team Updates

{
  "chatId": "@company_updates",
  "message": `
<b>Weekly Update</b><br>
<b>Highlights:</b><br>
• Feature: {{featureName}}<br>
• Fixes: {{bugCount}} resolved<br>
• Productivity: {{productivityScore}}%<br>
<i>Great work, team! 🚀</i>
  `,
  "parseMode": "HTML"
}

Event Reminders

{
  "chatId": "{{userChatId}}",
  "message": `
⏰ *Meeting Reminder*
 
*{{meetingTitle}}*
Time: {{meetingTime}}
Location: {{meetingLocation}}
 
*Agenda:*
{{meetingAgenda}}
 
[Join Meeting]({{meetingLink}})
  `,
  "parseMode": "Markdown"
}

Advanced Features

Interactive Messages

While Telegram bots don’t support buttons without inline keyboards, you can create engaging messages:

🤖 *Available Commands:*
 
• `/status` - View system status
• `/help` - Get assistance
• `/settings` - Adjust preferences
 
Reply with your choice or use a command.

Message Threading

Maintain conversation flows:

**Order Progress**
 
✅ Step 1: Order Placed
✅ Step 2: Payment Confirmed
⏳ Step 3: Processing
⬜ Step 4: Shipping
⬜ Step 5: Delivery
 
*Status*: {{currentStatus}}
*ETA*: {{estimatedTime}}

Rich Content Messages

📊 *Daily Analytics*
 
*Traffic:*
• Visitors: {{visitors}} (+{{visitorGrowth}}%)
• Page Views: {{pageViews}}
• Bounce Rate: {{bounceRate}}%
 
*Revenue:*
• Total: ${{revenue}}
• New Customers: {{newCustomers}}
• Conversion: {{conversionRate}}%
 
*Top Pages:*
1. {{topPage1}} ({{topPage1Views}})
2. {{topPage2}} ({{topPage2Views}})
3. {{topPage3}} ({{topPage3Views}})
 
*Generated*: {{reportTime}}

Getting Chat IDs

For Users

• Method 1: Send a message to your bot and retrieve the ID via GET https://api.telegram.org/bot<TOKEN>/getUpdates.
• Method 2: Forward a user’s message to @userinfobot to get their ID.

For Groups

• Method 1: Add your bot to the group, send a message, and use the getUpdates API to find the group ID.
• Method 2: Add @chatid_echo_bot to the group to display the group ID.

For Channels

• Public Channels: Use the @channelname format.
• Private Channels: Add the bot as an admin, post a message, and retrieve the ID via getUpdates.

Error Handling

Authentication Errors

"Unauthorized"

• Verify the bot token is correct and active.
• Check if the token was regenerated by @BotFather.
• Ensure the bot is not deleted or suspended.

Chat Access Errors

"Chat not found"

• Confirm the chat ID is accurate.
• For groups: Ensure the bot is a member.
• For channels: Ensure the bot has admin rights.

"Bot blocked by user"

• Ask the user to unblock the bot.
• Implement error handling for blocked users.

Message Format Errors

"Bad Request: can't parse entities"

• Check Markdown or HTML syntax.
• Escape special characters (e.g., _, *, <).
• Validate message structure.

Rate Limiting

"Too Many Requests"

• Telegram limits: ~30 messages/second to different chats.
• Add delays between messages.
• Use queuing for high-volume sending.

Best Practices

• Clear Messaging: Use concise, actionable content.
• Consistent Formatting: Maintain uniform styles for readability.
• Chat Relevance: Send messages to appropriate recipients.
• Secure Tokens: Store bot tokens in environment variables.
• Monitor Delivery: Track success rates and handle failures.

Integration Patterns

Alert System

1. Detect: Identify system issues.
2. Assess: Evaluate severity.
3. Notify: Send Telegram alerts.
4. Escalate: Notify key personnel if critical.
5. Resolve: Share resolution updates.

Customer Support

1. Ticket: Receive a customer issue.
2. Assign: Route to the support team.
3. Alert: Notify agents via Telegram.
4. Update: Share progress updates.
5. Close: Confirm resolution.

E-commerce Workflow

1. Order: Customer places an order.
2. Confirm: Send confirmation message.
3. Process: Update on processing status.
4. Ship: Share tracking details.
5. Deliver: Confirm delivery.

Response Mapping

Map Telegram API responses to workflow variables:

{
  "ok": true,
  "result": {
    "message_id": 123,
    "from": {
      "id": 987654321,
      "is_bot": true,
      "first_name": "WorkflowBot"
    },
    "chat": {
      "id": 123456789,
      "type": "private"
    },
    "date": 1642234567,
    "text": "Hello World!"
  }
}
// Mapping
result.message_id → {{messageId}}
result.date → {{sentTimestamp}}
result.chat.id → {{chatId}}
ok → {{deliverySuccess}}

Troubleshooting

Setup Issues

"Bot token invalid"

• Verify token format and completeness.
• Regenerate token via @BotFather if needed.
• Ensure the bot is active.

"Can't find chat"

• Validate chat ID format and value.
• For groups: Confirm bot membership.
• For channels: Verify admin rights.

Runtime Issues

"Message not delivered"

• Check if the recipient blocked the bot.
• Verify chat accessibility.
• Ensure message length and format are valid.

"Slow delivery"

• Check Telegram API status (opens in a new tab).
• Verify network connectivity.
• Implement retry logic.

Node Display

The Telegram Action Block displays:

• Chat Type: User, group, or channel with ID.
• Message Preview: Truncated message content.
• Parse Mode: Selected formatting (Markdown/HTML).
• Status: Configuration and delivery status.

Example Workflows

Incident Management

1. Detect: Identify a system error.
2. Assess: Classify severity.
3. Notify: Alert the team via Telegram.
4. Update: Share progress.
5. Resolve: Confirm resolution.

Customer Engagement

1. Action: Customer performs an action.
2. Check: Determine if notification is needed.
3. Personalize: Tailor the message.
4. Send: Deliver via Telegram.
5. Track: Monitor responses.

Marketing Automation

1. Trigger: Launch a campaign.
2. Select: Target specific users.
3. Generate: Create message content.
4. Broadcast: Send to Telegram audience.
5. Analyze: Track engagement metrics.