Telegram

17 actions for messages, chats, files, media, search, and contacts. Uses MTProto (user impersonation) — you authenticate with your own Telegram account, not a bot.

Connection

Telegram uses phone-based authentication instead of OAuth. Click Connect on your dashboard and enter your phone number. Telegram sends a code to your app; enter it (and your 2FA password if enabled) to link your account.

Messages

`send_message`

Parameter	Type	Required	Description
`chat`	string	yes	Username (@user), phone (+1234567890), or chat ID
`text`	string	yes	Message text
`file`	string	no	URL or file path to attach (photo, document, video)
`reply_to`	number	no	Message ID to reply to

exec("telegram.send_message", {
  chat: "@username",
  text: "Meeting confirmed for 3pm"
})

`get_messages`

Parameter	Type	Required	Description
`chat`	string	yes	Username, phone, or chat ID
`limit`	number	no	Number of messages (default 20, max 100)
`offset_id`	number	no	Get messages before this message ID

`search_messages`

Parameter	Type	Required	Description
`query`	string	yes	Search query text
`chat`	string	no	Chat to search in (omit for global search)
`limit`	number	no	Max results (default 20, max 100)

exec("telegram.search_messages", {
  query: "meeting notes",
  limit: 10
})

`edit_message`

Parameter	Type	Required	Description
`chat`	string	yes	Chat where the message is
`message_id`	number	yes	ID of the message to edit
`text`	string	yes	New message text

`delete_messages`

Parameter	Type	Required	Description
`chat`	string	yes	Chat where the messages are
`message_ids`	array	yes	Array of message IDs to delete
`revoke`	boolean	no	Delete for everyone (default true)

`forward_messages`

Parameter	Type	Required	Description
`from_chat`	string	yes	Source chat
`to_chat`	string	yes	Destination chat
`message_ids`	array	yes	Array of message IDs to forward

`mark_read`

Parameter	Type	Required
`chat`	string	yes

Chats

`get_dialogs`

Parameter	Type	Required	Description
`limit`	number	no	Number of chats (default 30, max 100)
`archived`	boolean	no	Include archived chats

`get_chat`

Parameter	Type	Required
`chat`	string	yes

`get_participants`

Parameter	Type	Required	Description
`chat`	string	yes	Group/channel username or ID
`limit`	number	no	Max participants (default 50)

Contacts

`get_contacts`

No parameters. Returns the user's full contact list.

`resolve_username`

Parameter	Type	Required	Description
`username`	string	yes	Username to resolve (with or without @)

Files

`send_file`

Send a file (photo, document, GIF, voice note, video) to a chat. Pass a URL via file or a Gateway file_id from gateway.upload_file.

Parameter	Type	Required	Description
`chat`	string	yes	Username, phone, or chat ID
`file`	string	no	URL or file path to send
`file_id`	string	no	Gateway file ID (from `gateway.upload_file`)
`caption`	string	no	Caption text (supports markdown)
`force_document`	boolean	no	Send as document instead of auto-detecting
`voice_note`	boolean	no	Send as voice note
`video_note`	boolean	no	Send as round video note
`reply_to`	number	no	Message ID to reply to

Either file or file_id is required.

# Send a photo via URL
exec("telegram.send_file", {
  chat: "@username",
  file: "https://example.com/photo.jpg",
  caption: "Check this out"
})
 
# Send a file from Gateway storage
exec("telegram.send_file", {
  chat: "@username",
  file_id: "abc123",
  caption: "Q1 report attached",
  force_document: true
})

`send_gif`

Search for a GIF and send it using the @gif inline bot.

Parameter	Type	Required	Description
`chat`	string	yes	Username, phone, or chat ID
`query`	string	yes	GIF search query
`index`	number	no	Which result to send (0-based, default 0)

exec("telegram.send_gif", {
  chat: "@username",
  query: "celebration"
})

`download_media`

Download media (photo, file, voice) from a message. Returns base64-encoded data with metadata. Max 10MB for base64 response.

Parameter	Type	Required	Description
`chat`	string	yes	Chat containing the message
`message_id`	number	yes	Message ID with media to download

exec("telegram.download_media", {
  chat: "@username",
  message_id: 123
})
# → { data: "base64...", filename: "photo.jpg", mimeType: "image/jpeg", size: "12345" }

`send_sticker`

Search for a sticker and send it using the @sticker inline bot.

Parameter	Type	Required	Description
`chat`	string	yes	Username, phone, or chat ID
`query`	string	yes	Sticker search query or emoji
`index`	number	no	Which result to pick (0-based, default 0)

`send_dice`

Send an animated dice/emoji.

Parameter	Type	Required	Description
`chat`	string	yes	Username, phone, or chat ID
`emoji`	string	no	🎲 🎯 🏀 ⚽ 🎰 🎳 (default 🎲)

exec("telegram.send_dice", { chat: "@channel", emoji: "🎯" })

Chat Identifiers

The chat parameter accepts multiple formats:

Format	Example
Username	`@username`
Phone	`+1234567890`
Numeric ID	`123456789`