Telegram Integration Guide

Overview

The Telegram integration allows your NINA workflows to connect with Telegram for messaging, chat management, and file handling. This integration enables you to send and manage messages, interact with chats, handle files, and manage callbacks, all directly from your workflows.

Status

At present, our integration comprehensively supports key functionalities related to:

• Messaging: Send, edit, and delete text messages
• Media: Send photos and documents
• Chat Management: Get chat information and manage chat members
• File Handling: Download and manage files
• Callbacks: Handle callback queries from inline keyboards

Credential Configuration

Before using the Telegram integration in your workflows, you need to configure credentials for authentication. The NINA platform supports bot token authentication for Telegram:

Authentication Methods

Bot Token Authentication

The integration uses Telegram Bot Token authentication:

Field	Description	Example
Access Token	Telegram Bot Access Token	1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
Base URL	Base URL for Telegram Bot API	https://api.telegram.org
Auth Type	Authentication type	botToken

How to get your Bot Token:

1. Open Telegram and search for @BotFather
2. Start a chat with BotFather
3. Send the command /newbot
4. Follow the instructions to create your bot:
   • Choose a name for your bot
   • Choose a username for your bot (must end in 'bot')
5. BotFather will provide you with a token that looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

User Authentication

For scraping channels, the integration uses Telegram User API authentication. This is necessary for operations that require a user context rather than a bot context.

Field	Description	Example
API ID	Telegram API ID	1234567
API Hash	Telegram API Hash	0123456789abcdef0123456789abcdef
Session File	Base64-encoded Telegram session file	(Base64 String)
Auth Type	Authentication type	userAuth

How to get your API ID and API Hash:

1. Go to my.telegram.org and log in with your Telegram account.
2. Click on "API development tools".
3. Fill out the form to register a new application.
4. You will be provided with an api_id and api_hash.

How to get your Session File: The session file is generated by authenticating with the Telegram user API. You can use a Python library such as Telethon, or any other script/tool, to generate this file and then Base64-encode it. Please note that we do not recommend using Russian or Iranian phone numbers, as Telegram tends to block them more readily when it detects script-driven activity. Also, if you plan to scrape channels operated by threat actors, do not use a personal phone number—use a dedicated device/account that is not tied to your identity. If you need help, reach out to us for support.

Creating a Telegram Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "Telegram Production Bot")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Telegram"
   • Auth Type: Choose "botToken" or "userAuth"
   • Fill in the authentication fields based on the chosen auth type.

4. Click Test Connection to verify credentials

5. Click Save to store the credential

[Screenshot: Telegram credential configuration form with fields for bot token authentication]

Supported Resources and Operations

The Telegram integration supports the following resources and operations:

Message

Operation	Description
Send Message	Sends a text message to a chat
Send Photo	Sends a photo to a chat
Send Document	Sends a document to a chat
Edit Message Text	Edits an existing text message
Delete Message	Deletes a message
Send and Wait	Sends a message and waits for user approval

Chat

Operation	Description
Get	Gets information about a chat
Get Administrators	Gets a list of administrators in a chat
Leave	Leaves a group, supergroup, or channel

File

Operation	Description
Get	Gets information about a file and optionally downloads it

Callback

Operation	Description
Answer Query	Sends answers to callback queries from inline keyboards

Channel

Requires User Authentication

Operation	Description
Scrape Channels	Retrieve information and messages from Telegram channels

Parameter Merging

The Telegram integration takes full advantage of NINA's parameter merging capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Telegram Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Telegram Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• The combined parameters are used to execute the Telegram operation

Examples

Sending a Basic Message

Below is an example of sending a message to a Telegram chat:

[Screenshot: Integration Node configuration panel showing chat and text fields for sending a Telegram message]

Node Configuration:

{
  "resource": "message",
  "operation": "sendMessage",
  "parameters": {
    "chatId": {
      "mode": "id",
      "value": "-1001234567890"
    },
    "text": "Alert: Security vulnerability detected in production environment",
    "additionalFields": {
      "parseMode": "Markdown",
      "disableWebPagePreview": true
    }
  }
}

Sending a Photo

Send a photo with a caption:

Node Configuration:

{
  "resource": "message",
  "operation": "sendPhoto",
  "parameters": {
    "chatId": {
      "mode": "username",
      "value": "@security_alerts"
    },
    "file_data": "base64_encoded_image_data",
    "filename": "alert.png",
    "caption": "Security Alert: Unusual Activity Detected",
    "additionalFields": {
      "parseMode": "Markdown"
    }
  }
}

Sending a Document

Send a document with a caption:

Node Configuration:

{
  "resource": "message",
  "operation": "sendDocument",
  "parameters": {
    "chatId": {
      "mode": "list",
      "value": "Security Team Chat"
    },
    "file_data": "base64_encoded_document_data",
    "filename": "security_report.pdf",
    "caption": "Monthly Security Report - January 2024",
    "additionalFields": {
      "parseMode": "Markdown"
    }
  }
}

Sending and Waiting for Approval

Send a message with approval buttons and wait for user response:

Node Configuration:

{
  "resource": "message",
  "operation": "sendAndWait",
  "parameters": {
    "chatId": {
      "mode": "id",
      "value": "-1001234567890"
    },
    "text": "Critical security update requires approval",
    "additionalFields": {
      "approvalText": "Approve Update",
      "disapprovalText": "Reject Update",
      "timeoutSeconds": 300,
      "parseMode": "Markdown"
    }
  }
}

Getting Chat Information

Retrieve information about a chat:

Node Configuration:

{
  "resource": "chat",
  "operation": "get",
  "parameters": {
    "chatId": {
      "mode": "username",
      "value": "@security_alerts"
    }
  }
}

Getting Chat Administrators

Get a list of administrators in a chat:

Node Configuration:

{
  "resource": "chat",
  "operation": "getAdministrators",
  "parameters": {
    "chatId": {
      "mode": "id",
      "value": "-1001234567890"
    }
  }
}

Downloading a File

Get and download a file:

Node Configuration:

{
  "resource": "file",
  "operation": "get",
  "parameters": {
    "fileId": "BQACAgEAAxkBAAIQ",
    "download": true
  }
}

Answering a Callback Query

Respond to a callback query from an inline keyboard:

Node Configuration:

{
  "resource": "callback",
  "operation": "answerQuery",
  "parameters": {
    "queryId": "123456789",
    "additionalFields": {
      "text": "Action completed successfully!",
      "showAlert": true
    }
  }
}

Scraping a Channel

Retrieve the last 20 messages from a public channel:

Note: This operation requires a credential with User Authentication.

Node Configuration:

{
  "resource": "channel",
  "operation": "scrapeChannels",
  "parameters": {
    "channelUrls": [
      "https://t.me/some_channel_name"
    ],
    "messageCount": 20
  }
}

Best Practices

1. Chat ID Selection:

   • Use the list mode to select from available chats when possible
   • Use ID mode for production workflows where chat IDs are stable
   • Use username mode for public channels and groups

2. Message Formatting:

   • Use Markdown or HTML formatting for better readability
   • Keep messages concise and well-structured
   • Use emojis sparingly for important alerts

3. File Handling:

   • Always specify a meaningful filename
   • Use appropriate file types for different content
   • Consider file size limits (50MB for regular users, 2GB for premium)

4. Approval Workflows:

   • Set reasonable timeout values for approval requests
   • Use clear and concise approval/rejection button text
   • Handle timeout scenarios in your workflow

5. Error Handling:

   • Implement proper error handling for failed operations
   • Use try-catch blocks in your workflows
   • Log important errors for debugging

Limitations

1. Message Size:

   • Text messages are limited to 4096 characters
   • Captions for media are limited to 1024 characters

2. File Size:

   • Regular users: 50MB limit
   • Premium users: 2GB limit

3. Rate Limits:

   • Bot API has rate limits that vary by method
   • Implement appropriate delays between requests

4. Chat Types:

   • Some operations are limited to specific chat types
   • Check documentation for chat type restrictions

Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify your bot token is correct
   • Ensure the bot has necessary permissions
   • Check if the bot is still active

2. Chat Access Issues:

   • Verify the bot is a member of the chat
   • Check if the bot has necessary permissions
   • Ensure the chat ID is correct

3. File Upload Issues:

   • Check file size limits
   • Verify file format is supported
   • Ensure proper base64 encoding

4. Message Formatting Issues:

   • Verify parse mode syntax
   • Check for invalid characters
   • Ensure proper escaping of special characters

Getting Help

If you encounter issues not covered in this guide:

1. Check the Telegram Bot API Documentation
2. Review the NINA logs for detailed error messages
3. Contact support with specific error details and workflow information