A Telegram from CORTROL

Sending notifications from a VMS to an external system has always been a wanted feature. Whether a night alarm or a camera has gone offline, you cannot rely on the live operators alone. So how do you get those into your phone?

Emails and short messages are standard methods for doing this—but what about modern approaches?

WhatsApp seems to be a trending messenger these days, but its API is closed and pricey. Luckily, there are other options. Let's look at Telegram: it has an open and powerful API, and it's also relatively safe, so why not start there?

Wait, What?

Telegram is a free personal and business messaging app with growing popularity. No surprise: it doesn't pass your messages to Facebook's featured ads and has a convenient choice of clients (web, mobile, and desktop).

Most users choose Telegram because of its safety but remember it is only as safe as its servers (which is always the case if you think about it). Also, the audience size and the amount of media content is growing, so you can chat, read news, and share files with others from across your clients within the app—and even use video chat!

If you don't have it, start installing your preferred Telegram client. The simplest way is to use web.telegram.org. Then, for enhanced mobility, get the app for your Android or iOS. Of course, don't forget there are dedicated desktop clients for your Windows, Mac, and Linux environments.

On your CORTROL server-side, install the latest CORTROL version for HTTPS supported, starting from CORTROL v.1.21.0. This is required as Telegram does not accept plain HTTP communications but requires HTTPS safety and security.

Now, we're ready to start, and the first step is to create a robot. (And it will be nothing like Optimus Prime!)

Create a Bot

How? Ask the "botfather" for a favor. Make sure to do it with respect.

Open your Telegram app and search for @BotFather — then make him an offer he can't refuse! Just type /newbot and follow the guidelines.

In the same chat window, you can modify the bot settings, set a picture, and add commands; for now, its existence is enough. At this point, the most important thing you need is the API token from the botfather, as you will need it to form requests.

SECURITY NOTE
Never let anyone know your bot token! It will give them complete control over your bot. If you think the token has been compromised, ask the botfather to revoke the current token. Users can be careless, but not I.T. administrators!

Now you can send yourself messages using the bot.

Behind Every Successful Frontend, There's Configuration

We must understand how the Telegram API works to build the message link. Don't worry; there's just a tiny bit of it required here (but you can dive in if you want). All queries to the Telegram Bot API must be served over HTTPS and need to be presented in the following format:

https://api.telegram.org/bot[BOT_API_KEY]/sendMessage?chat_id=[CHANNEL_USERNAME]&text=[MESSAGE_TEXT]

Here is an example:

https://api.telegram.org/bot1234567890:AAAAxY6udNO5u-9fO793yFdZaL1qU2RIkGT /sendMessage?chat_id=585858493&text=Hello World

(Don't worry, the API token is a dummy from Telegram's API description!)

There's a simple algorithm used to send direct messages to any user:

1. Find out their I.D. (chat_id).
2. Then, ask them to send a message to your bot first (for security reasons, bots cannot initiate chats).

So, if the first recipient is you, find out your chat I.D., and then send any message to your newly-created bot. To get your user ID: ask @userinfobot or other bots that give similar info (@RawDataBot, @getidsbot, a quick google shows quite a few).

Having done that, form a URL, which will send a message to your bot using the following format:

https://api.telegram.org/bot123456:A BC-DEF1234gh/k/-zyx57W2v1u123eWI1/sendMessage?

chat_id=000000000&text=Hello World

• "123456:ABC-DEF1234gh/k/-zyx57W2v1u123ew11" is the bot token
• “sendMessage” is the Telegram API method
• "000000000" is the chat identifier parameter of the target user or channel
• "Hello World" is the message you wish to pass.

This should be enough for you to start enjoying the CORTROL-to-your-bot message flow. Next, you can test the request by copying it into the browser address bar. If the message were sent successfully, the produced output in the browser window would start with OK: true, followed by result parameters. If you get a 404 or a similar error, carefully check the link and try again.

Broadcast: a Channel or a Group

Apart from sending the messages privately to a single user, it is also possible to deliver them to multiple recipients simultaneously. Telegram has groups and channels for this. Which one should you choose?

* Channels allow you to broadcast passively to a list of users

• Theoretically, this may be an unlimited audience
• Chances are, you will want a private channel for a CCTV alert broadcast

