Conceitos e solução de problemas

Nesta página, detalhamos as configurações específicas necessárias para a integração, além da solução de problemas comuns.

Requisitos de rede de telefonia

Se a rede filtrar o tráfego de saída, ela precisará permitir o tráfego de saída para sinalização SIP e streaming de mídia.

Para sinalização SIP, todo o intervalo de IP 74.125.88.128/25 (TCP) na porta 5672 precisa ser permitido. Para um conjunto de regras de firewall mais restritivo, é possível restringir a sinalização SIP a apenas um ou mais servidores SIP GTP regionalizados:

• Região dos EUA: us.telephony.goog (74.125.88.132)
• Região da UE: eu.telephony.goog (74.125.88.133)
• Região da APAC: ap.telephony.goog (74.125.88.134)
• Região da América do Sul: sa.telephony.goog (74.125.88.135)

Para mídia RTP, configure regras de firewall para permitir o tráfego destinado ao intervalo de IP CIDR 74.125.39.0/24. Normalmente, as portas necessárias para mídia são apenas 16384-32767 (TCP+UDP). No entanto, esse intervalo pode ser expandido no futuro.

Fornecedores ou modelos de SBC compatíveis

A tabela a seguir lista os fornecedores ou modelos de SBC e as versões de firmware compatíveis. Instruções detalhadas de integração para cada fornecedor estão vinculadas na versão do firmware.

Fornecedores e modelos	Versões de firmware
AudioCodes VE SBC	v7.60A.100.022 (SIPREC, SIP)
Controlador de borda de sessão da Avaya para empresas	v10.2.1.1-104-25336 (SIPREC, SIP)
Oracle E-SBC Acme Packet 4600	SCZ9.3.0 GA (Build 46) (SIPREC, SIP)
Ribbon Swe Core SBC	v11.01.01R005
Cisco Unified Border Element (CUBE)	v17.15.4 (SIPREC, SIP)

Observação: esta tabela representa as versões mínimas de firmware compatíveis que foram certificadas para funcionar com a integração de SIP. Versões de firmware mais recentes que fazem parte da mesma série de patches de firmware principal também são certificadas.

Protocolos de mídia e sinalização SBC compatíveis

Protocolo de sinalização	SIP por TLS
Mídia	SRTP
Criptografia de mídia	SDES
Pacote de criptografia de mídia compatível	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Codecs de mídia compatíveis	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

Cabeçalhos SIP

Ao configurar um perfil de conversa e um número de telefone, você criou um perfil de conversa da CCAI com o sipConfig.createConversationOnTheFly definido como true. O ID da conversa precisa ser gerado dinamicamente durante o SIP INVITE usando o valor do cabeçalho SIP de Call-Info ou UUI.

O valor do cabeçalho SIP aponta para o endpoint do Dialogflow definindo o ID do projetoGoogle Cloud e o ID da conversa:

1. O ID do projeto Google Cloud é o projeto que você usou ao configurar um projeto do Google Cloud .
2. O ID da conversa precisa ser gerado dinamicamente pelo SBC. O ID da conversa precisa estar em conformidade com a fórmula de expressão regular [a-zA-Z][a-zA-Z0-9_-]*, com o comprimento dos caracteres no intervalo de [3,64]. Para gerar dinamicamente o ID da conversa, um padrão comum é usar o valor Call-ID no SIP INVITE e prefixá-lo com letras para que ele esteja em conformidade com a expressão regular, conforme especificado anteriormente. Por exemplo, se o valor de Call-ID for 297363723_79131759_799783510, o prefixo "CID-" o tornaria compatível com a expressão regular [a-zA-Z][a-zA-Z0-9_-]*.

Cabeçalho SIP Call-Info

Insira um cabeçalho SIP personalizado chamado Call-Info no SIP INVITE para definir exclusivamente o ID da conversa:

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

Exemplo:

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

Cabeçalho SIP UUI

Se a definição do cabeçalho SIP personalizado Call-Info não for compatível, configure o cabeçalho SIP UUI (usuário para usuário) no SIP INVITE para transmitir o ID da conversa.

Use os mesmos dados solicitados em Call-Info com o URL codificado em hexadecimal e a finalidade definida como Goog-ContactCenter-Conversation. Confira a seguir um exemplo de cabeçalho, em que a string hexadecimal decodificada é 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

Se outros dados precisarem ser transmitidos ao agente e definidos como um parâmetro de sessão, transmita uma lista separada por ponto e vírgula de pares de valores-chave codificados em hexadecimal, seguidos por ;encoding=hex;purpose=Goog-Session-Param. Isso vai resultar em um parâmetro de sessão criado com o nome uui-headers que contém uma lista de strings de payload decodificadas.

Por exemplo, se a string key1=value1;key2=value2 precisasse ser transmitida, o cabeçalho UUI a seguir seria enviado, em que o payload é o valor codificado em hexadecimal de key1=value1;key2=value2.

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

