Menu

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.

In any Telegram client, open a chat with BotFather (search for the verified BotFather account).
Send the /newbot command, then follow the prompts: choose a display name, then a unique username for the bot.
Copy the bot token BotFather returns.
The token is the bot's entire identity: anyone holding it controls the bot completely. Because Telegram places the token inside the request URL rather than a header, treat it like a password everywhere it travels, and never paste it into chat messages, workflow configs, or URLs of your own. Mattering scrubs it from every output, error message, and log, but the copy on your clipboard is yours to protect.

Connect Telegram to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Telegram from the list.
Click Create new credential, paste the bot token, and save.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection: Mattering calls Telegram's identity method and confirms the token authenticates by returning your bot's username.
Click Connect. All 40 Telegram nodes appear in your canvas palette.

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
The token is invalid, was revoked, or picked up stray whitespace when pasted. Telegram answers a bad token with 401 Unauthorized before anything else runs. Open BotFather in Telegram, issue a fresh token for the bot, and update the credential on the connector.
A node returns 400 with chat not found
The chat id is wrong, or the bot has never seen that chat. Bots must be added to a group or channel before any node can act there, and a bot cannot message a user who has never started a conversation with it. To find the right id, send the bot a message in the target chat and run Telegram: Get Updates: each update carries its chat id. Group ids are negative numbers, which is expected.
A node returns 400 with not enough rights
The bot is in the chat but lacks the admin right the operation needs: pinning needs can_pin_messages, banning and restricting need can_restrict_members, deleting other people's messages needs can_delete_messages, and invite links need can_invite_users. A human admin must promote the bot and grant the specific right in the chat's administrator settings.
Telegram: Get Updates returns a 409 Conflict
A webhook is set on the bot, and Telegram allows one intake mode at a time: polling and webhooks are mutually exclusive per bot. Run Telegram: Get Webhook Info to see the registered URL, then Telegram: Delete Webhook to return to polling, or keep the webhook and stop polling. An empty url in the webhook info means the bot is already in polling mode.
Telegram: Get Updates comes back empty or seems to skip messages
Passing an offset confirms every earlier update permanently: Telegram will not return them again, which is correct between runs but surprising during testing. Track the highest update id from each run and pass that value plus one as the next offset; do not pass an offset at all if you want to re-read whatever is still unconfirmed.
A media send fails when given a URL
Telegram fetches the file server-side, so the URL must be publicly reachable with a direct file response: no login pages and no expired signed links. Check the size caps too: URL-fetched photos are limited to 5 MB and other media to 20 MB, and photos must be JPEG, PNG, GIF, or WEBP. There is no local upload fallback; hosting the file at a public URL or reusing an existing file_id are the two paths.
Everyone's invite link stopped working after an automation ran
Something called Telegram: Export Primary Invite Link, which generates a new primary link and revokes the previous one on every call. Anyone holding the old link loses it. To read the current primary link without rotating it, use Telegram: Get Chat; to hand out links without touching the primary, use Telegram: Create Chat Invite Link, which mints separate named links with optional expiry and member limits.
An unban removed someone from the chat
That is Telegram's own semantics: calling unban on a user who is still in the chat kicks them out of it. Telegram: Unban Chat Member defaults to acting only when the user is actually banned for exactly this reason, so this only happens when that safeguard is explicitly switched off. Leave the default in place unless you specifically intend the removal behavior.

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.

Start Free Explore our Products