Google Telephony Platform

This guide walks you through the process of creating and configuring a new Google Telephony Platform (GTP) phone number for your agent application. This out-of-the-box feature lets you attach a new phone number to your agent that can handle incoming traffic in only a few minutes.

If you want to use a pre-existing phone number, you can configure your Session Border Control (SBC) system to automatically redirect the existing number to the new GTP number. For detailed instructions on SBC integration and setup, see the Dialogflow CX telephony documentation.

Before you begin

Follow the steps on the setup and cleanup page to create or configure the project you'd like to use for the deployment.
Create and configure an agent application to use in the deployment.
Enable the Dialogflow API in the project.

Limitations

The following limitations apply:

Standard PSTN (Public Switched Telephone Network) phone numbers are supported for the us multi-region. For eu multi-region, you can use virtual phone numbers.
Only US phone numbers are supported in the us multi-region.
Virtual phone numbers can't be dialed from standard PSTN phones.

Connect an agent application to a GTP phone number

Open the CX Agent Studio console and select your agent application.
At the top of the console, click the Deploy tab followed by Connect to a platform. If you already have deployed channels, click +New channel.
Enter a Name for the channel and select Google Telephony Platform (GTP) from the Platform menu.
The default option is to provision a virtual phone number for testing your agent application in the browser. To provision a standard PSTN (Public Switched Telephone Network) phone number, select that option from the Connection type drop-down.
Select a Version for deployment. If you don't have pre-existing versions, create a new one.
(Optional) Click the Channel-specific behavior toggle to configure additional options. You can change the agent response length, enable DTMF input, and allow users to interrupt the agent mid-response. For more information about these settings, see the agent application settings documentation.
Click Create channel. You can now see the phone number and deployment ID for the channel.
If you provisioned a PSTN phone number, call it to test that it connects to your agent application, then click Done. The new channel appears on the agent application's Deployed channels page. You can now use this number to have customers call your agent. If you provisioned a virtual phone number, you can test it in the WebRTC widget.

Note: Virtual phone numbers can't be dialed from standard PSTN phones.

Test agent application in WebRTC widget

Whether you provisioned a standard PSTN or a virtual phone number, you can test your agent application in the WebRTC widget by using audio, video, or text.

At the top of the console, click the Deploy tab.
Click the icon next to the deployed channel name. A WebRTC widget will open on the right.
If prompted by the WebRTC widget, grant the browser permission to access your microphone and camera.
Interact with your agent through audio, video, or text. When using video, you can also switch to screen sharing by using the drop-down menu next to the camera icon.

Configure agent application behavior

You can customize your agent's behavior around ending and transferring calls.

Configure agent call termination

To allow the agent to terminate a call:

Click the plus symbol at the top right of the agent and click Add tools.
Add the end_session tool to the agent (and all sub-agents, if present). This system tool is automatically available to every agent by default.
Add a description of call termination behavior to the instructions. For example: End the call by executing the end_session tool with arguments reason="customer_query_ended".

Transfer a call to a human agent

To configure the agent to transfer the call to a human agent and end the virtual agent leg of the call:

Add the end_session system tool to the agent (and all sub-agents, if present).
Create the following variables:
- ESCALATION_MESSAGE: Optionally, add text to the Default value field if you would like the agent to say a message before transferring the call.
- telephonyTransferCall: Set the Type to Custom schema. Enter the following JSON object in the Schema input box with the phone number you want the agent to transfer calls to (E.164 format required).

{
  "phoneNumber": "+PHONE_NUMBER"
}

Add a description of this behavior to your instructions. For example: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Partner-supported human agent transfer

If your system incorporates a non-Google partner there are two available options for human agent transfer: A liveAgentHandoff variable or a TELEPHONY_PAYLOAD variable. In both cases, the JSON payload might vary depending on the partner's instructions.

Live agent handoff human agent transfer:

Add the end_session system tool to the agent (and all sub-agents, if present).
Create the following variable:
- liveAgentHandoff: Set the Type to Custom schema and add the partner-required JSON schema, for example:

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

Add a description of this behavior to your instructions. For example: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Custom payload human agent transfer:

Add the end_session system tool to the agent (and all sub-agents, if present).
Create the following variable:
- TELEPHONY_PAYLOAD: Set the Type to Custom schema and add the partner-required JSON schema, for example:

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

Add a description of this behavior to your instructions. For example: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Use SIP signaling to pass data to and from the agent

If you have done an SBC integration, you can use SIP signaling to pass data to the agent using SIP headers. You can also pass data out when a BYE, REFER or INVITE is triggered by the agent.

All data passed into the agent is accessible using variables. You must first create the variables in order to access the data.

The caller's phone number (ANI) is stored in the variable telephony-caller-id of type Text.

If the agent should say a message before doing an escalation, the message should be stored in the variable ESCALATION_MESSAGE of type Text.

To do a SIP REFER or SIP INVITE, the variable telephonyTransferCall of type Custom schema (advanced) should exist with variables phoneNumber and useOriginatingTrunk specified.

Any data that needs to be passed out should be present in the variable liveAgentHandoff of type Custom schema (advanced).

UUI SIP header

You can pass in a semicolon-separated list of key value pairs that is hex encoded, followed by ;encoding=hex;purpose=Goog-Session-Param. To access this within the agent, create a variable with the name uui-headers and type List.

For example, if the string key1=value1;key2=value2 needs to be passed in, the following UUI header should be sent, where the payload is the hex-encoded value key1=value1;key2=value2.

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

The variable uui-headers will contain the following object:

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

To pass uuiHeaders out when calling the end_session tool, specify params={"liveAgentHandoff": {"uuiHeaders": [ {uui-headers}[0] ]}}

For example, if the UUI headers passed in had to be passed out upon a SIP BYE, you would have an instruction similar to the following:

SIP x-headers

SIP headers starting with x- can be passed to the agent and saved as a variable x-headers and type Custom schema (advanced). The x- prefix is removed from the header name in the variable.

For example, if the SIP INVITE contains the following header:

x-billing-id: 12345

The variable x-headers will contain the following object:

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

To pass xHeaders out, when calling the end_session tool, specify params={"liveAgentHandoff": {"xHeaders": {x-headers} }}

For example, if the x-headers passed in had to be passed out upon a SIP BYE, you would have an instruction similar to the following:

Send a SIP BYE

When the agent ends the call, a SIP BYE is sent. To send uuiHeaders and xHeaders in the SIP BYE, use an instruction similar to the following example:

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]}] }}.

Send a SIP REFER

If the agent needs to escalate the call to a human agent and drop off the call, a SIP REFER should be used. A SIP REFER is triggered by specifying "sipRefer": true in the liveAgentHandoff variable and the refer-to number should be provided in the telephonyTransferCall variable. An example instruction to do a SIP REFER and pass out the uuiHeaders and 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": "+19496855555", "useOriginatingTrunk": true}, "liveAgentHandoff":{"sipRefer": true, "xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Send a SIP INVITE

If the agent needs to escalate the call to a human agent and stay on the call so that Agent Assist features can be used, a SIP INVITE should be used. A SIP INVITE is triggered by the phoneNumber in the telephonyTransferCall variable. An example instruction to do a SIP INVITE and pass out the uuiHeaders and 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": "+19496855555", "useOriginatingTrunk": true}, "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Create a handler for remote call disconnects

When a customer hangs up the call, it triggers a specific event, sys.remote-call-disconnected, that can be used to trigger a tool call within CX Agent Studio. In the following example, the tool sum is called when the customer hangs up the call.

The tool sum is defined as a Python code tool and contains the code:

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

In the root agent, create a Before LLM callback with the logic to watch for the call disconnect event. In the LlmResponse make the sum tool call and then call the end_session tool.

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