que resultaria na criação do seguinte parâmetro de sessão.

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

Se o SBC aceitar o envio de vários cabeçalhos UUI, você poderá enviar strings de valor-chave individuais por cabeçalho UUI, e elas estarão disponíveis como valores individuais no parâmetro de sessão uui-headers.

O snippet a seguir usa o valor do parâmetro e o divide várias vezes para acessar o valor apropriado da variável key2 na string.

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

O exemplo a seguir mostra uma função chamada por um gatilho nos blocos de código do Playbook, por exemplo: @PlaybookStartHandler, que é chamado ao entrar no playbook. Outras funções chamam essa função para receber valores do 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 ""

Outros dados podem ser enviados usando cabeçalhos UUI separados com valores de "finalidade" diferentes. Esses valores são adicionados ao objeto Conversation.telephonyConnectionInfo. Esses dados não estão disponíveis para o agente do Dialogflow CX em tempo de execução.

Cabeçalhos X do SIP

Os cabeçalhos SIP que começam com x- podem ser transmitidos ao agente e definidos como um parâmetro de sessão. Os cabeçalhos SIP estão disponíveis no parâmetro de sessão x-headers. O prefixo x- é removido do nome do cabeçalho no parâmetro de sessão.

Por exemplo, se o SIP INVITE contiver o seguinte cabeçalho:

x-billing-id: 12345

O parâmetro de sessão x-headers vai conter:

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

Para acessar o valor:

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

Transmitir informações do agente humano

Se você precisar transmitir informações específicas para agentes humanos, defina o atributo de rótulo de mídia do Protocolo de descrição de sessão (SDP, na sigla em inglês) para o fluxo do Protocolo de transporte em tempo real (RTP, na sigla em inglês) do agente humano com o valor de dados necessário. Exemplo: none a=label:7382373482 Esses dados serão preenchidos no campo sip_recording_media_label e estarão disponíveis no tópico do Pub/Sub New message notification que contém as transcrições. Procure o campo sip_recording_media_label na mensagem Message.attributes do pubsub.

Aviso: por motivos de compliance, não transmita dados de usuários de PII em cabeçalhos SIP. Eles devem ser usados apenas para transmitir pares de chave-valor não PII.

Configurar funções de participantes e ordem de stream de mídia

Por padrão, o primeiro stream de mídia é associado à função de participante END_USER, e os streams de mídia subsequentes são associados à função de participante HUMAN_AGENT.

Se você precisar de um comportamento diferente (por exemplo, em um sistema de chamadas externas), o URL transmitido no cabeçalho precisará ter o parâmetro "roles" anexado.

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

O URL especifica que o primeiro fluxo de mídia deve ter a função HUMAN_AGENT e o segundo fluxo de mídia deve ter a função END_USER. É possível aplicar o parâmetro "roles" com o cabeçalho SIP Call-Info ou UUI.

Definir parâmetros adicionais em uma conversa específica

Para definir outros parâmetros em uma conversa, use a chamada de RPC MatchIntentRequest. Você pode definir query_params.parameters como os pares de valores-chave necessários e query_input.text como algo como "Definindo parâmetros".

Faça a chamada de API após a resposta "200 OK" do SIP INVITE inicial, momento em que a conversa é criada. O ID da sessão para o MatchIntentRequest é o mesmo ID de conversa fornecido no cabeçalho Call-Info no INVITE.

Use SIP REFER para transferir uma chamada para um endpoint SIP

Para transferir uma chamada de um agente virtual para um endpoint SIP, use o método SIP REFER. Inclua uma carga útil no campo Live agent handoff e defina o campo Telephony transfer call como o número definido no campo SIP REFER Refer-To de saída. O payload Live agent handoff deve ser semelhante ao exemplo de código a seguir.

{
    "sip-refer": true
}

Se for preciso transmitir dados para fora do Dialogflow CX, os cabeçalhos UUI e x-headers poderão ser usados para transmitir strings de dados. Se você quiser fazer um SIP REFER e transmitir dois pares de chave-valor em um cabeçalho UUI e dois cabeçalhos x, use uma carga útil Live agent handoff semelhante ao exemplo de código a seguir.

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

Isso geraria um SIP REFER com o seguinte UUI e x-headers.

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

Usar SIP INVITE para fazer uma conferência com outro endpoint SIP

Para fazer uma conferência de uma ligação de um cliente final para um agente humano acessível usando um endpoint SIP, use o método SIP INVITE. Isso mantém o Google no caminho da mídia e permite o uso dos recursos do Agent Assist. Defina o campo Telephony transfer call como o número definido no campo SIP INVITE To de saída.

Se for preciso transmitir dados para fora do Dialogflow CX, os cabeçalhos UUI e x-headers poderão ser usados para transmitir strings de dados. Se você quiser fazer um SIP INVITE e transmitir dois pares de chave-valor em um cabeçalho UUI e dois cabeçalhos x, use uma carga útil Live agent handoff semelhante ao exemplo de código a seguir.

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

