Telegram (Bot)¶

The Telegram bot integration connects the agent to a Telegram bot account created with @BotFather. The agent can send and edit messages and media, run polls, manage group members and admins, handle invite links and join requests, configure the bot profile, and a long-polling listener turns incoming messages into events the agent reacts to.

For messaging from your own personal Telegram account instead of a bot account, see Telegram (User).

Requirements¶

Requirement	Details
Telegram account	Used once to talk to @BotFather and create the bot
Bot token	Generated by @BotFather with `/newbot`, in the form `123456:ABC...`
Shared bot (optional)	`/telegram_bot invite` connects a hosted bot when `TELEGRAM_SHARED_BOT_TOKEN` and `TELEGRAM_SHARED_BOT_USERNAME` are set
Network access	CraftBot calls `api.telegram.org` over HTTPS

Setup¶

Open Telegram and start a chat with @BotFather.
Send /newbot, then follow the prompts to pick a display name and a username ending in bot.
BotFather replies with a token (123456:ABC...). Copy it.
In CraftBot, open Settings → Integrations → Telegram Bot, paste the token into Bot Token, and connect. From chat, /telegram_bot login <bot_token> does the same thing.
In Telegram, send /start to your bot so it has a chat to reply into.
Verify with /telegram_bot status. It shows the connected bot username.

/telegram_bot invite connects a hosted shared bot instead of your own, when the deployment has one configured. /telegram_bot logout removes the credential and stops the listener.

How it connects¶

Authentication. Every API call sends the bot token in the request URL to api.telegram.org. At login CraftBot validates the token with getMe and stores the token and resolved username in the credential store as telegram_bot.json. See Credentials.

Long-polling listener. While connected, CraftBot calls getUpdates in a loop with a 30-second long-poll timeout, requesting only message updates. On startup it drains any backlog once so old messages do not replay, then dispatches each new message exactly once. Only messages that carry text are forwarded. After a poll error the listener waits 5 seconds and retries.

A bot is not a personal inbox. A bot has no self-chat and cannot message a user who has not first sent /start to it. If you want the agent to message you directly on Telegram, use Telegram (User) instead.

Identity formats. A chat_id is either a numeric ID (negative for groups, supergroups, and channels) or an @username that Telegram resolves server-side. Display names are not accepted.

Replies. When the agent responds to a Telegram event, it sends a message back to the originating chat.

What the agent can do¶

The 70 Telegram bot actions are grouped into action sets (telegram_messages, telegram_media, telegram_chats, telegram_bot_config, telegram_callbacks, telegram_webhooks) that the agent loads as a task needs them. See Actions and action sets.

Messages¶

Action	Purpose
`send_telegram_bot_message`	Send a text message to a Telegram chat via bot
`send_telegram_text_message`	Send a text message with full options (reply markup, silent send, no preview)
`edit_telegram_message_text`	Edit the text of a message sent by the bot
`edit_telegram_message_caption`	Edit the caption of a media message
`edit_telegram_message_reply_markup`	Edit only the reply markup of a message
`delete_telegram_message`	Delete a single message sent by or visible to the bot
`delete_telegram_messages`	Delete multiple messages in a chat in one call
`copy_telegram_message`	Copy a message to another chat without the "forwarded from" header
`forward_telegram_message`	Forward a message via bot
`forward_telegram_messages`	Forward multiple messages of any kind
`pin_telegram_message`	Pin a message in a chat
`unpin_telegram_message`	Unpin a specific message, or the most recent if omitted
`unpin_all_telegram_messages`	Clear the list of pinned messages in a chat
`set_telegram_message_reaction`	Set or remove emoji reactions on a message
`send_telegram_chat_action`	Show a "typing" or "upload photo" indicator to the user
`get_telegram_updates`	Get incoming updates (messages) for the Telegram bot

Media¶

Action	Purpose
`send_telegram_photo`	Send a photo to a Telegram chat via bot
`send_telegram_document`	Send a document to a Telegram chat via bot
`send_telegram_video`	Send a video file via bot
`send_telegram_audio`	Send an audio file (music) via bot
`send_telegram_voice`	Send a voice message (OGG opus) via bot
`send_telegram_video_note`	Send a rounded square video note (short circular video)
`send_telegram_animation`	Send an animation (GIF or MPEG-4 without sound)
`send_telegram_sticker`	Send a sticker
`send_telegram_location`	Send a geographic location
`send_telegram_venue`	Send a venue with name and address
`send_telegram_contact`	Send a phone contact card
`send_telegram_dice`	Send an animated dice or emoji-game
`send_telegram_poll`	Send a poll to a chat
`stop_telegram_poll`	Stop an active poll
`send_telegram_media_group`	Send photos, videos, audios, or documents as an album
`get_telegram_file`	Get file metadata (including `file_path`) for a `file_id`
`download_telegram_file`	Resolve a `file_id` and stream the bytes to a local path

Chats and members¶

