feat: complete change language flow, add tests

* to check: possible missing javadoc

.markdownlint.yaml

@@ -1,2 +1,3 @@
 MD013:
   line_length: 120
+  code_blocks: false

README.md

@@ -26,7 +26,9 @@ valid Telegram Bot token.
 To configure Webhook configuration for your bot, open up a terminal and type:
 
 ```shell
-curl -F "url=https://example.com/api/tg" https://api.telegram.org/bot<YOUR BOT TOKEN>/setWebhook
+curl -F "url=https://example.com/api/tg" \
+ -F "allowed_updates=[\"message\", \"edited_message\", \"channel_post\", \"edited_channel_post\", \"inline_query\", \"choosen_inline_result\", \"callback_query\", \"poll\", \"poll_answer\", \"my_chat_member\", \"chat_member\", \"chat_join_request\"]" \
+ https://api.telegram.org/bot<YOUR BOT TOKEN>/setWebhook
 ```
 
 ## Building

src/etc/stork/stork.yml

@@ -35,7 +35,7 @@ max_java_memory: 512
 #min_java_memory_pct: 10
 #max_java_memory_pct: 20
 
-# Try to create a symbolic link to java executable in <app_home>/run with
+# Try to createVelocityToolManager a symbolic link to java executable in <app_home>/run with
 # the name of "<app_name>-java" so that commands like "ps" will make it
 # easier to find your app
 symlink_java: true

src/main/java/com/github/polpetta/mezzotre/i18n/LocalizedMessageFactory.java

@@ -1,6 +1,7 @@
 package com.github.polpetta.mezzotre.i18n;
 
 import java.util.Locale;
+import java.util.ResourceBundle;
 import javax.inject.Inject;
 import org.apache.velocity.app.VelocityEngine;
 import org.apache.velocity.runtime.resource.loader.JarResourceLoader;
@@ -20,7 +21,7 @@ public class LocalizedMessageFactory {
     this.velocityEngine = velocityEngine;
   }
 
