Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Telegram

Scalekit connector
Open markdown

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.

Tools
23
What they doRead · write · destructive
7 · 14 · 27 read14 write2 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .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.

  4. Authorize a user and make your first call

    quickstart.mts
    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)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Telegram credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • telegram_bot_getGet the connected bot's own Telegram account: checks that the bot token works.Read-only

    Get Bot Info

    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.

    Inputs

    This tool takes no inputs.

  • telegram_chat_administrators_listList the administrators of a group, supergroup or channel.Read-only

    List Chat Administrators

    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.

    Inputs

    chat_idstringrequired
    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_botsboolean
    Set true to also include other bots that are administrators. By default only human admins and the current bot are returned. Example: true
  • telegram_chat_getGet up-to-date details of one chat by ID or @username.Read-only

    Get Chat

    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.

    Inputs

    chat_idstringrequired
    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
  • telegram_chat_member_count_getGet the number of members in a chat.Read-only

    Get Chat Member Count

    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.

    Inputs

    chat_idstringrequired
    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
  • telegram_chat_member_getGet one user's membership in a chat.Read-only

    Get Chat Member

    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.

    Inputs

    chat_idstringrequired
    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_idintegerrequired
    Numeric Telegram user ID of the member, for example from message.from.id in telegram_updates_get results. Example: 123456789
  • telegram_commands_getGet the bot's command list for a scope and language.Read-only

    Get Bot Commands

    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.

    Inputs

    language_codestring
    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
    scopeobject
    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"}
  • telegram_webhook_info_getGet the bot's current webhook status.Read-only

    Get Webhook Info

    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.

    Inputs

    This tool takes no inputs.

  • telegram_callback_query_answerAnswer a button press on an inline keyboard, optionally showing the user a short notification or alert.Write

    Answer Callback Query

    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.

    • Idempotent

    Inputs

    callback_query_idstringrequired
    ID of the callback query to answer, from callback_query.id in an update. Example: 4382bfdwdsb323b2d9
    cache_timeinteger
    Seconds the client may cache this answer. Telegram uses 0 when omitted. Example: 60
    show_alertboolean
    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
    textstring
    Notification text shown to the user, 0-200 characters. Omit to show nothing. Example: Approved
    urlstring
    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