---
title: Telegram
description: Interact with Telegram
---

import { BlockInfoCard } from "@/components/ui/block-info-card"

<BlockInfoCard 
  type="telegram"
  color="#FFFFFF"
/>

{/* MANUAL-CONTENT-START:intro */}
[Telegram](https://telegram.org) is a secure, cloud-based messaging platform that enables fast and reliable communication across devices. With its powerful Bot API, Telegram provides a robust framework for automated messaging and integration.

With the Telegram integration in Sim, you can:

- **Send messages**: Send text messages to Telegram chats, groups, or channels
- **Delete messages**: Remove previously sent messages from a chat
- **Send photos**: Share images with optional captions
- **Send videos**: Share video files with optional captions
- **Send audio**: Share audio files with optional captions
- **Send animations**: Share GIF animations with optional captions
- **Send documents**: Share files of any type with optional captions

In Sim, the Telegram integration enables your agents to send messages and rich media to Telegram chats as part of automated workflows. This is ideal for automated notifications, alerts, content distribution, and interactive bot experiences.

Learn how to create a webhook trigger in Sim that seamlessly initiates workflows from Telegram messages. This tutorial walks you through setting up a webhook, configuring it with Telegram's bot API, and triggering automated actions in real-time.

<iframe
  width="100%"
  height="400"
  src="https://www.youtube.com/embed/9oKcJtQ0_IM"
  title="Use Telegram with Sim"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

Learn how to use the Telegram Tool in Sim to seamlessly automate message delivery to any Telegram group. This tutorial walks you through integrating the tool into your workflow, configuring group messaging, and triggering automated updates in real-time.

<iframe
  width="100%"
  height="400"
  src="https://www.youtube.com/embed/AG55LpUreGI"
  title="Use Telegram with Sim"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>
{/* MANUAL-CONTENT-END */}


## Usage Instructions

Integrate Telegram into the workflow. Can send and delete messages. Can be used in trigger mode to trigger a workflow when a message is sent to a chat.



## Actions

### `telegram_message`

Send messages to Telegram channels or users through the Telegram Bot API. Enables direct communication and notifications with message tracking and chat confirmation.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `text` | string | Yes | Message text to send |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Telegram message data |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Chat information |
|     ↳ `id` | number | Chat ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Chat username \(if available\) |
|     ↳ `username` | string | Chat title \(for groups and channels\) |
|   ↳ `chat` | object | Information about the bot that sent the message |
|     ↳ `id` | number | Bot user ID |
|     ↳ `first_name` | string | Bot first name |
|     ↳ `username` | string | Bot username |
|     ↳ `type` | string | chat type private or channel |
|   ↳ `date` | number | Unix timestamp when message was sent |
|   ↳ `text` | string | Text content of the sent message |

### `telegram_delete_message`

Delete messages in Telegram channels or chats through the Telegram Bot API. Requires the message ID of the message to delete.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `messageId` | string | Yes | Telegram message ID \(numeric identifier of the message to delete\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Delete operation result |
|   ↳ `ok` | boolean | API response success status |
|   ↳ `deleted` | boolean | Whether the message was successfully deleted |

### `telegram_send_photo`

Send photos to Telegram channels or users through the Telegram Bot API.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `photo` | string | Yes | Photo to send. Pass a file_id or HTTP URL |
| `caption` | string | No | Photo caption \(optional\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Telegram message data including optional photo\(s\) |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Chat information |
|     ↳ `id` | number | Chat ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Chat username \(if available\) |
|     ↳ `username` | string | Chat title \(for groups and channels\) |
|   ↳ `chat` | object | Information about the bot that sent the message |
|     ↳ `id` | number | Bot user ID |
|     ↳ `first_name` | string | Bot first name |
|     ↳ `username` | string | Bot username |
|     ↳ `type` | string | Chat type \(private, group, supergroup, channel\) |
|   ↳ `date` | number | Unix timestamp when message was sent |
|   ↳ `text` | string | Text content of the sent message \(if applicable\) |
|   ↳ `photo` | array | List of photos included in the message |
|     ↳ `file_id` | string | Unique file ID of the photo |
|     ↳ `file_unique_id` | string | Unique identifier for this file across different bots |
|     ↳ `file_size` | number | Size of the photo file in bytes |
|     ↳ `width` | number | Photo width in pixels |
|     ↳ `height` | number | Photo height in pixels |

### `telegram_send_video`

Send videos to Telegram channels or users through the Telegram Bot API.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `video` | string | Yes | Video to send. Pass a file_id or HTTP URL |
| `caption` | string | No | Video caption \(optional\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Telegram message data including optional media |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Information about the sender |
|     ↳ `id` | number | Sender ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Sender's first name \(if available\) |
|     ↳ `username` | string | Sender's username \(if available\) |
|   ↳ `chat` | object | Information about the chat where message was sent |
|     ↳ `id` | number | Chat ID |
|     ↳ `first_name` | string | Chat first name \(if private chat\) |
|     ↳ `username` | string | Chat username \(for private or channels\) |
|     ↳ `type` | string | Type of chat \(private, group, supergroup, or channel\) |
|   ↳ `date` | number | Unix timestamp when the message was sent |
|   ↳ `text` | string | Text content of the sent message \(if applicable\) |
|   ↳ `format` | object | Media format information \(for videos, GIFs, etc.\) |
|     ↳ `file_name` | string | Media file name |
|     ↳ `mime_type` | string | Media MIME type |
|     ↳ `duration` | number | Duration of media in seconds |
|     ↳ `width` | number | Media width in pixels |
|     ↳ `height` | number | Media height in pixels |
|     ↳ `thumbnail` | object | Thumbnail image details |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `thumb` | object | Secondary thumbnail details \(duplicate of thumbnail\) |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `file_id` | string | Media file ID |
|     ↳ `file_unique_id` | string | Unique media file identifier |
|     ↳ `file_size` | number | Size of media file in bytes |
|   ↳ `document` | object | Document file details if the message contains a document |
|     ↳ `file_name` | string | Document file name |
|     ↳ `mime_type` | string | Document MIME type |
|     ↳ `thumbnail` | object | Document thumbnail information |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `thumb` | object | Duplicate thumbnail info \(used for compatibility\) |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `file_id` | string | Document file ID |
|     ↳ `file_unique_id` | string | Unique document file identifier |
|     ↳ `file_size` | number | Size of document file in bytes |

### `telegram_send_audio`

Send audio files to Telegram channels or users through the Telegram Bot API.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `audio` | string | Yes | Audio file to send. Pass a file_id or HTTP URL |
| `caption` | string | No | Audio caption \(optional\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Telegram message data including voice/audio information |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Information about the sender |
|     ↳ `id` | number | Sender ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Sender's first name \(if available\) |
|     ↳ `username` | string | Sender's username \(if available\) |
|   ↳ `chat` | object | Information about the chat where the message was sent |
|     ↳ `id` | number | Chat ID |
|     ↳ `first_name` | string | Chat first name \(if private chat\) |
|     ↳ `username` | string | Chat username \(for private or channels\) |
|     ↳ `type` | string | Type of chat \(private, group, supergroup, or channel\) |
|   ↳ `date` | number | Unix timestamp when the message was sent |
|   ↳ `text` | string | Text content of the sent message \(if applicable\) |
|   ↳ `audio` | object | Audio file details |
|     ↳ `duration` | number | Duration of the audio in seconds |
|     ↳ `performer` | string | Performer of the audio |
|     ↳ `title` | string | Title of the audio |
|     ↳ `file_name` | string | Original filename of the audio |
|     ↳ `mime_type` | string | MIME type of the audio file |
|     ↳ `file_id` | string | Unique file identifier for this audio |
|     ↳ `file_unique_id` | string | Unique identifier across different bots for this file |
|     ↳ `file_size` | number | Size of the audio file in bytes |

### `telegram_send_animation`

Send animations (GIFs) to Telegram channels or users through the Telegram Bot API.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `animation` | string | Yes | Animation to send. Pass a file_id or HTTP URL |
| `caption` | string | No | Animation caption \(optional\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `data` | object | Telegram message data including optional media |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Information about the sender |
|     ↳ `id` | number | Sender ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Sender's first name \(if available\) |
|     ↳ `username` | string | Sender's username \(if available\) |
|   ↳ `chat` | object | Information about the chat where message was sent |
|     ↳ `id` | number | Chat ID |
|     ↳ `first_name` | string | Chat first name \(if private chat\) |
|     ↳ `username` | string | Chat username \(for private or channels\) |
|     ↳ `type` | string | Type of chat \(private, group, supergroup, or channel\) |
|   ↳ `date` | number | Unix timestamp when the message was sent |
|   ↳ `text` | string | Text content of the sent message \(if applicable\) |
|   ↳ `format` | object | Media format information \(for videos, GIFs, etc.\) |
|     ↳ `file_name` | string | Media file name |
|     ↳ `mime_type` | string | Media MIME type |
|     ↳ `duration` | number | Duration of media in seconds |
|     ↳ `width` | number | Media width in pixels |
|     ↳ `height` | number | Media height in pixels |
|     ↳ `thumbnail` | object | Thumbnail image details |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `thumb` | object | Secondary thumbnail details \(duplicate of thumbnail\) |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `file_id` | string | Media file ID |
|     ↳ `file_unique_id` | string | Unique media file identifier |
|     ↳ `file_size` | number | Size of media file in bytes |
|   ↳ `document` | object | Document file details if the message contains a document |
|     ↳ `file_name` | string | Document file name |
|     ↳ `mime_type` | string | Document MIME type |
|     ↳ `thumbnail` | object | Document thumbnail information |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `thumb` | object | Duplicate thumbnail info \(used for compatibility\) |
|       ↳ `file_id` | string | Thumbnail file ID |
|       ↳ `file_unique_id` | string | Unique thumbnail file identifier |
|       ↳ `file_size` | number | Thumbnail file size in bytes |
|       ↳ `width` | number | Thumbnail width in pixels |
|       ↳ `height` | number | Thumbnail height in pixels |
|     ↳ `file_id` | string | Document file ID |
|     ↳ `file_unique_id` | string | Unique document file identifier |
|     ↳ `file_size` | number | Size of document file in bytes |

### `telegram_send_document`

Send documents (PDF, ZIP, DOC, etc.) to Telegram channels or users through the Telegram Bot API.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot API Token |
| `chatId` | string | Yes | Telegram chat ID \(numeric, can be negative for groups\) |
| `files` | file[] | No | Document file to send \(PDF, ZIP, DOC, etc.\). Max size: 50MB |
| `caption` | string | No | Document caption \(optional\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | string | Success or error message |
| `files` | file[] | Files attached to the message |
| `data` | object | Telegram message data including document |
|   ↳ `message_id` | number | Unique Telegram message identifier |
|   ↳ `from` | object | Information about the sender |
|     ↳ `id` | number | Sender ID |
|     ↳ `is_bot` | boolean | Whether the chat is a bot or not |
|     ↳ `first_name` | string | Sender's first name \(if available\) |
|     ↳ `username` | string | Sender's username \(if available\) |
|   ↳ `chat` | object | Information about the chat where message was sent |
|     ↳ `id` | number | Chat ID |
|     ↳ `first_name` | string | Chat first name \(if private chat\) |
|     ↳ `username` | string | Chat username \(for private or channels\) |
|     ↳ `type` | string | Type of chat \(private, group, supergroup, or channel\) |
|   ↳ `date` | number | Unix timestamp when the message was sent |
|   ↳ `document` | object | Document file details |
|     ↳ `file_name` | string | Document file name |
|     ↳ `mime_type` | string | Document MIME type |
|     ↳ `file_id` | string | Document file ID |
|     ↳ `file_unique_id` | string | Unique document file identifier |
|     ↳ `file_size` | number | Size of document file in bytes |



## Triggers

A **Trigger** is a block that starts a workflow when an event happens in this service.

### Telegram Webhook

Trigger workflow from Telegram bot messages and events

#### Configuration

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `botToken` | string | Yes | Your Telegram Bot Token from BotFather |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `message` | object | Telegram message data |
|   ↳ `id` | number | Telegram message ID |
|   ↳ `text` | string | Message text content \(if present\) |
|   ↳ `date` | number | Date the message was sent \(Unix timestamp\) |
|   ↳ `messageType` | string | Detected content type: text, photo, document, audio, video, voice, sticker, location, contact, poll |
|   ↳ `raw` | object | Raw Telegram message object |
|     ↳ `message_id` | number | Original Telegram message_id |
|     ↳ `date` | number | Original Telegram message date \(Unix timestamp\) |
|     ↳ `text` | string | Original Telegram text \(if present\) |
|     ↳ `caption` | string | Original Telegram caption \(if present\) |
|     ↳ `chat` | object | Chat information |
|       ↳ `id` | number | Chat identifier |
|       ↳ `username` | string | Chat username \(if available\) |
|       ↳ `first_name` | string | First name \(for private chats\) |
|       ↳ `last_name` | string | Last name \(for private chats\) |
|       ↳ `title` | string | Chat title \(for groups/channels\) |
|     ↳ `from` | object | Sender information |
|       ↳ `id` | number | Sender user ID |
|       ↳ `is_bot` | boolean | Whether the sender is a bot |
|       ↳ `first_name` | string | Sender first name |
|       ↳ `last_name` | string | Sender last name |
|       ↳ `username` | string | Sender username |
|       ↳ `language_code` | string | Sender language code \(if available\) |
|     ↳ `reply_to_message` | object | Original message being replied to |
|     ↳ `entities` | array | Message entities \(mentions, hashtags, URLs, etc.\) |
| `sender` | object | Sender information |
|   ↳ `id` | number | Sender user ID |
|   ↳ `username` | string | Sender username \(if available\) |
|   ↳ `firstName` | string | Sender first name |
|   ↳ `lastName` | string | Sender last name |
|   ↳ `languageCode` | string | Sender language code \(if available\) |
|   ↳ `isBot` | boolean | Whether the sender is a bot |
| `updateId` | number | Update ID for this webhook delivery |
| `updateType` | string | Type of update: message, edited_message, channel_post, edited_channel_post, unknown |

