アクションボットのCall Connection
概要
アクションボットのCall Connectionsオプションは、会話中に事前に定義された外部APIを呼び出す機能を提供します。
APIを呼び出す際、ボットはAPIにパラメーターを送信し、またレスポンスでパラメーターを取得できます。
呼び出し接続を使用する理由
外部APIを使用することでアクションボットを複数のシステムと統合できるようになり、会話の構築にさまざまなオプションを提供します。
APIを使用して、外部APIに情報を送信する(ITチケットを開くなど)、外部APIから情報を受信する(チケット番号を取得するなど)、またはその両方を行うことができます。
Call Connectionの使用方法
ステップ1:接続を作成する
このセクションでは、アクションボットのエディタアカウントに新しい接続を追加する方法を説明します。 会話の中で接続を使用する方法は、次のステップで説明します。
- 「接続」セクションで、「新規接続の追加」をクリックします。
- [Add new deinstation(新しい接続先の追加)]を選択します。
3. ダイアログウィンドウで必要なすべてのパラメーターを定義し、[Create(作成)]をクリックします(これは構成手順であり、これらのパラメーターはAPI所有者が提供する必要があります)。
-
- Destination Name(接続先名)-
- プロセスでの接続をあとで確認するために、分かりやすい名前をつけます。
- お好きな名前を選んでください。
- Request type(リクエストタイプ)-
- GET/POST/DELETE/PUTのいずれかです。
- API所有者が提供する必要があります。
- Destination URL(接続先URL)-
- 正式なAPI URLである必要があります。
- API所有者が提供する必要があります。
- Destination URL(接続先URL)には、ダイナミッククエリパラメーターが含まれる場合があります。
- Destination URL(接続先URL)内にダイナミッククエリパラメーターを作成するには、文字列を括弧{ }で囲みます。
- 例:https://test.api/{production}/
- Destination URL(接続先URL)には、ユーザーによるダイナミックURLパラメーターとエンドユーザーレスポンスのマッピングや、環境変数(wm-data、cookie、jqueryなど)に対応したBbcodeの使用が可能なBbcode変数が含まれている場合があります。
- Authorization type(認証タイプ)- 現在、3種類の認証のみをサポートしています。
- No Authentication(認証なし)- 情報は必要ありません。
- Bearer Token(署名なしトークン)- 認証トークンが必要です。
- Basic Authentication(基本認証)- ユーザーとパスワードが必要です。
- 基本認証のパスワードにはコロンシンボルを含めることができないことに注意してください:
- Headers(ヘッダー)(オプション)- 一部のAPIはヘッダーを要求または許可します。
- すべての詳細が正しいことを確認するために、API接続をテストすることをお勧めします。
- Destination Name(接続先名)-
4. 新しい接続は、接続リストに追加する必要があります
ステップ2:会話中に「コール接続」アクションを追加します
このセクションでは、前のステップで定義した接続を会話中に使用する方法について説明します。
- 新しいアクションを追加します。
- アクションタイプ[Call Connection]を選択し、呼び出しの接続先を選択します。 呼び出し接続先は、前のステップで定義した接続の名前です。
- ダイナミッククエリパラメーター、BBcode変数、またはその両方でCall Connectionsを作成する際に、ユーザーはエンドユーザーレスポンスをダイナミック変数として接続先URLにマッピングできます。
- ダイナミッククエリパラメーターとBBcode変数は、その接続先がダイナミッククエリパラメーターまたはBBcode変数を含む場合、[Select Call Connection Destination(Call Connectionの接続先の選択)]入力の下に表示されます。
- リストされるダイナミッククエリパラメーターまたはBBcode変数は、ドロップダウンから[Conversation(会話)]のエレメントにマッピングできます。
3. 「Data the WalkMe Connection Call sends(WalkMeのConnection Callが送信するデータ)」を定義する(オプション)
会話中のパラメーターをAPI呼び出しに送信できます。 各行では、左側は送信する会話データを定義し、右側はAPIが受信すると想定されるパラメーターの名前を定義します。
以下の例では、APIは「base」という名前のパラメーターを取得することを想定しており、「base」の値が前の質問(この場合は「どの通貨ですか?」)に対するユーザーの回答となるように定義します。
[raw]をクリックすると、XMLまたはJSON形式のパラメーターの自由な編集が可能になります。
4. レスポンスデータマッピングを定義する(オプション)
一部のAPIはレスポンスを返します。レスポンスがXMLやJSON形式の場合は、そのレスポンスを使用して新しい変数に保存することができ、後に会話の中で使用できます。
レスポンスを新しい変数にマッピングする
ユーザーは好きなだけ変数を追加できます。 変数ごとに、以下を定義する必要があります。
- Name(名前)- 新しい変数の名前を選択します。
- 変数名に特殊文字を追加しないでください。例:ハイフン、ダッシュ、コロン、;、()、!*、- {} @
- Type(タイプ)- 新しい変数のタイプを定義します。 現在、String/Number/Boolean/Array(文字列、数値、ブーリアン、配列)の基本的なタイプのみをサポートしています。
- Path(パス)- 目的の情報につながるJSON/XMLレスポンスのパスを定義します。 ユーザーがパスを定義しやすくするために、[path constructor(パスコンストラクター)]ツールが追加されました。 それをクリックすると、エディターは接続先APIにpingを実行してサンプルレスポンスを受信します。ユーザーはサンプルレスポンスを確認することで簡単にパスを定義できるようになります。 APIでパラメーターの送信が必要な場合、パスコンストラクターはサンプルパラメーターの提供を要求します。
- Default value(デフォルト値)- レスポンスで定義されたパスが有効なデータにつながらない場合、この値が変数に保存されます。
- Error Value(エラー値)- API呼び出しが失敗した場合は、この値は変数に保存されます。
ステップ3:会話中にレスポンスデータ変数を使用する
レスポンスデータから新たな変数が作成された場合、以下のようなケースで「@」を使用することで、後に会話の中で使用することができます。
- メッセージ内 - メッセージテキストの一部としてユーザーに変数を表示します。
- 質問内 - 質問文の一部としてユーザーに変数を表示します。
- 選択式の質問内 - ユーザーに表示される提案の一部として変数を表示します。 配列型の変数については、配列の各フィールドが別個の提案として表示されます。 配列に、各アイテムの単一属性ではなく、オブジェクトが含まれている場合、ユーザーに表示する属性と保存する属性を定義できます。
- 条件内 - 条件作成の際、変数を条件のベースとして使用できます。
- WMコンテンツ内(SWTなど)- WalkMeコンテンツを(アクションを介して)再生する場合、変数をコンテンツが必要とするデータに使用できます。
Tip Tuesday動画