Recursos para integrações de assistência ao agente personalizadas

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

Aplicativos de agente com suporte

É possível utilizar o MAX e os CXone Agent aplicativos têm suporte para uso com integrações personalizadas de assistência a agentes.

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 CXone.

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

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

• "streamPerspective": "RX": o áudio que está sendo transmitido pelo telefone do agente: o agente falando.
• "streamPerspective": "TX": o áudio que o agente ouve: o contato falando ou várias pessoas se a interação for em 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, que fornece separação estéreo. Uma mistura de ambos em um único fluxo mono é possível. 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, será recebido.

Se a conexão cair ou tiver outros problemas, como pacotes perdidos, o terminal de assistência ao agente personalizado tentará 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 do websocket será encerrada. Quando a interação recomeçar, uma nova conexão websocket é iniciada. Ela espera um handshake idêntico ao original.

Autorização

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

Autorização para o túnel proxy

Se quiser que o túnel proxy exija autorização para solicitações quando elas passam por ele, é necessário incluir esse requisito em 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 autorização baseada em token, o script precisa solicitar um token, armazená-lo no 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 do Studio para se comunicar com o servidor de autenticação.

Se usar autorização dinâmica, você 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 a agentes

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

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

• Gerar o cabeçalho de autorização para usar em seus scripts de integração de assistência a agentes personalizados. Consulte a documentação do provedor de assistência ao agente para todas as configurações aplicáveis.
• Adicionar os cabeçalhos necessários ao aplicativo Custom Agent Assist Endpoint no Hub do Agent Assist. Se usar o aplicativo de assistência a agentes 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 a agentes 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 a agentes.

Requisitos de configuração da plataforma CXone

Não há alterações de configuração necessárias na plataforma CXone para configurar uma integração de assistência a agentes personalizada. Você pode modificar os scripts existentes para incluir o novo aplicativo de assistência a agentes. No entanto, algumas configurações podem ser necessárias dependendo de como sua organização está usando o novo aplicativo. Você pode precisar:

• Criar um novo canal Uma maneira de os contatos interagirem com agentes ou bots. Um canal pode ser voz, e-mail, chat, mídia social e assim por diante. de voz ou chat do ACD.
• Criar um novo perfil de chat para o chat do ACD.
• Criar uma ou mais competências ACD e atribuí-las aos agentes para os quais deseja que o aplicativo personalizado de assistência a agentes esteja disponível.
• Criar um ponto de contato para um novo canal.
• Modificar um ponto de contato O ponto de entrada que um contato de entrada usa para iniciar uma interação, como um número de telefone ou endereço de e-mail. existente para iniciar um novo script. Não faça essa alteração até que a integração de assistência a agentes personalizada esteja totalmente testada e pronta para ser colocada em produção.

Diagramas de sequência

Os diagramas de sequência mostram como várias partes de uma integração de assistência a agentes personalizada interagem e a ordem em que essas interações ocorrem. Eles mostram a linha do tempo de uma interação, começando no canto superior esquerdo, depois vai e volta até o final da página.

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

Requisitos e diretrizes de script do Studio

Use os exemplos a seguir como base para criar os scripts para integrar seu aplicativo de assistência a agentes com o 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:

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

Nos dois scripts, a carga útil dos parâmetros do script Snippet é opcional. Você só precisa incluí-la se precisar passar parâmetros para o aplicativo de assistência a agentes.

Para concluir a configuração do script:

• Atribuir o aplicativo de configuração Pontos de Extremidade Personalizados de Assistência do Agente à ação Agent Assist.

• Certifique-se de que a ação opcional Script Param Payload Snippet contenha o JSON de carga útil personalizada a ser enviado ao provedor de assistência a agentes.

• Garantir 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 trechos de inicialização ao script usando as ações Snippet. Você pode fazer isso para personalizar seu aplicativo de assistência do 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 assistência com criação de scripts no Studio, entre em contato com seu Representante de Contas do CXone, consulte a seção Guia de referência técnica da ajuda online do Studio ou visite o site da Comunidade NICE CXone.

Snippet de carga útil de parâmetros do script

Este snippet define os dados passados ao aplicativo de assistência do agente pela actionação Agent Assist. Adicione este código a uma actionação Snippet 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 o 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 actionação Agent Assist com o nome da variável que contém o JSON. No exemplo fornecido, isso seria customParamjson.

Scripts novos ou existentes

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

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ê poderá mover o script modificado de volta para a produção. Mova um script para produção seguindo um destes procedimentos:

• Salvando-o com o nome de um script que está atualmente em produção.
• Configurando um ponto de contato O ponto de entrada que um contato de entrada usa para iniciar uma interação, como um número de telefone ou endereço de e-mail. para usar o script. Você pode salvar o script com um novo nome antes de configurar o ponto de contato.

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

