Skip to content
Nappai Documentation

Telegram Data Transformation

⚠️ DEPRECATION WARNING

This component is deprecated and will be removed in a future version of Nappai. Please migrate to the recommended alternative components.

Telegram Data Transformation is a legacy component that helps you turn raw Telegram messages into clean, usable data. It pulls the message payload from a Telegram webhook, pulls out the useful bits (text, images, etc.), and can optionally tweak the data so it fits the rest of your workflow.

How it Works

When a Telegram message arrives, the component receives a raw update – a JSON payload that contains everything the bot received. The component then:

  1. Parses the update – pulls out the message text, sender, timestamp, and any media.
  2. Applies a transformation – depending on the chosen operation, it can clean up the data (e.g., trim whitespace, convert dates to a standard format) or format it for a downstream tool.
  3. Outputs two things:
    • Transformed Data – a LangFlow Data object that holds the cleaned data.
    • Tool – a ready‑to‑use tool that an AI agent can call, with a name, description, and argument list.

If you enable Mapping Mode, you can feed a batch of updates at once and the component will process each record individually, letting you connect the output of other components to any of the input fields.

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:

  • Normalize Data: Normalizes the incoming data, ensuring consistent structure and formatting.
  • Prepare Output Payload: Prepares the output payload, formatting the transformed data into a structure suitable for downstream components or tools.

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:

  • Raw Update: Update payload captured via webhook or integration, wrapped in a LangFlow Data object.
    • Visible in: Normalize Data, Prepare Output Payload
  • Operation: Apply a single transformation to the extracted data.
    • Visible in: Normalize Data, Prepare Output Payload
  • Mapping Mode: Enable mapping mode to process multiple data records in batch.
    • Visible in: Normalize Data, Prepare Output Payload
  • 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: Normalize Data, Prepare Output Payload
  • 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: Normalize Data, Prepare Output Payload
  • Tools arguments metadata: Defines the arguments metadata for the tools.
    • Visible in: Normalize Data, Prepare Output Payload

Credential
This component requires a credential of type Telegram bot API.

  1. Configure the credential in the Nappai credentials section.
  2. Select that credential in the component’s “Credential” field.
    The credential needs a Telegram bot token (password). Create a bot or get a token from BotFather.

Outputs

  • Transformed Data: A Data object that contains the cleaned and optionally transformed Telegram message.
  • Tool: A Tool object that can be used by an AI agent. It includes the tool name, description, and argument metadata.

These outputs can be fed into other components, stored, or sent to an agent for further processing.

Usage Example

Example 1 – Normalizing a Telegram Message

  1. Drag the Telegram Data Transformation component onto the canvas.
  2. Select Normalize Data in the “Operation” field.
  3. Connect the “Raw Update” input to the output of a Telegram Webhook component.
  4. (Optional) Enable Mapping Mode if you want to process a batch of messages.
  5. The component will output Transformed Data that you can feed into a Data Storage component or an Agent.

Example 2 – Preparing a Payload for an Agent

  1. Use the same component but choose Prepare Output Payload.
  2. Provide a Tool Name like “Send Telegram Reply” and a helpful Tool Description.
  3. Connect the “Raw Update” to the webhook output.
  4. The component will output a Tool that an agent can call to reply to the user, and the Transformed Data can be used to build the reply content.
  • Telegram Base Data Transformation – The base class that handles the low‑level parsing of Telegram updates.
  • Telegram Bot API Credential – The credential type you need to set up before using this component.

Tips and Best Practices

  • Keep your bot token secure – Store it in Nappai’s credential manager, never hard‑code it in your workflow.
  • Use descriptive tool names – Agents rely on the name and description to decide when to use a tool.
  • Test with sample updates – Before deploying, run the component with a few real Telegram messages to verify the output.
  • Enable Mapping Mode only when needed – It adds overhead; use it only for batch processing.

Security Considerations

  • The Telegram bot token is a secret; treat it like a password.
  • Store the token in Nappai’s credential store and grant the component only the permissions it needs.
  • Avoid logging the raw update payload in plain text; if you must log it, mask sensitive fields.