Conceitos e resolução de problemas

Esta página detalha as configurações específicas necessárias para a integração, bem como a resolução de problemas comuns.

Requisitos da rede de telefonia

Se a sua rede filtrar o tráfego de saída, tem de permitir o tráfego de saída para a sinalização SIP e o streaming de multimédia.

Para a sinalização SIP, deve ser permitido todo o intervalo de IP 74.125.88.128/25 (TCP) na porta 5672. Para um conjunto de regras de firewall mais restritivo, pode restringir a sinalização SIP apenas a 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 o conteúdo multimédia RTP, tem de configurar 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 multimédia são apenas 16384-32767 (TCP+UDP). No entanto, este intervalo de portas pode ser expandido no futuro.

Fornecedores ou modelos de SBC suportados

A tabela seguinte indica os fornecedores ou os modelos de SBC e as versões de firmware suportados. As instruções de integração detalhadas para cada fornecedor estão associadas à versão do firmware.

Fornecedores e modelos	Versões de firmware
AudioCodes VE SBC	v7.60A.100.022 (SIPREC, SIP)
Controlador de limite de sessões da Avaya para empresas	v8.1.3.2-38-22279, v10.2.0.0-86-24077
Oracle E-SBC Acme Packet 3900	SCZ9.3.0 GA (Build 46)
Ribbon Swe Core SBC	v11.01.01R005
Cisco Unified Border Element (CUBE)	v17.15.03a

Nota: esta tabela representa as versões de firmware suportadas mínimas que foram certificadas para funcionar com a integração SIP. As 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 multimédia e sinalização de SBC suportados

Protocolo de sinalização	SIP por TLS
Multimédia	PTTRS
Encriptação de multimédia	SDES
Media Cipher Suite Supported	AES_CM_128_HMAC_SHA1_80, AEAD_AES_256_GCM
Codecs de multimédia suportados	G.711 µ-law (PCMU), G.711 A-law (PCMA), Opus

Cabeçalhos de SIP

Quando configura um perfil de conversa e um número de telefone, cria um perfil de conversa da CCAI com o sipConfig.createConversationOnTheFly definido como true. O ID da conversa deve ser gerado dinamicamente durante o SIP INVITE através do valor do cabeçalho SIP de Call-Info ou UUI.

O valor do cabeçalho SIP aponta para o ponto final do Dialogflow definindo o Google Cloud ID do projeto e o ID da conversa:

1. O Google Cloud ID do projeto é o projeto que usou quando configurou um Google Cloud projeto.
2. O ID da conversa deve ser gerado dinamicamente pelo SBC. O ID da conversa tem de estar em conformidade com a fórmula de expressão regular [a-zA-Z][a-zA-Z0-9_-]* com o comprimento dos carateres 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 o tornar compatível com a expressão regular, conforme especificado anteriormente. Por exemplo, se o valor de Call-ID for 297363723_79131759_799783510, prefixar o valor de Call-ID com "CID-" torna-o compatível com a expressão regular [a-zA-Z][a-zA-Z0-9_-]*.

Call-Info Cabeçalho SIP

Insira um cabeçalho de SIP personalizado denominado Call-Info no SIP INVITE para definir de forma exclusiva 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

UUI Cabeçalho SIP

Se a definição do cabeçalho SIP personalizado Call-Info não for suportada, pode configurar o cabeçalho SIP UUI (utilizador para utilizador) no SIP INVITE para transmitir o ID da conversa.

Use os mesmos dados pedidos em Call-Info com o URL codificado em hexadecimal e a finalidade definida como Goog-ContactCenter-Conversation. Segue-se um exemplo de um cabeçalho em que a string hexadecimal, quando descodificada, é 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 tiver de transmitir dados adicionais para o agente conversacional e defini-los como um parâmetro de sessão, pode fazê-lo transmitindo uma lista de pares de valores-chave separados por ponto e vírgula com codificação hexadecimal, seguida de ;encoding=hex;purpose=Goog-Session-Param. Isto resulta num parâmetro de sessão criado com o nome uui-headers que contém uma lista de strings de payload descodificadas.

Por exemplo, se a string key1=value1;key2=value2 tiver de ser transmitida, o seguinte cabeçalho UUI é enviado, em que a carga útil é 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 seu SBC suportar o envio de vários cabeçalhos UUI, pode enviar strings de valor-chave individuais por cabeçalho UUI, e estas ficam disponíveis como valores individuais no parâmetro de sessão uui-headers.

O fragmento seguinte obtém o valor do parâmetro e, em seguida, divide o parâmetro várias vezes para aceder ao valor adequado para a 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 seguinte mostra uma função que é chamada a partir de um acionador nos blocos de código do Playbook, por exemplo: @PlaybookStartHandler, que é chamado quando entra no Playbook. Outras funções chamam esta função para obter 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 ""

É possível enviar dados adicionais através de cabeçalhos UUI separados com valores de "finalidade" diferentes. Estes valores são adicionados ao objeto Conversation.telephonyConnectionInfo. Tenha em atenção que estes dados não estão disponíveis para o agente de agentes conversacionais (Dialogflow CX) no momento da execução.

Transmita informações do agente humano

