Google 电话平台

本指南将引导您完成为智能体应用创建和配置新的 Google Telephony Platform (GTP) 手机号码的流程。借助此开箱即用的功能，您只需几分钟即可为代理绑定一个新的手机号码，用于处理来电流量。

如果您想使用现有的手机号码，可以配置会话边界控制 (SBC) 系统，以自动将现有号码重定向到新的 GTP 号码。如需详细了解 SBC 集成和设置，请参阅 Dialogflow CX 电话文档。

准备工作

1. 按照设置和清理页面上的步骤创建或配置您要用于部署的项目。
2. 创建并配置要在部署中使用的代理应用。
3. 在项目中启用 Dialogflow API。

限制

存在以下限制：

• us 多区域支持标准 PSTN（公共交换手机网）手机号码。对于 eu 多区域，您可以使用虚拟手机号码。
• 在 us 多区域中，仅支持美国手机号码。
• 无法通过标准 PSTN 手机拨打虚拟手机号码。

将代理应用连接到 GTP 手机号码

1. 打开 CX Agent Studio 控制台，然后选择您的代理应用。
2. 在控制台顶部，依次点击部署标签页和连接到平台。如果您已部署渠道，请点击 + 新渠道。
3. 为渠道输入名称，然后从平台菜单中选择 Google Telephony Platform (GTP)。
4. 默认选项是在浏览器中为测试代理应用预配虚拟手机号码。如需配置标准 PSTN（公共交换手机网络）手机号码，请从 Connection type 下拉菜单中选择相应选项。
5. 选择要部署的版本。如果您没有预先存在的版本，请创建一个新版本。
6. （可选）点击渠道专用行为切换开关，以配置其他选项。您可以更改代理响应长度、启用 DTMF 输入，并允许用户在代理响应过程中中断代理。如需详细了解这些设置，请参阅代理应用设置文档。
7. 点击创建频道。您现在可以查看频道的手机号码和部署 ID。

8. 如果您已预配 PSTN 手机号码，请拨打该号码以测试它是否连接到您的代理应用，然后点击完成。新渠道会显示在代理应用的已部署的渠道页面上。您现在可以使用此号码让客户致电您的代理。如果您已预配虚拟手机号码，则可以在 WebRTC widget 中对其进行测试。

   注意： 无法通过标准 PSTN 手机拨打虚拟手机号码。

在 WebRTC widget 中测试代理应用

无论您是预配了标准 PSTN 手机号码还是虚拟手机号码，都可以使用音频、视频或文本在 WebRTC widget 中测试代理应用。

1. 点击控制台顶部的部署标签页。
2. 点击已部署的频道名称旁边的 图标。系统会在右侧打开一个 WebRTC widget。
3. 如果 WebRTC widget 提示您授予权限，请向浏览器授予麦克风和摄像头使用权限。
4. 通过音频、视频或文本与代理互动。使用视频时，您还可以使用摄像头图标旁边的下拉菜单切换到屏幕共享。

配置代理应用行为

您可以自定义智能体在结束和转接通话方面的行为。

注意：自 2026 年 7 月 1 日起，以下参数已从全大写切换为驼峰式命名法（为实现向后兼容，这两种命名法均受支持）：

• PHONE_GATEWAY_TRANSFER 现在是 telephonyTransferCall（及其嵌套键：phone_number -> phoneNumber、use_originating_trunk -> useOriginatingTrunk）
• LIVE_AGENT_HANDOFF 现在是 liveAgentHandoff（及其嵌套键：sip-refer -> sipRefer、uui-headers -> uuiHeaders、x-headers -> xHeaders）

配置客服人员通话结束

如需允许代理结束通话，请执行以下操作：

1. 点击代理右上角的加号，然后点击添加工具。
2. 将 end_session 工具添加到智能体（以及所有子智能体，如果有）。 默认情况下，每个代理都可以自动使用此系统工具。
3. 向说明添加了有关通话结束行为的说明。 例如 End the call by executing the end_session tool with arguments reason="customer_query_ended".

将通话转接给人工客服

如需将代理配置为将通话转接给人工客服并结束虚拟客服通话段，请执行以下操作：

• 将 end_session 系统工具添加到智能体（以及所有子智能体，如果有）。
• 创建以下变量：
  • ESCALATION_MESSAGE：您可以选择在默认值字段中添加文本，以便代理在转接通话前说出消息。
  • telephonyTransferCall：将类型设置为自定义架构。在 Schema 输入框中输入以下 JSON 对象，其中包含您希望代理将来电转接到的手机号码（必须采用 E.164 格式）。

{
  "phoneNumber": "+PHONE_NUMBER"
}

• 在说明中添加对该行为的描述。例如：Escalate the call to a human agent by executing the end_session tool with session_escalated=true。

合作伙伴支持的人工客服转移

如果您的系统包含 非 Google 合作伙伴，则有以下两种人工客服转移选项：liveAgentHandoff 变量或 TELEPHONY_PAYLOAD 变量。在这两种情况下，JSON 载荷可能会因合作伙伴的说明而异。

在线客服人员交接（人工客服转移）：

• 将 end_session 系统工具添加到智能体（以及所有子智能体，如果有）。
• 创建以下变量：
  • liveAgentHandoff：将类型设置为自定义架构，并添加合作伙伴所需的 JSON 架构，例如：

{
  "PARTNER_NAME": {
    "type": "action",
    "action": "deflection",
    "deflection_type": "sip",
    "sip_uri": "SIP_URI",
    "sip_refer": true,
    "sip_parameters": {
      "x-header": "value"
    }
  }
}

• 在说明中添加对该行为的描述。例如：Escalate the call to a human agent by executing the end_session tool with session_escalated=true。

