logo_smallAxellero.io

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

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

ParameterTypeRequiredDescription
tokenTEXTYesTelegram Bot token from @BotFather

Setup Instructions: See the Setup Guide for authentication configuration, connector creation, and webhook setup.

Available Operations

CategoryOperationDescription
Bot InformationgetMeGet information about the bot
MessagessendMessageSend a text message to a chat
MessagesforwardMessageForward a message from one chat to another
MessagescopyMessageCopy a message without the forward header
MessageseditMessageTextEdit the text of a message
MessageseditMessageCaptionEdit the caption of a media message
MessageseditMessageMediaReplace the media content of a message
MessageseditMessageReplyMarkupEdit the inline keyboard of a message
MessagesdeleteMessageDelete a message from a chat
MediasendPhotoSend a photo to a chat
MediasendDocumentSend a document/file to a chat
MediasendVideoSend a video file to a chat
MediasendAudioSend an audio file to a chat
MediasendAnimationSend a GIF or video without sound
MediasendVoiceSend a voice message (OGG/OPUS)
MediasendMediaGroupSend multiple photos/videos as an album
StickerssendStickerSend a sticker to a chat
StickersgetStickerSetGet a sticker set by name
Location & ContactssendLocationSend a location point on the map
Location & ContactssendVenueSend a venue with name and address
Location & ContactssendContactSend a phone contact
InteractivesendPollSend a poll (regular or quiz)
InteractivesendDiceSend a random dice animation
InteractiveanswerCallbackQueryRespond to inline keyboard button press
InteractiveanswerInlineQuerySend results for inline queries
InteractivesetMessageReactionReact to a message with an emoji
InteractivesendChatActionDisplay typing indicator or other action
Chat InformationgetChatGet information about a chat
Chat InformationgetChatMemberGet information about a chat member
Chat InformationgetFileGet file info and download URL
Chat ManagementpinChatMessagePin a message in a chat
Chat ManagementunpinChatMessageUnpin a message
Chat ManagementsetChatTitleChange the chat title
Chat ManagementbanChatMemberBan a user from a chat
Chat ManagementunbanChatMemberUnban a user
Chat ManagementrestrictChatMemberRestrict user permissions
Chat ManagementpromoteChatMemberPromote user to admin
Bot CommandssetMyCommandsSet the bot's command menu
Bot CommandsgetMyCommandsGet current bot commands
Bot CommandsdeleteMyCommandsDelete bot commands
UpdatesgetUpdatesReceive 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
textTEXTYes-Message content
parseModeTEXTNoMarkdownV2Formatting mode (HTML/Markdown/MarkdownV2)
disableNotificationBOOLEANNofalseSend silently
replyToMessageIdINTNo-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:

ParameterTypeRequiredDescription
chatIdTEXTYesDestination chat ID
fromChatIdTEXTYesSource chat ID
messageIdINTYesMessage ID to forward
disableNotificationBOOLEANNoForward 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Destination chat ID
fromChatIdTEXTYes-Source chat ID
messageIdINTYes-Message ID to copy
captionTEXTNo-New caption
parseModeTEXTNoMarkdownV2Caption 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTNo*-Chat ID (required with messageId)
messageIdINTNo*-Message ID to edit
inlineMessageIdTEXTNo*-Inline message ID (alternative)
textTEXTYes-New message text
parseModeTEXTNoMarkdownV2Text 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTNo*-Chat ID (required with messageId)
messageIdINTNo*-Message ID to edit
inlineMessageIdTEXTNo*-Inline message ID (alternative)
captionTEXTNo-New caption (empty to remove)
parseModeTEXTNoMarkdownV2Caption 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:

ParameterTypeRequiredDescription
chatIdTEXTNo*Chat ID (required with messageId)
messageIdINTNo*Message ID to edit
inlineMessageIdTEXTNo*Inline message ID (alternative)
mediaOBJECTYesNew 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:

