Plataforma de telefonia do Google

Este guia explica o processo de criação e configuração de um novo número de telefone da plataforma de telefonia do Google (GTP, na sigla em inglês) para o aplicativo do agente. Esse recurso pronto para uso permite anexar um novo número de telefone ao agente que pode lidar com o tráfego de entrada em apenas alguns minutos.

Se você quiser usar um número de telefone já existente, configure o sistema de controle de borda de sessão (SBC, na sigla em inglês) para redirecionar automaticamente o número atual para o novo número da GTP. Para instruções detalhadas sobre a integração e configuração do SBC, consulte a documentação de telefonia do Dialogflow CX.

Antes de começar

  1. Siga as etapas na página de configuração e limpeza para criar ou configurar o projeto que você quer usar na implantação.
  2. Crie e configure um aplicativo do agente para usar na implantação.
  3. Ative a API Dialogflow no projeto.

Limitações

Considere as seguintes limitações:

  • Os números de telefone PSTN (rede pública de telefonia comutada) padrão são aceitos na multirregião us. Para a multirregião eu, você pode usar números de telefone virtuais.
  • Apenas números de telefone dos EUA são aceitos na multirregião us.
  • Não é possível ligar para números de telefone virtuais de telefones PSTN padrão.

Conectar um aplicativo do agente a um número de telefone da GTP

  1. Abra o console do CX Agent Studio e selecione o aplicativo do agente.
  2. Na parte de cima do console, clique na guia Implantar e em Conectar a uma plataforma. Se você já tiver canais implantados, clique em +Novo canal.
  3. Insira um Nome para o canal e selecione Plataforma de telefonia do Google (GTP) no menu Plataforma.
  4. A opção padrão é provisionar um número de telefone virtual para testar o aplicativo do agente no navegador. Para provisionar um número de telefone PSTN (rede pública de telefonia comutada) padrão, selecione essa opção no menu suspenso Connection type.
  5. Selecione uma Versão para implantação. Se você não tiver versões preexistentes, crie uma.
  6. (Opcional) Clique na opção Comportamento específico do canal para configurar outras opções. É possível mudar o tamanho da resposta do agente, ativar a entrada DTMF e permitir que os usuários interrompam o agente no meio da resposta. Para mais informações sobre essas configurações, consulte a documentação de configurações do aplicativo do agente.
  7. Clique em Criar canal. Agora você pode conferir o número de telefone e o ID de implantação do canal.

  8. Se você provisionou um número de telefone PSTN, ligue para ele para testar se ele se conecta ao aplicativo do agente e clique em Concluído. O novo canal aparece na página Canais implantados do aplicativo do agente. Agora você pode usar esse número para que os clientes liguem para o agente. Se você provisionou um número de telefone virtual, você pode testá-lo no widget WebRTC.

Testar o aplicativo do agente no widget WebRTC

Se você provisionou um número de telefone PSTN padrão ou virtual, pode testar o aplicativo do agente no widget WebRTC usando áudio, vídeo ou texto.

  1. Na parte de cima do console, clique na guia Implantar.
  2. Clique no ícone ao lado do nome do canal implantado. Um widget WebRTC será aberto à direita.
  3. Se solicitado pelo widget WebRTC, conceda permissão ao navegador para acessar o microfone e a câmera.
  4. Interaja com o agente por áudio, vídeo ou texto. Ao usar o vídeo, você também pode mudar para o compartilhamento de tela usando o menu suspenso ao lado do ícone da câmera.

Configurar o comportamento do aplicativo do agente

É possível personalizar o comportamento do agente em relação ao encerramento e à transferência de chamadas.

Configurar o encerramento da chamada do agente

Para permitir que o agente encerre uma chamada:

  1. Clique no símbolo de adição no canto superior direito do agente e clique em Adicionar ferramentas.
  2. Adicione a ferramenta end_session ao agente (e a todos os subagentes, se houver). Essa ferramenta do sistema fica disponível automaticamente para todos os agentes por padrão.
  3. Adicione uma descrição do comportamento de encerramento da chamada às instruções. Por exemplo: End the call by executing the end_session tool with arguments reason="customer_query_ended".

