Conceptos y solución de problemas

En este documento, se detallan los parámetros de configuración específicos que necesitas para la integración, así como la solución de problemas comunes.

Requisitos de la red de telefonía

Si tu red filtra el tráfico saliente, debes permitir el tráfico saliente para la señalización de SIP y la transmisión de contenido multimedia.

Para la señalización de SIP, debes permitir todo el rango de IP 74.125.88.128/25 (TCP) en el puerto 5672. Para un conjunto de reglas de firewall más restrictivo, puedes restringir la señalización de SIP a uno de los siguientes servidores de SIP de GTP regionalizados:

• Región de EE.UU.: us.telephony.goog (74.125.88.132)
• Región de la UE: eu.telephony.goog (74.125.88.133)
• Región de APAC: ap.telephony.goog (74.125.88.134)
• Región de Sudamérica: sa.telephony.goog (74.125.88.135)

Para el contenido multimedia de RTP, debes configurar reglas de firewall que permitan el tráfico destinado al rango de IP de CIDR 74.125.39.0/24. Los puertos necesarios para el contenido multimedia suelen ser solo 16384-32767 (TCP+UDP), pero este rango de puertos se puede expandir en el futuro.

Proveedores o modelos de SBC compatibles

En la siguiente tabla, se enumeran los proveedores o modelos de SBC y las versiones de firmware compatibles. Puedes encontrar instrucciones de integración detalladas para cada proveedor vinculado en la versión de firmware.

Proveedores y modelos	Versiones de firmware (SIPREC, SIP)
AudioCodes VE SBC	v7.60A.100.022 (SIPREC, SIP)
Avaya Session Border Controller for Enterprise	v10.2.1.1-104-25336 (SIPREC, SIP)
Oracle E-SBC Acme Packet 4600	SCZ9.3.0 GA (compilación 46) (SIPREC, SIP)
Ribbon Swe Core SBC	v12.01.07R000 (SIPREC, SIP)
Cisco Unified Border Element (CUBE)	v17.15.4 (SIPREC, SIP)

Nota: En esta tabla, se muestran las versiones mínimas de firmware compatibles que se certificaron para funcionar con la integración de SIP. También se certifican las versiones de firmware posteriores que forman parte de la misma serie de parches de firmware principales.

Protocolos de señalización y de medios de SBC compatibles

Protocolo	Valor
Protocolo de señalización	SIP por TLS (SRTP)
Medios	SRTP (protocolo seguro de transporte en tiempo real)
Encriptación de medios	SDES (descripciones de seguridad para SDP)
Conjunto de algoritmos de cifrado de contenido multimedia compatible	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Códecs de contenido multimedia compatibles	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

Encabezados SIP

Cuando configuraste un perfil de conversación y un número de teléfono, creaste un perfil de conversación de CCAI con el sipConfig.createConversationOnTheFly establecido en true. Debes generar de forma dinámica el ID de conversación durante el INVITE de SIP con el valor del encabezado SIP de Call-Info o UUI.

El valor del encabezado SIP apunta al extremo de Dialogflow definiendo el Google Cloud ID del proyecto y el ID de la conversación:

1. El ID del proyecto de Google Cloud es el proyecto que usaste cuando configuraste un proyecto de Google Cloud .
2. El SBC debe generar de forma dinámica el ID de conversación. El ID de conversación debe cumplir con la fórmula de expresión regular [a-zA-Z][a-zA-Z0-9_-]* con una longitud de caracteres que varía de 3 a 64. Para generar de forma dinámica el ID de conversación, usa un patrón común en el que tomes el valor de Call-ID en el INVITE de SIP y le agregues un prefijo con letras para que cumpla con la expresión regular especificada anteriormente. Por ejemplo, si el valor de Call-ID es 297363723_79131759_799783510, agregarle el prefijo "CID-" haría que cumpla con la expresión regular [a-zA-Z][a-zA-Z0-9_-]*.

Encabezado SIP de Call-Info

Agrega un encabezado SIP personalizado llamado Call-Info al SIP INVITE para establecer de forma única el ID de conversación:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

Ejemplo:

Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation

Encabezado SIP de UUI

Si no se admite la configuración del encabezado SIP personalizado Call-Info, puedes configurar el encabezado SIP UUI (User-to-User) en el SIP INVITE para pasar el ID de conversación.

