> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Telegram

The Telegram connector lets your AI agent act in each user's Telegram account. Each user connects their own Telegram API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 23 tools.

**Authentication:** API Key
**Categories:** Communication
**Tools:** 23: 7 read, 14 write, 2 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=TELEGRAM)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Telegram connection

   In **AgentKit > Connections**, create a Telegram connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'telegram'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Telegram:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'telegram_bot_get',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "telegram"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Telegram:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="telegram_bot_get",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Telegram credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'telegram_bot_get',
  toolInput: {},
  connector: 'telegram',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="telegram_bot_get",
    tool_input={},
    connection_name="telegram",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `telegram_bot_get`

Get Bot Info · Read-only

Get the connected bot's own Telegram account: checks that the bot token works.
Returns the bot's user id, first_name, username, and flags such as can_join_groups and can_read_all_group_messages.
Use this first to confirm the connection or to learn the bot's @username.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `telegram_chat_administrators_list`

List Chat Administrators · Read-only

List the administrators of a group, supergroup or channel.
Returns an array of ChatMember objects with each admin's user, status (creator or administrator), custom title and rights.
Use this to find who can moderate a chat. Use telegram_chat_member_get to check one user.
Other bots are left out unless return_bots is true.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the group, supergroup or channel: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `return_bots` (`boolean`, optional): Set true to also include other bots that are administrators. By default only human admins and the current bot are returned. Example: true

Example input: `{"chat_id":"<chat_id>"}`

### `telegram_chat_get`

Get Chat · Read-only

Get up-to-date details of one chat by ID or @username.
Returns a ChatFullInfo object: id, type (private, group, supergroup or channel), title or name, username, description, invite_link, pinned_message, permissions and more.
Use this to look up a chat. Use telegram_chat_member_count_get for the member count and telegram_chat_administrators_list for its admins.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890

Example input: `{"chat_id":"<chat_id>"}`

### `telegram_chat_member_count_get`

Get Chat Member Count · Read-only

Get the number of members in a chat.
Returns an integer.
Use this for the size of a group or channel. Use telegram_chat_get for the chat's other details.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890

Example input: `{"chat_id":"<chat_id>"}`

### `telegram_chat_member_get`

Get Chat Member · Read-only

Get one user's membership in a chat.
Returns a ChatMember object with the user and their status (creator, administrator, member, restricted, left or kicked), plus admin rights or restrictions where they apply.
Use this to check whether a user is in a chat or is an admin. The bot must be an admin of the chat to read other users reliably.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `user_id` (`integer`, required): Numeric Telegram user ID of the member, for example from message.from.id in telegram_updates_get results. Example: 123456789

Example input: `{"chat_id":"<chat_id>","user_id":123456789}`

### `telegram_commands_get`

Get Bot Commands · Read-only

Get the bot's command list for a scope and language.
Returns an array of BotCommand objects with command and description; empty when none are set.
Use this before telegram_commands_set to see what is configured.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `language_code` (`string`, optional): Two-letter ISO 639-1 language code; the commands are read for users with that app language. Omit for users with no language-specific list. Example: es
- `scope` (`object`, optional): Which users the command list applies to, as a BotCommandScope object with a type: default, all_private_chats, all_group_chats, all_chat_administrators, chat, chat_administrators or chat_member (the chat types also need chat_id, and chat_member needs user_id). Telegram uses default when omitted. Example: {"type": "all_private_chats"}

Example input: `{}`

### `telegram_webhook_info_get`

Get Webhook Info · Read-only

Get the bot's current webhook status.
Returns a WebhookInfo object: url (empty when the bot uses polling), pending_update_count, last_error_date and last_error_message, max_connections and allowed_updates.
Use this to check whether a webhook is set and whether deliveries are failing.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `telegram_callback_query_answer`

Answer Callback Query · Write

Answer a button press on an inline keyboard, optionally showing the user a short notification or alert.
Returns true on success.
Call this for every callback_query update from telegram_updates_get, or the user's client keeps showing a progress indicator on the button.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `callback_query_id` (`string`, required): ID of the callback query to answer, from callback_query.id in an update. Example: 4382bfdwdsb323b2d9
- `cache_time` (`integer`, optional): Seconds the client may cache this answer. Telegram uses 0 when omitted. Example: 60
- `show_alert` (`boolean`, optional): Set true to show the text as an alert the user must dismiss instead of a notification at the top of the chat. Example: true
- `text` (`string`, optional): Notification text shown to the user, 0-200 characters. Omit to show nothing. Example: Approved
- `url` (`string`, optional): URL the user's client opens, for a game button or a t.me/<bot_username>?start=<parameter> link that opens the bot. Example: https://t.me/my_bot?start=welcome