Transferir uma chamada para um agente humano

Para configurar o agente para transferir a chamada para um agente humano e encerrar a parte da chamada do agente virtual:

  • Adicione a ferramenta do sistema end_session ao agente (e a todos os subagentes, se houver).
  • Crie as seguintes variáveis:
    • escalationMessage: opcionalmente, adicione texto ao campo Valor padrão se quiser que o agente diga uma mensagem antes de transferir a chamada.
    • telephonyTransferCall: defina o Tipo como Esquema personalizado. Insira o objeto JSON a seguir na caixa de entrada Esquema com o número de telefone para o qual você quer que o agente transfira as chamadas (formato E.164 obrigatório).
{
  "phoneNumber": "+PHONE_NUMBER"
}
  • Adicione uma descrição desse comportamento às instruções. Por exemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Transferência de agente humano com suporte de parceiro

Se o sistema incorporar um parceiro que não seja do Google há duas opções disponíveis para transferência de agente humano: uma variável liveAgentHandoff ou uma variável telephonyPayload. Em ambos os casos, o payload JSON pode variar dependendo das instruções do parceiro.

Transferência de agente humano ao vivo :

  • Adicione a ferramenta do sistema end_session ao agente (e a todos os subagentes, se houver).
  • Crie a seguinte variável:
    • liveAgentHandoff: defina o Tipo como Esquema personalizado e adicione o esquema JSON exigido pelo parceiro. Por exemplo:
{
  "PARTNER_NAME": {
    "type": "action",
    "action": "deflection",
    "deflection_type": "sip",
    "sip_uri": "SIP_URI",
    "sip_refer": true,
    "sip_parameters": {
      "x-header": "value"
    }
  }
}
  • Adicione uma descrição desse comportamento às instruções. Por exemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Transferência de agente humano de payload personalizado :

  • Adicione a ferramenta do sistema end_session ao agente (e a todos os subagentes, se houver).
  • Crie a seguinte variável:
    • telephonyPayload: defina o Tipo como Esquema personalizado e adicione o esquema JSON exigido pelo parceiro. Por exemplo:
{
  "PARTNER_NAME": {
    "type": "action",
    "action": "deflection",
    "deflection_type": "sip",
    "sip_uri": "SIP_URI",
    "sip_refer": true,
    "sip_parameters": {
      "x-header": "value"
    }
  }
}
  • Adicione uma descrição desse comportamento às instruções. Por exemplo: Escalate the call to a human agent by executing the end_session tool with session_escalated=true

Usar a sinalização SIP para transmitir dados de e para o agente

Se você fez uma integração do SBC, pode usar a sinalização SIP para transmitir dados ao agente usando cabeçalhos SIP. Também é possível transmitir dados quando um BYE, REFER ou INVITE é acionado pelo agente.

Todos os dados transmitidos ao agente podem ser acessados usando variáveis. Primeiro, você precisa criar as variáveis para acessar os dados.

O número de telefone do autor da chamada (ANI) é armazenado na variável telephony-caller-id do tipo Text.

Se o agente precisar dizer uma mensagem antes de fazer uma escalada, a mensagem deverá ser armazenada na variável escalationMessage do tipo Text.

Para fazer um SIP REFER ou SIP INVITE, a variável telephonyTransferCall do tipo Custom schema (advanced) precisa existir com as variáveis phoneNumber e useOriginatingTrunk especificadas.

Todos os dados que precisam ser transmitidos devem estar presentes na variável liveAgentHandoff do tipo Custom schema (advanced).

Cabeçalho SIP UUI

É possível transmitir uma lista de pares de valores-chave separados por ponto e vírgula que é codificada em hexadecimal, seguida por ;encoding=hex;purpose=Goog-Session-Param. Para acessar isso no agente, crie uma variável com o nome uui-headers e o tipo List.