Usa los mismos datos solicitados en Call-Info con la URL codificada en formato hexadecimal y el propósito establecido en Goog-ContactCenter-Conversation. El siguiente es un encabezado de ejemplo, en el que la cadena hexadecimal, cuando se decodifica, es http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510:

User-to-User: 687474703a2f2f6469616c6f67666c6f772e676f6f676c65617069732e636f6d2f763262657461312f70726f6a656374732f6763702d70726f6a6563742d69642d31323334352f636f6e766572736174696f6e732f4349442d3239373336333732335f37393133313735395f373939373833353130;encoding=hex;purpose=Goog-ContactCenter-Conversation

Para pasar datos adicionales al agente y establecerlos como un parámetro de sesión, puedes pasar una lista de pares clave-valor codificados en formato hexadecimal separados por punto y coma, seguidos de ;encoding=hex;purpose=Goog-Session-Param. Esto crea un parámetro de sesión llamado uui-headers que contiene una lista de cadenas de carga útil decodificadas.

Por ejemplo, si necesitas pasar la cadena key1=value1;key2=value2, se envía el siguiente encabezado de UUI, en el que la carga útil es el valor codificado en hexadecimal de key1=value1;key2=value2:

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

Esta acción crea el siguiente parámetro de sesión:

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

Si tu SBC admite el envío de varios encabezados de UUI, puedes enviar cadenas de pares clave-valor individuales por encabezado de UUI para que estén disponibles como valores individuales en el parámetro de sesión uui-headers.

En el siguiente fragmento, se toma el valor del parámetro y se divide varias veces para acceder al valor adecuado de la variable key2 en la cadena:

$sys.func.GET($sys.func.SPLIT($sys.func.GET($sys.func.SPLIT($session.params.uui-headers,";"),1),"="),1)

En el siguiente ejemplo, se muestra una función a la que se llama desde un activador en los bloques de código de la guía, por ejemplo, @PlaybookStartHandler, a la que se llama cuando se ingresa a la guía. Otras funciones llaman a esta función para obtener valores del parámetro uui-headers.

def _get_fromuui(attribute):
    try:
        uui_headers_src = history.playbook_input.action_parameters['uui-headers']
        # If uui_headers_src is a string, split by ';'
        if isinstance(uui_headers_src, str):
            headers = uui_headers_src.split(';')
        else:
            # If it's a list, join and split
            headers = ';'.join(uui_headers_src).split(';')
        for header in headers:
            header = header.strip()
            if header.lower().startswith(f"{attribute.lower()}="):
                return header[len(attribute) + 1:]
        return ""
    except Exception:
        return ""

Puedes enviar datos adicionales con encabezados UUI independientes que tengan diferentes valores de propósito. Estos valores se agregan al objeto Conversation.telephonyConnectionInfo. Ten en cuenta que estos datos no están disponibles para el agente de Dialogflow CX durante el tiempo de ejecución.

Encabezados X de SIP

Puedes pasar encabezados SIP que comiencen con x- al agente y establecerlos como un parámetro de sesión. Los encabezados SIP están disponibles en el parámetro de sesión x-headers. El sistema quita el prefijo x- del nombre del encabezado en el parámetro de sesión.

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

x-billing-id: 12345

El parámetro de sesión x-headers contiene lo siguiente:

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

Para acceder al valor, sigue estos pasos:

$session.params.x-headers.billing-id

Pasa información del agente humano

Si necesitas pasar información específica a los agentes humanos, puedes establecer el atributo de etiqueta de medios del Protocolo de descripción de sesión (SDP) para el flujo del Protocolo de transporte en tiempo real (RTP) del agente humano en el valor de datos requerido.

Ejemplo:

a=label:7382373482

Estos datos se propagan en el campo sip_recording_media_label y están disponibles en el tema de Pub/Sub New message notification que contiene las transcripciones. Busca el campo sip_recording_media_label en el mensaje de Pub/Sub Message.attributes.

Precaución: Por motivos de cumplimiento, no pases ningún dato de usuario de PII en los encabezados SIP. Úsalos solo para pasar pares clave-valor que no sean de información de identificación personal.

Configura los roles de los participantes y el orden de las transmisiones de contenido multimedia

