==============
Ask @BotFather to create new bot /newbot.
You will be asked to enter name of the bot and then the username. After that you will get the Token.
You should set password for communication in configuration dialog. After this start the adapter.
To start a conversation with your bot you need to authenticate user with "/password phrase", where phrase is your configured password. So open a new conversation with your generated Bot in Telegram and then you need to enter the passwort as first command.
Note: you can use short form "/p phrase".
To add nice avatar picture enter /setuserpic and upload him desired picture (512x512 pixels), like this one logo.
You can send message to all authenticated users over messageBox sendTo('telegram', 'Test message')
or to specific user sendTo('telegram', '@userName Test message').
User must be authenticated before.
You can specify user in that way too:
sendTo('telegram', {user: 'UserName', text: 'Test message'}, function (res) {
console.log('Sent to ' + res + ' users');
});
If you use the example above be aware of that you have to replace 'UserName' with either the firstname or the Public-Telegram-Username of the User you want to send the message to. (Depends on if the 'Store username not firstname' setting in the Adaptersettings is enabled or not) If the option is set and the user did not specify a public username in his telegram account, then the adapter will continue to use the firstname of the user. Keep in mind that if the user sets a public username later (after authenticating to your bot) the saved firstname will be replaced by the username the next time the user sends a message to the bot.
It is possible to specify more than one recipient (just separate the Usernames by comma). For example: Recipient: "User1,User4,User5"
You can send message over state too, just set state "telegram.INSTANCE.communicate.response" with value "@userName Test message".
You can use telegram with text2command adapter. There are predefined communication schema and you can command to you home in text form.
To send photo, just send a path to file instead of text or URL: sendTo('telegram', 'absolute/path/file.png') or sendTo('telegram', 'https://telegram.org/img/t_logo.png').
Example how to send screenshot from webcam to telegram:
var request = require('request');
var fs = require('fs');
function sendImage() {
request.get({url: 'http://login:pass@ipaddress/web/tmpfs/snap.jpg', encoding: 'binary'}, function (err, response, body) {
fs.writeFile("/tmp/snap.jpg", body, 'binary', function(err) {
if (err) {
console.error(err);
} else {
console.log('Snapshot sent');
sendTo('telegram.0', '/tmp/snap.jpg');
//sendTo('telegram.0', {text: '/tmp/snap.jpg', caption: 'Snapshot'});
}
});
});
}
on("someState", function (obj) {
if (obj.state.val) {
// send 4 images: immediately, in 5, 15 and 30 seconds
sendImage();
setTimeout(sendImage, 5000);
setTimeout(sendImage, 15000);
setTimeout(sendImage, 30000);
}
});
Following messages are reserved for actions:
- typing - for text messages,
- upload_photo - for photos,
- upload_video - for videos,
- record_video - for videos,
- record_audio - for audio,
- upload_audio - for audio,
- upload_document - for documents,
- find_location - for location data
In this case the action command will be sent.
The description for telegram API can be found here and you can use all options defined in this api, just by including that into send object. E.g.:
sendTo('telegram.0', {
text: '/tmp/snap.jpg',
caption: 'Snapshot',
disable_notification: true
});
Possible options:
- disable_notification: Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. (all types)
- parse_mode: Send Markdown or HTML, if you want Telegram apps to show bold, italic, fixed-width text or inline URLs in your bot's message. Possible values: "Markdown", "HTML" (message)
- disable_web_page_preview: Disables link previews for links in this message (message)
- caption: Caption for the document, photo or video, 0-200 characters (video, audio, photo, document)
- duration: Duration of sent video or audio in seconds (audio, video)
- performer: Performer of the audio file (audio)
- title: Track name of the audio file (audio)
- width: Video width (video)
- height: Video height (video)
Adapter tries to detect the type of message (photo, video, audio, document, sticker, action, location) depends on text in the message if the text is path to existing file, it will be sent as according type.
Location will be detected on attribute latitude:
sendTo('telegram.0', {
latitude: 52.522430,
longitude: 13.372234,
disable_notification: true
});
You have the possibility to define extra the type of the message in case you want to send the data as buffer.
Following types are possible: sticker, video, document, audio, photo.
sendTo('telegram.0', {
text: fs.readFileSync('/opt/path/picture.png'),
type: 'photo'
});
You can show keyboard ReplyKeyboardMarkup in the client:
sendTo('telegram.0', {
text: 'Press button',
reply_markup: {
keyboard: [
['Line 1, Button 1', 'Line 1, Button 2'],
['Line 2, Button 3', 'Line 2, Button 4']
],
resize_keyboard: true,
one_time_keyboard: true
}
});
You can read more here and here.
You can show keyboard InlineKeyboardMarkup in the client:
sendTo('telegram', {
user: user,
text: 'Click the button',
reply_markup: {
inline_keyboard: [
[{ text: 'Button 1_1', callback_data: '1_1' }],
[{ text: 'Button 1_2', callback_data: '1_2' }]
]
}
});
You can read more here and here.
NOTE: After the user presses a callback button, Telegram clients will display a progress bar until you call answerCallbackQuery. It is, therefore, necessary to react by calling answerCallbackQuery even if no notification to the user is needed (e.g., without specifying any of the optional parameters).
Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.
if (command ==="1_2") {
sendTo('telegram', {
user: user,
answerCallbackQuery: {
text: "Pressed!",
showAlert: false // Optional parameter
}
});
}
You can read more here.
From version 0.4.0 you can use chat ID to send messages to chat.
sendTo('telegram.0', {text: 'Message to chat', chatId: 'SOME-CHAT-ID-123');
The following methods allow you to change an existing message in the message history instead of sending a new one with a result of an action. This is most useful for messages with inline keyboards using callback queries, but can also help reduce clutter in conversations with regular chat bots.
Use this method to edit text sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
if (command ==="1_2") {
sendTo('telegram', {
user: user,
text: 'New text before buttons',
editMessageText: {
options: {
chat_id: getState("telegram.0.communicate.requestChatId").val,
message_id: getState("telegram.0.communicate.requestMessageId").val,
reply_markup: {
inline_keyboard: [
[{ text: 'Button 1', callback_data: '2_1' }],
[{ text: 'Button 2', callback_data: '2_2' }]
],
}
}
}
});
}
or new text for last message:
if (command ==="1_2") {
sendTo('telegram', {
user: user,
text: 'New text message',
editMessageText: {
options: {
chat_id: getState("telegram.0.communicate.requestChatId").val,
message_id: getState("telegram.0.communicate.requestMessageId").val,
}
}
});
}
You can read more here.
Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots). On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
if (command ==="1_2") {
sendTo('telegram', {
user: user,
text: 'New text before buttons',
editMessageReplyMarkup: {
options: {
chat_id: getState("telegram.0.communicate.botSendChatId").val,
message_id: getState("telegram.0.communicate.botSendMessageId").val,
reply_markup: {
inline_keyboard: [
[{ text: 'Button 1', callback_data: '2_1' }],
[{ text: 'Button 2', callback_data: '2_2' }]
],
}
}
}
});
}
You can read more here.
Use this method to delete a message, including service messages, with the following limitations:
- A message can only be deleted if it was sent less than 48 hours ago. Returns True on success.
if (command ==="delete") {
sendTo('telegram', {
user: user,
deleteMessage: {
options: {
chat_id: getState("telegram.0.communicate.requestChatId").val,
message_id: getState("telegram.0.communicate.requestMessageId").val
}
}
});
}
You can read more here.
You can request the value of state if you now the ID:
/state system.adapter.admin.0.memHeapTotal
> 56.45
You can set the value of state if you now the ID:
/state hm-rpc.0.JEQ0ABCDE.3.STOP true
> Done
If polling mode is used, the adapter polls by default every 300ms the telegram server for updates. It uses traffic and messages can be delayed for up to the polling interval. The polling interval can be defined in adapter configuration.
To use server mode you ioBroker instance must be reachable from internet (e.g. with noip.com dynamic DNS service).
Telegram can work only with HTTPS servers, but you can use let's encrypt certificates.
Following settings must be provided for server mode:
- URL - in form https://yourdomain.com:8443.
- IP - Ip address, where the server will be bound. Default 0.0.0.0. Do not change it if you are not sure.
- Port - actually only 443, 80, 88, 8443 ports are supported by telegram, but you can forward ports to any one through your router.
- Public certificate - required, if let's encrypt is disabled.
- Private key - required, if let's encrypt is disabled.
- Chain certificate (optional)
- Let's encrypt options - It is very easy to setup let's encrypt certificates. Please read here about it.
TODO:
- venue
- dialogs
- (simatec) Support for Compact mode
- (bluefox) Custom settings for states were added
- (Apollon77) fix #78
- (BuZZy1337) Fix a small error caused by previous commit
- (BuZZy1337) Ask if saved users should be wiped when password is changed.
- (BuZZy1337) Show warning if no password is set.
- (BuZZy1337) Just minor cosmetic fixes/changes
- (bluefox) The ability of enable/disable of states controlling was added
- (BuZZy1337) Added possibility to delete authenticated users in the Adapter-Config screen (via Messages tab)
- (BuZZy1337) fixed a problem "building" the Blockly sendto block when no adapter instance exists.
- (BuZZy1337) Added "disable notification" checkbox to blockly block.
- (BuZZy1337) Added "parse_mode" selector to blockly block.
- (BuZZy1337) Added support for sending Messages to Group-Chats via Blockly.
- (BuZZy1337) Added possibility to specify more than one recipient. (separated by comma)
- (BuZZy1337) remove HTML Tags from Logerror-Messages
- (Apollon77) fix misleading error when setting a value for a state
- (Osrx) Added Socks5 settings to config dialog on machines running admin 2.
- (kirovilya) Changed library for Proxy Socks5
- (Haba) Added support for Proxy Socks5.
- (AlGu) Possibility to define polling interval in configuration wizard. Default is 300ms.
- (BasGo) Added checks before accessing non-existing options
- (BasGo) Fixed issue preventing adapter to terminate correctly
- (BasGo) Fixed issue with wrong callback query id
- (BasGo) Reworked configuration and translation
- (Haba) New objects: botSendChatId, botSendMessageId
- (bluefox) Possibility to send photo, video, document, audio as buffer.
- (Haba) Sending an image without intermediate caching
- (Haba) Updating for Admin3
- (kirovilya) Allow send gif via sendDocument
- (Haba1234) initPolling() this is deprecated. -> startPolling()
- (Haba1234) Add log polling_error and webhook_error.
- (Haba) New function: deleteMessage. Update version lib node-telegram-bot-api
- (Haba) Fix an incorrect order of writing variables
- (Haba) inline keyboard and new functions: answerCallbackQuery, editMessageText, editMessageReplyMarkup
- (dwm) Fix longitude and latitude
- (bluefox) Fix position message
- (bluefox) show only installed instances in blockly
- (bluefox) Show user name in error message
- (bluefox) server mode with web hooks
- (bluefox) support of blockly
- (bluefox) filter out double messages
- (bluefox) translations
- (bluefox) configurable restarting/started texts
- (bluefox) response to chatId and not to userId
- (bluefox) cut messages with @
- (bluefox) add new states: requestChatId and requestUserId
- (bluefox) allow send messages to chats via chat-ID
- (bluefox) support of video(mp4), audio, document, location, sticker, action
- (bluefox) restart connection every hour
- (bluefox) replace "_" with " " when sending to text2command
- (bluefox) replace "/" with "#" when sending to text2command
- (Jonas) fix unload
- (Jonas) fix configuration and send to more than one user
- (bluefox) add send photo possibility
- (bluefox) fix double responses.
- (bluefox) inform about new start
- (bluefox) fix error with sendTo
- (bluefox) intial commit
The MIT License (MIT)
Copyright (c) 2016-2019, bluefox dogafox@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.