Documentation / @agentick/connector-telegram

@agentick/connector-telegram

Telegram platform adapter for the Agentick connector system. Bridge a Telegram bot to an agent session.

Install

pnpm add @agentick/connector-telegram grammy

grammy is a peer dependency.

Usage

import { createConnector } from "@agentick/connector";
import { TelegramPlatform } from "@agentick/connector-telegram";

const connector = createConnector(
  client,
  new TelegramPlatform({
    token: process.env.TELEGRAM_BOT_TOKEN!,
    allowedUsers: [parseInt(process.env.TELEGRAM_USER_ID!)],
  }),
  {
    sessionId: "main",
    contentPolicy: "summarized",
    deliveryStrategy: "debounced",
    debounceMs: 2000,
  },
);

await connector.start();

Options

interface TelegramConnectorOptions {
  token: string;
  allowedUsers?: number[];
  chatId?: number;
  confirmationStyle?: "inline-keyboard" | "text";
}

token — Telegram bot token from @BotFather.

allowedUsers — Whitelist of Telegram user IDs. Empty array allows all users. Get your ID from @userinfobot.

chatId — Specific chat to use. If omitted, auto-detects from the first incoming message.

confirmationStyle — How tool confirmations are presented. Default: "inline-keyboard".

Tool Confirmations

Inline Keyboard (default)

Sends a message with Approve/Deny buttons. The user taps a button, the confirmation resolves.

Text-based

Sends a text prompt. The next message from the user is parsed as the confirmation response. Supports natural language — "yes but skip tests" is approved with the full text as reason.

Recommended Config

For a conversational bot experience:

{
  contentPolicy: "summarized",   // collapse tool calls into brief summaries
  deliveryStrategy: "debounced", // wait for a pause before sending
  debounceMs: 2000,
}

For a long-running agent that reports results:

{
  contentPolicy: "text-only",    // only deliver text, no tool noise
  deliveryStrategy: "on-idle",   // deliver only when execution completes
}

Gateway Plugin

TelegramPlugin connects a bot directly to the gateway without a separate connector process:

import { createGateway } from "@agentick/gateway";
import { TelegramPlugin } from "@agentick/connector-telegram";

const gateway = createGateway({
  apps: { myApp },
  defaultApp: "myApp",
  plugins: [
    new TelegramPlugin({
      token: process.env.TELEGRAM_BOT_TOKEN!,
      allowedUsers: [12345678],
    }),
  ],
});

The plugin receives messages from Telegram, routes them to sessions, and delivers responses back. Registers a telegram:send method for outbound messaging from tool handlers.

Gateway Config File

With the gateway config system, Telegram options live in agentick.config.json:

{
  "connectors": {
    "telegram": {
      "token": "${env:TELEGRAM_BOT_TOKEN}",
      "allowedUsers": [12345678],
      "chatId": 987654321
    }
  }
}

Read it from the config store:

import { getConfig } from "@agentick/gateway";

const telegram = getConfig().get("connectors")?.telegram;
if (telegram) {
  gateway.use(new TelegramPlugin(telegram));
}

Importing @agentick/connector-telegram augments the gateway's ConnectorConfigs type, so get("connectors")?.telegram is fully typed.

Exports

export { TelegramPlugin, type TelegramPluginOptions } from "./telegram-plugin.js";
export { escapeMarkdownV2 } from "./telegram-format.js";
export { parseTextConfirmation, formatConfirmationMessage } from "./confirmation-utils.js";

Classes

• TelegramPlugin

Interfaces

• TelegramPluginOptions

Functions

• escapeMarkdownV2
• formatConfirmationMessage
• parseTextConfirmation