Telegram Connection

Telegram Connection

Use this skill for the organization-scoped Telegram bot integration: bot setup details, inbound message semantics, Telegram hook scope, and Telegram-specific runtime tool purposes.

Telegram configuration

User-supplied configuration fields:

• botToken: Telegram BotFather token. Secret.
• botUsername: optional bot username, with or without @.
• apiBaseUrl: optional Telegram API base URL override.

Backoffice generates the webhook secret during configuration.

Setup procedure:

1. Tell the user how to register a bot with Telegram:
   • Open a chat with the verified @BotFather account in Telegram.
   • Send /newbot and follow the prompts to choose a display name and a unique username.
   • Copy the bot token BotFather returns and enter it in the Backoffice Telegram connection.
   • Treat the bot token like a password and regenerate it in BotFather if it is exposed.
2. Save the connection configuration. Backoffice generates a cryptographically secure webhook secret, derives the organization-scoped webhook URL, and registers both with Telegram.

The stored secret must match the X-Telegram-Bot-Api-Secret-Token header Telegram sends to the webhook.

Telegram events

Message received

Fires when the Telegram webhook receives a bot message for the organization.

Catalog identity:

• source: telegram
• eventType: message.received

Before parsing payloads, inspect the catalog schema with codemode:

const descriptor = await events.catalogGet({ source: "telegram", eventType: "message.received" });

Payload fields:

• messageId: Telegram message id as a string.
• chatId: Telegram chat id as a string. Use this with Telegram chat tools.
• fromUserId: Telegram user id when available, otherwise null.
• text: message text when available, otherwise null.
• attachments: optional attachment metadata. Voice notes and files are represented here, not as raw Telegram message.voice fields.

When reading a queued ingest hook through internal.hooksGet({ fragment: "automations", hookId }), the normalized Telegram payload is inside the event envelope:

const entry = await internal.hooksGet({ fragment: "automations", hookId });
const payload = entry?.payload?.payload;
const attachments = payload?.attachments ?? [];

Actor:

• scope: external
• source: telegram
• type: chat
• id: the Telegram chat id

Common automation pattern: filter on event.source === "telegram" and event.eventType === "message.received", then route slash commands, plain text, or attachments.

Capability configured

Fires after Telegram is configured for an organization for the first time. Use it to bootstrap Telegram-specific automation state.

Catalog identity:

• source: telegram
• eventType: capability.configured

Hook scope: telegram.

Telegram tools

Telegram tools can:

• send chat messages;
• send typing indicators;
• edit existing messages;
• resolve Telegram file metadata;
• download Telegram files.

Use codemode first. The telegram provider methods are sendMessage, sendChatAction, editMessage, getFile, and downloadFile.

Example:

await telegram.sendMessage({ chatId, text: "Hello", parseMode: "Markdown" });