Telegram
Arcade.dev LLM tools for Telegram
2.0.1Arcade toolkit for building bots on Telegram. Enables LLMs to send messages, poll for replies, handle inline-button interactions, retrieve chat metadata, and deliver TTS audio — all via a Telegram bot identity.
Capabilities
- Bot identity & chat inspection: Retrieve the bot's own profile and capabilities, or fetch metadata (type, title, description, member count) for any chat, group, or channel the bot has joined.
- Messaging: Send text messages to any chat, group, or channel the bot can access; attach inline buttons to structured questions and optionally block until the user taps one.
- Long-poll message receiving: Read unacknowledged messages from private 1:1 chats via
getUpdates; supports pagination withnext_offset, bounded wait windows, andtimed_outsignals for resuming. Group/channel messages are excluded for security. - Inline-button resumption: Resume waiting for a button tap on a previously sent message without re-sending it; bounded long-poll acknowledges the tap and collapses the keyboard automatically.
- Text-to-speech audio: Convert text to speech via OpenAI TTS (MP3) and deliver it as an audio message in a Telegram chat.
Note:
getUpdates-based tools (ReceiveMessages,ReceiveButtonPress) are mutually exclusive with Telegram webhooks — the bot must not have an active webhook when using them.
Secrets
TELEGRAM_BOT_TOKEN — The authentication token for your Telegram bot. Create a bot by messaging @BotFather on Telegram and sending /newbot. BotFather will issue a token in the format 123456789:ABCdef.... This token authenticates all API calls made on behalf of the bot and should be kept private. See the Telegram Bot API docs for details.
OPENAI_API_KEY — An OpenAI API key used to call the TTS endpoint (tts-1 or similar model) when generating audio with SendTtsAudio. Generate one in the OpenAI API keys dashboard under your OpenAI account. The key must belong to an account with access to the Audio/TTS API; usage is billed to that account.
Store both secrets in Arcade via https://docs.arcade.dev/en/guides/create-tools/tool-basics/create-tool-secrets (or manage them at https://api.arcade.dev/dashboard/auth/secrets).
Available tools(6)
| 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. | 1 | ||
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. | 1 | ||
Receive the messages a private chat sent the bot that it hasn't received yet.
This is built on Telegram's getUpdates. Messages already waiting come back at once, oldest
first; when none is waiting, it waits up to timeout_seconds for one to arrive. Returned
messages are acknowledged, so later calls don't return them again, and updates from other
chats that the read passes over are acknowledged and dropped too. has_more is true when more
updates may be waiting: call again with next_offset to read them. If nothing arrives in time,
it returns an empty message list with timed_out set to true and a next_offset to keep waiting
from.
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. | 1 | ||
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. | 1 | ||
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 | ||
Get information about the Telegram bot.
Returns the bot's identity including its ID, username, and capabilities. | 1 |