アプリケーションによって開始される会話は、外部アプリケーションからスキルまたはそれが属するデジタル・アシスタントにイベントが送信されると開始されます。会話が適切な場所で開始し、目的の値を表示するように、スキルに加える必要がある変更がいくつかあります。

外部アプリケーションから送信されるイベントには、スキルに対するイベントを一意に識別するペイロード・タイプが含まれる必要があります。通常、ペイロード・タイプは、msgReminderやcancelAppointmentなど、スキルの実行目的を示します。また、イベントには、患者の名前やアポイントメント時間など、variables JSONオブジェクトのパラメータを含めることができます。

スキルでは、すべてのイベントに対してダイアログ・フローに開始状態があることを確認する必要があります(複数のイベントが同じ開始状態になることがあります)。また、フロー・レベルの変数を追加して、パラメータ値(存在する場合)を保持する必要があります。次に、イベントのペイロード・タイプを開始状態にマップする必要があります。

各イベントについて、次のステップを実行します:

1. 外部アプリケーションがイベントのメッセージ・ペイロードにvariablesオブジェクトを渡す場合は、オブジェクトのプロパティの値を保持するフロー・レベル変数を追加します。

   フロー・レベルの変数名は、variablesオブジェクト内のプロパティ名と一致している必要があります。たとえば、外部アプリケーションがアポイントメント・リマインダ・イベントについて次のようなリクエスト本文を送信するとします:

   {
       "userId": "16035550100",
       "messagePayload": {
           "type": "application",
           "payloadType": "msgReminder",
           "channelName": "AppointmentUserChannel",
           "variables": {
           	"patientName": "Joe Doe",
           	"appointmentTime": "5:00 pm"
           }
       }
   }

2. ダイアログ・フローにイベントの開始状態があることを確認します。

   ヒント:

   メッセージング・プラットフォームがテキストのみの場合、スキルのダイアログ・フローで自動採番を構成することで、ユーザー入力のエラーを少なくすることを検討してください。また、メッセージング・プラットフォームに基づいてテキストを表示するか非表示にすることも検討してください。テキストのみのチャネルを参照してください。

3. イベントを開始状態にマップするには、「設定」をクリックし、「イベント」をクリックして、「+マッピングの追加」をクリックします。その後、次のフィールドを入力します:

   • ペイロード・タイプ: イベントを一意に識別する名前。外部アプリケーションは、この名前を使用してメッセージを適切な状態に移行します。

     ペイロード・タイプは定数であるため、実際の状態名ではなく外部アプリケーションからのペイロード・タイプを使用しますが、状態の名前は、ダイアログ・フローが修正されると変更される可能性があります。

   • 状態名: ダイアログ・フローにおけるイベントの開始状態。

   このスクリーンショットでは、msgReminderペイロード・タイプがダイアログ・フローのremindermessage状態にマップされています。

   
   
   図イベントの説明-map.png
   

   スキルをデジタル・アシスタントに追加すると、スキルのイベントから状態へのマッピングがデジタル・アシスタントの「イベント」ページに自動的に追加されます。このページには、デジタル・アシスタントの「設定」ページからアクセスします。

スキルでユーザーがOracle Identity Cloud ServiceまたはOracle Access Managerで認証する必要がある場合は、アプリケーション・チャネル、スキルおよび外部アプリケーションを構成して、スキルが認証済ユーザーIDをボットのユーザーIDに関連付けることができるようにする必要があります。

ユーザー認証済スキルに送信されたイベントが機能するには、ユーザーがスキルからアイデンティティ・プロバイダにすでにサインインしている必要があります。たとえば、Devaがスキルを使用して経費レポートを作成したとします。彼女は、スキル内でなんらかの作業をする前に、サインインすることを求められます。次に、認証済ユーザーIDが、メッセージング・プラットフォームのユーザーIDおよびユーザーのプロファイルにキャッシュされたメッセージング・プラットフォーム・パラメータと関連付けられます。

彼女は、レポートの完了後、経費が承認されたときに通知するよう依頼します。会社は、外部アプリケーションを使用して通知イベントを同じスキルに送信します。アプリケーションがユーザー認証済スキルにイベントを送信するには、メッセージング・プラットフォームのユーザーIDではなく、Devaの認証済ユーザーIDを送信する必要があります。認証済ユーザーIDが提供されると、スキルでは、プラットフォームのユーザーIDと、Devaが最初にサインインしたときに取得されたキャッシュ済プロファイルの情報を検索できます。

Devaがスキルからサインインしなかった場合、認証が期限切れの場合、またはプロファイル・キャッシュが期限切れの場合、デジタル・アシスタントは500エラー付きでイベント・リクエストに応答します。

