整合变量

在线编辑

通过编写表达式，您可以访问集成变量，即集成（如网络聊天和电话集成）专用的上下文变量。 所有集成变量都包含在 "system_integrationsJSON 对象中，您可以使用以下表达式访问该对象：

${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

始终包括在内。 该对象包含用于与 AI 助手通信的通道的一般信息。

属性

private对象中包含的属性被视为私有变量，不会包含在日志中。

表 1. 通道对象的属性

名称

Type

描述

channel.name

字符串

正在使用的通道名称。 以下值之一：\n - Web chat \n - Phone \n - SMS \n - SlackWhatsapp \n - \n - Facebook Messenger \n - teams

channel.private.user.id

字符串

通过该渠道与 AI 助手进行交互的用户的 ID。 此 ID 专用于该频道，可能与 AI 助手用于计费的用户 ID 不同。 如需更多信息，请参阅 “频道用户 ID”。

channel.private.user.phone_number

字符串

与用户相关联的电话号码。 由电话、短信和WhatsApp集成设置。

channel.private.user.name

字符串

通过该渠道与 AI 助手进行交互的用户名称。 由 Microsoft Teams 集成设置。

channel.private.user.aadObjectId

字符串

通过该渠道与 AI 助手进行交互的用户的 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 的来源取决于通道：

表 2. 频道用户 ID 的来源

通道

频道用户 ID

Web 聊天

网络聊天实例设置的用户 ID。 更多信息，请参阅管理网络聊天中的用户身份信息。

Slack

Slack 成员 ID（例如，"U2147483697）。

脸书

Facebook 发件人 ID（例如 "4310101122439797）。

Whatsapp

客户的电话号码。

电话

客户的电话号码。

SMS with Twilio

客户的电话号码。

团队

团队用户 ID（例如 "29:1CV2T75j3QUY-mQCQcIk2...）并提供团队用户的 "aadObjectId。

chat

仅在使用网络聊天集成时才包括在内。

属性

表 3. chat 对象的属性

名称

Type

描述

browser_info.browser_name

字符串

浏览器名称，如 "chrome、"edge或 "firefox。

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

数组

安数组 IP 地址，由 HTTP X-Forwarded-For 请求头指定。

示例 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")

您可以将此表达式指定为布尔会话变量的值，然后将其用于步骤条件中。 例如，如果您的网站只支持 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对象中包含的属性被视为私有变量，不会包含在日志中。

表 4. 获取 voice_telephony 对象的属性

名称

Type

描述

sip_call_id

字符串

与电话呼叫相关的 SIP 呼叫 ID。

assistant_phone_number

字符串

与该 AI助手关联的电话号码将在通话结束时显示。

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"
  }
}

响应属性（由 AI 助手设置）

表 5. voice_telephony 对象的响应属性

名称

Type

描述

final_utterance_timeout_count

整数

等待 Speech to Text 服务返回最终响应所需的时间（以毫秒为单位）。 如果在超时发生前未收到最终语音输入，电话集成会向 AI 助手发送一条消息，其中 final_utterance_timeout_occurred 属性设置为 true。

post_response_timeout_count

整数

播放最后一个应答后等待新语音的时间（毫秒）。 如果在超时发生前未收到任何语音输入，电话集成会向 AI 助手发送一条消息，其中包含一个 post_response_timeout_occurred 属性，其值设为 true。

cdr_custom_data

对象

一个 JSON 对象，包含要存储在呼叫 CDR 记录中的键/值对。 每次发送该对象时，其内容都会与呼叫期间之前发送的数据合并。

turn_settings.timeout_count

整数

等待 AI 助手完成每次对话轮次处理所需的时间（以毫秒为单位）。

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

仅在使用与 Twilio 集成的 SMS 时才包括在内。

属性

private对象中包含的属性被视为私有变量，不会包含在日志中。

表 6. text_messaging 对象的属性

名称

Type

描述

assistant_phone_number

字符串

与该 AI助手关联的电话号码。

private.user_phone_number

字符串

发送客户短信的电话号码。

示例 JSON

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

whatsapp

仅在使用WhatsApp集成时才包含。

属性

private对象中包含的属性被视为私有变量，不会包含在日志中。

表 7. WhatsApp 对象的属性

名称

Type

描述

assistant_phone_number

字符串

与该 AI助手关联的电话号码。

private.user_phone_number

字符串

客户发送WhatsApp消息的电话号码。

示例 JSON

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

slack

仅在使用 Slack 集成时才包括在内。

属性

表 8. slack 对象的属性

名称

Type

描述

team_id

字符串

Slack 团队的唯一标识符。

channel_id

字符串

Slack 频道的唯一标识符。

示例 JSON

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

facebook

仅在使用 Facebook 集成时才包括在内。

属性

无附加属性。

示例 JSON

"facebook": {}

teams

仅在使用 Microsoft Teams 集成时包含。

属性

表9。 teams 对象的属性

名称

Type

描述

conversation_id

字符串

Microsoft Teams 对话的唯一标识符。

示例 JSON

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