Introduction

This guide will outline the necessary steps to create a REST service from which text messages can be sent, which will reach Telegram groups using a Telegram bot.

To achieve this, the «node-red-contrib-telegrambot» package will be used to connect with Telegram in a quick and straightforward manner.

To follow this tutorial, it is essential to have a personal Telegram account.

Steps

Access to Flow Engine

The first step will involve accessing the Flow Engine module, which is located in the Logic > My Flows menu.

The list of available Flow Engine instances will then be displayed. If there are none for the user currently logged in, a new one can be created by clicking the "+" button located in the top right corner of the screen:

As with other resources in Onesait Platform, a user with a role other than "administrator" can only have a single instance of Flow Engine.

The Flow Engine creation wizard will appear, where you will need to specify both the unique identifier and the limits for the states of the sockets.

For this tutorial, you only need to specify the name of the instance.

Once created, the screen will return to the list of Flow Engine instances. You will need to start it by clicking the "▶" button located in the instance's properties.

After a few seconds, the instance will start. To access it, you will need to click the "👁" button:

Setting up the workspace and installing the necessary packages

Once inside the Flow Engine instance, it is recommended to create a new workspace tab. To do this, click the "+" button located in the top right corner.

This will generate a new tab. By double-clicking on the name of the tab, you can access its properties, where you can change the name. In this case, the tab has been renamed to "Telegram API":

After changing the name, the next step will be to install the Telegram dependency for Node-RED. To do this, navigate to the ≡ > Manage palette menu.

The window with the manager for nodes and dependencies that can be installed will then be displayed. Click on the "Install" tab and search for "telegrambot" in the search bar:

Once located, click the "Install" button to install the dependencies. Once completed, a window will appear showing the added nodes.

Create the REST API to send the messages

The following nodes will be used for this step:

Input:
- onesaitplatform api rest operation
- onesaitplatform api rest
Output:
- onesaitplatform api rest operation response

First, the ‘onesaitplatform api rest’ node shall be searched for and added, which can be found in the node list on the left side of the screen:

Once on the canvas, double-clicking on the node will take you to its properties, where you will have to fill in some fields.

Name: the name of the API; in this case, ‘APITelegram’.
Description: a short text describing the functionality of the API.
Categories: the availability will be selected; in this case ‘ALL’.

The ‘onesaitplatform api rest operation’ node will then be added:

As in the previous case, once in the canvas, click twice to access its properties, where it will be configured as follows:

Method: the type of API operation. In this case, ‘POST’ type will be chosen.
URL: ‘/sender’ will be indicated.
Description: optional text describing the operation.
Query params: this field is used to perform queries and filters, if needed. In this case, nothing will be entered.

At the bottom is a notation indicating that the URL refers to the name of the Flow Engine instance that has been specified. This value will be different for each user most of the time.

Once the node is configured, it will be merged with the previously created node.

When the flow is deployed, these two nodes will automatically create the corresponding REST API service, with the generated POST operation.

Finally, the ‘onesaitplatform api rest operation response’ block will be added, which will be used to indicate what the response of the call is (expecting a 200, indicating that everything went well).

Once added to the canvas, its properties will be accessed in the same way as in the previous cases.

In this case, it will only be necessary to add the value ‘200’ to the ‘Status code’ field, to indicate that the operation has succeeded.

As a good practice, an error capture node will be added to the flow to indicate when something fails. To do this, another ‘onesaitplatform api rest operation response’ node shall be created, configured with a status code of 500, and a ‘catch’ node shall be added to it beforehand, which shall be linked to the node.

It should look something like this:

The ‘catch’ node will be configured later, as the creation of the flow progresses.

Preparing the bot message

The next step is to add a function node.

This node will be edited to add the following code, the purpose of which is to transform the call and pass the necessary options for the bot node.

var message = msg.payload.text || 'empty message.';
var chatId = msg.payload.chatId || -4630946845
msg.payload = { chatId: chatId, type : 'message', content : message};

// activate markdown
msg.payload.options = {disable_web_page_preview : true, parse_mode : "Markdown"};
return msg;

The chatId property refers to the Telegram group identifier; the value shown here refers to an internal example. This will be discussed further below.

