Recursos para integrações personalizadas do assistente de agente

Os recursos nesta página fornecem as informações necessárias para planejar e implementar uma integração personalizada de assistência do agente com o NiCE CXone.

Aplicativos de Agente com suporte

MAX e os aplicativos NiCE CXone Agent Workspace (Agent) são compatíveis para uso com integrações personalizadas de agent assist. Nos aplicativos NiCE CXone Agent Workspace (Agent), as integrações personalizadas de agent assist sempre abrem em uma nova guia.

Transmissão de Áudio

Os pacotes de áudio são codificados como áudio bruto G711 μlaw de 8 bits e 8000 kHz. Esse é o mesmo formato de todo o áudio de telefonia do NiCE CXone.

Ao configurar a sua integração de assistência ao agente personalizada em Agent Assist Hub, você pode escolher qual áudio deseja enviar ao aplicativo de assistência ao agente. Você pode enviar áudio do contato, do agente ou de ambos.

No início de cada transmissão, o NiCE CXone envia uma mensagem inicial para o aplicativo Custom Agent Assist Endpoint.A mensagem inicial inclui o parâmetro streamPerspective, que indica se o fluxo de áudio é do Agente ou do contato:

  • "streamPerspective": "RX": O áudio transmitido pelo telefone do agente: o agente falando.
  • "streamPerspective": "TX": O áudio que o agente escuta: o contato falando, ou várias pessoas, se a interação estiver no modo de conferência.
  • "streamPerspective": "MIX": Contém as transmissões de áudio do agente e do contato.

Uma conexão de websocket individual contém apenas áudio de uma perspectiva. Normalmente, isso é TX ou RX, o que fornece separação estéreo. É possível uma combinação dos dois em um único fluxo mono. Se ocorrer uma interação no modo de conferência, o áudio recebido dependerá da perspectiva de fluxo configurada. Se a perspectiva for TX, o áudio de todos os participantes, exceto o agente, é recebido.

Se a conexão cair ou tiver outros problemas, como perda de pacotes, o terminal de assistência de agente personalizado tenta recuperar a conexão com o websocket. Ela espera um novo handshake de autenticação idêntico ao inicial que recebe.

Se um contato for colocado em espera, a conexão websocket é encerrada. Quando a interação recomeçar, uma nova conexão websocket é iniciada. Ele espera um handshake idêntico ao original.

Autorização

Você pode usar autorização em integrações personalizadas de Agent Assist. Sua integração pode exigir autenticação para solicitações no túnel de proxy e no aplicativo de Agent Assist.

Autorização para o túnel proxy

Se desejar que o túnel proxy exija autorização para as solicitações quando elas passam por ele, você precisa incluir esse requisito no seu design. Você pode usar qualquer tipo de autorização, como cabeçalhos ou autorização baseada em token dinâmico. Você deve criar seu túnel proxy para usar o método de autorização escolhido.

Você também precisa configurar seu script Studio para gerenciar a autorização:

  • Para autorização baseada em cabeçalho, o script deve incluir o cabeçalho nas solicitações que envia.
  • Para a autorização baseada em token, o script precisa solicitar um token, armazená-lo em cache e gerenciar a expiração do token. Quando o token expira, o script deve solicitar um novo token, se necessário. Use a ação REST API Studio para se comunicar com o servidor de autenticação.

Se você usar autorização dinâmica, também precisará configurar um servidor de autorização, caso ainda não tenha um disponível. O servidor de autorização fornece tokens quando o script os solicita.

Autorização para o Aplicativo de assistência ao Agente

Se o seu provedor de assistência do agente exigir autorização com todas as solicitações, você poderá configurá-lo no aplicativo Custom Agent Assist Endpoint no Agent Assist Hub.

Para usar a autorização com sua integração personalizada, você precisa:

  • Gere o cabeçalho DE autorização para usar em seus scripts de integração personalizados de assistência ao agente. Consulte a documentação do provedor de assistência do agente para todas as configurações aplicáveis.
  • Adicione os cabeçalhos necessários ao aplicativo de Terminal do Custom Agent Assist em Agent Assist Hub. Se você usar o aplicativo de assistência ao Agente com interações de texto e voz, você precisará de cabeçalhos separados para cada tipo de interação. Consulte a documentação do provedor de assistência do agente para saber como gerar cabeçalhos.

