仮想エージェントのカスタム ペイロード

Dialogflow CX のカスタム ペイロードを使用すると、プレーン テキストベースのチャットやインタラクションを超えて、仮想エージェントのエクスペリエンスを強化できます。 Dialogflow CX でカスタム ペイロードを使用すると、カスタム レスポンスと引用を表示するように仮想エージェントを構成できます。

カスタム レスポンス メッセージの種類

カスタム レスポンス を使用すると、次のメッセージ タイプを表示できます。

  • テキスト

  • インライン ボタン

  • 固定ボタン

  • 画像

  • 動画

  • ドキュメント

  • 複合ビュー（1 つ以上のメッセージ タイプの組み合わせ）

カスタム アクション を使用すると、仮想エージェントは次のアクションを実行できます。

  • 人間のエージェントへのエスカレーション

  • 人間のエージェントへの計画的な転送

  • サポート セッションを終了する

コンタクト センター AI プラットフォーム（CCAI プラットフォーム）のペイロード

Dialogflow CX でカスタム ペイロードとして使用されます。次の例は、Dialogflow CX を使用した webSDK のレスポンスの形式を示しています。

{
  "ujet": {
    "type": "text|inline_button|sticky_button|image|video|document|complex|action",
    "action": "escalation|end",
    "title": "message displayed on the top of the message",
    "escalation_reason": "by_consumer|by_virtual_agent",
    "session_variable": {
      "capture_target": "payload|end_user_response",
      "capture_key": "key",
      "payload": {
      }
    },
    "messages": [
      "Hello",
      "How can I help you?"
    ],
    "buttons": [
      {
        "title": "Button 1",
        "action": "quick_reply"
      },
      {
        "title": "Button 2",
        "action": "quick_reply"
      }
    ],
    "images": [
      {
        "url": "https://image.url",
        "text": "an alternate text for an image for when failed to load an image"
      },
      {
        "url": "https://image.url",
        "text": "an alternate text for an image"
      }
    ],
    "videos": [
      {
        "url": "https://video.url",
        "text": "an alternate text for a video for when failed to load a video"
      },
      {
        "url": "https://video.url",
        "text": "an alternate text for a video"
      }
    ],
    "documents": [
      {
        "url": "https://document.url",
        "text": "an alternate text for a document for when failed to load a document"
      },
      {
        "url": "https://document.url",
        "text": "an alternate text for a document"
      }
    ],
    "components": [
      {
        "type": "text",
        "messages": [
          "We need the information for helping you.",
          "Could you please choose the following options?"
        ]
      },
      {
        "type": "inline_button",
        "buttons": [
          {
            "title": "Button 1",
            "action": "quick_reply"
          },
          {
            "title": "Button 2",
            "action": "quick_reply"
          }
        ]
      },
      {
        "type": "image",
        "images": [
          {
            "url": "https://image.url",
            "text": "an alternate text for an image for when failed to load an image"
          },
          {
            "url": "https://image.url",
            "text": "an alternate text for an image"
          }
        ]
      }
    ]
  }
}

カスタム ペイロードのチャット メッセージ形式

適切な UI を表示するために CCAI プラットフォーム SDK で使用されます。Dialogflow CX のカスタム ペイロード形式と同じですが、ルートに「ujet」フィールドはありません。

詳細については、次の例をご覧ください。

例

以降のセクションでは、Dialogflow CX で使用できるペイロードの例を示します。

テキスト

{
  "ujet": {
    "type": "text",
    "messages": [
      "Hello",
      "How can I help you?"
    ]
  }
}

同じキューへのエスカレーション

仮想エージェントによる場合:

{
  "ujet": {
    "type": "action",
    "action": "escalation",
    "escalation_reason": "by_virtual_agent"
  }
}

エンドユーザーによる場合:

{
  "ujet": {
    "type": "action",
    "action": "escalation",
    "escalation_reason": "by_consumer"
  }
}

escalation_reason の値はダッシュボードに報告されます。

ターゲット キューへのエスカレーション

仮想エージェントによる場合:

{
  "ujet": {
    "type": "action",
    "action": "escalation",
    "escalation_reason": "by_virtual_agent",
    "menu_id": 100,
    "language": "ko"
  }
}

