Hi there! Did you ever wonder how to send a PI Notification via Telegram Messenger? It as not as hard as you might think! Actually, with this tutorial, I hope to make it as easy as possible for you!

 

In PI Notifications 2016 R2, you have two delivery options: Email and Web Service. We will configure a Web Service. In the end, this Web Service will be a contact in PI System Explorer, just like the email contacts that you probably already use.

 

This is the list of what you will need, the versions I used and some useful links (i'll not include pre-requisites, check the manuals):

 

 

Ok, now we are ready to start!!

 

  

STEP 1: Configure a Telegram Bot

 

Apart from the Bots: An introduction for developers and the Telegram Bot API Manual, there are several videos on YouTube that teach you how to do this. This one helped me a lot!

 

Take note of your bot ID. Quoting their website: "Each bot is given a unique authentication token when it is created. The token looks something like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11, but we'll use simply <token> in this document instead."

 

You will also need the chat ID of the person you want to send the message to.

 

The easiest way is to send a message to the bot and access the getUpdates website. There you will find the message and the chat ID from the sender. This video may help you.

 

The website will be https://api.telegram.org/bot<token>/getUpdates where <token> is your bot token.

 

Now that you have your bot token and chat id (from the person you want to send message to), let's configure the website.

  

  

STEP 2: Configure a Web Service

 

I hope you followed the How to Install and Configure a PHP Website on IIS link above and have a functional website. You don't need anything fancy, just guarantee it is functional by loading a default document. In this case, it may be a simple file named index.php in the root directory of the website, containing the following line of code (Notepad++ may help you a lot):

 

<?php phpinfo(); ?>

 

If you are able to see the php information website, when you access your website URL, it is functional. Remember to configure the security, I'm using HTTPS and Kerberos Authentication.

 

Remember the NuSOAP - SOAP Toolkit for PHP I talked about earlier? Now is a good time to unzip the folder you downloaded and place the lib folder in your website root directory. Also, go to the php installation directory (mine is: "C:\Program Files\PHP\v7.0"), find the php.ini file and comment the following line, if you find it (the semicolon is the comment character):

 

;extension=php_soap.dll

 

Good. Now let's create a php file called server.php. Below is a sample code, but remember, you will need to change some things to adapt it to your environment, particularly URLs and Telegram token and IDs. It is commented and I'm placing what you need to change between percentage signs, like this: %YOU_NEED_TO_CHANGE_THIS%.

 

SERVER.PHP:

 

<?php

// SOAP
// call library
require_once('lib/nusoap.php');

// CHANGE THE FOLLOWING LINE!!!
$URL = "%YOUR_WEBSITE_URL%/server.php";
$namespace = $URL.'?wsdl';

// using soap_server to create server object
$server = new soap_server;
$server->configureWSDL('TelegramMessage', $namespace);

// register a function that works on server
// I named the function after myself. Feel free to change it to whatever you like, just remember to be consistent throughout the code. 
// Using a name on it helps configuring the contact in PI System Explorer later.
$server->register('TelegramVictorWolf', array ("message" => "xsd:string", "message2" => "xsd:string"), array("return" => "xsd:string"));

// create the function
function TelegramVictorWolf($message, $message2)
{
  // Telegram Settings
  // CHANGE THE FOLLOWING LINE!!!!!
  $botToken = "%YOUR_BOT_TOKEN%";
  $website = "https://api.telegram.org/bot".$botToken;

  // CHANGE THE FOLLOWING LINE!!!!
  $chatId = "%CHAT_ID_OF_THE_PERSON_THAT_WILL_RECEIVE_THE_MESSAGE%"; // Log Settings
  $filename = "log.txt";
  $date = date("d-M-Y H:i:s");

  $fullmessage = $message.$message2;

  if (!$fullmessage) 
  {
  // Message Log
        file_put_contents($filename , "LOG... Current Time: ".$date.". ERROR.<br>\n \r\n", FILE_APPEND);
        return new soap_fault('Client', '', 'Victor');    
  }

  // Sends Telegram Message
  file_get_contents($website."/sendmessage?chat_id=".$chatId."&text=".$fullmessage);

  // Message Log
  file_put_contents($filename , "LOG... Current Time: ".$date.". Message is: ".$fullmessage.".<br>\n \r\n", FILE_APPEND);

  // Function Return
  // CHANGE THE FOLLOWING LINE
  $result = "The following message was sent to %YOUR_NAME_HERE%'s Telegram: ".$fullmessage;
  return $result;
}


$rawPostData = file_get_contents("php://input");
$server->service($rawPostData);
exit();
     
?>

 

To check if it is working, access your website (ending in /server.php) and you should get something like this:

 

If you click the function name, in my case TelegramVictorWolf, you should see something like this:

 

 

And clicking on WSDL should give something like this:

 

 

Now that you have a functioning web service, let's configure the part that is actually in the PI System!

 

  

STEP 3 - Configure a contact on PI System Explorer

 

Now it's the easy part!

 

Just follow the steps:

 

2016-12-20 10_20_07-2016-12-09 15_28_31-__VWOLF-VM3_Test - PI System Explorer (Administrator).png

  1. Open your PI System Explorer and go to the Contacts tab.
  2. Right click "Delivery Endpoints" and choose "New Delivery Endpoint".
  3. Choose a name for your Delivery Endpoint.
  4. In the Delivery Channel drop-down list, choose "WebService".
  5. Fill in your Web Service Address and click on "Get Web Services". This should fill the drop-down lists below.
  6. Choose the correct Web Service and Web Method and Check In!

 

I'm assuming you already have a functioning notification rule, sending an email. If you do not, check out this playlist on our YouTube OSIsoftLearning Channel!

 

Go to your notification rule and click on View/Edit Subscriptions.

 

 

You'll find your contact under "Delivery Endpoints". Just click and drag to the Subscriptions area!

 

 

Now you need to configure it. Click on the little wrench:

 

 

In our case, there will be two messages available, concatenated in the server code. I used a String Builder Attribute on the first one and the Event Frame ID on the second, so I can build the exact message I want to deliver.

 

If you are curious on how I configured the String Builder attribute:

 

 

Web Service Configuration:

 

 

Click OK, then OK again. Check in and that's it! Make sure your notification rule is started.

 

Oh, look! I just received a message!

 

 

Now I can click on the link and access PI Coresight, to see or Acknowledge the Event Frame:

 

 

How about that?

 

Voilà! You made it!!! Congratulations! I told you it was going to be simple!

 

I hope this functionality will help you on your job!