Você não precisa configurar nada no seu script. O aplicativo Custom Agent Assist Endpoint lida com a passagem do cabeçalho para o aplicativo de assistência ao Agente.

NiCE CXone Requisitos de Configuração da plataforma

Não há alterações de configuração obrigatórias na plataforma NiCE CXone para configurar uma integração personalizada de assistência ao agente. Você pode modificar scripts existentes para incluir o novo aplicativo de assistência ao agente. No entanto, pode ser necessária alguma configuração dependendo de como a sua organização está usando a nova aplicativo. Você pode precisar:

Diagramas de sequência

Os diagramas de sequência mostram como diversas partes de uma integração de assistência de agente personalizada interagem e a ordem em que essas Interações ocorrem. Eles mostram uma linha do tempo de uma interação, começando no canto superior esquerdo e, em seguida, movendo-se para frente e para trás ao longo da página.

Diagramas de sequência são uma parte importante do planejamento da sua integração personalizada. Você pode usá-los para mapear o fluxo de solicitações e respostas entre NiCE CXone, Agent Assist Hub, o túnel proxy e o seu aplicativo de agent assist. Eles também podem ser úteis para determinar o fluxo que o seu script Studio deve seguir.

An example of a sequence diagram for a custom agent assist integration.

Requisitos e diretrizes de script do Studio

Use as amostras a seguir como base para criar os Scripts de integração do seu aplicativo de assistência ao agente ao NiCE CXone. As interações de entrada e saída requerem scripts separados. A imagem a seguir mostra as ações essenciais para um script de entrada:

Um exemplo de script mostrando a ação onAnswer conectada à ação Rest API, que está conectada à ação Agent Assist.

Esta imagem mostra as ações essenciais para um script de saída:

Studio workflow diagram showing Begin, Snippet, and Agent Assist actions connected in sequence

Em ambos os scripts, o Snippet de Carga útil de Parâmetro do Script Snippet é opcional. Você só precisa incluí-lo se precisar passar parâmetros para o aplicativo de assistência ao agente.

Para concluir a configuração do script:

  • Atribua o aplicativo de configuração Custom Agent Assist Endpoints à ação Agent Assist.
  • Certifique-se de que a ação Script Param Payload Snippet opcional contenha o JSON de carga útil personalizada a ser enviado ao provedor de assistência ao agente.

  • Certifique-se de que a propriedade scriptParams na ação Agent Assist esteja definida como {customPayloadJSON}. Isso é necessário somente se você incluir a ação opcional Snippet com carga útil personalizada.
  • Adicione snippets de inicialização ao script usando as ações Snippet actions. Você pode fazer isso para personalizar seu aplicativo de assistência ao agente.
  • Reconfigure os conectores de ação para garantir o fluxo de contato adequado e corrigir possíveis erros.
  • Conclua qualquer script adicional e teste o script.

Se precisar de ajuda com scripts em Studio, entre em contato com seu representante de conta, consulte a seção Referência Técnica Guide na ajuda online do Studio, ou visite o site da Comunidade NiCE Icon of a square with an arrow point from the center through the top right corner. para NiCE CXone.

Snippet de Carga útil de parâmetros do script

Este Snippet define os dados passados para o aplicativo de assistência ao agente pela Agent Assist ação. Adicione este código a uma Snippet ação no seu script:

DYNAMIC customParam
customParam.param1 = "{value1}"
customParam.param2 = "{value2}"
customParam.param3 = "{value3}"
customParam.param4 = "{value4}"

ASSIGN customParamjson = "{customParam.asJSON()}" 

Caso não haja parâmetros de carga útil personalizada para enviar mas o snippet de Parâmetros de script seja exigido, você pode incluir as declarações da variável no snippet sem atribuir valores. Por exemplo:

DYNAMIC customParam
ASSIGN customParamjson = "{customParam.asJSON()}" 

