KosmoKrator

communication

Telegram Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Telegram KosmoKrator integration.

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

Lua Namespace

Agents call this integration through app.integrations.telegram.*. Use lua_read_doc("integrations.telegram") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Telegram — Lua API Reference

send_message

Send a text message to a Telegram chat.

Parameters

NameTypeRequiredDescription
chat_idstringyesUnique identifier for the target chat or @username of the target channel.
textstringyesText of the message to send.
parse_modestringnoParse mode: Markdown, MarkdownV2, or HTML.
reply_to_message_idintegernoID of the original message if this is a reply.
disable_notificationbooleannoSend the message silently. Default: false.

Response

Returns the sent message object:

FieldTypeDescription
message_idintegerUnique message identifier.
dateintegerSend date as Unix timestamp.
chatobjectChat the message was sent to.
fromobjectBot info that sent the message.
textstringThe message text.

Example

local msg = app.integrations.telegram.send_message({
  chat_id = "123456789",
  text = "Hello from the AI agent! 🤖",
  parse_mode = "Markdown"
})

print("Sent message ID: " .. msg.message_id)

list_updates

Get incoming updates (messages, callbacks, etc.) for the bot.

Parameters

NameTypeRequiredDescription
offsetintegernoIdentifier of the first update to return. Must be one greater than the highest previously received update_id.
limitintegernoNumber of updates to fetch (1–100). Default: 100.
timeoutintegernoLong polling timeout in seconds. Default: 0.

Response

Returns an array of update objects:

FieldTypeDescription
update_idintegerUnique update identifier.
messageobjectNew incoming message (if present).
edited_messageobjectEdited message (if present).
channel_postobjectNew channel post (if present).
callback_queryobjectCallback query (if present).

Example

local updates = app.integrations.telegram.list_updates({
  limit = 10
})

for _, update in ipairs(updates) do
  if update.message then
    print("From: " .. update.message.from.first_name .. " — " .. update.message.text)
  end
end

get_me

Get information about the authenticated Telegram bot.

Parameters

None.

Response

Returns a bot user object:

FieldTypeDescription
idintegerBot user ID.
is_botbooleanAlways true for bots.
first_namestringBot display name.
usernamestringBot @username.
can_join_groupsbooleanWhether the bot can join groups.
can_read_all_group_messagesbooleanWhether the bot receives all group messages.

Example

local bot = app.integrations.telegram.get_me({})

print("Bot: @" .. bot.username .. " (" .. bot.first_name .. ")")

list_chats

List recent chats the bot has interacted with.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of updates to scan for chats (1–100). Default: 100.

Response

Returns an array of chat summary objects:

FieldTypeDescription
idintegerChat ID.
typestringChat type: private, group, supergroup, or channel.
titlestringChat title (for groups/channels).
usernamestringChat @username (if available).
first_namestringFirst name (for private chats).
last_namestringLast name (for private chats).

Example

local chats = app.integrations.telegram.list_chats({
  limit = 50
})

for _, chat in ipairs(chats) do
  local name = chat.title or (chat.first_name or "Unknown")
  print(name .. " (" .. chat.type .. ") — " .. chat.id)
end

get_chat

Get information about a specific Telegram chat.

Parameters

NameTypeRequiredDescription
chat_idstringyesUnique identifier for the target chat or @username of the target channel.

Response

Returns a chat object:

FieldTypeDescription
idintegerChat ID.
typestringChat type: private, group, supergroup, or channel.
titlestringChat title (for groups/channels).
usernamestringChat @username (if available).
first_namestringFirst name (for private chats).
last_namestringLast name (for private chats).
descriptionstringChat description (for groups/channels).
member_countintegerNumber of members (for groups/channels).

Example

local chat = app.integrations.telegram.get_chat({
  chat_id = "-1001234567890"
})

print("Chat: " .. (chat.title or "DM") .. " (" .. chat.type .. ")")
if chat.member_count then
  print("Members: " .. chat.member_count)