* Groups allow all members to post messages, too

• This leaves room for a discussion
• It also means all users will be able to see each other.

You are free to create any number of either private or public channels (remember that anyone can join the public one). Why not create a separate private channel for the I.T. guys and another for the company managers? Add your bot as an admin for each channel and allow it to post messages. For groups, invite your bot to participate as a regular user—the rest is the same.

Any Arguments?

Now, let's see what happens on the CORTROL side. Traditionally, the Event & Action Configurator is responsible for automation—and this case is no exception. Add a new action of the Send HTTP Request type and fill in the fields. As you have seen above, all you need is a carefully-built link containing the target and the message.

Depending on your use case and source event, you might want to add some event-related values to your message. For example, you can pass arguments from the event that triggered the message, such as {EVENT_SOURCE_TITLE} or {ADDITION_INFORMATION}.

Right-click the text box or click the Insert field button to see the list of available variables. Their availability depends on the originating event type. For example, the following macros are useful if a recognition event triggers the action:

• {ADDITION INFORMATION:Plate} — Recognizes and lists the license plate for LPR
• {ADDITION_INFORMATION:Subject} — Recognizes and lists the subject name for facial recognition
• {ADDITION INFORMATION:Tag} — Recognizes and lists the item tag if available

Other fields refer to the event source, e.g., a channel:

{EVENT_SOURCE_ID} — Internal identifier of the target channel (can be used for building CORTROL API links)

{EVENT_SOURCE_TITLE} — Channel name

For other event sources (user buttons, doors, servers), their corresponding names will be reflected for other event sources.

Now, use your action to build a rule, as usual.

TROUBLESHOOTING‍After creating the action rule, verify if CORTROL can successfully execute it by clicking the Test button in the Rules tab. Next, check the Audit Log section > Servers to see the execution report. If the HTTP response is not OK, use Wireshark to check the details.

Can I Get Video, Too?

Of course! Check this one out: not just a message but a direct link to the live video stream!

You will need to build an API link to the live video stream and add it to the message. The link looks like this:

* http://[CORTROL_server_IP]:[CORTROL_HTTP_port]/publicLive/[channel_ID]/mainStream

Or, since we're all for security here:

* https://[CORTROL_server_IP]:[CORTROL_HTTPS_port]/publicLive/[channel_ID]/mainStream

Make sure you have HTTPS enabled, and it is set up on the CORTROL side!

TROUBLESHOOTING
Use plain HTTP at the configuration phase, as it will allow you to see the exact request and the Telegram response via Wireshark. Once your messages are coming through, switch to HTTPS before finalizing the setup.

The message will contain another link in it in this case. The Send HTTP Request action does not support some characters and multi-line commands, but that's not a problem: we shall use a different action—Run Program. The Run Program action executes an external file with the specified parameters, so there is much more freedom.

The general plan is:

1. Create a script
2. Add a Run Program action
3. Add permissions

Here is an example of a CURL command in the executable file. It includes both plain text and a channel URL, plus it uses a parameter (%1, which will be passed from the action):

With CURL, you can put the whole request between quotation marks and freely use blank spaces and special characters inside.

Now, the action:

{EVENT SOURCE_ID} will be used as an argument (%1 for the batch file in this example; if you're using a different scripting language, check its instructions on passing the parameters).

This takes care of sending the correct message to your Telegram client. Next, combine this action with events of your choice in your desired CORT ROL server: these may be motion events, triggered analytics, opened doors, or customers buying certain items in the shops. Don't forget you can also dispatch multiple actions based on a single event.

For Justice, We Must Go to Permission Management

Finally, one last step: add permission so that you can open the link. For this, go to your target channel's Permissions > find Anonymous in the user list > give them the permission to View live video. This will allow you (and anyone you share the link with) to see the video.

Congratulations! Now you know how to set up notifications for Telegram! Hopefully, you will use those bots for security and other automated systems like intelligent homes or access control.

Have you set up CORTROL notifications for another messenger? Please share your experience with us!

P.S. There's good news for those who prefer traditional methods: we add SMS sending in the next major release, CORTROL version 1.22! Keep an eye out for the next release's announcement.

‍