PowerShell Push Notifications powered by Boxcar

Not wanting to add to my already bursting email inbox and finding the need for a more immediate mobile notification of scripted events I find myself looking at https://boxcar.io and their end-user API .

The API provides an example on how to use the service with cURL so as before I will be converting this simple format to use the PowerShell Invoke-WebRequest cmdlet and wrap this into an advanced function.

Setup
•    Download the Boxcar iOS app
•    Get your Access Token and replace the value for the $user_credentials variable in the Param section of the function  – How to get the Token from the client app
•    Like all PowerShell functions you will need to run the code at least once and you can call it as many times as required for the session.

The best way to copy the code from a WordPress blog such as this one is to double click in the below window and then copy, this usually preserves the formatting.

function Send-BoxcarPush  {
<#
.SYNOPSIS
A function to send Boxcar Push messages.
.DESCRIPTION
An example of using PowerShell to send Universal Push Notification messages. Typically the target device is a mobile running iOS (https://boxcar.io/client) or Andriod.
.PARAMETER notificationTitle
Message Title/Subject. 140 Character Maximum.
.PARAMETER notificationLongMessage
Message body text. 1000 Character Maximum.
.PARAMETER notificationSound
Notification Sound played on receiving device. Default is ‘bird-1’, see the Available sounds list for options - https://boxcar.uservoice.com/knowledgebase/articles/306788-how-to-send-your-boxcar-account-a-notification
.PARAMETER hostURI
Default is usually fine.
.PARAMETER user_credentials
Boxcar Access Token. Its recommended you change this value in the Param section of this function else it will need to be specified each time. The access token is available from the general "Settings" screen of Boxcar Client app.
.EXAMPLE
Send-BoxcarPush -notificationTitle "Test Title" -notificationLongMessage "Body message text"
.NOTES
Author: John Milner
Blog  : https://jfrmilner.wordpress.com
File Name: Send-BoxcarPush.ps1
Author: jfrmilner
Email: jfrmilner@googlemail.com
Requires: Powershell v4 (May work on older versions but untested)
Legal: This script is provided "AS IS" with no warranties or guarantees, and confers no rights. You may use, modify, reproduce, and distribute this script file in any way provided that you agree to give the original author credit.
Version: v1.0 - 2014 March 1st - First Version
Version: v1.1 - 2014 March 2nd - Added URL Encoding
.LINK
https://jfrmilner.wordpress.com/2014/03/01/powershell-pus…ered-by-boxcar/
#>
Param(
[String]
[parameter(Mandatory=$true)]
[ValidateLength(1,140)]
$notificationTitle = "test"
,
[String]
[parameter(Mandatory=$true)]
[ValidateLength(1,1000)] #Max is 4kb so 1000 is playing safe.
$notificationLongMessage = "text here"
,
[String]
$notificationSound = 'bird-1'
,
[String]
$hostURI = 'https://new.boxcar.io/api/notifications' #HOST: This is the server to use to send HTTPS API calls.
,
[String]
$user_credentials = 'Put Your Access Token Here' #Access Token. Change this value to your own here or specify here.
)

BEGIN{
Add-Type -AssemblyName System.Web
}#begin
PROCESS{

try
{
$message = Invoke-WebRequest -Uri $hostURI -Method POST -Body "user_credentials=$($user_credentials)&notification[title]=$([System.Web.HttpUtility]::UrlEncode($notificationTitle))&notification[long_message]=$([System.Web.HttpUtility]::UrlEncode($notificationLongMessage))&notification[sound]=$($notificationSound)"
if ($message.StatusCode -eq 201) {
"Message Sent:"
$message.Content | ConvertFrom-Json
}
}

catch [System.Net.WebException]
{
Write-Host  -ForegroundColor Red $_.Exception.Message
switch -regex ($_.Exception.Message)
{
"401" {Write-Host  -ForegroundColor Red "Failure: Check Access Token"}
"404" {Write-Host  -ForegroundColor Red "Failure: No associated device"}
"422" {Write-Host  -ForegroundColor Red "Failure: Unprocessable Entity - All non UTF-8 encoding are rejected"}
default {Write-Host  -ForegroundColor Red $_.Exception.Message}
}

}

finally
{

}
}#process
END{}#end

}

Example

Boxcar deliver a great service which is free for 200 pushes per minute and its fast, very fast.
Boxcar notifications can use 20+ different sounds which I’m starting to find quite useful, for example you can have different scripts use different sounds which I just listen out for and this saves me having to look at the phone. I’m also thinking I could use different sounds for different levels of importance.

As always thank you for reading and if you found this post useful please share and/or leave a comment.

Regards, jfrmilner