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.

Connect an agent application to a GTP phone number

Open the Gemini Enterprise for CX console and select your agent application.
At the top of the console, click the Deploy tab followed by Connect to a platform.
Enter a Name for the channel, select Google Telephony Platform (GTP) from the Platform menu, and 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.
Call the provided phone number 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.

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.
- PHONE_GATEWAY_TRANSFER: 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).

{
  "phone_number": "+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 LIVE_AGENT_HANDOFF 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:
- LIVE_AGENT_HANDOFF: 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 PHONE_GATEWAY_TRANSFER of type Custom schema (advanced) should exist with variables phone_number and use_originating_trunk specified.

Any data that needs to be passed out should be present in the variable LIVE_AGENT_HANDOFF 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 uui-headers out when calling the end_session tool, specify params={"LIVE_AGENT_HANDOFF": {"uui-headers": [ {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 x-headers out, when calling the end_session tool, specify params={"LIVE_AGENT_HANDOFF": {"x-headers": {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 uui-headers and x-headers 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", "LIVE_AGENT_HANDOFF":{"x-headers": {x-headers}, "uui-headers": [{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 "sip-refer": true in the LIVE_AGENT_HANDOFF variable and the refer-to number should be provided in the PHONE_GATEWAY_TRANSFER variable. An example instruction to do a SIP REFER and pass out the uui-headers and x-headers:

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", "PHONE_GATEWAY_TRANSFER": {"phone_number": "+19496855555", "use_originating_trunk": true}, "LIVE_AGENT_HANDOFF":{"sip-refer": true, "x-headers": {x-headers}, "uui-headers": [{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 phone_number in the PHONE_GATEWAY_TRANSFER variable. An example instruction to do a SIP INVITE and pass out the uui-headers and x-headers:

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", "PHONE_GATEWAY_TRANSFER": {"phone_number": "+19496855555", "use_originating_trunk": true}, "LIVE_AGENT_HANDOFF":{"x-headers": {x-headers}, "uui-headers": [{uui-headers[0]}] }}.

Google Telephony Platform Stay organized with collections Save and categorize content based on your preferences.