De forma predeterminada, el primer flujo de contenido multimedia se asocia con el rol de participante END_USER, y los flujos de contenido multimedia posteriores se asocian con el rol de participante HUMAN_AGENT.

Si necesitas un comportamiento diferente, como para un sistema de llamadas salientes, debes agregar el parámetro de roles a la URL que se pasa en el encabezado.

Ejemplo:

http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510?roles=HUMAN_AGENT,END_USER

La URL especifica que la primera transmisión de contenido multimedia debe tener el rol HUMAN_AGENT y la segunda, el rol END_USER. Puedes aplicar el parámetro de roles con el encabezado SIP Call-Info o UUI.

Establece parámetros adicionales en una conversación determinada

Para establecer parámetros adicionales en una conversación determinada, usa la llamada RPC MatchIntentRequest. Puedes establecer query_params.parameters en los pares clave-valor requeridos y query_input.text en Setting parameters.

Realiza la llamada a la API después de la respuesta 200 OK para el SIP INVITE inicial, momento en el que se creó la conversación. El ID de sesión para MatchIntentRequest es el mismo ID de conversación que se proporciona en el encabezado Call-Info en el INVITE.

Usa SIP REFER para transferir una llamada a un extremo SIP

Para transferir una llamada de un agente virtual a un extremo SIP, usa el método SIP REFER. Incluye una carga útil en el campo Live agent handoff y establece el campo Telephony transfer call en el número que se establece en el campo SIP REFER Refer-To saliente. La carga útil de Live agent handoff es similar al siguiente ejemplo:

{
    "sip-refer": true
}

Si necesitas pasar datos fuera de Dialogflow CX, puedes usar encabezados de UUI y encabezados x para pasar cadenas de datos. Si quieres realizar un SIP REFER y pasar dos pares clave-valor en un encabezado de UUI y dos encabezados X, puedes usar una carga útil de Live agent handoff similar a la siguiente muestra de código:

{
    "sip-refer": true,
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Esto genera un SIP REFER con los siguientes encabezados UUI y x-headers:

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Usa SIP INVITE para realizar una llamada de conferencia con otro extremo SIP

Para realizar una conferencia de una llamada de un cliente final a un agente humano al que se puede acceder con un extremo SIP, usa el método SIP INVITE. Esto mantiene a Google en la ruta de acceso de los medios y te permite usar las funciones de Agent Assist. Establece el campo Telephony transfer call en el número que se establece en el campo SIP INVITE To de salida.

Si necesitas pasar datos fuera de Dialogflow CX, puedes usar encabezados de UUI y encabezados x para pasar cadenas de datos. Si quieres realizar una SIP INVITE y pasar dos pares clave-valor en un encabezado de UUI y dos encabezados X, puedes usar una carga útil de Live agent handoff similar a la siguiente muestra de código:

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Esto genera un mensaje INVITE de SIP con los siguientes encabezados UUI y x:

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Pasa datos en un mensaje BYE de SIP

Navegar a End Session genera un mensaje BYE de SIP. Para pasar datos fuera de Dialogflow CX, puedes usar encabezados de UUI o encabezados X para pasar cadenas de datos. Puedes enrutar la llamada a una página que defina la carga útil de Live agent handoff similar a la siguiente muestra de código antes de realizar la transición a End Session:

{
    "uui-headers": [
        "key1=value1;key2=value2"
    ],
    "x-headers": {
        "header1": "value1",
        "header2": "value2"
    }
}

Esto genera un SIP BYE con los siguientes encabezados UUI y x:

User-to-User: <hex encoded "key1=value1;key2=value2">;encoding=hex;purpose=Goog-Session-Param
x-header1: value1
x-header2: value2

Activa una acción cuando el emisor remoto cuelga

La nueva API de BiDi (use_bidi_streaming=True en el perfil de conversación) admite la activación de una llamada de herramienta dentro de una guía o una llamada de webhook dentro de un flujo cuando la persona que llama de forma remota cuelga.

Cuando la persona que llama de forma remota cuelga y Dialogflow CX recibe un mensaje SIP BYE, se activa sys.remote-call-disconnected. Si creas un controlador con este nombre de evento específico, puedes usarlo para activar una llamada a una herramienta con una guía o una llamada de webhook dentro de un flujo.

Permitir llamadas solo desde el SBC

Para rechazar llamadas de la PSTN y solo conectar las llamadas que se originan en tu SBC, actualiza el objeto PhoneNumber para especificar el mensaje allowedSipTrunks. Si la integración usa un enlace troncal SIP, puedes especificar una lista de IDs de enlaces troncales SIP específicos. Si el mensaje se crea con una lista vacía, se permite cualquier enlace troncal SIP. Si se establece una interconexión privada, proporciona el ID de operador que aprovisionó el equipo de telefonía de Google.

Soluciona problemas

Es posible que el equipo de Google te pida que proporciones los siguientes artefactos para ayudar a solucionar problemas de ping de SIP OPTIONS y llamadas de prueba:

1. Captura de paquetes de red.
2. Seguimiento de depuración de SIP que muestra el encabezado completo y el SDP de SIP:
   • Valor de Call-ID
   • Valor de Call-Info (si existe)

Captura de paquetes de red

La captura de paquetes de red debe mostrar lo siguiente:

1. Un protocolo de enlace TCP de 3 vías completo (SYN, SYN-ACK, ACK) entre tu SBC y los servidores SIP de GTP comunicados a través del puerto TCP 5672. Si no se puede establecer una conexión TCP, los posibles problemas incluyen los siguientes:

   • Tu red está bloqueando el tráfico saliente.
   • La comunicación no se envía a uno de los servidores SIP de GTP regionalizados. Consulta el requisito de red de conectividad de telefonía.
   • La comunicación no se envía a través del puerto TCP 5672.

2. Un protocolo de enlace de conexión TLS completo con lo siguiente:

   • Tu SBC inicia TLS v1.2 o una versión posterior.
   • Tu SBC inicia un "Client Hello" y GTP responde con "Server Hello".
   • Se produce el proceso de autenticación TLS mutua:
     • GTP responde con su propio certificado TLS de servidor, que tu SBC autentica.
     • El SBC envía su propio certificado TLS de cliente, que GTP autentica.
   • Se establece un canal encriptado, como lo demuestra el mensaje "Encrypted Handshake Message" en la captura de paquetes.
   • La evidencia de los "datos de la aplicación" se transmite a través del canal de TLS.

   Si no se puede establecer una conexión TLS, los posibles problemas incluyen los siguientes: - No se creó el enlace troncal SIP en el lado de GTP. - El FQDN configurado del enlace troncal SIP no coincide con el FQDN que se presenta en el certificado TLS (atributo CN o SAN) del SBC. - No se admite la versión de TLS, ya que solo se admiten las versiones 1.2 o posteriores: - No se admite el conjunto de algoritmos de cifrado solicitado. Consulta la configuración de TLS del SBC. - Proveedores de certificados TLS no confiables, consulta la configuración de TLS del SBC.

3. El seguimiento de depuración de SIP debería mostrar lo siguiente:

   • Encabezado SIP Call-Info del cliente insertado en este formato:

     Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation
     

     Ejemplo:

     Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/gcp-project-id-12345/conversations/CID-297363723_79131759_799783510>;purpose=Goog-ContactCenter-Conversation
     

   • Los encabezados SIP muestran el número de teléfono en formato E.164 ([phone]).

   • Los encabezados SIP muestran las direcciones IP públicas que se usan en el URI de solicitud y otros campos de encabezado SIP, como Para, De y Vía. Se rechazan las direcciones IP privadas.

   • La información de conexión del SDP de SIP (c= …) se especifica con una dirección IP pública. Se rechazan las direcciones IP privadas.

   • Envía primero la transmisión del usuario final y, luego, la transmisión de contenido multimedia del agente humano, ya que GTP trata la primera transmisión de contenido multimedia como el usuario final de forma predeterminada.

   Si recibes un código de respuesta de error de SIP, haz lo siguiente:

   • Un error de clase 400 de SIP, por ejemplo, 488 No aceptable aquí, indica que GTP rechazó un encabezado SIP o una configuración de SDP de medios SIP.
   • Un error de clase 600 de SIP, como el error 603 de SIP rechazado, indica un problema relacionado con la cuota. Consulta la página de cuotas y límites para obtener detalles sobre cómo solicitar un aumento.