Conceitos e solução de problemas

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

Requisitos da 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 a 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, você pode 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 a 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 a mídia são apenas 16384-32767 (TCP + UDP). No entanto, esse intervalo de portas poderá 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 à versão do firmware.

Fornecedores e modelos	Versões de firmware
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 (Build 46) (SIPREC, SIP)
Ribbon Swe Core SBC	v12.01.07R000 (SIPREC, SIP)
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 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 de SBC compatíveis

Protocolo de sinalização	SIP sobre 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 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 Google Cloud ID do projeto e o ID da conversa:

1. O Google Cloud ID do projeto é o projeto que você usou ao configurar um Google Cloud projeto.
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 de Call-ID no SIP INVITE e prefixá-lo com letras para que ele esteja em conformidade com a expressão regular especificada anteriormente. Por exemplo, se o valor de Call-ID for 297363723_79131759_799783510, prefixar o valor de Call-ID com "CID-" o deixará em conformidade 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 configuração do cabeçalho SIP personalizado Call-Info for indisponível, você poderá configurar o cabeçalho SIP UUI (User-to-User) 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, quando 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, faça isso transmitindo uma lista de pares de chave-valor separados por ponto e vírgula que seja codificada em hexadecimal, seguida por ;encoding=hex;purpose=Goog-Session-Param. Isso 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 seguinte cabeçalho UUI 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

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

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

Se o SBC oferecer suporte ao 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 de 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 que é chamada de um acionador 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 Conversation.telephonyConnectionInfo objeto. Esses dados não estão disponíveis para o agente do Dialogflow CX no momento da 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 agente humano, o fluxo do Protocolo de transporte em tempo real (RTP, na sigla em inglês) para 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 sip_recording_media_label campo na mensagem Message.attributes do Pub/Sub.

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

Configurar papéis de participantes e ordem do fluxo de mídia

Por padrão, o primeiro fluxo de mídia é associado ao papel de participante END_USER, e os fluxos de mídia subsequentes são associados ao papel de participante HUMAN_AGENT.

Se você precisar de um comportamento diferente (por exemplo, em um sistema de chamadas de saída), o URL transmitido no cabeçalho precisará ter o parâmetro de papéis 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 precisa ter o papel HUMAN_AGENT e o segundo fluxo de mídia precisa ter o papel END_USER. É possível aplicar o parâmetro de papéis com o Call-Info ou UUI cabeçalho SIP.

Definir outros parâmetros em uma conversa específica

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

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

Usar 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 um payload no campo Live agent handoff e defina o campo Telephony transfer call como o número definido no campo Refer-To SIP REFER de saída. O payload Live agent handoff precisa ser semelhante ao exemplo de código a seguir.

{
    "sip-refer": true
}

Se os dados precisarem ser transmitidos 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 x-headers, poderá usar um payload 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 os seguintes cabeçalhos 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 conferenciar uma chamada com outro endpoint SIP

Para conferenciar uma chamada 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 de mídia e permite o uso dos recursos do Agent Assist. Defina o campo Telephony transfer call como o número definido no campo To SIP INVITE de saída.

Se os dados precisarem ser transmitidos 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 x-headers, poderá usar um payload 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 SIP INVITE com os seguintes cabeçalhos 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

Transmitir dados em um SIP BYE

A navegação até End Session vai acionar um SIP BYE. Se você quiser transmitir dados do Dialogflow CX, os cabeçalhos UUI ou x-headers poderão ser usados para transmitir strings de dados. Você rotearia a chamada para uma página que definiu o payload Live agent handoff semelhante ao exemplo de código a seguir antes de fazer a 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 cabeçalhos 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

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

A nova API BiDi (use_bidi_streaming=True no ConversationProfile) oferece suporte ao acionamento de uma chamada de ferramenta em um playbook ou uma chamada de webhook em um fluxo quando o autor da chamada remota desliga.

Quando o autor da chamada remota desliga e o Dialogflow CX recebe uma mensagem SIP BYE, o evento personalizado sys.remote-call-disconnected é acionado. Se você criar um handler 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.

Permitir chamadas apenas do SBC

Para recusar chamadas da PSTN e conectar apenas chamadas originadas do SBC, atualize o PhoneNumber objeto para especificar a allowedSipTrunks mensagem. Se a integração usar um tronco SIP, você poderá especificar uma lista de IDs de tronco SIP específicos. Se a mensagem for criada com uma lista vazia, qualquer tronco SIP será permitido. Se uma interconexão particular for estabelecida, forneça o ID da operadora provisionado pela equipe do Google Telephony.

Solução de problemas

A equipe do Google poderá pedir que você forneça os seguintes artefatos para ajudar na solução de problemas do ping de OPÇÕES SIP e das chamadas de teste realizadas:

1. Captura de pacote de rede
2. Rastreamento de depuração SIP mostrando o cabeçalho completo e o SDP SIP:
   • Valor de Call-ID
   • Valor de 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 serão:

   • A rede está bloqueando o tráfego de saída.
   • A comunicação não está sendo enviada para um dos servidores SIP GTP regionalizados. Consulte o requisito de rede de 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.
   • 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 próprio certificado TLS do servidor, que é autenticado pelo 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 "Dados do aplicativo" sendo transmitidos pelo canal TLS.

   Se a conexão TLS não for estabelecida, os possíveis problemas serão:

   • O tronco 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 mais recente do TLS é compatível.
   • O pacote de criptografia solicitado não é compatível. Consulte a configuração TLS do SBC.
   • Provedores de certificados TLS não confiáveis. Consulte a configuração TLS do SBC .

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

   • Cabeçalho SIP Call-Info do cliente 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 endereços IP públicos sendo usados no URI de solicitação e outros campos de cabeçalho SIP (por exemplo, To, From, Via). Os endereços IP particulares serão rejeitados.

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

   • Verifique se a priorização de mídia envia o stream dos usuários finais primeiro, seguido pelo stream de mídia do agente humano, porque o GTP trata o primeiro stream de mídia como os 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 de SDP de mídia SIP.
   • Um código de resposta de erro SIP 600 (erro SIP 603 Declined) provavelmente indica um problema relacionado à cota. Consulte a página Cotas e limites para mais detalhes sobre como solicitar um aumento.