Se precisar de transmitir informações específicas aos agentes humanos, pode definir o atributo de etiqueta de multimédia do Session Description Protocol (SDP) para a stream do Real-time Transport Protocol (RTP) do agente humano para o valor de dados necessário. Exemplo: none a=label:7382373482 Estes dados vão ser preenchidos no campo sip_recording_media_label e vão estar 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 pubsub.

Aviso: por motivos de conformidade, não transmita dados de utilizadores de IIP em cabeçalhos SIP. Devem ser usados apenas para transmitir pares de chave-valor não PII.

Configure as funções dos participantes e a ordem da stream de multimédia

Por predefinição, a primeira stream de multimédia está associada à função de END_USERparticipante e as streams de multimédia subsequentes estão associadas à função de HUMAN_AGENTparticipante.

Se precisar de um comportamento diferente (por exemplo, num sistema de chamadas de saída), o URL transmitido no cabeçalho deve 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 a primeira stream de multimédia deve ter a função HUMAN_AGENT e a segunda stream de multimédia deve ter a função END_USER. Pode aplicar o parâmetro roles com o cabeçalho SIP Call-Info ou UUI.

Defina parâmetros adicionais numa determinada conversa

Para definir parâmetros adicionais numa determinada conversa, use a chamada RPC MatchIntentRequest. Pode definir query_params.parameters para os pares de chaves-valores necessários e query_input.text para algo como "Definir parâmetros".

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

Use SIP REFER para transferir uma chamada para um ponto final SIP

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

{
    "sip-refer": true
}

Se os dados tiverem de ser transmitidos para fora dos agentes conversacionais (Dialogflow CX), podem ser usados cabeçalhos UUI para transmitir strings de dados. Se quisesse fazer um SIP REFER e distribuir 2 pares de valores-chave, podia usar um payload semelhante ao seguinte exemplo de código.

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

Isto geraria um SIP REFER com o seguinte cabeçalho UUI.

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

Transmita dados num SIP BYE

A navegação para End Session aciona um SIP BYE. Se quiser transmitir dados de agentes conversacionais (Dialogflow CX), pode usar cabeçalhos UUI para transmitir strings de dados. Encaminharia a chamada para uma página que definiu a carga útil Live agent handoff semelhante ao seguinte exemplo de código antes de fazer a transição para End Session.

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

Isto geraria um SIP BYE com o seguinte cabeçalho UUI.

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

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

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

Quando o autor da chamada remota desliga e os agentes conversacionais (Dialogflow CX) recebem uma mensagem SIP BYE, o evento personalizado sys.remote-call-disconnected é acionado. Se criar um controlador com este nome de evento específico, pode usá-lo para acionar uma chamada de ferramenta com um guia interativo ou uma chamada de webhook num fluxo.

Resolução de problemas

A equipa da Google pode pedir-lhe que faculte os seguintes artefactos para ajudar na resolução de problemas do ping OPTIONS SIP e das chamadas de teste realizadas:

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

Captura de pacotes de rede

A captura de pacotes de rede deve mostrar o seguinte:

1. Uma confirmação TCP de 3 vias completa (SYN, SYN-ACK, ACK) entre o seu SBC e os servidores SIP GTP comunicados através da porta TCP 5672. Se não for possível estabelecer a ligação TCP, os possíveis problemas são:

   • A sua rede está a bloquear o tráfego de saída.
   • A comunicação não está a ser enviada para um dos servidores SIP GTP regionalizados. Consulte o requisito de rede de conetividade de telefonia.
   • A comunicação não está a ser enviada através da porta TCP 5672.

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

   • TLS v1.2 ou posterior iniciado pelo seu SBC.
   • O SBC inicia um "Client Hello" e o GTP responde com "Server Hello".
   • Processo de autenticação TLS mútua.
     • O GTP responde com o respetivo certificado TLS do servidor, que é autenticado pelo seu SBC.
     • O SBC envia o seu próprio certificado TLS de cliente, que é autenticado pelo GTP.
   • Canal encriptado estabelecido, como é evidente na "Mensagem de handshake encriptada".
   • Prova de que os "Dados da aplicação" são transmitidos através do canal TLS.

   Se não for possível estabelecer a ligação TLS, os possíveis problemas são:

   • O ramal de 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 TLS não é suportada. Apenas são suportadas as versões TLS 1.2 ou posteriores.
   • O conjunto de cifras pedido não é suportado. Consulte a configuração de TLS do SBC.
   • Fornecedores de certificados TLS não fidedignos. Consulte a secção Configuração de TLS do SBC.

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

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

     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 que estão a ser usados no URI do pedido e noutros campos de cabeçalho SIP (por exemplo, To, From, Via). Os endereços IP privados seriam rejeitados.

   • As informações de ligação SDP SIP (c= …) são especificadas com um endereço IP público. Os endereços IP privados seriam rejeitados.

   • Certifique-se de que a priorização de multimédia envia primeiro a stream do utilizador final e, em seguida, a stream de multimédia do agente humano, porque o GTP trata a primeira stream de multimédia como a do utilizador final por predefinição.

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

   • O código de resposta de erro SIP 400 (por exemplo, 488 Not Acceptable Here) indica provavelmente que o GTP rejeitou uma configuração de cabeçalho SIP ou SDP de multimédia SIP.
   • Um código de resposta de erro SIP 600 (erro SIP 603 recusado) indica provavelmente um problema relacionado com a quota. Consulte a página Quotas e limites para ver detalhes sobre como pedir um aumento.