Can I use Telegram as a CLI?

Yes. KosmoKrator exposes a Telegram CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Telegram through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Telegram tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Telegram credentials stored?

Telegram credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Telegram MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Telegram CLI for AI Agents

Use the Telegram CLI from KosmoKrator to call Telegram tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Telegram CLI Setup

Telegram can be configured headlessly with `kosmokrator integrations:configure telegram`.

Install, configure, and verify

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure telegram --set access_token="$TELEGRAM_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor telegram --json
kosmokrator integrations:status --json

Credentials

Authentication type: Bearer token bearer_token. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`access_token`	`TELEGRAM_ACCESS_TOKEN`	Secret `secret`	yes	Bot Token
`url`	`TELEGRAM_URL`	URL `url`	no	API Base URL

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call

kosmo integrations:call telegram.telegram_send_message '{"chat_id":"example_chat_id","text":"example_text","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

Provider shortcut

kosmo integrations:telegram telegram_send_message '{"chat_id":"example_chat_id","text":"example_text","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands

kosmo integrations:docs telegram --json
kosmo integrations:docs telegram.telegram_send_message --json
kosmo integrations:schema telegram.telegram_send_message --json
kosmo integrations:search "Telegram" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

`telegram.telegram_send_message`

Send a text message to a Telegram chat. Provide the chat_id and message text. The chat_id can be a numeric ID or @channelusername. Supports optional parse_mode (Markdown, MarkdownV2, HTML) and other formatting options.

Write write

Parameters: chat_id, text, parse_mode, reply_to_message_id, disable_notification

Generic call

kosmo integrations:call telegram.telegram_send_message '{"chat_id":"example_chat_id","text":"example_text","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

Shortcut

kosmo integrations:telegram telegram_send_message '{"chat_id":"example_chat_id","text":"example_text","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

`telegram.telegram_list_updates`

Get incoming updates (messages, callback queries, inline queries, etc.) for the Telegram bot. Use offset to acknowledge previously received updates. Returns an array of update objects.

Read read

Parameters: offset, limit, timeout

Generic call

kosmo integrations:call telegram.telegram_list_updates '{"offset":1,"limit":1,"timeout":1}' --json

Shortcut

kosmo integrations:telegram telegram_list_updates '{"offset":1,"limit":1,"timeout":1}' --json

`telegram.telegram_get_me`

Get information about the authenticated Telegram bot. Returns the bot ID, username, display name, and capability flags.

Read read

Parameters: none

Generic call

kosmo integrations:call telegram.telegram_get_me '{}' --json

Shortcut

kosmo integrations:telegram telegram_get_me '{}' --json

`telegram.telegram_list_chats`

List recent chats the bot has interacted with. Since Telegram Bot API does not have a native list-chats endpoint, this fetches recent updates and extracts unique chats. Returns chat IDs, types, and titles.

Read read

Parameters: limit

Generic call

kosmo integrations:call telegram.telegram_list_chats '{"limit":1}' --json

Shortcut

kosmo integrations:telegram telegram_list_chats '{"limit":1}' --json

`telegram.telegram_get_chat`

Get information about a specific Telegram chat by its ID or @username. Returns chat type, title, description, member count, and other metadata.

Read read

Parameters: chat_id

Generic call

kosmo integrations:call telegram.telegram_get_chat '{"chat_id":"example_chat_id"}' --json

Shortcut

kosmo integrations:telegram telegram_get_chat '{"chat_id":"example_chat_id"}' --json

`telegram.telegram_send_photo`

Send a photo to a Telegram chat. Provide the chat_id and a photo URL or file_id. Supports optional caption with formatting and other options.

Write write

Parameters: chat_id, photo, caption, parse_mode, reply_to_message_id, disable_notification

Generic call

kosmo integrations:call telegram.telegram_send_photo '{"chat_id":"example_chat_id","photo":"example_photo","caption":"example_caption","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

Shortcut

kosmo integrations:telegram telegram_send_photo '{"chat_id":"example_chat_id","photo":"example_photo","caption":"example_caption","parse_mode":"example_parse_mode","reply_to_message_id":1,"disable_notification":true}' --json

`telegram.telegram_get_current_user`

Get the profile of the currently authenticated Telegram bot. Returns bot ID, username, display name, and capability flags.

Read read

Parameters: none

Generic call

kosmo integrations:call telegram.telegram_get_current_user '{}' --json

Shortcut

kosmo integrations:telegram telegram_get_current_user '{}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

telegram.telegram_send_message 5 parameters

Schema command

kosmo integrations:schema telegram.telegram_send_message --json

Parameter	Type	Required	Description
`chat_id`	string	yes	Unique identifier for the target chat or @username of the target channel.
`text`	string	yes	Text of the message to send.
`parse_mode`	string	no	Parse mode for the message: Markdown, MarkdownV2, or HTML.
`reply_to_message_id`	integer	no	If the message is a reply, ID of the original message.
`disable_notification`	boolean	no	Send the message silently. Default: false.

telegram.telegram_list_updates 3 parameters

Schema command

kosmo integrations:schema telegram.telegram_list_updates --json

Parameter	Type	Required	Description
`offset`	integer	no	Identifier of the first update to return. Must be greater by one than the highest previously received update_id.
`limit`	integer	no	Number of updates to fetch (1–100). Default: 100.
`timeout`	integer	no	Long polling timeout in seconds. Default: 0 (no long polling).

telegram.telegram_get_me 0 parameters

Schema command

kosmo integrations:schema telegram.telegram_get_me --json

Parameter	Type	Required	Description
No parameters.

telegram.telegram_list_chats 1 parameters

Schema command

kosmo integrations:schema telegram.telegram_list_chats --json

Parameter	Type	Required	Description
`limit`	integer	no	Maximum number of updates to scan for chats (1–100). Default: 100.

telegram.telegram_get_chat 1 parameters

Schema command

kosmo integrations:schema telegram.telegram_get_chat --json

Parameter	Type	Required	Description
`chat_id`	string	yes	Unique identifier for the target chat or @username of the target channel.

telegram.telegram_send_photo 6 parameters

Schema command

kosmo integrations:schema telegram.telegram_send_photo --json

Parameter	Type	Required	Description
`chat_id`	string	yes	Unique identifier for the target chat or @username of the target channel.
`photo`	string	yes	URL of the photo to send, or file_id of a photo already on Telegram servers.
`caption`	string	no	Photo caption (0–1024 characters).
`parse_mode`	string	no	Parse mode for the caption: Markdown, MarkdownV2, or HTML.
`reply_to_message_id`	integer	no	If the message is a reply, ID of the original message.
`disable_notification`	boolean	no	Send the message silently. Default: false.

telegram.telegram_get_current_user 0 parameters

Schema command

kosmo integrations:schema telegram.telegram_get_current_user --json

Parameter	Type	Required	Description
No parameters.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.