This node shall be connected to the ‘onesaitplatform api rest operation response’ node as follows:

Telegram bot configuration

Next, a Telegram bot will be generated. To do this, we will use BotFather:

https://telegram.me/BotFather

After entering the indicated URL, click on the ‘Start Bot’ button:

If nothing happens when you click on the button, or if an error occurs, it will be necessary to launch BotFather from the Telegram web application using a personal user.

Once the chat with BotFather has been started, a list of available actions will be displayed:

The first thing to do is to create a new bot with the command /newbot (or click on the bot link). The BotFather will then ask for the name you want the bot to have:

You will then be asked for the bot's username, which must be unique and end in ‘bot’:

Bot names are universal, so they must be unique. If a bot with that name already exists, even if it has not been created by the user, it cannot be created.

If everything has gone well, you will receive a response message indicating that the bot has been created, with the URL to access the bot, as well as the HTTP API service token.

Configuring the Telegram node

Going back to the Flow Engine canvas, the ‘sender’ node within the Telegram group will be searched for and dragged.

After adding it, you will have to open its properties to select the bot to use and the name of the node.

As there are probably no previous bots, the first thing to do is to create a new one by clicking on the ‘🖉’ button:

A window will then open where you will have to configure the bot you created in the previous step.

There are several options to configure, but you only need to enter:

Bot-Name: the user name of the bot that has been created (not what it will be called). In the case of the example, ‘onesaitplatform002bot’.
Token: the token associated with the bot that must always be kept safe and never shared with anyone or anywhere. It will be in the style of 1234567890:EsTeToKeNeSuNiNvEnTdEcUiDaDo.

This node will have to be connected to the previous function's node, which will look like this:

Create a group in Telegram and add the bot

From Telegram, create a new user group. To do this, click on the ‘🖉’ button at the bottom and select ‘New Group’ from the different options.

You will then be shown a list of all available contacts to add to the group. However, instead, the search engine will be used to find the bot, which will appear with its unique name:

Finally, you will be asked to characterise the group with a profile picture as well as the name of the group.

Once created, the group will be available in the user's chat list:

Before finishing with this part, it is important to save, together with the bot's username and token, the identifier of the group created. This can be extracted from the group's URL:

Testing the sending of messages

With the group configured, the next step will be to test that everything works correctly. To do this, first of all, the flow that has been created so far will be deployed to generate the REST API and its POST operation.

To do this, just click on the ‘Deploy’ button.

If everything works as expected, a notification will be displayed indicating that the deployment was successful, and a status will be displayed in the Telegram bot indicating that you are connected.

Next, navigate in another tab to the Logic > My APIs menu.

The list of APIs available to the user will be displayed, and it will be possible to check that the API defined in the Flow Engine is created:

In the API options, the ‘Swagger’ option shall be selected:

The list of available bot API operations will then be accessed:

You will have to authorise the use of the operations beforehand by adding the user token in the ‘Authorise’ section.

To send the message, the first thing to do is to set up the JSON object of the message to be sent. It consists of two properties:

text: with the body text to send.
chatId: the unique identifier of the group, which was obtained from the URL as seen previously.

Thus, as an example text could be sent:

{
  "text": "Good morning, starshine... the earth says hello!",
  "chatId": -4781592641
}

This object shall be inserted in the body of the POST operation:

By clicking on the ‘Execute’ button, the message will be launched and, if everything went well, it will be received in the Telegram group.

Interestingly, it is possible to send formatted text via markdown.

Configuring the Catch

The bot is now working, but before finishing, there is one last step to complete, and that is to configure the Catch node that was created several steps before, and now we are ready to configure it properly.

What you have to do is open its properties and select the ‘selected nodes’ option in the error selector:

This will enable a list of nodes, from which the following must be chosen:

Once this is done, the node will be saved. This will be used so that, if an error occurs both in the function that sends the message and in the node that sends it to Telegram, an error message will be displayed.

Finally, the flow created will be deployed again and the last changes will be updated, leaving everything as follows:

platform-doc-en

How to create a Rest API with Flow Engine that sends messages to Telegram groups