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](https://telegram.me/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](https://curl.haxx.se). For Windows, the [Chocolatey method](https://chocolatey.org/packages/curl) 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 `herald.m`.
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](https://telegram.me/get_id_bot) and the `chatId` will be returned to you.
How to Obtain a ChatId (Using Channels)
The `chatId` is obtained from forwarding a random message inside the dedicated channel to [@get_id_bot](https://telegram.me/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.