# n8n-nodes-telegram-business

Send text and media from n8n on behalf of a connected Telegram Business account through the Telegram Bot API.

This is a regular n8n input/output node. Place it after the workflow step that selects the business connection, customer chat, and content. It does not receive Telegram updates or create a trigger or webhook. Your workflow remains responsible for authorization, routing, deduplication, conversation context, and state.

Operations

The default operation is Send Message.

Installation

Install n8n-nodes-telegram-business through Settings → Community Nodes on a self-hosted n8n instance. This package has not been verified by n8n.

Requirements

1. Enable Secretary Mode for your bot in @BotFather.
2. Connect the bot from the Telegram Business account and grant it the can_reply right for the chats it should handle.
3. Send only to an eligible private chat that the account owner has made available to the connection. Telegram allows business bots to send and edit messages in private chats with an incoming message from the last 24 hours. The connection must also remain enabled.

A valid bot token alone does not grant access to a business account or its chats.

Credentials

Create a Telegram Business API credential in n8n.

The credential test calls getMe. It checks the bot token, but does not prove that Business Mode is enabled, that a business connection is active, or that it has can_reply access to a particular chat.

Configure the node

Choose an operation and map the fields from your workflow:

• Business Connection ID overrides the credential default. Leave it empty to use the ID stored in the credential. One of these must be set; an explicit node value takes precedence.
• Chat ID identifies the managed private chat. Keep numeric IDs as decimal strings in expressions to avoid number precision loss.
• Text is used by Send Message.
• Media accepts a Telegram file ID or HTTPS URL. Send Video Note requires a Telegram file ID.
• Parse Mode supports Telegram formatting modes such as MarkdownV2. The node passes text through as supplied and does not escape it for you.
• Options is a JSON object of method-specific, allowlisted Bot API fields. Unsupported fields are rejected.

Telegram applies method-specific URL restrictions: document URL fetching currently supports PDF and ZIP, and sticker URLs support static WEBP rather than animated or video stickers. Use a Telegram file ID for those other formats. Telegram validates the actual remote file content.

For example, to replace a manual sendMessage HTTP Request, map the existing workflow values like this:

The token stays in the n8n credential; do not put it in an expression or workflow URL.

Options

Option names use Telegram Bot API spelling. The accepted fields depend on the selected operation. Common fields include disable_notification, protect_content, message_effect_id, reply_parameters, and reply_markup. Text entities, captions, caption entities, link preview settings, and media metadata are available where supported by the selected method.

reply_markup accepts an inline keyboard in this node:

{
  "reply_markup": {
    "inline_keyboard": [
      [{ "text": "Open", "url": "https://example.com" }]
    ]
  }
}

A same-chat reply can use reply_parameters.message_id. Business messages do not support the cross-chat reply_parameters.chat_id field. This node supports inline keyboards; it does not accept reply keyboards or ForceReply.

Media groups

For Send Media Group, provide a JSON array of 2–10 InputMedia objects. This node supports the photo, video, audio, and document types. Each item must include type and media; media can be a Telegram file ID or HTTPS URL. Photos and videos can be combined. Audio albums must contain only audio items, and document albums must contain only document items. Live Photo albums are not included in this release.

[
  { "type": "photo", "media": "<telegram-file-id-or-https-url>" },
  { "type": "video", "media": "<telegram-file-id-or-https-url>" }
]

Local files and multipart uploads are not supported. Paid media and paid-broadcast options are not included.

Output and errors

Successful single-message operations return the Telegram Message object at the root of the n8n output item's json. A media group returns an object shaped like { "messages": [...] }. Item linking to the corresponding input item is preserved.

Each request has a 30-second deadline and a 1 MiB response limit. The node does not automatically retry sends. If a request times out or the connection fails after dispatch, Telegram may have accepted the message even though n8n did not receive the response. When Retry On Fail is enabled, this can send a duplicate; reconcile the outcome before retrying.

With the n8n error-continuation setting enabled, failures are returned as an error object with safe diagnostics such as request_started, statusCode, error_code, code, retry_after, and outcome_unknown, when available. The node does not include the token, request URL, raw response, or Telegram's error description in these diagnostics.

Reference

• Telegram Business Bots
• Telegram Bot API
• sendMessage
• sendMediaGroup
• Telegram message formatting

Requires Node.js 22 or later. MIT licensed. Maintained by wordpost.

The package name is n8n-nodes-telegram-business. It has not been verified by n8n. The initial npm CLI release does not include provenance; n8n's publication requirements call for a public repository and a GitHub Actions release with provenance.

Development

npm ci
npm run build
npm run lint
npm test
npm pack --dry-run