Properties
Yaml
Toml
Groovy
Hocon
JSON
micronaut:
chatbots:
telegram:
bots:
mnexample:
token: 'xxxyyyzzz'
at-username: '@MicronautExampleBot'
Ease the creation of ChatBots with the Micronaut Framework
Version: 1.3.0
This module eases the creation of Telegram Bots, Basecamp Bots with the Micronaut Framework.
For this project, you can find a list of releases (with release notes) here:
You can develop a Telegram Bot quickly with Micronaut Chatbots.
Create a Telegram Bot by talking with the @BotFather.
To see what actions the BotFather can perform for you, send /help in the chat.
|
First send the command /newbot
to the BotFather and follow the instructions to create a new bot.
At the end of this process, you will receive a token to access the HTTP API.
Properties
Yaml
Toml
Groovy
Hocon
JSON
micronaut:
chatbots:
telegram:
bots:
mnexample:
token: 'xxxyyyzzz'
at-username: '@MicronautExampleBot'
micronaut.chabots.telegram.bots.*.token
matches the value specified as secret_token
while setting the webhook.
You have to set the webhook via the Telegram API.
curl -X "POST" "https://api.telegram.org/bot{httpApiToken}/setWebhook?url={webhookUrl}&secret_token={secretToken}"
httpApiToken
You obtain this value via the @BotFather
webhookUrl
is the endpoint of your Micronaut application.
{secretToken}
- A secret token, Telegram sends in a header X-Telegram-Bot-Api-Secret-Token
in every webhook request.
To develop your bot, create beans of type TelegramHandler.
Java
Groovy
Kotlin
@Singleton
class HelloWorldHandler implements TelegramHandler<SendMessage> {
private final SpaceParser<Update, Chat> spaceParser;
HelloWorldHandler(SpaceParser<Update, Chat> spaceParser) {
this.spaceParser = spaceParser;
}
@Override
public boolean canHandle(@Nullable TelegramBotConfiguration bot, @NotNull Update input) {
return input.getMessage().getText().contains("hello");
}
@Override
public Optional<SendMessage> handle(@Nullable TelegramBotConfiguration bot, @NotNull Update input) {
return SendMessageUtils.compose(spaceParser, input, "Hello World");
}
}
To respond to Telegram Bot commands, with static content, you can extend from CommandHandler.
For example to respond to an /about
command with a static message, you create a CommandHandler
bean:
Java
Groovy
Kotlin
@Singleton
class AboutCommandHandler extends CommandHandler {
private static final String COMMAND_ABOUT = "/about";
AboutCommandHandler(
TelegramSlashCommandParser slashCommandParser,
TextResourceLoader textResourceLoader,
SpaceParser<Update, Chat> spaceParser
) {
super(slashCommandParser, textResourceLoader, spaceParser);
}
@Override
@NonNull
public String getCommand() {
return COMMAND_ABOUT;
}
}
And then create some content with a matching name in the botcommands
directory:
Bot developed with 💙 using [Micronaut](https://micronaut.io)
The botcommands
directory may be configured via the micronaut.chatbots.folder
configuration property.
Property | Type | Description |
---|---|---|
|
boolean |
Whether chatbots is enabled. Default value (true). |
|
java.lang.String |
The folder to look for bot commands. |
|
java.util.List |
Possible static command file extensions. Default values MARKDOWN, HTML, TXT |
Chatbot handlers have order, and the first handler to support a command is the one used.
To change the order of handlers, you can override the getOrder
method in your handler.
Java
Groovy
Kotlin
@Singleton
class UnknownCommandHandler implements TelegramHandler<SendMessage> {
private final SpaceParser<Update, Chat> spaceParser;
UnknownCommandHandler(SpaceParser<Update, Chat> spaceParser) {
this.spaceParser = spaceParser;
}
@Override
public boolean canHandle(@Nullable TelegramBotConfiguration bot, @NotNull Update input) {
return true; // (1)
}
@Override
public Optional<SendMessage> handle(@Nullable TelegramBotConfiguration bot, @NotNull Update input) {
return SendMessageUtils.compose(spaceParser, input, "I don't know how to handle your query: %s".formatted(input.getMessage().getText()));
}
@Override
public int getOrder() {
return Ordered.LOWEST_PRECEDENCE; // (2)
}
}
1 | This handler will handle any message. |
2 | Ensure this handler is last in the list of handlers. |
If you want to deploy to AWS Lambda, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-telegram-lambda")
Use the class io.micronaut.chatbots.telegram.lambda.Handler
as the AWS Lambda function handler.
If you want to deploy to Google Cloud Functions, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-telegram-gcp-function")
You can use the following entry point:
Use the class io.micronaut.chatbots.telegram.googlecloud.Handler
as the Http Function entrypoint.
If you want to deploy to an Azure function, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-telegram-azure-function")
This adds an AzureFunction
with the name TelegramTrigger
via the class io.micronaut.chatbots.telegram.azurefunction.Handler
If you want to configure one endpoint as the Telegram chatbot webhook while using a runtime such as Netty or Servlet, you can include the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-mironaut-chatbots-telegram-http")
You can configure the path with:
Property | Type | Description |
---|---|---|
|
boolean |
Enables the controller. Default value true . |
|
java.lang.String |
Path to the controller. Default value "/telegram" . |
You can develop Basecamp Chatbots quickly with Micronaut Chatbots.
You have to set the webhook via the Basecamp API.
curl -s \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"service_name":"${BOTNAME}","command_url":"${YOUR_HTTP_TRIGGER_URL}"}' \
https://3.basecampapi.com/${APP_ID}/buckets/${BUCKET_ID}/chats/${CHAT_ID}/integrations.json
BOTNAME
is the name of your bot
ACCESS_TOKEN
is your Oauth2 Basecamp access token
YOUR_HTTP_TRIGGER_URL
is the https address of your URL of your controller or function
APP_ID
, BUCKET_ID
and CHAT_ID
are the IDs of your Basecamp application, bucket and chat respectively
To develop your bot, create beans of type BasecampHandler.
Java
Groovy
Kotlin
@Singleton
class HelloWorldHandler implements BasecampHandler {
@Override
public boolean canHandle(BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return input.getCommand().contains("hello");
}
@NonNull
@Override
public Optional<String> handle(BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return Optional.of("Hello World");
}
}
To respond to specific messages with static content, you extend from BasecampHandler and utilize the TextResourceLoader class to load the content.
For example to respond to an /about
command with a static message, you create a bean:
Java
Groovy
Kotlin
@Singleton
class AboutCommandHandler implements BasecampHandler {
public static final String ABOUT = "about";
private final TextResourceLoader textResourceLoader;
AboutCommandHandler(TextResourceLoader textResourceLoader) {
this.textResourceLoader = textResourceLoader;
}
@Override
public boolean canHandle(@Nullable BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return input.getCommand().equalsIgnoreCase("/" + ABOUT);
}
@Override
public @NonNull Optional<String> handle(@Nullable BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return textResourceLoader
.composeCommandResponse(ABOUT)
.map(CommandResponse::text);
}
}
And then create some content with a matching name in the botcommands
directory:
Bot developed with 💙 using [Micronaut](https://micronaut.io)
The botcommands
directory may be configured via the micronaut.chatbots.folder
configuration property.
Property | Type | Description |
---|---|---|
|
boolean |
Whether chatbots is enabled. Default value (true). |
|
java.lang.String |
The folder to look for bot commands. |
|
java.util.List |
Possible static command file extensions. Default values MARKDOWN, HTML, TXT |
Chatbot handlers have order, and the first handler to support a command is the one used.
To change the order of handlers, you can override the getOrder
method in your handler.
Java
Groovy
Kotlin
@Singleton
class UnknownCommandHandler implements BasecampHandler {
@Override
public boolean canHandle(@Nullable BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return true; // (1)
}
@Override
public @NonNull Optional<String> handle(@Nullable BasecampBotConfiguration bot, @NonNull @NotNull Query input) {
return Optional.of("I don't know how to handle your query: %s".formatted(input.getCommand()));
}
@Override
public int getOrder() {
return Ordered.LOWEST_PRECEDENCE; // (2)
}
}
1 | This handler will handle any message. |
2 | Ensure this handler is last in the list of handlers. |
If you want to deploy to AWS Lambda, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-basecamp-lambda")
Use the class io.micronaut.chatbots.basecamp.lambda.Handler
as the AWS Lambda function handler.
If you want to deploy to Google Cloud Functions, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-basecamp-gcp-function")
You can use the following entry point:
Use the class: io.micronaut.chatbots.basecamp.googlecloud.Handler
as the Http Function entrypoint.
If you want to deploy to an Azure function, you can use the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-basecamp-azure-function")
This adds an AzureFunction
with the name BasecampTrigger
via the class io.micronaut.chatbots.basecamp.azurefunction.Handler
If you want to configure one endpoint as the Basecamp chatbot webhook while using a runtime such as Netty or Servlet, you can include the following dependency:
Gradle
Maven
implementation("io.micronaut.chatbots:micronaut-chatbots-basecamp-http")
You can configure the path with:
Property | Type | Description |
---|---|---|
|
boolean |
Enables the controller. Default value true. |
|
java.lang.String |
Path to the controller. Default value "/basecamp". |
This section documents breaking changes between Micronaut Chatbots versions:
The private class field io.micronaut.chatbots.google.api.Space.type
deprecated previously has been removed.
As a consequence the corresponding accessor/mutator methods getType()
and setType(Type)
have also been removed,
even though they were not deprecated explicitly.
Use the accessor/mutator methods for singleUserBotDm
or spaceType
(developer preview) instead.
You can find the source code of this project in this repository: