Concept of Telegram bots
A bot is a Telegram entity which can send messages to a channel and manage them. Tools like herald use the Telegram Bot API to interact with channels through bots.
Creating a custom bot
Create a custom bot by starting a conversation with @BotFather and provide the bot's API token as described above.
Make sure the
heraldCore.m file and the
private folder are in the current workspace or have been added to PATH. It is recommended to use a wrapper around the
heraldCore() function (see below).
On the system side, 'cURL' needs to installed. This is included in linux, macOS and Windows 10. If cURL is not available, please install from this site. For Windows, the Chocolatey method is recommended.
Herald works with Matlab R2007a and newer. Older versions may work but have not yet been tested.
The following documentation assumes you created a wrapper named
Sending a message or a plot
herald(text) sends the message text to the channel.
herald(figHandle) sends the figure with handle figHandle as a PNG directly to the channel.
msg = herald(...) returns information about the message or picture sent in the struct msg.
Deleting a message
herald(, msg) will delete the message msg. This can be text or a picture.
Updating a message
herald(text, msg) updates the message msg with the new content text.
Note: updating an image is currently not supported. Consider deleting the picture and sending a new one.
Notes on using Herald
How to obtain a chatId (using direct chat)
After starting a conversation with your custom bot, forward a message inside that conversation to @get_id_bot and the
chatId will be returned to you.
How to obtain a chatId (using channels)
chatId is obtained from forwarding a random message inside the dedicated channel to @get_id_bot. This channel should have your custom bot as an administrator in order to function.
Note about wrappers
It is recommended to build a wrapper around
heraldCore() similar to the included
heraldWrapper(). The wrapper will forward all requests "as is" to the core herald function along with the chat id (see above).
If you choose to not use a wrapper and instead interact with the
heraldCore() function directly, two additional arguments must be provided as such:
heraldCore(botToken, chatId, ...). Detailed instructions can be obtained by running
help heraldCore in Matlab.