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 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. If you are using an emulation mode, you can provide ID of your private chat to the application, so that it will respond to you in private. The way of finding out ID of this chat is the same as described above for the group chat.
Once you have collected all IDs, fill them in the mailbox sketch, as explained in Getting Started.
One important thing to notice is that communication with Telegram cloud must be made via HTTPS, which means that encryption support will be linked into the sketch. This will easily double its size (e.g., from 250 kB to 500 kB).
The underlying library Universal-Telegram-Bot uses polling to receive update. Frequency of polling determines how quickly bot will react on your commands. The default set in the sketch is 10 seconds, meaning bot will respond to your command anytime between 0 and 10 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. Note that even with 10 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 message to arrive to the receiver first, in a normal conditions you will get Telegram notification about 4-6 seconds after door has been opened.
Bot supports three commands: /help — show help, /ack — acknowledge mailbox alarm, and /status — show mailbox status. /ack also supports +status parameter, which will reset alarm and display status in one single message. The most frequently used commands are conveniently presented in keyboard, so they can be entered with one tap.
/status command will show for each mailbox its alarm status, battery level (%), radio link quality (%) and the last moment the mailbox was active.
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.
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 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 bot, either in public or in private.
On a final note, while direct communication with Telegram from ESP8266 is possible, it can clearly seen that it is not the best choice. It blows up the sketch size and puts a lot of load on ESP (especially when Internet or Telegram become unresponsive). Probably, a better option would be to send a message to 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.