エンドユーザーによる場合:

{
  "ujet": {
      "type": "action",
      "action": "escalation",
      "escalation_reason": "by_consumer",
      "menu_id": 100,
      "language": "ko"
  }
}

escalation_reason の値はダッシュボードに報告されます。

会話を終了する

{
  "ujet": {
    "type": "action",
    "action": "end"
  }
}

インライン ボタン

{
  "ujet": {
    "type": "inline_button",
    "title": "Select a menu",
    "buttons": [
      {
        "title": "Lorem Ipsum",
        "action": "quick_reply"
      },
      {
        "title": "Lorem Ipsum Dolor Sit Amet",
        "action": "escalation"
      }
    ]
  }
}

例

インライン ボタンの例

固定ボタン

{
  "ujet": {
    "type": "sticky_button",
    "title": "Select a menu",
    "buttons": [
      {
        "title": "Lorem Ipsum",
        "action": "quick_reply"
      },
      {
        "title": "Lorem Ipsum Dolor Sit Amet",
        "action": "escalation"
      }
    ]
  }
}

例

スティッキー ボタンの例

画像の表示

{
  "ujet": {
    "type": "image",
    "title": "Please see the following images",
    "images": [
      {
        "url": "https://image1.url",
        "text": "an alternate text for an image for when failed to load an image"
      },
      {
        "url": "https://image2.url",
        "text": "an alternate text for an image"
      }
    ]
  }
}

動画の視聴

{
  "ujet": {
    "type": "video",
    "title": "Please see the following videos",
    "videos": [
      {
        "url": "https://video1.url",
        "text": "an alternate text for a video for when failed to load a video"
      },
      {
        "url": "https://video2.url",
        "text": "an alternate text for a video"
      }
    ]
  }
}

ドキュメントの閲覧

{
  "ujet": {
    "type": "document",
    "title": "Please see the following document",
    "documents": [
      {
        "url": "https://document1.url",
        "text": "an alternate text for a document for when failed to load a document"
      },
      {
        "url": "https://document2.url",
        "text": "an alternate text for a document"
      }
    ]
  }
}

複合ビュー

{
  "ujet": {
    "type": "complex",
    "type": "Welcome to CCAI Platform world!",
    "components": [
      {
        "type": "text",
        "messages": [
          "We need the information for helping you.",
          "Could you please choose the following options?"
        ]
      },
      {
        "type": "inline_button",
        "buttons": [
          {
            "title": "Button 1",
            "action": "quick_reply"
          },
          {
            "title": "Button 2",
            "action": "quick_reply"
          }
        ]
      },
      {
        "type": "image",
        "images": [
          {
            "url": "https://image1.url",
            "text": "an alternate text for an image for when failed to load an image"
          },
          {
            "url": "https://image2.url",
            "text": "an alternate text for an image"
          }
        ]
      }
    ]
  }
}

Dialogflow でカスタム ペイロードを構成する

Dialogflow を使用してカスタム ペイロードを構成する方法については、カスタム ペイロード レスポンス （Dialogflow ES）または カスタム ペイロード （Dialogflow CX）リソースをご覧ください。

詳細については、カスタム ペイロード処理の カスタム セッション変数をご覧ください。

仮想エージェントから電話番号または SIP エンドポイントへの転送

Dialogflow CX のカスタム ペイロードを使用すると、音声仮想エージェントから指定した電話番号または SIP エンドポイントに電話を転送できます。接続に成功すると、仮想エージェントが通話から削除され、通話が続行されます。接続に失敗すると、転送失敗メッセージが再生され、仮想エージェントとの通話が続行されます。

仮想エージェントの転送は、内部通話と外部通話の両方で機能します。仮想エージェントの転送は、レポートで Planned Transfers として記録されます。

電話番号に電話を転送する

仮想エージェントから電話番号に電話を転送するには、次のコードサンプルと同様の Dialogflow CX ペイロードを使用します。

{
  "ujet": {
    "type": "action",
    "action": "deflection",
    "deflection_type" : "phone",
    "phone_number": "+16509424879"
  }
}

SIP エンドポイントに電話を転送する

