Conceptos y solución de problemas

En esta página se detallan las configuraciones específicas necesarias para la integración, así como la solución de problemas habituales.

Requisitos de red telefónica

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

Para la señalización SIP, se debe permitir todo el intervalo de IPs 74.125.88.128/25 (TCP) en el puerto 5672. Para definir un conjunto de reglas de cortafuegos más restrictivo, puedes limitar la señalización SIP a uno o varios servidores SIP 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 Asia-Pacífico: ap.telephony.goog (74.125.88.134)
• Región de Sudamérica: sa.telephony.goog (74.125.88.135)

En el caso de los medios RTP, debes configurar reglas de cortafuegos para permitir el tráfico destinado al intervalo de IP CIDR 74.125.39.0/24. Normalmente, los puertos necesarios para los archivos multimedia son solo del 16384 al 32767 (TCP y UDP). Sin embargo, este intervalo de puertos puede ampliarse en el futuro.

Proveedores o modelos de SBC compatibles

En la siguiente tabla se indican los proveedores o modelos de SBC y las versiones de firmware compatibles. Las instrucciones de integración detalladas de cada proveedor se vinculan en la versión de firmware.

Protocolos de señalización y multimedia de SBC admitidos

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 configurado como true. El ID de conversación debe generarse de forma dinámica durante el SIP INVITE mediante el valor del encabezado SIP de Call-Info o UUI.

El valor del encabezado SIP apunta al endpoint de Dialogflow definiendo el ID del proyectoGoogle Cloud y el ID de conversación:

1. El ID de proyecto es el que usaste cuando configuraste un Google Cloud proyecto. Google Cloud
2. El ID de conversación debe generarlo dinámicamente el SBC. El ID de conversación debe cumplir la fórmula de expresión regular [a-zA-Z][a-zA-Z0-9_-]* y tener una longitud de entre [3,64] caracteres. Para generar dinámicamente el ID de conversación, se suele usar el valor Call-ID en la invitación SIP y prefijarlo con letras para que cumpla la expresión regular especificada anteriormente. Por ejemplo, si el valor de Call-ID es 297363723_79131759_799783510, al añadirle el prefijo "CID-", se ajustará a la expresión regular [a-zA-Z][a-zA-Z0-9_-]*.

Call-Info Encabezado de SIP

Inserta un encabezado SIP personalizado llamado Call-Info en el SIP INVITE para definir 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

UUI Encabezado de SIP

Si no se admite la configuración del encabezado SIP personalizado Call-Info, puedes configurar el encabezado SIP UUI (de usuario a usuario) en la invitación SIP para incluir el ID de conversación.

Use los mismos datos solicitados en Call-Info con la URL codificada en hexadecimal y el valor Goog-ContactCenter-Conversation en el campo "purpose". A continuación, se muestra un ejemplo de encabezado, donde la cadena hexadecimal decodificada 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

Si necesita enviar datos adicionales al agente conversacional y definirlos como parámetro de sesión, puede hacerlo enviando una lista de pares clave-valor separados por punto y coma que esté codificada en hexadecimal, seguida de ;encoding=hex;purpose=Goog-Session-Param. De este modo, se creará un parámetro de sesión con el nombre uui-headers que contendrá una lista de cadenas de carga útil decodificadas.

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

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

Esto daría lugar a la creación del siguiente parámetro de sesión.

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

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

El siguiente fragmento toma el valor del parámetro y, a continuación, divide el parámetro 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 que se llama desde un activador en los bloques de código del manual, por ejemplo: @PlaybookStartHandler, que se llama al entrar en 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 ""

Se pueden enviar datos adicionales mediante encabezados UUI independientes con diferentes valores de "purpose" (finalidad). Estos valores se añaden al objeto Conversation.telephonyConnectionInfo. Ten en cuenta que estos datos no están disponibles para el agente de Conversational Agents (Dialogflow CX) en tiempo de ejecución.

Enviar información del agente humano

Si necesitas transferir información específica a agentes humanos, puedes definir el atributo de etiqueta de medio del protocolo de descripción de sesión (SDP) para el flujo del protocolo de transporte en tiempo real (RTP) del agente humano con el valor de datos necesario. Ejemplo: none a=label:7382373482 Estos datos se incluirán en el campo sip_recording_media_label y estará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 Message.attributes de Pub/Sub.

Configurar los roles de los participantes y el orden de los flujos multimedia

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

Si necesitas un comportamiento diferente (por ejemplo, en un sistema de llamadas salientes), la URL que se transfiera en el encabezado debe tener el parámetro roles añadido.

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

La URL especifica que el primer flujo multimedia debe tener el rol HUMAN_AGENT y el segundo, el rol END_USER. Puedes aplicar el parámetro roles con el encabezado SIP Call-Info o UUI.

Definir parámetros adicionales en una conversación determinada

