Telegram Message

Send messages, media, or perform actions using Telegram Bot API

How it Works

The Telegram Message component talks to Telegram’s Bot API.
When you choose an operation (for example “Send Text” or “Send Poll”) the component builds the proper HTTP request and sends it to Telegram.
If you enable Mapping Mode, the component can take a list of records and send a message for each one, using the same settings or values that come from other components in the workflow.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

Send Text: Send a plain text message to a chat.
Send Photo: Send a photo file to a chat.
Send Audio: Send an audio file to a chat.
Send Animation: Send an animated GIF or similar to a chat.
Send Video: Send a video file to a chat.
Send Document: Send a document file to a chat.
Send Contact: Share a contact’s phone number and optional vCard.
Delete Message: Remove a message from a chat.
Pin Message: Pin a message in a chat.
Unpin Message: Unpin a previously pinned message.
Send Poll: Create a poll with one or more options.

To use the component, first select the operation you need in the Operation field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

Fixed: You type the value directly into the field.
Mapped: You connect the output of another component to use its result as the value.
Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

Attachment: Media file to attach (photo, video, audio, document, etc.).
- Visible in: Send Photo, Send Audio, Send Animation, Send Video, Send Document
Action: Select the action you want to perform on Telegram. Each option requires different fields to be filled.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Chat ID: Unique number of the Telegram chat where the message will be sent.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
First Name: First name of the person whose contact you want to share. Required to send contact information.
- Visible in: Send Contact
Is Anonymus: Determines if the poll will hide voter identities. In anonymous polls, who voted for which option is not shown.
- Visible in: Send Poll
Last Name: Last name of the person whose contact you want to share. Optional.
- Visible in: Send Contact
Mapping Mode: Enable mapping mode to process multiple data records in batch.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Message ID: Number of the message you want to reply to. Number of the message you want to edit, pin, or delete. Required for these specific operations.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Send Poll, Delete Message, Pin Message, Unpin Message
Mode: Choose between a simple setup where the chat ID from the Telegram webhook is taken, or an advanced setup where additional inputs are provided.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Multiple Answers: If enabled, users can select multiple options in the poll. Useful for multiple-choice surveys.
- Visible in: Send Poll
Options: List of options for the poll (minimum 2). Each should be a possible answer to the question.
- Visible in: Send Poll
Phone Number: Phone number you want to share as a contact. Must be in international format (+1234567890).
- Visible in: Send Contact
Question: Poll question text to show to users. Should be clear and concise.
- Visible in: Send Poll
Session ID: Unique identifier for this conversation. Helps maintain chat context and organize messages by session.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Text: Text of the message you want to send. You can include emojis and basic formatting like bold or italic.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document
VCard: Additional contact information in standard vCard format. Optional.
- Visible in: Send Contact
Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Tools arguments metadata: Defines the arguments metadata for the tools.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
message_to_modify: Content to replace the existing message when editing.
- Visible in: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Send Poll, Delete Message, Pin Message, Unpin Message

Outputs

Telegram Response: Data returned from Telegram API after performing the selected operation.
Tool: Tool representation for use in agent workflows.

Usage Example

Scenario 1 – Send a simple text message

Drag the Telegram Message component onto the canvas.
In the Operation field, choose Send Text.
Set Chat ID to the numeric ID of the chat you want to message.
Enter the message in the Text field.
(Optional) Provide a Session ID if you want to keep track of the conversation.
Run the workflow – the component will send the text to Telegram and return the API response.

Scenario 2 – Create a poll

Drag the Telegram Message component onto the canvas.
Choose Send Poll as the operation.
Fill in Chat ID and Question.
List at least two options in the Options field, separated by commas.
Toggle Is Anonymus or Multiple Answers if needed.
Run the workflow – a poll will appear in the specified chat.

Telegram Bot API Credential – Create and store the bot token that the component uses to authenticate with Telegram.
Telegram Message – The component itself, used for sending messages, media, and performing actions.

Tips and Best Practices

Use Mapping Mode when you need to send the same message to many chats or records.
Keep your bot token secure; store it in the Nappai credentials section and never expose it in the workflow.
Stick to Telegram’s file size limits (e.g., 50 MB for photos, 20 MB for audio).
For polls, provide clear, concise questions and a minimum of two options.
If you’re sending many messages, consider adding short pauses to avoid hitting Telegram’s rate limits.

Security Considerations

Store the Telegram bot token in the Nappai credentials store; never hard‑code it in the workflow.
Limit the bot’s permissions to only the actions you need (e.g., sending messages, deleting messages).
Use HTTPS endpoints for any webhook integrations to protect data in transit.