仮想エージェントから SIP エンドポイントに電話を転送できます。呼び出しタイムアウトは省略可能です。

呼び出しタイムアウト

呼び出しタイムアウトを構成するには、sip_ring_timeout フィールドを追加します。これにより、内部拡張機能またはユニファイド コミュニケーション（UC）の宛先への通話は、切断される前に十分な時間応答できます。これは Twilio ユーザーのみが対象です。 Twilio では、構成した呼び出しタイムアウトに約 5 秒が追加されます。

例

仮想エージェントから SIP エンドポイントに電話を転送するには、次のコードサンプルと同様の Dialogflow ペイロードを使用します。

{
  "ujet": {
    "type": "action",
    "action": "deflection",
    "deflection_type" : "sip",
    "sip_uri": "SIP_ENDPOINT",
    "sip_ring_timeout": SIP_RINGING_TIMEOUT
  }
}

次のように置き換えます。

  • SIP_ENDPOINT: 通話の転送先の SIP エンドポイント。sip:1-999-123-4567@voip-provider.example.net のようになります。

  • SIP_RINGING_TIMEOUT: 省略可: 通話がタイムアウトするまでの呼び出し時間（秒単位）。有効な値: 10～600（両端を含む）。この範囲外の値を設定すると、デフォルトの呼び出しタイムアウトである 30 秒が使用されます。デフォルト: 30 秒。

SIP REFER メソッドを使用して SIP エンドポイントに電話を転送する

SIP REFER メソッドを使用して仮想エージェントから SIP エンドポイントに電話を転送するには、次のコードサンプルと同様の Dialogflow CX ペイロードを使用します。SIP REFER メソッドを使用すると、ヘッダー プロパティを使用して有用な情報を渡すことができます。

{
    "ujet": {
       "type": "action",
       "action": "deflection",
       "deflection_type" : "sip"
       "sip_uri": "sip:1-999-123-4567@voip-provider.example.net"
       "sip_refer": true
       "sip_parameters": {
       "x-header": "value",
       "x-header": "value"
       }
    }
}

カスタム ペイロード処理のカスタム セッション変数

カスタム セッション変数を使用して、インテント レスポンスとエンドユーザー レスポンスから値を取得し、それらをすべて収集して、コメントとして CRM にアップロードします。 詳細については、カスタム セッション 変数の Dialogflow ペイロードをご覧ください。

エンドユーザー レスポンスからキャプチャする

Flow

  1. CCAI プラットフォームは、Dialogflow CX にレスポンスをリクエストします。

    Dialogflow CX は、フルフィルメントによってお客様のサーバーにコールバックすることがあります。

    お客様のサーバーは、レスポンスの session_variable フィールドに入力する必要があります。

  2. Dialogflow CX は、capture_target = end_user_response の session_variable フィールドを含むカスタム ペイロードでレスポンスを返します。

  3. エンドユーザーがメッセージを送信します。

  4. CCAI プラットフォームは、前のステップで送信されたエンドユーザー メッセージを保持します。

  5. 仮想エージェントがチャットから離れたときに、チャット セッションでキャプチャされたすべてのセッション変数が、コメントとして CRM に投稿されます。

カスタム ペイロード形式

{
  "ujet": {
    "session_variable": {
      "capture_target": "end_user_response",
      "capture_key": "key"
    }
  }
}

仮想エージェントがカスタム ペイロードを送信した直後のエンドユーザー メッセージは、キー「key」のセッション変数としてキャプチャされます。

インテント レスポンスからキャプチャする

Flow

  1. CCAI プラットフォームは、Dialogflow CX にレスポンスをリクエストします。

    1. Dialogflow CX は、フルフィルメントによってお客様のサーバーにコールバックすることがあります。

    2. お客様のサーバーは、レスポンスの session_variable フィールドに入力する必要があります。

  2. Dialogflow CX は、カスタム ペイロード を含む session_variable フィールドと capture_target = "payload" でレスポンスを返します。

  3. CCAI プラットフォーム サーバーは、ステップ 2 で payload オブジェクトを保持します。

仮想エージェントがチャットから離れたときに、チャット セッションでキャプチャされたすべてのセッション変数が、コメントとして CRM に投稿されます。

カスタム ペイロード形式