Para definir parámetros adicionales en una conversación determinada, usa la llamada a MatchIntentRequest RPC. Puede asignar a query_params.parameters los pares clave-valor necesarios y a query_input.text un valor como "Setting parameters" (Definir parámetros).

Haz la llamada a la API después de la respuesta 200 OK de la invitación SIP inicial, momento en el que se habrá creado la conversación. El ID de sesión de MatchIntentRequest es el mismo ID de conversación que se proporciona en el encabezado Call-Info del mensaje INVITE.

Usar SIP REFER para transferir una llamada a un endpoint SIP

Para transferir una llamada de un agente virtual a un endpoint SIP, usa el método SIP REFER. Incluye una carga útil en el campo Live agent handoff y asigna al campo Telephony transfer call el número que se haya definido en el campo SIP REFER Refer-To de salida. La carga útil debería tener un aspecto similar al del siguiente código de ejemplo.

{
    "sip-refer": true
}

Si es necesario transferir datos fuera de los agentes conversacionales (Dialogflow CX), se pueden usar encabezados de UUI para transferir cadenas de datos. Si quieres hacer una SIP REFER y distribuir dos pares clave-valor, puedes usar una carga útil similar al siguiente ejemplo de código.

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

Se generaría un SIP REFER con el siguiente encabezado UUI.

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

Transferir datos en un mensaje BYE de SIP

Si se desplaza a End Session, se activará un mensaje BYE de SIP. Si quieres enviar datos desde Conversational Agents (Dialogflow CX), puedes usar encabezados UUI para enviar cadenas de datos. Debería dirigir la llamada a una página que definiera la carga útil Live agent handoff de forma similar al siguiente fragmento de código antes de pasar a End Session.

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

Se generaría un mensaje SIP BYE con el siguiente encabezado UUI.

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

Activar una acción cuando la persona que llama de forma remota cuelga

La nueva API BiDi (use_bidi_streaming=True en ConversationProfile) permite activar una llamada a herramienta en un libro de jugadas o una llamada a webhook en un flujo cuando el interlocutor remoto cuelga.

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

Solución de problemas

El equipo de Google puede pedirte que proporciones los siguientes elementos para ayudar a solucionar los problemas del ping de OPTIONS de SIP y de las llamadas de prueba realizadas:

1. Captura de paquetes de red
2. Registro 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 debería mostrar lo siguiente:

1. Un handshake TCP completo de tres vías (SYN, SYN-ACK y ACK) entre tu SBC y los servidores SIP de GTP a través del puerto TCP 5672. Si no se ha podido establecer la conexión TCP, los posibles problemas son 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 los requisitos de red para la conectividad telefónica.
   • La comunicación no se envía a través del puerto TCP 5672.

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

   • TLS v1.2 o una versión posterior iniciada por tu SBC.
   • Tu SBC inicia un "Client Hello" y GTP responde con "Server Hello".
   • Proceso de autenticación TLS mutua.
     • GTP responde con su propio certificado TLS de servidor, que autentica tu SBC.
     • El SBC envía su propio certificado de cliente TLS, que se autentica mediante GTP.
   • Se ha establecido un canal cifrado, como se indica en "Mensaje de handshake cifrado".
   • Pruebas de que se han transmitido "datos de aplicación" a través del canal TLS.

   Si no se ha podido establecer la conexión TLS, los posibles problemas son los siguientes:

   • No se ha creado ningún troncal SIP en el lado de GTP.
   • El FQDN configurado del tronco SIP no coincide con el FQDN presentado en el certificado TLS (atributo CN o SAN) del SBC.
   • No se admite la versión de TLS. Solo se admiten las versiones 1.2 o posteriores de TLS.
   • El paquete de cifrado solicitado no es compatible. Consulta la configuración de TLS de SBC.
   • Proveedores de certificados TLS no fiables. Consulta Configuración de TLS de SBC.

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

   • Encabezado de SIP Call-Info del cliente insertado en este formato: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

     Ejemplo: none 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 (+16501234567).

   • Los encabezados SIP muestran las direcciones IP públicas que se usan en el URI de la solicitud y en otros campos de encabezado SIP (por ejemplo, Para, De y Vía). Se rechazarían las direcciones IP privadas.

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

   • Asegúrate de que la priorización de los medios envíe primero el flujo del usuario final y, después, el flujo de medios del agente humano, ya que GTP trata el primer flujo de medios como el del usuario final de forma predeterminada.

   Si recibes un código de respuesta de error de SIP:

   • El código de respuesta de error 400 de SIP (por ejemplo, 488 Not Acceptable Here) probablemente indica que GTP ha rechazado un encabezado SIP o una configuración SDP de medios SIP.
   • Es probable que un código de respuesta de error SIP 600 (error 603 Rechazado de SIP) indique un problema relacionado con la cuota. Consulta la página Cuotas y límites para obtener información sobre cómo solicitar un aumento.