Para usar este snippet:

  1. Altere os nomes e valores de parâmetros conforme necessário para atender às necessidades da sua organização e do aplicativo de assistência do agente que você usa.
  2. Coloque a ação Snippet no script antes da ação Agent Assist.
  3. Configure a propriedade scriptParams na Agent Assist ação com o nome da variável que contém o JSON. No exemplo fornecido, seria customParamjson.

Scripts novos ou existentes

Você pode criar novos scripts para usar com sua integração personalizada de assistência ao agente.Você também pode modificar os scripts existentes. Não faça alterações diretamente em Scripts que estejam atualmente em produção. Fazer isso pode resultar em erros que interrompem o roteamento de contatos.

Se quiser usar um script existente, salve uma cópia do script e modifique-a. Quando sua integração personalizada estiver totalmente testada e pronta para implementação, você pode mover o script modificado de volta para a produção. Mova um script para produção seguindo um destes procedimentos:

Desenvolvimento e especificações do webhook do túnel proxy

O proxy tunnel é o middleware entre NiCE CXone e o terminal do aplicativo de assistência ao agente. Todas as solicitações e respostam passam por ele. Ele deve traduzir solicitações de NiCE CXone para um formato que o aplicativo de assistência ao agente entenda. De forma semelhante, ele deve traduzir as respostas do aplicativo de assistência ao agente para o formato que NiCE CXone entende. Para realizar essas traduções, você deve mapear os endpoints entre NiCE CXone e o aplicativo de assistência ao agente.

O túnel proxy não é necessário. No entanto, recomenda-se incluí-lo em sua integração. O túnel proxy fornece os seguintes benefícios:

  • Ela fornece maior segurança porque há um único ponto de entrada no seu data center para gerenciar.
  • Fornece failover e balanceamento de carga.
  • Converte protocolos entre o NiCE CXone e o sistema do provedor de assistência a agentes.

Se você não incluir um túnel de proxy na sua integração, o script enviará a solicitação websocket inicial para as URLs de webhook. Você deve configurar seu script para enviar e receber solicitações no formato esperado pelo aplicativo de assistência ao agente.

As seguintes seções fornecem:

Fatos chave sobre o Desenvolvimento do Túnel Proxy

As seguintes informações podem ajudar você a planejar e desenvolver o terminal de túnel proxy:

  • O terminal de retransmissão de texto deve usar HTTPS. Ele não funcionará com HTTP.

  • O terminal de retransmissão de áudio deve usar um websocket. Ele pode ser protegido (WSS) ou não protegido (WS).

  • Todos os terminais do túnel proxy devem ser capazes de enviar e receber comunicação da rede do NiCE CXone.

  • Apenas os dados binários fluem pelo webhook.

  • Para interações de voz, os únicos dados enviados da chamada são bytes de áudio. Nenhum controle de chamada ou outros metadados são incluídos.

  • As integrações de assistência do agente personalizadas suportam pelo menos 2000 solicitações simultâneas.

  • Não há um tempo de expiração ou tempo máximo de conexão para transmitir uma interação. As integrações de assistência do agente personalizadas permitem que as chamadas permaneçam abertas enquanto estiverem ativas. Quando a chamada termina, a conexão é encerrada.

  • Quando uma chamada é colocada em espera, a conexão permanece aberta, mas nenhum dado é enviado.

  • Os IDs de contato são exclusivos por locatário. NiCE CXone tem uma API que você pode usar para obter dados em tempo real sobre o contactID. Para visualizar a documentação sobre a API, você precisa de acesso ao NiCE CXone Dev Portal. Pergunte ao seu representante de conta para obter informações sobre o acesso.

Conectar ao Webhook de Áudio: Solicitação inicial

