統合変数

式を作成することにより、統合 (Web チャットや電話統合など) に固有のコンテキスト変数である統合変数にアクセスすることができます。 すべての統合変数は system_integrations JSON オブジェクトに含まれています。このオブジェクトには、以下の式を使用してアクセスできます。

${system_integrations}

system_integrations

{
  "channel": {
    "name": "{channel_name}",
    "private": {
      "user": {
        "id": "{user_id}",
        "phone_number": "{phone_number}",
        "name": "{name}"
      }
    }
  },
  "chat": {...},
  "voice_telephony": {...},
  "text_messaging": {...},
  "whatsapp": {...},
  "slack": {...},
  "facebook": {...},
  "teams": {...}
}

channel

常に含まれます。 このオブジェクトには、アシスタントとの通信に使用されているチャネルに関する一般情報が含まれています。

プロパティー

private オブジェクトに含まれるプロパティーは、ログに含まれないプライベート変数として扱われます。

チャネル・オブジェクトのプロパティー
名前 タイプ 説明
channel.name ストリング

使用されているチャネルの名前。 以下のいずれかの値:

  • Web chat
  • Phone
  • SMS
  • Whatsapp
  • Slack
  • Facebook Messenger
  • teams
channel.private.user.id ストリング チャネルを使用してアシスタントと対話しているユーザーの ID。 この ID はチャネルに固有のものであり、 watsonx Assistant が請求処理の目的で使用するユーザー ID とは異なる場合があります。 詳しくは、 チャネル・ユーザー ID を参照してください。
channel.private.user.phone_number ストリング ユーザーに関連付けられている電話番号。 電話、SMS、および WhatsApp の統合によって設定されます。
channel.private.user.name ストリング チャネルを使用してアシスタントと対話しているユーザーの名前。 Microsoft Teams 統合によって設定されます。
channel.private.user.aadObjectId ストリング チャネルを介してアシスタントと対話しているユーザーの Azure Active Directory (AAD) のオブジェクト ID。 Microsoft Teams 統合によって設定されます。

JSON の例

"channel": {
  {
    "name": "Web chat",
    "private": {
      "user": {
        "id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
      }
    }
  }
}

チャネル・ユーザー ID

channel.private.user.id プロパティー (チャネル統合によって設定される) は、チャネルに固有の顧客のユーザー ID を指定します。 このユーザー ID のソースは、チャネルによって異なります。

チャネル・ユーザー ID のソース
チャネル チャネル・ユーザー ID
Web チャット Web チャット・インスタンスによって設定されたユーザー ID。 詳しくは、 Web チャットでのユーザー ID 情報の管理 を参照してください。
Slack Slack のメンバー ID (例えば、 U2147483697)。
Facebook Facebook 送信者 ID (例えば、 4310101122439797)。
Whatsapp 顧客の電話番号。
電話番号 顧客の電話番号。
SMS with Twilio 顧客の電話番号。
チーム チーム・ユーザー ID (例えば、 29:1CV2T75j3QUY-mQCQcIk2...)。チーム・ユーザーの aadObjectId を指定します。

chat

Web チャット統合が使用されている場合にのみ含まれます。

プロパティー

チャット・オブジェクトのプロパティー
名前 タイプ 説明
browser_info.browser_name ストリング chromeedgefirefox などのブラウザ名。
browser_info.browser_version ストリング ブラウザーのバージョン ( 109.0.0 など)。
browser_info.browser_OS ストリング お客様コンピューターのオペレーティング・システム、例えば Mac OS
browser_info.language ストリング ブラウザのデフォルトロケールコード、例えば en-US
browser_info.page_url ストリング ウェブチャットが埋め込まれたウェブページの URL (クエリパラメータやハッシュは含まない)。
browser_info.screen_resolution ストリング ブラウザー・ウィンドウの高さと幅 ( width: 1440, height: 900 など)。
browser_info.user_agent ストリング HTTP User-Agent リクエストヘッダの内容。
browser_info.client_ip_address ストリング お客様コンピューターのIPアドレス。
browser_info.ip_address_list 配列 HTTP X-Forwarded-For リクエストヘッダで指定されたアン配列IPアドレス。

JSON の例

