| Table of Contents |
|---|
Introduction
Telegram is a widespread messaging service for all kinds of platforms and devices (similar to WhatsApp).
While WhatsApp only supports sending end-to-end messages from one physical mobile phone number to another, Telegram allows the creation of custom "Bots".
...
Essentially, it works like this:
Inside the Telegram app on your mobile phone, you create a custom bot, which can then be used to publish messages to
The created bot has a unique "Token" and "Chat ID", which can be seen as a physical mobile phone number of a contact
The NETx BMS Core Server can now send messages to your bot, which you will instantly receive on your mobile phone
| Note |
|---|
...
Keep in mind |
...
that everyone knowing your secret "Token" and "Chat ID" is able to push messages to your |
...
bot. |
...
remember to treat this information confidently. |
Prerequisites
A Telegram account is required
Download the telegram app for your operating system on your mobile phone
Follow the instructions to create an account or use your existing account, if you already have one
Create a custom Telegram bot
| Info |
|---|
In this tutorial, the configuration of the custom bot is performed on iOS, but works similarly on other operating systems, such as Android. |
Telegram uses a special account called "BotFather", which is used to create and manage custom bots on your mobile phone.
To create a custom bot, open the Telegram application and search for "BotFather", click the BotFather account to open the chat.
...
BotFather initially shows a list of all available commands. All commands need to start with a slash ( / ). To create a new bot, we need to use the /newbot command.
As you start typing, BotFather will automatically suggest available commands. Click the "newbot" command. The BotFather will then ask you to provide some information for your new bot.
Once you're done giving your bot a username and a name (the username of the bot needs to end in with "bot"), the BotFather will text you the unique token of your bot.
As mentioned in the introduction, this is the unique identifier of your bot, which you will need to send messages to it.
Copy or write down the token now, because we will need it later on when configuring Telegram for the NETx BMS Core Server.
...
Great! You have created a custom bot.
Add the bot to your contacts and initiate a conversation
Now that you've added a custom bot, we need to add it to your contact list and initiate a conversation so that it's ready to receive messages from us.
Enter the name or username of your new bot in the search bar (both "NETxTutorialBot" in our case) and click it. The conversation opens.
Click the "Start" button to initiate the conversation and send an initial messages so that everything's set up correctly (for example "hello").
...
Perfect. You have initiated a conversation with your new bot. This means that it's almost ready to be used. The last step is to retrieve the chat ID, which is the unique identifier of the initiated conversation.
Retrieve the chat ID
This one is a bit tricky. As already mentioned, the chat ID represents the unique identifier of the initiated conversation between you and your bot. The reason that you also need a chat ID is,
that you could, for example, add your bot to a group conversation as well. Therefore, the bot token itself is not enough to identify where to push the message to. So in order to know where to publish messages to,
Telegram requires a combination of both the token (unique identifier of YOUR bot) plus the chat ID of a conversation (in this case, the 1:1 conversation with you and your bot).
...
Open a web browser (for example Google Chrome), and enter the following urlURL:
https://api.telegram.org/bot<bot token>/getUpdates
where you need to replace <bot_token> with your bot's unique token. In our example:
https://api.telegram.org/bot794823343:AAHYbhf59s0TZacUFpwrghqpUBQJOakacZ8/getUpdates
It may occur that this request won't return the desired results, which should look similar to this:
...
If this happens, just send another message from your mobile phone to your bot and try it again.
If everything has been set up correctly, you should receive a JSON response containing the required chat ID, which should look similar to this:
...
Write down the chat ID, in this case "569011464", because we'll need it in the next step.
Well done, you have now finished setting everything up. Now let's configure your telegram bot within the NETx BMS Core Server.
Configure your Telegram bot within the NETx BMS Core Server
Open the [Live] Twitter configuration within the Messenger Module menu entry.
and add a new definition (right click, Insert new definition).
...
Give your telegram configuration profile a reasonable name, for example "Tutorial", if we're using the NETxTutorialBot in this profile. Use the noted token and chat ID of your bot and save the configuration (no restart required).
...
All done. You are now able to send messages to your custom bot within the NETx BMS Platform.
Send a message via XLogic
As mentioned in the Messenger module configuration, NETx BMS Platform ships with pre-built messenger Commands.
We can use the MESSENGER.SENDTELEGRAMMESSAGE XCommand to send a test message to our bot.
Select the Menu → Tools → Run XCommand... in the NETx BMS Core Studio.
...
Select the MESSENGER.SENDTELEGRAMMESSAGE XCommand, enter the name of the previously configured profile and a test message (note: if the profile name does not exist or if this parameter is blank, the first found Telegram definition will be used).
Click "Execute". You should now receive the entered message within the Telegram application on your mobile phone.
...
You can now use this Telegram messenger profile whenever you want to send a message to your bot (for example in an action within the Web Manager).
Send a message via LUA
you can send telegram message within LUA scripts. To do so, you have to use the LUA function XMessage.
XMessage is general LUA function that can be used to send notification and visualization message via LUA. For sending telegram messages, the following parameter values must be used:
Device: not used for sending Telegram messages. Leave it empty.
User: not used for sending Telegram messages. Leave it empty.
Type: the string value "Telegram" must be used.
Profile: enter the name of your Telegram profile that you want to use to send the message.
Message: message text as string.
For sending a Telegram message with profile "Tutorial", use the following LUA code:
| Code Block |
|---|
nxa.XMessage("","","Telegram","Tutorial", "Hello from NETx BMS Core Server!") |