An implementation of the Telegram Bot API in 100% OCaml, using Lwt for asynchronous operations and Cohttp for networking. Implements most basic functionality present in the API, plus convenience modules for error handling and defining commands.
Published: 20 Dec 2017
Before creating a bot, it's recommended that you read through this page, which outlines some of the basic usage of bots and the process of registering and managing your bots.
The API is designed to make heavy use of OCaml's module system to provide a configurable template for creating new bots, with optional higher-level representations of features such as commands, chat events, or inline responses. All bots are created as modules, by instantiating the
Telegram.Api.Mk functor, which will generate a module for using your bot directly. The direct commands can be accessed as members of the module, with the API's methods in
~named arguments. However, when using the higher-level APIs (for the inline responses, chat events, or commands), it may be useful to reuse the same command generically across different bots. As a result, the commands/inline response functions are expected to return values of the
Telegram.Api.Command.action. Using this type, the command is represented as an abstract data type. These commands are named in
CamelCase, but they are equivalent to those directly accessible through the module. Note that the arguments are not named, so read the official documentation or the type signatures of the equivalent functions in order to understand what each argument represents.
If you need to get around the restrictions of using the
action type to encode the responses, you can use the peek_update function to view the update before it's removed from the queue and process it manually. Note that the
Telegram.Api.Command module provides convenience functions for helping you parse incoming commands manually if necessary.
Full OCamldoc-generated documentation is available here.
Send "Hello, world" message
module MyBot = Telegram.Api.Mk (struct include Telegram.BotDefaults let token = [%blob "../bot.token"] end);; Lwt_main.run begin MyBot.send_message ~chat_id:(int_of_string [%blob "../chat.id"]) ~text:"Hello, world" ~disable_notification:true ~reply_to:None ~reply_markup:None end
Note that this example loads the files "chat.id" and "bot.token" from the surrounding directory to use as the
Demos, examples, and users:
hello world - Send "Hello, world" to a chat
example - Responds to /say_hi, tests getting user profile pictures
inline - Inline bot test
greet - Chat event test
glgbot - Some groupchat utilities: saved quotes, correcting messages, music jukebox, cute cat pics, and more
telegraml-dashboard - Tool for auto-generating web dashboards for your bots
If you're using TelegraML and you'd like your bot/extension/tutorial listed here, feel free to open a PR to list it here with a link and a short description.
All of the data types
Most of the methods (everything but
Modular interface makes writing extensions simple (see telegraml-dashboard)
High-level interface for commands (
Telegram.Api.BOT.commands : Telegram.Api.Command.command list)
Tons of convenience functions for parsing commands, etc.
Can exclude commands meant for other bots (
Telegram.Api.BOT.command_postfix : string option)
Admin-only command authorization (
Telegram.Api.Command.with_auth : command:Telegram.Api.Command.command -> Telegram.Api.Command.action)
Global command enabling/disabling
Combinators for composing complex actions sequences (
High-level chat event handling (
Telegram.Api.BOT.new_chat_member : Telegram.Api.Chat.chat -> Telegram.Api.User.user -> Telegram.Api.Command.action, etc.)
High-level inline mode bindings (
Telegram.Api.BOT.inline : Telegram.Api.InlineQuery.inline_query -> Telegram.Api.Command.action)
Telegram.Api.TELEGRAM_BOT.run : ?log:bool -> unit -> unitfunction for easy event loop setup
Asynchronous, Lwt-based I/O
sendDocument(uses only mime-type