Creating a Telegram bot
We are looking for @BotFather
.
We say /newbot
.
We enter title
and username
.
We get a token
.
We can add a picture to the new bot by telling BotFather /setuserpic
and uploading a picture.
Calling the bot from Totum
Creating a button in Totum that makes a test call to the telegram-api
:
= : linkToDataJson(title: "Answer"; data: $extr)
extr: jsonExtract(text: $getfs)
getfs: getFromScript(uri: str`"https://api.telegram.org/bot" + $token + "/" + $command`)
token: "YOUR_BOT_TOKEN"
command: "getMe"
Execute and see the response with our bot's data β if not, check where the error occurred.
Adding Remout in Totum
Next, create a Remout
in Totum to receive incoming messages from our bot.
Go to System tables
β Main
β API
β Remotes
.
Add a Remout
with name
: telegram_bot_incoming_HASH
(replace HASH
with your random sequence of 6-10 characters) and select remote_user
.
Add a simple table for testing: incoming_from_bot
with the field incoming_message
of type Data in the row part.
In the remout code, write the addition of a row to this table when a hook
comes in:
=: insert(table: 'incoming_from_bot'; field: 'incoming_message' = $extract)
extract: jsonExtract(text: $#input)
Registering the Remout address in the bot
Register our hook
in the bot (replace HOST
with your host):
= : linkToDataJson(title: "Answer"; data: $extr)
extr: jsonExtract(text: $getfs)
getfs: getFromScript(uri: str`"https://api.telegram.org/bot" + $token + "/" + $command`; post: "url" = "https://HOST/Remotes/telegram_bot_incoming"; post: "secret_token" = $secret_token)
token: "YOUR_BOT_TOKEN"
command: "setWebhook"
secret_token: "goldenBrown"
in url
pass https://HOST/Remotes/telegram_bot_incoming
(replace HOST
with your host)
in secret_token
any arbitrary phrase. You can use A-Z
, a-z
, 0-9
, _
and -
. This phrase will be used by the bot to sign when sending a message to your Totum.
Execute and you can check the set hook address:
= : linkToDataJson(title: "Answer"; data: $extr)
extr: jsonExtract(text: $getfs)
getfs: getFromScript(uri: str`"https://api.telegram.org/bot" + $token + "/" + $command`)
token: "YOUR_BOT_TOKEN"
command: "getWebhookInfo"
Connecting to the bot
Now we search for our bot in telegram
by @your_bot_username
and send it a message, then check the received data in the incoming_from_bot
table.
We are interested in #message[chat][id]
β this is the id
we need to send a reply message.
The bot sends a message
Now let's try to send a message to the user:
= : linkToDataJson(title: "Answer"; data: $extr)
extr: jsonExtract(text: $getfs)
getfs: getFromScript(uri: str`"https://api.telegram.org/bot" + $token + "/" + $command`; post: "chat_id" = "169521867"; post: "text" = $text)
token: "YOUR_BOT_TOKEN"
command: "sendMessage"
text: "Some great text!"
If it arrives, then everything is okay and we can attach the sending of the required notification to the trigger.
Sending buttons in the message
By default, when using getFromScript
, if the content type is not specified in the header, the data is sent as application/x-www-form-urlencoded
.
Thus, the array passed to the posts parameter is sent to the Telegram server. In this array, chat_id and text are strings (which is fine), but reply_markup is a Totum structure and Telegram cannot read it.
In reply_markup
, it expects text in json format, which needs to be created using jsonCreate.
I made a few minor adjustments, and the resulting code looks like this:
=: getFromScript(uri: $link; post: "text" = $message; post: "chat_id" = "CHAT_ID_HERE"; post: "reply_markup" = $markup)
// Generating the link
~link: str`"https://api.telegram.org/bot" + "BOT_KEY_HERE" + "/sendMessage"`
// Message text
~message: "Test message 3"
// Markups
markup: jsonCreate(data: $row)
row: rowCreate(field: "inline_keyboard" = $list)
list: listCreate(item: $row_list_buttons)
row_list_buttons: rowlistCreate(field: "text" = $buttons; field: "callback_data" = $urls)
~buttons: listCreate(item: "Approve"; item: "Reject")
~urls: listCreate(item: "https://host1.com"; item: "https://host2.com")
Conclusion
This is the simplest bot sending notifications, but the Telegram API allows for a huge number of things https://core.telegram.org/bots/api#available-methods.
Now that you know the general method of interacting with the bot, you can program your own.
Checking the secret phrase when calling the webhook
To check the secret phrase when the webhook
is triggered, modify the code in Remotes
:
=: if(condition: $#headers["X-Telegram-Bot-Api-Secret-Token"][0] = "goldenBrown"; then: $insert)
insert: insert(table: 'incoming_from_bot'; field: 'incoming_message' = $extract)
extract: jsonExtract(text: $#input)
Please note that the secret key comes in the header X-Telegram-Bot-Api-Secret-Token
(the name of which contains hyphens -
) where it is stored in a list
and the key is in the first element of this list
. To ensure Totum can access this key, it must be specified in quotes!