{
  "ujet": {
    "session_variable": {
      "capture_target": "payload",
      "capture_type": [
        "comment",
        "agent"
      ],
      "payload": {
        "status": "STATUS",
        "order_id": "ORDER_ID",
        "personal_id": "PERSONAL_ID"
      },
        "invisible_to_agent": ["INVISIBLE_TO_AGENT"],
        "display_order_in_adapter": ["DISPLAY_ORDER_IN_ADAPTER"]
    }
  }
}

次のように置き換えます。

  • STATUS: 注文のステータス

  • ORDER_ID: 注文 ID

  • PERSONAL_ID: エンドユーザーの識別子。

  • INVISIBLE_TO_AGENT: エージェント アダプターに表示しないプロパティの配列。たとえば、ここに "personal_id" の値を指定すると、personal_id プロパティがエージェント アダプターに表示されなくなります 。詳細については、仮想エージェントのセッション 変数を表示するをご覧ください。

  • DISPLAY_ORDER_IN_ADAPTER: セッション変数をエージェント アダプターと CRM レコードに表示する順序を指定するプロパティの配列。詳細については、仮想エージェントのセッション 変数を表示するをご覧ください。

CRM へのカスタム セッション変数のアップロード

各セッション変数について、サーバーはすべてのセッション変数を内部的に収集し、仮想エージェントが離れたときに CRM にアップロードする必要があります。

CRM メッセージの例

    ###########################

    Chat ID: 1
    Menu ID: 1
    Chatbot Platform: Platform Name
    Chatbot Workflow: Workflow Name
    Virtual Agent: Virtual Agent Name

    ###########################

    Intent: Intent Captured from End User Response
    Captured At: 2020-06-25 14:54:19

    Captured Variables
    request: Cancel Order

    ###########################

    Intent: Intent Captured from Payload
    Captured At: 2020-06-25 14:58:23

    Captured Variables
    status: Cancelled
    order_id: #12345

    ###########################

シナリオの例

以下は、仮想エージェントとエンドユーザーの間でやり取りされるさまざまなステップとメッセージを示す会話のサンプルです。

ステップ 1

仮想エージェントからのチャット メッセージ

How can I help you? (Button) Show my orders (Button) Cancel an order

インテント レスポンス（カスタム ペイロード）

{
  "ujet": {
    "type": "inline_button",
    "title": "How can I help you?",
    "buttons": [
      {
        "title": "Show my orders",
        "action": "quick_reply"
      },
      {
        "title": "Cancel an order",
        "action": "quick_reply"
      }
    ]
  }
}

キャプチャされたセッション変数

なし

ステップ 2

エンドユーザーからのチャット メッセージ

Click "Cancel an order" button.

キャプチャされたセッション変数

なし

ステップ 3

仮想エージェントからのチャット メッセージ

Can you provide the order id please

インテント レスポンス（カスタム ペイロード）

{
  "ujet": {
    "type": "text"
    "messages": [
      "Can you provide the order id please"
    ],
    "session_variable": {
       "capture_target": "end_user_response",
       "capture_key": "order_id";
    }
  }
}

キャプチャされたセッション変数

なし

ステップ 4

エンドユーザーからのチャット メッセージ

Order id is #12345

キャプチャされたセッション変数

order_id: "Order ID is #12345"

ステップ 5

仮想エージェントからのチャット メッセージ

Order #12345 is cancelled. Do you need anything else?

インテント レスポンス（カスタム ペイロード）

{
  "ujet": {
    "type": "text",
    "messages": [
      "Order #12345 is canceled.",
      "Do you need anything else?"
    ],
    "session_variable": {
      "capture_target": "payload",
      "capture_type": [
        "agent",
        "comment",
        "event"
      ],
      "payload": {
        "order_id": "#12345",
        "order_status": "cancelled"
      }
    }
  }
}

キャプチャされたセッション変数

order_id: "#12345", order_status: canceled

ステップ 6

エンドユーザーからのチャット メッセージ

I would like to speak with a human agent.

ステップ 7

仮想エージェントからのチャット メッセージ

Virtual Agent is left from the conversation.

{
  "ujet": {
    "type": "escalation",
    "escalation_reason": "by_consumer"
  }
}

