(Kotlin) インタラクティブ UI をメッセージに追加する方法

前提条件

次のように仮定します。

• 「リマインダー」ボットのソースコード(英語)があります。

• チャットボットの作成方法チュートリアルを完了しました。具体的には、環境をセットアップする手順を完了しました。

  • ステップ 3. トンネリングサービスを実行する

  • ステップ 4. Space にチャットボットを登録する

何をしたらいいでしょう

このチュートリアルでは、(Kotlin) チャットボットの作成方法チュートリアルで作成した「リマインダー」ボットの機能を拡張します。具体的には、ボットメッセージの 1 つに UI 要素を追加します。ユーザーが正確な時刻を指定せずに remind を送信すると、ボットは事前定義された時刻が記載された 3 つのボタンを含むメッセージをユーザーに送信します。

このチュートリアルを段階的に進めるのではなく、結果のコードだけを見たい場合でも、まったく課題ありません。これがソースコード(英語)です。

ステップ 1. インタラクティブボタンを含むメッセージを作成する

(Kotlin) チャットボットの作成方法チュートリアルで覚えているかもしれませんが、Space SDK はチャットメッセージを作成するための別の DSL を提供します。それをメッセージビルダーと呼んでいます。以前は、メッセージに派手な外観を追加するためだけにこれを使用していました。次に、これを使用して、クリック可能なボタンを含むメッセージを作成してみましょう。

現在、メッセージ内の対話的な要素はボタンのみです。button には action が割り当てられている必要があります。ユーザーがボタンをクリックすると、Space は特殊な MessageActionPayload 型のペイロードを送信します。このようなペイロードには、チャットボットで解析できるアクション ID とアクション引数が含まれています。

MessageControlGroupBuilder、MessageFieldBuilder、MessageSectionBuilder : これらは、メッセージビルダー DSL を拡張できるクラスです。button は制御グループ要素に属します。そこで、独自のカスタムボタン関数を使用して MessageControlGroupBuilder クラスを拡張します。

3 つのボタンを使用して 3 つのリマインダー時間間隔をユーザーに提案する新しいメッセージタイプを作成してみましょう。

1. CommandRemind.kt ファイルを開き、次のコードを追加します。

   private fun MessageControlGroupBuilder.remindButton(delayMs: Long, reminderText: String) { val text = "${delayMs / 1000} seconds" val style = MessageButtonStyle.PRIMARY val action = PostMessageAction("remind", "$delayMs $reminderText") button(text, action, style) }

   ここでは、カスタムスタイルとテキストを使用してボタンを事前定義します。ここで最も重要な変数は action です。これは、remind アクション ID、タイマー遅延値、リマインダーテキストを含む PostMessageAction のインスタンスを返します。

   このようなボタンは次のようになります。

   

