# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.agenticflow.ai/reference/nodes/telegram_send_document.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.