miso_soup3 Blog

主に ASP.NET 関連について書いています。

Action types of Adaptive Cards (in Microsoft Bot Framework WebChat)

Microsoft Bot Framework

Microsoft Bot Framework の Adaptive Cards で行えるアクションの種類を調べました。

環境

  • Server side
    • C#, Microsoft.Bot.Builder 3.8.4.0
  • Channel
    • Bot Framework Channel Emulator 3.5.29
    • WebChat 0.11.0

他の Rich Card とアクションの種類が違う

Bot Framework では、メッセージや画像の他に、カードの表現でメッセージを送信できます。そのカードには、ここのドキュメント の「Types of rich cards」にあるように、AdaptiveCard を含め、AnimationCard、AudioCard といった8個の種類があります。このうちの1つの Adaptive Card は、Build 2017 で発表されたものです。それまで固定のレイアウトしかできなかったカードですが、Adaptive Card では、開発者がある程度自由にレイアウトできます。

カードで行えるアクションは Adaptive Card とその他のカードで種類が違うようです。

  • Adaptive Card カード以外で使えるアクションの種類（参照）
    • openUrl, imBack, postBack, call, playAudio, playVido, showImage, downloadFile, signin
  • Adaptive Card で使えるアクションの種類（参照 Action.*の項目）
    • OpenUrl, Submit, Http, ShowCard

例えば、Adaptive Card 内で「imBack」の処理（imBackは、ボタンを選択するとその値のメッセージをユーザーから Bot に送信します）を行いたい場合は、Adaptive Card のアクションの種類「Submit」を利用して、同じような挙動を実現します。

※Adaptive Card は発表されたばかりなので、今後種類が増えていく可能性はあります。

※Adaptive Card の性質を考えると、既存のカードの実装を置き換えてもよさそうですが、実際にどのような実装になっているかはわからず。代わりに次のような記述を見つけました。

The existing Bot Builder SDK card types (Hero, Thumbnail, Audio, Video, Animation, SignIn, Receipt) are now implemented as Adaptive Cards. BotFramework-WebChat/AdaptiveCards.md at master · Microsoft/BotFramework-WebChat

アクションボタンのレイアウト

Adaptive Card のアクションは、一つのカードに対して複数のアクションを設定する、という形のようです。ですので、次の図のようにボタンが下部に配置されます。文章やとある Column の中にボタンを置く、といった自由なレイアウトはできませんでした。

f:id:miso_soup3:20170730154302p:plain

Channel が WebChat の場合のアクション

Channel を WebChat に限定し、Adaptive Card で使えるアクションがどのようなものか調べました。 WebChat の場合は、「Http」のアクションはサポートしていません。その他 WebChat での Adaptive Card については下記にあります。

BotFramework-WebChat/AdaptiveCards.md at master · Microsoft/BotFramework-WebChat

実装方法の調べ方としては、上のサイトに加え、Adaptive Card のスキーマの定義をみつつ（Adaptive Cards）、Adaptive Card の C# のサンプルをみる（BotBuilder-Samples/CSharp/cards-AdaptiveCards at master · Microsoft/BotBuilder-Samples）、が良さそうです。

OpenUrl

OpenUrl は、ボタンを選択するとブラウザでそのURLにアクセスします。

f:id:miso_soup3:20170730154315p:plain

コード

ShowCard

ShowCard は、ボタンを選択すると、別の Adaptive Card を表示します。

コード

f:id:miso_soup3:20170730154326p:plain

「コメント」をタップすると、下のように別の Adaptive Card が表示されます。

f:id:miso_soup3:20170730154341p:plain

こちらにもサンプルがあります。 ActivityUpdate | Adaptive Cards

Submit

Submit は、ボタンを選択すると、input 要素に入力された値を送信します。

f:id:miso_soup3:20170730154353p:plain

コード

こちらと同じサンプルです：InputForm | Adaptive Cards

入力された値を受け取るには、context.Wait(...) などでユーザーの IMessageActivity を受け取り、そのプロパティのValueから値を取得します。下記はそのサンプルです。

private async Task SelectedCardAsync(IDialogContext context, IAwaitable<string> result)
{
    //Adaptive Cardを送信する
    await context.PostAsync(AdaptiveCardGenerator.CreateAdaptiveCard(context, AdaptiveCardGenerator.CreateShowCard()));
    context.Wait(FormReceivedAsync);
}

/// <summary>
/// 入力フォームを受け取った後
/// </summary>
/// <param name="context"></param>
/// <param name="result"></param>
/// <returns></returns>
private async Task FormReceivedAsync(IDialogContext context, IAwaitable<IMessageActivity> result)
{
    var message = await result;

    if (message.Value != null)
    {
        dynamic value = message.Value;
        await context.PostAsync($"received: myName:{value.myName}, myEmail:{value.myEmail}, myTel:{value.myTel}. ");
    }

    //...

先の方で「imBack」のような挙動は Adapptive Card では「Submit」で代わりに実装する、と書きました。「Submit」では、input要素以外に任意のキーと値のペアを送信できるので（該当の場所のコード）、その値でユーザーの選択したボタンを区別し、分岐することにより「imBack」のような挙動を真似できます。

この Submit で注意したいことですが、私の環境の Bot Framework Channel Emulator 3.5.29 では入力値を受け取ることができませんでした（Value プロパティが null。値の送信もしてない様子）。しかし、ブラウザ上からの WebChat と、Bot Framework のポータルサイトの Test では、正常な動作を確認しました。下記のサイトでは、Mac では動いたけど Windows では動かない、といった記述があります。Emulator のバージョンの確認や再インストールで動いたとありますが、私の環境ではそれでもできませんでした。Adaptive card not working on Emulator · Issue #244 · Microsoft/BotFramework-Emulator