MicrosoftのDirect Line API × jQueryでWebブラウザで動くボットを作る

おはようございます、岡田です。

今回は、みなさん馴染み深いjQueryを使って、Webブラウザ上でBotと対話をしてみます！

非常に多くのチャンネルでBotを作成できるMicrosoft Bot Framework。実はBotをREST APIとして扱う事ができる仕組みが用意されています。それが「Direct Line API」です。

Direct Line APIとjQueryを組み合わせれば、WebブラウザでBotと会話できる事はもちろん、Botに柔軟なUIを与えてあげる事ができそう。

REST APIですので、HTTP通信さえできればプログラミング言語やデバイスを問わず、様々なシーンでBotを呼び出せるというメリットがあります。覚えといて損はありません。

記事の最後には、すぐに試せるデモとサンプルコードもありますので、参考にしてみてください。

前回のMS Bot Framework を使った記事はこちら
>> 意外に簡単。Microsoft Bot Frameworkを使ってWebページに自作Botを埋め込んでみた

Direct Line APIを使うための準備

それでは、さっそくDirect Line APIを使う準備をしましょう！

まずは、Microsoft Bot Frameworkの公式サイトにサインインして、「My Bots」を開きます。

次に、Direct Line APIを使用したいBotをクリックして、Botの管理画面に進みます。

Add another channelに、追加可能なチャンネルが表示されていますので、その中から、Direct LineのAddをクリックします。

次の画面で、「Generate Direct Line secret」のボタンをクリックし、Secretキーを発行します。

Secretキーが発行されますので、こちらをコピーして保管しておきましょう。

「I’m done configuring Direct Line」のボタンをクリックして、設定完了です！

Direct Line API の基本操作3つ

さて、これで準備が整いましたので、さっそくDirect Line APIを使っていきましょう。

Direct Line APIには基本となる3つの動作があります。

convertationIdを発行
Botにメッセージを送信
Botのメッセージを取得

以上3つの操作で、Botとの対話をしていきます。順に解説していきます。

conversationIdを発行する

Direct Line APIでBotと対話をするためには、conversationIdというものを発行する必要があります。

これは、Direct Line APIが、あなたとBotの会話ログを記録しておくためのIDで、このIDがないとBotと対話する事はできません。

なお、サーバにリクエストを送るのには、$.ajax()関数を使用します。

$.ajax({
  method: "POST",
  contentType: "application/json",
  headers: {
    Authorization: "Botconnector xkyR6XSfVQM.cwA.qUw.KBdFH5UtudREtKq4_pfF8EMzvxL592q7OH9ltpreOFY"
  },
  url: "https://directline.botframework.com/api/conversations",
  success: function(data){
    console.log(data);
  }
});

POSTメソッドで

https://directline.botframework.com/api/conversations

へリクエストを送る際、ヘッダーには認証のために

Authorization: “Botconnector YOUR_SECRET_KEY”

を指定します。

上記コードを実行すると、ブラウザのコンソールに以下のようなオブジェクトが返されます。

{
  conversationId: "2y7YRcZAx4f",
  token: "xkyR6XSfVQM.dAA.MgB5ADcAWQBSAGMAWgBBAHgANABmAA.O1R3HwvL0QE.-2L97p8XuRA.XpyptkBFriShOOg_ujewf9hD2kxi0rpwp-xClpwSIpI"
}

この中の「conversationId」は、Botとのメッセージとのやり取りをするために必要になってきます。

ちなみにこのIDは、30分たつと自動で消去されるようになっていますので、30分ごとに作成する必要があります。

Botにメッセージを送信する

さて、いよいよBotにメッセージを送信します。

function sendMessage (convId, msg) {

  var user = "user_" + convId; // from用のユーザー名を作成します

  $.ajax({
    method: "POST",
    contentType: "application/json",
    headers: {
      Authorization: "Botconnector xkyR6XSfVQM.cwA.qUw.KBdFH5UtudREtKq4_pfF8EMzvxL592q7OH9ltpreOFY"
    },
    url: 'https://directline.botframework.com/api/conversations/' + convId + '/messages',
    data: JSON.stringify({
    　　"text": msg, // 送信するメッセージ内容です
     "from": user // 同じユーザーからのメッセージであることを認識させるために、fromを入れます
    }),
    success: function (obj) {
    　　console.log("メッセージを送りました！");
    }
  });

}

sendMessage("2y7YRcZAx4f", "自己紹介して");