"chat": {
  "browser_info": {
    "browser_name": "chrome",
    "browser_version": "109.0.0",
    "browser_OS": "Mac OS",
    "language": "en-US",
    "page_url": "https://us-south.assistant.watson.cloud.ibm.com/crn%3Av1%3Abluemix%3Apublic%3Aconversation%3Aus-south%3Aa%2Fc41400d63d91741a749091dc63574c2c%3Ab696c1e5-7316-4fb0-a61c-664438397e91%3A%3A/assistants/e344fcfe-506c-449f-a182-ebdefe4356ad/actions/actions/custom/edit/action_28584",
    "screen_resolution": "width: 1920, height: 1080",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36",
    "client_ip_address": "65.191.135.254",
    "ip_address_list": [
      "65.191.135.254",
      " 104.99.56.143",
      "10.185.27.136",
      "172.30.226.64"
    ]
  }
},
"channel": {
  "name": "Web chat",
  "private": {
    "user": {
      "id": "anonymous_IBMuid-727c0302-6fd7-4abb-b7ee-f06b4bf30e99"
    }
  }
}

式の例

  • この式は、顧客が Chrome ブラウザーを使用しているかどうかをテストします。

    ${system_integrations}.chat.browser_info.browser_name.equals("chrome")
    

    この式をブール・セッション変数の値として指定し、ステップ条件で使用することができます。 例えば、Web サイトが Chrome のみをサポートしている場合、この変数を false としてステップを条件付けし、出力を I see you aren't using the Chrome browser. Some features of our website work only on Chrome. とすることができます。

  • この式は、現在のページ URL に文字列 payment.html が含まれているかどうかをテストする:

    ${system_integrations}.chat.browser_info.page_url.contains("payment.html")
    

    既に表示されているページにナビゲートするように顧客に指示することを避けるために、この式をステップ条件で使用することができます。 例えば、請求書を支払うアクションでは、この変数を false としてステップを条件付けし、以下の出力を得ることができます。 First, click **Pay bill** to navigate to the bill payment page.

voice_telephony

電話統合が使用中の場合にのみ含まれます。

voice_telephony オブジェクトには、応答プロパティーと要求プロパティーの両方が含まれています。 要求プロパティーは、電話統合によって設定される値であり、通話に関する情報を提供します。 応答プロパティーは、ロギング・データを送信したり、呼び出しの構成オプションを変更したりするためにアクションで変更できる入力値です。

要求プロパティー (電話統合によって設定)

private オブジェクトに含まれるプロパティーは、ログに含まれないプライベート変数として扱われます。

voice_telephony オブジェクトの要求プロパティー
名前 タイプ 説明
sip_call_id ストリング 電話に関連付けられたSIPコールID。
assistant_phone_number ストリング 通話の watsonx Assistant の終端に関連付けられている電話番号。
sip_custom_invite_headers オブジェクト SIP INVITE 要求からの SIP ヘッダーを含むキー/値のペアのユーザー定義配列。
private.user_phone_number ストリング 顧客の電話の発信元の電話番号。
private.sip_request_uri ストリング 電話呼び出しを開始したインバウンド SIP 要求 URI。
private.sip_from_uri ストリング SIP 要求の From ヘッダーに含まれる URI。
private.sip_to_uri ストリング SIP 要求の To ヘッダーに含まれる URI。
final_utterance_timeout_occurred ブール値 最終発話タイムアウトに達した場合は、 true に設定します。 このタイムアウトは、 final_utterance_timeout_count プロパティーを送信することによって構成できます。
post_response_timeout_occurred ブール値 最終発話タイムアウトに達した場合は、 true に設定します。 このタイムアウトは、 post_response_timeout_count プロパティーを送信することによって構成できます。

要求 JSON の例

"voice_telephony": {
  "private":{
    "user_phone_number":"+18595553456",
    "sip_request_uri":"sips:+18885557777@public.voip.us-east.assistant.watson.cloud.ibm.com",
    "sip_from_uri":"sips:+18565558576@twilio.com",
    "sip_to_uri":"sips:+18885557777@public.voip.us-east.assistant.watson.cloud.ibm.com"
  },
  "sip_call_id": "Aob2-2743-5678-1234",
  "assistant_phone_number":"+18885556789",
  "sip_custom_invite_headers": {
    "custom-header1": "123",
    "custom-header2": "456"
  }
}

