Telegram
Service domainMESSAGING
Arcade Optimized
Arcade.dev LLM tools for Telegram
Author:Arcade
Version:
1.1.0Auth:No authentication required
7tools
7require secrets
Telegram Toolkit
Arcade toolkit for interacting with the Telegram Bot API, enabling bots to send messages, receive updates, stream audio, and manage interactive inline keyboards from LLM-driven workflows.
Capabilities
- Bot identity & chat metadata: Retrieve the bot's own profile and fetch metadata (type, title, description, member count) for any chat, group, or channel the bot has joined.
- Messaging: Send text messages to private chats, groups, or channels; attach inline keyboard buttons to capture structured user responses and auto-collapse the keyboard on selection.
- Message retrieval: Fetch unacknowledged private-chat updates via
getUpdates; filtered to 1:1 chats only (groups/channels excluded for injection safety); offset management controls acknowledgement. - Long-polling for responses: Bounded long-polls to wait for a new incoming message or an inline button tap without re-sending content; resume across timeout windows using a
next_offsetcursor. Incompatible with active webhooks. - Text-to-speech audio: Convert text to MP3 via OpenAI TTS and deliver it as a Telegram audio message in one step.
Secrets
This toolkit requires two secrets injected at runtime.
TELEGRAM_BOT_TOKEN
The authentication token for your Telegram bot, issued by @BotFather on Telegram. To obtain one: open a chat with @BotFather, send /newbot, follow the prompts to name your bot, and copy the token it returns (format: 123456789:ABCdef...). Keep this value secret — anyone with it can send and receive messages as your bot. See Telegram Bot API docs for details.
OPENAI_API_KEY
An API key for the OpenAI platform, required by the SendTtsAudio tool to call OpenAI's text-to-speech API. Generate one in the OpenAI API keys dashboard under your account. The key must belong to an account with access to the tts-1 or equivalent TTS model; ensure your account has an active billing method and sufficient quota. Use a key scoped to your project where possible to limit blast radius if leaked.
Configure secrets in Arcade at https://docs.arcade.dev/en/guides/create-tools/tool-basics/create-tool-secrets or manage them directly at https://api.arcade.dev/dashboard/auth/secrets.
Available tools(7)
7 of 7 tools
Operations
Behavior
| Tool name | Description | Secrets | |
|---|---|---|---|
Get metadata about a Telegram chat, group, or channel.
Returns information including the chat type, title, description, and member count.
The bot must be a member of the chat to retrieve its information. | 2 | ||
Get recent private-chat messages sent to the bot via Telegram's getUpdates API.
Returns messages from private (1:1) chats only. Group and channel messages are
excluded for security — any group member could inject content into the response.
Only pending (unacknowledged) updates are returned.
The limit parameter controls how many raw Telegram updates are fetched, not how
many messages are returned. After filtering to private-chat messages for the
requested chat_id, the result may contain fewer items. has_more indicates whether
more updates exist on the server, not whether more messages exist for this chat.
Note: This retrieves updates delivered to the bot, not the full history of a chat.
Passing a non-zero offset permanently confirms all earlier updates — they cannot be
retrieved again. Returns newest messages last. | 2 | ||
Send a text message to a Telegram chat, group, or channel.
The bot must be a member of the target chat or have permission to send messages to the
specified channel.
When the message asks the recipient a question, prefer attaching the possible answers as inline
`buttons` rather than asking in free text. With buttons and wait_for_response (the default),
this call waits for the user to tap one and returns it as `selected_option` — the toolkit
collapses the keyboard to the choice automatically, so you do not react to the tap yourself. If
no tap arrives in the wait window, `timed_out` is true and `next_offset` lets you resume waiting
without re-sending. Reserve a plain (button-less) message for statements or genuinely
open-ended questions. | 2 | ||
Convert text to speech using OpenAI TTS and send it as an audio message on Telegram.
Generates an MP3 audio file from the provided text using OpenAI's text-to-speech API,
then sends it to the specified Telegram chat. | 2 | ||
Resume waiting for an inline-button tap on a message that was already sent with buttons.
Use this only to keep waiting after an earlier attempt's wait window elapsed without a tap — it
does NOT send anything. It is a bounded long-poll on Telegram's getUpdates: it waits a short
window for a tap on the given message, and when one happens the toolkit acknowledges it and
collapses the keyboard to the chosen option (no agent round-trip), returning the choice as
selected_option. If the window elapses with no tap, it returns timed_out=true with a
next_offset cursor to resume from again.
Cannot be used while the bot has an active webhook, because getUpdates and webhooks are
mutually exclusive. | 2 | ||
Wait for the next new message in a Telegram private chat, returning as soon as one arrives.
This is a bounded long-poll built on Telegram's getUpdates: it waits up to timeout_seconds
for a new message in the given chat. If one or more arrive, they are returned immediately
with timed_out set to false. If the budget elapses with nothing, it returns an empty message
list with timed_out set to true and a next_offset cursor, so you can call again with that
next_offset to keep waiting.
On the first call, leave offset at 0: the tool skips any already-pending backlog and waits for
messages that arrive after the call begins. To read pending messages without waiting, use
get_messages instead.
Returns messages from private (1:1) chats only — group and channel messages are excluded for
security, since any group member could inject content. This tool cannot be used while the bot
has an active webhook, because getUpdates and webhooks are mutually exclusive. | 2 | ||
Get information about the Telegram bot.
Returns the bot's identity including its ID, username, and capabilities. | 2 |
Last updated on