PoshGram
PoshGram copied to clipboard
Published
20 hours ago •
techthoughts2
techthoughts2
Send messages via the Telegram Bot API using PowerShell
PoshGram
| Branch | Windows | MacOS | Linux |
|---|---|---|---|
| main |  |
 |
|
| Enhancements |  |
 |
Synopsis
PoshGram is a PowerShell module that enables you to send messages via the Telegram Bot API
Description
PoshGram provides functionality to send various message types to a specified Telegram chat via the Telegram Bot API. Separate PowerShell functions are used for each message type. Checks are included to ensure that file extensions, and file size restrictions are adhered to based on Telegram requirements.
PoshGram provides the following functions:
- Get-TelegramStickerPackInfo
- Send-TelegramContact
- Send-TelegramDice
- Send-TelegramLocalAnimation
- Send-TelegramLocalAudio
- Send-TelegramLocalDocument
- Send-TelegramLocalPhoto
- Send-TelegramLocalSticker
- Send-TelegramLocalVideo
- Send-TelegramLocation
- Send-TelegramMediaGroup
- Send-TelegramPoll
- Send-TelegramSticker
- Send-TelegramTextMessage
- Send-TelegramURLAnimation
- Send-TelegramURLAudio
- Send-TelegramURLDocument
- Send-TelegramURLPhoto
- Send-TelegramURLSticker
- Send-TelegramURLVideo
- Send-TelegramVenue
- Test-BotToken
Why
The Telegram Bot API requires very specific formatting and criteria for Bot messaging. The goal of this project is to abstract that complexity away in favor of simple and direct PowerShell commands.
PoshGram also opens up several programmatic use cases:
- Load PoshGram into Azure functions to alert you of potential conditions
- Load PoshGram into AWS Lambda to alert you of potential conditions
- Custom scripts tied to task scheduler could alert you to potential system conditions
- Test-LowDisk.ps1 tied to task scheduler --> leverages PoshGram to alert you if low disk condition found
- Enable a script to provide Telegram notifications
- In a ForEach you could easily message multiple chat groups that your bot is a member of
Installation
Prerequisites
- PowerShell 6.1.0 (or higher version)
- A Telegram Account
- Telegram Bot created
- Chat ID number
- Bot must be a member of the specified chat
Installing PoshGram via PowerShell Gallery
#from a 6.1.0+ PowerShell session
Install-Module -Name "PoshGram" -Scope CurrentUser
Quick start
#------------------------------------------------------------------------------------------------
#import the PoshGram module
Import-Module -Name "PoshGram"
#------------------------------------------------------------------------------------------------
#easy way to validate your Bot token is functional
Test-BotToken -BotToken $botToken
#------------------------------------------------------------------------------------------------
#send a basic Text Message
Send-TelegramTextMessage -BotToken $botToken -ChatID $chat -Message "Hello"
#------------------------------------------------------------------------------------------------
#send a photo message from a local source
Send-TelegramLocalPhoto -BotToken $botToken -ChatID $chat -PhotoPath $photo
#------------------------------------------------------------------------------------------------
#send a photo message from a URL source
Send-TelegramURLPhoto -BotToken $botToken -ChatID $chat -PhotoURL $photoURL
#------------------------------------------------------------------------------------------------
#send a file message from a local source
Send-TelegramLocalDocument -BotToken $botToken -ChatID $chat -File $file
#------------------------------------------------------------------------------------------------
#send a file message from a URL source
Send-TelegramURLDocument -BotToken $botToken -ChatID $chat -FileURL $fileURL
#------------------------------------------------------------------------------------------------
#send a video message from a local source
Send-TelegramLocalVideo -BotToken $botToken -ChatID $chat -Video $video
#------------------------------------------------------------------------------------------------
#send a video message from a URL source
Send-TelegramURLVideo -BotToken $botToken -ChatID $chat -VideoURL $videoURL
#------------------------------------------------------------------------------------------------
#send an audio message from a local source
Send-TelegramLocalAudio -BotToken $botToken -ChatID $chat -Audio $audio
#------------------------------------------------------------------------------------------------
#send an audio message from a URL source
Send-TelegramURLAudio -BotToken $botToken -ChatID $chat -AudioURL $audioURL
#------------------------------------------------------------------------------------------------
#send a map point location using Latitude and Longitude
Send-TelegramLocation -BotToken $botToken -ChatID $chat -Latitude $latitude -Longitude $longitude
#------------------------------------------------------------------------------------------------
#send an animated gif from a local source
Send-TelegramLocalAnimation -BotToken $botToken -ChatID $chat -AnimationPath $animation
#------------------------------------------------------------------------------------------------
#send an animated gif from a URL source
Send-TelegramURLAnimation -BotToken $botToken -ChatID $chat -AnimationURL $AnimationURL
#------------------------------------------------------------------------------------------------
#sends a group of photos or videos as an album from a local source
Send-TelegramMediaGroup -BotToken $botToken -ChatID $chat -FilePaths (Get-ChildItem C:\PhotoGroup | Select-Object -ExpandProperty FullName)
#------------------------------------------------------------------------------------------------
#send a contact's information
Send-TelegramContact -BotToken $botToken -ChatID $chat -PhoneNumber $phone -FirstName $firstName
#------------------------------------------------------------------------------------------------
#send information about a venue
Send-TelegramVenue -BotToken $botToken -ChatID $chat -Latitude $latitude -Longitude $longitude -Title $title -Address $address
#------------------------------------------------------------------------------------------------
#send a poll with a question and options
Send-TelegramPoll -BotToken $botToken -ChatID $chat -Question $question -Options $opt
#------------------------------------------------------------------------------------------------
#get information for a Telegram sticker pack
Get-TelegramStickerPackInfo -BotToken $botToken -StickerSetName STPicard
#------------------------------------------------------------------------------------------------
#sends Telegram sticker message from a local source
Send-TelegramLocalSticker -BotToken $botToken -ChatID $chat -StickerPath $sticker
#------------------------------------------------------------------------------------------------
#send Telegram sticker with known sticker file_id
Send-TelegramSticker -BotToken $botToken -ChatID $chat -FileID $sticker
#send Telegram sticker (best effort) with sticker pack name and emoji shortcode
Send-TelegramSticker -BotToken $botToken -ChatID $chat -StickerSetName STPicard -Shortcode ':slightly_smiling_face:'
#------------------------------------------------------------------------------------------------
#send a sticker message from a URL source
Send-TelegramURLSticker -BotToken $botToken -ChatID $chat -StickerURL $StickerURL
#------------------------------------------------------------------------------------------------
#send an animated emoji that will display a random value
Send-TelegramDice -BotToken $botToken -ChatID $chat -Emoji $emoji
#------------------------------------------------------------------------------------------------
###########################################################################
#sending a telegram message from older versions of powershell
###########################################################################
#here is an example of calling PowerShell 6.1+ from PowerShell 5.1 to send a Telegram message with PoshGram
& 'C:\Program Files\PowerShell\6\pwsh.exe' -command { Import-Module PoshGram;$token = '#########:xxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxx';$chat = '-nnnnnnnnn';Send-TelegramTextMessage -BotToken $token -ChatID $chat -Message "Test from 5.1 calling 6.1+ to send Telegram Message via PoshGram" }
#--------------------------------------------------------------------------
#here is an example of calling PowerShell 6.1+ from PowerShell 5.1 to send a Telegram message with PoshGram using dynamic variables in the message
$token = “#########:xxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxx”
$chat = “-#########”
$test = "I am a test"
& '.\Program Files\PowerShell\6\pwsh.exe' -command "& {Import-Module PoshGram;Send-TelegramTextMessage -BotToken $token -ChatID $chat -Message '$test';}"
#--------------------------------------------------------------------------
#here is an example of calling PowerShell 7+ from PowerShell 5.1 to send a Telegram message with PoshGram
& 'C:\Program Files\PowerShell\7-preview\pwsh.exe' -command { Import-Module PoshGram;$token = '#########:xxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxx';$chat = '-nnnnnnnnn';Send-TelegramTextMessage -BotToken $token -ChatID $chat -Message "Test from 5.1 calling 7+ to send Telegram Message via PoshGram" }
#--------------------------------------------------------------------------
FAQ
PoshGram - FAQ
Author
Jake Morrison - https://www.techthoughts.info/
Contributors
- Justin Saylor - Logo
- Mark Kraus - PowerShell 6.1 Form handling advice
- Andrew Pearce - CI/CD advice
Notes
For a description of the Bot API, see this page: https://core.telegram.org/bots/api
This PowerShell project was created with Catesta.
License
This project is licensed under the MIT License.
Changelog
Reference the Changelog
Metadata
132
Stars
13
Forks
Watchers
Owner
techthoughts2
Metadata
Send messages via the Telegram Bot API using PowerShell