スキルの構成のステップに加え、次のステップを完了して、ユーザー認証済スキルのアプリケーションによって開始される会話を構成する必要があります:

1. スキルですでにユーザー認証が有効になっている場合は、「設定」→「認証サービス」に移動してサービスをオープンし、「リフレッシュ・トークンの保持期間」が、ユーザー・プロファイル・キャッシュの有効期限に一致する14日間に設定されていることを確認します。これらの値は同期している必要があります。

2. スキルでまだユーザー認証が有効にされていない場合は、次のステップを実行します:

   1. 管理者がアイデンティティ・プロバイダ登録のステップを完了していることを確認します。

   2. 認証サービスの説明に従って、アイデンティティ・プロバイダの認証サービスを作成します。

   3. 認証サービスの「リフレッシュ・トークンの保持期間」が、ユーザー・プロファイル・キャッシュの有効期限に一致する14日間に設定されていることを確認します。これらの値は同期している必要があります。

   4. ユーザーがスキルからサインインできるようにするには、OAuth 2.0アカウント・リンクの説明に従って、OAuth 2.0アカウント・リンク・コンポーネントの状態をダイアログ・フローに追加します。

3. アプリケーション・チャネルを作成する場合、「認証済ユーザーIDを使用」を「オン」に切り替えます。または、すでに作成されている場合は、チャネルをオープンして「オン」に切り替えます。

外部アプリケーションがデジタル・アシスタントに送信するリクエスト本文で、userIdプロパティを、外部アプリケーションの構成の説明に従って必ず認証済ユーザーIDに設定してください。

アプリケーションによって開始される会話を機能させるには、ユーザー・チャネルを作成して、スキルをメッセージング・プラットフォーム・アカウントにリンクする必要があります。特定のプラットフォーム用のユーザー・チャネルを作成するステップは、次のトピックを参照してください。

• Twilio/SMS
• Slack
• Microsoft Teams

チャネルの「ルート先」リストからスキルを選択した場合、このチャネルに送信されるすべての外部アプリケーション・メッセージが、選択したスキルにルーティングされます。ただし、デジタル・アシスタントを選択した場合は、外部アプリケーションのメッセージ・ペイロードでターゲット・スキルを指定する必要があります。

外部アプリケーションからデジタル・アシスタントにメッセージを送信できるようにするには、アプリケーション・チャネルを作成する必要があります。チャネルの作成後、デジタル・アシスタントは秘密キーを割り当てます。外部アプリケーションではこの秘密キーを使用する必要があります。

1. 左側のナビゲーション・バーから「チャネル」をクリックし、「アプリケーション」をクリックして、「+アプリケーション構成」をクリックします。

2. 名前を入力し、オプションで説明を入力します。

3. (オプション)チャネル関連のすべてのエラー・メッセージがサーバー・ログ・ファイルに記録されます。デジタル・アシスタントから外部Webサービスにもこれらのエラー・メッセージが送信されるようにする場合は、「アウトバウンド・アプリケーションURL」フィールドにWebサービスのURLを入力します。

   ユーザー・チャネルを介した会話の開始に関する問題など、エラーが発生した場合、デジタル・アシスタントは、botId、sessionIdおよびmessageプロパティを持つJSONオブジェクトとしてエラー・メッセージを送信します。

4. (オプション)ターゲット・スキルでOAuth 2.0アカウント・リンク・コンポーネントを使用した認証が必要で、外部アプリケーションがメッセージング・プラットフォームのユーザーIDではなく認証済ユーザーIDを送信する場合は、「認証済ユーザーIDを使用」を「オン」に切り替えます。

   これがオンに切り替えられると、デジタル・アシスタントは、指定された認証済ユーザーIDに対してメッセージング・プラットフォームのユーザーIDを検索します。検索が正常に完了するには、ユーザーがスキルを通じてサインインしている必要があります。詳細は、ユーザー認証済スキルの構成を参照してください。

5. 「作成」をクリックします。

6. 「アプリケーション有効」を「オン」に切り替えます。

7. 秘密キーとインバウンドURLをノートにとります。これらは外部アプリケーションによって使用されます。

   • インバウンドURLにPOSTリクエストを送信することによってメッセージを送信します。
   • 秘密キーを使用してPOSTリクエストを認証します。

アプリケーションによって開始される会話がスキルでサポートされ、それをデジタル・アシスタントに追加する場合、デジタル・アシスタントの「設定」ページで次の構成パラメータを調整できます:

• 割込みプロンプト: このプロンプトは、フローを中断して新しいフローを開始するときに表示されます。
• ポストバック・アクションでの自動採番の有効化: ユーザー入力のエラーを少なくするため、すべてのテキストのみのチャネルでこの設定がtrueであることを確認することをお薦めします。デフォルトでは、この設定はすべてのTwilioチャネルについてtrueです: ${(system.channelType=='twilio')?then('true','false')}