CRM へのカスタム セッション変数のアップロード

上記のシナリオでは、次のコメントが CRM チケットに投稿されます。

    ---------------------------------

    Chat ID: 1
    Menu ID: 1
    Chatbot Platform: Platform Name
    Chatbot Workflow: Workflow Name
    Virtual Agent: Virtual Agent Name

    --------------------------------

    Intent: Intent Captured from End User Response
    Captured At: 2020-06-25 14:54:19

    Captured Variables
    order_id: Order id is #12345.

    --------------------------------

    Intent: Intent Captured from Payload
    Captured At: 2020-06-25 14:58:23

    Captured Variables
    order_id: #12345
    order_status: canceled

    --------------------------------

コンテンツ カードを構成する

コンテンツ カード は、カード形式で簡潔で視覚的に魅力的なコンテンツを表示し、エンドユーザーが提示された情報を簡単に利用できるようにします。Dialogflow CX を使用してコンテンツ カードを作成し、タイトル、サブタイトル、本文をカスタマイズできます。

次の例では、コンテンツ カードを使用して、レストランのオプションをエンドユーザーに表示します。

コンテンツ カードの例

コンテンツ カードのプロパティ

プロパティ名 説明 必須 タイプ
title カードのタイトル。 はい 文字列
subtitle カードのサブタイトル。 いいえ 文字列
body コンテンツ カードの説明。 はい 文字列
link ウェブページ リンクまたはディープリンク。SDK は OS の機能を使用して開きます。 いいえ 文字列
event_params クリック イベントに関する追加情報を含む辞書。SDK で使用されます。 いいえ 辞書

Dialogflow CX ペイロード: 検証を追加してコンテンツ カードタイプを受け入れる

特定の Dialogflow CX ペイロード タイプは、chatbot サーバーを介してエンドユーザーからメッセージを受信したときにコンテンツ カードを処理します。以下に、Dialogflow CX ペイロードの例を示します。

{
  "ujet": {
    "type": "content_card",
    "cards": [
      {
        "title": "Title",
        "subtitle": "Subtitle",
        "body": "Body",
        "link": "app://page",
        "event_params": {} # for deep-link click event
      }
    ]
  }
}

CRM チャット履歴のコンテンツ カードに関する情報

カードのタイトル情報は、エンドユーザーがクリックしたカードを追跡するために記録されます。この情報は CRM チャット履歴に記録されます。

次の例では、CRM のチャット メッセージ履歴にコンテンツ カードのインタラクションが表示されます。

[Chat message history]
ID: 305   |   2023-07-06     PDT
--------------------------------------------------
[01:13:32     VA]     Welcome message

[01:14:35     Mobile U.]     Content Cards:
- Title 1
- Title 2

コンテンツ カードのタイトル クリック イベントをログに記録する

エンドユーザーがコンテンツ カードのタイトルをクリックしたときにログに記録するには、次の形式でイベントをキャプチャします。

{end_user_name} clicked on the '{title}' card.
Note Title: Content Card click
Note Comment: 'John Doe' clicked on the 'See our new website' card.

エンドユーザー イベント API を使用してコンテンツ カードのクリック イベントを作成する

エンドユーザーがコンテンツ カードのタイトルをクリックしたときに、クリックしたカードのタイトルとともに指定した URL に POST リクエストを送信して、このイベントを記録できます。

API エンドポイント: POST /api/v2/chat/:id/end_user_event

使用方法: コンテンツ カードのクリック イベントを作成します。

URL: /api/v2/chats/:id/end_user_event

メソッド: POST

パラメータ:

フィールド タイプ 説明
event オブジェクト
event.name 文字列 コンテンツ カードのクリック イベントには content_card_clicked を使用します。
event.payload オブジェクト
event.payload.title 文字列 クリックしたカードのタイトルを入力します。
（省略可）end_user_name 文字列 エンドユーザーの名前を入力します。空白のままにすると、名前は CRM から取得されます。

リクエスト例:

{
  "event": {
    "name": "content_card_clicked",
    "payload": {
      "title": "New our website"
    }
  },
  "end_user_name": "consumer 1"   ## optional
}

対処: Status: 202 Accepted