Plataforma de telefonía de Google

En esta guía, se explica el proceso de creación y configuración de un nuevo número de teléfono de la Plataforma de telefonía de Google (GTP) para tu aplicación de agente. Esta función lista para usar te permite adjuntar un número de teléfono nuevo a tu agente que puede controlar el tráfico entrante en solo unos minutos.

Si quieres usar un número de teléfono preexistente, puedes configurar tu sistema de control de borde de sesión (SBC) para que redireccione automáticamente el número existente al nuevo número de GTP o a un número de teléfono virtual a través de un enlace troncal SIP. Para obtener instrucciones detalladas sobre la integración y la configuración de SBC, consulta la documentación de telefonía de Dialogflow CX.

Antes de comenzar

1. Sigue los pasos de la página Configuración y limpieza para crear o configurar el proyecto que deseas usar para la implementación.
2. Crea y configura una aplicación de agente para usarla en la implementación.
3. Habilita la API de Dialogflow en el proyecto.

Limitaciones

Se aplica la siguiente limitación:

• Los números de teléfono estándar de la red telefónica conmutada (PSTN) son compatibles con la multirregión us. Para la multirregión eu, puedes usar números de teléfono virtuales.
• No se puede marcar directamente a los números de teléfono virtuales desde teléfonos PSTN estándar, pero puedes enrutarles llamadas desde tu SBC a través de un enlace troncal SIP o probarlos en el widget de WebRTC.

Conecta una aplicación de agente a un número de teléfono de GTP

1. Abre la consola de CX Agent Studio y selecciona tu aplicación de agente.
2. En la parte superior de la consola, haz clic en la pestaña Implementar y, luego, en Conectarse a una plataforma. Si ya tienes canales implementados, haz clic en +Canal nuevo.
3. Ingresa un Nombre para el canal y selecciona Plataforma de telefonía de Google (GTP) en el menú Plataforma.
4. La opción predeterminada es aprovisionar un número de teléfono virtual para probar tu aplicación de agente en el navegador o enrutar las llamadas entrantes desde un SBC a través de un enlace troncal SIP. Para aprovisionar un número de teléfono estándar de PSTN (red telefónica conmutada), selecciona esa opción en el menú desplegable Connection type.
5. Selecciona una Versión para la implementación. Si no tienes versiones preexistentes, crea una nueva.
6. (Opcional) Haz clic en el botón de activación Comportamiento específico del canal para configurar opciones adicionales. Puedes cambiar la longitud de la respuesta del agente, habilitar la entrada de DTMF y permitir que los usuarios interrumpan al agente a mitad de la respuesta. Para obtener más información sobre estos parámetros de configuración, consulta la documentación de configuración de la aplicación del agente.
7. Haz clic en Crear canal. Ahora puedes ver el número de teléfono y el ID de implementación del canal.

8. Si aprovisionaste un número de teléfono de PSTN, llámalo para probar que se conecte a tu aplicación de agente y, luego, haz clic en Listo. El canal nuevo aparece en la página Canales implementados de la aplicación del agente. Ahora puedes usar este número para que los clientes llamen a tu agente. Si aprovisionaste un número de teléfono virtual, puedes probarlo en el widget de WebRTC o conectarlo a un SBC a través de un enlace troncal SIP.

   Nota: Los números de teléfono virtuales no se pueden marcar directamente desde teléfonos PSTN estándar. Para enrutar las llamadas de la RTC a un número de teléfono virtual, reenvía las llamadas desde tu SBC a través de un enlace troncal SIP.

Prueba la aplicación del agente en el widget de WebRTC

Ya sea que hayas aprovisionado una PSTN estándar o un número de teléfono virtual, puedes probar tu aplicación de agente en el widget de WebRTC con audio, video o texto.

1. En la parte superior de la consola, haz clic en la pestaña Implementar.
2. Haz clic en el ícono junto al nombre del canal implementado. Se abrirá un widget de WebRTC a la derecha.
3. Si el widget de WebRTC lo solicita, otorga permiso al navegador para acceder al micrófono y a la cámara.
4. Interactúa con tu agente a través de audio, video o texto. Cuando uses video, también puedes cambiar a compartir pantalla con el menú desplegable junto al ícono de la cámara.

Conecta un número de teléfono virtual a un SBC a través de un enlace troncal SIP

Puedes enrutar las llamadas entrantes de RTC o VoIP desde tu propio controlador de borde de sesión (SBC) o proveedor a un número de teléfono virtual de CX Agent Studio a través de un enlace troncal SIP seguro. Los números de teléfono virtuales son identificadores independientes del país (con el prefijo +0 seguido de 32 caracteres hexadecimales) que te permiten conservar tus números de teléfono de operador existentes en cualquier país y desviar las llamadas entrantes a tu agente.

Requisitos previos para la conectividad de enlace troncal SIP

Antes de enviar tráfico SIP desde tu SBC a un número de teléfono virtual, completa la configuración del enlace troncal SIP y la configuración del SBC estándar de Dialogflow CX.

Asigna un formato al URI de SIP para un número de teléfono virtual

