![](\"https://img.shields.io/badge/Donate-Bitcoin-green.svg\"/){kind=icon}
\n![](\"https://img.shields.io/badge/Donate-PayPal-blue.svg\"/){kind=icon}
\n\n![\"Buy](\"https://cdn.buymeacoffee.com/buttons/default-orange.png\")
\n\n\n# Credits\n - dvv (Vladimir Dronnikov): for providing the saveDataDir configuration option\n - snippet-java: for adding venue messages and for providing the markdown problem fallback\n - greenstone7: for providing the callback query node\n - dceejay: for cleaning up the project\n - psyntium: for providing the weblink for additional content link videos, pictures, animations, audio files\n - MatthiasHunziker: for extending the callback query node to support generic events\n - Skiepp: for providing the send chat action idea.\n - MK-2001: for providing the sendMediaGroup fuhttps://github.com/yagop/node-telegram-bot-apinction\n - cowchimp: for adding the support for `Node-RED v1.0+` (async)\n - JokerQyou: for adding the support for using webhook without certificate\n - bonastreyair: for providing ideas for improving the command node\n - StephanStS: for extension/clearification/beautification of Readme.md and finding minor bugs\n - Diddlik: for extending webhook options\n - MorbidDevil: for extending answerInlineQuery with options\n - daredoes: for providing the webhook decumentation on Unraid/Docker with SWAG/NGINX/REVERSE-PROXY\n - kickouille: for fixing the payment functions and providing the full payment example flow\n - skrashevich: for providing approveChatJoinRequest, declineChatJoinRequest\n - ShotokanZH: for providing the web app data example\n - Dodoooh: for providing the send to topic example flow\n - MariusSchiffer: for improving documentation\n - ptath: for providing pullrequest for setChatAdministratorCustomTitle \n - gmag11: for providing pullrequest for enhancing getFile\n - ivanjh: for providing the patch for improving output of polling errors\n - GrimbiXcode: for replacing pump with pipeline\n - y8: for providing ideas for improving receiver node\n - ptath: for providing setChatMemberTag\n - MK-2001: for providing pullrequest with safe stringify\n\n# 👥 Contributors\n\n \n \n \n \n
![](\"images/TelegramBotErrorHandling2.png\" "\\"Sender")
\n\n**Fig. 2:** Sender node dialog\n\n\n![Alt text](images/TelegramBotErrorHandling.png?raw=true \"Error handling in sender node.\") \n[**error handling example flow**](examples/errorhandling.json) \n\n\n\n## Configuration Node\nThe mandatory configuration entries are\n- the *Bot-Name* and\n- the *Token*\n\nwhich you received from @botfather when creating a new bot.\n\n![](\"images/TelegramBotConfigurationNodeDialog.png\" "\\"Configuration")
\n\n**Fig. 3:** Configuration node dialog\n\n\n### Reading token from external location\nInstead 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.\n\n#### Reading token from environment variable\nEnvironment variables are entered in the settings.js of node-red before startup. \n```javascript\nprocess.env.BOT_TOKEN = \"![](\"images/TelegramSettingsUsername.png\" "\\"Telegram")
\n\n**Fig. 4:** Telegram app settings dialog (example Android phone app)\n\nIf no *Username* is set you can only filter via the *ChatId* property.\n\n\n### Configuration property *Server URL*\nThis 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.\n\nTypically this field is left blank.\n\n\n### Configuration property *Test Environment*\nThis enables the test environment see: (https://core.telegram.org/bots/features#testing-your-bot). \n\nTypically this checkbox is unchecked.\n\n\n### Configuration property *Update Mode*\nThe update mode can be chosen from *Polling* or *Webhook*.\n\n#### Polling mode\nBy 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)?\nE.g. a table with these coloumns:\n- text: chatId, messageId, type (= \"message\"), content (text)\n- photo: chatId, messageId, type (= \"photo\"), content (photo[index].file_id with index = different photo sizes), caption, date, blob (= true), photos (???), mediaGroupId\n- audio: chatId, messageId, type (= \"audio\"), content (file_id), cation, date, blob (= true)\n...*Polling Options*.\n\n#### Webhook mode\nThe *Webhook* method may be chosen to avoid polling.\n\n![](\"images/TelegramBotWebHookConfiguration.png\" "\\"Webhook")
\n\n**Fig. 5:** Example configuration for webhook mode\n\nAs setting up a webhook can be very complex depending on the infrastructure this was moved to a seprate readme file.\nSee also [WEBHOOK.md](WEBHOOK.md)\n\n\n#### None mode\nThe *None* method may be chosen to avoid traffic due to polling or incoming webhook calls.\nYou can only send messages using the sender node but you can not receive any data.\n\n\n### Configuration property *IP address family*\nYou can force a certain IP version to be used when making requests to the telegram server.\nNormally this is up to the operating system und you can just keep the default setting \"Any\".\nIf you discover problems e.g. the telegram server is unreachable. Then you can try to force\nusing IPv4 or IPv6.\n\n\n### Configuration property flag *Use SOCKS*\nSOCKS4/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.\n\nAs setting up a socks5 proxy can be very complex depending on the infrastructure this was moved to a seprate readme file.\nSee also [SOCKS5.md](SOCKS5.md)\n\n\n### Configuration property flag *Verbose Logging*\nThe ***Verbose Logging*** flag should only be activated when debugging network problems as this will create cyclic warnings when the network is down.\n\n\n## Receiver Node\nThis node can **receive telegram messages** sent to the bot and (under certain circumstances) also **receive messages from a chat**.\n\n![node-appearance-receiver](images/TelegramBotNodeReceiver.png \"Receiver node appearance\") \n**Fig. 6:** Receiver node appearance\n\n**Telegram messages** sent directly to the bot are automatically received (if not masked via the configuration node property *Users*). \nTo 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.\n\nYou can control if the bot receives every message by calling **/setprivacy @botfather** (refer also to [**there**](https://core.telegram.org/bots/features#privacy-mode)).\n\nNote 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.\n\n### Configuration\n\n#### Configuration property *Download Directory*\nWhen 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`.\nIn addition to that the message object may contain the direct download link in the payload: `msg.payload.weblink`.\n\n#### Configuration property *Events*\nNext 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.\n\n#### Configuration property *Filter*\nNormally, 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. \nI.e. the command message then only appears in the configured command node and not in this node.\n\n#### Configuration property *Message Input*\nEnable 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.\n\nSee the example flow [**control bot**](examples/externalreceiverl.json) in the examples folder.\n![](\"images/TelegramBotConfigurationDialogEvent.png\" "\\"Event")
\n\n**Fig. 10:** Event node configuration dialog\n\nWith the ***Event*** property the listening event is selcted.\n\nThe ***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.\n\n\n### Outputs\nThe output `msg.payload` typically contains the parsed data as follows:\n- ***chatId:*** Unique identifier for this chat\n- ***messageId:*** Telegram message identifier\n- ***type:*** Event type (see configurable events above)\n- ***date:*** Timestamp\n- ***content:*** The actual UTF-8 text of the message\nOther properties may be present depending on the type of message.\n\nThe output `msg.originalMessage` contains the raw data object from the underlying library, and contains many useful properties.\n\n\n\nSee also the following descriptions for the event handling:\n- callback_query, edited_message, channel_post, edited_channel_post: [Getting updates](https://core.telegram.org/bots/api#update)\n- edited_message_text, edited_message_caption: [Updating messages](https://core.telegram.org/bots/api#updating-messages)\n- inline_query: [Inline mode](https://core.telegram.org/bots/api#inline-mode)\n\n\n## Reply Node\nA telegram node that is triggered when someone answered to a specified message.\n\n![node-appearance-reply](images/TelegramBotNodeReply.png \"Reply node appearance\") \n**Fig. 11:** Reply node appearance\n\nThe reply node waits for an answer to a specified message. It should be used in conjunction with the sender node.\n\n### Input\nStandard Input: Calls the *onReplyToMessage* of the bot.\n\n### Output\nStandard Output: Contains the result from the *onReplyToMessage* call.\n\nThis 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.\n\nThe `msg.payload` contains:\n- **chatId** : Destination chatId\n- **sentMessageId** : The id of the previously sent message in the chat\n- **content** : The message content.\n\n\n## Control Node\nThis node can be used to stop, start, restart a bot (config node).\nIt can inject a command message to all command nodes.\nIt can detect if a specified server in the internet can be reached (online/offline)\nIt send a message to the output after every poll cycle.\nSee the example flow [**control bot**](examples/control.json) in the examples folder.\n\n### Input\nThe `msg.payload` contains:\n- **command** : 'start' | 'stop' | 'restart' | 'command'\n- **delay** : Optional delay (between stop and start) in milliseconds for 'restart'.\n\n### Output\nStandard Output: Contains the msg object passed to the input or a message with poll information:\n- **cycle** : Polling cycle number.\n- **duration** : Duration in milliseconds for the request.\n\n\n# Keyboards\n\n## General\nKeyboards 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. \nTwo different keyboard types are available:\n- ***Custom Keyboards*** - These are keyboards which replace the standard keyboard. They are located below the message enter area.\n- ***Inline Keyboards*** - These are keyboards which are inline in the message area.\n\nA remarkable feature of *Inline Keyboards* is the ability to change them on the fly. See examples section for further details.\n\nWith keyboards also complex keyboard procedures with several hierarchy levels can be implemented to direct the user in a step by step button pressing procedure.\n\n\n## Custom keyboards\nExamples for *Custom keyboards* can be seen in the [Keyboards section](https://core.telegram.org/bots#keyboards) of the telegram bot description.\n\nCustom keyboards act with ***message nodes*** and ***telegram receiver nodes*** to handle the keyboard procedure, which is as follows:\n1. 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.\n2. The user presses a displayed key.\n3. The key text is sent back via a *message*. This message is received with a *receiver node* and can then be evaluated.\n\n\nThe 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. \nSee also the custom keyboard example.\n\nA basic flow handling a custom keyboard with its reply shows the following figure.\n\n![Alt text](images/TelegramBotCustomKeyboardBasicFlow.png?raw=true \"Custom keyboard basic flow\") \n[**custom keyboard basic flow**](examples/basiccustomkeyboard.json) \n**Fig. 12:** Custom keyboard basic flow example\n\n![](\"images/TelegramBotConfirmationMessage4.png\" "\\"Keyboard")
\n\n**Fig. 13:** Custom keyboard example screenshot\n\nThe answering options are located below the user text input field. \n\nSeveral 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/). \nThe keyboard layout shown in Fig. 12 (given in the *create response* node) is\n ```javascript\nkeyboard: [\n ['Yes'],\n ['No']],\n```\n\nAnother example of a different key layout may be to arrange several keys in one line.\nThis may be like:\n```javascript\nkeyboard: [\n ['Yes','No','Maybe'],\n ['Conditional']],\n```\n\nThis leads to a layout like:\n\n![](\"images/TelegramBotConfirmationMessage5.png\" "\\"Keyboard")
\n\n**Fig. 14:** Custom keyboard example screenshot with different layout\n\n\n\n## Inline keyboards\nExamples 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.\n\nInline keyboards act with ***message nodes*** and ***event nodes*** (event *Callback Query*) to handle the keyboard procedure, which is as follows:\n1. 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.\n2. The user presses a displayed key.\n3. The key text is sent back via an *Callback Query* event. This message is received with an *event node* and can then be evaluated.\n\n\nThe 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. \nSee also the inline keyboard example.\n\nA basic flow handling an inline keyboard with its reply shows the following figure.\n\n![Alt text](images/TelegramBotInlineKeyboardBasicFlow.png?raw=true \"Inline keyboard basic flow\") \n[**inline keyboard basic flow**](examples/basicinlinekeyboard.json) \n**Fig. 15:** Inline keyboard basic flow example\n\n![](\"images/TelegramBotInlineKeyboard4.png\" "\\"Inline")
\n\n**Fig. 16:** Inline keyboard example screenshot\n\nThe answering options are located within the dialog field. \n\nSeveral 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/). \nThe keyboard layout shown in Fig. 15 (given in the *inline keyboard message* node) is\n ```javascript\n\"inline_keyboard\": [[\n {\"text\": \"Yes\",\"callback_data\": \"FOO YES\"},\n {\"text\": \"No\", \"callback_data\": \"FOO NO\"}\n]]\n```\n\nAnother example of a different key layout may be to arrange several keys in one line.\nThis may be like:\n\n```javascript\n\"inline_keyboard\": [[\n {\"text\": \"Yes\",\"callback_data\": \"FOO YES\"},\n {\"text\": \"No\",\"callback_data\": \"FOO NO\"}],\n [\n {\"text\": \"#1\",\"callback_data\": \"FOO ONE\"},\n {\"text\": \"#2\",\"callback_data\": \"FOO TWO\"},\n {\"text\": \"#3\",\"callback_data\": \"FOO THREE\"}\n ],\n [\n {\"text\": \"dog\",\"callback_data\": \"FOO DOG\"},\n {\"text\": \"eel\",\"callback_data\": \"FOO EEL\"},\n {\"text\": \"cow\",\"callback_data\": \"FOO COW\"},\n {\"text\": \"cat\",\"callback_data\": \"FOO CAT\"}\n ]\n]\n```\n\nThis leads to a layout like:\n\n![](\"images/TelegramBotInlineKeyboard5.png\" "\\"Inline")
\n\n**Fig. 17:** Inline Keyboard example screenshot with different layout\n\n\n\n# Examples\n***\n**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. \nAll example flows can also be found in the examples folder of this package.\n***\n\n## Implementing a simple echo\nThis example is self-explaining. The received message is returned to the sender.\n\n![Alt text](images/TelegramBotEcho.png?raw=true \"Echo flow\") \n[**echo flow**](examples/echo.json) \n**Fig. 18:** Simple echo flow\n\n\n## Implementing a /help command\nThis flow returns the help message of your bot. It receives the command and creates a new message, which is returned:\n\n![Alt text](images/TelegramBotHelp.png?raw=true \"Help command flow\") \n[**help message flow**](examples/sendhelpmessage.json) \n**Fig. 19:** Help command flow example\n\n\n