# Telegram

Send messages, photos, documents, albums, polls and rich messages from a Telegram bot, edit, pin and react to messages, manage chats and download files.

## Connect Telegram

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `telegram` and choose **Telegram**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Bot Token · Required**: The token @BotFather gave you, such as 123456789:AAH….

Paste your bot’s token. In Telegram, open @BotFather, send /newbot (or /mybots → your bot → API Token) and copy the token it gives. Add the bot to each group or channel it should write to; a person must start a chat with the bot before it can write to them.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Telegram**. The trigger uses the same connection as the steps.

### On Telegram Update

Starts a run for each update Telegram delivers to the bot. Publishing points the bot's webhook at this workflow (with a secret every delivery must carry); unpublishing removes it. A bot has one webhook: if it already sends its updates elsewhere (another workflow, another tool), publishing is refused. Use one bot per workflow. A redelivered update starts no second run.

- **Trigger On · Required**: Which updates start a run. Telegram sends the bot only these. Options: Any update to Generation stopped (28 options).
- **Only From Chats · Optional**: Chat IDs, separated by commas, whose updates start a run. Empty: every chat.
- **Only From People · Optional**: User IDs, separated by commas, whose updates start a run. Empty: everyone.

A later step can use its data, such as `{{trigger.callback_query}}`, `{{trigger.channel_post}}`, `{{trigger.message}}` and 2 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Telegram

