KosmoKrator

communication

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.

7 functions 5 read 2 write Bearer token auth
Submit Telegram feedback View package source

Telegram CLI Setup

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

# 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 use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

KeyEnv varTypeRequiredLabel
access_token TELEGRAM_ACCESS_TOKEN Secret secret yes Bot Token
url TELEGRAM_URL URL url no API Base URL

Call Telegram Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

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

Use the provider shortcut form for shorter human-facing commands.

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

Agent Discovery Commands

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

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

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Telegram.

telegram.telegram_send_message

Write write

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.

Parameters
chat_id, text, parse_mode, reply_to_message_id, disable_notification

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

telegram.telegram_list_updates

Read read

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.

Parameters
offset, limit, timeout

Generic CLI call

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

Provider shortcut

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

telegram.telegram_get_me

Read read

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

Parameters
none

Generic CLI call

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

Provider shortcut

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

telegram.telegram_list_chats

Read read

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.

Parameters
limit

Generic CLI call

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

Provider shortcut

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

telegram.telegram_get_chat

Read read

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

Parameters
chat_id

Generic CLI call

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

Provider shortcut

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

telegram.telegram_send_photo

Write write

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.

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

Generic CLI 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

Provider 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

Read read

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

Parameters
none

Generic CLI call

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

Provider 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

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.

Operation
Write write
Schema command
kosmo integrations:schema telegram.telegram_send_message --json
ParameterTypeRequiredDescription
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

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.

Operation
Read read
Schema command
kosmo integrations:schema telegram.telegram_list_updates --json
ParameterTypeRequiredDescription
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

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

Operation
Read read
Schema command
kosmo integrations:schema telegram.telegram_get_me --json
ParameterTypeRequiredDescription
No parameters.

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.

Operation
Read read
Schema command
kosmo integrations:schema telegram.telegram_list_chats --json
ParameterTypeRequiredDescription
limit integer no Maximum number of updates to scan for chats (1–100). Default: 100.

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.

Operation
Read read
Schema command
kosmo integrations:schema telegram.telegram_get_chat --json
ParameterTypeRequiredDescription
chat_id string yes Unique identifier for the target chat or @username of the target channel.

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.

Operation
Write write
Schema command
kosmo integrations:schema telegram.telegram_send_photo --json
ParameterTypeRequiredDescription
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

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

Operation
Read read
Schema command
kosmo integrations:schema telegram.telegram_get_current_user --json
ParameterTypeRequiredDescription
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.