Example input: `{"callback_query_id":"<callback_query_id>"}`

### `telegram_chat_action_send`

Send Chat Action · Write

Show a status such as typing or uploading a photo next to the bot's name in a chat for up to 5 seconds.
Returns true on success.
Use this before a slow reply so the user sees the bot is working. Not supported in channels.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `action` (`string`, required): Status to show: typing for text, upload_photo, record_video or upload_video, record_voice or upload_voice, upload_document, choose_sticker, find_location, record_video_note or upload_video_note. Example: typing. One of: `typing`, `upload_photo`, `record_video`, `upload_video`, `record_voice`, `upload_voice`, `upload_document`, `choose_sticker`, `find_location`, `record_video_note`, `upload_video_note`.
- `chat_id` (`string`, required): Identifier of a private chat, group or supergroup: the numeric chat ID (negative for groups, e.g. -1001234567890 for a supergroup) or the public @username of a supergroup. A channel does not show this status. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7

Example input: `{"action":"typing","chat_id":"<chat_id>"}`

### `telegram_commands_set`

Set Bot Commands · Write

Replace the bot's command list (the menu users see when they type /) for a scope and language.
Returns true on success.
Use telegram_commands_get to read the current list first; this call overwrites it.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `commands` (`array`, required): Commands to set, at most 100. Each has a command (1-32 characters: lowercase letters, digits and underscores, without the leading /) and a description (1-256 characters). Example: [{"command": "start", "description": "Start the bot"}, {"command": "status", "description": "Show service status"}]
- `language_code` (`string`, optional): Two-letter ISO 639-1 language code; the commands apply for users with that app language. Omit for users with no language-specific list. Example: es
- `scope` (`object`, optional): Which users the command list applies to, as a BotCommandScope object with a type: default, all_private_chats, all_group_chats, all_chat_administrators, chat, chat_administrators or chat_member (the chat types also need chat_id, and chat_member needs user_id). Telegram uses default when omitted. Example: {"type": "all_private_chats"}

Example input: `{"commands":[{"command":"start","description":"Start the bot"},{"command":"status","description":"Show service status"}]}`

### `telegram_document_send`

Send Document · Write