Add a **Telegram** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Message](https://docs.gorunner.io/apps/telegram#fields-f-message): Send Message · Send and Wait for Approval · Send Photo · Send Document · Send Video · Send Audio · Send Animation · Send Voice Message · Send Sticker · Send Album (Media Group) · Send Location · Send Contact · Send Poll · Send Chat Action · Send Rich Message · Send Message Draft · Send Rich Message Draft · Edit Message Text · Edit Message Caption · Forward Message · Copy Message · Set Reaction · Pin Message · Unpin Message · Delete Message
- [Chat](https://docs.gorunner.io/apps/telegram#fields-f-chat): Get · Get Administrators · Get Member · Leave · Set Description · Set Title
- [Callback](https://docs.gorunner.io/apps/telegram#fields-f-callback): Answer Query · Answer Inline Query
- [File](https://docs.gorunner.io/apps/telegram#fields-f-file): Get

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Telegram can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Telegram says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Telegram is `pieceId: "telegram"` with `actionId: "telegram"`, set by `resource` and an `operation_…` field, such as `operation_callback`. Its trigger is `telegramtrigger` / `telegram_update`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Telegram › Message

### Send Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Text · Required**: The message, up to 4,096 characters.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **No Link Preview · Optional**: Don't show a preview of the first link in the text. Off by default.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send and Wait for Approval

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Message · Required**: What the person is asked to decide. Its first line is the title the run page shows.
- **Buttons · Optional**: Approve and Reject, or a single Approve button when the only useful answer is yes. Options: Approve and Reject, Approve only. Default: Approve and Reject.
- **Approve Button Label · Optional**: Default: Approve.
- **Reject Button Label · Optional**: Default: Reject. Shows when **Buttons** isn’t **Approve only**.
- **Auto-continue after (timeout) · Optional**: Resume automatically after this long if nobody answers (0 = wait indefinitely). Then status is "timed_out": branch on status == "approved". Default: 0.
- **Timeout Unit · Optional**: Options: Seconds, Minutes, Hours, Days. Default: Hours.
- **Public Base URL · Optional**: This installation's public address, for the buttons' links. Defaults to PUBLIC_API_URL. Telegram refuses a button that points at localhost.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.

### Send Photo, Send Document, Send Video, Send Audio, Send Animation and Send Voice Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Upload a File · Optional**: On: upload a file from this or an earlier step. Off: send one Telegram already has (its file_id) or one at a public URL. Off by default.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Photos up to 10 MB, other files up to 50 MB. Shows when **Upload a File** is on.
- **File ID or URL · Required**: A file_id Telegram gave for a file it already has (recommended), or a public HTTP URL for Telegram to fetch. Shows when **Upload a File** is off.
- **Caption · Optional**: Text shown with the file, up to 1,024 characters.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Sticker

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Upload a File · Optional**: On: upload a file from this or an earlier step. Off: send one Telegram already has (its file_id) or one at a public URL. Off by default.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Photos up to 10 MB, other files up to 50 MB. Shows when **Upload a File** is on.
- **File ID or URL · Required**: A file_id Telegram gave for a file it already has (recommended), or a public HTTP URL for Telegram to fetch. Shows when **Upload a File** is off.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Album (Media Group)

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Media · Required**: 2 to 10 items, each {"type": "photo"|"video"|"document"|"audio", "media": \<file_id, URL or a file from an earlier step>, "caption": "…"}. Documents and audio can only be grouped with their own kind.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.

### Send Location

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Latitude · Required**
- **Longitude · Required**
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Contact

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Phone Number · Required**
- **First Name · Required**
- **Last Name · Optional**
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Poll

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Question · Required**: The poll's question, up to 300 characters.
- **Answers · Required**: One answer per line (2 to 12), or a JSON list of texts.
- **Anonymous · Optional**: Hide who voted for what. On by default.
- **Allow Several Answers · Optional**: Off by default.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Chat Action

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Action · Required**: What the chat shows the bot doing, for up to 5 seconds or until its next message. Options: Typing, Sending a photo, Recording a video, Sending a video, Recording a voice message, Sending a voice message, Sending a file, Choosing a sticker, Finding a location, Recording a video message, Sending a video message. Default: Typing.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.

### Send Rich Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Format · Optional**: Which syntax the rich message is written in. Options: HTML, Markdown. Default: HTML.
- **Rich Message · Required**: Headings, lists, tables, quotes and more, in the chosen syntax (up to 32,768 characters).
- **Right-to-Left · Optional**: Off by default.
- **Skip Link Detection · Optional**: Don't turn URLs, @mentions, hashtags and phone numbers into links. Off by default.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Send Message Draft

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Draft ID · Required**: Any non-zero number. Drafts with the same ID replace one another with an animation; send the finished message with Send Message.
- **Text · Optional**: What the draft shows so far, up to 4,096 characters. Empty shows a "Thinking…" placeholder.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.

### Send Rich Message Draft

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Draft ID · Required**: Any non-zero number. Drafts with the same ID replace one another with an animation; send the finished message with Send Message.
- **Format · Optional**: Which syntax the rich message is written in. Options: HTML, Markdown. Default: HTML.
- **Rich Message · Required**: Headings, lists, tables, quotes and more, in the chosen syntax (up to 32,768 characters).
- **Right-to-Left · Optional**: Off by default.
- **Skip Link Detection · Optional**: Don't turn URLs, @mentions, hashtags and phone numbers into links. Off by default.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.

### Edit Message Text

- **Message Type · Optional**: A message in a chat, or a message sent through the bot's inline mode. Options: Message, Inline Message. Default: Message.
- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Inline Message ID · Required**: The inline_message_id Telegram gave with the inline query's chosen result. Shows when **Message Type** is **Inline Message**.
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Text · Required**: The message, up to 4,096 characters.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **No Link Preview · Optional**: Don't show a preview of the first link in the text. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Edit Message Caption

- **Message Type · Optional**: A message in a chat, or a message sent through the bot's inline mode. Options: Message, Inline Message. Default: Message.
- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Inline Message ID · Required**: The inline_message_id Telegram gave with the inline query's chosen result. Shows when **Message Type** is **Inline Message**.
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Caption · Optional**: Text shown with the file, up to 1,024 characters.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Forward Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **From Chat ID · Required**: The chat the message is in now (numeric ID or @username).
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.

### Copy Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **From Chat ID · Required**: The chat the message is in now (numeric ID or @username).
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Caption · Optional**: Text shown with the file, up to 1,024 characters.
- **Parse Mode · Optional**: How Telegram reads formatting in the text or caption. Options: Plain text, HTML, MarkdownV2, Markdown (legacy). Default: Plain text.
- **Topic (Thread) ID · Optional**: Send into this forum topic of a supergroup.
- **Reply To Message ID · Optional**: Send as a reply to this message in the same chat.
- **Send Silently · Optional**: People get the message without a sound. Off by default.
- **Protect Content · Optional**: The message can't be forwarded or saved. Off by default.
- **Reply Markup · Optional**: Buttons under the message or a custom keyboard, as Telegram defines them, such as {"inline_keyboard": [[{"text": "Open order", "url": "https://shop.example.com/o/1042"}]]}. Also {"keyboard": …}, {"remove_keyboard": true} or {"force_reply": true}.

### Set Reaction

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Emoji · Optional**: The reaction, such as 👍 (one of Telegram's reaction emoji). Empty removes the bot's reaction.

### Pin Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.
- **Send Silently · Optional**: People get the message without a sound. Off by default.

### Unpin Message and Delete Message

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username. Shows when **Message Type** isn’t **Inline Message**.
- **Message ID · Required**: The message's id in that chat (message_id from the step that sent it, or from an update Telegram sent). Shows when **Message Type** isn’t **Inline Message**.

### Telegram › Chat

### Get, Get Administrators and Leave

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username.

### Get Member

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username.
- **User ID · Required**: The person's numeric Telegram user id.

### Set Description

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username.
- **Description · Optional**: The new description, up to 255 characters. Empty removes it.

### Set Title

- **Chat ID · Required**: The chat's numeric ID (groups and channels start with -100) or a public channel's @username.
- **Title · Required**: The new title, 1 to 128 characters.

### Telegram › Callback

### Answer Query

- **Query ID · Required**: The id of the callback query (a button press) or inline query, from the update Telegram sent.
- **Text · Optional**: A note shown to the person (up to 200 characters). Empty shows nothing.
- **Show as Alert · Optional**: Show the text in a dialog instead of a notice at the top of the chat. Off by default.
- **URL · Optional**: A game or t.me link to open for the person.
- **Cache Time (seconds) · Optional**: How long Telegram may keep the answer cached.

### Answer Inline Query

- **Query ID · Required**: The id of the callback query (a button press) or inline query, from the update Telegram sent.
- **Results · Required**: Up to 50 InlineQueryResult objects, such as [{"type": "article", "id": "1", "title": "Order #1042", "input_message_content": {"message_text": "Order #1042 shipped"}}].
- **Cache Time (seconds) · Optional**: How long Telegram may keep the answer cached.

### Telegram › File

### Get

- **File ID · Required**: The file_id from a message (a photo's largest size, a document, a voice message).
- **Download · Optional**: Also download the file (up to 20 MB, the most Telegram lets a bot download) into the output's file. On by default.

Source: https://docs.gorunner.io/apps/telegram