end

send_photo

Send a photo to a Telegram chat.

Parameters

NameTypeRequiredDescription
chat_idstringyesUnique identifier for the target chat or @username of the target channel.
photostringyesURL of the photo or file_id of a photo already on Telegram servers.
captionstringnoPhoto caption (0–1024 characters).
parse_modestringnoParse mode for the caption: Markdown, MarkdownV2, or HTML.
reply_to_message_idintegernoID of the original message if this is a reply.
disable_notificationbooleannoSend silently. Default: false.

Response

Returns the sent message object with photo array.

Example

local msg = app.integrations.telegram.send_photo({
  chat_id = "123456789",
  photo = "https://example.com/photo.jpg",
  caption = "Check this out! 📸",
  parse_mode = "Markdown"
})

print("Sent photo, message ID: " .. msg.message_id)

get_current_user

Get the authenticated bot user profile.

Parameters

None.

Response

Returns a bot user object (same as get_me):

FieldTypeDescription
idintegerBot user ID.
is_botbooleanAlways true.
first_namestringBot display name.
usernamestringBot @username.

Example

local bot = app.integrations.telegram.get_current_user({})

print("Bot: @" .. bot.username .. " (" .. bot.first_name .. ")")

Multi-Account Usage

If you have multiple Telegram bots configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.telegram.send_message({chat_id = "123", text = "Hello"})

-- Explicit default (portable across setups)
app.integrations.telegram.default.send_message({chat_id = "123", text = "Hello"})

-- Named accounts
app.integrations.telegram.sales_bot.send_message({chat_id = "123", text = "Hello"})
app.integrations.telegram.support_bot.send_message({chat_id = "123", text = "Hello"})

All functions are identical across accounts — only the bot token differs.

Raw agent markdown 
# Telegram — Lua API Reference

## send_message

Send a text message to a Telegram chat.

### Parameters

| Name | 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: Markdown, MarkdownV2, or HTML. |
| `reply_to_message_id` | integer | no | ID of the original message if this is a reply. |
| `disable_notification` | boolean | no | Send the message silently. Default: false. |

### Response

Returns the sent message object:

| Field | Type | Description |
|-------|------|-------------|
| `message_id` | integer | Unique message identifier. |
| `date` | integer | Send date as Unix timestamp. |
| `chat` | object | Chat the message was sent to. |
| `from` | object | Bot info that sent the message. |
| `text` | string | The message text. |

### Example

```lua
local msg = app.integrations.telegram.send_message({
  chat_id = "123456789",
  text = "Hello from the AI agent! 🤖",
  parse_mode = "Markdown"
})

print("Sent message ID: " .. msg.message_id)
```

---

## list_updates

Get incoming updates (messages, callbacks, etc.) for the bot.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `offset` | integer | no | Identifier of the first update to return. Must be one greater 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. |

### Response

Returns an array of update objects:

| Field | Type | Description |
|-------|------|-------------|
| `update_id` | integer | Unique update identifier. |
| `message` | object | New incoming message (if present). |
| `edited_message` | object | Edited message (if present). |
| `channel_post` | object | New channel post (if present). |
| `callback_query` | object | Callback query (if present). |

### Example

```lua
local updates = app.integrations.telegram.list_updates({
  limit = 10
})

for _, update in ipairs(updates) do
  if update.message then
    print("From: " .. update.message.from.first_name .. " — " .. update.message.text)
  end
end
```

---

## get_me

Get information about the authenticated Telegram bot.

### Parameters

None.

### Response

Returns a bot user object:

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Bot user ID. |
| `is_bot` | boolean | Always true for bots. |
| `first_name` | string | Bot display name. |
| `username` | string | Bot @username. |
| `can_join_groups` | boolean | Whether the bot can join groups. |
| `can_read_all_group_messages` | boolean | Whether the bot receives all group messages. |

### Example

```lua
local bot = app.integrations.telegram.get_me({})

print("Bot: @" .. bot.username .. " (" .. bot.first_name .. ")")
```