As interações de voz devem usar solicitações de websocket (WSS ou WS). A solicitação inicial de websocket do NiCE CXone segue este formato:

 
"authenticationToken": "[header provided in Custom Agent Assist app]",
"executionInfo": {    
      "contactId": 0, 
      "busNo": 0, 
      "requestId": 0,  
      "actionType": "string",  
      "actionId": 0,  
      "scriptName": "string"
},
      "systemTelemetryData": {    
            "consumerProcessHost": "string",  
            "consumerProcessName": "string",  
            "consumerProcessVersion": "string",  
            "inContactClusterAlias": "string",  
            "inContactScriptEngineHost": "string",  
            "consumerMetaData": {  
                  "additionalProp1": "string",
                  "additionalProp2": "string",   
                  "additionalProp3": "string"  
            }
      },
"streamPerspective": "TX/RX/MIX",
"streamsConfiguration": "string",
"appParams": "string",
"appConfig": "string"
			
		

Os parâmetros desta solicitação são descritos na seção Esquemas desta página:

Conectar-se ao Audio Hook: Resposta de handshake

Se authenticationToken for fornecido, valide o token ou cabeçalho e, em seguida, envie uma resposta de handshake. A resposta deve seguir o formato da classe CXoneWebSocketMessage:


public class CXOneWebSocketMessage 
{ 
/// Type of command - see CXOneWebSocketCommandType below
public CXOneWebSocketCommandType command { get; set; } 

/// Type of message returned 
public string messageType { get; set; } 

/// Text message 
public string message { get; set; } 

/// Additional parameters 
public object parameters { get; set; } 
)

public enum CXOneWebSocketCommandType
{ 
CONNECT, 
/// When the initial message/auth validation is a success 
CONNECTED, 
/// Message command 
MESSAGE,  
/// Error command, for example when the initial message/auth is invalid 
ERROR
}
		

Por exemplo:


{
    "command": "CONNECTED",
    "messageType": "COMMAND",
    "message": "BEGIN AUDIO STREAM"
}
		

Um exemplo de código para conexão com o websocket:

	
WebSocketReceiveResult result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);
if (result.MessageType == WebSocketMessageType.Text)
{ 
    _logger.LogInformation(string.Concat ("MessageType : ", result.MessageType.ToString()));
    if (buffer == null || buffer?.Length == 0)
    {
       return;
    }
    var message = Encoding.UTF8.GetString(buffer, 0, buffer?.Length ?? 0);
    _logger.LogInformation(string.Concat("On Connected", message));
 
    // Validates initial message
    var initialMessage = JsonConvert.DeserializeObject<WebSocketHookInitializeMessage>(message);
    webSocketHookInitilizeMessage = initialMessage;
    param = JsonConvert.SerializeObject(webSocketHookInitializeMessage.appConfig);
 
    // Send response back to  after successful validation
    CXOneWebSocketMessage connectedMessage = new CXOneWebSocketMessage
    {
       command = CXOneWebSocketCommandType.CONNECTED,
       messageType = "COMMAND", 
       message = "BEGIN AUDIO STREAM"
   }; 

    var jsonResponse = Newtonsoft.Json.JsonConvert.SerializeObject(connectedMessage);
    await webSocket?.SendAsync(buffer: new ArraySegment<byte>(array: Encoding.UTF8.GetBytes(jsonResponse),
             offset: 0,
             count: jsonResponse.Length),
             messageType: WebSocketMessageType.Text,
             endOfMessage: true,
             cancellationToken: CancellationToken.None);
}

else if (result.MessageType == WebSocketMessageType.Binary)
{
// You can read the binary voice data
}		
				
		

A seção Esquemas desta página descreve o seguinte:

Conectar ao webhook de texto

Para receber dados de chat de texto, você precisa se conectar ao webhook de texto. Somente solicitações HTTP/HTTPS são aceitas.

Cada solicitação inclui os seguintes objetos. O cabeçalho DE autorização é enviado somente se você adicionar um no aplicativo Custom Agent Assist Endpoints em Agent Assist Hub. Cabeçalhos DE autorização não são necessários.


public class WebHooksMessagesRequest
{
	/// If you provide this information in the configuration, it's included.
	public string authorizationHeader { get; set; }
	public int contactId { get; set; }
	public int busNo { get; set; }
	public string tenantId { get; set; }
	
	/// This will be one of the following: patron, agent, or system
	public string participantId { get; set; }
	