Send a file as a document attachment to a chat, from a public HTTPS URL or from the file_id of a file already on Telegram, with an optional caption.
Returns the sent Message, including its message_id and the document's file_id, file_name and mime_type.
Use this for PDFs and other files. Use telegram_photo_send to show an image inline.
Uploading a file from the device is not supported; pass a URL or file_id. By URL, only PDF and ZIP files work; a GIF or other file by URL is rejected, so pass its file_id instead.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the target chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `document` (`string`, required): The file: an HTTP(S) URL Telegram downloads (at most 20 MB by URL; only PDF and ZIP files work this way, a GIF link is rejected), or the file_id of a file already on Telegram servers. Example: https://example.com/reports/q3.pdf
- `caption` (`string`, optional): Caption shown under the document, 0-1024 characters after formatting is parsed. Example: Q3 report attached
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `parse_mode` (`string`, optional): How Telegram formats the caption: MarkdownV2, HTML or the legacy Markdown. Omit to send plain text. In MarkdownV2 the characters _ * [ ] ( ) ~ ` > # + - = | { } . ! must be escaped with a backslash when they are not formatting. Example: HTML. One of: `MarkdownV2`, `HTML`, `Markdown`.
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true
- `reply_markup` (`object`, optional): Buttons to attach, as a Telegram reply markup object. Most common is an inline keyboard: inline_keyboard is a list of button rows, each button has a text and either a url or a callback_data string that comes back to the bot as a callback query. Other shapes show a custom reply keyboard (keyboard), remove one (remove_keyboard true) or ask the user to reply (force_reply true). Example: {"inline_keyboard": [[{"text": "Open docs", "url": "https://example.com"}, {"text": "Approve", "callback_data": "approve_42"}]]}
- `reply_parameters` (`object`, optional): Makes the message a reply to another message, as a Telegram ReplyParameters object. It needs the message_id of the message to reply to; add chat_id to reply to a message in another chat, and allow_sending_without_reply true to send anyway if that message is gone. Example: {"message_id": 42}

Example input: `{"chat_id":"<chat_id>","document":"<document>"}`

### `telegram_message_copy`

Copy Message · Write

Send a copy of a message to another chat without a link to the original, optionally with a new caption.
Returns the message_id of the new message.
Use this to repost content as the bot. Use telegram_message_forward to show the forwarded-from header.
Service, paid media, giveaway and invoice messages cannot be copied.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat to send the copy to: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `from_chat_id` (`string`, required): Chat where the original message was sent: a numeric chat ID or a public @username. Example: -1009876543210
- `message_id` (`integer`, required): ID of the message to copy, in the from_chat_id chat. Example: 42
- `caption` (`string`, optional): New caption for a media message, 0-1024 characters. Omit to keep the original caption. Example: Reposted from the ops channel
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `parse_mode` (`string`, optional): How Telegram formats the new caption: MarkdownV2, HTML or the legacy Markdown. Omit to send plain text. In MarkdownV2 the characters _ * [ ] ( ) ~ ` > # + - = | { } . ! must be escaped with a backslash when they are not formatting. Example: HTML. One of: `MarkdownV2`, `HTML`, `Markdown`.
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true
- `reply_markup` (`object`, optional): Buttons to attach, as a Telegram reply markup object. Most common is an inline keyboard: inline_keyboard is a list of button rows, each button has a text and either a url or a callback_data string that comes back to the bot as a callback query. Other shapes show a custom reply keyboard (keyboard), remove one (remove_keyboard true) or ask the user to reply (force_reply true). Example: {"inline_keyboard": [[{"text": "Open docs", "url": "https://example.com"}, {"text": "Approve", "callback_data": "approve_42"}]]}
- `reply_parameters` (`object`, optional): Makes the message a reply to another message, as a Telegram ReplyParameters object. It needs the message_id of the message to reply to; add chat_id to reply to a message in another chat, and allow_sending_without_reply true to send anyway if that message is gone. Example: {"message_id": 42}

Example input: `{"chat_id":"<chat_id>","from_chat_id":"<from_chat_id>","message_id":42}`

### `telegram_message_edit_text`

Edit Message Text · Write