Debido a que los números de teléfono virtuales (+0...) no son números E.164 de RTC, la plataforma de telefonía de Google los enruta según el dominio SIP en el URI de solicitud INVITE y el encabezado To.

Asigna el formato al URI de SIP de destino tanto en el URI de solicitud INVITE como en el encabezado To de la siguiente manera:

sip:[e-mail]:5672;transport=tls

Reemplaza lo siguiente:

• VIRTUAL_NUMBER: Es el número de teléfono virtual completo de 34 caracteres copiado de la consola, que comienza con +0 seguido de 32 caracteres hexadecimales en mayúscula y sin espacios (por ejemplo, +01BCE14D51A354F8E84E142E7E1E3B4E5).
• LOCATION: Es el ID de ubicación de Google Cloud en el que se crearon el canal de implementación de GTP y el número de teléfono virtual (por ejemplo, us, eu).

Ubicación Google Cloud del canal	Dominio de SIP (ccai.prod-LOCATION.telephony.goog)	Ejemplo de URI de SIP
global	ccai.prod-global.telephony.goog	sip:[e-mail]
us	ccai.prod-us.telephony.goog	sip:[e-mail]
eu	ccai.prod-eu.telephony.goog	sip:[e-mail]
Otra región admitida (REGION)	ccai.prod-REGION.telephony.goog	sip:[e-mail]

Ejemplo de SIP INVITE para un número de teléfono virtual

En el siguiente ejemplo, se muestra un SIP INVITE válido enviado a través de mTLS a us.telephony.goog:5672 (74.125.88.132:5672) que se orienta al número de teléfono virtual +01BCE14D51A354F8E84E142E7E1E3B4E5 en la ubicación us:

INVITE sip:[e-mail]:5672;transport=tls SIP/2.0
Via: SIP/2.0/TLS sbc.example.com:5672;branch=z9hG4bK74bf9;rport
Max-Forwards: 70
From: "Caller" <sip:[e-mail]>;tag=9fxced76sl
To: <sip:[e-mail]:5672;transport=tls>
Call-ID: [e-mail]
CSeq: 1 INVITE
Contact: <sip:[e-mail]:5672;transport=tls>
Content-Type: application/sdp
Content-Length: ...

Configura el comportamiento de la aplicación del agente

Puedes personalizar el comportamiento de tu agente en relación con la finalización y la transferencia de llamadas.

Nota: Desde el 1 de agosto de 2026, los siguientes parámetros se cambiaron de TODO_EN_MAYÚSCULAS a camelCase (ambos se admiten por retrocompatibilidad):

• PHONE_GATEWAY_TRANSFER ahora es telephonyTransferCall (y sus claves anidadas: phone_number -> phoneNumber, use_originating_trunk -> useOriginatingTrunk)
• LIVE_AGENT_HANDOFF ahora es liveAgentHandoff (y sus claves anidadas: sip-refer -> sipRefer, uui-headers -> uuiHeaders, x-headers -> xHeaders)
• TELEPHONY_PAYLOAD es ahora telephonyPayload
• ESCALATION_MESSAGE es ahora escalationMessage

Configura la finalización de llamadas del agente

Para permitir que el agente finalice una llamada, haz lo siguiente:

1. Haz clic en el símbolo de signo más en la parte superior derecha del agente y, luego, en Agregar herramientas.
2. Agrega la herramienta end_session al agente (y a todos los agentes secundarios, si los hay). Esta herramienta del sistema está disponible automáticamente para todos los agentes de forma predeterminada.
3. Agrega una descripción del comportamiento de finalización de llamadas a las instrucciones. Por ejemplo: End the call by executing the end_session tool with arguments reason="customer_query_ended"..

Transfiere una llamada a un agente humano

Para configurar el agente de modo que transfiera la llamada a un agente humano y finalice el tramo de la llamada del agente virtual, haz lo siguiente:

• Agrega la herramienta del sistema end_session al agente (y a todos los agentes secundarios, si están presentes).
• Crea las siguientes variables:
  • escalationMessage: De manera opcional, agrega texto al campo Valor predeterminado si quieres que el agente diga un mensaje antes de transferir la llamada.
  • telephonyTransferCall: Establece el Tipo en Esquema personalizado. Ingresa el siguiente objeto JSON en el cuadro de entrada Esquema con el número de teléfono al que deseas que el agente transfiera las llamadas (se requiere el formato E.164).

{
  "phoneNumber": "+PHONE_NUMBER"
}

• Agrega una descripción de este comportamiento a tus instrucciones. Por ejemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Transferencia a un agente humano compatible con socios

Si tu sistema incorpora un socio que no es de Google, hay dos opciones disponibles para la transferencia a un agente humano: una variable liveAgentHandoff o una variable telephonyPayload. En ambos casos, la carga útil de JSON puede variar según las instrucciones del socio.

Transferencia a un agente humano:

• Agrega la herramienta del sistema end_session al agente (y a todos los agentes secundarios, si están presentes).
• Crea la siguiente variable:
  • liveAgentHandoff: Establece el Tipo en Esquema personalizado y agrega el esquema JSON que requiere el socio, por ejemplo:

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

