Telegram integration

What it does

The Telegram integration lets your workflows act as a client's Telegram bot. Send text, photos, files, voice notes, polls and invoices, attach buttons and react when someone presses them, moderate groups and channels, manage invite links and join requests, and download the files people send the bot. Twenty-three triggers turn every kind of update the bot receives into a workflow run as it happens.

Each client connects their own bot, so messages come from their brand and you can revoke access for one client without touching anyone else's setup.

Connect a Telegram account

In Telegram, open a chat with @BotFather and send /newbot (or /token for an existing bot).
Follow the prompts. BotFather replies with a token in the form 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.
In TaskJuice, open Connections, choose Telegram, paste the token and save.

Use a separate bot per client so revocation stays scoped. Send /revoke to BotFather at any time to invalidate a token; the next step that uses the connection fails with an authentication error so you know to reconnect.

To act in a group or channel, add the bot to it. Moderation, invite-link, join-request and permission actions need the bot to be an administrator with the matching right.

Triggers

Trigger	Fires when
`telegram/message-received`	someone sends the bot a message, or posts in a group it is in
`telegram/message-edited`	a message the bot can see is edited
`telegram/channel-post-received`	a new post appears in a channel the bot administers
`telegram/channel-post-edited`	a channel post is edited
`telegram/callback-query-received`	someone presses an inline button under one of the bot's messages
`telegram/inline-query-received`	someone types `@yourbot` and a query in any chat
`telegram/chosen-inline-result-received`	someone picks one of the bot's inline results
`telegram/poll-state-changed`	a poll's state or vote counts change
`telegram/poll-answer-received`	someone votes in a non-anonymous poll the bot sent
`telegram/message-reaction-changed`	someone changes their reaction to a message
`telegram/message-reaction-count-changed`	anonymous reaction counts on a message change
`telegram/bot-membership-changed`	the bot is added to, removed from or promoted in a chat
`telegram/chat-member-changed`	a member joins, leaves or changes role in a chat the bot administers
`telegram/chat-join-request-received`	someone asks to join a chat the bot administers
`telegram/business-connection-updated`	a Telegram Business account connects or disconnects the bot
`telegram/business-message-received`	a customer messages a connected Telegram Business account
`telegram/business-message-edited`	a message in a connected business chat is edited
`telegram/business-messages-deleted`	messages are deleted from a connected business chat
`telegram/chat-boost-updated`	someone boosts a channel or group the bot administers
`telegram/chat-boost-removed`	a boost is removed from that chat
`telegram/pre-checkout-query-received`	a buyer confirms payment details for one of the bot's invoices
`telegram/shipping-query-received`	a buyer enters a shipping address for a flexible-price invoice
`telegram/paid-media-purchased`	someone buys paid media the bot sent

You do not register a webhook yourself. Publishing a workflow points the bot's webhook at TaskJuice, asks Telegram for exactly the update kinds your published triggers use, and sets a secret token that TaskJuice checks on every delivery. One delivery starts one workflow run.

A bot has one webhook. If the bot was already sending updates to another server, publishing a Telegram trigger replaces that webhook, so use a bot that is dedicated to TaskJuice. Removing the Telegram connection deletes the webhook.

To react to a specific chat or to bot commands such as /start, add a Filter step after Message Received on message.chat.id or message.text.

Business triggers need a Telegram Business account (Telegram Premium) that has connected the bot under Settings, Telegram Business, Chatbots.

Actions

Send

Send Message, with optional reply-to, forum topic, link-preview control and buttons (an inline keyboard whose presses arrive on Callback Query Received)
Send Photo, Send Document, Send Video, Send Audio, Send Animation, Send Sticker, Send Voice Message, Send Video Note: upload a file from an earlier step
Send Photo, Video, Document, Audio, Animation, Sticker or Voice Message by URL or File ID: send a file Telegram fetches from a web address, or one already on Telegram, with no upload. A sticker sent by URL must be a static .WEBP, and a voice message sent by URL must be OGG/OPUS up to 1 MB (a larger file arrives as a document).
Send Video Note by File ID (Telegram can't fetch video notes from a URL): resend a round video message that is already on Telegram
Send Media Group, Send Location, Send Poll, Send Chat Action (for example "typing…")
Forward Message, Copy Message

Edit and manage messages

Edit Message Text, Edit Message Caption, Edit Message Media, Edit Message Buttons
Delete Message, Pin Chat Message, Unpin Chat Message, Set Message Reaction

Interactive bots

Answer Callback Query, Answer Inline Query
Get Bot Commands, Set Bot Commands: read or replace the slash-command menu
List Updates: inspect pending updates on a bot that has no published trigger yet, for example to find a chat ID

Payments

Send Invoice: card payments through a payment provider token from BotFather, or Telegram Stars with currency XTR
Answer Pre-Checkout Query: approve or reject the order. Telegram needs the answer within 10 seconds, so put this step directly after Pre-Checkout Query Received.
Answer Shipping Query: offer shipping options for a flexible-price invoice

Files

Get File, then Download File: turn a file someone sent the bot into a file you can pass to later steps (up to 20 MB)

Chats and members

Get Bot Info, Get Chat, Get Chat Administrators, Get Chat Member, Get Chat Member Count, Get User Profile Photos
Set Chat Title, Set Chat Description, Set Chat Permissions, Leave Chat
Ban Chat Member, Unban Chat Member, Restrict Chat Member, Promote Chat Member. To kick someone without a lasting ban, run Ban Chat Member then Unban Chat Member.
Create, Edit, Revoke and Export Chat Invite Link
Approve Chat Join Request, Decline Chat Join Request

Known limitations

The Bot API has no way to list the chats a bot is in. Chat IDs come from trigger data (message.chat.id), from List Updates before a trigger is published, or as a public @username.
List Updates stops working once a Telegram trigger is published for the bot, because Telegram delivers updates either to a webhook or to List Updates, never both.
Telegram rate-limits bots to roughly 30 messages per second overall and about one message per second to a given chat. TaskJuice retries 429 responses with backoff.
A bot can only message people who have started a chat with it, and can only edit messages it sent.
Bots can upload files up to 50 MB, download files up to 20 MB, and have Telegram fetch photos up to 5 MB and other files up to 20 MB by URL.
Update kinds added in Bot API 10.x (guest messages, managed bots, payment subscriptions, stopped message generation) are not available as triggers yet.