Telegram
Integration with Telegram Bot API for sending messages, media, and receiving updates
Telegram Bot API integration for automated messaging and bot management in Axellero Workflow Designer and Agentflow Designer.
Setup Required: See the Setup Guide for authentication configuration and connector setup.
Quick Navigation
Setup Guide
Step-by-step authentication and connector configuration
Changelog
Version history and recent updates
Overview
The Telegram node enables comprehensive automation of bot operations including sending messages and media, managing groups and channels, creating interactive experiences with inline keyboards and callbacks, and monitoring bot activity in real-time through webhook triggers.
Key Features:
- Send & Receive - Send text, photos, videos, documents, audio, animations, stickers, and receive updates via webhooks
- Interactivity - Inline keyboards, callback queries, polls, dice, reactions, and inline queries
- Group Management - Ban/unban users, restrict permissions, promote admins, pin messages, set titles
- AI Agent Support - Long polling with getUpdates for building conversational bots in agentflows
- Full Media - Photo albums, voice messages, contacts, locations, venues, and file downloads
Connection Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
| token | TEXT | Yes | Telegram Bot token from @BotFather |
Setup Instructions: See the Setup Guide for authentication configuration, connector creation, and webhook setup.
Available Operations
| Category | Operation | Description |
|---|---|---|
| Bot Information | getMe | Get information about the bot |
| Messages | sendMessage | Send a text message to a chat |
| Messages | forwardMessage | Forward a message from one chat to another |
| Messages | copyMessage | Copy a message without the forward header |
| Messages | editMessageText | Edit the text of a message |
| Messages | editMessageCaption | Edit the caption of a media message |
| Messages | editMessageMedia | Replace the media content of a message |
| Messages | editMessageReplyMarkup | Edit the inline keyboard of a message |
| Messages | deleteMessage | Delete a message from a chat |
| Media | sendPhoto | Send a photo to a chat |
| Media | sendDocument | Send a document/file to a chat |
| Media | sendVideo | Send a video file to a chat |
| Media | sendAudio | Send an audio file to a chat |
| Media | sendAnimation | Send a GIF or video without sound |
| Media | sendVoice | Send a voice message (OGG/OPUS) |
| Media | sendMediaGroup | Send multiple photos/videos as an album |
| Stickers | sendSticker | Send a sticker to a chat |
| Stickers | getStickerSet | Get a sticker set by name |
| Location & Contacts | sendLocation | Send a location point on the map |
| Location & Contacts | sendVenue | Send a venue with name and address |
| Location & Contacts | sendContact | Send a phone contact |
| Interactive | sendPoll | Send a poll (regular or quiz) |
| Interactive | sendDice | Send a random dice animation |
| Interactive | answerCallbackQuery | Respond to inline keyboard button press |
| Interactive | answerInlineQuery | Send results for inline queries |
| Interactive | setMessageReaction | React to a message with an emoji |
| Interactive | sendChatAction | Display typing indicator or other action |
| Chat Information | getChat | Get information about a chat |
| Chat Information | getChatMember | Get information about a chat member |
| Chat Information | getFile | Get file info and download URL |
| Chat Management | pinChatMessage | Pin a message in a chat |
| Chat Management | unpinChatMessage | Unpin a message |
| Chat Management | setChatTitle | Change the chat title |
| Chat Management | banChatMember | Ban a user from a chat |
| Chat Management | unbanChatMember | Unban a user |
| Chat Management | restrictChatMember | Restrict user permissions |
| Chat Management | promoteChatMember | Promote user to admin |
| Bot Commands | setMyCommands | Set the bot's command menu |
| Bot Commands | getMyCommands | Get current bot commands |
| Bot Commands | deleteMyCommands | Delete bot commands |
| Updates | getUpdates | Receive incoming updates via long polling |
Operations Reference
Bot Information
getMe
Get the bot's profile including id, username, first name, and permissions.
Parameters:
No additional parameters required.
Configuration Example:
{}Note: Connector options (like
token) are automatically injected by the runtime. You only need to specify operation-specific parameters.
Success Response:
{
"success": true,
"data": {
"id": 123456789,
"isBot": true,
"firstName": "My Bot",
"username": "my_bot",
"canJoinGroups": true,
"canReadAllGroupMessages": false,
"supportsInlineQueries": false
}
}Error Response:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired bot token"
}
}Messages
sendMessage
Send a text message to a Telegram chat. Supports formatting with HTML, Markdown, or MarkdownV2.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| text | TEXT | Yes | - | Message content |
| parseMode | TEXT | No | MarkdownV2 | Formatting mode (HTML/Markdown/MarkdownV2) |
| disableNotification | BOOLEAN | No | false | Send silently |
| replyToMessageId | INT | No | - | Message ID to reply to |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"text": "Hello, {{ctx.vars.userName}}!",
"parseMode": "HTML"
}Note: Connector options (like
token) are automatically injected by the runtime. You only need to specify operation-specific parameters.
Success Response:
{
"success": true,
"data": {
"messageId": 123,
"chatId": -1001234567890,
"text": "Hello, John!",
"date": 1704067200
}
}Error Response:
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Bad Request: chat not found"
}
}forwardMessage
Forward a message from one chat to another. The forwarded message shows the original sender.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Destination chat ID |
| fromChatId | TEXT | Yes | Source chat ID |
| messageId | INT | Yes | Message ID to forward |
| disableNotification | BOOLEAN | No | Forward silently |
Configuration Example:
{
"chatId": "{{ctx.vars.destinationChatId}}",
"fromChatId": "{{ctx.vars.sourceChatId}}",
"messageId": "{{ctx.vars.messageId}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 456,
"chatId": -1001234567890,
"date": 1704067200
}
}copyMessage
Copy a message to another chat without the "Forwarded from" header. The copied message appears as if sent directly.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Destination chat ID |
| fromChatId | TEXT | Yes | - | Source chat ID |
| messageId | INT | Yes | - | Message ID to copy |
| caption | TEXT | No | - | New caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
Configuration Example:
{
"chatId": "{{ctx.vars.destinationChatId}}",
"fromChatId": "{{ctx.vars.sourceChatId}}",
"messageId": "{{ctx.vars.messageId}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 789
}
}editMessageText
Edit the text of a previously sent message.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | No* | - | Chat ID (required with messageId) |
| messageId | INT | No* | - | Message ID to edit |
| inlineMessageId | TEXT | No* | - | Inline message ID (alternative) |
| text | TEXT | Yes | - | New message text |
| parseMode | TEXT | No | MarkdownV2 | Text formatting mode |
*Either chatId+messageId or inlineMessageId is required.
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}",
"text": "Updated: {{ctx.vars.newText}}",
"parseMode": "HTML"
}Success Response:
{
"success": true,
"data": {
"messageId": 123,
"chatId": -1001234567890,
"text": "Updated: new content",
"date": 1704067200
}
}editMessageCaption
Edit the caption of a media message (photo, video, etc.).
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | No* | - | Chat ID (required with messageId) |
| messageId | INT | No* | - | Message ID to edit |
| inlineMessageId | TEXT | No* | - | Inline message ID (alternative) |
| caption | TEXT | No | - | New caption (empty to remove) |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
*Either chatId+messageId or inlineMessageId is required.
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}",
"caption": "Updated caption: {{ctx.vars.newCaption}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 123,
"chatId": -1001234567890
}
}editMessageMedia
Replace the media content of a message with new media.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | No* | Chat ID (required with messageId) |
| messageId | INT | No* | Message ID to edit |
| inlineMessageId | TEXT | No* | Inline message ID (alternative) |
| media | OBJECT | Yes | New media object |
*Either chatId+messageId or inlineMessageId is required.
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}",
"media": {"type": "photo", "media": "https://example.com/new-image.jpg", "caption": "New caption"}
}Success Response:
{
"success": true,
"data": {
"messageId": 123,
"chatId": -1001234567890
}
}editMessageReplyMarkup
Edit the inline keyboard buttons of a message.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | No* | Chat ID (required with messageId) |
| messageId | INT | No* | Message ID to edit |
| inlineMessageId | TEXT | No* | Inline message ID (alternative) |
| replyMarkup | OBJECT | No | New keyboard (empty to remove) |
*Either chatId+messageId or inlineMessageId is required.
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}",
"replyMarkup": {
"inline_keyboard": [
[{"text": "Updated Button", "callback_data": "updated_action"}]
]
}
}Success Response:
{
"success": true,
"data": {
"messageId": 123,
"chatId": -1001234567890
}
}deleteMessage
Delete a message from a chat. Bots can delete outgoing messages and messages in chats where they have appropriate permissions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID containing the message |
| messageId | INT | Yes | Message ID to delete |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}"
}Success Response:
{
"success": true,
"data": {
"deleted": true
}
}Media
sendPhoto
Send a photo to a Telegram chat.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| photo | TEXT | Yes | - | Photo to send: file_id, HTTP/HTTPS URL, or base64 data |
| caption | TEXT | No | - | Photo caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"photo": "https://example.com/image.jpg",
"caption": "<b>Check out this photo!</b>",
"parseMode": "HTML"
}Success Response:
{
"success": true,
"data": {
"messageId": 124,
"chatId": -1001234567890,
"photo": [
{"file_id": "photo_small_id", "width": 320, "height": 240},
{"file_id": "photo_large_id", "width": 1280, "height": 960}
],
"date": 1704067200
}
}sendDocument
Send a document or file to a Telegram chat. Supports most file types including PDF, ZIP, TXT, etc.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| document | TEXT | Yes | - | Document to send: file_id, HTTP/HTTPS URL, or base64 data |
| caption | TEXT | No | - | Document caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"document": "{{ctx.vars.documentUrl}}",
"caption": "Here is your report"
}Success Response:
{
"success": true,
"data": {
"messageId": 125,
"chatId": -1001234567890,
"document": {
"file_id": "doc_file_id",
"file_name": "report.pdf",
"file_size": 102400
},
"date": 1704067200
}
}sendVideo
Send a video file to a Telegram chat. Supports MP4 format.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| video | TEXT | Yes | - | Video to send: file_id, HTTP/HTTPS URL (YouTube NOT supported), or base64 data |
| caption | TEXT | No | - | Video caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
| duration | INT | No | - | Duration in seconds |
| width | INT | No | - | Video width |
| height | INT | No | - | Video height |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"video": "{{ctx.vars.videoUrl}}",
"caption": "Training video - Module {{ctx.vars.moduleNumber}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 126,
"chatId": -1001234567890,
"video": {
"file_id": "video_file_id",
"duration": 120,
"width": 1920,
"height": 1080
},
"date": 1704067200
}
}sendAudio
Send an audio file to a Telegram chat. Displays as a music track with player. Supports MP3 and M4A formats.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| audio | TEXT | Yes | - | Audio to send: file_id, HTTP/HTTPS URL, or base64 data |
| caption | TEXT | No | - | Audio caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
| duration | INT | No | - | Duration in seconds |
| performer | TEXT | No | - | Performer name |
| title | TEXT | No | - | Track name |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"audio": "{{ctx.vars.audioUrl}}",
"title": "{{ctx.vars.trackTitle}}",
"performer": "{{ctx.vars.artistName}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 127,
"chatId": -1001234567890,
"audio": {
"file_id": "audio_file_id",
"duration": 240,
"performer": "Artist",
"title": "Track Name"
},
"date": 1704067200
}
}sendAnimation
Send an animation (GIF or H.264/MPEG-4 AVC video without sound) to a Telegram chat.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| animation | TEXT | Yes | - | Animation to send: file_id, HTTP/HTTPS URL, or base64 data |
| caption | TEXT | No | - | Animation caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"animation": "https://example.com/animation.gif",
"caption": "Check this out!"
}Success Response:
{
"success": true,
"data": {
"messageId": 128,
"chatId": -1001234567890,
"animation": {
"file_id": "animation_file_id",
"duration": 5,
"width": 480,
"height": 360
},
"date": 1704067200
}
}sendVoice
Send a voice message to a Telegram chat. Must be in OGG format with OPUS codec.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| voice | TEXT | Yes | - | Voice to send: file_id, HTTP/HTTPS URL, or base64 data (OGG/OPUS only) |
| caption | TEXT | No | - | Voice message caption |
| parseMode | TEXT | No | MarkdownV2 | Caption formatting mode |
| duration | INT | No | - | Duration in seconds |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"voice": "{{ctx.vars.voiceFileId}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 129,
"chatId": -1001234567890,
"voice": {
"file_id": "voice_file_id",
"duration": 15
},
"date": 1704067200
}
}sendMediaGroup
Send a group of photos or videos as an album (2-10 items).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| media | OBJECT | Yes | Array of media objects (2-10 items) |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"media": [
{"type": "photo", "media": "https://example.com/image1.jpg"},
{"type": "photo", "media": "https://example.com/image2.jpg", "caption": "Second image"}
]
}Success Response:
{
"success": true,
"data": [
{"messageId": 130, "chatId": -1001234567890},
{"messageId": 131, "chatId": -1001234567890}
]
}Stickers
sendSticker
Send a sticker to a Telegram chat. Supports .WEBP (static), .TGS (animated), and .WEBM (video) formats.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| sticker | TEXT | Yes | Sticker file_id (recommended) or HTTP URL of .WEBP/.TGS/.WEBM file |
| emoji | TEXT | No | Associated emoji for search |
| disableNotification | BOOLEAN | No | Send silently |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"sticker": "{{ctx.vars.stickerFileId}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 132,
"chatId": -1001234567890,
"sticker": {
"file_id": "sticker_file_id",
"type": "regular",
"width": 512,
"height": 512,
"emoji": "👍"
},
"date": 1704067200
}
}getStickerSet
Get information about a sticker set including all stickers in the set.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | TEXT | Yes | Sticker set name (the part after /addstickers/ in the pack URL) |
Configuration Example:
{
"name": "Animals"
}Success Response:
{
"success": true,
"data": {
"name": "Animals",
"title": "Animal Stickers",
"stickerType": "regular",
"stickers": [
{"file_id": "sticker_1", "emoji": "🐱", "width": 512, "height": 512},
{"file_id": "sticker_2", "emoji": "🐶", "width": 512, "height": 512}
]
}
}Location & Contacts
sendLocation
Send a location point on the map. Optionally share live location that updates.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chatId | TEXT | Yes | - | Chat ID or @username |
| latitude | FRACTIONAL | Yes | - | Latitude coordinate |
| longitude | FRACTIONAL | Yes | - | Longitude coordinate |
| livePeriod | INT | No | 3600 | Live location period (60-86400 seconds) |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"latitude": 51.5074,
"longitude": -0.1278
}Success Response:
{
"success": true,
"data": {
"messageId": 133,
"chatId": -1001234567890,
"location": {
"latitude": 51.5074,
"longitude": -0.1278
},
"date": 1704067200
}
}sendVenue
Send a venue with location, name, and address. Perfect for sharing business locations or meeting points.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| latitude | FRACTIONAL | Yes | Latitude coordinate |
| longitude | FRACTIONAL | Yes | Longitude coordinate |
| title | TEXT | Yes | Venue name |
| address | TEXT | Yes | Venue address |
| foursquareId | TEXT | No | Foursquare ID |
| googlePlaceId | TEXT | No | Google Places ID |
| disableNotification | BOOLEAN | No | Send silently |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"latitude": 51.5074,
"longitude": -0.1278,
"title": "{{ctx.vars.venueName}}",
"address": "{{ctx.vars.venueAddress}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 134,
"chatId": -1001234567890,
"venue": {
"location": {"latitude": 51.5074, "longitude": -0.1278},
"title": "Office",
"address": "123 Main St"
},
"date": 1704067200
}
}sendContact
Send a phone contact to a chat. Ideal for sharing business or personal contact information.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| phoneNumber | TEXT | Yes | Phone number |
| firstName | TEXT | Yes | First name |
| lastName | TEXT | No | Last name |
| vcard | TEXT | No | vCard data (0-2048 bytes) |
| disableNotification | BOOLEAN | No | Send silently |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"phoneNumber": "{{ctx.vars.contactPhone}}",
"firstName": "{{ctx.vars.contactFirstName}}",
"lastName": "{{ctx.vars.contactLastName}}"
}Success Response:
{
"success": true,
"data": {
"messageId": 135,
"chatId": -1001234567890,
"contact": {
"phone_number": "+1234567890",
"first_name": "John",
"last_name": "Doe"
},
"date": 1704067200
}
}Interactive
sendPoll
Send a native poll to a Telegram chat. Supports regular polls and quizzes.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| question | TEXT | Yes | Poll question (1-300 chars) |
| options | OBJECT | Yes | Array of option strings (2-10) |
| isAnonymous | BOOLEAN | No | Anonymous poll (default: true) |
| type | TEXT | No | "regular" or "quiz" |
| allowsMultipleAnswers | BOOLEAN | No | Allow multiple answers |
| correctOptionId | INT | No | Correct option index (quiz only) |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"question": "What's your favorite color?",
"options": ["Red", "Blue", "Green", "Yellow"],
"isAnonymous": true,
"type": "regular"
}Success Response:
{
"success": true,
"data": {
"messageId": 136,
"chatId": -1001234567890,
"poll": {
"id": "5678901234567890123",
"question": "What's your favorite color?",
"options": [
{"text": "Red", "voter_count": 0},
{"text": "Blue", "voter_count": 0},
{"text": "Green", "voter_count": 0},
{"text": "Yellow", "voter_count": 0}
],
"is_anonymous": true,
"type": "regular"
},
"date": 1704067200
}
}sendDice
Send a randomized dice animation. Great for games, decisions, or fun interactions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
| emoji | TEXT | No | Dice type (default: dice) |
| disableNotification | BOOLEAN | No | Send silently |
Dice Types and Value Ranges:
- Dice (1-6)
- Darts (1-6)
- Basketball (1-5)
- Football (1-5)
- Bowling (1-6)
- Slot Machine (1-64)
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"emoji": "🎲"
}Success Response:
{
"success": true,
"data": {
"messageId": 137,
"chatId": -1001234567890,
"dice": {
"emoji": "🎲",
"value": 4
},
"date": 1704067200
}
}answerCallbackQuery
Send an answer to a callback query from an inline keyboard button press.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| callbackQueryId | TEXT | Yes | - | Callback query identifier |
| text | TEXT | No | - | Notification text (0-200 chars) |
| showAlert | BOOLEAN | No | false | Show alert instead of toast |
| url | TEXT | No | - | URL to open |
| cacheTime | INT | No | 300 | Cache time (0-3600 seconds) |
Configuration Example:
{
"callbackQueryId": "{{ctx.nodes.telegram_trigger.outputs.data.callback_query.id}}",
"text": "Option selected!",
"showAlert": false
}Success Response:
{
"success": true,
"data": {
"answered": true
}
}answerInlineQuery
Send results for an inline query. Called when a user types @botname in any chat.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| inlineQueryId | TEXT | Yes | - | Query identifier |
| results | OBJECT | Yes | - | Array of results (max 50) |
| cacheTime | INT | No | 300 | Cache time (0-3600 seconds) |
| isPersonal | BOOLEAN | No | false | User-specific caching |
| nextOffset | TEXT | No | - | Pagination offset |
| button | OBJECT | No | - | Button above results |
Configuration Example:
{
"inlineQueryId": "{{ctx.nodes.telegram_trigger.outputs.data.inline_query.id}}",
"results": [
{
"type": "article",
"id": "1",
"title": "Result Title",
"input_message_content": {"message_text": "Selected result"}
}
],
"cacheTime": 60
}Success Response:
{
"success": true,
"data": {
"answered": true
}
}setMessageReaction
Add or remove an emoji reaction to a message.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| messageId | INT | Yes | Message ID to react to |
| emoji | TEXT | No | Emoji (empty to remove reaction) |
| isBig | BOOLEAN | No | Show big animation |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}",
"emoji": "👍"
}Success Response:
{
"success": true,
"data": {
"reacted": true
}
}sendChatAction
Display a typing indicator or other action status in the chat. Useful for long-running operations.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| action | TEXT | Yes | Action type |
Available Actions: typing, upload_photo, record_video, upload_video, record_voice, upload_voice, upload_document, choose_sticker, find_location, record_video_note, upload_video_note
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"action": "typing"
}Success Response:
{
"success": true,
"data": {
"sent": true
}
}Chat Information
getChat
Get detailed information about a chat including title, type, description, and settings.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID or @username |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}"
}Success Response:
{
"success": true,
"data": {
"id": -1001234567890,
"type": "supergroup",
"title": "My Group",
"description": "A group for discussions",
"memberCount": 150
}
}getChatMember
Get information about a member of a chat including their status and permissions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| userId | INT | Yes | User ID to look up |
Member Status: creator, administrator, member, restricted, left, kicked
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"userId": "{{ctx.vars.userId}}"
}Success Response:
{
"success": true,
"data": {
"status": "administrator",
"user": {
"id": 987654321,
"firstName": "John",
"username": "john_doe"
},
"canDeleteMessages": true,
"canRestrictMembers": true
}
}getFile
Get information about a file and a download URL. Files are available for at least 1 hour.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| fileId | TEXT | Yes | File identifier from message |
Note: The download URL follows the format: https://api.telegram.org/file/bot<token>/<file_path>
Configuration Example:
{
"fileId": "{{ctx.vars.fileId}}"
}Success Response:
{
"success": true,
"data": {
"fileId": "file_abc123",
"fileUniqueId": "unique_abc123",
"fileSize": 102400,
"filePath": "documents/file_0.pdf"
}
}Chat Management
pinChatMessage
Pin a message in a group, supergroup, or channel. Requires appropriate admin permissions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| messageId | INT | Yes | Message ID to pin |
| disableNotification | BOOLEAN | No | Pin silently |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"messageId": "{{ctx.vars.messageId}}"
}Success Response:
{
"success": true,
"data": {
"pinned": true
}
}unpinChatMessage
Unpin a message in a group, supergroup, or channel. If messageId is not specified, unpins the most recent pinned message.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| messageId | INT | No | Message ID to unpin |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}"
}Success Response:
{
"success": true,
"data": {
"unpinned": true
}
}setChatTitle
Change the title of a group, supergroup, or channel. Requires appropriate admin permissions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| title | TEXT | Yes | New title (1-128 chars) |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"title": "{{ctx.vars.newTitle}}"
}Success Response:
{
"success": true,
"data": {
"updated": true
}
}banChatMember
Ban a user from a group, supergroup, or channel. The user will not be able to return unless unbanned.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| userId | INT | Yes | User ID to ban |
| untilDate | INT | No | Unix timestamp for ban expiry |
| revokeMessages | BOOLEAN | No | Delete user's messages |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"userId": "{{ctx.vars.userId}}",
"revokeMessages": true
}Success Response:
{
"success": true,
"data": {
"banned": true
}
}unbanChatMember
Unban a previously banned user, allowing them to rejoin the group.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| userId | INT | Yes | User ID to unban |
| onlyIfBanned | BOOLEAN | No | Only unban if currently banned |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"userId": "{{ctx.vars.userId}}",
"onlyIfBanned": true
}Success Response:
{
"success": true,
"data": {
"unbanned": true
}
}restrictChatMember
Restrict a user's permissions in a supergroup.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| userId | INT | Yes | User ID to restrict |
| permissions | OBJECT | Yes | Permissions object |
| untilDate | INT | No | Restriction expiry timestamp |
| useIndependentChatPermissions | BOOLEAN | No | Use independent permissions |
Permissions Object Fields: canSendMessages, canSendAudios, canSendDocuments, canSendPhotos, canSendVideos, canSendVideoNotes, canSendVoiceNotes, canSendPolls, canSendOtherMessages, canAddWebPagePreviews, canChangeInfo, canInviteUsers, canPinMessages, canManageTopics
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"userId": "{{ctx.vars.userId}}",
"permissions": {
"canSendMessages": true,
"canSendPhotos": false,
"canSendVideos": false
}
}Success Response:
{
"success": true,
"data": {
"restricted": true
}
}promoteChatMember
Promote a user to admin with specific privileges, or demote by setting all to false.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| chatId | TEXT | Yes | Chat ID |
| userId | INT | Yes | User ID to promote |
| isAnonymous | BOOLEAN | No | Hide admin identity |
| canManageChat | BOOLEAN | No | Manage chat |
| canDeleteMessages | BOOLEAN | No | Delete messages |
| canManageVideoChats | BOOLEAN | No | Manage video chats |
| canRestrictMembers | BOOLEAN | No | Restrict members |
| canPromoteMembers | BOOLEAN | No | Promote members |
| canChangeInfo | BOOLEAN | No | Change chat info |
| canInviteUsers | BOOLEAN | No | Invite users |
| canPostMessages | BOOLEAN | No | Post in channels |
| canEditMessages | BOOLEAN | No | Edit in channels |
| canPinMessages | BOOLEAN | No | Pin messages |
| canManageTopics | BOOLEAN | No | Manage topics |
Configuration Example:
{
"chatId": "{{ctx.vars.chatId}}",
"userId": "{{ctx.vars.userId}}",
"canManageChat": true,
"canDeleteMessages": true,
"canRestrictMembers": true,
"canPinMessages": true
}Success Response:
{
"success": true,
"data": {
"promoted": true
}
}Bot Commands
setMyCommands
Set the list of commands shown in the bot's menu.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| commands | OBJECT | Yes | Array of command objects |
| languageCode | TEXT | No | Language code (ISO 639-1) |
Configuration Example:
{
"commands": [
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "Show help"},
{"command": "settings", "description": "Bot settings"}
]
}Success Response:
{
"success": true,
"data": {
"updated": true
}
}getMyCommands
Retrieve the current list of bot commands for the specified language.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| languageCode | TEXT | No | Language code (ISO 639-1) |
Configuration Example:
{}Success Response:
{
"success": true,
"data": {
"commands": [
{"command": "start", "description": "Start the bot"},
{"command": "help", "description": "Show help"}
]
}
}deleteMyCommands
Remove all bot commands for the specified language scope.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| languageCode | TEXT | No | Language code (ISO 639-1) |
Configuration Example:
{}Success Response:
{
"success": true,
"data": {
"deleted": true
}
}Updates
getUpdates
Receive incoming updates via long polling. Essential for AI agents building conversational bots.
Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| offset | INT | No | - | First update ID to return |
| limit | INT | No | 100 | Max updates (1-100) |
| timeout | INT | No | - | Long polling timeout |
| allowedUpdates | TEXT | No | - | Update types filter (comma-separated) |
Configuration Example:
{
"offset": "{{ctx.vars.lastUpdateId}}",
"limit": 100,
"timeout": 30
}Tip: Use offset = last_update_id + 1 to acknowledge processed updates.
Success Response:
{
"success": true,
"data": {
"updates": [
{
"update_id": 123456789,
"message": {
"message_id": 123,
"from": {"id": 987654321, "first_name": "John"},
"chat": {"id": -1001234567890, "type": "supergroup"},
"text": "Hello!"
}
}
]
}
}Triggers
Telegram Update
Receive real-time updates when messages or events occur in your bot via webhooks.
Supported Events
| Event Code | Event Name | Description |
|---|---|---|
message | Message | New message received in private chat or group |
edited_message | Edited Message | A message was edited by a user |
channel_post | Channel Post | New post published in a channel |
edited_channel_post | Edited Channel Post | A channel post was edited |
callback_query | Callback Query | User pressed an inline keyboard button |
inline_query | Inline Query | User typed @botname in any chat |
poll | Poll | Poll state changed (anonymous votes) |
poll_answer | Poll Answer | User changed their poll answer (non-anonymous) |
chat_member | Chat Member | Member status changed in a chat |
my_chat_member | My Chat Member | Bot's status changed in a chat |
chat_join_request | Chat Join Request | User requested to join a private chat |
Configuration Options
| Option | Type | Required | Description |
|---|---|---|---|
secret | TEXT | No | Secret token for webhook verification. Telegram sends this in X-Telegram-Bot-Api-Secret-Token header |
events | SELECT | Yes | Types of updates to receive. Select one or more from the events above |
Event Payload Examples
Message (message):
{
"update_id": 123456789,
"message": {
"message_id": 123,
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"last_name": "Doe",
"username": "john_doe",
"language_code": "en"
},
"chat": {
"id": -1001234567890,
"type": "supergroup",
"title": "My Group"
},
"date": 1704067200,
"text": "Hello, bot!"
}
}Callback Query (callback_query):
{
"update_id": 123456790,
"callback_query": {
"id": "callback_123",
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"username": "john_doe"
},
"message": {
"message_id": 456,
"chat": {
"id": -1001234567890,
"type": "supergroup"
}
},
"chat_instance": "1234567890123456789",
"data": "button_action"
}
}Inline Query (inline_query):
{
"update_id": 123456791,
"inline_query": {
"id": "inline_123",
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"username": "john_doe"
},
"query": "search term",
"offset": ""
}
}Poll Answer (poll_answer):
{
"update_id": 123456792,
"poll_answer": {
"poll_id": "5678901234567890123",
"user": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"username": "john_doe"
},
"option_ids": [0, 2]
}
}Chat Member (chat_member):
{
"update_id": 123456793,
"chat_member": {
"chat": {
"id": -1001234567890,
"type": "supergroup",
"title": "My Group"
},
"from": {
"id": 123456789,
"is_bot": false,
"first_name": "Admin"
},
"date": 1704067200,
"old_member": {
"user": {"id": 987654321, "first_name": "John"},
"status": "member"
},
"new_member": {
"user": {"id": 987654321, "first_name": "John"},
"status": "administrator"
}
}
}Chat Join Request (chat_join_request):
{
"update_id": 123456794,
"chat_join_request": {
"chat": {
"id": -1001234567890,
"type": "supergroup",
"title": "Private Group"
},
"from": {
"id": 987654321,
"is_bot": false,
"first_name": "John",
"username": "john_doe"
},
"date": 1704067200,
"bio": "Hello, I'd like to join!",
"invite_link": {
"invite_link": "https://t.me/+abc123",
"creator": {"id": 123456789}
}
}
}Webhook Setup: See the Setup Guide for trigger creation and bot configuration.
Accessing Trigger Data in Workflows
When using the Telegram trigger in workflows, access the incoming data via the ctx.nodes object:
{{ctx.nodes.{trigger_node_code}.outputs.data.message}}
{{ctx.nodes.{trigger_node_code}.outputs.data.callback_query}}Example - Sending a reply:
{
"chatId": "{{ctx.nodes.telegram_trigger.outputs.data.message.chat.id}}",
"text": "You said: {{ctx.nodes.telegram_trigger.outputs.data.message.text}}"
}Use Cases
Customer Support Bot
Build an automated customer support system that handles inquiries 24/7.
- Trigger: Telegram Update (message)
- Action: Process message with AI/NLP
- Action: Telegram
sendMessagewith response - Action: Telegram
sendChatAction(typing) for longer operations
Notification System
Send automated notifications from business systems to Telegram channels and groups.
- Trigger: Webhook from your application or Gmail trigger (new email)
- Action: Telegram
sendMessageorsendPhotowith notification - Optional: Add inline keyboard for quick actions via
answerCallbackQuery
Support Ticket Creation
Monitor incoming bot messages and create tickets in your project management system.
- Trigger: Telegram Update (message)
- Action: Parse message content
- Action: Linear
createIssuewith message details - Action: Telegram
sendMessagewith ticket confirmation
Group Moderation Bot
Automatically moderate group conversations using content analysis.
- Trigger: Telegram Update (message)
- Action: Analyze message content
- Action: Telegram
deleteMessageif inappropriate - Action: Telegram
restrictChatMemberif repeat offender - Action: Telegram
banChatMemberfor severe violations
Interactive Quiz Bot
Create engaging quiz experiences with polls and track scores.
- Action: Telegram
sendPollwith quiz type - Trigger: Telegram Update (poll_answer)
- Action: Track scores and Telegram
sendMessagewith results
Error Handling
Common Error Codes:
| Code | Description |
|---|---|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid bot token |
| 403 | Forbidden - Bot blocked or lacks permissions |
| 404 | Not Found - Chat or message doesn't exist |
| 409 | Conflict - Webhook/getUpdates conflict |
| 429 | Too Many Requests - Rate limited |
Error Response Format:
{
"success": false,
"error": {
"code": "TELEGRAM_ERROR",
"message": "Bad Request: chat not found"
}
}Resources
- Telegram Bot API Documentation
- BotFather - Create and manage bots
- Telegram Bot FAQ
- Axellero Workflows Documentation