外部アプリケーションは、POSTリクエストをアプリケーション・チャネルのインバウンドURLに送信してイベントを開始します。次に、リクエストを準備および送信するためにアプリケーションで実行する必要がある処理を示します。

• リクエスト本文に次のプロパティを含めます(例が続きます):

  • userId: これは次のIDのいずれかである必要があります:

    • Microsoftボット・ユーザーID: Microsoftボット・チャネルのボット・ユーザーID。このIDは、各Microsoftボット・チャネルに固有です。この値は、スキルによってprofile.msBotUserId変数に保存されます。

    • SlackユーザーID: SlackユーザーのメンバーID。スキルは、この値をsystem.message.channelConversation.userIdに保存します。

    • Twilio/SMSチャネルID: ユーザーの携帯電話番号。これは、デジタル・アシスタントのユーザー・チャネル構成で指定されているTwilioアカウントの電話番号に関連付けられている番号のいずれかである必要があります。この値は、スキルによってprofile.firstName変数に保存されます。

    • システム生成ユーザーID: 「プレビュー」でスキルをテストする場合、これは、「プレビュー」内のセッションに対してシステムで生成されるユーザーIDである必要があります。アプリケーションによって開始される会話のプレビューでのテストを参照してください。

    • 認証済ユーザーID: 関連付けられたアプリケーション・チャネルで「認証済ユーザーIDを使用」が「オン」に切り替えられている場合、これは認証済ユーザーIDである必要があります。この認証済ユーザーIDを持つユーザーは、OAuth 2.0アカウント・リンク・コンポーネントを介してターゲット・スキルにすでにサインインしている必要があります。ユーザー認証済スキルの構成を参照してください。

  • messagePayload: このオブジェクトの内容:

    • type: これをapplicationに設定します。

    • payloadType: ダイアログ・フローの目的の開始状態にマップされるイベントの名前(ペイロード・タイプ)。スキルの構成を参照してください。

    • skillNameおよびversion: (オプション)メッセージング・プラットフォームのユーザー・チャネルがデジタル・アシスタントにルーティングされる場合は、デジタル・アシスタントがイベントの送信先のスキルおよびバージョンを認識できるように、スキルのskillNameおよびversionを含める必要があります。

    • channelName: スキルまたはデジタル・アシスタントについて構成されているメッセージング・プラットフォームのユーザー・チャネルの名前。

      プレビューでスキルをテストする場合は、channelNameをシステム・チャネルの名前に設定する必要があります。アプリケーションによって開始される会話のプレビューでのテストを参照してください。

    • variables: (オプション)ダイアログ・フローの変数に渡されるキーと値のペア。対応するフロー変数がダイアログ・フローで定義されている場合、このオブジェクトから渡される値が移入されます。

  • channelProperties: このオブジェクトはMS TeamsおよびSlack用です。ユーザー・チャネルで「認証済ユーザーIDを使用」がオンに切り替えられている場合、このオブジェクトをリクエスト本文に含める必要はありません。

    MS Teams channelPropertiesオブジェクト

    このオブジェクトは、ユーザーが14日以内に会話とやり取りしていない場合に必要です。このプロパティは:

    • botName: これは、ボット・チャネル登録の作成時に指定したボット・ハンドルです(ステップ1: ボットの作成を参照)。この値は、profile.botName変数に保存されます。

    • tenantId: Microsoft TeamsテナントのID。この値は、profile.tenantId変数に保存されます。

    • serviceUrl: ボットのサービスURL。この値は、profile.serviceUrl変数に保存されます。

    Microsoft Teamsユーザーがスキルと会話すると、デジタル・アシスタントは、これらの値を取得してプロファイル・キャッシュに格納します。イベントのリクエスト・ペイロードにchannelPropertiesオブジェクトが含まれない場合、スキルは、使用可能であればプロファイル・キャッシュの値を使用します(キャッシュは14日後に期限切れになります)。スキルは、キャッシュされたプロファイル値がリクエスト本文にない場合にのみそれらの値を使用します。

    ダイアログ・フローは、カスタム・コンポーネントなどを通じてバックエンドに通知のリクエストを送信する場合、それらのプロファイル値をバックエンドに渡す必要があります。その後、外部アプリケーションは、プロファイル・キャッシュが期限切れになった場合にchannelPropertiesオブジェクト内の値を使用できます。次に、バックエンドに送信する値を取得するカスタム・コンポーネント・コードのスニペットを示します。

        let serviceUrl = conversation.variable('profile.serviceUrl') ?
            conversation.variable('profile.serviceUrl') : "";
        let tenantId = conversation.variable('profile.tenantId') ? 
            conversation.variable('profile.tenantId') : "";
        let botName = conversation.variable('profile.botName') ?
            conversation.variable('profile.botName') : "";
        let msBotUserId = conversation.variable('profile.msBotUserId') ?       
            conversation.variable('profile.msBotUserId') : "";

    Slack channelPropertiesオブジェクト

    Slackの場合、channelPropertiesオブジェクトに次のプロパティを含めます:

    • teamId: SlackワークスペースID。この値は、profile.team_id変数に保存されます。

    • channel: ワークスペース内のチャネルのID。つまり、ユーザーのチャネルです。この値は、profile.channel変数に保存されます。

    Slack Web URLからチームIDおよびチャネルを取得できます。たとえば、URLがhttps://app.slack.com/client/ABCDEFG/HIJKLMNOPの場合、チームIDはABCDEFGで、チャネルはHIJKLMNOPです。

  次に、認証済ユーザーIDを使用しないスキルの様々なメッセージング・プラットフォームの例を示します:

  Slackの例:

  { 
      "userId": "ABCDE712A3",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "teamId": "ABCDEFG",
              "channel":"HIJKLMNOP" 
          } 
      }
  }

  MS Teamsの例:

  { 
      "userId": "12:1A2B3C3d....",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "tenantId": "ab12c34d-e56...",
              "botName":"my-bot",
              "serviceUrl":"https://example.com/path/"
          } 
      }
  }

  Twilioの例:

  { 
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  この例では、デジタル・アシスタントにルーティングされるチャネルにイベントを送信する方法を示します。チャネルがデジタル・アシスタントにルーティングされる場合、スキル名とバージョンを含める必要があります。

  {
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "skillName": "myBot",
          "version": "1.0",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  次に、ユーザー認証済スキルの例を示します(関連付けられたアプリケーション・チャネルで「認証済ユーザーIDを使用」が「オン」に切り替えられています)。この例は、MS Teams、SlackおよびTwilioに適用されますMS TeamsおよびSlackの場合、ユーザー認証済スキルにルーティングするときにchannelPropertiesオブジェクトを含めないことに注意してください。

  {
      "userId": "first.last@example.com",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

• リクエストを認証するには、アプリケーション・チャネルの秘密鍵を使用して、本文のSHA256ハッシュを指定してX-Hub-Signatureヘッダーを追加します。例:

  X-Hub-Signature: sha256={{HMAC SHA-256 signature of body}}

  「アプリケーションによって開始された会話を使用したリマインダの送信」チュートリアルの「外部アプリケーションとしてのPostmanの使用」セクションは、このヘッダーの設定例を示しています。

• POSTリクエストをアプリケーション・チャネルのインバウンドURLに送信します。次の例のようになります。

  POST https://<host>:<port>/connectors/v2/listeners/application/channels/4E09-42F7-ECB7A7F18F62

外部アプリケーションのメッセージをプレビューに送信するには、システム・チャネル名とプレビューのユーザーIDが必要です。外部アプリケーションがシステム・チャネルにメッセージを送信すると、Oracle Digital Assistantは、指定されたユーザーIDのプレビューにそのメッセージをルーティングします。

1. システム・チャネルの名前を取得するには、左側のナビゲーション・バーから「チャネル」をクリックし、「システム」をクリックして、名前を確認します。

   名前はSystem_Bot_TestまたはSystem_Global_Testです。

2. プレビューのユーザーIDを取得するには、スキルを開き、「プレビュー」をクリックします。

3. 最初にブラウザ・メニューで「Web開発者」を選択し、次に「ネットワーク」をクリックして、ネットワーク・モニターを開きます。

4. 「XHR」を選択してRESTリクエストのみを表示します。

5. プレビューにメッセージを入力します。

6. スキルがテキストを出力した後、ネットワーク・モニターに移動して、「レスポンス」タブを確認します。

   messagePayloadを含むレスポンスが見つかるまで、各レスポンスを選択します。

7. 「フィルタ・プロパティ」フィールドにuserIdと入力して、userIdの値を表示します。

8. プレビューはアクティブなままにし、「リセット」をクリックしないでください。

   プレビューをリセットするか閉じると、ユーザーIDが変更されます。

システム・チャネルの名前およびシステムのユーザーIDを取得した後、外部アプリケーションからスキルのプレビューにメッセージを送信できます。

メッセージング・サービスのかわりにプレビューを使用するには、次のように、userIdをプレビューのユーザーIDに設定し、channelNameをシステム・チャネルの名前に設定します:

{
    "userId": "7319408",
    "messagePayload": {
        "type": "application",
        "payloadType": "msgReminder",
        "channelName": "System_Global_Test",
        "variables": {
        	"patientName": "Joe Doe",
        	"appointmentTime": "5:00 pm"
        }
    }
}