> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bot Integration for AI Agents & Workflows

> Send messages, manage chats, and interact with users via Telegram Bot API. Supports text messages, media, chat management, and user moderation.

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/df8MOr-hXotYLTh5/logos/telegram.svg?fit=max&auto=format&n=df8MOr-hXotYLTh5&q=85&s=7449a17c983e343dc2b034223a93d5be" alt="Telegram Bot logo" width="72" height="72" data-path="logos/telegram.svg" />

## Overview

Add **Telegram Bot** to any ModuleX agent or workflow. Telegram Bot API integration via direct HTTP against `api.telegram.org/bot<token>/<method>`. Covers messaging, chat/member management, and a long-poll updates feed.

<Info>
  **Categories**: Communication · Communication & Collaboration · Automation · Development · Social Media · Messaging · **Auth**: Bot Token · **Actions**: 17
</Info>

## Authentication

### Bot Token Authentication

Authenticate using your Telegram Bot token from @BotFather

#### Required Credentials

| Field              | Description                                      | Required | Format |
| ------------------ | ------------------------------------------------ | -------- | ------ |
| Telegram Bot Token | Your Telegram Bot token obtained from @BotFather | Yes      | `-`    |

## Available Actions

<AccordionGroup>
  <Accordion title="send_text_message — Send a text message to a Telegram chat. Supports Markdown, MarkdownV2, and HTML formatting.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="text" type="string" required>
      Text of the message (1-4096 characters)
    </ResponseField>

    <ResponseField name="parse_mode" type="string">
      Mode for parsing entities ('Markdown', 'MarkdownV2', or 'HTML')
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently with no sound (Default: `false`)
    </ResponseField>

    <ResponseField name="reply_to_message_id" type="integer">
      ID of the message to reply to
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendTextMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_photo — Send a photo to a Telegram chat. Photos can be sent by URL or file_id.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="photo" type="string" required>
      Photo to send (file\_id or HTTP URL)
    </ResponseField>

    <ResponseField name="caption" type="string">
      Photo caption (0-1024 characters)
    </ResponseField>

    <ResponseField name="parse_mode" type="string">
      Mode for parsing entities ('Markdown', 'MarkdownV2', or 'HTML')
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently with no sound (Default: `false`)
    </ResponseField>

    <ResponseField name="reply_to_message_id" type="integer">
      ID of the message to reply to
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendPhotoOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_document — Send a document or file to a Telegram chat.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="document" type="string" required>
      Document to send (file\_id or HTTP URL)
    </ResponseField>

    <ResponseField name="caption" type="string">
      Document caption (0-1024 characters)
    </ResponseField>

    <ResponseField name="parse_mode" type="string">
      Mode for parsing entities ('Markdown', 'MarkdownV2', or 'HTML')
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently with no sound (Default: `false`)
    </ResponseField>

    <ResponseField name="reply_to_message_id" type="integer">
      ID of the message to reply to
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendDocumentOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_video — Send a video to a Telegram chat.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="video" type="string" required>
      Video to send (file\_id or HTTP URL)
    </ResponseField>

    <ResponseField name="caption" type="string">
      Video caption (0-1024 characters)
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Duration of sent video in seconds
    </ResponseField>

    <ResponseField name="parse_mode" type="string">
      Mode for parsing entities ('Markdown', 'MarkdownV2', or 'HTML')
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently with no sound (Default: `false`)
    </ResponseField>

    <ResponseField name="reply_to_message_id" type="integer">
      ID of the message to reply to
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendVideoOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="send_audio — Send an audio file to a Telegram chat.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="audio" type="string" required>
      Audio to send (file\_id or HTTP URL)
    </ResponseField>

    <ResponseField name="caption" type="string">
      Audio caption (0-1024 characters)
    </ResponseField>

    <ResponseField name="duration" type="integer">
      Duration of the audio in seconds
    </ResponseField>

    <ResponseField name="performer" type="string">
      Performer of the audio
    </ResponseField>

    <ResponseField name="title" type="string">
      Track name
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendAudioOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="forward_message — Forward a message from one chat to another.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="from_chat_id" type="string" required>
      Chat where the original message was sent
    </ResponseField>

    <ResponseField name="message_id" type="integer" required>
      Message identifier in from\_chat\_id
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Send silently (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "ForwardMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="edit_text_message — Edit a text message previously sent by the bot.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="message_id" type="integer" required>
      Identifier of the message to edit
    </ResponseField>

    <ResponseField name="text" type="string" required>
      New text of the message (1-4096 characters)
    </ResponseField>

    <ResponseField name="parse_mode" type="string">
      Mode for parsing entities
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "EditTextMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="delete_message — Delete a message from a chat (messages older than 48 hours cannot be deleted).">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="message_id" type="integer" required>
      Identifier of the message to delete
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "DeleteMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="pin_message — Pin a message in a chat. Bot must be an administrator with can_pin_messages permission.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="message_id" type="integer" required>
      Identifier of the message to pin
    </ResponseField>

    <ResponseField name="disable_notification" type="boolean">
      Pin silently (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "PinMessageOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_chat_member_count — Get the number of members in a chat.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetChatMemberCountOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_chat_administrators — Get a list of administrators in a chat with their permissions.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetChatAdministratorsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_updates — Get incoming updates via long polling: messages, edited messages, channel posts, and other events.">
    ### Parameters

    <ResponseField name="offset" type="integer">
      Identifier of the first update to be returned
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Number of updates to retrieve (1-100) (Default: `100`)
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Timeout in seconds for long polling (Default: `0`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetUpdatesOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="ban_chat_member — Ban a user from a group, supergroup, or channel. Bot must be an administrator.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="user_id" type="integer" required>
      Unique identifier of the target user
    </ResponseField>

    <ResponseField name="until_date" type="integer">
      Date when the user will be unbanned (Unix time)
    </ResponseField>

    <ResponseField name="revoke_messages" type="boolean">
      Delete all messages from the chat for the user (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "BanChatMemberOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="unban_chat_member — Unban a previously banned user.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="user_id" type="integer" required>
      Unique identifier of the target user
    </ResponseField>

    <ResponseField name="only_if_banned" type="boolean">
      Do nothing if the user is not banned (Default: `true`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "UnbanChatMemberOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="create_chat_invite_link — Create an additional invite link for a chat. Bot must have can_invite_users permission.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    <ResponseField name="name" type="string">
      Invite link name (0-32 characters)
    </ResponseField>

    <ResponseField name="expire_date" type="integer">
      Unix timestamp when the link will expire
    </ResponseField>

    <ResponseField name="member_limit" type="integer">
      Maximum number of users (1-99999)
    </ResponseField>

    <ResponseField name="creates_join_request" type="boolean">
      Users joining need admin approval (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "CreateChatInviteLinkOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_chat — Get up-to-date information about a chat including title, description, photo, and settings.">
    ### Parameters

    <ResponseField name="chat_id" type="string" required>
      Unique identifier for the target chat or @username of the target channel
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetChatOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_me — Get basic information about the bot — its username, name, and capabilities.">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "result": {
          "default": null,
          "title": "Result"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetMeOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* Media (`send_photo` / `send_document` / `send_video` /
  `send_audio`) accepts a **file\_id or HTTPS URL** only — local
  file uploads via multipart aren't supported here (the legacy
  implementation didn't actually upload bytes either, despite the
  docstring claim — we preserve the simpler behavior).
* Failures (Telegram `ok: false`, HTTP errors, exceptions) all
  surface as `success=False` + `error` carrying the upstream
  `description` field where available.
* `delete_message` only works for messages younger than 48 hours
  (Telegram constraint).

## Related integrations

<CardGroup cols={3}>
  <Card title="Pinterest" href="/integrations/tools/pinterest" />

  <Card title="Slack" href="/integrations/tools/slack" />

  <Card title="WhatsApp" href="/integrations/tools/whatsapp" />
</CardGroup>

## Links

* [Telegram Bot](https://core.telegram.org/bots/api)