Send messages via the Telegram Bot API using PowerShell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.vscode Initial commit Jul 3, 2018
docs
media
test
PoshGram.psd1
PoshGram.psm1 Initial commit Jul 3, 2018
README.md

README.md

PoshGram

PowerShell Gallery Minimum Supported PowerShell Version

Synopsis

PoshGram is a PowerShell module that enables you to send messages via the Telegram Bot API

PoshGram Gif Demo

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:

Why

The Telegram Bot API requires very specific formatting criteria for Bot messaging. The goal of this project to abstract that complexity away in favor of simple and direct PowerShell functions.

PoshGram also opens up several programmatic use cases:

  • 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 script to provide Telegram notifications
  • In a ForEach you could easily message multiple chat groups that your bot is a member of

Installation

Prerequisites

Installing PoshGram via PowerShell Gallery

#from an administrative 6.1.0+ PowerShell session
Install-Module -Name "PoshGram"

Installing PoshGram direct from GitHub

  1. Create the following directory: C:\Program Files\WindowsPowerShell\Modules\PoshGram
  2. Download Zip from GitHub
  3. Extract files
  4. Copy the extracted files into the created directory

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 URL source
Send-TelegramLocalAudio -BotToken $botToken -ChatID $chat -Audio $audio
#--------------------------------------------------------------------------
#send an audio message from a local source
Send-TelegramURLAudio -BotToken $botToken -ChatID $chat -AudioURL $audioURL
#--------------------------------------------------------------------------
###########################################################################
#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-preview\pwsh.exe' -command { Import-Module PoshGram;$token = "#########:xxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxx";$chat = "-#########";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-preview\pwsh.exe' -command "& {Import-Module PoshGram;Send-TelegramTextMessage -BotToken $token -ChatID $chat -Message '$test';}"
#--------------------------------------------------------------------------

Author

Jake Morrison - http://techthoughts.info/

Contributors

Justin Saylor - Logo

Notes

  • PoshGram Video Demo

  • PoshGram Blog Write-up

  • Why is PowerShell 6.1.0 required? - Why can't I use 5.1?

    • For new files to be uploaded and sent to a chat via bot, Telegram requires the use of multipart/form-data. This is not natively supported in 5.1. It is available in 6.0.0, but requires the manual creation of the form. 6.1.0 introduces native form capabilities. Functions that reference a URL, or that only use messaging (Send-TelegramTextMessage) are 5.1 compatible. However, you would have to pull these functions out separately if you are absolutely set on using 5.1
  • I don't want to use PowerShell 6.1.0 because I primarily use 5.1 or lower

    • Good news - PowerShell 6.1.0 installs to a completely separate folder, has a completely different exe (pwsh.exe), and references a different module path. This means you can install it on any system and use PoshGram while continuing to use any other version of PowerShell

    • Here is an example of how you can call PS 6.1 and use PoshGram 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-preview\pwsh.exe' -command { Import-Module PoshGram;$token = "#########:xxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxx";$chat = "-#########";Send-TelegramTextMessage -BotToken $token -ChatID $chat -Message "Test from 5.1 calling 6.1 to send Telegram Message via PoshGram" }
  • I want to start using this, but how do I create a Telegram Bot and get a token?

  • I've got a bot setup, and I have a token, but how do I determine my channel ID?

    • Forward a message from your channel to the getidsbot https://telegram.me/getidsbot
    • Use the Telegram web client and copy the channel ID in your browser's address bar
      • Don't forget to include the (-) before the channel number
        • Ex "-#########"
  • Are there any restrictions when using PoshGram?

    • Bots can currently send files of up to 50 MB in size
    • Certain functions are limited to certain file extensions, see each function's documentation for more information

For a description of the Bot API, see this page: https://core.telegram.org/bots/api