Telegram

1. Overview

The Telegram tool in GoInsight allows you to seamlessly integrate the Telegram Bot API into your automated workflows. By connecting your Telegram Bot, you can automate communication, manage community interactions, and process media files directly within your processes.

Through this node, you can perform a comprehensive range of operations, including:

• Message Management: Send, edit, delete, and pin various types of messages including text, photos, videos, documents, and media groups.
• Chat Administration: Retrieve chat information, manage administrators, update chat titles and descriptions, and handle chat members.
• Interactive Queries: Answer inline queries and callback queries from inline keyboards to build interactive bot experiences.
• Update Handling: Fetch the latest updates (messages, callbacks, events) via long polling to trigger subsequent workflow actions.

2. Prerequisites

Before using the Telegram node, you must meet the following requirements:

• You need a valid Telegram account.
• You must create a Telegram Bot via BotFather and obtain the Bot Token.
• For group or channel management operations, your bot must be added to the target chat and granted the necessary administrator privileges.

3. Credentials

For detailed instructions on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: Chat, File, Message, Query, and Update.

Operation Details

Get a Chat

Gets up-to-date information about the chat.

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername)

Output:

• Chat (object): Full information about a chat.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Get Chat Administrators

Gets a list of administrators in a chat, which aren't bots.

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername)

Output:

• Administrators (object-array): List of administrator data retrieved from Telegram.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Get Chat Member

Gets information about a member of a chat. The method is only guaranteed to work for other users if the bot is an administrator in the chat.

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername)
• UserId: Unique identifier of the target user.

Output:

• Member (object): Member data retrieved from Telegram.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Set Chat Title

Changes the title of a chat. Titles can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights.

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername).
• Title: New chat title, 1-128 characters.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Set Chat Description

Changes the description of a group, a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate administrator rights

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername).

Options:

• Description: New chat description, 0-255 characters.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Chat Action

Sends a chat action when you need to tell the user that something is happening on the bot's side. The status is set for 5 seconds or less.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target supergroup (in the format @supergroupusername).
• Action: Type of action to broadcast.

Options:

• BusinessConnectionId: Unique identifier of the business connection on behalf of which the message will be sended.
• MessageThreadId: Identifies the target message thread or forum topic.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Leave a Chat

Leaves a group, supergroup or channel for your bot. ⚠️ Warning: This action is irreversible.

Input Parameters:

• ChatId: The unique identifier for the target chat or username of the target supergroup or channel (in the format @channelusername)

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Get a File

Gets basic information about a file and prepares it for downloading. Maximum downloadable file size is 20MB.

Input Parameters:

• FileId: The unique identifier of the file to retrieve.

Options:

• Downloaded: Whether to download the file content immediately.

Output:

• File (object): A file object ready to be downloaded.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Text Message

Sends a text message to a chat.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername)
• Text: Text of the message to be sent, 1-4096 characters after entities parsing.

Options:

• ParseMode: Mode for parsing entities in the message text.
• Entities: List of special entities that appear in the text, which can be specified instead of parse_mode.
• LinkPreviewOptions: Options for link preview.
• SuggestedPostParameters: Contains parameters of a post that is being suggested by the bot.
• ReplyParameters: Contains parameters of a reply to a message.
• ReplyMarkup: Contains parameters of a reply markup to a message.
• AdditionalFields: Additional fields to be included in the sent message.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Document

Sends a document to a chat. Supports file ID, URL, or binary file content.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername).
• FileIdUrl: ⚠️ Mutually exclusive with FileContent. Can be a file_id, an HTTP URL for Telegram to get a file from the Internet.

Options:

• Caption: Document caption, 0-1024 characters.
• ParseMode: Mode for parsing entities in the document caption.
• ReplyParameters: Contains parameters of a reply to a message.
• AdditionalFields: Additional fields to be included in the request.
• FileContent: ⚠️ Mutually exclusive with FileIdUrl. The contents of a file to be uploaded.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Photo

Sends a photo to a chat. Supports file ID, URL, or binary file path.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername).
• Photo: Photo to send. Can be a file_id, an HTTP URL, or local file path to a photo file.

Options:

• Caption: Photo caption, 0-1024 characters after entities parsing.
• ParseMode: Mode for parsing entities in the document caption.
• CaptionEntities: A list of special entities that appear in the caption.
• AdditionalFields: Additional fields to be included in the sent message.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Video

Sends a video file to a chat, Telegram clients support MPEG4 videos. Supports file ID, URL, or MPEG4 videos file.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) to send the video to.
• Video: Can be a file_id, an HTTP URL, or local file path to a video file.