Action	Purpose
`get_telegram_chat`	Get information about a Telegram chat via bot
`get_telegram_chat_members_count`	Get the chat member count
`get_telegram_chat_administrators`	List the administrators of a chat
`get_telegram_chat_member`	Get information about a single member of a chat
`ban_telegram_chat_member`	Ban a user from a group, supergroup, or channel
`unban_telegram_chat_member`	Unban a previously banned user
`restrict_telegram_chat_member`	Restrict a user in a supergroup with specific permissions
`promote_telegram_chat_member`	Promote or demote a user (pass `False` to remove a privilege)
`set_telegram_chat_administrator_custom_title`	Set a custom title for an administrator
`set_telegram_chat_permissions`	Set default chat permissions for all non-admin members
`set_telegram_chat_title`	Change the title of a chat
`set_telegram_chat_description`	Change the description of a group, supergroup, or channel
`delete_telegram_chat_photo`	Delete the photo of a group, supergroup, or channel
`leave_telegram_chat`	Make the bot leave a chat
`search_telegram_contact`	Search for a contact by name from the bot's recent chat history

Invite links and join requests¶

Action	Purpose
`export_telegram_chat_invite_link`	Generate a new primary invite link, revoking the previous primary
`create_telegram_chat_invite_link`	Create an additional invite link without revoking the primary
`edit_telegram_chat_invite_link`	Edit an existing non-primary invite link
`revoke_telegram_chat_invite_link`	Revoke an invite link
`approve_telegram_chat_join_request`	Approve a pending chat join request
`decline_telegram_chat_join_request`	Decline a pending chat join request

Bot configuration¶

Action	Purpose
`set_telegram_my_commands`	Set the list of bot commands shown in the Telegram UI
`get_telegram_my_commands`	Get the current list of bot commands
`delete_telegram_my_commands`	Delete the bot commands list for a given scope
`set_telegram_my_description`	Set the bot's long description shown on the empty-chat screen
`get_telegram_my_description`	Get the bot's current description
`set_telegram_my_short_description`	Set the bot's short description shown on its profile page
`set_telegram_my_name`	Set the bot's display name
`set_telegram_chat_menu_button`	Set the menu button shown in a specific chat or the default
`get_telegram_chat_menu_button`	Get the menu button for a chat or the default
`set_telegram_my_default_administrator_rights`	Set default admin rights requested when the bot is added to a group or channel
`get_telegram_my_default_administrator_rights`	Get the default admin rights
`get_telegram_bot_info`	Get bot info (`getMe`)

Callback queries¶

Action	Purpose
`answer_telegram_callback_query`	Answer an inline-keyboard callback query with optional notification text or an alert

Webhooks¶

Action	Purpose
`set_telegram_webhook`	Register a webhook URL to receive updates via HTTPS POST
`delete_telegram_webhook`	Remove the registered webhook and return to long polling
`get_telegram_webhook_info`	Get the current webhook registration info

Example requests¶

Send "deploy finished" to my Telegram chat 123456789.

Post a poll in the team group asking which day works for the offsite, options Mon, Wed, Fri.

Someone requested to join the announcements channel. Approve them.

Ban the user who posted spam in the support group and delete their recent messages.

Set the bot's command list to /start, /help, and /status with short descriptions.

Send the file report.pdf from the workspace to chat 123456789 with a caption.

Configuration¶

The setting lives in Settings → Integrations → Telegram Bot and is stored in telegram_bot_config.json next to the credential. The listener re-reads it on every incoming message, so changes apply without reconnecting.

Setting	Type	Default	Effect
Private DMs only (`self_messages_only`)	checkbox	off	When on, only messages from 1:1 private chats reach the agent. Group, supergroup, and channel messages are dropped before dispatch

Troubleshooting¶

Symptom	Likely cause	Fix
"Invalid bot token" at login	Token is wrong, or was revoked in @BotFather	Copy the token again from @BotFather and run `/telegram_bot login <token>`
"chat not found" when messaging a user	The user has not sent `/start` to the bot, or the bot is not in the target chat	Ask the person to start the bot first. Retrying the same call does not help
Bot does not see messages in a group	Privacy Mode is on, so the bot only receives messages addressed to it	Disable Privacy Mode for the bot in @BotFather, then re-add it to the group
`get_telegram_updates` fails with a 409 conflict	A webhook is registered, which is mutually exclusive with polling	Run `delete_telegram_webhook`, then poll again
Agent stops reacting to group messages	`self_messages_only` is on	Turn it off in Settings → Integrations → Telegram Bot
`/telegram_bot invite` reports the shared bot is not configured	`TELEGRAM_SHARED_BOT_TOKEN` or `TELEGRAM_SHARED_BOT_USERNAME` is unset	Use `/telegram_bot login <token>` with your own bot from @BotFather

Next¶

Telegram (User): connect your own account over MTProto for personal messaging
Credentials: where the bot token is stored and how /cred status reports it
Triggers: how listener events become tasks