	/// Text of the user input (from participantId)
	public string messageBody { get; set; }
	
	/// Other useful data about the message or that are part of the message, such as images or links.
	public object messageData { get; set; }
	
	/// Configuration blob from Agent Assist Hub. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}
 	

Os parâmetros neste código são descritos na seção Esquemas desta página.

Parâmetros de configuração

Você pode incluir parâmetros adicionais ao configurar o aplicativo Custom Agent Assist Endpoints em Agent Assist Hub. Isso é útil se o provedor de assistência do agente exigir que determinados parâmetros sejam enviados com cada solicitação. Eles não são necessários. todos os parâmetros que você adicionar são enviados no objeto agentAssistAppConfig no objeto WebHooksMessagesRequest. Por exemplo:


"agentAssistAppConfig":{ 
   "param1": "value1", 
   "param2": "value2",
} 
		

Terminais do NiCE CXone para integrações de assistência do Agente personalizadas

Os endpoints de API fornecidos aqui são referências interativas que você pode usar com sua integração personalizada de assistência ao agente para obter exemplos de solicitações de NiCE CXone. Informações adicionais, incluindo os esquemas originais, estão disponíveis na documentação do Swagger da API.

Endpoints para Aplicativos de Agente Auxiliar Baseados em Voz

GET ​/agent_assist_audio_websocket_hooks​/example-websocket-server: Este terminal fornece um exemplo de URL de solicitação de servidor websocket. Este exemplo está em conformidade com a NiCE CXone especificação de hook de websocket de áudio.

GET ​/agent_assist_audio_websocket_hooks​/initializemessage-example: Este terminal fornece um exemplo de mensagem de inicialização do websocket.

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example: Este terminal fornece um exemplo da solicitação e resposta iniciais. Consulte o WebSocketHookInitializeMessage esquema e o CXoneWebSocketMessage esquema para obter detalhes.

Terminal para Aplicativos de Assistente de agente baseados em chat

POST ​/agent_assist_text_webhooks​/utterance: Este terminal oferece um exemplo de recebimento de enunciadosClosed O que um contato diz ou digita. baseados em texto em tempo real e de fornecimento de assistência ao agente de forma assíncrona. Os enunciados podem ser apenas do contato, apenas do agente ou de ambos.

Esquemas

As seções a seguir fornecem informações sobre os esquemas usados com os terminais de assistência do agente personalizados. Sempre verifique os esquemas na versão mais recente do documento Swagger antes de usar estas informações em seus scripts.

ActionExecutionInfo

Contém informações sobre a ação e o script que estão sendo executados.

Parâmetro

Tipo

Detalhes

contactId Inteiro O identificador exclusivo para a interação.
busNo Inteiro O ID da NiCE CXoneunidade de negóciosClosed Agrupamento organizacional de alto nível usado para gerenciar o suporte técnico, o faturamento e as configurações globais do seu sistema NiCE CXone. em que o script está localizado.
requestId Inteiro

Um número iterativo que identifica cada solicitação em uma interação específica. Se você incluir o requestId nas solicitações, ele poderá ser incluído nas respostas.

Isso pode ser útil para solucionar problemas e outras questões. Se requestID for um valor exclusivo, ele poderá ser usado para localizar uma solicitação/resposta nos arquivos de log.

actionType

Comando

O tipo DE ação que faz a solicitação para o terminal personalizado.
actionId

Inteiro

O número do Id da ação Studio no script. Ids de ação são baseados na ordem em que as ações foram adicionadas ao script.
scriptName

Comando

O caminho e o nome do script que está fazendo a solicitação.

AgentAssistUtterance_V1

Contém o corpo da mensagem e informações sobre a mensagem.

Parâmetro

Tipo

Detalhes

contactId integer ($int64) O id do contato na instância atual do script.
busNo integer ($int32) O ID da NiCE CXone unidade de negóciosClosed Agrupamento organizacional de alto nível usado para gerenciar o suporte técnico, o faturamento e as configurações globais do seu sistema NiCE CXone. onde o script está localizado.
tenantId

Sequência

O id DO locatário NiCE CXone em que o script está localizado.
participantId

Sequência

Indica se a mensagem inclui o contato (Patron), o agente (Agente), ou ambos (Sistema).
messageBody

Sequência

O texto da mensagem.
messageMetaData  

Contém parâmetros que armazenam dados úteis sobre a mensagem em messageBody. Se a mensagem for de chat, esse parâmetro também pode conter imagens, links ou outro conteúdo enviado como parte da mensagem.

agentAssistAppConfig  

Contém informações de configuração do Agent Assist Hub. Para aplicativos de Agent Assist com blobs de configuração grandes, esse objeto pode incluir somente o identificador de configuração.

{
	"agentAssistAppConfig":
        {

          "param1": "value1",

          "param2": "value2"

        }

}

CXoneWebSocketCommandType

Define o tipo de comando que está sendo enviado. Os valores possíveis são:

  • CONNECT .
  • CONNECTED para quando a mensagem inicial ou validação de autorização for bem-sucedida.
  • MESSAGE para usar ao enviar uma mensagem.
  • ERROR para uso quando a mensagem inicial ou validação de autorização for inválida.

CXoneWebSocketMessage

Contém a mensagem enviada a NiCE CXone a partir do aplicativo de assistência ao agente.

Parâmetro

Tipo

Detalhes

command Sequência Contém o valor de CXOneWebSocketCommandType.
messageType

Sequência

Contém o tipo de mensagem.
message

Sequência

Contém o texto da mensagem.
parameters  

Um objeto que contém quaisquer parâmetros adicionais exigidos pelo aplicativo de assistência ao agente. Configure os parâmetros que você precisa incluir no aplicativo Custom Agent Assist Endpoint no Agent Assist Hub.

{
	additional parameters
}

StreamPerspective

Contém uma matriz de strings com três valores possíveis. Este parâmetro reflete a configuração de Participantes feita no aplicativo Custom Agent Assist Endpoints no Agent Assist Hub. Define se a transmissão de áudio contém áudio apenas do contato (0 (TX)), apenas do Agente (1 (RX) ) ou uma combinação (2 (MX)).

SystemTelemetryData

Contém dados sobre o consumidor da API que não está associado à ação de script do Studio. Os dados que esse objeto contém podem ser úteis para depuração, faturamento, relatórios, entre outros.

Parâmetro

Tipo

Detalhes

consumerProcessHost Comando O nome DO host do aplicativo que está chamando a API.
consumerProcessName Comando O nome do processo ou aplicativo que está fazendo a Chamada de API. Por exemplo, EsnMediaServer.exe.
consumerProcessVersion Comando Informações de versão sobre o aplicativo que está chamando a API.
inContactClusterAlias Comando Se aplicável e disponível, forneça o alias do cluster NiCE CXone em que o script está sendo executado. Por exemplo, C7 ou M33.
inContactScriptEngineHost Comando Se aplicável e disponível, forneça o nome DO host do mecanismo de script NiCE CXone. Por exemplo, lax-c4cor01 ou aoa-c32cor01.
consumerMetaData Objeto

Contém dados arbitrários e extensíveis sobre o consumidor da API.

{
	< * >:
}

WebSocketHookInitializeMessage

Esta é a estrutura de mensagem da primeira carga útil de um cliente de websocket em conexão, como o servidor de mídia NiCE CXone.

Parâmetro

Tipo

Detalhes

authenticationToken Sequência

Contém o cabeçalho de autenticação configurado no aplicativo Custom Agent Assist Endpoints em Agent Assist Hub.

executionInfo   Contém o objeto ActionExecutionInfo.
systemTelemetryData   Contém o objeto SystemTelemetryData.
streamPerspective   Contém o valor de StreamPerspective.
streamsConfiguration   Não atualmente em uso.
appParams  

Parâmetros de contato dinâmicos que podem ser transmitidos de scripts do Studio ou outras fontes.

{
	parameters
}
appConfig  

Configurações predefinidas do aplicativo de assistência do agente.

{
	parameters
}