Options:

• Caption: Video caption, 0-1024 characters after entities parsing.
• ParseMode: Mode for parsing entities in the video caption.
• Thumbnail: The content of thumbnail for the document being sent.
• AdditionalFields: Additional fields to be included in the sent video.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send an Audio

Sends an audio file.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) to send the audio to.
• Audio: Can be a file_id, an HTTP URL, or local file path to an audio file.

Options:

• Caption: Audio caption, 0-1024 characters after entities parsing.
• ParseMode: Mode for parsing entities in the audio caption.
• Thumbnail: Thumbnail of sent audio.
• AdditionalFields: Additional fields to be included in the sent audio.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send an Animation

Sends an animated file (GIF or H.264/MPEG-4 AVC video without sound) to a chat. Supports file ID, URL, or gif file.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) to send the animation to.
• Animation: Can be a file_id, an HTTP URL, or local file path to an animation file.

Options:

• Caption: Animation caption, 0-1024 characters after entities parsing.
• ParseMode: Mode for parsing entities in the animation caption.
• Thumbnail: The content of thumbnail for the document being sent.
• SuggestedPostParameters: Contains parameters of a post that is being suggested by the bot.
• ReplyParameters: Contains parameters of a reply to a message.
• ReplyMarkup: Contains parameters of a reply markup to a message.
• AdditionalFields: Additional fields to be included in the sent animation.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Sticker

Sends a sticker to a chat. Supports file ID, URL, binary file, or local file path to a sticker file.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) to send the sticker to.
• Sticker: Sticker to send. Can be a file_id, an HTTP URL, or local file path to a sticker file.

Options:

• Emoji: Emoji associated with the sticker; only for just uploaded stickers
• DisableNotification: Sends the message silently.
• ProtectContent: Protects the contents of the sent message from forwarding and saving.
• AdditionalFields: Additional fields to be included in the request.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Location

Sends a location (point on the map) to a chat.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername).
• Latitude: Latitude of the location.
• Longitude: Longitude of the location.

Options:

• HorizontalAccuracy: The radius of uncertainty for the location, measured in meters.
• LivePeriod: Period in seconds for which the location will be updated.
• AdditionalFields: Additional fields to be included in the sent message.

Output:

• Message (object): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send a Media Group Message

Sends a group of photos, videos, documents or audios as an album to a chat.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) to send the media group to.
• MediaList: List of media items must include 2-10 items.

Options:

• ReplyParameters: Reply to a specific message in the chat.
• BusinessConnectionId: Unique identifier of the business connection on behalf of which the message will be sent.
• AdditionalFields: Additional fields to be included in the request.

Output:

• Message (object-array): Contains the sent message.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Send and Wait for Response

Send a message to a Telegram chat and pause the workflow execution until the user confirms the operation.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername)
• Text: Text of the message to be sent to the user (1-4096 characters).

Options:

• WaitTimeout: Timeout in seconds for waiting for the response.
• PollingInterval: Check interval (seconds): How many seconds does the system wait before checking if the user has replied?
• ForceReply: Whether to show a 'Reply' button to the user.

Output:

• Text (string): Reply text from the user.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Edit a Text Message

Edits text and game messages.

Input Parameters:

• Text: New text of the message, 1-4096 characters.

Options:

• ChatId: Unique identifier for the target chat or username of the target channel (in the format @channelusername) where the message is located.
• MessageId: The ID of the message to edit.
• InlineMessageId: Identifier of the inline message.
• ParseMode: Mode for parsing entities in the message text.
• BusinessConnectionId: Unique identifier of the business connection on behalf of which the message to be edited was sent.
• AdditionalFields: Additional fields to be included in the request.

Output:

• Message (object): Message details edited.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Delete a Chat Message

Deletes a chat message, including service messages, with limitations.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername) where the message is located.
• MessageId: The ID of the message to delete.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Pin a Chat Message

Adds a message to the chat's pinned messages list.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername) where the message is located.
• MessageId: The ID of the message to pin.

Options:

• BusinessConnectionId: Unique identifier of the business connection on behalf of which the message will be pinned.
• DisableNotification: Set to True to suppress notifications for the new pinned message.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Unpin a Chat Message

Removes a message to the chat's pinned messages list.

Input Parameters:

• ChatId: Unique identifier for the target chat or username of the target user, supergroup or channel (in the format @channelusername) where the message is located.

Options:

• MessageId: The ID of the message to unpin.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Answer Inline Query

Sends an answer to an inline query. No more than 50 results per query are allowed.

Input Parameters:

• InlineQueryId: Unique identifier for the answered query.
• Results: A list of results for the inline query.

Options:

• CacheTime: The maximum amount of time in seconds that the result of the inline query may be cached on the server.
• IsPersonal: Pass True, if results may be cached on the server side only for the user that sent the query.
• NextOffset: Pass the offset that a client should send in the next query with the same text to receive more results.
• Button: A button to be shown above inline query results.

Output:

• InlineQueryId (string): Echo of the inline query ID that was answered.
• ResultCount (number): Number of results sent to Telegram.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Answer Query

Sends an answer to a callback query sent from an inline keyboard.

Input Parameters:

• CallbackQueryId: Unique identifier for the query to be answered.

Options:

• Text: Text of the notification.
• ShowAlert: If True, an alert will be shown by the client instead of a notification at the top of the chat screen.
• Url: URL that will be opened by the user's client.
• CacheTime: The maximum time (in seconds) for the client to cache the results of this callback query.

Output:

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

Get Updates

Retrieves new updates for the bot using long polling. Each update may contain messages, callback queries, member changes, etc.

Options:

• Offset: Identifier of the first update to be returned.
• Limit: Limits the number of updates to be retrieved.
• Timeout: Timeout for long polling (in seconds).
• AllowedUpdates: A list of the update types you want your bot to receive.

Output:

• Updates (object-array): Updates retrieved from Telegram.
• NextOffset (number): The offset to use for the next getUpdates call.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• StatusCode (number): Operation status code: 200=Success, -1=Parameter validation error, 500=System error.
• ErrorMessage (string): Detailed error message if any error occurred.

5. Example Usage

This section will guide you through creating a simple workflow to send a text message to a specific Telegram chat using the Send a Text Message action.

Workflow Overview: Start -> Telegram -> End

Step-by-Step Guide:

1. Add the Telegram Node:
   • In your workflow canvas, click the "+" icon to add a new node.
   • Navigate to the "Tools" tab in the panel.
   • Find and select Telegram.
   • From the list of supported operations, select Send a Text Message. This will add the node to your canvas.
2. Configure the Node:
   • Click on the newly added Send a Text Message node to open its configuration panel on the right.
   • Credentials: At the top of the panel, select your pre-configured Telegram Bot credentials from the dropdown menu.
   • Parameter Configuration:
   • ChatId: Enter the unique identifier for the target chat. This can be a numeric ID (e.g., 123456789) or a channel username (e.g., @my_channel_username).
   • Text: Enter the message you want to send. For example: Hello from GoInsight! This is an automated message.
   • (Optional) ParseMode: If you want to format your text (e.g., bold or italics), you can select HTML or MarkdownV2 and format your Text accordingly.
3. Run and Verify:
   • Once the required parameters are filled, any error indicators on the node will disappear.
   • Click the "Test Run" (or "Run") button in the top right corner of the canvas.
   • After a successful execution, check your Telegram app. You should see the message delivered to the specified chat. You can also click the log icon on the node to view the detailed API response.

By completing these steps, you have successfully automated sending a message via Telegram.

6. FAQs

Q: How do I find the ChatId for a user or a group?

• A: You can find the ChatId by doing the following:
  • Send a message to your bot from the target user or group.
  • Use the Get Updates operation in GoInsight.
  • Look at the output logs. Inside the Updates array, find the message object, and locate the chat.id field. This numeric value is your ChatId.

Q: Why is my bot failing to send messages to a group? (Error 403 or similar)

• A: Please check the following points:
  • Ensure the bot has actually been added to the group.
  • If the group has strict permissions, ensure the bot has been promoted to an Administrator with "Send Messages" rights.
  • Check if the bot's "Group Privacy" mode is enabled in BotFather, which might restrict it from reading or interacting with certain messages.

Q: What is the difference between MarkdownV2 and HTML in ParseMode?

• A: Both allow you to format text, but they use different syntaxes:
  • HTML uses standard tags like bold and italic. It is generally easier for beginners and less prone to escaping errors.
  • MarkdownV2 uses symbols like bold and _italic_. It requires strict escaping for special characters (like -, ., !), which can sometimes cause errors if not formatted perfectly.

Q: Why is the "Send and Wait for Response" node timing out even though the user replied?

• A: The user must explicitly use Telegram's built-in "Reply" feature on the specific message sent by the bot. If the user simply types a new message in the chat without replying to the bot's prompt, the node will not recognize it and will eventually time out.

7. Official Documentation

For more advanced configurations and a deeper understanding of the API, please refer to the official documentation:

Telegram Official API Documentation