Replace the text of a text message the bot sent earlier, and optionally its inline keyboard.
Returns the edited Message, or true when an inline message was edited.
Use this to update a status message in place. Use telegram_message_send to post a new message.
Identify the message by chat_id plus message_id, or by inline_message_id for messages sent via inline mode.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `text` (`string`, required): New text of the message, 1-4096 characters after formatting is parsed. Example: Deployment finished: 3 services updated.
- `chat_id` (`string`, optional): Chat that holds the message: a numeric chat ID or a public @username. Required unless inline_message_id is given. Example: -1001234567890
- `inline_message_id` (`string`, optional): Identifier of a message sent via the bot's inline mode, from a chosen_inline_result or callback_query update. Use instead of chat_id and message_id. Example: AAAAAKxyz123
- `link_preview_options` (`object`, optional): Controls the link preview Telegram generates for the first URL in the text, as a LinkPreviewOptions object. Set is_disabled true to turn the preview off; url, prefer_small_media, prefer_large_media and show_above_text adjust it. Example: {"is_disabled": true}
- `message_id` (`integer`, optional): ID of the message to edit, from the message_id returned when it was sent. Required unless inline_message_id is given. Example: 42
- `parse_mode` (`string`, optional): How Telegram formats the new text: MarkdownV2, HTML or the legacy Markdown. Omit to send plain text. In MarkdownV2 the characters _ * [ ] ( ) ~ ` > # + - = | { } . ! must be escaped with a backslash when they are not formatting. Example: HTML. One of: `MarkdownV2`, `HTML`, `Markdown`.
- `reply_markup` (`object`, optional): New inline keyboard for the message, as an InlineKeyboardMarkup object (a list of button rows). Omit to remove the current inline keyboard. Example: {"inline_keyboard": [[{"text": "Done", "callback_data": "done_42"}]]}

Example input: `{"text":"<text>"}`

### `telegram_message_forward`

Forward Message · Write

Forward a message from one chat to another, keeping a link to the original sender.
Returns the new Message in the target chat.
Use this when the recipients should see where the message came from. Use telegram_message_copy to resend it without the forwarded-from header.
Service messages and messages with protected content cannot be forwarded.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat to forward the message to: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `from_chat_id` (`string`, required): Chat where the original message was sent: a numeric chat ID or a public @username. Example: -1009876543210
- `message_id` (`integer`, required): ID of the message to forward, in the from_chat_id chat. Example: 42
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true

Example input: `{"chat_id":"<chat_id>","from_chat_id":"<from_chat_id>","message_id":42}`

### `telegram_message_pin`

Pin Message · Write

Pin a message in a chat.
Returns true on success.
Use telegram_message_unpin to remove a pin. In groups the bot needs the can_pin_messages admin right, in channels can_edit_messages; in private chats any message can be pinned.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `message_id` (`integer`, required): ID of the message to pin. Example: 42
- `disable_notification` (`boolean`, optional): Set true to pin without notifying chat members. Notifications are always off in channels and private chats. Example: true

Example input: `{"chat_id":"<chat_id>","message_id":42}`

### `telegram_message_send`

Send Message · Write

Send a text message from the bot to a user, group, supergroup or channel, optionally formatted and with inline buttons.
Returns the sent Message, including its message_id, chat and date.
Use this for text. Use telegram_photo_send, telegram_document_send or telegram_poll_send for media and polls; use telegram_message_edit_text to change a message already sent.
The bot can message a user only after that user has started a chat with it.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the target chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `text` (`string`, required): Text of the message, 1-4096 characters after formatting is parsed. Example: Deployment finished successfully.
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `link_preview_options` (`object`, optional): Controls the link preview Telegram generates for the first URL in the text, as a LinkPreviewOptions object. Set is_disabled true to turn the preview off; url, prefer_small_media, prefer_large_media and show_above_text adjust it. Example: {"is_disabled": true}
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `parse_mode` (`string`, optional): How Telegram formats the text: MarkdownV2, HTML or the legacy Markdown. Omit to send plain text. In MarkdownV2 the characters _ * [ ] ( ) ~ ` > # + - = | { } . ! must be escaped with a backslash when they are not formatting. Example: HTML. One of: `MarkdownV2`, `HTML`, `Markdown`.
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true
- `reply_markup` (`object`, optional): Buttons to attach, as a Telegram reply markup object. Most common is an inline keyboard: inline_keyboard is a list of button rows, each button has a text and either a url or a callback_data string that comes back to the bot as a callback query. Other shapes show a custom reply keyboard (keyboard), remove one (remove_keyboard true) or ask the user to reply (force_reply true). Example: {"inline_keyboard": [[{"text": "Open docs", "url": "https://example.com"}, {"text": "Approve", "callback_data": "approve_42"}]]}
- `reply_parameters` (`object`, optional): Makes the message a reply to another message, as a Telegram ReplyParameters object. It needs the message_id of the message to reply to; add chat_id to reply to a message in another chat, and allow_sending_without_reply true to send anyway if that message is gone. Example: {"message_id": 42}

Example input: `{"chat_id":"<chat_id>","text":"<text>"}`

### `telegram_message_unpin`

Unpin Message · Write

Remove a message from a chat's pinned messages; with no message_id, unpin the most recently pinned one.
Returns true on success.
Use telegram_message_pin to pin. The bot needs the same admin rights as for pinning.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `message_id` (`integer`, optional): ID of the pinned message to unpin. Omit to unpin the most recently pinned message. Example: 42

Example input: `{"chat_id":"<chat_id>"}`

### `telegram_photo_send`

Send Photo · Write