O túnel de proxy é o middleware entre o CXone e o terminal do seu aplicativo de assistência a agentes. Todas as solicitações e respostam passam por ele. Ele deve converter as solicitações do CXone em um formato que o aplicativo de assistência a agentes entenda. Da mesma forma, ele deve converter as respostas do aplicativo de assistência a agentes em um formato que o CXone entenda. Para fazer essas conversões, você deve mapear os terminais entre o CXone e o aplicativo de assistência a agentes.

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

• Ele fornece maior segurança porque há um único ponto de entrada em sua central de dados para gerenciar.
• Fornece failover e balanceamento de carga.
• Converte protocolos entre o CXone e o sistema do provedor de assistência a agentes.

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

As seguintes seções fornecem:

• Fatos importantes sobre integrações de assistência do agente personalizadas e os terminais de túnel proxy.
• Formato da solicitação de websocket inicial do CXone para interações de voz.
• Formato da resposta ao handshake para interações de voz.
• Formato da conexão do webhook para interações de chat.
• Formato para incluir os parâmetros de configuração com solicitações.

Principais fatos 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 a agentes 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 para cada usuário Alto nível de agrupamento organizacional usado para gerenciar o suporte técnico, cobrança e configurações globais para o seu ambiente CXone. O CXone tem uma API que você pode usar para obter dados em tempo real sobre o contactID. Para ver a documentação sobre a API, você precisa acessar o Portal do Desenvolvedor do CXone. Peça informações sobre o acesso ao seu Representante de Contas do CXone.

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 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:

• authenticationToken, streamsConfiguration, appParams e appConfig estão descritos na seção WebSocketHookInitializeMessage.
• systemTelemetryData está descrito em sua própria seção.
• streamPerspective está descrito em sua própria seção.

Conectar ao webhook de áudio: 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
}		
				
		

Ver uma imagem do código de exemplo

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

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

Conectar ao webhook de texto

Para receber dados de chat de texto, você precisa 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 Pontos de Extremidade Personalizados de Assistência do Agente no Hub do Agent Assist. 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 Hub do Agent Assist. 
	/// 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 Endpoint no Hub do Agent Assist. Isso é útil se o provedor de assistência a agentes exigir que determinados parâmetros sejam enviados com cada solicitação. Eles não são necessários. Todos os parâmetros adicionados são enviados no objeto agentAssistAppConfig no objeto WebHooksMessagesRequest. Por exemplo:

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

Terminais do CXone para integrações de assistência a agentes personalizadas

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

Terminais para aplicativos de assistência a agentes 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 especificação de websocket hook de áudio do CXone.

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 esquema WebSocketHookInitializeMessage e o esquema CXoneWebSocketMessage para saber os detalhes.

Terminais para aplicativos de assistência a agentes baseados em chat

POST ​/agent_assist_text_webhooks​/utterance: este terminal fornece um exemplo de recebimento de enunciados O que um contato diz ou digita. baseadas em texto em tempo real e de fornecimento de assistência a agentes 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 a agentes personalizados. Sempre verifique os esquemas na versão mais recente do documento do Swagger antes de usar essas 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 unidade de negócios Alto nível de agrupamento organizacional usado para gerenciar o suporte técnico, cobrança e configurações globais para o seu ambiente CXone do CXone onde o script está localizado.
requestId	Inteiro	Um número interativo 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. Os 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 unidade de negócios Alto nível de agrupamento organizacional usado para gerenciar o suporte técnico, cobrança e configurações globais para o seu ambiente CXone do CXone onde o script está localizado.
tenantId	string	O ID do locatário do CXone onde o script está localizado.
participantId	string	Indica se a mensagem inclui o contato (Patron), o agente (Agente), ou ambos (Sistema).
messageBody	string	O texto da mensagem.
messageMetaData		Contém parâmetros com 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 Hub do Agent Assist. Para aplicativos de assistência a agentes com grandes blobs de configuração, esse objeto pode incluir apenas 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 ao CXone do aplicativo de assistência a agentes.

{ additional parameters

}

StreamPerspective

Contém uma matriz de string com três valores possíveis. Este parâmetro reflete a configuração de Participantes feita no aplicativo Custom Agent Assist Endpoints no Hub do Agent Assist. 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 contidos neste objeto podem ser úteis para depuração, cobrança, relatórios e assim por diante.

{
	< * >:

}

WebSocketHookInitializeMessage

Esta é a estrutura da mensagem para a primeira carga útil de um cliente websocket conectado, como o servidor de mídia da NICE CXone.

{ parameters

}

{ parameters

}