カスタムSIPヘッダーには、以下のフォーマットでアクセスできます:

${system_integrations.voice_telephony.sip_custom_invite_headers}[<headername>]

以下に例を示します。

${system_integrations.voice_telephony.sip_custom_invite_headers}["custom-header1"]

は値 123 を返す。

応答プロパティー (アシスタントによって設定)

voice_telephony オブジェクトの応答プロパティー
名前 タイプ 説明
final_utterance_timeout_count 整数 Speech to Text サービスからの最終的な発話を待機する時間 (ミリ秒単位)。 タイムアウトが発生する前に最終的な発話を受信しなかった場合、電話統合は、 final_utterance_timeout_occurred プロパティーを true に設定して、アシスタントにメッセージを送信します。
post_response_timeout_count 整数 最後の応答が再生された後、新しい発話を待機する時間 (ミリ秒)。 タイムアウトが発生する前に発話を受信しなかった場合、電話統合は、 true に設定された post_response_timeout_occurred プロパティーを含むメッセージをアシスタントに送信します。
cdr_custom_data オブジェクト 通話の CDR レコードに保管されるキー/値のペアを含む JSON オブジェクト。 このオブジェクトが送信されるたびに, その内容が呼び出し中に前に送信されたデータと組み合わされます。
turn_settings.timeout_count 整数 watsonx Assistant が各会話ターンの処理を終了するまで待機する時間 (ミリ秒)。

応答 JSON の例

"voice_telephony" : {
  "post_response_timeout_count":10000,
  "final_utterance_timeout_count":30000,
  "turn_settings": {
    "timeout_count": 5000
  },
  "cdr_custom_data" : {
    "custom_data_1": "data 1",
    "custom_data_2": "data 2"
  }
}

text_messaging

SMS with Twilio 統合が使用されている場合にのみ含まれます。

プロパティー

private オブジェクトに含まれるプロパティーは、ログに含まれないプライベート変数として扱われます。

text_messaging オブジェクトのプロパティー
名前 タイプ 説明
assistant_phone_number ストリング 会話の watsonx Assistant 終了に関連付けられている電話番号。
private.user_phone_number ストリング 顧客の SMS メッセージの発信元の電話番号。

JSON の例

"text_messaging": {
  "private":{
    "user_phone_number":"+18595553456"
  },
  "assistant_phone_number":"+18885556789"
}

whatsapp

WhatsApp 統合が使用中の場合にのみ含まれます。

プロパティー

private オブジェクトに含まれるプロパティーは、ログに含まれないプライベート変数として扱われます。

whatsapp オブジェクトのプロパティ
名前 タイプ 説明
assistant_phone_number ストリング 会話の watsonx Assistant 終了に関連付けられている電話番号。
private.user_phone_number ストリング 顧客の WhatsApp メッセージの発信元の電話番号。

JSON の例

"whatsapp": {
  "private":{
    "user_phone_number":"+18595553456"
  },
  "assistant_phone_number":"+18885556789"
}

slack

Slack 統合が使用されている場合にのみ含まれます。

プロパティー

Slack オブジェクトのプロパティー
名前 タイプ 説明
team_id ストリング Slackチームのユニークな識別子。
channel_id ストリング Slack チャネルの一意の識別子。

JSON の例

"slack": {
  "team_id":"T02F3KE542J",
  "channel_id":"C4K3KTTRD"
}

facebook

Facebook 統合が使用中の場合にのみ含まれます。

プロパティー

追加のプロパティーはありません。

JSON の例

"facebook": {}

teams

Microsoft Teams 統合が使用されている場合にのみ含まれます。

プロパティー

teams オブジェクトのプロパティー
名前 タイプ 説明
conversation_id ストリング Microsoft Teams 会話の一意の識別子。

JSON の例

"teams":{
  "conversation_id":"a:1ATy08jyGkPGy2QdKIrGZL5u_o6fIUVDRKeIZtkIUAkQDC23FC9S97f18i-UNl-eISAfDWqoQeTbregvSE8jK0LNy6h9VssNcN3CsGG9guMiUB0EeSqxnnEFpAVzbkayR"
}