node-red-contrib-telegrambot
Version:
Telegram bot nodes for Node-RED
919 lines (679 loc) • 83.6 kB
Markdown
# Telegram bot nodes for Node-RED
[](https://nodered.org)
[](https://www.npmjs.com/package/node-red-contrib-telegrambot)
[](https://www.npmjs.com/package/node-red-contrib-telegrambot)
[](https://www.npmjs.org/package/node-red-contrib-telegrambot)
[](https://snyk.io/test/npm/node-red-contrib-telegrambot)
[](https://t.me/nodered_telegrambot)
[](https://packagequality.com/#?package=node-red-contrib-telegrambot)
[](https://github.com/windkh/node-red-contrib-telegrambot/issues)
[](https://github.com/windkh/node-red-contrib-telegrambot/issues?q=is%3Aissue+is%3Aclosed)
...
This package contains a receiver and a sender node which act as a Telegram Bot.
The only thing required is the `token` that can be retrieved by the `@botfather` [Telegram Bot](https://core.telegram.org/bots).
# Thanks for your donation
If you want to support this free project. Any help is welcome. You can donate by clicking one of the following links:
<a target="blank" href="https://blockchain.com/btc/payment_request?address=1PBi7BoZ1mBLQx4ePbwh1MVoK2RaoiDsp5"><img src="https://img.shields.io/badge/Donate-Bitcoin-green.svg"/></a>
<a target="blank" href="https://www.paypal.me/windkh"><img src="https://img.shields.io/badge/Donate-PayPal-blue.svg"/></a>
<a href="https://www.buymeacoffee.com/windka" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
# Credits
- dvv (Vladimir Dronnikov): for providing the saveDataDir configuration option
- snippet-java: for adding venue messages and for providing the markdown problem fallback
- greenstone7: for providing the callback query node
- dceejay: for cleaning up the project
- psyntium: for providing the weblink for additional content link videos, pictures, animations, audio files
- MatthiasHunziker: for extending the callback query node to support generic events
- Skiepp: for providing the send chat action idea.
- MK-2001: for providing the sendMediaGroup fuhttps://github.com/yagop/node-telegram-bot-apinction
- cowchimp: for adding the support for `Node-RED v1.0+` (async)
- JokerQyou: for adding the support for using webhook without certificate
- bonastreyair: for providing ideas for improving the command node
- StephanStS: for extension/clearification/beautification of Readme.md and finding minor bugs
- Diddlik: for extending webhook options
- MorbidDevil: for extending answerInlineQuery with options
- daredoes: for providing the webhook decumentation on Unraid/Docker with SWAG/NGINX/REVERSE-PROXY
- kickouille: for fixing the payment functions and providing the full payment example flow
- skrashevich: for providing approveChatJoinRequest, declineChatJoinRequest
- ShotokanZH: for providing the web app data example
- Dodoooh: for providing the send to topic example flow
- MariusSchiffer: for improving documentation
- ptath: for providing pullrequest for setChatAdministratorCustomTitle
- gmag11: for providing pullrequest for enhancing getFile
- ivanjh: for providing the patch for improving output of polling errors
- GrimbiXcode: for replacing pump with pipeline
- y8: for providing ideas for improving receiver node
# 👥 Contributors
<p align="center">
<a href="https://github.com/windkh/node-red-contrib-telegrambot/graphs/contributors">
<img src="https://contrib.rocks/image?repo=windkh/node-red-contrib-telegrambot" />
</a>
</p>
# Installation
[](https://nodei.co/npm/node-red-contrib-telegrambot/)
You can install the nodes using node-red's "Manage palette" in the side bar.
Or run the following command in the root directory of your Node-RED installation
npm install node-red-contrib-telegrambot --save
Note that the minimum node-red version 1.3.7 and minimum nodejs version is 12.x.
# Dependencies
The nodes are tested with `Node.js v18.20.0` and `Node-RED v3.1.9`.
- [node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api)
- [socks-proxy-agent](https://www.npmjs.com/package/socks-proxy-agent)
# Changelog
Changes can be followed [here](/CHANGELOG.md).
# Hints
- It is recommended to always do a full deploy when you changed some of the nodes of this library to prevent unexpected behavior.
- Do not use a token in more than one configuration node at the same time as the telegram server does not allow multiple connections for one bot.
# Usage
## Basics
### Receiver and sender nodes
The *Telegram receiver* node receives messages from the bot and sends a message object with the following layout:
`msg.payload` contains the message details with the following elements:
- ***chatId*** : The unique id of the chat. This value needs to be passed to the out node when responding to the same chat
- ***type*** : The type of message received. Types see table below
- ***content*** : Received message content: String or file_id, or object with full data (location, contact)
- Additional:
- ***date*** (Optional element): Date the message was sent in Unix time (integer)
- **further elements** depending on the *type* (see table below)
`msg.originalMessage` contains the original message object from the underlying [**node-telegram-bot-api**](https://github.com/yagop/node-telegram-bot-api) lib.
`msg.telegramBot` contains the bot details object which can be used inside the flow to find out what bot received the message`.
The *Telegram sender* node sends the content to a specified username or chat. The node's input `msg` object is similar to the output `msg` object of the *Telegram receiver* node. Some of the additional elements are mandatory and some are optional (see table below).
A simple echo flow looks like:
[**echo flow**](examples/echo.json)
**Fig. 1:** Simple echo flow
### Types of telegram messages
The following message contents can be sent and received (given in `msg.payload.type`):
- **message** - content is text
- **photo** - content is the file_id of the photo with the highest resolution
- **audio** - content is the file_id of the audio file
- **document** - content is the file_id of the document
- **sticker** - content is the file_id of the sticker
- **animation** - content is the file_id of the animation file
- **dice** - content is a dice
- **video** - content is the file_id of the video file
- **video_note** - content is the file_id of the video note file
- **voice** - content is the file_id of the voice file
- **location** - content is an object with latitude and longitude
- **venue** - content is the venue object
- **contact** - content is the contact information object
- **poll** - content is a poll object
- **invoice** - content is an invoice for a payment
- **successful_payment** - content is a service message about a successful payment
Note that media groups are sent/received not as a group, but as separate messages of type photo and video.
The following `msg.payload.type` contents indicate changes in the group or channel itself:
- **new_chat_title** - content is the new chat title
- **new_chat_photo** - content is the file_id (see photo)
- **new_chat_members** - content is an array of new chat members
- **left_chat_member** - content is an object describing the chat member that left
- **delete_chat_photo** - content is true
- **pinned_message** - content is the pinned message object
- **channel_chat_created** - content is true
- **group_chat_created** - content is true
- **supergroup_chat_created** - content is true
- **migrate_from_chat_id** - content is the chat id. The chat property describes the chat.
- **migrate_to_chat_id** - content is the chat id. The chat property describes the chat.
For more details of the content types listed above also refer to the [**telegram api description**](https://core.telegram.org/bots/api#available-types).
### Message types and corresponding *content* elements in `msg.payload`
The `msg.payload` contains several elements additional to *chatId*, *type* and *content*. These additional elements depend on the contents of `msg.payload.type`. In addition the format of `msg.payload.content` depends on the *type*.
The following table shows the relationship between the message *type* and additional elements.
| *msg.payload.type* | *msg.payload.content* | *chat* | *caption* | *blob* | *photos* | *mediaGroupId* |
| :- | :- | :-: | :-: | :-: | :-: | :-: |
| **message** | text |-|-|-|-|-|
| **photo** | photo[index].file_id |-| optional | true | + | optional |
| **audio**| audio.file_id | - | optional | true | - | - |
| **dice**| dice | - | - | false | - | - |
| **sticker**| sticker.file_id | - | - | true | - | - |
| **animation**| animation.file_id | - | optional | true | - | optional |
| **video**| video.file_id | - | optional | true | - | optional |
| **video_note**| video_note.file_id | - | - | true | - | - |
| **voice**| voice.file_id | - | optional | true | - | - |
| **location**| location | - | - | - | - | - |
| **venue**| venue | - | - | - | - | - |
| **contact**| contact | - | - | - | - | - |
| **document**| document.file_id | - | optional | true | - | - |
| **poll**| poll | - | - | - | - | - |
| **invoice**| invoice | - | - | - | - | - |
| **successful_payment**| successful_payment | - | - | - | - | - |
| **new_chat_title**| new_chat_title | - | - | - | - | - |
| **new_chat_photo**| new_chat_photo[index].file_id | - | - | true | + | - |
| **new_chat_members**| new_chat_members | - | - | - | - | - |
| **left_chat_member**| left_chat_members | - | - | - | - | - |
| **delete_chat_photo**| delete_chat_photo | - | - | - | - | - |
| **pinned_message**| pinned_message | - | - | - | - | - |
| **channel_chat_created**| channel_chat_created | - | - | - | - | - |
| **group_chat_created**| group_chat_created | + | - | - | - | - |
| **supergroup_chat_created**| supergroup_chat_created | + | - |- | - | - |
| **migrate_from_chat_id**| migrate_from_chat_id | + | - | - | - | - |
| **migrate_to_chat_id**| migrate_to_chat_id | + | - | - | - | - |
Legend:
- **-** : Element is not present in `msg.payload` structure
- **+** : Element is mandatory in `msg.payload` structure
- **optional** : Element is optional in *Sender* node and always present in *Receiver* node
- **true** : Element is mandatory and has to be set to boolean value *true*
**Tab. 1:** Data elements in `msg.payload` depending on `msg.payload.type`
For more details of the content types listed above also refer to the [**telegram api description**](https://core.telegram.org/bots/api#available-types) and the [**telegram bot api description**](https://core.telegram.org/bots/api).
### Error handling
There are two ways of how to handle errors in the sender node:
1. Default: all errors can be handled in a catch-all node.
2. Enable second output: errors are sent to this additional output. The msg contains an additional `msg.error` property.
<img src="images/TelegramBotErrorHandling2.png" title="Sender node dialog" width="600" />
**Fig. 2:** Sender node dialog
[**error handling example flow**](examples/errorhandling.json)
## Configuration Node
The mandatory configuration entries are
- the *Bot-Name* and
- the *Token*
which you received from @botfather when creating a new bot.
<img src="images/TelegramBotConfigurationNodeDialog.png" title="Configuration node dialog" width="600" />
**Fig. 3:** Configuration node dialog
### Reading token from external location
Instead of entering the token from bot father directly into the token field, you can also instruct the node to read ot from on external location.
#### Reading token from environment variable
Environment variables are entered in the settings.js of node-red before startup.
```javascript
process.env.BOT_TOKEN = "<your bot token here>";
```
The token field in the configuration node must then look like
```javascript
{env.get("BOT_TOKEN")}
```
### Configuration properties *Users* and *ChatIds*
The node contains the two optional properties: ***Users*** and ***ChatIds***. You may enter a list of names and/or chatIds that are authorized to use this bot. This is useful, if the bot should only accept incoming calls from dedicated persons resp. chat groups.
The values in the property fields must be separated by a comma e.g.:
Hugo,Sepp,Egon
Leave the fields *Users* and *ChatIds* blank if you do not want to use this feature to mask senders.
User names can only be used, if a telegram user has set its Username in the Telegram settings. The following screenshot shows the according settings dialog in the Telegram app where you can set your personal preferences:
<img src="images/TelegramSettingsUsername.png" title="Telegram user name settings" width="350" />
**Fig. 4:** Telegram app settings dialog (example Android phone app)
If no *Username* is set you can only filter via the *ChatId* property.
### Configuration property *Server URL*
This is the server url of the telegram server (https://api.telegram.org). If you use a different instance of a telegram server somewhere else (e.g. on premise) you could then use this property to connect to that server instead the global one.
Typically this field is left blank.
### Configuration property *Test Environment*
This enables the test environment see: (https://core.telegram.org/bots/features#testing-your-bot).
Typically this checkbox is unchecked.
### Configuration property *Update Mode*
The update mode can be chosen from *Polling* or *Webhook*.
#### Polling mode
By default the bot is polling every 300ms for new messages. This polling interval can be set via the property ***Poll Interval*** in the Do you mean a table which describes the logic within the function getMessageDetails(botMsg)?
E.g. a table with these coloumns:
- text: chatId, messageId, type (= "message"), content (text)
- photo: chatId, messageId, type (= "photo"), content (photo[index].file_id with index = different photo sizes), caption, date, blob (= true), photos (???), mediaGroupId
- audio: chatId, messageId, type (= "audio"), content (file_id), cation, date, blob (= true)
...*Polling Options*.
#### Webhook mode
The *Webhook* method may be chosen to avoid polling.
<img src="images/TelegramBotWebHookConfiguration.png" title="Webhook configuration with self signed sertificate" width="350" />
**Fig. 5:** Example configuration for webhook mode
As setting up a webhook can be very complex depending on the infrastructure this was moved to a seprate readme file.
See also [WEBHOOK.md](WEBHOOK.md)
#### None mode
The *None* method may be chosen to avoid traffic due to polling or incoming webhook calls.
You can only send messages using the sender node but you can not receive any data.
### Configuration property *IP address family*
You can force a certain IP version to be used when making requests to the telegram server.
Normally this is up to the operating system und you can just keep the default setting "Any".
If you discover problems e.g. the telegram server is unreachable. Then you can try to force
using IPv4 or IPv6.
### Configuration property flag *Use SOCKS*
SOCKS4/5 proxy support is optional when running behind a SOCKS4/5 proxy that requires authentication. In this case, additional configuration properties have to be set in the configuration node.
As setting up a socks5 proxy can be very complex depending on the infrastructure this was moved to a seprate readme file.
See also [SOCKS5.md](SOCKS5.md)
### Configuration property flag *Verbose Logging*
The ***Verbose Logging*** flag should only be activated when debugging network problems as this will create cyclic warnings when the network is down.
## Receiver Node
This node can **receive telegram messages** sent to the bot and (under certain circumstances) also **receive messages from a chat**.
**Fig. 6:** Receiver node appearance
**Telegram messages** sent directly to the bot are automatically received (if not masked via the configuration node property *Users*).
To be able to receive **telegram chat messages**, invite the bot to a chat (/setprivacy must be configured correctly!). If the configuration node property *ChatIds* is not set, all chat messages are received.
You can control if the bot receives every message by calling **/setprivacy @botfather** (refer also to [**there**](https://core.telegram.org/bots/features#privacy-mode)).
Note that there are certain limitations for bots in channels, groups and super groups. You should make the bot admin or grant the rights if you discover problems. Bot to bot communication is also not allowed by telegram. Please read the telegram bot documentation.
### Configuration
#### Configuration property *Download Directory*
When the receiver node receives data like videos, documents and so on, the file is downloaded automatically to the local harddisc when the node's property ***Download Directory*** is set in the configuration node. The directory may also be part of the message payload: `msg.payload.path`.
In addition to that the message object may contain the direct download link in the payload: `msg.payload.weblink`.
#### Configuration property *Events*
Next to messages the bot receives a number of events which can be received using the event node. By activating this flag all events are handled by the receiver node, too.
#### Configuration property *Filter*
Normally, a receiver node receives all content that is sent to the bot. However if you have command nodes next to a receiver you can enable the *commands* flag in the configuration property ***Filter*** so that commands meant for a command node will not be handled by the receiver node.
I.e. the command message then only appears in the configured command node and not in this node.
#### Configuration property *Message Input*
Enable this checkbox if you want to receive updates from telegram using an external source (like http node, mqtt). The format must match the one provided by telegram. It is recommended to disable webhook and polling in config node when providing updates from external sources via this input.
See the example flow [**control bot**](examples/externalreceiverl.json) in the examples folder.
<details>
<summary>Click to expand code snippet for <em><b>message</b></em> example</summary>
```javascript
{
update_id: 276165414,
message: {
message_id: 6196,
from: {
id: 1234,
is_bot: false,
first_name: "Bigfoot",
last_name: "VLOG",
username: "Bigfoot",
language_code: "de",
},
chat: {
id: 1234,
first_name: "Bigfoot",
last_name: "VLOG",
username: "Bigfoot",
type: "private",
},
date: 1763891508,
text: "Hello guys!",
},
}
```
</details>
See the example flow [**control bot**](examples/externalreceiver2.json) in the examples folder.
### Outputs
The original message from the underlying node library is stored in `msg.originalMessage`. The `msg.payload` contains the most important data like **chatId**, **type** and **content**. Additional elements are present in the `msg.payload` structure and depend on the message *type*. These additional elements are described in the table **Tab. 1** above.
The content format depends on the message type. E.g. if you receive a text message then the content format is a string, if you receive a location, the content format is an object containing latitude and longitude. See also ["available methods" in the api core description](https://core.telegram.org/bots/api#available-methods).
The node has two outputs:
1. The node's upper output (***Standard Output***) is used if the message is from an authorized user.
2. The node's lower output (***Unauthorized Output***) is used when security is applied (via configuration properties *Users* and *ChatIds*) and the user is not authorized to access the bot.
## Sender Node
This node **sends contents** to a telegram user or to a telegram chat. It is triggered by an incoming `msg` object at its input containing all necessary telegram information.
**Fig. 7:** Sender node appearance
### Inputs
The input `msg.payload` must contain the following elements:
- `msg.payload.chatId` - **chatId** or an **array of chatIds** if you want to send the same message to several chats
- `msg.payload.type` - e.g. **message**, **document**, **photo**, etc. (see section *Receiver Node* above)
- `msg.payload.content` - your message content (e.g. message text)
Additional elements are present in the `msg.payload` structure and depend on the message *type*. These additional elements are described in the table **Tab. 1** above.
| *msg.payload.type* | *msg.payload.content* | *msg.payload.options* | *see also* |
| :- | :- | :- | :- |
| **message** | text (string) | optional arguments | https://core.telegram.org/bots/api#sendmessage |
| **document** | document (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#senddocument |
| **photo** | photo (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendphoto |
| **audio** | audio (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendaudio |
| **video** | video (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendvideo |
| **animation** | animation (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendanimation |
| **voice** | voice (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendvoice |
| **video_note** | video_note (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendvideonote |
| **mediaGroup** | media (array of InputMediaAudio, InputMediaDocument, InputMediaPhoto and InputMediaVideo) | optional arguments | https://core.telegram.org/bots/api#sendmediagroup |
| **poll** | { question (string), options (array of string) } | optional arguments | |
| **sticker** | sticker (InputFile/string) | optional arguments | https://core.telegram.org/bots/api#sendsticker |
| **dice** | - | optional arguments | https://core.telegram.org/bots/api#senddice |
| **venue** | { latitude (float), longitude (float), title (string), address (string) } | optional arguments | https://core.telegram.org/bots/api#sendvenue |
| **contact** | { phone_number (string), first_name (string) } | optional arguments | https://core.telegram.org/bots/api#sendcontact |
The content format depends on the message type. E.g. if you send a text message then the content format is a string, if you send a location, the content format is an object containing latitude and longitude. See also ["available methods" in the api core description](https://core.telegram.org/bots/api#available-methods).
### Outputs
Basically the input `msg` object is forwarded unchanged to the node's output.
The node has up to two outputs (selectable via the *Send errors to second output* flag):
1. The node's first/upper output (***Standard Output***) is used if the message was successfully transmitted.
2. The node's second/lower output (***Error Output***) is used when an exception occured. The output `msg` object contains a string property `msg.error`.
### Issueing API commands
Additionally to sending content, the sender node can be used to issue commands direct to the API. In this case the `msg.payload` elements contain (see examples for further details):
- `msg.payload.type` - one of the commands listed below
- `msg.payload.content` - required command arguments
- `msg.payload.chatId` - chatId if required
- `msg.payload.options` (optional) - additional command arguments
The `msg.payload.type` needs to be set to one of the following values:
| *msg.payload.type* | *msg.payload.content* | *msg.payload.options* | *see also* |
| :- | :- | :- | :- |
| **editMessageCaption** | - | optional arguments | https://core.telegram.org/bots/api#editmessagecaption |
| **editMessageText** | text (string) | optional arguments | https://core.telegram.org/bots/api#editmessagetext |
| **editMessageReplyMarkup** | - | optional arguments | https://core.telegram.org/bots/api#editmessagereplymarkup |
| **editMessageMedia** | media (InputMedia) | optional arguments | https://core.telegram.org/bots/api#editmessagemedia |
| **deleteMessage** | message_id (integer) | - | https://core.telegram.org/bots/api#deletemessage |
| **setMessageReaction** | message_id (integer) | optional arguments | https://core.telegram.org/bots/api#setmessagereaction |
| **editMessageLiveLocation** | { latitude (float), longitude (float) } | optional arguments | https://core.telegram.org/bots/api#editmessagelivelocation |
| **stopMessageLiveLocation** | - | optional arguments | https://core.telegram.org/bots/api#stopmessagelivelocation |
| **callback_query** | url (string) | optional arguments | https://core.telegram.org/bots/api#answercallbackquery |
| **answerCallbackQuery** | url (string) | optional arguments | https://core.telegram.org/bots/api#answercallbackquery |
| **inline_query** | { inlineQueryId (string), results (array of InlineQueryResult) } | optional arguments | https://core.telegram.org/bots/api#answerinlinequery |
| **answerInlineQuery** | { inlineQueryId (string), results (array of InlineQueryResult) } | optional arguments | https://core.telegram.org/bots/api#answerinlinequery |
| **answerWebAppQuery** | { webAppQueryId (string), result (InlineQueryResult) } | - | https://core.telegram.org/bots/api#answerwebappquery |
| **action** | action (string) | optional arguments | https://core.telegram.org/bots/api#sendchataction |
| **sendChatAction** | action (string) | optional arguments | https://core.telegram.org/bots/api#sendchataction |
| **leaveChat** | - | - | https://core.telegram.org/bots/api#leavechat |
| **exportChatInviteLink** | - | - | https://core.telegram.org/bots/api#exportchatinvitelink |
| **createChatInviteLink** | - | - | https://core.telegram.org/bots/api#createchatinvitelink |
| **banChatMember** | user_id (integer) | optional arguments | https://core.telegram.org/bots/api#banchatmember |
| **unbanChatMember** | user_id (integer) | optional arguments | https://core.telegram.org/bots/api#unbanchatmember |
| **restrictChatMember** | user_id (integer) | { permissions (ChatPermissions) } | https://core.telegram.org/bots/api#restrictchatmember |
| **promoteChatMember** | user_id (integer) | optional arguments | https://core.telegram.org/bots/api#promotechatmember |
| **setChatAdministratorCustomTitle** | user_id (integer) | custom title as string | https://core.telegram.org/bots/api#setchatadministratorcustomtitle |
| **setChatPhoto** | photo (InputFile) | - | https://core.telegram.org/bots/api#setchatphoto |
| **setChatTitle** | title (string) | - | https://core.telegram.org/bots/api#setchattitle |
| **setChatDescription** | description (string) |- | https://core.telegram.org/bots/api#setchatdescription |
| **setChatMenuButton** | menue button (MenuButton) | - | https://core.telegram.org/bots/api#setchatmenubutton |
| **setChatStickerSet** | sticker set name (string) | - | https://core.telegram.org/bots/api#setchatstickerset |
| **deleteChatStickerSet** | - | - | https://core.telegram.org/bots/api#deleteChatStickerSet |
| **pinChatMessage** | message_id (integer) | optional arguments | https://core.telegram.org/bots/api#pinchatmessage |
| **unpinChatMessage** | optional arguments | - | https://core.telegram.org/bots/api#unpinchatmessage |
| **unpinAllChatMessages** | - | - | https://core.telegram.org/bots/api#unpinallchatmessages |
| **deleteChatPhoto** | - | - | https://core.telegram.org/bots/api#deletechatphoto |
| **getChatAdministrators** | - | - | https://core.telegram.org/bots/api#getchatadministrators |
| **getChatMemberCount** | - | - | https://core.telegram.org/bots/api#getchatmembercount |
| **getChat** | - | - | https://core.telegram.org/bots/api#getchat |
| **getChatMember** | user_id (integer) | - | https://core.telegram.org/bots/api#getchatmember |
| **approveChatJoinRequest** | user_id (integer) | - | https://core.telegram.org/bots/api#approvechatjoinrequest |
| **declineChatJoinRequest** | user_id (integer) | - | https://core.telegram.org/bots/api#declinechatjoinrequest |
| **sendInvoice** | { title (string), description (string), payload (string), providerToken (string), startParameter (string), currency (string), prices (string) } | optional arguments | https://core.telegram.org/bots/api#sendinvoice |
| **answerPreCheckoutQuery** | { preCheckoutQueryId (string), ok (boolean)} | optional arguments | https://core.telegram.org/bots/api#answerprecheckoutquery |
| **pre_checkout_query** | { preCheckoutQueryId (string), ok (boolean)} | optional arguments | https://core.telegram.org/bots/api#answerprecheckoutquery |
| **shipping_query** | { shippingQueryId (string), ok (boolean) } | optional arguments | https://core.telegram.org/bots/api#answershippingquery |
| **answerShippingQuery** | { shippingQueryId (string), ok (boolean) } | optional arguments | https://core.telegram.org/bots/api#answershippingquery |
| **getForumTopicIconStickers** | - | - | https://core.telegram.org/bots/api#getforumtopiciconstickers |
| **getChatMenuButton** | - | - | https://core.telegram.org/bots/api#getchatmenubutton |
| **createForumTopic** | name (string) | optional arguments | https://core.telegram.org/bots/api#createforumtopic |
| **editForumTopic** | message_thread_id (integer) | optional arguments | https://core.telegram.org/bots/api#editforumtopic |
| **closeForumTopic** | message_thread_id (integer) | - | https://core.telegram.org/bots/api#closeforumtopic |
| **reopenForumTopic** | message_thread_id (integer) | - | https://core.telegram.org/bots/api#reopenforumtopic |
| **deleteForumTopic** | message_thread_id (integer) | - | https://core.telegram.org/bots/api#deleteforumtopic |
| **editGeneralForumTopic** | name (string) | - | https://core.telegram.org/bots/api#editgeneralforumtopic |
| **unpinAllForumTopicMessages** | name (string) | - | https://core.telegram.org/bots/api#unpinallforumtopicmessages |
| **closeGeneralForumTopic** | - | - | https://core.telegram.org/bots/api#closegeneralforumtopic |
| **reopenGeneralForumTopic** | - | - | https://core.telegram.org/bots/api#reopengeneralforumtopic |
| **hideGeneralForumTopic** | - | - | https://core.telegram.org/bots/api#hidegeneralforumtopic |
| **unhideGeneralForumTopic** | - | - | https://core.telegram.org/bots/api#unhidegeneralforumtopic |
| **stopPoll** | message_id (integer) | optional arguments | https://core.telegram.org/bots/api#stoppoll |
| **setChatAdministratorCustomTitle** | message_id (integer) | optional arguments | https://core.telegram.org/bots/api#setchatadministratorcustomtitle |
The content format of the command arguments (required and optional) depends on the api command.
See also ["available methods" in the api core description](https://core.telegram.org/bots/api#available-methods).
## Command Node
The command node can be used for triggering a message when a specified command is received: e.g. /help. See examples below.
Note that commands always start with a / like /help, /start, /stop. if you have several bots in one group chat implementing the
same command e.g. /help you should send commands directly to a dedicated bot using the full notation /help@YourBot to avoid
that different bots would get triggered at once. It it recommended to turn on the strict mode in this case.
**Fig. 8:** Command node appearance
### Configuration
The node's configuration contains the following special properties:
- **Command**: The command which shall be implemented.
Commands usually start with a / like for example /foo. According to the telegram api documentation the command should be issued following the bot name like /foo@YourBot. This is important when you add several different bots to one single group chat.
- **Register at telegram server** flag: To automatically register the command and the description at the telegram server.
- **Description**: The description is used when the command should be published via /setMyCommands at the telegram server. /
It is optional if the **Register at telegram server** flag is not checked.
- **Language**: The 2 digit language code (see ISO-639-1). If this field is empty it will be shown in every language, otherwise only to the users that have set the language of their client to this language.
- **Scope**: The scope to register the command to: see also [BotCommandScope](https://core.telegram.org/bots/api#botcommandscope).
- **Strict in group chats** flag: To avoid that the bot handles commands that are not directly sent to it using the long notation (e.g. /foo@YourBot) you can set the "strict" mode in the options of the command node. In this case the bot only accepts the full command notation in group chats.
- **Has response output** flag: This enables the second output (*Unathorized Output*). Otherwise the node only has one single output.
- **Use Regex** flag: Allows the usage of regular expressions as command. E.g. ^/toggle_ allows all commands starting with /toggle_.
- **Remove Command** flag: This optional flag is used when **Use Regex** is checked. If checked it removed the matched command from the beginning of the message. If your command contains addressinformation you should uncheck this flag to be able to parse this information on your own.
### Outputs
The node has up to two outputs (selectable via the *Has response output* flag):
1. The node's first/upper output (***Standard Output***) is used if the message is from an authorized user and it contains a specified command at the beginning of the message.
2. The node's second/lower output (***Unauthorized Output***) is used in all other cases. This may be the case when security is applied (via configuration properties *Users* and *ChatIds*) and the user is not authorized to access the bot or if it is from an autorized user and the message does not contain a specified command.
The second output is useful when you want to use a keyboard. See example below.
It is only issued if a command was received before. If another command was triggered in the meantime, the pending status of the first one is reset. The state is stored per user and per chat.
## Event Node
A telegram node that triggers the output when a event is received from a chat.
**Fig. 9:** Event node appearance
The node receives events from the bot like:
- **Callback Query** of inline keyboards. See example-flow [inline keyboard flow](examples/inlinekeyboard.json) in examples folder.
- **Inline Query** of inline bots. See [Inline mode](https://core.telegram.org/bots/api#inline-mode) in the bot API.
- **Edited Message** which is triggered when someone alters an already sent message.
- **Edited Message Text** which is triggered when someone alters an already sent message text.
- **Edited Message Caption** which is triggered when someone alters an already sent caption e.g. of a photo.
- **Channel Post** which is triggered when the bot is member of a public channel (/setprivacy to disabled!).
- **Edited Channel Post** which is triggered when someone alters an already sent message in a public channel.
- **Edited Channel Post Text** which is triggered when someone alters an already sent message text in a public channel.
- **Edited Channel Post Caption** which is triggered when someone alters an already sent caption of e.g. a photo in a public channel.
- **Pre Checkout Query** which is triggered when someone issues a payment (see send invoice).
- **Shipping Query** which is triggered when someone issues a shipping.
- **Chosen Inline Result** which is triggered when a user has chosen a result from an inline query.
- **Poll** which is triggered when a poll is created.
- **Poll Answer** which is triggered when a poll is answered.
- **My Chat Member** which is triggered when the status of the bot is changed.
- **Chat Join Request** which is triggered when a chat join request is issued.
Note that - **Chat Member** is deactivated as it requires special rights by the bot and modifications in polling.
### Configuration
The Event to be received is configured via the node's configuration dialog:
<img src="images/TelegramBotConfigurationDialogEvent.png" title="Event node configuration" width="400" />
**Fig. 10:** Event node configuration dialog
With the ***Event*** property the listening event is selcted.
The ***Auto-Answer*** checkbox can be set for Callback_Query. If activated, you do not need to send an explicit answer to the bot on your own.
### Outputs
The output `msg.payload` typically contains the parsed data as follows:
- ***chatId:*** Unique identifier for this chat
- ***messageId:*** Telegram message identifier
- ***type:*** Event type (see configurable events above)
- ***date:*** Timestamp
- ***content:*** The actual UTF-8 text of the message
Other properties may be present depending on the type of message.
The output `msg.originalMessage` contains the raw data object from the underlying library, and contains many useful properties.
See also the following descriptions for the event handling:
- callback_query, edited_message, channel_post, edited_channel_post: [Getting updates](https://core.telegram.org/bots/api#update)
- edited_message_text, edited_message_caption: [Updating messages](https://core.telegram.org/bots/api#updating-messages)
- inline_query: [Inline mode](https://core.telegram.org/bots/api#inline-mode)
## Reply Node
A telegram node that is triggered when someone answered to a specified message.
**Fig. 11:** Reply node appearance
The reply node waits for an answer to a specified message. It should be used in conjunction with the sender node.
### Input
Standard Input: Calls the *onReplyToMessage* of the bot.
### Output
Standard Output: Contains the result from the *onReplyToMessage* call.
This node may be useful, when the bot e.g. sent a message and you want to take some action when someone responded to this specified message. Responding to messages is done by clicking on the message in your client and choose *answer* from the popup.
The `msg.payload` contains:
- **chatId** : Destination chatId
- **sentMessageId** : The id of the previously sent message in the chat
- **content** : The message content.
## Control Node
This node can be used to stop, start, restart a bot (config node).
It send a message to the output after every poll cycle.
See the example flow [**control bot**](examples/control.json) in the examples folder.
### Input
The `msg.payload` contains:
- **command** : 'start' | 'stop' | 'restart' | 'command'
- **delay** : Optional delay (between stop and start) in milliseconds for 'restart'.
### Output
Standard Output: Contains the msg object passed to the input or a message with poll information:
- **cycle** : Polling cycle number.
- **duration** : Duration in milliseconds for the request.
# Keyboards
## General
Keyboards can be used to interact with the user by displaying a flexibly definable keyboard. The user then presses one of the keys to give his selection.
Two different keyboard types are available:
- ***Custom Keyboards*** - These are keyboards which replace the standard keyboard. They are located below the message enter area.
- ***Inline Keyboards*** - These are keyboards which are inline in the message area.
A remarkable feature of *Inline Keyboards* is the ability to change them on the fly. See examples section for further details.
With keyboards also complex keyboard procedures with several hierarchy levels can be implemented to direct the user in a step by step button pressing procedure.
## Custom keyboards
Examples for *Custom keyboards* can be seen in the [Keyboards section](https://core.telegram.org/bots#keyboards) of the telegram bot description.
Custom keyboards act with ***message nodes*** and ***telegram receiver nodes*** to handle the keyboard procedure, which is as follows:
1. The appearance of the keyboard is initiated via a *message* sent to the bot. In the message the keyboard configuration is defined within the `msg.payload.options` property.
2. The user presses a displayed key.
3. The key text is sent back via a *message*. This message is received with a *receiver node* and can then be evaluated.
The keyboard configuration contains the key description, layout and further options. A description of it can be found in the [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) section.
See also the custom keyboard example.
A basic flow handling a custom keyboard with its reply shows the following figure.
[**custom keyboard basic flow**](examples/basiccustomkeyboard.json)
**Fig. 12:** Custom keyboard basic flow example
<details>
<summary>Click to expand code snippet for <em><b>build keyboard</b></em> function</summary>
```javascript
var opts = {
reply_markup: JSON.stringify({
keyboard: [
['A1'],
['A2']],
'resize_keyboard' : true,
'one_time_keyboard' : true
})
};
msg.error = false;
// Dialogaufbau
msg.payload.content = 'Selection?';
msg.payload.options = opts;
msg.payload.chatId = 123445;
msg.payload.messageId = 99;
msg.payload.sentMessageId = 99;
msg.payload.type = "message";
return [ msg ];
```
</details>
<br>
The look&feel at a mobile device could look like the following figure:
<img src="images/TelegramBotConfirmationMessage4.png" title="Keyboard look@feel" width="300" />
**Fig. 13:** Custom keyboard example screenshot
The answering options are located below the user text input field.
Several options for the keyboard layout can be found there in the [Telegram Bot API SDK description](https://irazasyed.github.io/telegram-bot-sdk/usage/keyboards/).
The keyboard layout shown in Fig. 12 (given in the *create response* node) is
```javascript
keyboard: [
['Yes'],
['No']],
```
Another example of a different key layout may be to arrange several keys in one line.
This may be like:
```javascript
keyboard: [
['Yes','No','Maybe'],
['Conditional']],
```
This leads to a layout like:
<img src="images/TelegramBotConfirmationMessage5.png" title="Keyboard look@feel" width="300" />
**Fig. 14:** Custom keyboard example screenshot with different layout
## Inline keyboards
Examples for *Inline keyboards* can be seen in the [Inline keyboards section](https://core.telegram.org/bots#inline-keyboards-and-on-the-fly-updating) of the telegram bot description.
Inline keyboards act with ***message nodes*** and ***event nodes*** (event *Callback Query*) to handle the keyboard procedure, which is as follows:
1. The appearance of the keyboard is initiated via a *message* sent to the bot. In the message the keyboard configuration is defined within the `msg.payload.options` property.
2. The user presses a displayed key.
3. The key text is sent back via an *Callback Query* event. This message is received with an *event node* and can then be evaluated.
The keyboard configuration contains the key description, layout and further options. A description of it can be found in the [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) section.
See also the inline keyboard example.
A basic flow handling an inline keyboard with its reply shows the following figure.
[**inline keyboard basic flow**](examples/basicinlinekeyboard.json)
**Fig. 15:** Inline keyboard basic flow example
<details>
<summary>Click to expand code snippet for <em><b>build keyboard</b></em> function</summary>
```javascript
var opts = {
reply_markup: JSON.stringify({
"inline_keyboard": [[
{
"text": "A1",
"callback_data": "1"
},
{
"text": "A2",
"callback_data": "2"
}]
]
})
};
msg.payload.content = "Selection?";
msg.payload.options = opts;
msg.payload.chatId = 12345;
msg.payload.messageId = 99;
msg.payload.sentMessageId = 99;
msg.payload.type = "message";
return [ msg ];
```
</details>
<br>
The look&feel at a mobile device could look like the following figure:
<img src="images/TelegramBotInlineKeyboard4.png" title="Inline keyboard look@feel" width="300" />
**Fig. 16:** Inline keyboard example screenshot
The answering options are located within the dialog field.
Several options for the keyboard layout can be found there in the [Telegram Bot API SDK description](https://irazasyed.github.io/telegram-bot-sdk/usage/keyboards/).
The keyboard layout shown in Fig. 15 (given in the *inline keyboard message* node) is
```javascript
"inline_keyboard": [[
{"text": "Yes","callback_data": "FOO YES"},
{"text": "No", "callback_data": "FOO NO"}
]]
```
Another example of a different key layout may be to arrange several keys in one line.
This may be like:
```javascript
"inline_keyboard": [[
{"text": "Yes","callback_data": "FOO YES"},
{"text": "No","callback_data": "FOO NO"}],
[
{"text": "#1","callback_data": "FOO ONE"},
{"text": "#2","callback_data": "FOO TWO"},
{"text": "#3","callback_data": "FOO THREE"}
],
[
{"text": "dog","callback_data": "FOO DOG"},
{"text": "eel","callback_data": "FOO EEL"},
{"text": "cow","callback_data": "FOO COW"},
{"text": "cat","callback_data": "FOO CAT"}
]
]
```
This leads to a layout like:
<img src="images/TelegramBotInlineKeyboard5.png" title="Inline keyboard look@feel" width="200" />
**Fig. 17:** Inline Keyboard example screenshot with different layout
# Examples
***
**Remark**: Example flows are present in the examples subdirectory. In Node-RED they can be imported via the import function and then selecting *Examples* in the vertical tab menue.
All example flows can also be found in the examples folder of this package.
***
## Implementing a simple echo
This example is self-explaining. The received message is returned to the sender.
[**echo flow**](examples/echo.json)
**Fig. 18:** Simple echo flow
## Implementing a /help command
This flow returns the help message of your bot. It receives the command and creates a new message, which is returned:
[**help message flow**](examples/sendhelpmessage.json)
**Fig. 19:** Help command flow example
<details>
<summary>Click to expand code snippet for <em><b>create help text</b></em> function</summary>
```javascript
var helpMessage = "/help - shows help";
helpMessage += "\r\n/foo - opens a dialog";
helpMessage += "\r\n";
helpMessage += "\r\nYou are welcome: "+msg.originalMessage.from.username;
helpMessage += "\r\nYour chat id is " + msg.payload.chatId;
helpMessage += "\r\n";
msg.payload.content = helpMessage;
return msg;
```
</details>
<br>
The output looks on a mobile device like the following figure:
**Fig. 20:** Help command screenshot
**Note**: You can access the sender's data via the `msg.originalMessage` property.
## Implementing a custom keyboard
Custom keyboards are very useful for getting additional data from the sender.
When the command is received the first output is triggered and a dialog is opened:
[**keyboard flow**](examples/keyboard.json)
**Fig. 21:** Keyboard example
The answer is send to the second output triggering the lower flow. Data is passed via global properties here.
<details>
<summary>Click to expand code snippet for <em><b>confirmation message</b></em> function</summary>
```javascript
context.global.keyboard = { pending : true };
var opts = {
reply_to_message_id: msg.payload.messageId,
reply_markup: JSON.stringify({
keyboard: [
['Yes'],
['No']],
'resize_keyboard' : true,
'one_time_keyboard' : true
})
};
msg.payload.content = 'Really?';
msg.payload.options = opts;
return [ msg ];
```
</details>
<details>
<summary>Click to expand code snippet for <em><b>create response</b></em> function</summary>
```javascript
if (context.global.keyboard.pending) {
context.global.keyboard.pending = false;
if(msg.payload.content === 'Yes') {