Isso geraria um convite SIP com o seguinte UUI e cabeçalhos x.

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

Transmitir dados em um SIP BYE

A navegação até End Session vai acionar um SIP BYE. Se quiser transmitir dados do Dialogflow CX, use cabeçalhos UUI ou x-cabeçalhos para transmitir strings de dados. Você encaminharia a chamada para uma página que definisse o payload Live agent handoff de maneira semelhante ao exemplo de código a seguir antes da transição para End Session.

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

Isso geraria um SIP BYE com os seguintes UUI e cabeçalhos x.

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

Acionar uma ação quando o autor da chamada remota desliga

A nova API BiDi (use_bidi_streaming=True em ConversationProfile) permite acionar uma chamada de ferramenta em um playbook ou uma chamada de webhook em um fluxo quando o autor da chamada remota desliga.

Quando o usuário remoto desliga e o Dialogflow CX recebe uma mensagem SIP BYE, o evento personalizado sys.remote-call-disconnected é acionado. Se você criar um manipulador com esse nome de evento específico, poderá usá-lo para acionar uma chamada de ferramenta com um playbook ou uma chamada de webhook em um fluxo.

Solução de problemas

A equipe do Google pode pedir que você forneça os seguintes artefatos para ajudar na solução de problemas do ping de OPTIONS do SIP e das chamadas de teste realizadas:

1. Captura de pacote de rede
2. Rastreamento de depuração do SIP mostrando o cabeçalho completo e o SDP do SIP:
   • Valor do ID da chamada
   • Valor Call-Info (se existir)

Captura de pacote de rede

A captura de pacote de rede precisa mostrar o seguinte:

1. Um handshake TCP completo de três vias (SYN, SYN-ACK, ACK) entre o SBC e os servidores SIP GTP comunicados pela porta TCP 5672. Se a conexão TCP não for estabelecida, os possíveis problemas são:

   • Sua rede está bloqueando o tráfego de saída.
   • A comunicação não está sendo enviada para um dos servidores SIP do GTP regionalizados. Consulte Requisito de rede para conectividade de telefonia.
   • A comunicação não está sendo enviada pela porta TCP 5672.

2. Um handshake de conexão TLS completo com o seguinte:

   • TLS v1.2 ou mais recente iniciado pelo SBC.
   • Seu SBC iniciar um "Client Hello" e o GTP responder com "Server Hello".
   • Processo de autenticação TLS mútua.
     • O GTP responde com o próprio certificado TLS do servidor, que é autenticado pelo seu SBC.
     • O SBC envia o próprio certificado TLS do cliente, que é autenticado pelo GTP.
   • Canal criptografado estabelecido, conforme evidenciado pela "Mensagem de handshake criptografada".
   • Evidências de que os "Dados de aplicativo" estão sendo transmitidos pelo canal TLS.

   Se a conexão TLS não foi estabelecida, os possíveis problemas são:

   • O entroncamento SIP não foi criado no lado do GTP.
   • O FQDN configurado do tronco SIP não corresponde ao FQDN apresentado no certificado TLS (atributo CN ou SAN) do SBC.
   • A versão do TLS não é compatível. Apenas a versão 1.2 ou posterior é compatível.
   • O pacote de criptografia solicitado não é compatível. Consulte Configuração do TLS do SBC.
   • Provedores de certificados TLS não confiáveis, consulte Configuração de TLS do SBC.

3. O rastreamento de depuração do SIP deve mostrar o seguinte:

   • Cabeçalho SIP do cliente Call-Info inserido neste formato: none Call-Info: <http://dialogflow.googleapis.com/v2beta1/projects/$PROJECT_ID/conversations/$CONVERSATION_ID>;purpose=Goog-ContactCenter-Conversation

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

   • Os cabeçalhos SIP mostram o número de telefone no formato E.164 ([phone]).

   • Os cabeçalhos SIP mostram os endereços IP públicos usados no URI da solicitação e outros campos de cabeçalho SIP (por exemplo, "Para", "De", "Via"). Endereços IP particulares seriam rejeitados.

   • As informações de conexão SDP do SIP (c= ... ) são especificadas com um endereço IP público. Endereços IP particulares seriam rejeitados.

   • Verifique se a priorização de mídia envia primeiro o stream dos usuários finais e depois o stream de mídia do atendente humano, porque o GTP trata o primeiro stream de mídia como o dos usuários finais por padrão.

   Se você receber um código de resposta de erro SIP:

   • O código de resposta de erro SIP 400 (por exemplo, 488 Not Acceptable Here) provavelmente indica que o GTP rejeitou um cabeçalho SIP ou uma configuração SDP de mídia SIP.
   • Um código de resposta de erro SIP 600 (erro recusado SIP 603) provavelmente indica um problema relacionado à cota. Consulte a página Cotas e limites para saber como solicitar um aumento.