Send a photo to a chat from a public HTTPS URL or from the file_id of a photo already on Telegram, with an optional caption.
Returns the sent Message, including its message_id and the photo sizes with their file_id values.
Use this for images shown inline. Use telegram_document_send to send a file as an attachment.
Uploading a file from the device is not supported; pass a URL or file_id.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the target chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `photo` (`string`, required): The photo: an HTTP(S) URL Telegram downloads (at most 5 MB for photos fetched by URL), or the file_id of a photo already on Telegram servers (from an earlier message). Example: https://example.com/images/chart.png
- `caption` (`string`, optional): Caption shown under the photo, 0-1024 characters after formatting is parsed. Example: Q3 report attached
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `has_spoiler` (`boolean`, optional): Set true to cover the photo with a spoiler animation until it is tapped. Example: true
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `parse_mode` (`string`, optional): How Telegram formats the caption: MarkdownV2, HTML or the legacy Markdown. Omit to send plain text. In MarkdownV2 the characters _ * [ ] ( ) ~ ` > # + - = | { } . ! must be escaped with a backslash when they are not formatting. Example: HTML. One of: `MarkdownV2`, `HTML`, `Markdown`.
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true
- `reply_markup` (`object`, optional): Buttons to attach, as a Telegram reply markup object. Most common is an inline keyboard: inline_keyboard is a list of button rows, each button has a text and either a url or a callback_data string that comes back to the bot as a callback query. Other shapes show a custom reply keyboard (keyboard), remove one (remove_keyboard true) or ask the user to reply (force_reply true). Example: {"inline_keyboard": [[{"text": "Open docs", "url": "https://example.com"}, {"text": "Approve", "callback_data": "approve_42"}]]}
- `reply_parameters` (`object`, optional): Makes the message a reply to another message, as a Telegram ReplyParameters object. It needs the message_id of the message to reply to; add chat_id to reply to a message in another chat, and allow_sending_without_reply true to send anyway if that message is gone. Example: {"message_id": 42}

Example input: `{"chat_id":"<chat_id>","photo":"<photo>"}`

### `telegram_poll_send`

Send Poll · Write

Send a native poll or quiz to a chat.
Returns the sent Message, with the poll's id, question and options.
Use this to collect votes. Use telegram_message_send for plain text.
A quiz needs type quiz and correct_option_ids.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `chat_id` (`string`, required): Identifier of the target chat: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `options` (`array`, required): Answer options, 1-12 of them. Each is an object with the option text (1-100 characters). Example: [{"text": "Tuesday"}, {"text": "Thursday"}]
- `question` (`string`, required): Poll question, 1-300 characters. Example: Which day works for the team offsite?
- `allows_multiple_answers` (`boolean`, optional): Set true to let voters pick more than one option. Example: true
- `close_date` (`integer`, optional): Unix timestamp when the poll closes, 5 to 2628000 seconds in the future. Do not combine with open_period. Example: 1767225600
- `correct_option_ids` (`array`, optional): 0-based indexes of the correct options, in increasing order; required for a quiz. Example: [1]
- `disable_notification` (`boolean`, optional): Set true to send the message silently: recipients get a notification with no sound. Example: true
- `explanation` (`string`, optional): Text shown when a quiz answer is wrong or the lamp icon is tapped, 0-200 characters. Example: The offsite is on Thursdays.
- `is_anonymous` (`boolean`, optional): Whether votes are anonymous. Telegram uses true when omitted. Example: false
- `message_thread_id` (`integer`, optional): Forum topic to post in, for forum supergroups (and private chats with topics enabled) only. It is the message_thread_id of a message in that topic. Example: 7
- `open_period` (`integer`, optional): Seconds the poll stays open after it is sent, 5-2628000. Do not combine with close_date. Example: 3600
- `protect_content` (`boolean`, optional): Set true to stop recipients from forwarding or saving the sent message. Example: true
- `reply_markup` (`object`, optional): Buttons to attach, as a Telegram reply markup object. Most common is an inline keyboard: inline_keyboard is a list of button rows, each button has a text and either a url or a callback_data string that comes back to the bot as a callback query. Other shapes show a custom reply keyboard (keyboard), remove one (remove_keyboard true) or ask the user to reply (force_reply true). Example: {"inline_keyboard": [[{"text": "Open docs", "url": "https://example.com"}, {"text": "Approve", "callback_data": "approve_42"}]]}
- `reply_parameters` (`object`, optional): Makes the message a reply to another message, as a Telegram ReplyParameters object. It needs the message_id of the message to reply to; add chat_id to reply to a message in another chat, and allow_sending_without_reply true to send anyway if that message is gone. Example: {"message_id": 42}
- `type` (`string`, optional): Poll type: regular or quiz. Telegram uses regular when omitted. Example: quiz. One of: `regular`, `quiz`.

Example input: `{"chat_id":"<chat_id>","options":[{"text":"Tuesday"},{"text":"Thursday"}],"question":"<question>"}`

### `telegram_updates_get`

Get Updates · Write

Fetch incoming updates for the bot (new messages, edited messages, channel posts, button presses, poll answers) by polling.
Returns an array of Update objects, each with an update_id and one payload such as message or callback_query.
Use this to read what users sent the bot and to find chat IDs. Fails while a webhook is set; call telegram_webhook_delete first.
Passing offset confirms and removes every update below it, so they are not returned again. Telegram keeps unconfirmed updates for 24 hours.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `allowed_updates` (`array`, optional): Update types to receive, for example message, edited_message, channel_post, callback_query, poll_answer, my_chat_member, chat_member. An empty list means every type except chat_member, message_reaction and message_reaction_count. Omit to keep the previous setting. Example: ["message", "callback_query"]
- `limit` (`integer`, optional): Maximum number of updates to return, 1-100. Telegram uses 100 when omitted. Example: 20
- `offset` (`integer`, optional): ID of the first update to return: one more than the highest update_id already processed. Updates below it are confirmed and deleted from the queue. A negative value returns the last -offset updates. Omit to get the earliest unconfirmed updates. Example: 123456790
- `timeout` (`integer`, optional): Long-polling timeout in seconds. 0 (the default) returns at once; keep it short, at most 25, so the call finishes before the 30-second tool timeout. Example: 0

Example input: `{}`

### `telegram_webhook_set`

Set Webhook · Write

Register an HTTPS URL that Telegram posts every new update to, replacing any webhook already set.
Returns true on success.
Use this to receive updates by push. While a webhook is set, telegram_updates_get fails; use telegram_webhook_delete to switch back and telegram_webhook_info_get to check delivery.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `url` (`string`, required): HTTPS URL that receives updates as JSON POST requests. Only ports 443, 80, 88 and 8443 are supported. An empty string removes the webhook. Example: https://example.com/telegram/webhook
- `allowed_updates` (`array`, optional): Update types to deliver, for example message, edited_message, channel_post, callback_query, poll_answer, my_chat_member, chat_member. An empty list means every type except chat_member, message_reaction and message_reaction_count. Omit to keep the previous setting. Example: ["message", "callback_query"]
- `drop_pending_updates` (`boolean`, optional): Set true to discard updates that are waiting to be delivered. Example: true
- `ip_address` (`string`, optional): Fixed IP address to send webhook requests to instead of resolving the URL's host through DNS. Example: 203.0.113.10
- `max_connections` (`integer`, optional): Maximum simultaneous HTTPS connections Telegram opens to the webhook, 1-100. Telegram uses 40 when omitted. Example: 40
- `secret_token` (`string`, optional): Secret, 1-256 characters of A-Z, a-z, 0-9, _ and -, that Telegram sends in the X-Telegram-Bot-Api-Secret-Token header of every webhook request so your endpoint can verify it. Example: my_webhook_secret_2026

Example input: `{"url":"<url>"}`

### `telegram_message_delete`

Delete Message · Destructive

Delete a message from a chat.
Returns true on success.
A message can be deleted only within 48 hours of being sent. The bot can always delete its own messages in private chats and groups; deleting other people's messages needs admin rights (can_delete_messages in supergroups and channels).

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `chat_id` (`string`, required): Identifier of the chat that holds the message: the numeric chat ID (negative for groups and channels, e.g. -1001234567890 for a supergroup or channel) or a public @username of a channel or supergroup. Get numeric IDs from message.chat.id in telegram_updates_get results or from telegram_chat_get. Example: -1001234567890
- `message_id` (`integer`, required): ID of the message to delete. Example: 42

Example input: `{"chat_id":"<chat_id>","message_id":42}`

### `telegram_webhook_delete`

Delete Webhook · Destructive

Remove the bot's webhook so updates can be read with telegram_updates_get again.
Returns true on success.
Use telegram_webhook_set to register a webhook.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `drop_pending_updates` (`boolean`, optional): Set true to also discard updates that are waiting to be delivered. Example: true

Example input: `{}`

## Related

Other Communication connectors ([all 132](/agentkit/connectors/?category=communication)):

- [Gmail](/agentkit/connectors/gmail/): Scalekit connector, OAuth, 48 tools
- [Slack](/agentkit/connectors/slack/): Scalekit connector, OAuth, 96 tools
- [Google Calendar](/agentkit/connectors/googlecalendar/): Scalekit connector, OAuth, 30 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
