> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/reference/nodes/telegram_send_document.md). # Send Telegram Document **Action ID:** `telegram_send_document` ## Description Send a document to a Telegram chat. This node allows you to send any file as a document to individual users or group chats. Supports sending files by Telegram file ID, HTTP URL, or direct upload, with optional captions and metadata. ## Provider **Telegram** ## Connection | Name | Description | Required | Category | | ----------------------- | ------------------------------------------------------------ | :------: | -------- | | Telegram Bot Connection | The Telegram bot connection to use for sending the document. | ✓ | telegram | ## Input Parameters | Name | Type | Required | Default | Description | | --------------------------------- | ------- | :------: | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | chat\_id | string | ✓ | - | Unique identifier for the target chat or username of the target channel (in the format @channelusername) | | document | string | ✓ | - | File to send. Pass a file\_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. | | business\_connection\_id | string | - | - | Unique identifier of the business connection on behalf of which the message will be sent | | message\_thread\_id | integer | - | - | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only | | thumbnail | string | - | - | Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. | | caption | string | - | - | Document caption (may also be used when resending documents by file\_id), 0-1024 characters after entities parsing | | parse\_mode | string | - | - | Mode for parsing entities in the document caption. Can be 'Markdown', 'MarkdownV2', or 'HTML' | | caption\_entities | array | - | - | A JSON-serialized list of special entities that appear in the caption | | disable\_content\_type\_detection | boolean | - | - | Disables automatic server-side content type detection for files uploaded using multipart/form-data | | disable\_notification | boolean | - | - | Sends the message silently. Users will receive a notification with no sound | | protect\_content | boolean | - | - | Protects the contents of the sent message from forwarding and saving | | allow\_paid\_broadcast | boolean | - | - | Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee | | message\_effect\_id | string | - | - | Unique identifier of the message effect to be added to the message; for private chats only | | reply\_parameters | object | - | - | Description of the message to reply to | | reply\_markup | object | - | - | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, etc. |
View JSON Schema ```json { "description": "Telegram send document node input.", "properties": { "chat_id": { "title": "Chat ID", "type": "string", "description": "Unique identifier for the target chat or username of the target channel (in the format @channelusername)" }, "document": { "title": "Document", "type": "string", "description": "File to send. Pass a file_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data." }, "business_connection_id": { "title": "Business Connection ID", "type": "string", "description": "Unique identifier of the business connection on behalf of which the message will be sent" }, "message_thread_id": { "title": "Message Thread ID", "type": "integer", "description": "Unique identifier for the target message thread (topic) of the forum; for forum supergroups only" }, "thumbnail": { "title": "Thumbnail", "type": "string", "description": "Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320." }, "caption": { "title": "Caption", "type": "string", "description": "Document caption (may also be used when resending documents by file_id), 0-1024 characters after entities parsing" }, "parse_mode": { "title": "Parse Mode", "type": "string", "description": "Mode for parsing entities in the document caption. Can be 'Markdown', 'MarkdownV2', or 'HTML'" }, "caption_entities": { "title": "Caption Entities", "type": "array", "description": "A JSON-serialized list of special entities that appear in the caption" }, "disable_content_type_detection": { "title": "Disable Content Type Detection", "type": "boolean", "description": "Disables automatic server-side content type detection for files uploaded using multipart/form-data" }, "disable_notification": { "title": "Disable Notification", "type": "boolean", "description": "Sends the message silently. Users will receive a notification with no sound" }, "protect_content": { "title": "Protect Content", "type": "boolean", "description": "Protects the contents of the sent message from forwarding and saving" }, "allow_paid_broadcast": { "title": "Allow Paid Broadcast", "type": "boolean", "description": "Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee" }, "message_effect_id": { "title": "Message Effect ID", "type": "string", "description": "Unique identifier of the message effect to be added to the message; for private chats only" }, "reply_parameters": { "title": "Reply Parameters", "type": "object", "description": "Description of the message to reply to" }, "reply_markup": { "title": "Reply Markup", "type": "object", "description": "Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, etc." } }, "required": [ "chat_id", "document" ], "title": "TelegramSendDocumentInput", "type": "object" } ```
## Output Parameters | Name | Type | Description | | ------------- | ------- | ------------------------------------------------------------------ | | sent\_message | object | The message that was sent (if successful). | | success | boolean | Whether the document was sent successfully. | | error | string | The error that occurred if the document was not sent successfully. |
View JSON Schema ```json { "description": "Output from a Telegram send document.", "properties": { "sent_message": { "title": "Sent Message if successful", "type": "object", "description": "The message that was sent." }, "success": { "title": "Success", "type": "boolean", "description": "Whether the document was sent successfully." }, "error": { "title": "Error", "type": "string", "description": "The error that occurred if the document was not sent successfully." } }, "required": [ "success" ], "title": "TelegramSendDocumentOutput", "type": "object" } ```
## How It Works This node sends a document file to a specified Telegram chat. You can provide the document in three ways: using a Telegram file\_id (fastest), providing an HTTP URL that Telegram can fetch, or uploading the file directly. The document can include a caption with optional text formatting (HTML/Markdown). Optional thumbnails and reply options can enhance the document message. The node returns success status and either the sent message details or error information. ## Usage Examples ### Example 1: Send PDF Document by File ID **Input:** ``` chat_id: "123456789" document: "BQACAgIAAxkBAAIBZ2Z-..." caption: "Here's the project proposal document" parse_mode: "HTML" ``` **Output:** ``` success: true sent_message: { "message_id": 123, "chat": { "id": 123456789, "type": "private" }, "document": { "file_id": "BQACAgIAAxkBAAIBZ2Z-...", "file_name": "proposal.pdf", "mime_type": "application/pdf", "file_size": 245632 }, "caption": "Here's the project proposal document" } ``` ### Example 2: Send Document by URL to Group **Input:** ``` chat_id: "-1001234567890" document: "https://example.com/report.docx" caption: "Monthly report - November 2024" parse_mode: "HTML" disable_notification: false ``` **Output:** ``` success: true sent_message: { "message_id": 456, "chat": { "id": -1001234567890, "type": "supergroup" }, "document": { "file_id": "BQACAgIAAxkBAAIBZ2Z-...", "file_name": "report.docx", "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "file_size": 523648 } } ``` ### Example 3: Send Spreadsheet to Channel with Protection **Input:** ``` chat_id: "@mydocumentchannel" document: "https://drive.example.com/data.xlsx" caption: "Quarterly sales data" protect_content: true disable_notification: true ``` **Output:** ``` success: true sent_message: { "message_id": 789, "chat": { "username": "mydocumentchannel", "type": "channel" }, "document": { "file_id": "BQACAgIAAxkBAAIBZ2Z-...", "file_name": "data.xlsx" } } ``` ## Common Use Cases * **Document Sharing**: Share reports, presentations, or documents with users * **File Distribution**: Distribute files to groups or channels * **Invoice Delivery**: Send invoices or receipts to users * **Contract Management**: Share contracts or legal documents * **Educational Materials**: Distribute study materials or coursework * **Backup Archives**: Send backup files or archives * **Team Collaboration**: Share files with team members in groups ## Error Handling | Error Type | Cause | Solution | | -------------------- | ------------------------------------------------ | ------------------------------------------------------- | | Invalid Chat ID | Chat ID doesn't exist or bot doesn't have access | Verify chat ID and ensure bot is member of chat/channel | | Invalid Document | Document file is invalid or URL inaccessible | Check file format and ensure URL is publicly accessible | | File Too Large | Document exceeds Telegram's size limit (2 GB) | Reduce file size or compress document | | Invalid File ID | File ID is expired or invalid | Use a valid file\_id or provide URL/file | | Authentication Error | Bot token is invalid or expired | Verify Telegram connection configuration | | Permission Denied | Bot lacks permission to send messages | Check bot permissions in chat/channel | | Message Too Long | Caption exceeds 1024 characters | Reduce caption length | | Invalid Parse Mode | Parse mode is not supported | Use 'Markdown', 'MarkdownV2', or 'HTML' | | Timeout Error | Request took too long to complete | Try again or check connection | ## Notes * **File ID Optimization**: Using file\_id is fastest and doesn't require re-uploading. Telegram stores file IDs indefinitely. * **File Size Limit**: Maximum file size is 2 GB. For very large files, consider splitting or compression. * **Content Type Detection**: Telegram automatically detects file type. Use disable\_content\_type\_detection if you need to override this. * **Captions**: Use formatting (HTML or Markdown) for rich text captions with bold, italic, and links. * **Silent Messages**: Setting disable\_notification=true prevents sound notifications for users. * **Protected Content**: Setting protect\_content=true prevents forwarding and saving by users. * **Message Effects**: Message effects work only in private chats, not groups or channels. * **Channel Access**: To send to channels, use @channelname format and ensure bot is admin.