上記コードでは、conversationIdと送信するメッセージを引数にとるsendMessageという関数を作成しました。

先ほどと同様に、POSTメソッドでリクエストを送信します。

メッセージを送信するには、エンドポイントに

https://directline.botframework.com/api/conversations/{conversationId}/messages

を指定し、{ text: “送信するメッセージ”, from: “ユーザー名” }というデータを送ります。その他にも送信できるデータはありますが、詳しくは公式ドキュメントをご覧ください。

fromを指定する事で、「同じユーザーからのメッセージですよ」という事をBotに伝えることができます。逆に、fromの指定がないと、「違うユーザーからのメッセージだ」とBotが勘違いして、Botとの受け答えや会話が正しく成立しなくなってしまうので注意。

上記コードを実行して、メッセージ送信に成功すれば、「メッセージを送りました！」という文字がブラウザのコンソールに表示されるはずです。

Botのメッセージを受信する

さて、いよいよBotからのメッセージを取得します。

上記コードでは、conversationIdとwatermarkを引数にとる、getMessageという関数を作成しました。

Botからメッセージを取得するには、エンドポイントに

https://directline.botframework.com/api/conversations/{conversationId}/messages

を指定し、GETメソッドでリクエストを送信します。

今回は、認証用のヘッダーだけで大丈夫です。サンプルコードは下記の通りです。

function getMessage(convId, watermark) {

  var url;

  // ウォーターマークの有無により、URLの分岐
  if (watermark) {
    url = "https://directline.botframework.com/api/conversations/" + convId + "/messages?watermark=" + watermark;
  } else {
    url = "https://directline.botframework.com/api/conversations/" + convId + "/messages";
  }

  return $.ajax({
    method: "GET",
    contentType: "application/json",
    headers: {
      Authorization: "Botconnector xkyR6XSfVQM.cwA.qUw.KBdFH5UtudREtKq4_pfF8EMzvxL592q7OH9ltpreOFY"
    },
    url: url,
    success: function (data) {

      console.log(JSON.stringify(data));

    }
  });
}

getMessage("2y7YRcZAx4f");

上記コードを実行すると、下記のようなオブジェクトが返ってきます。

{
  messages: [{
      id: "2y7YRcZAx4f|131113209232385773",
      conversationId: "2y7YRcZAx4f",
      created: "2016-06-25T09:35:23.2385773Z",
      from: "user_2y7YRcZAx4f",
      text: "自己紹介して",
      images: [],
      attachments: [],
      eTag: "W/\"datetime'2016-06-25T09%3A35%3A24.2168782Z'\""
    },
    {
      id: "2y7YRcZAx4f|131113209266579021",
      conversationId: "2y7YRcZAx4f",
      created: "2016-06-25T09:35:26.2873792Z",
      from: "qavppytestbot",
      text: "こんにちは！ぼくの名前は、かぶっぴー。よろしくね(๑•̀ㅁ•́๑)✧",
      images: [],
      attachments: [],
      eTag: "W/\"datetime'2016-06-25T09%3A35%3A27.1026598Z'\""
    }]
  ,
  watermark: "131113209945100859"
}

あとは、このオブジェクトからメッセージを抜き出していけば、好きなUIを作成していく事ができます。

ちょっとオブジェクトの解説

オブジェクトの解説をしますと、messagesの中には、配列として、ユーザとBotのやり取りが入っています。
watermarkというのが、「メッセージをここまで取得しました」という印になっています。メッセージを取得するサンプルコードの中にも、

// ウォーターマークの有無により、URLの分岐
if (watermark) {
  url = "https://directline.botframework.com/api/conversations/" + convId + "/messages?watermark=" + watermark;
} else {
  url = "https://directline.botframework.com/api/conversations/" + convId + "/messages";
}

とあります。

このwatermarkをエンドポイントにつけて、リクエストをすると、そのwatermark以降のメッセージだけ取得できます。つまり、「新着メッセージ」だけを取得する事ができます。

デモ

今回の3つの機能を組み合わせた実際のデモを用意しました！ >> こちら
デモでは、一度convertationIdを作成したら、30分間クッキーに保存するという機能もつけています。

demo

ソースコードをGitHubでも公開していますので、ぜひ覗いてみてください！

さいごに

今回はDirect Line APIを使用してBotと対話する所までできました。

HTTP通信ができれば、jQueryだけでなくどんなプログラムからでも大丈夫ですので、ぜひお試しください。

次回は、Direct Line APIを使用して本格的なチャットUIを作成したいと思います。

それではー！