Por exemplo, se a string key1=value1;key2=value2 precisar ser transmitida, o seguinte cabeçalho UUI deverá ser enviado, em que o payload é o valor codificado em hexadecimal key1=value1;key2=value2.

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

A variável uui-headers vai conter o seguinte objeto:

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

Para transmitir uuiHeaders ao chamar a ferramenta end_session, especifique params={"liveAgentHandoff": {"uuiHeaders": [ {uui-headers}[0] ]}}

Por exemplo, se os cabeçalhos UUI transmitidos precisassem ser transmitidos em um SIP BYE, você teria uma instrução semelhante a esta:

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"uuiHeaders": [ {uui-headers}[0] ]}}.

Cabeçalhos SIP x

Os cabeçalhos SIP que começam com x- podem ser transmitidos ao agente e salvos como uma variável x-headers e o tipo Custom schema (advanced). O prefixo x- é removido do nome do cabeçalho na variável.

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

x-billing-id: 12345

A variável x-headers vai conter o seguinte objeto:

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

Para transmitir xHeaders, ao chamar a ferramenta end_session, especifique params={"liveAgentHandoff": {"xHeaders": {x-headers} }}

Por exemplo, se os cabeçalhos x transmitidos precisassem ser transmitidos em um SIP BYE, você teria uma instrução semelhante a esta:

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers} }}.

Enviar um SIP BYE

Quando o agente encerra a chamada, um SIP BYE é enviado. Para enviar uuiHeaders e xHeaders no SIP BYE, use uma instrução semelhante ao exemplo a seguir:

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"escalationMessage": "I am transferring you to an agent", "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Enviar um SIP REFER

Se o agente precisar escalar a chamada para um agente humano e abandonar a chamada, um SIP REFER deverá ser usado. Um SIP REFER é acionado especificando "sipRefer": true na variável liveAgentHandoff, e o número refer-to precisa ser fornecido na variável telephonyTransferCall. Um exemplo de instrução para fazer um SIP REFER e transmitir os uuiHeaders e xHeaders:

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"escalationMessage": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "+19496855555", "useOriginatingTrunk": true}, "liveAgentHandoff":{"sipRefer": true, "xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Enviar um SIP INVITE

Se o agente precisar escalar a chamada para um agente humano e permanecer na chamada para que os recursos do Agent Assist possam ser usados, um SIP INVITE deverá ser usado. Um SIP INVITE é acionado pelo phoneNumber na variável telephonyTransferCall. Um exemplo de instrução para fazer um SIP INVITE e transmitir os uuiHeaders e xHeaders:

If the user says that they would like to speak to an agent, escalate the call to the agent by executing the end_session tool with session_escalated=true and params={"escalationMessage": "I am transferring you to an agent", "telephonyTransferCall": {"phoneNumber": "+19496855555", "useOriginatingTrunk": true}, "liveAgentHandoff":{"xHeaders": {x-headers}, "uuiHeaders": [{uui-headers[0]}] }}.

Criar um handler para desconexões de chamadas remotas

Quando um cliente desliga a chamada, isso aciona um evento específico, sys.remote-call-disconnected, que pode ser usado para acionar uma chamada de ferramenta no CX Agent Studio. No exemplo a seguir, a ferramenta sum é chamada quando o cliente desliga a chamada.

A ferramenta sum é definida como uma ferramenta de código Python e contém o código:

def sum(x: int, y: int) -> int:
  """
  Computes the sum of two numbers.

  Args:
    x: The first number.
    y: The second number.

  Returns:
    The sum of the two numbers.
  """
  return x+y

No agente raiz, crie um callback Before LLM com a lógica para observar o evento de desconexão da chamada. No LlmResponse, faça a chamada da ferramenta sum e chame a ferramenta end_session.

def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> Optional[LlmResponse]:

  for part in callback_context.get_last_user_input():
    if part.text == "<event>sys.remote-call-disconnected</event>":
      return LlmResponse.from_parts(
        [Part.from_function_call('sum', {'x': 1, 'y': 2}),
         Part.from_end_session(reason='sum tool called after caller disconnected')]
      )
  return None