Telematic icon

Telematic

Use Telegram Client API

Actions12

Overview

This node integrates with the Telegram Client API, enabling users to perform a wide range of Telegram messaging and chat management operations directly within n8n workflows. It supports sending text messages, media files (photos, videos, audio, voice notes, documents), forwarding and replying to messages, deleting messages, retrieving message history and chat members, searching messages, and managing chat membership (joining or leaving chats).

Common scenarios include automating notifications via Telegram, managing group chats, archiving chat histories, or building bots that interact with users by sending or processing messages.

For example:

  • Automatically send a notification message to a Telegram channel when a new order is received.
  • Forward important messages from one chat to another.
  • Retrieve recent messages from a chat for analysis or logging.
  • Search messages containing specific keywords in a chat.

Properties

Name Meaning
Options Collection of optional parameters:
• Silent: Send message without notification (true/false)
• Caption: Caption text for media messages
• Parse Mode: How to parse message text — None, Markdown, or HTML
• Limit: Maximum number of items to return (for list operations)

Note: The node also requires other properties depending on the operation, such as:

  • Chat ID: Identifier or username of the chat/channel.
  • User ID: Identifier or username of a user (for user info retrieval).
  • Message Text: Text content of the message to send.
  • File Path Or URL: Path or URL of the file/media to send.
  • Media Type: Type of media (photo, video, audio, voice, document).
  • Message ID: ID of a specific message (for reply, forward, delete).
  • To Chat ID: Target chat ID for forwarding messages.
  • Search Query: Text query for searching messages.

These are dynamically shown based on the selected operation.

Output

The node outputs JSON objects representing the result of each operation. Common output fields include:

  • success: Boolean indicating if the operation succeeded.
  • For message sending operations:
    • messageId: ID of the sent message.
    • date: Timestamp of the message.
    • text or mediaType: Content details.
  • For message history or search:
    • messages: Array of message objects retrieved.
  • For chat members:
    • members: Array of chat participant objects.
  • For user info:
    • user: User entity information.
  • For delete, join, leave operations:
    • Confirmation flags like deletedMessageId, joined, or left.
  • For forwarding:
    • Details about original and forwarded messages.

If binary data is involved (e.g., sending files), the node handles it internally but does not output raw binary data.

Dependencies

  • Requires an API key credential with Telegram API credentials (apiId and apiHash) and a valid session string.
  • Uses the Telegram Client SDK to connect and interact with Telegram servers.
  • Requires network access to Telegram's API endpoints.
  • No additional environment variables are needed beyond the provided credentials.

Troubleshooting

  • Missing Credentials: The node will throw an error if no Telegram API credentials are provided. Ensure you have configured the required API ID, API hash, and session token.
  • Invalid Chat or User IDs: Errors may occur if chat IDs, usernames, or user IDs are incorrect or inaccessible. Verify these identifiers carefully.
  • Operation Not Supported: Selecting an unsupported operation will cause an error.
  • Connection Issues: Network problems or invalid session tokens can prevent connecting to Telegram. Check your internet connection and credential validity.
  • File Sending Errors: If file paths or URLs are invalid or inaccessible, sending media or files will fail.
  • Rate Limits: Telegram enforces rate limits; excessive requests may be throttled or blocked temporarily.

To resolve errors, review the error messages returned in the output JSON under the error field when "Continue On Fail" is enabled, or check the workflow execution logs.

Links and References

Discussion