自定义载荷人工客服转移：

• 将 end_session 系统工具添加到智能体（以及所有子智能体，如果有）。
• 创建以下变量：
  • TELEPHONY_PAYLOAD：将类型设置为自定义架构，并添加合作伙伴所需的 JSON 架构，例如：

{
  "PARTNER_NAME": {
    "type": "action",
    "action": "deflection",
    "deflection_type": "sip",
    "sip_uri": "SIP_URI",
    "sip_refer": true,
    "sip_parameters": {
      "x-header": "value"
    }
  }
}

• 在说明中添加对该行为的描述。例如：Escalate the call to a human agent by executing the end_session tool with session_escalated=true。

使用 SIP 信令将数据传递给代理和从代理传递数据

如果您已完成 SBC 集成，则可以使用 SIP 信令通过 SIP 标头将数据传递给客服人员。当代理触发 BYE、REFER 或 INVITE 时，您也可以传递数据。

传递给代理的所有数据都可以通过变量进行访问。您必须先创建变量，然后才能访问数据。

主叫方的手机号码 (ANI) 存储在类型为 Text 的变量 telephony-caller-id 中。

如果代理应在升级之前说出一条消息，则该消息应存储在类型为 Text 的变量 ESCALATION_MESSAGE 中。

如需执行 SIP REFER 或 SIP INVITE，应存在类型为 Custom schema (advanced) 的变量 telephonyTransferCall，并指定变量 phoneNumber 和 useOriginatingTrunk。

任何需要传递出的数据都应存在于类型为 Custom schema (advanced) 的变量 liveAgentHandoff 中。

UUI SIP 标头

您可以传入以英文分号分隔的键值对列表（采用十六进制编码），后跟 ;encoding=hex;purpose=Goog-Session-Param。如需在代理中访问此信息，请创建一个名称为 uui-headers 且类型为 List 的变量。

例如，如果需要传入字符串 key1=value1;key2=value2，则应发送以下 UUI 标头，其中载荷为十六进制编码的值 key1=value1;key2=value2。

User-to-User: 6B6579313D76616C7565313B6B6579323D76616C756532;encoding=hex;purpose=Goog-Session-Param

变量 uui-headers 将包含以下对象：

"uui-headers": ["key1=value1;key2=value2"]

如需在调用 end_session 工具时传递 uuiHeaders，请指定 params={"liveAgentHandoff": {"uuiHeaders": [ {uui-headers}[0] ]}}

例如，如果传入的 UUI 标头必须在 SIP BYE 时传出，您将获得类似于以下内容的指令：

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"ESCALATION_MESSAGE": "I am transferring you to an agent", "liveAgentHandoff":{"uuiHeaders": [ {uui-headers}[0] ]}}.

SIP x-headers

以 x- 开头的 SIP 标头可以传递给代理，并保存为变量 x-headers 和类型 Custom schema (advanced)。从变量中的标题名称中移除了 x- 前缀。

例如，如果 SIP INVITE 包含以下标头：

x-billing-id: 12345

变量 x-headers 将包含以下对象：

{
  "x-headers": {
    "billing-id": "12345"
  }
}

如需在调用 end_session 工具时传出 xHeaders，请指定 params={"liveAgentHandoff": {"xHeaders": {x-headers} }}

例如，如果传入的 x-headers 必须在 SIP BYE 时传出，您将获得类似于以下内容的指令：

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"ESCALATION_MESSAGE": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers} }}.

发送 SIP BYE

当代理结束通话时，系统会发送 SIP BYE。如需在 SIP BYE 中发送 uuiHeaders 和 xHeaders，请使用类似于以下示例的指令：

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"ESCALATION_MESSAGE": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

发送 SIP REFER

如果代理需要将通话升级到人工客服并挂断电话，则应使用 SIP REFER。通过在 liveAgentHandoff 变量中指定 "sipRefer": true 来触发 SIP REFER，并且应在 telephonyTransferCall 变量中提供 refer-to 号码。以下是一个执行 SIP REFER 并传递 uuiHeaders 和 xHeaders 的指令示例：

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"ESCALATION_MESSAGE": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "[phone]", "useOriginatingTrunk": true}, "liveAgentHandoff":{"sipRefer": true, "xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

发送 SIP INVITE

如果代理需要将通话升级到人工客服，并保持通话以便使用 Agent Assist 功能，则应使用 SIP INVITE。SIP INVITE 由 telephonyTransferCall 变量中的 phoneNumber 触发。执行 SIP INVITE 并传递 uuiHeaders 和 xHeaders 的指令示例：

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"ESCALATION_MESSAGE": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "[phone]", "useOriginatingTrunk": true}, "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

创建远程通话断开连接的处理脚本

当客户挂断电话时，系统会触发一个特定事件 sys.remote-call-disconnected，该事件可用于在 CX Agent Studio 中触发工具调用。在以下示例中，当客户挂断电话时，系统会调用工具 sum。

工具 sum 定义为 Python 代码工具，包含以下代码：

def sum(x: int, y: int) -> int:
  """
  Computes the sum of two numbers.

  Args:
    x: The first number.
    y: The second number.

  Returns:
    The sum of the two numbers.
  """
  return x+y

在根代理中，创建一个 Before LLM 回调，其中包含用于监听通话断开连接事件的逻辑。在 LlmResponse 中，调用 sum 工具，然后调用 end_session 工具。

def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]:

  for part in callback_context.get_last_user_input():
    if part.text == "<event>sys.remote-call-disconnected</event>":
      return LlmResponse.from_parts(
        [Part.from_function_call('sum', {'x': 1, 'y': 2}),
         Part.from_end_session(reason='sum tool called after caller disconnected')]
      )
  return None