-  public ToolManager create(Locale locale) {
+  public ToolManager createVelocityToolManager(Locale locale) {
 
     final ToolManager toolManager = new ToolManager();
     toolManager.setVelocityEngine(velocityEngine);
@@ -37,4 +38,8 @@ public class LocalizedMessageFactory {
     toolManager.configure(factoryConfiguration);
     return toolManager;
   }
+
+  public ResourceBundle createResourceBundle(Locale locale) {
+    return ResourceBundle.getBundle("i18n/message", locale);
+  }
 }

src/main/java/com/github/polpetta/mezzotre/orm/model/TgChat.java

@@ -3,7 +3,6 @@ package com.github.polpetta.mezzotre.orm.model;
 import com.github.polpetta.types.json.ChatContext;
 import io.ebean.annotation.DbJsonB;
 import io.ebean.annotation.Length;
-import javax.annotation.Nullable;
 import javax.persistence.Column;
 import javax.persistence.Entity;
 import javax.persistence.Id;
@@ -41,18 +40,13 @@ public class TgChat extends Base {
 
   /** The locale to use when chatting. Defaults to {@code en-US} */
   @NotNull
-  @Length(5)
+  @Length(10)
   @Column(columnDefinition = "varchar(5) not null default 'en-US'")
   private String locale;
 
-  /**
-   * See {@link #TgChat( Long, ChatContext, String)}. The default locale set here is {@code en-US}
-   */
-  public TgChat(Long id, ChatContext chatContext) {
-    this.id = id;
-    this.chatContext = chatContext;
-    this.locale = "en";
-  }
+  @NotNull
+  @Column(columnDefinition = "boolean default false")
+  private Boolean hasHelpBeenShown;
 
   /**
    * Build a new Telegram Chat
@@ -61,11 +55,21 @@ public class TgChat extends Base {
    * @param chatContext the context of the chat, where possible metadata can be stored. See {@link
    *     ChatContext}
    * @param locale a specific locale for this chat
+   * @param hasHelpBeenShown boolean indicating if the user has seen the /help command at least once
    */
-  public TgChat(Long id, @Nullable ChatContext chatContext, String locale) {
+  public TgChat(Long id, ChatContext chatContext, String locale, boolean hasHelpBeenShown) {
     this.id = id;
     this.chatContext = chatContext;
     this.locale = locale;
+    this.hasHelpBeenShown = hasHelpBeenShown;
+  }
+
+  /**
+   * See {@link #TgChat( Long, ChatContext, String,boolean)}. The default locale set here is {@code
+   * en-US}, and {@link #hasHelpBeenShown} is set to {@code false}
+   */
+  public TgChat(Long id, ChatContext chatContext) {
+    this(id, chatContext, "en-US", false);
   }
 
   public Long getId() {
@@ -89,6 +93,14 @@ public class TgChat extends Base {
     this.locale = locale;
   }
 
+  public Boolean getHasHelpBeenShown() {
+    return hasHelpBeenShown;
+  }
+
+  public void setHasHelpBeenShown(Boolean hasHelpBeenShown) {
+    this.hasHelpBeenShown = hasHelpBeenShown;
+  }
+
   @Override
   public String toString() {
     return "TgChat{"
@@ -99,6 +111,8 @@ public class TgChat extends Base {
         + ", locale='"
         + locale
         + '\''
+        + ", isTutorialComplete="
+        + hasHelpBeenShown
         + '}';
   }
 }

src/main/java/com/github/polpetta/mezzotre/route/Telegram.java

@@ -60,7 +60,7 @@ public class Telegram {
   public CompletableFuture<String> incomingUpdate(Context context, Update update) {
     /*
     Steps:
-    1 - Retrieve the chat. If new chat, create and entry in the db
+    1 - Retrieve the chat. If new chat, createVelocityToolManager and entry in the db
     2 - Check if the incoming payload is an inline event (keyboard, query, ecc). Possibly check if there is any context previously saved in the database to retrieve. In that case, process the payload accordingly
     3 - If it is not an inline event, then process it as an incoming message
      */

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/SelectLanguageTutorial.java

@@ -4,9 +4,15 @@ import com.github.polpetta.mezzotre.i18n.LocalizedMessageFactory;
 import com.github.polpetta.mezzotre.orm.model.CallbackQueryContext;
 import com.github.polpetta.mezzotre.orm.model.query.QCallbackQueryContext;
 import com.github.polpetta.mezzotre.orm.model.query.QTgChat;
+import com.github.polpetta.mezzotre.util.UUIDGenerator;
+import com.github.polpetta.types.json.CallbackQueryMetadata;
+import com.pengrad.telegrambot.model.Message;
 import com.pengrad.telegrambot.model.Update;
+import com.pengrad.telegrambot.model.request.InlineKeyboardButton;
+import com.pengrad.telegrambot.model.request.InlineKeyboardMarkup;
 import com.pengrad.telegrambot.model.request.ParseMode;
 import com.pengrad.telegrambot.request.BaseRequest;
+import com.pengrad.telegrambot.request.EditMessageText;
 import com.pengrad.telegrambot.request.SendMessage;
 import io.vavr.control.Try;
 import java.nio.charset.StandardCharsets;
@@ -24,18 +30,20 @@ import org.apache.velocity.util.StringBuilderWriter;
 import org.slf4j.Logger;
 
 /**
- * ChangeLanguage event is related to support locale change for a particular chat
+ * SelectLanguageTutorial event is related to support locale change for a particular chat when the
+ * interaction with a new user starts
  *
  * @author Davide Polonio
  * @since 1.0
  */
 @Singleton
-public class ChangeLanguage implements Processor {
+public class SelectLanguageTutorial implements Processor {
 
-  public static final String EVENT_NAME = "changeLanguage";
+  public static final String EVENT_NAME = "selectLanguageTutorial";
   private final Executor threadPool;
   private final LocalizedMessageFactory localizedMessageFactory;
   private final Logger log;
+  private final UUIDGenerator uuidGenerator;
 
   /**
    * Additional fields that are related to {@code changeLanguage} event
@@ -79,13 +87,15 @@ public class ChangeLanguage implements Processor {
   }
 
   @Inject
-  public ChangeLanguage(
+  public SelectLanguageTutorial(
       @Named("eventThreadPool") Executor threadPool,
       LocalizedMessageFactory localizedMessageFactory,
-      Logger log) {
+      Logger log,
+      UUIDGenerator uuidGenerator) {
     this.threadPool = threadPool;
     this.localizedMessageFactory = localizedMessageFactory;
     this.log = log;
+    this.uuidGenerator = uuidGenerator;
   }
 
   @Override
@@ -99,13 +109,15 @@ public class ChangeLanguage implements Processor {
     return CompletableFuture.supplyAsync(
             () ->
                 Optional.of(callbackQueryContext.getFields().getTelegramChatId())
-                    .filter(
-                        chatId ->
-                            chatId.longValue() != 0L
-                                && !chatId.isNaN()
-                                && !chatId.isInfinite()
-                                && chatId != Double.MIN_VALUE)
-                    .flatMap(chatId -> new QTgChat().id.eq(chatId.longValue()).findOneOrEmpty())
+                    .map(Double::longValue)
+                    // If we're desperate, search in the message for the chat id
+                    .or(
+                        () ->
+                            Optional.ofNullable(update.callbackQuery().message())
+                                .map(Message::messageId)
+                                .map(Long::valueOf))
+                    .filter(chatId -> chatId != 0L && chatId != Long.MIN_VALUE)
+                    .flatMap(chatId -> new QTgChat().id.eq(chatId).findOneOrEmpty())
                     .map(
                         tgChat -> {
                           tgChat.setLocale(
@@ -117,6 +129,11 @@ public class ChangeLanguage implements Processor {
                                           Field.NewLanguage.getName(),
                                           Language.English.getLocale()));
                           tgChat.save();
+                          log.trace(
+                              "Locale for chat "
+                                  + tgChat.getId()
+                                  + " is now set in "
+                                  + tgChat.getLocale());
                           return tgChat;
                         })
                     .orElseThrow(
@@ -135,10 +152,13 @@ public class ChangeLanguage implements Processor {
                   Try.of(
                           () -> {
                             final Locale locale = Locale.forLanguageTag(tgChat.getLocale());
-                            final ToolManager toolManager = localizedMessageFactory.create(locale);
+                            final ToolManager toolManager =
+                                localizedMessageFactory.createVelocityToolManager(locale);
                             final VelocityContext velocityContext =
                                 new VelocityContext(toolManager.createContext());
 
+                            velocityContext.put("hasHelpBeenShown", tgChat.getHasHelpBeenShown());
+
                             final StringBuilder content = new StringBuilder();
                             final StringBuilderWriter stringBuilderWriter =
                                 new StringBuilderWriter(content);
@@ -146,7 +166,7 @@ public class ChangeLanguage implements Processor {
                             toolManager
                                 .getVelocityEngine()
                                 .mergeTemplate(
-                                    "/template/callbackQuery/changeLanguage.vm",
+                                    "/template/callbackQuery/selectLanguageTutorial.vm",
                                     StandardCharsets.UTF_8.name(),
                                     velocityContext,
                                     stringBuilderWriter);
@@ -156,7 +176,7 @@ public class ChangeLanguage implements Processor {
                           })
                       .get();
 
-              log.trace("ChangeLanguage event - message to send back: " + message);
+              log.trace("SelectLanguageTutorial event - message to send back: " + message);
 
               final String callBackGroupToDelete = callbackQueryContext.getEntryGroup();
               final int delete =
@@ -167,8 +187,53 @@ public class ChangeLanguage implements Processor {
                       + " entries regarding callback group "
                       + callBackGroupToDelete);
 
-              return Optional.of(
-                  new SendMessage(tgChat.getId(), message).parseMode(ParseMode.Markdown));
+              final Optional<Integer> messageId =
+                  Optional.ofNullable(update.callbackQuery().message()).map(Message::messageId);
+              BaseRequest<?, ?> baseRequest;
+              Optional<InlineKeyboardMarkup> helpButton = Optional.empty();
+              if (!tgChat.getHasHelpBeenShown()) {
+                // Add a button to show all the possible commands
+                final String showMeTutorialString =
+                    localizedMessageFactory
+                        .createResourceBundle(Locale.forLanguageTag(tgChat.getLocale()))
+                        .getString("button.showMeTutorial");
+
+                final CallbackQueryMetadata callbackQueryMetadata =
+                    new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
+                        .withEvent(ShowHelp.EVENT_NAME)
+                        .withTelegramChatId(tgChat.getId())
+                        .build();
+
+                final CallbackQueryContext callbackData =
+                    new CallbackQueryContext(
+                        uuidGenerator.generateAsString(),
+                        uuidGenerator.generateAsString(),
+                        callbackQueryMetadata);
+                callbackData.save();
+
+                helpButton =
+                    Optional.of(
+                        new InlineKeyboardMarkup(
+                            new InlineKeyboardButton(showMeTutorialString)
+                                .callbackData(callbackData.getId())));
+              }
+
+              if (messageId.isPresent()) {
+                log.trace("message id is present - editing old message");
+                final EditMessageText editMessageText =
+                    new EditMessageText(tgChat.getId(), messageId.get(), message)
+                        .parseMode(ParseMode.Markdown);
+                helpButton.ifPresent(editMessageText::replyMarkup);
+                baseRequest = editMessageText;
+              } else {
+                log.trace("no message id - sending a new message");
+                final SendMessage sendMessage =
+                    new SendMessage(tgChat.getId(), message).parseMode(ParseMode.Markdown);
+                helpButton.ifPresent(sendMessage::replyMarkup);
+                baseRequest = sendMessage;
+              }
+
+              return Optional.of(baseRequest);
             },
             threadPool);
   }

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/ShowHelp.java

@@ -0,0 +1,26 @@
+package com.github.polpetta.mezzotre.telegram.callbackquery;
+
+import com.github.polpetta.mezzotre.orm.model.CallbackQueryContext;
+import com.pengrad.telegrambot.model.Update;
+import com.pengrad.telegrambot.request.BaseRequest;
+import com.pengrad.telegrambot.request.SendMessage;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+public class ShowHelp implements Processor {
+
+  public static String EVENT_NAME = "showHelp";
+
+  @Override
+  public String getEventName() {
+    return EVENT_NAME;
+  }
+
+  @Override
+  public CompletableFuture<Optional<BaseRequest<?, ?>>> process(
+      CallbackQueryContext callbackQueryContext, Update update) {
+    // TODO implement this method and put `hasHelpBeenShown` in tgChat to false
+    return CompletableFuture.completedFuture(
+        Optional.of(new SendMessage(callbackQueryContext.getFields().getTelegramChatId(), "TODO")));
+  }
+}

src/main/java/com/github/polpetta/mezzotre/telegram/callbackquery/di/CallbackQuery.java

@@ -1,7 +1,8 @@
 package com.github.polpetta.mezzotre.telegram.callbackquery.di;
 
-import com.github.polpetta.mezzotre.telegram.callbackquery.ChangeLanguage;
 import com.github.polpetta.mezzotre.telegram.callbackquery.Processor;
+import com.github.polpetta.mezzotre.telegram.callbackquery.SelectLanguageTutorial;
+import com.github.polpetta.mezzotre.telegram.callbackquery.ShowHelp;
 import com.google.inject.AbstractModule;
 import com.google.inject.Provides;
 import java.util.Set;
@@ -12,7 +13,8 @@ public class CallbackQuery extends AbstractModule {
   @Provides
   @Singleton
   @Named("eventProcessors")
-  public Set<Processor> getEventProcessor(ChangeLanguage changeLanguage) {
-    return Set.of(changeLanguage);
+  public Set<Processor> getEventProcessor(
+      SelectLanguageTutorial selectLanguageTutorial, ShowHelp showHelp) {
+    return Set.of(selectLanguageTutorial, showHelp);
   }
 }

src/main/java/com/github/polpetta/mezzotre/telegram/command/Processor.java

@@ -30,6 +30,5 @@ public interface Processor {
    * @param update the update to process
    * @return a {@link CompletableFuture} with the result of the computation
    */
-  // FIXME cannot be void - we don't want pesky side effects!
   CompletableFuture<Optional<BaseRequest<?, ?>>> process(TgChat chat, Update update);
 }

src/main/java/com/github/polpetta/mezzotre/telegram/command/Start.java

@@ -3,7 +3,7 @@ package com.github.polpetta.mezzotre.telegram.command;
 import com.github.polpetta.mezzotre.i18n.LocalizedMessageFactory;
 import com.github.polpetta.mezzotre.orm.model.CallbackQueryContext;
 import com.github.polpetta.mezzotre.orm.model.TgChat;
-import com.github.polpetta.mezzotre.telegram.callbackquery.ChangeLanguage;
+import com.github.polpetta.mezzotre.telegram.callbackquery.SelectLanguageTutorial;
 import com.github.polpetta.mezzotre.util.Clock;
 import com.github.polpetta.mezzotre.util.UUIDGenerator;
 import com.github.polpetta.types.json.CallbackQueryMetadata;
@@ -76,7 +76,8 @@ public class Start implements Processor {
               Try.of(
                       () -> {
                         final Locale locale = Locale.forLanguageTag(chat.getLocale());
-                        final ToolManager toolManager = localizedMessageFactory.create(locale);
+                        final ToolManager toolManager =
+                            localizedMessageFactory.createVelocityToolManager(locale);
                         final VelocityContext context =
                             new VelocityContext(toolManager.createContext());
                         context.put("firstName", update.message().chat().firstName());
@@ -114,11 +115,11 @@ public class Start implements Processor {
                   uuidGenerator.generateAsString(),
                   groupId,
                   new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
-                      .withEvent(ChangeLanguage.EVENT_NAME)
+                      .withEvent(SelectLanguageTutorial.EVENT_NAME)
                       .withTelegramChatId(update.message().chat().id())
                       .withAdditionalProperty(
-                          ChangeLanguage.Field.NewLanguage.getName(),
-                          ChangeLanguage.Language.English)
+                          SelectLanguageTutorial.Field.NewLanguage.getName(),
+                          SelectLanguageTutorial.Language.English.getLocale())
                       .build());
 
           final CallbackQueryContext switchToItalian =
@@ -126,20 +127,30 @@ public class Start implements Processor {
                   uuidGenerator.generateAsString(),
                   groupId,
                   new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
-                      .withEvent(ChangeLanguage.EVENT_NAME)
+                      .withEvent(SelectLanguageTutorial.EVENT_NAME)
                       .withTelegramChatId(update.message().chat().id())
                       .withAdditionalProperty(
-                          ChangeLanguage.Field.NewLanguage.getName(),
-                          ChangeLanguage.Language.Italian)
+                          SelectLanguageTutorial.Field.NewLanguage.getName(),
+                          SelectLanguageTutorial.Language.Italian.getLocale())
                       .build());
 
+          final String englishButton =
+              localizedMessageFactory
+                  .createResourceBundle(Locale.US)
+                  .getString("changeLanguage.english");
+          final String italianButton =
+              localizedMessageFactory
+                  .createResourceBundle(Locale.ITALY)
+                  .getString("changeLanguage.italian");
+
           final SendMessage messageToSend =
               new SendMessage(chat.getId(), message)
                   .parseMode(ParseMode.Markdown)
                   .replyMarkup(
                       new InlineKeyboardMarkup(
-                          new InlineKeyboardButton("English").callbackData(switchToEnglish.getId()),
-                          new InlineKeyboardButton("Italian")
+                          new InlineKeyboardButton(englishButton)
+                              .callbackData(switchToEnglish.getId()),
+                          new InlineKeyboardButton(italianButton)
                               .callbackData(switchToItalian.getId())));
 
           switchToEnglish.save();

src/main/resources/db/migration/V1_0_0__Create_initial_db.sql

@@ -2,7 +2,7 @@
 create table callback_query_context (
                                         id                            varchar(36) not null,
                                         entry_group                   varchar(36) not null,
-                                        fields                        json not null,
+                                        fields                        json not null default '{}'::json not null,
                                         entry_created                 timestamptz not null,
                                         entry_modified                timestamptz not null,
                                         constraint pk_callback_query_context primary key (id)
@@ -12,6 +12,7 @@ create table telegram_chat (
                                id                            bigint generated by default as identity not null,
                                chat_context                  jsonb not null default '{}'::jsonb not null,
                                locale                        varchar(5) not null default 'en-US' not null,
+                               has_help_been_shown           boolean default false not null,
                                entry_created                 timestamptz not null,
                                entry_modified                timestamptz not null,
                                constraint pk_telegram_chat primary key (id)

src/main/resources/i18n/message.properties

@@ -1,6 +1,11 @@
 start.helloFirstName=Hello {0}! \ud83d\udc4b
 start.description=This is {0}, a simple bot focused on DnD content management! Please start by choosing a language down below \ud83d\udc47
-changeLanguage.drinkAction=*Proceeds to drink a potion with a strange, multicolor liquid*
-changeLanguage.setLanguage=Thanks! Now that I drank this modified potion of {0} that I''ve found at the "Crystal Fermentary" magic potion shop yesterday I can speak with you in the language you prefer!
-changeLanguage.instructions=You can always change your language settings by typing /changeLanguage in the chat.
+selectLanguageTutorial.drinkAction=*Proceeds to drink a potion with a strange, multicolor liquid*
+selectLanguageTutorial.setLanguage=Thanks! Now that I drank this modified potion of {0} that I''ve found at the "Crystal Fermentary" magic potion shop yesterday I can speak with you in the language that you prefer!
+selectLanguageTutorial.instructions=You can always change your language settings by typing /selectLanguageTutorial in the chat.
+changeLanguage.english=English
+changeLanguage.italian=Italian
 spell.speakWithAnimals=Speak with animals
+button.showMeTutorial=Show me what you can do!
+help.notShownYet=It seems you haven''t checked out what I can do yet! To have a complete list of my abilities, type /help in chat at any time!
+help.buttonBelow=Alternatively, you can click the button down below.

src/main/resources/i18n/message_en_US.properties

@@ -1,6 +1,11 @@
 start.helloFirstName=Hello {0}! \ud83d\udc4b
 start.description=This is {0}, a simple bot focused on DnD content management! Please start by choosing a language down below \ud83d\udc47
-changeLanguage.drinkAction=*Proceeds to drink a potion with a strange, multicolor liquid*
-changeLanguage.setLanguage=Thanks! Now that I drank this modified potion of {0} that I''ve found at the "Crystal Fermentary" magic potion shop yesterday I can speak with you in the language you prefer!
-changeLanguage.instructions=You can always change your language settings by typing /changeLanguage in the chat.
+selectLanguageTutorial.drinkAction=*Proceeds to drink a potion with a strange, multicolor liquid*
+selectLanguageTutorial.setLanguage=Thanks! Now that I drank this modified potion of {0} that I''ve found at the "Crystal Fermentary" magic potion shop yesterday I can speak with you in the language that you prefer!
+selectLanguageTutorial.instructions=You can always change your language settings by typing /selectLanguageTutorial in the chat.
+selectLanguageTutorial.english=English
+selectLanguageTutorial.italian=Italian
 spell.speakWithAnimals=Speak with animals
+button.showMeTutorial=Show me what you can do!
+help.notShownYet=It seems you haven''t checked out what I can do yet! To have a complete list of my abilities, type /help in chat at any time!
+help.buttonBelow=Alternatively, you can click the button down below.

src/main/resources/i18n/message_it.properties

@@ -1,6 +1,11 @@
 start.helloFirstName=Ciao {0}! \ud83d\udc4b
 start.description=Questo è {0}, un semplice bot che ci concenta sulla gestione di contenuto per DnD! Per favore comincia selezionando la lingua qui sotto \ud83d\udc47
-changeLanguage.drinkAction=*Procede a bere una pozione al cui suo interno si trova uno strano liquido multicolore*
-changeLanguage.setLanguage=Grazie! Ora che ho bevuto quest posizione modificata di {0} che ho trovato ieri al negozio di pozioni magiche la "Cristalleria Fermentatrice" posso parlare con te nel linguaggio che preferisci!
-changeLanguage.instructions=Puoi sempre cambiare le preferenze della tua lingua scrivendo /changeLanguage nella chat.
+selectLanguageTutorial.drinkAction=*Procede a bere una pozione al cui suo interno si trova uno strano liquido multicolore*
+selectLanguageTutorial.setLanguage=Grazie! Ora che ho bevuto questa posizione modificata di {0} che ho trovato ieri al negozio di pozioni magiche la "Cristalleria Fermentatrice" posso parlare con te nel linguaggio che preferisci!
+selectLanguageTutorial.instructions=Puoi sempre cambiare le preferenze della tua lingua scrivendo /selectLanguageTutorial nella chat.
+selectLanguageTutorial.english=Inglese
+selectLanguageTutorial.italian=Italiano
 spell.speakWithAnimals=Parlare con animali
+button.showMeTutorial=Mostrami cosa puoi fare!
+help.notShownYet=Sembra tu non abbia ancora visto cosa posso fare! Per avere una lista completa delle mie abilità, scrivi /help nella chat in qualsiasi momento!
+help.buttonBelow=Alternativamente, puoi premere il bottone qui sotto.

src/main/resources/i18n/message_it_IT.properties

@@ -1,6 +1,11 @@
 start.helloFirstName=Ciao {0}! \ud83d\udc4b
 start.description=Questo è {0}, un semplice bot che ci concenta sulla gestione di contenuto per DnD! Per favore comincia selezionando la lingua qui sotto \ud83d\udc47
-changeLanguage.drinkAction=*Procede a bere una pozione al cui suo interno si trova uno strano liquido multicolore*
-changeLanguage.setLanguage=Grazie! Ora che ho bevuto quest posizione modificata di {0} che ho trovato ieri al negozio di pozioni magiche la "Cristalleria Fermentatrice" posso parlare con te nel linguaggio che preferisci!
-changeLanguage.instructions=Puoi sempre cambiare le preferenze della tua lingua scrivendo /changeLanguage nella chat.
+selectLanguageTutorial.drinkAction=*Procede a bere una pozione al cui suo interno si trova uno strano liquido multicolore*
+selectLanguageTutorial.setLanguage=Grazie! Ora che ho bevuto questa posizione modificata di {0} che ho trovato ieri al negozio di pozioni magiche la "Cristalleria Fermentatrice" posso parlare con te nel linguaggio che preferisci!
+selectLanguageTutorial.instructions=Puoi sempre cambiare le preferenze della tua lingua scrivendo /selectLanguageTutorial nella chat.
+selectLanguageTutorial.english=Inglese
+selectLanguageTutorial.italian=Italiano
 spell.speakWithAnimals=Parlare con animali
+button.showMeTutorial=Mostrami cosa puoi fare!
+help.notShownYet=Sembra tu non abbia ancora visto cosa posso fare! Per avere una lista completa delle mie abilità, scrivi /help nella chat in qualsiasi momento!
+help.buttonBelow=Alternativamente, puoi premere il bottone qui sotto.

src/main/resources/template/callbackQuery/changeLanguage.vm

@@ -1,5 +0,0 @@
-_${i18n.changeLanguage.drinkAction}_
-
-${i18n.changeLanguage.setLanguage.insert(${i18n.spell.speakWithAnimals})}
-
-${i18n.changeLanguage.instructions}

src/main/resources/template/callbackQuery/selectLanguageTutorial.vm

@@ -0,0 +1,9 @@
+_${i18n.selectLanguageTutorial.drinkAction}_
+
+${i18n.selectLanguageTutorial.setLanguage.insert(${i18n.spell.speakWithAnimals})}
+
+${i18n.selectLanguageTutorial.instructions}
+
+#if(${hasHelpBeenShown} == false)
+${i18n.help.notShownYet} ${i18n.help.buttonBelow}
+#end

src/test/java/com/github/polpetta/mezzotre/orm/model/TgChatIntegrationTest.java

@@ -54,7 +54,7 @@ class TgChatIntegrationTest {
             .withPreviousMessageUnixTimestampInSeconds(42)
             .build();
 
-    final TgChat user = new TgChat(1234L, chatContext, "en");
+    final TgChat user = new TgChat(1234L, chatContext, "en", false);
 
     user.save();
     final String query = "select * from telegram_chat where id = ?";
@@ -63,6 +63,7 @@ class TgChatIntegrationTest {
     assertNotNull(savedChat);
     assertEquals(1234L, savedChat.getLong("id"));
     assertEquals("en", savedChat.getString("locale"));
+    assertFalse(savedChat.getBoolean("has_help_been_shown"));
     assertNotNull(savedChat.get("chat_context"));
     assertEquals("jsonb", ((PGobject) savedChat.get("chat_context")).getType());
     assertEquals(
@@ -82,13 +83,14 @@ class TgChatIntegrationTest {
             .withPreviousMessageUnixTimestampInSeconds(42)
             .build();
 
-    final String insertQuery = "insert into telegram_chat values (?, ?::jsonb, ?, ?, ?)";
+    final String insertQuery = "insert into telegram_chat values (?, ?::jsonb, ?, ?, ?, ?)";
     final int affectedRows =
         database
             .sqlUpdate(insertQuery)
             .setParameter(1234L)
             .setParameter(objectMapper.writeValueAsString(chatContext))
             .setParameter("en-US")
+            .setParameter(false)
             .setParameter(timestampFromUnixEpoch)
             .setParameter(timestampFromUnixEpoch)
             .execute();
@@ -97,6 +99,7 @@ class TgChatIntegrationTest {
 
     final TgChat got = new QTgChat().id.eq(1234L).findOne();
     assertNotNull(got);
+    assertFalse(got.getHasHelpBeenShown());
     final ChatContext gotChatContext = got.getChatContext();
     assertNotNull(gotChatContext);
     assertEquals("/start", gotChatContext.getStage());

src/test/java/com/github/polpetta/mezzotre/telegram/callbackquery/ChangeLanguageIntegrationTest.java

@@ -1,148 +0,0 @@
-package com.github.polpetta.mezzotre.telegram.callbackquery;
-
-import static org.junit.jupiter.api.Assertions.*;
-
-import com.github.polpetta.mezzotre.helper.Loader;
-import com.github.polpetta.mezzotre.helper.TestConfig;
-import com.github.polpetta.mezzotre.i18n.LocalizedMessageFactory;
-import com.github.polpetta.mezzotre.orm.model.CallbackQueryContext;
-import com.github.polpetta.mezzotre.orm.model.TgChat;
-import com.github.polpetta.mezzotre.orm.model.query.QCallbackQueryContext;
-import com.github.polpetta.mezzotre.orm.model.query.QTgChat;
-import com.github.polpetta.types.json.CallbackQueryMetadata;
-import com.github.polpetta.types.json.ChatContext;
-import com.google.gson.Gson;
-import com.pengrad.telegrambot.model.Update;
-import com.pengrad.telegrambot.request.BaseRequest;
-import com.pengrad.telegrambot.request.SendMessage;
-import io.ebean.Database;
-import java.util.Optional;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.Executors;
-import java.util.concurrent.TimeUnit;
-import java.util.stream.Stream;
-import org.junit.jupiter.api.*;
-import org.junit.jupiter.params.ParameterizedTest;
-import org.junit.jupiter.params.provider.Arguments;
-import org.junit.jupiter.params.provider.MethodSource;
-import org.slf4j.LoggerFactory;
-import org.testcontainers.containers.PostgreSQLContainer;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
-
-@Tag("slow")
-@Tag("database")
-@Tag("velocity")
-@Testcontainers
-class ChangeLanguageIntegrationTest {
-
-  private static Gson gson;
-
-  @Container
-  private final PostgreSQLContainer<?> postgresServer =
-      new PostgreSQLContainer<>(TestConfig.POSTGRES_DOCKER_IMAGE);
-
-  private Database database;
-  private ChangeLanguage changeLanguage;
-
-  @BeforeAll
-  static void beforeAll() {
-    gson = new Gson();
-  }
-
-  @BeforeEach
-  void setUp() throws Exception {
-    database =
-        Loader.connectToDatabase(Loader.loadDefaultEbeanConfigWithPostgresSettings(postgresServer));
-
-    changeLanguage =
-        new ChangeLanguage(
-            Executors.newSingleThreadExecutor(),
-            new LocalizedMessageFactory(Loader.defaultVelocityEngine()),
-            LoggerFactory.getLogger(ChangeLanguage.class));
-  }
-
-  private static Stream<Arguments> getTestLocales() {
-    return Stream.of(
-        Arguments.of(
-            ChangeLanguage.Language.Italian,
-            "_*Procede a bere una pozione al cui suo interno si trova uno strano liquido"
-                + " multicolore*_\n"
-                + "\n"
-                + "Grazie! Ora che ho bevuto quest posizione modificata di Parlare con animali che"
-                + " ho trovato ieri al negozio di pozioni magiche la \"Cristalleria Fermentatrice\""
-                + " posso parlare con te nel linguaggio che preferisci!\n"
-                + "\n"
-                + "Puoi sempre cambiare le preferenze della tua lingua scrivendo /changeLanguage"
-                + " nella chat.",
-            "en-US"),
-        Arguments.of(
-            ChangeLanguage.Language.English,
-            "_*Proceeds to drink a potion with a strange, multicolor liquid*_\n"
-                + "\n"
-                + "Thanks! Now that I drank this modified potion of Speak with animals that I've"
-                + " found at the \"Crystal Fermentary\" magic potion shop yesterday I can speak"
-                + " with you in the language you prefer!\n"
-                + "\n"
-                + "You can always change your language settings by typing /changeLanguage in the"
-                + " chat.",
-            "it-IT"));
-  }
-
-  @ParameterizedTest
-  @Timeout(value = 1, unit = TimeUnit.MINUTES)
-  @MethodSource("getTestLocales")
-  void shouldProcessChangeLanguageToDesiredOne(
-      ChangeLanguage.Language language, String expectedResult, String startingLocale)
-      throws Exception {
-
-    final Update update =
-        gson.fromJson(
-            "{\n"
-                + "\"update_id\":10000,\n"
-                + "\"callback_query\":{\n"
-                + "  \"id\": \"4382bfdwdsb323b2d9\",\n"
-                + "  \"from\":{\n"
-                + "     \"last_name\":\"Test Lastname\",\n"
-                + "     \"type\": \"private\",\n"
-                + "     \"id\":1111111,\n"
-                + "     \"first_name\":\"Test Firstname\",\n"
-                + "     \"username\":\"Testusername\"\n"
-                + "  },\n"
-                + "  \"data\": \"Data from button callback\",\n"
-                + "  \"inline_message_id\": \"1234csdbsk4839\"\n"
-                + "}\n"
-                + "}",
-            Update.class);
-
-    final long tgChatId = 1111111L;
-    final ChatContext chatContext = new ChatContext();
-    final TgChat tgChat = new TgChat(tgChatId, chatContext, startingLocale);
-    tgChat.save();
-
-    final CallbackQueryMetadata callbackQueryMetadata =
-        new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
-            .withEvent("changeLanguage")
-            .withTelegramChatId(tgChatId)
-            .withAdditionalProperty(
-                ChangeLanguage.Field.NewLanguage.getName(), language.getLocale())
-            .build();
-    final String entryGroupId = "2e67774a-e4e4-4369-a414-a7f8bfe74b80";
-    final CallbackQueryContext changeLanguageCallbackQueryContext =
-        new CallbackQueryContext(
-            "c018108f-6612-4848-8fca-cf301460d4eb", entryGroupId, callbackQueryMetadata);
-    changeLanguageCallbackQueryContext.save();
-
-    final CompletableFuture<Optional<BaseRequest<?, ?>>> processFuture =
-        changeLanguage.process(changeLanguageCallbackQueryContext, update);
-    final Optional<BaseRequest<?, ?>> gotResponseOpt = processFuture.get();
-    final SendMessage gotMessage = (SendMessage) gotResponseOpt.get();
-    assertEquals(expectedResult, gotMessage.getParameters().get("text"));
-
-    final TgChat retrievedTgChat = new QTgChat().id.eq(tgChatId).findOne();
-    assertNotNull(retrievedTgChat);
-    assertEquals(language.getLocale(), retrievedTgChat.getLocale());
-
-    assertEquals(0, new QCallbackQueryContext().entryGroup.eq(entryGroupId).findCount());
-  }
-}

src/test/java/com/github/polpetta/mezzotre/telegram/callbackquery/SelectLanguageTutorialIntegrationTest.java

@@ -0,0 +1,338 @@
+package com.github.polpetta.mezzotre.telegram.callbackquery;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+import com.github.polpetta.mezzotre.helper.Loader;
+import com.github.polpetta.mezzotre.helper.TestConfig;
+import com.github.polpetta.mezzotre.i18n.LocalizedMessageFactory;
+import com.github.polpetta.mezzotre.orm.model.CallbackQueryContext;
+import com.github.polpetta.mezzotre.orm.model.TgChat;
+import com.github.polpetta.mezzotre.orm.model.query.QCallbackQueryContext;
+import com.github.polpetta.mezzotre.orm.model.query.QTgChat;
+import com.github.polpetta.mezzotre.util.UUIDGenerator;
+import com.github.polpetta.types.json.CallbackQueryMetadata;
+import com.github.polpetta.types.json.ChatContext;
+import com.google.gson.Gson;
+import com.pengrad.telegrambot.model.Update;
+import com.pengrad.telegrambot.model.request.InlineKeyboardButton;
+import com.pengrad.telegrambot.model.request.InlineKeyboardMarkup;
+import com.pengrad.telegrambot.request.BaseRequest;
+import com.pengrad.telegrambot.request.EditMessageText;
+import com.pengrad.telegrambot.request.SendMessage;
+import io.ebean.Database;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Stream;
+import org.junit.jupiter.api.*;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.slf4j.LoggerFactory;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+@Tag("slow")
+@Tag("database")
+@Tag("velocity")
+@Testcontainers
+class SelectLanguageTutorialIntegrationTest {
+
+  private static Gson gson;
+
+  @Container
+  private final PostgreSQLContainer<?> postgresServer =
+      new PostgreSQLContainer<>(TestConfig.POSTGRES_DOCKER_IMAGE);
+
+  private Database database;
+  private SelectLanguageTutorial selectLanguageTutorial;
+  private UUIDGenerator fakeUUIDGenerator;
+
+  @BeforeAll
+  static void beforeAll() {
+    gson = new Gson();
+  }
+
+  @BeforeEach
+  void setUp() throws Exception {
+    database =
+        Loader.connectToDatabase(Loader.loadDefaultEbeanConfigWithPostgresSettings(postgresServer));
+
+    fakeUUIDGenerator = mock(UUIDGenerator.class);
+
+    selectLanguageTutorial =
+        new SelectLanguageTutorial(
+            Executors.newSingleThreadExecutor(),
+            new LocalizedMessageFactory(Loader.defaultVelocityEngine()),
+            LoggerFactory.getLogger(SelectLanguageTutorial.class),
+            fakeUUIDGenerator);
+  }
+
+  private static Stream<Arguments> getTestLocales() {
+    return Stream.of(
+        Arguments.of(
+            SelectLanguageTutorial.Language.Italian,
+            "_*Procede a bere una pozione al cui suo interno si trova uno strano liquido"
+                + " multicolore*_\n"
+                + "\n"
+                + "Grazie! Ora che ho bevuto questa posizione modificata di Parlare con animali che"
+                + " ho trovato ieri al negozio di pozioni magiche la \"Cristalleria Fermentatrice\""
+                + " posso parlare con te nel linguaggio che preferisci!\n"
+                + "\n"
+                + "Puoi sempre cambiare le preferenze della tua lingua scrivendo"
+                + " /selectLanguageTutorial nella chat.\n"
+                + "\n"
+                + "Sembra tu non abbia ancora visto cosa posso fare! Per avere una lista completa"
+                + " delle mie abilità, scrivi /help nella chat in qualsiasi momento!"
+                + " Alternativamente, puoi premere il bottone qui sotto.\n",
+            "en-US",
+            "Mostrami cosa puoi fare!",
+            false),
+        Arguments.of(
+            SelectLanguageTutorial.Language.English,
+            "_*Proceeds to drink a potion with a strange, multicolor liquid*_\n"
+                + "\n"
+                + "Thanks! Now that I drank this modified potion of Speak with animals that I've"
+                + " found at the \"Crystal Fermentary\" magic potion shop yesterday I can speak"
+                + " with you in the language that you prefer!\n"
+                + "\n"
+                + "You can always change your language settings by typing /selectLanguageTutorial"
+                + " in the chat.\n"
+                + "\n"
+                + "It seems you haven't checked out what I can do yet! To have a complete list of"
+                + " my abilities, type /help in chat at any time! Alternatively, you can click the"
+                + " button down below.\n",
+            "it-IT",
+            "Show me what you can do!",
+            false),
+        Arguments.of(
+            SelectLanguageTutorial.Language.Italian,
+            "_*Procede a bere una pozione al cui suo interno si trova uno strano liquido"
+                + " multicolore*_\n"
+                + "\n"
+                + "Grazie! Ora che ho bevuto questa posizione modificata di Parlare con animali che"
+                + " ho trovato ieri al negozio di pozioni magiche la \"Cristalleria Fermentatrice\""
+                + " posso parlare con te nel linguaggio che preferisci!\n"
+                + "\n"
+                + "Puoi sempre cambiare le preferenze della tua lingua scrivendo"
+                + " /selectLanguageTutorial nella chat.\n\n",
+            "en-US",
+            "Mostrami cosa puoi fare!",
+            true),
+        Arguments.of(
+            SelectLanguageTutorial.Language.English,
+            "_*Proceeds to drink a potion with a strange, multicolor liquid*_\n"
+                + "\n"
+                + "Thanks! Now that I drank this modified potion of Speak with animals that I've"
+                + " found at the \"Crystal Fermentary\" magic potion shop yesterday I can speak"
+                + " with you in the language that you prefer!\n"
+                + "\n"
+                + "You can always change your language settings by typing /selectLanguageTutorial"
+                + " in the chat.\n\n",
+            "it-IT",
+            "Show me what you can do!",
+            true));
+  }
+
+  @ParameterizedTest
+  @Timeout(value = 1, unit = TimeUnit.MINUTES)
+  @MethodSource("getTestLocales")
+  void shouldProcessChangeLanguageToDesiredOneSendMessage(
+      SelectLanguageTutorial.Language language,
+      String expectedResult,
+      String startingLocale,
+      String buttonLocale,
+      boolean hasHelpBeenShown)
+      throws Exception {
+
+    when(fakeUUIDGenerator.generateAsString())
+        .thenReturn("e86e6fa1-fdd4-4120-b85d-a5482db2e8b5")
+        .thenReturn("16507fbd-9f28-48a8-9de1-3ea1c943af67");
+
+    final Update update =
+        gson.fromJson(
+            "{\n"
+                + "\"update_id\":10000,\n"
+                + "\"callback_query\":{\n"
+                + "  \"id\": \"4382bfdwdsb323b2d9\",\n"
+                + "  \"from\":{\n"
+                + "     \"last_name\":\"Test Lastname\",\n"
+                + "     \"type\": \"private\",\n"
+                + "     \"id\":1111111,\n"
+                + "     \"first_name\":\"Test Firstname\",\n"
+                + "     \"username\":\"Testusername\"\n"
+                + "  },\n"
+                + "  \"data\": \"Data from button callback\",\n"
+                + "  \"inline_message_id\": \"1234csdbsk4839\"\n"
+                + "}\n"
+                + "}",
+            Update.class);
+
+    final long tgChatId = 1111111L;
+    final ChatContext chatContext = new ChatContext();
+    final TgChat tgChat = new TgChat(tgChatId, chatContext, startingLocale, hasHelpBeenShown);
+    tgChat.save();
+
+    final CallbackQueryMetadata callbackQueryMetadata =
+        new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
+            .withEvent("selectLanguageTutorial")
+            .withTelegramChatId(tgChatId)
+            .withAdditionalProperty(
+                SelectLanguageTutorial.Field.NewLanguage.getName(), language.getLocale())
+            .build();
+    final String entryGroupId = "2e67774a-e4e4-4369-a414-a7f8bfe74b80";
+    final CallbackQueryContext changeLanguageCallbackQueryContext =
+        new CallbackQueryContext(
+            "c018108f-6612-4848-8fca-cf301460d4eb", entryGroupId, callbackQueryMetadata);
+    changeLanguageCallbackQueryContext.save();
+
+    final CompletableFuture<Optional<BaseRequest<?, ?>>> processFuture =
+        selectLanguageTutorial.process(changeLanguageCallbackQueryContext, update);
+    final Optional<BaseRequest<?, ?>> gotResponseOpt = processFuture.get();
+    final SendMessage gotMessage = (SendMessage) gotResponseOpt.get();
+    assertEquals(expectedResult, gotMessage.getParameters().get("text"));
+
+    final InlineKeyboardButton[][] replyMarkups =
+        ((InlineKeyboardMarkup)
+                gotMessage.getParameters().getOrDefault("reply_markup", new InlineKeyboardMarkup()))
+            .inlineKeyboard();
+    final List<InlineKeyboardButton> keyboardButtons =
+        Stream.of(replyMarkups).flatMap(Stream::of).toList();
+    if (!hasHelpBeenShown) {
+      assertEquals(1, keyboardButtons.size());
+      assertEquals(buttonLocale, keyboardButtons.get(0).text());
+
+      verify(fakeUUIDGenerator, times(2)).generateAsString();
+      assertEquals(
+          1, new QCallbackQueryContext().id.eq("e86e6fa1-fdd4-4120-b85d-a5482db2e8b5").findCount());
+    } else {
+      assertEquals(0, keyboardButtons.size());
+      assertEquals(0, new QCallbackQueryContext().findCount());
+    }
+
+    final TgChat retrievedTgChat = new QTgChat().id.eq(tgChatId).findOne();
+    assertNotNull(retrievedTgChat);
+    assertEquals(language.getLocale(), retrievedTgChat.getLocale());
+
+    assertEquals(0, new QCallbackQueryContext().entryGroup.eq(entryGroupId).findCount());
+  }
+
+  @ParameterizedTest
+  @Timeout(value = 1, unit = TimeUnit.MINUTES)
+  @MethodSource("getTestLocales")
+  void shouldProcessChangeLanguageToDesiredOneEditMessage(
+      SelectLanguageTutorial.Language language,
+      String expectedResult,
+      String startingLocale,
+      String buttonLocale,
+      boolean hasHelpBeenShown)
+      throws Exception {
+
+    when(fakeUUIDGenerator.generateAsString())
+        .thenReturn("e86e6fa1-fdd4-4120-b85d-a5482db2e8b5")
+        .thenReturn("16507fbd-9f28-48a8-9de1-3ea1c943af67");
+
+    final Update update =
+        gson.fromJson(
+            "{\n"
+                + "  \"update_id\": 10000,\n"
+                + "  \"callback_query\": {\n"
+                + "    \"id\": \"4382bfdwdsb323b2d9\",\n"
+                + "    \"from\": {\n"
+                + "      \"last_name\": \"Test Lastname\",\n"
+                + "      \"type\": \"private\",\n"
+                + "      \"id\": 1111111,\n"
+                + "      \"first_name\": \"Test Firstname\",\n"
+                + "      \"username\": \"Testusername\"\n"
+                + "    },\n"
+                + "    \"message\": {\n"
+                + "      \"message_id\": 2631,\n"
+                + "      \"from\": {\n"
+                + "        \"id\": 244745330,\n"
+                + "        \"is_bot\": true,\n"
+                + "        \"first_name\": \"test\",\n"
+                + "        \"username\": \"test\"\n"
+                + "      },\n"
+                + "      \"date\": 1680276288,\n"
+                + "      \"chat\": {\n"
+                + "        \"id\": 4772108,\n"
+                + "        \"type\": \"private\",\n"
+                + "        \"username\": \"userTest\",\n"
+                + "        \"first_name\": \"First Name\",\n"
+                + "        \"last_name\": \"Last Name\"\n"
+                + "      },\n"
+                + "      \"text\": \"Previous message content\",\n"
+                + "      \"reply_markup\": {\n"
+                + "        \"inline_keyboard\": [\n"
+                + "          [\n"
+                + "            {\n"
+                + "              \"text\": \"English\",\n"
+                + "              \"callback_data\": \"b345ea60-391a-40a4-96ac-8c36c4366498\"\n"
+                + "            },\n"
+                + "            {\n"
+                + "              \"text\": \"Italian\",\n"
+                + "              \"callback_data\": \"ab6487fa-b010-4eb6-a316-5b60f3b6bc1e\"\n"
+                + "            }\n"
+                + "          ]\n"
+                + "        ]\n"
+                + "      }\n"
+                + "    },\n"
+                + "    \"data\": \"Data from button callback\",\n"
+                + "    \"inline_message_id\": \"1234csdbsk4839\"\n"
+                + "  }\n"
+                + "}",
+            Update.class);
+
+    final long tgChatId = 1111111L;
+    final ChatContext chatContext = new ChatContext();
+    final TgChat tgChat = new TgChat(tgChatId, chatContext, startingLocale, hasHelpBeenShown);
+    tgChat.save();
+
+    final CallbackQueryMetadata callbackQueryMetadata =
+        new CallbackQueryMetadata.CallbackQueryMetadataBuilder()
+            .withEvent("selectLanguageTutorial")
+            .withTelegramChatId(tgChatId)
+            .withAdditionalProperty(
+                SelectLanguageTutorial.Field.NewLanguage.getName(), language.getLocale())
+            .build();
+    final String entryGroupId = "2e67774a-e4e4-4369-a414-a7f8bfe74b80";
+    final CallbackQueryContext changeLanguageCallbackQueryContext =
+        new CallbackQueryContext(
+            "c018108f-6612-4848-8fca-cf301460d4eb", entryGroupId, callbackQueryMetadata);
+    changeLanguageCallbackQueryContext.save();
+
+    final CompletableFuture<Optional<BaseRequest<?, ?>>> processFuture =
+        selectLanguageTutorial.process(changeLanguageCallbackQueryContext, update);
+    final Optional<BaseRequest<?, ?>> gotResponseOpt = processFuture.get();
+    final EditMessageText gotMessage = (EditMessageText) gotResponseOpt.get();
+    assertEquals(expectedResult, gotMessage.getParameters().get("text"));
+
+    final InlineKeyboardButton[][] replyMarkups =
+        ((InlineKeyboardMarkup)
+                gotMessage.getParameters().getOrDefault("reply_markup", new InlineKeyboardMarkup()))
+            .inlineKeyboard();
+    final List<InlineKeyboardButton> keyboardButtons =
+        Stream.of(replyMarkups).flatMap(Stream::of).toList();
+    if (!hasHelpBeenShown) {
+      assertEquals(1, keyboardButtons.size());
+      assertEquals(buttonLocale, keyboardButtons.get(0).text());
+
+      verify(fakeUUIDGenerator, times(2)).generateAsString();
+      assertEquals(
+          1, new QCallbackQueryContext().id.eq("e86e6fa1-fdd4-4120-b85d-a5482db2e8b5").findCount());
+    } else {
+      assertEquals(0, keyboardButtons.size());
+      assertEquals(0, new QCallbackQueryContext().findCount());
+    }
+
+    final TgChat retrievedTgChat = new QTgChat().id.eq(tgChatId).findOne();
+    assertNotNull(retrievedTgChat);
+    assertEquals(language.getLocale(), retrievedTgChat.getLocale());
+
+    assertEquals(0, new QCallbackQueryContext().entryGroup.eq(entryGroupId).findCount());
+  }
+}

src/test/java/com/github/polpetta/mezzotre/telegram/command/StartIntegrationTest.java

@@ -7,6 +7,7 @@ import com.github.polpetta.mezzotre.helper.Loader;
 import com.github.polpetta.mezzotre.helper.TestConfig;
 import com.github.polpetta.mezzotre.i18n.LocalizedMessageFactory;
 import com.github.polpetta.mezzotre.orm.model.TgChat;
+import com.github.polpetta.mezzotre.orm.model.query.QCallbackQueryContext;
 import com.github.polpetta.mezzotre.orm.model.query.QTgChat;
 import com.github.polpetta.mezzotre.util.Clock;
 import com.github.polpetta.mezzotre.util.UUIDGenerator;
@@ -149,7 +150,7 @@ class StartIntegrationTest {
         .thenReturn("16507fbd-9f28-48a8-9de1-3ea1c943af67")
         .thenReturn("0b0ac18e-f621-484e-aa8d-9b176be5b930");
 
-    final TgChat tgChat = new TgChat(1111111L, new ChatContext(), "en-US");
+    final TgChat tgChat = new TgChat(1111111L, new ChatContext(), "en-US", false);
 
     final Update update =
         gson.fromJson(
@@ -189,6 +190,15 @@ class StartIntegrationTest {
             + " choosing a language down below \uD83D\uDC47",
         message);
     assertEquals(1111111L, (Long) gotMessage.getParameters().get("chat_id"));
+
+    verify(fakeUUIDGenerator, times(3)).generateAsString();
+    assertEquals(
+        2,
+        new QCallbackQueryContext()
+            .entryGroup
+            .eq("e86e6fa1-fdd4-4120-b85d-a5482db2e8b5")
+            .findCount());
+    assertEquals(2, new QCallbackQueryContext().findCount());
   }
 
   @Test