Skip to content

Send Telegram Message

🤖 Node: Send Telegram Message

This node allows you to send Telegram messages automatically from your automations. It uses the Telegram Bot API to send messages, media files, and interactive buttons to Telegram users or groups.

🔧 Initial Setup: Creating a Telegram Bot

Before you can use this node, you need to create a Telegram bot and obtain your Bot Token. Follow these steps:

Step 1: Open BotFather

  1. Open Telegram on your mobile phone or computer.
  2. Search for and open @BotFather (the official bot for creating bots).
  3. Direct link: https://web.telegram.org/k/#@BotFather

Step 2: Create Your Bot

  1. Send the command /newbot to BotFather.
  2. BotFather will ask you to choose a name for your bot (this is the display name users will see).
  3. Example: Netsocs Arrive Telegram Bot
  4. Then BotFather will ask you to choose a username for your bot (must end in "bot").
  5. Example: netsocs_arrive_bot
  6. Once created, BotFather will send you a message with your Bot Token.
  7. Example: 7767979311:AAHEFLKJSDFLKJSDFxxx

⚠️ Important: Save this token in a secure place. Anyone with this token can control your bot.

Step 3: Start a Conversation with Your Bot

This step is mandatory if you want to send messages using the username field:

  1. Search for your bot using the username you created (e.g., @netsocs_arrive_bot).
  2. Open the chat with your bot.
  3. Click the "Start" button or send the /start command.

Why is this necessary? Telegram bots can only send messages to users who have initiated a conversation with them first. This is a security measure by Telegram.

⚙️ Node Configuration

Once you have created your bot and obtained the Bot Token, you can configure the node. Below we explain each field in the form:

Telegram node configuration form

📋 Configuration Fields

The node configuration is a JSON object with the following structure:

{
  "botToken": "77679793111:AAKSDJFKLSDFXXX",
  "chatId": "",
  "commands": [
    {
      "command": "option1",
      "description": "Option 1",
      "callbackData": "option_1"
    }
  ],
  "mediaFile": "",
  "mediaURL": "",
  "text": "LPR Detection",
  "username": "Netsocs Arrive Telegram Bot",
  "waitResponse": false,
  "waitTime": 30
}

1. botToken ⚠️ (Required)

What is it?
The authentication token for your Telegram bot. This is the "password" that allows the system to send messages through your bot.

Where do I get it?
You receive this token from BotFather when you create your bot (see "Initial Setup" section above).

Format:
A long string of numbers and letters separated by a colon.

Example:

"botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx"

⚠️ Security: Never share your Bot Token with anyone. Anyone with this token can control your bot.

2. chatId (Optional)

What is it?
The unique identifier of the chat where the message will be sent. This can be a user ID or a group ID.

When to use it?
Use chatId when you know the numeric ID of the recipient. This is useful for sending to specific users or groups.

Format:
A numeric string (can be positive or negative for groups).

Example:

"chatId": "123456789"

For groups:

"chatId": "-987654321"

Note: You can use either chatId OR username, but at least one is required. If you provide both, chatId takes priority.

How to get a chatId? - For users: They need to send a message to your bot, then you can retrieve their chatId from the Telegram API. - For groups: Add your bot to the group, then use the Telegram API to get the group's chatId.

3. username (Optional)

What is it?
The Telegram username of the recipient (without the @ symbol).

When to use it?
Use username when you want to send a message to a specific user by their username instead of their numeric ID.

Format:
Text string representing the username (without @).

Example:

"username": "john_doe"

⚠️ Important Requirements:

  • The recipient must have started a conversation with your bot first (clicked "Start" or sent /start).
  • If the user has never interacted with your bot, the message will fail.
  • You can use either chatId OR username, but at least one is required.

4. text ⚠️ (Required)

What is it?
The text message that will be sent to the recipient.

Format:
Any text string. You can include emojis, line breaks, and Telegram formatting.

Example:

"text": "Hello! This is an automated message from Netsocs."

With line breaks:

"text": "LPR Detection\nVehicle plate: ABC123\nTime: 14:30"

With variables (advanced):

"text": "Alert: {{eventType}} detected at {{location}}"

5. commands (Optional)

What is it?
An array of interactive buttons that will appear below your message. These buttons allow recipients to respond with predefined options.

Format:
Array of objects, where each object has: - command: The button label (what the user sees) - description: A description of what the button does - callbackData: The data that will be sent back when the button is clicked

Example:

"commands": [
  {
    "command": "option1",
    "description": "Option 1",
    "callbackData": "option_1"
  },
  {
    "command": "option2",
    "description": "Option 2",
    "callbackData": "option_2"
  }
]

Note: If you don't want to send buttons, you can leave this field as an empty array [] or omit it entirely.

6. mediaFile (Optional)

What is it?
The path to a local file on the server that you want to send as an attachment (image, video, document, etc.).

Format:
String with the file path on the server.

Example:

"mediaFile": "/path/to/local/image.jpg"

Note: This field is for files stored on the Netsocs server. If you want to send a file from a URL, use mediaURL instead.

