Mattering Automations Telegram integration
Connect Telegram to Mattering Automations: bot messaging, media by URL, polls, chat management, moderation, invite links, and update polling as workflow steps, authenticated with a bot token from BotFather.
The Mattering Automations Telegram integration adds Telegram bot messaging to your automation canvas: send, edit, forward, and copy messages with formatting and keyboards, deliver photos, documents, video, audio, and albums by URL or file_id, run polls, send locations and contacts, read and manage chats, moderate groups, handle invite links, poll for incoming updates, manage the bot's webhook, and maintain the bot's command menu. It works with bots only, never with personal Telegram accounts.
Setup takes a few minutes: create a bot through BotFather inside Telegram, attach its token as a credential in Mattering, and test the connection. This guide walks through each step and ends with the full node reference.
The security model is worth knowing up front. Telegram's API carries the bot token inside the URL of every request, a place credentials do not normally live, and the integration treats that as a first-class threat: the token never appears in workflow outputs, error messages, or logs. The four operations with no undo (deleting a message, banning a member, leaving a chat, and revoking an invite link) are flagged destructive, and the safest first step is always a read like Telegram: Get Bot Info.
Before you start
- A Telegram account. Creating a bot is free and takes under a minute; no paid tier is involved anywhere in the Bot API.
- A Mattering workspace with access to the Automations app.
- For group and channel work: the ability to add the bot to those chats and, where moderation, pinning, or invite links are involved, a human admin willing to grant the bot the matching admin rights.
Create a Telegram bot and copy its token
Mattering authenticates to Telegram with a bot token issued by BotFather, Telegram's official bot for creating bots. There is no OAuth flow: the token is the whole credential, and Telegram's API expects it inside the request URL of every call, which is exactly why the integration goes to unusual lengths to keep it out of everything it stores or shows.
Connect Telegram to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Telegram section should list the query and action nodes. Drop Telegram: Get Bot Info onto the canvas and run a test step. It takes no parameters and is a safe, read-only call; a successful response returns the bot's id, username, and capability flags. A 401 here means the token is wrong, and nothing else will work until it is fixed.
To verify messaging, add the bot to a scratch group, then run Telegram: Get Chat to confirm the bot can see it and Telegram: Send Message to post a test message. If you do not know a chat's id, send the bot a message in that chat and run Telegram: Get Updates: each update carries the chat id it came from. Note that a bot cannot start a conversation with a user who has never messaged it, so direct messages only verify against accounts that have opened the bot first.
Node reference
40 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 9
Telegram: Get Bot Commands
telegram_get_my_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
telegram_get_me
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
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
telegram_get_chat_administrators
List all administrators of a group or channel (excluding other bots), each with their admin rights.
Telegram: Get Chat Member
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
telegram_get_chat_member_count
Return the number of members in a chat as a plain integer.
Telegram: Get File Info
telegram_get_file
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
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
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
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
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
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
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
telegram_delete_my_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
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
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
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
telegram_export_chat_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
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
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
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
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
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
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
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
telegram_send_contact
Send a phone contact card (phone number plus name, with an optional vCard payload) to a chat.
Telegram: Send Document
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
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
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
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
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
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
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
telegram_set_my_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
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
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
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
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
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
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.
Using the integration
On the automation canvas
Telegram nodes chain with every other node: a failed workflow can announce itself in the team channel through Telegram: Send Message with a link back to the run, a weekly Telegram: Send Poll can have its final counts from Telegram: Stop Poll written into a Mattering database, and a review task in Mattering Productivity can gate the destructive steps like Telegram: Delete Message so a person decides before anything is removed.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools. Claude, ChatGPT, and Matter can post updates, run polls, and read chat information through the same nodes your workflows use. The read nodes (Telegram: Get Bot Info, Telegram: Get Chat, Telegram: Get Chat Administrators, Telegram: Get Chat Member Count) are the safest Telegram surface to hand an agent.
The token secrecy model
Telegram's API embeds the bot token in the URL of every request, so a raw transport error would normally quote the credential back in plain text. The integration closes that: the token never appears in workflow outputs, error messages, or logs, and failure messages show a placeholder where the token would have been. This is also why Telegram: Get File Info stops at metadata: Telegram's file download URL embeds the token in its path, so the integration never constructs it.
Media by URL or file_id
Telegram: Send Photo, Telegram: Send Document, Telegram: Send Video, Telegram: Send Audio, and Telegram: Send Media Group accept an HTTP URL that Telegram fetches server-side, or a file_id referencing something already on Telegram. Uploading local file bytes is not supported anywhere in the integration. Telegram caps URL-fetched photos at 5 MB and other media at 20 MB, and albums hold 2 to 10 items, with documents and audio grouped only with their own type.
Reacting to messages: polling and webhooks
Telegram: Get Updates is the intake surface: run it on a schedule, loop over the results, and pass the highest update id plus one back as the offset next run. Two constraints are baked into Telegram itself: passing an offset confirms earlier updates permanently, and polling answers 409 Conflict while a webhook is set, because each bot gets one intake mode at a time. The webhook nodes are management only: Telegram: Set Webhook registers a delivery URL (point it at an Automations inbound webhook trigger to receive events), Telegram: Get Webhook Info inspects the current state, and Telegram: Delete Webhook returns the bot to polling.
Moderation and invite links, with honest defaults
Telegram: Ban Chat Member, Telegram: Restrict Chat Member, and Telegram: Unban Chat Member cover moderation, and the unban node defaults to acting only on users who are actually banned, because Telegram's bare unban removes a member who is still in the chat. On links, Telegram: Export Primary Invite Link rotates the primary link on every call, revoking the old one, so use Telegram: Get Chat to read the current link without rotating it and Telegram: Create Chat Invite Link to mint extra links that leave the primary alone.
Troubleshooting
Test Connection fails with a 401
A node returns 400 with chat not found
A node returns 400 with not enough rights
Telegram: Get Updates returns a 409 Conflict
Telegram: Get Updates comes back empty or seems to skip messages
A media send fails when given a URL
Everyone's invite link stopped working after an automation ran
An unban removed someone from the chat
Related
The Telegram MCP
What connecting Telegram unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Telegram is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.