Telegram
To send notifications on Telegram, you need to create a Telegram bot and invite him in a group chat where announcements will be made. See Telegram docs for information on bot setup. The bot is controlled by dedicated commands, meaning it can stay in "privacy mode" and do not have access to other chat messages (this is default in Telegram). You can also register three commands that the bot will support: /help, /ack and /status (see below). This is not strictly required, but Telegram clients make use of this information to facilitate communication with a bot.
After creation of the bot you will know a "bot token" (some long string). Bot library also needs know the ID of the chat where the bot will speak. The easiest way to find it out is to open a link https://api.telegram.org/bot<bot-token>/getUpdates. You will need to insert your bot ID into this link (without angle brackets) before opening. The link will show you what your bot sees. Once opened, type a command like /help in the chat, then refresh the API web page. You will see a piece of JSON; find the "chat" section and get its ID field. In my case it is some negative integer number.
Apart from group chat, the application also supports communication in private, so you can open chat to the bot and write commands there. This way of communication is convenient when you are testing your bot, to avoid testing traffic in the group chat. The way of finding out ID of this private chat is the same as described above for the group chat.
One important thing to notice is that communication with Telegram cloud must be made via HTTPS, which means that encryption support will be added into the sketch. This would easily double its size (e.g., from 250 kB to 500 kB). This is why Telegram support is not included by default and needs to be activated during program compilation (see Getting Started for more info). Encryption would also take non-negligible time to process Telegram traffic; for this reason it is recommended to run ESP8266 in 160 MHz mode instead of standard 80 MHz.
Another catch with connection encryption is that it requires significant amount of RAM — peaking at 28 kB as per ESP8266 BearSSL documentation. An empty sketch would normally have about 40 kB of RAM available, and with a feature-rich application like Mailbox one, the remaining memory would be almost all consumed. This means that the application with Telegram enabled may occasionally hit "out of memory" condition, which would cause failures in Telegram reporting at best and reboot at worst. It also makes application prone to stability problems when upgrading the libraries or ESP8266 Arduino Core itself (this was actually observed).
To configure Telegram connection, open the mailbox website http://mailbox.local and go to the conf section:
Enter bot token and chat ID. You can click the Test button to send a test message from Mailbox. Make sure that you checked on the service and click Save.
The underlying library Universal-Telegram-Bot uses polling to receive new messages. Frequency of polling determines how quickly bot will react on your commands. The default set in the sketch is generous 20 seconds, meaning bot will lazily respond to your command anytime between 0 and 20 seconds. In this application it is not important to have fast response, but if you want to make it quicker, change POLL_INTERVAL constant in Telegram.cpp. 20 seconds are selected because the SSL connection timeout in ESP8266 Arduino library is set to 15 seconds; so that we do not try piling up poll requests if the connection to Telegram gets unstable. Note that even with 20 seconds the application generates a lot of traffic (like tens of GB per month). The reason for this is not yet understood — it could be a bug or misuse of the library.
Sending notification, on the contrary, is a direct action, so delays are mostly linked to Telegram processing. Taking into account ≈2 seconds for a message to arrive to the receiver first, in normal conditions you will get Telegram notification about 4–6 seconds after the door has been opened.
Bot supports three commands: /help — show help, /ack — acknowledge mailbox alarm, and /status — show mailbox status. Both /ack and status support as optional parameter an ID of mailbox of interest, e.g., /status 1. If not specified, action will be taken on all mailboxes at once. /ack also supports +status option, which will reset alarm and display status in one single message. The most frequently used commands are conveniently presented in the keyboard, so they can be entered with one tap.
/status command will show for each mailbox its alarm status, battery level (%), radio link quality (%), uptime and the last time when mailbox was active. This is the same information that can be found from the internal website.
Apart from normal notifications, you will also get Telegram messages for off-normal events: when remote (mailbox) or local (home) module has rebooted, when mailbox is low on battery or have not reported for more than three consecutive days, or when there have been mailbox events lost due to bad connection.
Notifications are prepended with a time stamp. Even though it is not strictly required, as each message in Telegram has its own time stamp, it could be still useful for telling similar events apart. Also, at the times when you move far away from home, Telegram will show time stamps of your area, while the time stamp in the message would still be in the home's time.
Like any alarm actions, acknowledgements made via Telegram are logged in the application log:
2020/11/25 10:19:19: Alarm "Door flipped" acknowledged via Telegram by Denis
System (diagnostic) log will report all commands received by the bot, either in public or in private. Reconfiguration events will be equally reported (without credentials).
On a final note, while direct communication with Telegram from ESP8266 is possible, it can be clearly seen that it is not the best choice. It blows up the sketch size, puts a lot of stress on ESP CPU and RAM and may render the application unstable, especially when Internet or Telegram become unresponsive. Probably, a better option would be to send a message to an MQTT server in a local network, and have some application on top to talk to Telegram. This might be done in future versions of the program.