2. 次に、remindButton を含むメッセージを作成しましょう。例: メッセージに 3 つのボタンを追加してみましょう。それぞれに一定の遅延時間がかかります。

   次のコードを CommandRemind.kt に追加します。

   private fun suggestRemindMessage(reminderText: String): ChatMessage { return message { section { text("Remind me in ...") controls { // buttons for 5, 60, and 300 seconds remindButton(5 * 1000, reminderText) remindButton(60 * 1000, reminderText) remindButton(300 * 1000, reminderText) } } } }

   最終的なメッセージは次のようになります。

   

3. 次に、新しく作成した suggestRemindMessage() をユーザーにいつ表示するかを決めましょう。最も明白な決定は、ユーザーが remind コマンドとリマインダーテキストを送信したが、時間間隔を指定しなかった場合にそれを表示することです。

   CommandRemind.kt で runRemindCommand() 関数を見つけて、以下のように更新します。

   suspend fun runRemindCommand(payload: MessagePayload) { val remindMeArgs = getArgs(payload) when { remindMeArgs == null -> { sendMessage(payload.userId, helpMessage()) } remindMeArgs.delayMs == null && remindMeArgs.reminderText.isNotEmpty() -> { sendMessage(payload.userId, suggestRemindMessage(remindMeArgs.reminderText)) } remindMeArgs.delayMs == null -> { sendMessage(payload.userId, helpMessage()) } else -> { remindAfterDelay(payload.userId, remindMeArgs.delayMs, remindMeArgs.reminderText) } } }

4. 終わり ! これで、ユーザーが時間間隔なしで remind を送信したときにユーザーに返されるボタン付きのメッセージが完成しました。しかし、ユーザーが実際にいずれかのボタンをクリックすると何が起こるでしょうか ?

ステップ 2. MessageActionPayload を処理する

ユーザーがボタンをクリックすると、Space は MessageActionPayload ペイロードをボットに送信します。ペイロードには、ボタンとアクション引数で指定されたアクションの ID が含まれます。私たちのタスクはペイロードを処理することです。

1. まず、runRemindCommand(payload: MessagePayload) 関数のオーバーロードを作成しましょう。既存のものは MessagePayload を受け入れますが、MessageActionPayload も受け入れる必要があります。

   CommandRemind.kt を開いてコードを追加します。

   suspend fun runRemindCommand(payload: MessageActionPayload) { val remindMeArgs = getArgs(payload) ?: return val delayMs = remindMeArgs.delayMs ?: return val reminderText = remindMeArgs.reminderText remindAfterDelay(payload.userId, delayMs, reminderText) } // overload of getArgs that accepts MessageActionPayload private fun getArgs(payload: MessageActionPayload): RemindMeArgs? { val args = payload.actionValue val delayMs = args.substringBefore(" ").toLongOrNull() ?: return null val reminderText = args.substringAfter(" ").trimStart().takeIf { it.isNotEmpty() } ?: return null return RemindMeArgs(delayMs, reminderText) }

   ここでは、payload.actionValue を使用してペイロードからアクション引数を取得し、この引数を使用してタイマーを実行します。

2. 次に、チャットボットのエンドポイントに MessageActionPayload を処理するように教えてみましょう。

   Routes.kt ファイルを開き、Application.configureRouting() 関数を更新します。

   fun Application.configureRouting() { routing { post("api/space") { // read request body val body = call.receiveText() // verify if the request comes from a trusted Space instance val signature = call.request.header("X-Space-Public-Key-Signature") val timestamp = call.request.header("X-Space-Timestamp")?.toLongOrNull() // verifyWithPublicKey gets a key from Space, uses it to generate message hash // and compares the generated hash to the hash in a message if (signature.isNullOrBlank() || timestamp == null || !spaceClient.verifyWithPublicKey(body, timestamp, signature) ) { call.respond(HttpStatusCode.Unauthorized) return@post } when (val payload = readPayload(body)) { is ListCommandsPayload -> { // Space requests the list of supported commands call.respondText( ObjectMapper().writeValueAsString(getSupportedCommands()), ContentType.Application.Json ) } is MessagePayload -> { // user sent a message to the application val command = supportedCommands.find { it.name == payload.command() } if (command == null) { runHelpCommand(payload) } else { launch { command.run(payload) } } call.respond(HttpStatusCode.OK, "") } is MessageActionPayload -> { when (payload.actionId) { "remind" -> { launch { runRemindCommand(payload) } } else -> error("Unknown command ${payload.actionId}") } // After sending a command, Space will wait for HTTP OK confirmation call.respond(HttpStatusCode.OK, "") } } } } }

   ここでは、actionId をチェックする is MessageActionPayload 条件を追加し、remind の場合は、追加したばかりの runRemindCommand オーバーロードを実行します。

3. ニース ! 仕組みをチェックしてみましょう !

ステップ 3. ボットを実行する

1. Application.kt の main 関数の横にあるガターの Run をクリックして、アプリケーションを起動します。

   

2. Space インスタンスを開いてボットを見つけます。Ctrl+K を押してその名前を入力します。

   

3. remind メッセージを送信します。

4. 応答で、5 秒ボタンをクリックします。