• Agrega una descripción de este comportamiento a tus instrucciones. Por ejemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Transferencia de agente humano con carga útil personalizada:

• Agrega la herramienta del sistema end_session al agente (y a todos los agentes secundarios, si están presentes).
• Crea la siguiente variable:
  • telephonyPayload: Establece el Tipo en Esquema personalizado y agrega el esquema JSON que requiere el socio, por ejemplo:

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

• Agrega una descripción de este comportamiento a tus instrucciones. Por ejemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Usar la señalización de SIP para pasar datos hacia y desde el agente

Si realizaste una integración de SBC, puedes usar la señalización de SIP para pasar datos al agente con encabezados de SIP. También puedes pasar datos cuando el agente activa un BYE, REFER o INVITE.

Se puede acceder a todos los datos que se pasan al agente con variables. Primero, debes crear las variables para acceder a los datos.

El número de teléfono de la persona que llama (ANI) se almacena en la variable telephony-caller-id de tipo Text.

Si el agente debe decir un mensaje antes de realizar una derivación, el mensaje debe almacenarse en la variable escalationMessage de tipo Text.

Para realizar un SIP REFER o un SIP INVITE, la variable telephonyTransferCall de tipo Custom schema (advanced) debe existir con las variables phoneNumber y useOriginatingTrunk especificadas.

Todos los datos que se deben pasar deben estar presentes en la variable liveAgentHandoff de tipo Custom schema (advanced).

Encabezado SIP de UUI

Puedes pasar una lista de pares clave-valor separados por punto y coma que esté codificada en formato hexadecimal, seguida de ;encoding=hex;purpose=Goog-Session-Param. Para acceder a esto dentro del agente, crea una variable con el nombre uui-headers y el tipo List.

Por ejemplo, si se debe pasar la cadena key1=value1;key2=value2, se debe enviar el siguiente encabezado de UUI, en el que la carga útil es el valor codificado en hexadecimal key1=value1;key2=value2.

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

La variable uui-headers contendrá el siguiente objeto:

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

Para pasar uuiHeaders cuando llames a la herramienta end_session, especifica params={"liveAgentHandoff": {"uuiHeaders": [ {uui-headers}[0] ]}}.

Por ejemplo, si los encabezados de UUI que se pasaron se tuvieran que pasar en un SIP BYE, tendrías una instrucción similar a la siguiente:

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={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"uuiHeaders": [ {uui-headers}[0] ]}}.

Encabezados X de SIP

Los encabezados SIP que comienzan con x- se pueden pasar al agente y guardar como una variable x-headers y un tipo Custom schema (advanced). El prefijo x- se quita del nombre del encabezado en la variable.

Por ejemplo, si el INVITE de SIP contiene el siguiente encabezado:

x-billing-id: 12345

La variable x-headers contendrá el siguiente objeto:

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

Para pasar xHeaders, cuando llames a la herramienta end_session, especifica params={"liveAgentHandoff": {"xHeaders": {x-headers} }}.

Por ejemplo, si los encabezados X que se pasaron debían pasarse en un SIP BYE, tendrías una instrucción similar a la siguiente:

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={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers} }}.

Nota: La plataforma de telefonía receptora debe esperar una x- en minúscula, no una X- en mayúscula.

Envía un mensaje BYE de SIP

Cuando el agente finaliza la llamada, se envía un mensaje SIP BYE. Para enviar uuiHeaders y xHeaders en el SIP BYE, usa una instrucción similar al siguiente ejemplo:

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={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Envía un SIP REFER

Si el agente necesita derivar la llamada a un agente humano y abandonarla, se debe usar un SIP REFER. Se activa un SIP REFER especificando "sipRefer": true en la variable liveAgentHandoff, y el número refer-to se debe proporcionar en la variable telephonyTransferCall. Un ejemplo de instrucción para realizar un SIP REFER y pasar el uuiHeaders y el 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={"escalationMessage": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "[phone]", "useOriginatingTrunk": true}, "liveAgentHandoff":{"sipRefer": true, "xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Envía un mensaje INVITE de SIP

Si el agente necesita derivar la llamada a un agente humano y permanecer en ella para que se puedan usar las funciones de Agent Assist, se debe usar un SIP INVITE. El phoneNumber activa un SIP INVITE en la variable telephonyTransferCall. Este es un ejemplo de instrucción para realizar una INVITE de SIP y pasar el uuiHeaders y el 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={"escalationMessage": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "[phone]", "useOriginatingTrunk": true}, "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Crea un controlador para las desconexiones de llamadas remotas

Cuando un cliente cuelga la llamada, se activa un evento específico, sys.remote-call-disconnected, que se puede usar para activar una llamada a una herramienta en CX Agent Studio. En el siguiente ejemplo, se llama a la herramienta sum cuando el cliente cuelga la llamada.

La herramienta sum se define como una herramienta de código de Python y contiene el siguiente código:

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

En el agente raíz, crea una devolución de llamada Before LLM con la lógica para detectar el evento de desconexión de la llamada. En LlmResponse, realiza la llamada a la herramienta sum y, luego, llama a la herramienta 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