A Telegram MCP where the bot token never leaks
Connect one bot token from BotFather and Telegram messaging, media, polls, chat management, and update polling become workflow steps for visual automations and AI agents. Telegram's API puts the token inside the request URL itself, so the connector treats secrecy as a first-class job: the token never appears in workflow outputs, error messages, or logs.
What the Telegram MCP connector does
The Telegram connector for Mattering Automations is 40 nodes across the official Bot API: send, edit, delete, forward, and copy messages, send photos, documents, video, audio, and albums by URL or file_id, send locations, contacts, polls, and typing indicators, read chat information, members, and administrators, manage titles, descriptions, and pinned messages, moderate with ban, unban, and restrict, create and revoke invite links, poll for incoming updates, manage the bot's webhook, look up file metadata, answer inline keyboard button presses, and manage the bot's command menu.
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and any MCP-capable assistant can use them, alongside Matter, the AI assistant built into the platform. An assistant can post a formatted update to the team channel, run a poll and read back the final counts, or check who administers a group, without anyone opening Telegram.
Because Mattering is a work platform rather than middleware, Telegram activity lands somewhere useful by default: a workflow failure can announce itself in the team channel with a link back to the run, and a weekly poll's final vote counts can be written into a Mattering database next to the rest of the team's records, all on one canvas.
Trust boundaries are explicit. Telegram's API carries the bot token in the URL of every call, a place credentials do not normally live, and the connector is built around that fact: the token is scrubbed from every output, error message, and log the platform produces. The four operations with no undo (deleting a message, banning a member, leaving a chat, and revoking an invite link) are flagged destructive so they are deliberate steps, never accidents.
One connection, three surfaces
- Visual automations. Drag Telegram nodes onto the canvas and wire them to triggers, conditions, and other apps.
- AI agents, yours or ours. These nodes speak MCP, the open protocol, so Claude, ChatGPT, and any MCP-capable assistant can use them, and Matter, the agent built into the platform, uses them natively.
- The whole platform. Combine with native tasks, projects, and other connectors, no middleware in between.
Every Telegram node, ready to drop on the canvas
40 nodes, generated from the connector itself so this list always matches what ships. Expand a category to browse.
Read and query nodes 9
Telegram: Get Bot Commands
Read the bot's current command list for a scope and language. Returns an empty array when no list is set for that scope.
Telegram: Get Bot Info
Return the bot's own identity: id, username, name, and capability flags such as can_join_groups. Takes no parameters, so it doubles as the credential health check: a bad token returns 401 Unauthorized before anything else runs.
Telegram: Get Chat
Fetch full information about a chat (ChatFullInfo): title, type, description, invite link, pinned message, permissions, and member count-adjacent settings.
Telegram: Get Chat Administrators
List all administrators of a group or channel (excluding other bots), each with their admin rights.
Telegram: Get Chat Member
Fetch one member of a chat: their user object plus status (creator, administrator, member, restricted, left, or kicked) and any admin or restriction details.
Telegram: Get Chat Member Count
Return the number of members in a chat as a plain integer.
Telegram: Get File Info
Look up a file by file_id and return its metadata: size, unique id, and the server-side file_path (valid for at least one hour, files up to 20 MB). Security note: Telegram's actual download URL embeds the bot token in its path, so this node deliberately does NOT construct it; it returns the metadata plus a note explaining that. Handle downloads outside the automation with your own tooling if you truly need the bytes.
Telegram: Get Updates
Poll for incoming updates (messages, button presses, member changes) since the last confirmed offset. This is the polling trigger surface: run it on a schedule, loop over data.result, and pass the highest update_id plus 1 back as offset next run. Honest constraints: passing an offset CONFIRMS earlier updates (they will not be returned again), and getUpdates returns a 409 Conflict while a webhook is set: the two intake modes are mutually exclusive per bot.
Telegram: Get Webhook Info
Inspect the bot's current webhook state: the registered URL, pending update count, and the last delivery error if any. An empty url means the bot is in getUpdates polling mode.
Action nodes 31
Telegram: Answer Callback Query
Acknowledge an inline-keyboard button press (callback query), optionally showing a toast or alert to the user. Every callback query should be answered, or the user's client shows a loading spinner for up to a minute. Ephemeral: nothing persists in the chat.
Telegram: Ban Chat Member
Ban a user from a group, supergroup, or channel: they are removed and cannot return on their own until unbanned. With revoke_messages, ALL their messages in the chat are deleted permanently, which cannot be undone even after an unban. The bot must be an admin with can_restrict_members.
Telegram: Copy Message
Copy a message to another chat without the 'Forwarded from' attribution, optionally replacing the caption. Returns only the new message id (as a MessageId object), not the full Message.
Telegram: Create Chat Invite Link
Create an additional named invite link for a chat, with optional expiry, member limit, or join-request approval. Does not touch the chat's primary link. The bot must be an admin with can_invite_users.
Telegram: Delete Bot Commands
Delete the bot's command list for a scope and language, so users in that scope fall back to a higher-level list. Recoverable by setting a list again with Set Bot Commands.
Telegram: Delete Message
Permanently delete a message from a chat. There is no undo and no trash: the message is gone for everyone. Bots can delete their own messages within 48 hours, and other users' messages only in groups where the bot is an admin with can_delete_messages.
Telegram: Delete Webhook
Remove the bot's webhook and return to getUpdates polling mode. Reversible by setting the webhook again; with drop_pending_updates the queued updates are discarded permanently.
Telegram: Edit Message Text
Edit the text (and optionally the inline keyboard) of a message the bot sent earlier, identified by chat_id plus message_id. Useful for live status messages that update in place instead of flooding the chat. Bots can edit their own messages up to 48 hours after sending.
Telegram: Export Primary Invite Link
Generate a NEW primary invite link for the chat and return it as a string. Warning: every call REVOKES the previous primary link, so anyone holding the old one loses access to it. To read the current link without rotating it use Get Chat; to mint extra links without touching the primary use Create Chat Invite Link.
Telegram: Forward Message
Forward a message from one chat to another, keeping the 'Forwarded from' attribution header. Use Copy Message instead when the copy should look like a fresh message without attribution.
Telegram: Leave Chat
Make the bot leave a group, supergroup, or channel. The bot cannot rejoin on its own: a human admin must re-add it and restore its admin rights, so treat this as one-way from the automation's point of view.
Telegram: Pin Chat Message
Pin a message to the top of a chat. In groups the bot needs the can_pin_messages admin right. Reversible with the Unpin node.
Telegram: Restrict Chat Member
Restrict what a supergroup member can do (mute, block media, and so on) by passing a ChatPermissions object, optionally until a date. Reversible: pass all permissions as true to lift the restrictions. The bot must be an admin with can_restrict_members.
Telegram: Revoke Chat Invite Link
Revoke an invite link so it stops working immediately. The revocation itself cannot be undone: everyone holding that link loses it, and a replacement is a NEW link that must be re-shared. Revoking the primary link auto-generates a fresh primary.
Telegram: Send Audio
Send an audio file (MP3 or M4A, shown in the music player) by HTTP URL or file_id, with optional performer and title metadata. Uploading local file bytes is not supported; URL-fetched audio is capped at 20 MB.
Telegram: Send Chat Action
Show a status indicator in the chat (typing, upload_photo, upload_document, and similar) for up to 5 seconds or until the bot's next message. Purely cosmetic and self-expiring; useful before a slow step so users see the bot is working.
Telegram: Send Contact
Send a phone contact card (phone number plus name, with an optional vCard payload) to a chat.
Telegram: Send Document
Send a general file (PDF, ZIP, CSV, any type) by HTTP URL or file_id, with an optional caption. Uploading local file bytes is not supported; URL-fetched files are capped at 20 MB.
Telegram: Send Location
Send a map point to a chat as latitude and longitude. For live locations that update over time, pass live_period via extra parameters.
Telegram: Send Media Group
Send 2 to 10 media items as one album. Each item is an InputMedia JSON object whose media field is an HTTP URL or file_id (local uploads not supported). Photos and videos can mix; documents and audio must be grouped only with their own type.
Telegram: Send Message
Send a text message to a chat, group, or channel, with optional MarkdownV2/HTML formatting, link preview control, reply threading, and inline or reply keyboards. Returns the sent Message (data.result.message_id) for later edits, pins, or deletion.
Telegram: Send Photo
Send a photo by HTTP URL or file_id, with an optional formatted caption and keyboard. Uploading local file bytes is not supported; host the image at a URL first. URL photos must be JPEG/PNG/GIF/WEBP and at most 5 MB.
Telegram: Send Poll
Send a native poll (regular or quiz) to a chat. Options are InputPollOption objects; a plain list of strings like [{"text": "Yes"}, {"text": "No"}] is the common case. Stop it later with the Stop Poll node.
Telegram: Send Video
Send an MP4 video by HTTP URL or file_id, with an optional caption and streaming support. Uploading local file bytes is not supported; URL-fetched videos are capped at 20 MB.
Telegram: Set Bot Commands
Set the bot's command list (the menu users see when typing /), optionally per scope and language. Overwrites the previous list for that scope; re-settable at any time.
Telegram: Set Chat Description
Change the description of a group, supergroup, or channel. The bot must be an admin with the right to change chat info. Leave the description blank to clear it.
Telegram: Set Chat Title
Rename a group, supergroup, or channel. The bot must be an admin with the right to change chat info. Fully reversible by setting the old title back.
Telegram: Set Webhook
Register an HTTPS endpoint to receive the bot's updates as POSTed JSON. Management only: this node does not receive events itself. Recipe: create an Automations inbound webhook trigger and use its URL here. Setting a webhook disables getUpdates polling (409 Conflict) until the webhook is deleted. Supported ports: 443, 80, 88, 8443.
Telegram: Stop Poll
Close a poll the bot sent, returning the final Poll with vote counts. A stopped poll cannot be reopened (send a new one instead), but the results stay visible in the chat.
Telegram: Unban Chat Member
Lift a ban so the user can join the chat again (they are not re-added automatically). Note: calling this on a user who is still IN the chat removes them from it, which is why only_if_banned defaults to true here.
Telegram: Unpin Chat Message
Unpin a message in a chat. Leave message_id blank to unpin the most recent pinned message. Reversible by pinning again.
Connecting Telegram takes one credential
Telegram issues bot tokens through BotFather, the official bot for creating bots. Message BotFather in any Telegram client, send the /newbot command, choose a name and username, and it returns the token. Creating a bot is free and takes under a minute; the Bot API itself is free to use. This connector works with bots only, never with personal Telegram accounts.
In Telegram, open a chat with BotFather, send /newbot, choose a display name and a unique username, and copy the token it returns.
In Mattering Automations, open Connectors, click Add Connector, choose Telegram, and create a credential with that token.
Click Test Connection. Mattering runs the same call as Telegram: Get Bot Info and confirms the token authenticates by returning the bot's own identity.
All 40 Telegram nodes appear in the canvas palette. Add the bot to the chats and groups it should work in: nodes can only act where the bot is a member, and moderation or pinning needs the matching admin rights.
Common uses for the Telegram MCP
Workflow alerts in the team channel
Telegram: Send Message posts formatted text with MarkdownV2 or HTML, link preview control, and inline keyboards to any chat, group, or channel the bot belongs to. A failed job, a new signup, or a completed run can announce itself where the team already talks, and the returned message_id makes the message addressable later.
Live status messages that update in place
Telegram: Edit Message Text rewrites a message the bot sent earlier, so a long-running workflow can keep one status message current instead of flooding the chat with updates. Telegram: Send Chat Action adds a typing or uploading indicator before slow steps so people can see the bot is working.
Polls whose results land in a database
Telegram: Send Poll posts a regular or quiz poll to a chat, and Telegram: Stop Poll closes it and returns the final vote counts. Write those counts into a Mattering database and a weekly team poll becomes a record the rest of the platform can chart, filter, and act on.
Reports and files delivered by URL
Telegram: Send Photo, Telegram: Send Document, Telegram: Send Video, Telegram: Send Audio, and Telegram: Send Media Group deliver media from an HTTP URL or an existing file_id, with captions and albums of up to 10 items. Host the file at a URL first: local file uploads are not part of this connector.
Group housekeeping and moderation
Telegram: Get Chat, Telegram: Get Chat Administrators, and Telegram: Get Chat Member Count keep an eye on a community, while Telegram: Set Chat Title, Telegram: Pin Chat Message, and the invite link nodes handle upkeep. Moderation is honest about its sharp edges: Telegram: Unban Chat Member defaults to acting only on banned users, because a bare unban kicks a member who is still in the chat.
Reacting to incoming messages
Telegram: Get Updates is the polling surface: run it on a schedule, loop over the returned updates, and route messages, button presses, and member changes into workflows. Telegram: Answer Callback Query acknowledges inline keyboard presses so users never stare at a loading spinner.
Example: A weekly team poll whose results land in a Mattering database
Built on the Automations canvas in a few minutes, or described in plain language to Matter and built for you.
Trigger: a Monday morning schedule starts the run.
Telegram: Send Poll posts the week's question to the team group, and the returned message_id is saved to a Mattering database record.
Telegram: Pin Chat Message pins the poll so it stays visible all week.
A second scheduled run on Friday reads the saved message_id back from the database.
Telegram: Stop Poll closes the poll and returns the final vote counts for each option.
The counts are written onto the database record, Telegram: Unpin Chat Message tidies the chat, and Telegram: Send Message posts the results summary.
Telegram MCP questions, answered
What Telegram operations are supported?
40 nodes on the official Bot API: messages (send, edit, delete, forward, copy), media by URL or file_id (photos, documents, video, audio, albums), locations, contacts, polls, chat action indicators, chat information and member reads, titles, descriptions, pinning, moderation (ban, unban, restrict, leave), invite links, update polling, webhook management, file metadata, callback query answers, and the bot command menu. Deliberately not shipped: stickers, inline mode, payments, games, forum topic management, and anything touching personal accounts, since this connector is for bots only.
Does this work with Claude, ChatGPT, or other AI assistants?
Yes. Mattering exposes these nodes over MCP, an open protocol for connecting AI assistants to tools, so any MCP-capable assistant, including Claude and ChatGPT, can connect to your workspace and use them. Matter, the assistant built into the platform, uses the same nodes natively.
Is my bot token safe?
It is treated as the connector's defining risk. Telegram's API embeds the bot token in the URL of every request, which means it can surface in places header credentials never touch, like transport error messages. The connector is built so the token never appears in workflow outputs, error messages, or logs: every failure surface is scrubbed before anything is stored or shown. The credential itself is stored encrypted, and anyone holding a bot token controls the bot, so it is handled like the password it is.
Can I upload files from my computer?
No. Every media node accepts an HTTP URL or an existing Telegram file_id, and nothing else: uploading local file bytes is not supported. Host the file at a publicly reachable URL first, or reuse a file_id from something already sent through Telegram. URL-fetched photos are capped at 5 MB and other media at 20 MB, which are Telegram's own limits.
Can I download files a user sent to the bot?
Not through this connector, and that is deliberate. Telegram: Get File Info returns a file's metadata, including its size and server-side path, which is genuinely useful for routing decisions. But Telegram's actual download URL embeds the bot token in its path, so the connector never constructs it: building that URL into workflow outputs would leak the credential. If you truly need the bytes, handle the download outside the automation with your own tooling.
Can a Telegram message trigger a workflow?
Through polling, yes. Telegram: Get Updates fetches incoming messages, button presses, and member changes; run it on a schedule and feed the highest update id plus one back as the offset next run. Two honest constraints: passing an offset confirms earlier updates so they will not be returned again, and polling returns a 409 Conflict while a webhook is set, because Telegram allows one intake mode per bot. The webhook nodes manage that configuration rather than receiving events themselves; the recipe is to point Telegram: Set Webhook at an Automations inbound webhook trigger URL.
Does this cost anything on the Telegram side?
No. The Bot API is free, creating a bot through BotFather is free, and every operation this connector ships is on the free surface. There is no paid tier involved anywhere in the integration.
Why can the bot not message someone or act in a group?
Bots only work where they have been let in. A bot cannot start a conversation with a user who has never messaged it, it must be added to a group or channel before any node can act there, and admin operations like pinning, deleting other people's messages, or banning need the matching admin rights granted by a human admin. If a node returns chat not found or not enough rights, the fix is membership and permissions in Telegram, not the workflow.
Put Telegram to work inside your workspace
Connect once, then use every node in visual automations and AI agent workflows across the Mattering platform.
All product names, logos, and brands are property of their respective owners and are used for identification purposes only. Use of these names, logos, and brands does not imply endorsement or affiliation. Telegram is a product of its respective owner; Mattering is an independent platform.