---

## list_chats

List recent chats the bot has interacted with.

### Parameters

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

### Response

Returns an array of chat summary objects:

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Chat ID. |
| `type` | string | Chat type: private, group, supergroup, or channel. |
| `title` | string | Chat title (for groups/channels). |
| `username` | string | Chat @username (if available). |
| `first_name` | string | First name (for private chats). |
| `last_name` | string | Last name (for private chats). |

### Example

```lua
local chats = app.integrations.telegram.list_chats({
  limit = 50
})

for _, chat in ipairs(chats) do
  local name = chat.title or (chat.first_name or "Unknown")
  print(name .. " (" .. chat.type .. ") — " .. chat.id)
end
```

---

## get_chat

Get information about a specific Telegram chat.

### Parameters

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

### Response

Returns a chat object:

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Chat ID. |
| `type` | string | Chat type: private, group, supergroup, or channel. |
| `title` | string | Chat title (for groups/channels). |
| `username` | string | Chat @username (if available). |
| `first_name` | string | First name (for private chats). |
| `last_name` | string | Last name (for private chats). |
| `description` | string | Chat description (for groups/channels). |
| `member_count` | integer | Number of members (for groups/channels). |

### Example

```lua
local chat = app.integrations.telegram.get_chat({
  chat_id = "-1001234567890"
})

print("Chat: " .. (chat.title or "DM") .. " (" .. chat.type .. ")")
if chat.member_count then
  print("Members: " .. chat.member_count)
end
```

---

## send_photo

Send a photo to a Telegram chat.

### Parameters

| Name | 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 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 | ID of the original message if this is a reply. |
| `disable_notification` | boolean | no | Send silently. Default: false. |

### Response

Returns the sent message object with photo array.

### Example

```lua
local msg = app.integrations.telegram.send_photo({
  chat_id = "123456789",
  photo = "https://example.com/photo.jpg",
  caption = "Check this out! 📸",
  parse_mode = "Markdown"
})

print("Sent photo, message ID: " .. msg.message_id)
```

---

## get_current_user

Get the authenticated bot user profile.

### Parameters

None.

### Response

Returns a bot user object (same as get_me):

| Field | Type | Description |
|-------|------|-------------|
| `id` | integer | Bot user ID. |
| `is_bot` | boolean | Always true. |
| `first_name` | string | Bot display name. |
| `username` | string | Bot @username. |

### Example

```lua
local bot = app.integrations.telegram.get_current_user({})

print("Bot: @" .. bot.username .. " (" .. bot.first_name .. ")")
```

---

## Multi-Account Usage

If you have multiple Telegram bots configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.telegram.send_message({chat_id = "123", text = "Hello"})

-- Explicit default (portable across setups)
app.integrations.telegram.default.send_message({chat_id = "123", text = "Hello"})

-- Named accounts
app.integrations.telegram.sales_bot.send_message({chat_id = "123", text = "Hello"})
app.integrations.telegram.support_bot.send_message({chat_id = "123", text = "Hello"})
```

All functions are identical across accounts — only the bot token differs.

Metadata-Derived Lua Example

local result = app.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
})
print(result)

Functions

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
Full name
telegram.telegram_send_message
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_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
Full name
telegram.telegram_list_updates
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_get_me

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

Operation
Read read
Full name
telegram.telegram_get_me
ParameterTypeRequiredDescription
No parameters.

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
Full name
telegram.telegram_list_chats
ParameterTypeRequiredDescription
limit integer no Maximum number of updates to scan for chats (1–100). Default: 100.

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
Full name
telegram.telegram_get_chat
ParameterTypeRequiredDescription
chat_id string yes Unique identifier for the target chat or @username of the target channel.

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
Full name
telegram.telegram_send_photo
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_get_current_user

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

Operation
Read read
Full name
telegram.telegram_get_current_user
ParameterTypeRequiredDescription
No parameters.