ParameterTypeRequiredDescription
chatIdTEXTNo*Chat ID (required with messageId)
messageIdINTNo*Message ID to edit
inlineMessageIdTEXTNo*Inline message ID (alternative)
replyMarkupOBJECTNoNew 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID containing the message
messageIdINTYesMessage 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
photoTEXTYes-Photo to send: file_id, HTTP/HTTPS URL, or base64 data
captionTEXTNo-Photo caption
parseModeTEXTNoMarkdownV2Caption 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
documentTEXTYes-Document to send: file_id, HTTP/HTTPS URL, or base64 data
captionTEXTNo-Document caption
parseModeTEXTNoMarkdownV2Caption 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
videoTEXTYes-Video to send: file_id, HTTP/HTTPS URL (YouTube NOT supported), or base64 data
captionTEXTNo-Video caption
parseModeTEXTNoMarkdownV2Caption formatting mode
durationINTNo-Duration in seconds
widthINTNo-Video width
heightINTNo-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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
audioTEXTYes-Audio to send: file_id, HTTP/HTTPS URL, or base64 data
captionTEXTNo-Audio caption
parseModeTEXTNoMarkdownV2Caption formatting mode
durationINTNo-Duration in seconds
performerTEXTNo-Performer name
titleTEXTNo-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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
animationTEXTYes-Animation to send: file_id, HTTP/HTTPS URL, or base64 data
captionTEXTNo-Animation caption
parseModeTEXTNoMarkdownV2Caption 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
voiceTEXTYes-Voice to send: file_id, HTTP/HTTPS URL, or base64 data (OGG/OPUS only)
captionTEXTNo-Voice message caption
parseModeTEXTNoMarkdownV2Caption formatting mode
durationINTNo-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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
mediaOBJECTYesArray 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
stickerTEXTYesSticker file_id (recommended) or HTTP URL of .WEBP/.TGS/.WEBM file
emojiTEXTNoAssociated emoji for search
disableNotificationBOOLEANNoSend 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:

ParameterTypeRequiredDescription
nameTEXTYesSticker 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:

ParameterTypeRequiredDefaultDescription
chatIdTEXTYes-Chat ID or @username
latitudeFRACTIONALYes-Latitude coordinate
longitudeFRACTIONALYes-Longitude coordinate
livePeriodINTNo3600Live 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
latitudeFRACTIONALYesLatitude coordinate
longitudeFRACTIONALYesLongitude coordinate
titleTEXTYesVenue name
addressTEXTYesVenue address
foursquareIdTEXTNoFoursquare ID
googlePlaceIdTEXTNoGoogle Places ID
disableNotificationBOOLEANNoSend 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
phoneNumberTEXTYesPhone number
firstNameTEXTYesFirst name
lastNameTEXTNoLast name
vcardTEXTNovCard data (0-2048 bytes)
disableNotificationBOOLEANNoSend 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
questionTEXTYesPoll question (1-300 chars)
optionsOBJECTYesArray of option strings (2-10)
isAnonymousBOOLEANNoAnonymous poll (default: true)
typeTEXTNo"regular" or "quiz"
allowsMultipleAnswersBOOLEANNoAllow multiple answers
correctOptionIdINTNoCorrect 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID or @username
emojiTEXTNoDice type (default: dice)
disableNotificationBOOLEANNoSend 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:

ParameterTypeRequiredDefaultDescription
callbackQueryIdTEXTYes-Callback query identifier
textTEXTNo-Notification text (0-200 chars)
showAlertBOOLEANNofalseShow alert instead of toast
urlTEXTNo-URL to open
cacheTimeINTNo300Cache 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:

ParameterTypeRequiredDefaultDescription
inlineQueryIdTEXTYes-Query identifier
resultsOBJECTYes-Array of results (max 50)
cacheTimeINTNo300Cache time (0-3600 seconds)
isPersonalBOOLEANNofalseUser-specific caching
nextOffsetTEXTNo-Pagination offset
buttonOBJECTNo-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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
messageIdINTYesMessage ID to react to
emojiTEXTNoEmoji (empty to remove reaction)
isBigBOOLEANNoShow 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
actionTEXTYesAction 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
userIdINTYesUser 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:

ParameterTypeRequiredDescription
fileIdTEXTYesFile 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
messageIdINTYesMessage ID to pin
disableNotificationBOOLEANNoPin 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
messageIdINTNoMessage 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
titleTEXTYesNew 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
userIdINTYesUser ID to ban
untilDateINTNoUnix timestamp for ban expiry
revokeMessagesBOOLEANNoDelete 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
userIdINTYesUser ID to unban
onlyIfBannedBOOLEANNoOnly 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
userIdINTYesUser ID to restrict
permissionsOBJECTYesPermissions object
untilDateINTNoRestriction expiry timestamp
useIndependentChatPermissionsBOOLEANNoUse 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:

ParameterTypeRequiredDescription
chatIdTEXTYesChat ID
userIdINTYesUser ID to promote
isAnonymousBOOLEANNoHide admin identity
canManageChatBOOLEANNoManage chat
canDeleteMessagesBOOLEANNoDelete messages
canManageVideoChatsBOOLEANNoManage video chats
canRestrictMembersBOOLEANNoRestrict members
canPromoteMembersBOOLEANNoPromote members
canChangeInfoBOOLEANNoChange chat info
canInviteUsersBOOLEANNoInvite users
canPostMessagesBOOLEANNoPost in channels
canEditMessagesBOOLEANNoEdit in channels
canPinMessagesBOOLEANNoPin messages
canManageTopicsBOOLEANNoManage 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:

ParameterTypeRequiredDescription
commandsOBJECTYesArray of command objects
languageCodeTEXTNoLanguage 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:

ParameterTypeRequiredDescription
languageCodeTEXTNoLanguage 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:

ParameterTypeRequiredDescription
languageCodeTEXTNoLanguage 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:

ParameterTypeRequiredDefaultDescription
offsetINTNo-First update ID to return
limitINTNo100Max updates (1-100)
timeoutINTNo-Long polling timeout
allowedUpdatesTEXTNo-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 CodeEvent NameDescription
messageMessageNew message received in private chat or group
edited_messageEdited MessageA message was edited by a user
channel_postChannel PostNew post published in a channel
edited_channel_postEdited Channel PostA channel post was edited
callback_queryCallback QueryUser pressed an inline keyboard button
inline_queryInline QueryUser typed @botname in any chat
pollPollPoll state changed (anonymous votes)
poll_answerPoll AnswerUser changed their poll answer (non-anonymous)
chat_memberChat MemberMember status changed in a chat
my_chat_memberMy Chat MemberBot's status changed in a chat
chat_join_requestChat Join RequestUser requested to join a private chat

Configuration Options

OptionTypeRequiredDescription
secretTEXTNoSecret token for webhook verification. Telegram sends this in X-Telegram-Bot-Api-Secret-Token header
eventsSELECTYesTypes 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.

  1. Trigger: Telegram Update (message)
  2. Action: Process message with AI/NLP
  3. Action: Telegram sendMessage with response
  4. Action: Telegram sendChatAction (typing) for longer operations

Notification System

Send automated notifications from business systems to Telegram channels and groups.

  1. Trigger: Webhook from your application or Gmail trigger (new email)
  2. Action: Telegram sendMessage or sendPhoto with notification
  3. Optional: Add inline keyboard for quick actions via answerCallbackQuery

Support Ticket Creation

Monitor incoming bot messages and create tickets in your project management system.

  1. Trigger: Telegram Update (message)
  2. Action: Parse message content
  3. Action: Linear createIssue with message details
  4. Action: Telegram sendMessage with ticket confirmation

Group Moderation Bot

Automatically moderate group conversations using content analysis.

  1. Trigger: Telegram Update (message)
  2. Action: Analyze message content
  3. Action: Telegram deleteMessage if inappropriate
  4. Action: Telegram restrictChatMember if repeat offender
  5. Action: Telegram banChatMember for severe violations

Interactive Quiz Bot

Create engaging quiz experiences with polls and track scores.

  1. Action: Telegram sendPoll with quiz type
  2. Trigger: Telegram Update (poll_answer)
  3. Action: Track scores and Telegram sendMessage with results

Error Handling

Common Error Codes:

CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid bot token
403Forbidden - Bot blocked or lacks permissions
404Not Found - Chat or message doesn't exist
409Conflict - Webhook/getUpdates conflict
429Too Many Requests - Rate limited

Error Response Format:

{
  "success": false,
  "error": {
    "code": "TELEGRAM_ERROR",
    "message": "Bad Request: chat not found"
  }
}

Resources