7. mediaURL (Optional)

What is it?
A public URL to an image, video, or document that you want to send as an attachment.

Format:
Complete URL (must be publicly accessible on the internet).

Example:

"mediaURL": "https://example.com/photo.jpg"

Note: The URL must be publicly accessible. Private URLs or files behind authentication will not work.

8. waitResponse (Optional)

What is it?
A boolean flag that determines whether the automation should wait for a response from the recipient.

Format:
true or false

When to use it? - Set to true if you want the automation to wait for the user to click a button (from commands) before continuing. - Set to false (default) if you just want to send the message and continue immediately.

Example:

"waitResponse": true

Note: If set to true, you should also define commands (buttons) and set an appropriate waitTime.

9. waitTime (Optional)

What is it?
The maximum time (in seconds) that the automation will wait for a response from the recipient.

Format:
Number (integer)

When to use it?
This field only matters if waitResponse is set to true. It defines how long the system will wait before timing out.

Example:

"waitTime": 30

This means the system will wait up to 30 seconds for the user to respond.

Default: If not specified, the default is typically 30 seconds.

✅ Required Fields Summary

Fields marked with ⚠️ are mandatory and must be completed for the node to work:

  • ✅ botToken - Your Telegram bot token (from BotFather)
  • ✅ text - The message text to send
  • ✅ chatId OR username - At least one recipient identifier (chatId or username)
  • ⭕ commands - Interactive buttons (optional)
  • ⭕ mediaFile - Local file attachment (optional)
  • ⭕ mediaURL - URL file attachment (optional)
  • ⭕ waitResponse - Wait for user response (optional, default: false)
  • ⭕ waitTime - Maximum wait time in seconds (optional, default: 30)

🎯 Complete Configuration Examples

Example 1: Simple Text Message

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "chatId": "123456789",
  "text": "Hello! This is a test message from Netsocs automation."
}

Example 2: Message with Interactive Buttons

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "username": "john_doe",
  "text": "LPR Detection: Vehicle ABC123 detected at Main Gate",
  "commands": [
    {
      "command": "Allow Entry",
      "description": "Grant access to the vehicle",
      "callbackData": "allow_entry"
    },
    {
      "command": "Deny Entry",
      "description": "Block the vehicle",
      "callbackData": "deny_entry"
    }
  ],
  "waitResponse": true,
  "waitTime": 60
}

Example 3: Message with Image from URL

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "chatId": "123456789",
  "text": "Intrusion detected! See captured image below:",
  "mediaURL": "https://example.com/security/snapshot.jpg"
}

Example 4: Message with Local File

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "username": "security_team",
  "text": "Daily report attached",
  "mediaFile": "/var/reports/daily-report.pdf"
}

🔍 Troubleshooting

Message is not being sent

  1. Verify your Bot Token:
  2. Make sure you copied the complete token from BotFather.

  3. The token should look like: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

  4. Check the recipient identifier:

  5. If using username, make sure the user has started a conversation with your bot.

  6. If using chatId, verify that the ID is correct.

  7. Test your bot manually:

  8. Try sending a message to your bot from Telegram.
  9. If your bot doesn't respond, there may be an issue with your Bot Token.

Error: "Forbidden: bot was blocked by the user"

Cause: The user has blocked your bot in Telegram.

Solution: The user needs to unblock your bot and start a new conversation.

Error: "Bad Request: chat not found"

Cause: The chatId or username is incorrect, or the user has never interacted with your bot.

Solution: - Verify that the chatId or username is correct. - If using username, make sure the user has sent /start to your bot at least once.

Buttons are not appearing

  1. Verify the commands format:
  2. Make sure the commands field is an array of objects.

  3. Each object must have command, description, and callbackData properties.

  4. Check JSON syntax:

  5. Make sure your JSON is properly formatted (no missing commas, brackets, etc.).

Media file is not being sent

  1. For mediaURL:
  2. Verify that the URL is publicly accessible.

  3. Try opening the URL in your browser to confirm it works.

  4. For mediaFile:

  5. Verify that the file exists on the server.
  6. Check that the Netsocs system has permission to read the file.

📚 Additional Information

  • Telegram Bot API Documentation: For advanced features, refer to the official Telegram Bot API documentation.
  • Message Limits: Telegram has limits on message length (4096 characters) and file sizes (up to 50 MB for most file types).
  • Bot Privacy: By default, bots in groups can only see messages that are direct replies to them or commands starting with /. You can change this in BotFather settings.
  • Response Handling: If waitResponse is true, the automation will capture the button click data (callbackData) and can use it in subsequent nodes.

🔒 Security Best Practices

  1. Protect your Bot Token:
  2. Never commit your Bot Token to version control (Git).

  3. Store it securely in environment variables or configuration files with restricted access.

  4. Validate recipient identifiers:

  5. Make sure you're sending messages only to authorized users.

  6. Limit bot permissions:

  7. Only grant your bot the minimum permissions necessary.

  8. Monitor bot activity:

  9. Regularly check your bot's activity for any suspicious behavior.