# Send Telegram Audio **Action ID:** `telegram_send_audio` ## Description Send an audio file to a Telegram chat. This node allows you to send audio files (MP3, M4A, etc.) to individual users or group chats, with optional metadata like track name, performer, and duration. Supports file uploads, Telegram file IDs, or HTTP URLs. ## Provider **Telegram** ## Connection | Name | Description | Required | Category | | ----------------------- | --------------------------------------------------------- | :------: | -------- | | Telegram Bot Connection | The Telegram bot connection to use for sending the audio. | ✓ | 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) | | audio | string | ✓ | - | Audio file to send. Pass a file\_id as String to send an audio file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get an audio 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 | | caption | string | - | - | Audio caption, 0-1024 characters after entities parsing | | parse\_mode | string | - | - | Mode for parsing entities in the audio caption. Can be 'Markdown', 'MarkdownV2', or 'HTML' | | caption\_entities | array | - | - | A JSON-serialized list of special entities that appear in the caption | | duration | integer | - | - | Duration of the audio in seconds | | performer | string | - | - | Performer of the audio | | title | string | - | - | Track name | | 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. | | 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 audio 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)" }, "audio": { "title": "Audio", "type": "string", "description": "Audio file to send. Pass a file_id as String to send an audio file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get an audio 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" }, "caption": { "title": "Caption", "type": "string", "description": "Audio caption, 0-1024 characters after entities parsing" }, "parse_mode": { "title": "Parse Mode", "type": "string", "description": "Mode for parsing entities in the audio 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" }, "duration": { "title": "Duration", "type": "integer", "description": "Duration of the audio in seconds" }, "performer": { "title": "Performer", "type": "string", "description": "Performer of the audio" }, "title": { "title": "Title", "type": "string", "description": "Track name" }, "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." }, "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", "audio" ], "title": "TelegramSendAudioInput", "type": "object" } ```
## Output Parameters | Name | Type | Description | | ------------- | ------- | --------------------------------------------------------------- | | sent\_message | object | The message that was sent (if successful). | | success | boolean | Whether the audio was sent successfully. | | error | string | The error that occurred if the audio was not sent successfully. |
View JSON Schema ```json { "description": "Output from a Telegram send audio.", "properties": { "sent_message": { "title": "Sent Message if successful", "type": "object", "description": "The message that was sent." }, "success": { "title": "Success", "type": "boolean", "description": "Whether the audio was sent successfully." }, "error": { "title": "Error", "type": "string", "description": "The error that occurred if the audio was not sent successfully." } }, "required": [ "success" ], "title": "TelegramSendAudioOutput", "type": "object" } ```
## How It Works This node sends an audio file to a specified Telegram chat. You can provide the audio in three ways: using a Telegram file\_id (fastest), providing an HTTP URL that Telegram can fetch, or uploading the file directly. The audio can include metadata like track name, performer, and duration. Optional caption with formatting, thumbnails, and message effects can enhance the audio message. The node returns success status and either the sent message details or error information. ## Usage Examples ### Example 1: Send Audio by File ID **Input:** ``` chat_id: "123456789" audio: "AgACAgIAAxkBAAIBZ2Z-..." title: "My Favorite Song" performer: "Artist Name" duration: 180 caption: "Check out this amazing track!" ``` **Output:** ``` success: true sent_message: { "message_id": 123, "chat": { "id": 123456789, "type": "private" }, "audio": { "file_id": "AgACAgIAAxkBAAIBZ2Z-...", "duration": 180, "performer": "Artist Name", "title": "My Favorite Song" }, "caption": "Check out this amazing track!" } ``` ### Example 2: Send Audio by URL to Group **Input:** ``` chat_id: "-1001234567890" audio: "https://example.com/music.mp3" caption: "New podcast episode available" parse_mode: "HTML" disable_notification: false ``` **Output:** ``` success: true sent_message: { "message_id": 456, "chat": { "id": -1001234567890, "type": "supergroup" }, "audio": { "file_id": "AgACAgIAAxkBAAIBZ2Z-...", "duration": 2400 }, "caption": "New podcast episode available" } ``` ### Example 3: Send to Channel with Silent Notification **Input:** ``` chat_id: "@mychannel" audio: "https://cdn.example.com/announcement.mp3" title: "Important Announcement" caption: "Listen to our latest update" disable_notification: true protect_content: true ``` **Output:** ``` success: true sent_message: { "message_id": 789, "chat": { "username": "mychannel", "type": "channel" }, "audio": { "file_id": "AgACAgIAAxkBAAIBZ2Z-..." } } ``` ## Common Use Cases * **Music Sharing**: Send music tracks or audio clips to users * **Podcast Distribution**: Distribute podcast episodes to channels or groups * **Voice Messages**: Send audio messages as alternatives to text * **Audio Alerts**: Send audio alerts or notifications * **Music Bot**: Build a music sharing or streaming bot * **Educational Content**: Distribute audio lectures or lessons * **Announcements**: Send audio announcements to groups or channels ## 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 Audio | Audio file is invalid or URL inaccessible | Check file format and ensure URL is publicly accessible | | File Too Large | Audio file exceeds Telegram's size limit (50 MB) | Compress audio or reduce file size | | 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. * **File Size Limit**: Maximum file size is 50 MB. Larger files must be compressed. * **Audio Metadata**: Providing title and performer improves the user experience in Telegram's music player. * **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_audio.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.