Documentação do Oracle Cloud Infrastructure

Recursos

Aqui estão os recursos que você pode configurar no Oracle Web SDK.

Timestamps Absolutos e Relativos

  • Flag de recurso: timestampMode: 'relative' | 'absolute' (padrão: 'relative')
  • Configuração do recurso: timestampMode

Você pode ativar timestamps absolutos ou relativos para mensagens de chat. Os timestamps absolutos exibem a hora exata de cada mensagem. Os carimbos de data/hora relativos só são exibidos na mensagem mais recente e expressam o tempo em termos de segundos, dias, horas, meses ou anos atrás em relação à mensagem anterior.
A seguir, descrição de relativa-v-absoluta-timestamps.png
Descrição da ilustração relative-v-absolute-timestamps.png
A precisão Com os carimbos de data/hora absolutos, eles são ideais para tarefas de arquivamento, mas dentro do contexto limitado de uma sessão de chat, essa precisão é extraída da experiência do usuário porque os usuários devem comparar os carimbos de data/hora para descobrir a passagem de tempo entre as mensagens. Os timestamps relativos permitem que os usuários rastreiem a conversa facilmente por meio de termos como Há Pouco e Há alguns momentos que podem ser imediatamente compreendidos. Os timestamps relativos melhoram a experiência do usuário de outra forma, além de também simplificar suas tarefas de desenvolvimento: como os timestamps relativos marcam as mensagens em termos de segundos, dias, horas, meses ou anos atrás, você não precisa convertê-las em fusos horários.

Como os Timestamps Relativos Se Comportam

Como mencionado anteriormente, um timestamp relativo só é exibido na mensagem mais recente. Veja aqui o comportamento com um pouco mais de detalhes. Quando você configura o data e hora (timestampMode: 'relative' ou timestampMode: 'default'), um data e hora absoluto é exibido antes da primeira mensagem do dia como cabeçalho. Esse cabeçalho é exibido quando a conversa não foi limpa e mensagens mais antigas ainda estão disponíveis no histórico.
Descrição da primeira-mensagem-day.png seguinte
Descrição da ilustração First-Message-day.png

Um timestamp relativo será exibido em cada nova mensagem.
Veja a seguir a descrição da mensagem mais recente-timestamp.png
Descrição da ilustração most-recent-message-timestamp.png
Esse timestamp é atualizado nos seguintes intervalos regulares (segundos, minutos etc.) até que uma nova mensagem seja recebida.
  • Nos primeiros 10s
  • Entre 10s e 60s
  • Cada minuto entre 1m e 60m
  • Cada hora entre 1hr e 24hr
  • Cada dia entre 1d e 30d
  • Cada mês entre 1m e 12m
  • Todo ano após o primeiro ano
Quando uma nova mensagem é carregada no chat, o timestamp relativo na mensagem anterior é removido e um novo timestamp aparece na nova mensagem exibindo a hora relativa à mensagem anterior. Nesse ponto, o timestamp relativo é atualizado até que a próxima mensagem chegue.

Adicionar um Timestamp Relativo

Para adicionar um timestamp relativo:
  • Ativar timestamps relativos – timestampMode: 'relative'
  • Etapas opcionais:
    • Defina a cor do timestamp relativo – timestamp: '<a hexadecimal color value>'
    • Para habilidades multilíngues, localize o texto do timestamp usando estas chaves:
      Chave Texto Padrão Descrição
      relTimeNow Now O timestamp inicial, que é exibido nos primeiros 9 segundos. Esse timestamp também é exibido quando a conversa é redefinida.
      relTimeMoment a few moments ago Exibido por 10 a 60 segundos.
      relTimeMin {0}min ago Atualizações a cada minuto
      relTimeHr {0}hr ago Atualizações a cada hora
      relTimeDay {0}d ago Atualizações todos os dias do primeiro mês.
      relTimeMon {0}mth ago Atualizações todos os meses nos primeiros doze meses.
      relTimeYr {0}yr ago Atualizações a cada ano.
    • Use as definições timeStampFormat para alterar o formato do timestamp absoluto que é exibido antes da primeira mensagem de cada dia.

Conclusão Automática

  • Flag de recurso: enableAutocomplete: true (padrão: false)
  • Ativar cache no lado do cliente: enableAutocompleteClientCache
O preenchimento automático minimiza o erro do usuário, fornecendo frases efetivas que podem ser usadas como entrada direta e como sugestões. Para ativar esse recurso, atualize as definições do widget com enableAutocomplete: true e adicione um conjunto de mensagens otimizadas do usuário à página Criar Intenção. Uma vez ativado, um pop-up exibe essas mensagens depois que os usuários inserem três ou mais caracteres. As palavras nas mensagens sugeridas que correspondem à entrada do usuário são definidas em negrito. Desse ponto em diante, os usuários podem inserir suas próprias entradas ou optar por uma das mensagens de preenchimento automático.
Observação

Este recurso só está disponível em WebSocket.

A seguir, descrição de autocomplete-phrase-list.png
Descrição da ilustração autocomplete-phrase-list.png

Quando um assistente digital é associado ao canal Oracle Web, todas as declarações de amostra configuradas para qualquer uma das habilidades registradas para esse assistente digital pode ser usada como sugestões de preenchimento automático.

Envio automático de um campo

Quando um campo tem a propriedade autoSubmit definida como true, o cliente envia um FormSubmissionMessagePayload com o mapa submittedField contendo os valores de campo válidos que foram informados até o momento. Todos os campos que ainda não foram definidos (independentemente de serem obrigatórios) ou campos que violam uma validação do cliente não são incluídos no mapa submittedField. Se o próprio campo enviado automaticamente contiver um valor que não seja válido, a mensagem de envio não será enviada e a mensagem de erro do cliente será exibida para esse campo específico. Quando um envio automático for bem-sucedido, o partialSubmitField na mensagem de envio do formulário será definido como id do campo autoSubmit.

Substituindo um formulário de entrada anterior

Quando o usuário final envia o formulário, porque um campo tem autosubmit definido como true, a habilidade pode enviar um novo EditFormMessagePayload. Essa mensagem deve substituir a mensagem anterior do formulário de entrada. Definindo a propriedade de extensão do canal replaceMessage como true, você ativa o SDK para substituir a mensagem anterior do form de entrada pela mensagem atual do form de entrada.

Layout de RTL Automático

Quando a direção base da página do host é definida com <html dir="rtl"> para acomodar idiomas da direita para a esquerda (RTL), o widget de chat é automaticamente renderizado no lado esquerdo. Como o widget está alinhado à esquerda para idiomas RTL, seus ícones e elementos de texto são igualmente reposicionados. Os ícones ficam nas posições opostas de onde estariam em uma renderização da esquerda para a direita (LTR). Por exemplo, os ícones de envio, mic e anexo são invertidos para que os ícones mic e envio ocupem o lado esquerdo do campo de entrada (com o ícone de envio direcional apontando para a esquerda), enquanto o ícone de anexo fica no lado direito do campo de entrada. O alinhamento dos elementos de texto, como inputPlaceholder e chatTitle, se baseia no fato de o idioma do texto ser LTR ou RTL. Para os idiomas RTL, o texto inputPlaceHolder e chatTitle aparecem no lado direito do campo de entrada.

Avatars

Por padrão, nenhuma das mensagens no chat é acompanhada de avatares. No entanto, usando os parâmetros a seguir, você pode configurar avatares para a habilidade, o usuário e um avatar do agente quando a habilidade é integrada com suporte ao agente ao vivo.
  • avatarBot - O URL da origem da imagem ou a string de origem da imagem SVG exibida ao lado das mensagens da habilidade.
  • avatarUser - O URL da origem da imagem ou a string de origem da imagem SVG exibida ao lado das mensagens do usuário. Além disso, se a habilidade tiver uma integração de agente ao vivo, o SDK poderá ser configurado para mostrar outro ícone para mensagens do agente.
  • avatarAgent - O URL da origem da imagem ou a string de origem da imagem SVG que é exibida ao lado das mensagens do agente. Se esse valor não for fornecido, mas avatarBot estiver definido, o ícone avatarBot será usado.
Observação

Essas definições só podem ser informadas nas definições de inicialização. Elas não podem ser modificadas dinamicamente. 
new WebSDK({
URI: '<URI>',
//...,
icons: {
    avatarBot: '../assets/images/avatar-bot.png',
    avatarUser: '../assets/images/avatar-user.jpg',
    avatarAgent: '<svg xmlns="http://www.w3.org/2000/svg" height="24" width="24"><path d="M12 6c1.1 0 2 .9 2 2s-.9 2-2 2-2-.9-2-2 .9-2 2-2m0 9c2.7 0 5.8 1.29 6 2v1H6v-.99c.2-.72 3.3-2.01 6-2.01m0-11C9.79 4 8 5.79 8 8s1.79 4 4 4 4-1.79 4-4-1.79-4-4-4zm0 9c-2.67 0-8 1.34-8 4v3h16v-3c0-2.66-5.33-4-8-4z"/></svg>'
}
})

Sincronização de Conversa entre Guias

Flag de recurso: enableTabsSync: true (padrão: true)

Os usuários podem precisar abrir o site em várias abas por vários motivos. Com enableTabsSync: true, você pode sincronizar e continuar a conversa do usuário em qualquer guia, desde que os parâmetros de conexão (URI, channelId e userId) sejam os mesmos em todas as guias. Esse recurso garante que os usuários possam exibir mensagens da habilidade em qualquer guia e responder da mesma guia ou de qualquer outra. Além disso, se o usuário limpar o histórico de conversas em uma guia, ele também será excluído das outras guias. Se o usuário atualizar o idioma do bate-papo em uma guia, o idioma do bate-papo será sincronizado com as outras guias.

Há algumas limitações:
  • Uma nova guia é sincronizada com a(s) guia(s) existente(s) para as novas mensagens entre o usuário e a habilidade ao abrir. Se você não tiver configurado o SDK para exibir mensagens do histórico de conversas, o widget de chat inicial na nova guia aparecerá vazio quando aberto.
  • Se você tiver configurado o SDK para exibir o histórico de conversas, as mensagens do chat atual nas guias existentes aparecerão como parte do histórico de conversas em uma nova guia. A definição de disablePastActions como all ou postback pode impedir a interação com as ações das mensagens na nova guia.
  • O navegador Safari atualmente não suporta esse recurso.

Renderização de Mensagem Personalizada

Flag de recurso: delegate.render: (message) => boolean (default: undefined)

Use esse recurso para substituir a renderização de mensagem padrão pelo seu próprio modelo de mensagem personalizado. Para usar esse recurso, você precisa implementar a função de delegação render que usa o modelo de mensagem como entrada e retorna um flag booliano como saída. Ele deve retornar true para substituir a renderização padrão por sua renderização personalizada para um tipo de mensagem específico. Se false for retornado, a mensagem padrão será renderizada.
Observação

Para renderização personalizada, todo o tratamento de cliques da ação e a desativação ou ativação da ação devem ser tratados explicitamente.
Você pode usar qualquer componente de estrutura externa para a renderização da mensagem. Consulte as amostras de integração incluídas no diretório samples do SDK para verificar como você pode usar esse recurso com estruturas como React, Angular e Oracle JavaScript Extension Toolkit (JET).

Respostas Padrão do Cliente

Flag de recurso: enableDefaultClientResponse: true (padrão: false)

Use esse flag para fornecer respostas padrão do cliente juntamente com um indicador de digitação quando a resposta da habilidade tiver sido atrasada ou quando não houver resposta da habilidade. Se o usuário enviar a primeira mensagem/consulta, mas a habilidade não responder dentro do número de segundos definido pelo flag defaultGreetingTimeout, a habilidade poderá exibir uma mensagem de saudação configurada usando a string de tradução defaultGreetingMessage. Em seguida, o cliente verifica novamente a resposta da habilidade. O cliente exibirá a resposta da habilidade se ela tiver sido recebida, mas se não tiver sido recebida, o cliente exibirá uma mensagem de espera (configurada com a string de tradução defaultWaitMessage) em intervalos definidos por defaultWaitMessageInterval. Quando a espera pela resposta da habilidade excede o limite definido pelo flag typingIndicatorTimeout, o cliente exibe uma resposta lamentável ao usuário e interrompe o indicador de digitação. Você pode configurar a resposta de desculpas usando a string de tradução defaultSorryMessage.

Delegação

Configuração de recurso: delegate

O recurso de delegação define um delegado para receber callbacks antes de determinados eventos na conversa. Para definir um delegado, especifique o parâmetro delegate ou use o método setDelegate. O objeto delegado pode, opcionalmente, conter as funções delegadas beforeDisplay, beforeSend, beforePostbackSend, beforeEndConversation e render.
const delegate = {
    beforeDisplay: function(message) {
        return message;
    },
    beforeSend: function(message) {
        return message;
    },
    beforePostbackSend: function(postback) {
        return postback;
    },
    beforeEndConversation: function(message) {
        return new Promise((resolve, reject) => {
            setTimeout(() => {
                resolve(message);
            }, 2000);
        });
    },
    render: function(message) {
        if (message.messagePayload.type === 'card') {
            // Perform custom rendering for card using msgId
            return true;
        }
        return false;
    }
}

Bots.setDelegate(delegate);

beforeDisplay

O delegado beforeDisplay permite que a mensagem de uma habilidade seja modificada antes de ser exibida na conversa. A mensagem retornada pelo delegado é exibida em vez da mensagem original. A mensagem retornada não será exibida se o delegado retornar um valor falso como null, undefined ou false. Se o delegado apresentar erros, a mensagem original será exibida em vez da mensagem retornada pelo delegado. Use a delegação beforeDisplay para aplicar seletivamente o comportamento de link da WebView in-widget.

beforeSend

O delegado beforeSend permite que uma mensagem de usuário seja modificada antes de ser enviada ao servidor de chat como parte de sendMessage. A mensagem retornada pelo delegador é enviada à habilidade, em vez da mensagem original. A mensagem retornada pelo delegado não será definida se o delegado retornar um valor falso como null, undefined ou false; em seguida, a mensagem não será enviada. Se houver erros, a mensagem original será enviada em vez da mensagem retornada pelo delegado.

beforePostbackSend

O delegado beforePostbackSend é semelhante a beforeSend, aplicado apenas às mensagens de postback do usuário. O postback retornado pelo delegado é enviado à habilidade. Se retornar um valor falso, como null, undefined ou false, nenhuma mensagem será enviada.

beforeEndConversation

O delegado beforeEndConversation permitirá uma interceptação no final de um fluxo de conversas se alguma atividade de pré-saída precisar ser executada. O function recebe a mensagem de saída como seu parâmetro de entrada e deve retornar um Promise. Se esse Promise for resolvido com a mensagem de saída, a mensagem de saída CloseSession será enviada ao servidor de chat. Caso contrário, a mensagem de saída será impedida de ser enviada.
...

 beforeEndConversation: function(message) {
        return new Promise((resolve, reject) => {
            setTimeout(() => {
                resolve(message);
            }, 2000);
        });
    }

render

O delegado render permite substituir a renderização de mensagem padrão. Se a função delegar render retornar true para um tipo de mensagem específico, WebSDK criará um slot de espaço reservado em vez da renderização de mensagem padrão. Para identificar o espaço reservado, adicione o msgId da mensagem como o id do elemento. Na função delegar render, você pode usar esse identificador para obter a referência do espaço reservado e renderizar seu modelo de mensagem personalizado. Consulte Renderização de Mensagem Personalizada.

Botão de Início Arrastável e Widget

Flag de recurso: enableDraggableButton: true (padrão: false)

Às vezes, especialmente em dispositivos móveis nos quais o tamanho da tela é limitado, o widget de chat ou o botão de início podem bloquear conteúdo em uma página web. Ao definir enableDraggableButton: true, você pode permitir que os usuários arrastem do caminho o widget ou o botão de início quando ele está bloqueando a exibição. Esse flag só afeta o local do botão de início, não o widget de chat: o widget ainda será aberto em seu local original.

Indicador de Digitação Dinâmica

Flag de recurso: showTypingIndicator: 'true'

Um indicador de digitação instrui os usuários a adiarem o envio de uma mensagem porque a habilidade está preparando uma resposta. Por padrão, as habilidades exibem o indicador de digitação somente para a primeira resposta quando você inicializa o SDK com showTypingIndicator: 'true'. Para uma experiência ideal do usuário, a habilidade deve ter um indicador de digitação dinâmica, que é um indicador de digitação exibido após cada resposta de habilidade. Além de alertar os usuários de que a habilidade não sofreu timeout, e ainda está trabalhando ativamente em uma resposta, exibir o indicador de digitação após cada resposta de habilidade garante que os usuários não tentarão enviar mensagens prematuramente, como pode ser o caso quando a propriedade keepTurn direciona a habilidade para responder com uma série de mensagens separadas que não permitem que o usuário interpor uma resposta.

Para ativar um indicador de digitação após cada resposta de habilidade:
  • Inicialize o SDK com a propriedade showTypingIndicator definida como true.
  • Chame a API showTypingIndicator
O showTypingIndicator só pode ativar a exibição do indicador de digitação dinâmica quando:
  • O widget está conectado ao Oracle Chat Server. O indicador de digitação dinâmica não aparecerá quando a conexão for fechada.
  • O SDK for inicializado com a propriedade showTypingIndicator definida como true.
    Observação

    Esta API não pode funcionar quando o SDK é usado no modo sem interface do usuário.
O indicador de digitação é exibido pela duração definida pela propriedade opcional typingIndicatorTimeout, que tem a definição padrão de 20 segundos. Se a API for chamada enquanto um indicador de digitação já estiver sendo exibido, o timer será redefinido e o indicador ficará oculto.

O indicador de digitação desaparece assim que o usuário recebe as mensagens da habilidade. O indicador de digitação move-se para a parte inferior da janela de chat se um usuário digitar uma mensagem, fizer upload de um anexo ou enviar um local, enquanto ele estiver sendo exibido.

Controlar Comportamento de Link Incorporado

  • Tratamento personalizado: linkHandler: { onclick: <function>, target: '<string>' }
  • Na webview In-widget: linkHandler: { target: 'oda-chat-webview' }
  • Em uma nova janela: openLinksInNewWindow: 'true'

O Web SDK fornece várias maneiras de controlar o local de destino dos links de URL nas conversas. Por padrão, clicar em qualquer link na conversa abre o URL vinculado na nova guia. Você pode configurar o widget para abri-lo em um destino específico usando a definição linkHandler.

A definição linkHandler espera um objeto que pode ter dois campos opcionais, target e onclick. O campo de destino aceita uma string que identifica o local onde o URL vinculado deve ser exibido (uma guia, janela ou <iframe>). As seguintes palavras-chave têm significados especiais para onde carregar o URL:
  • '_self': o contexto de navegação atual.
  • '_blank': geralmente uma nova guia, mas você pode configurar navegadores para abrir uma nova janela.
  • '_parent': o contexto de navegação principal do atual. Se não houver contexto de navegação principal, o comportamento assumirá '_self' como padrão.
  • '_top': o contexto de navegação mais alto (ou seja, o contexto "mais alto" que é um ancestral do atual). Se não houver ancestrais, ele se comportará como '_self'. 
settings = {
    ...,
    linkHandler: { target: '_blank'}
};

const Bots = new WebSDK(settings);
Para abrir os links dentro de um iframe, você pode especificar seu atributo de nome na propriedade de destino.
<iframe name="container" width="400" height="300"></iframe>

<script>
  settings = {
      ...
      linkHandler: { target: 'container'}
  }

  const Bots = new WebSDK(settings);
</script>
A propriedade onclick de linkHandler permite adicionar um listener de eventos em todos os links de âncora na conversa. O listener é acionado antes de o link ser aberto e pode ser usado para executar ações com base no link. O listener recebe um objeto de evento como parâmetro que é gerado pela ação de clique. Você pode impedir que o link seja aberto retornando false do listener. O ouvinte também é vinculado ao elemento âncora que é clicado. O contexto se refere ao HTMLAnchorElement dentro do listener. Você pode definir uma ou ambas as propriedades da definição linkHandler, mas é necessário especificar um dos campos.
linkHandler: {
    onclick: function(event) {
        console.log('The element clicked is', this);
        console.log('The event fired from the click is', event);
        console.log('The clicked link is', event.target.href);
        console.log('Preventing the link from being opened');
        return false;
    }
}

Dica:

Em alguns cenários, talvez você queira substituir as preferências do navegador para abrir links explicitamente em uma nova janela. Para fazer isso, passe openLinksInNewWindow: true nas configurações.

Modo Incorporado

  • Flag de recurso: embedded: true (padrão: false)
  • Informe o ID do elemento do contêiner de destino: targetElement
Além das outras definições que personalizam a aparência do widget que executa o chat, você pode incorporar o próprio widget na página Web ao:
  • Adicionar embedded: true.
  • Definir a propriedade targetElement com o ID do elemento DOM (um componente HTML) usado como contêiner do widget (como 'container-div' no trecho de código a seguir). 
<head>
    <meta charset="utf-8">
    <title>Oracle Web SDK Sample</title>
    <script src="scripts/settings.js"></script>
     <script>
        const chatSettings = {
            URI: YOUR_URI,
            channelId: YOUR_CHANNELID,
            embedded: true,
            targetElement: 'container-div'
...

    </script> 
</head>
<body>
    <h3 align="center">The Widget Is Embedded Here!</h3>
</body>
           <div id="container-div" 
                style="height: 600px; width: 380px; padding: 0; text-align: initial">
            </div>
Observação

O widget ocupa toda a largura e altura do contêiner. Se não puder ser acomodado pelo contêiner, o widget não será exibido na página.

Encerrar a Sessão da Conversa

Flag de recurso: enableEndConversation: true (padrão: true)

A partir da Versão 21.12, o SDK adiciona um botão de fechamento ao cabeçalho do widget de chat por padrão (enableEndConversation: true) que permite aos usuários encerrar a sessão atual.
Esta é uma imagem do botão fechar no cabeçalho do widget de chat.

Depois que os usuários clicam nesse botão, o SDK os apresenta com um prompt de confirmação cujo texto ("Tem certeza de que deseja encerrar a conversa? Isso também limpará seu histórico de conversas.") você pode personalizar com as chaves endConversationConfirmMessage e endConversationDescription. Quando um usuário descarta o prompt clicando em Sim, o SDK envia à habilidade uma mensagem de evento que marca a sessão de conversa atual como encerrada. Em seguida, a instância se desconecta da habilidade, recolhe o widget de chat e apaga o histórico de conversas do usuário atual. Ele também gera um evento chatend no qual você pode se registrar:
Bots.on('chatend', function() {
    console.log('The conversation is ended.');
});
A abertura do widget de chat inicia depois uma nova sessão de conversa.
Observação

Você também pode encerrar uma sessão chamando o método Bots.endChat() (descrito na referência que acompanha o Oracle Web SDK disponível na página Downloads). Chamar esse método pode ser útil quando o SDK é inicializado no modo sem interface do usuário.

Focar na Primeira Ação em uma Mensagem

Flag de recurso: focusOnNewMessage: 'action' (padrão: 'input')

Para usuários que preferem a navegação pelo teclado (que inclui usuários avançados), você pode mudar o foco do campo de entrada do usuário para o primeiro (ou mais à esquerda) botão de ação em uma mensagem. Por padrão, o widget de chat define o foco novamente para o campo de entrada do usuário a cada nova mensagem (focusOnNewMessage: 'input'). Isso funciona bem para fluxos de caixas de diálogo que esperam uma grande quantidade de entrada textual do usuário, mas quando o fluxo de caixas de diálogo contém várias mensagens com ações, os usuários só podem selecionar essas ações usando o mouse ou a navegação inversa pela tecla tab. Para esse caso de uso, você pode alterar o foco para o primeiro botão de ação na mensagem da habilidade conforme ela é recebida definindo focusOnNewMessage: 'action'. Se a mensagem não contiver ações, o foco será definido como campo de entrada do usuário.

Atalhos e Teclas de Atalho

Ao definir o objeto hotkeys, você pode criar atalhos de combinação Alt Key que ativam ou mudam o foco para elementos de IU no widget de chat. Os usuários podem executar esses atalhos em vez de usar o mouse ou os gestos de toque. Por exemplo, os usuários podem inserir Alt + L para iniciar o widget de chat e Alt + C para recolhê-lo. Atribua as teclas do teclado a elementos usando os pares de chave/valor do objeto hotkeys. Por exemplo : 
const settings = {
    // ...,
    hotkeys: {
        collapse: 'c',  // Usage: press Alt + C to collapse the chat widget when chat widget is expanded
        launch: 'l'     // Usage: press Alt + L to launch the chat widget when chat widget is collapsed
    }
};
Ao criar estes pares de chave/valor:
  • Você só pode passar uma única letra ou dígito para uma chave.
  • É possível usar somente as teclas de teclado a-z e 0-9 como valores.
Você pode passar o atributo de tecla de atalho definindo as seguintes teclas.
Observação

O atributo não faz distinção entre maiúsculas e minúsculas.
Chave Elemento
clearHistory O botão que limpa o histórico de conversas.
close O botão que fecha o widget de chat e encerra a conversa.
collapse O botão que recolhe o widget de chat expandido.
input O campo de entrada de texto no rodapé do chat
keyboard O botão que alterna o modo de entrada de voz para texto.
language O menu de seleção que mostra a lista de seleção de idioma.
launch O botão de inicialização do widget de chat
mic O botão que alterna o modo de entrada de texto para voz.
send O botão que envia o texto de entrada para a habilidade.
shareMenu O botão do menu de compartilhamento no rodapé do chat
shareMenuAudio O item de menu no pop-up do menu de compartilhamento que seleciona um arquivo de áudio para compartilhamento.
shareMenuFile O item de menu no pop-up do menu de compartilhamento que seleciona um arquivo genérico para compartilhamento
shareMenuLocation O item de menu no pop-up do menu de compartilhamento que seleciona o local do usuário para compartilhamento.
shareMenuVisual O item de menu no pop-up do menu de compartilhamento que seleciona uma imagem ou um arquivo de vídeo para compartilhamento.

SDK sem Interface do Usuário

Flag de recurso: enableHeadless: true (padrão: false)

Semelhante aos browsers sem interface do usuário, o SDK também pode ser usado sem sua interface do usuário. O SDK mantém a conexão com o servidor e fornece APIs para enviar mensagens, receber mensagens e obter atualizações sobre o status da rede. Você pode usar essas APIs para interagir com o SDK e atualizar a interface do usuário. Para ativar esse recurso, especifique enableHeadless: true nas definições iniciais. A comunicação pode ser implementada da seguinte maneira:
  • Enviando mensagens - Chama Bots.sendMessage(message) para especificar qualquer payload para o servidor.
  • Recebendo mensagens - É possível fazer listening das respostas para usar Bots.on('message:received', <messageReceivedCallbackFunction>).
  • Obtendo atualização do status da conexão - Faz listening de atualizações sobre o status da conexão usando Bots.on('networkstatuschange', <networkStatusCallbackFunction>). O callback possui um parâmetro de status que é atualizado com valores de 0 a 3, cada um dos quais é mapeado para estados do WebSocket:
    • 0 : WebSocket.CONNECTING
    • 1: WebSocket.OPEN
    • 2: WebSocket.CLOSING
    • 3: WebSocket.CLOSED
    • Retornar sugestões para uma consulta – Retorna uma Promessa que resolve as sugestões da string de consulta fornecida. A Promessa será rejeitada se demorar muito (aproximadamente 10 segundos) para extrair a sugestão. 
      Bots.getSuggestions(utterance)
    .then((suggestions) => {
        const suggestionString = suggestions.toString();
        console.log('The suggestions are: ', suggestionString);
    })
    .catch((reason) => {
        console.log('Suggestion request failed', reason);
    });
    Observação

    Para usar essa API, é necessário ativar o preenchimento automático (
    enableAutocomplete: true
    ) e configurar o preenchimento automático para as intenções.

Chat multilíngue

O suporte ao idioma nativo do Web SDK permite que o widget de chat detecte o idioma de um usuário ou permita que os usuários selecionem o idioma da conversa. Os usuários podem alternar entre os idiomas, mas apenas entre as conversas, não durante, porque a conversa é redefinida sempre que um usuário seleciona um novo idioma.

Ativar o menu Language

Você pode ativar um menu que permita aos usuários selecionar um idioma preferencial em um menu drop-down definindo a propriedade multiLangChat com um objeto que contenha o array supportedLangs, que é composto por tags de idioma (lang) e labels de exibição opcionais (label). Fora desse array, você tem a opção de definir o idioma padrão com a chave primary (primary: 'en' no trecho de código a seguir).
multiLangChat: {
    supportedLangs: [{
        lang: 'en'
    }, {
        lang: 'es',
        label: 'Español'
    }, {
        lang: 'fr',
        label: 'Français'
    }, {
        lang: 'hi',
        label: 'हिंदी'
    }],
    primary: 'en'
}
Em um menu drop-down localizado no cabeçalho, o widget de chat exibe os idiomas suportados transmitidos. Além dos idiomas disponíveis, o menu também inclui uma opção Detectar Idioma. Quando um usuário seleciona um idioma nesse menu, a conversa atual é redefinida e uma nova conversa é iniciada com o idioma selecionado. O idioma selecionado pelo usuário persiste entre as sessões no mesmo browser; por isso, o idioma anterior do usuário é selecionado automaticamente quando o usuário visita de novo a habilidade por meio da página que contém o widget de chat.

Dica:

Você pode adicionar um listener de eventos para o evento chatlanguagechange (descrito na referência que acompanha o Oracle Web SDK disponível na página Downloads), que é acionado quando um idioma de bate-papo é selecionado no menu suspenso ou foi alterado.
Bots.on('chatlanguagechange', function(language) {
    console.log('The selected chat language is', language);
});
Veja o que você deve ter em mente ao configurar o menu suspenso de idiomas:
  • Defina no mínimo dois idiomas para permitir a exibição do menu drop-down.
  • A chave label é opcional para os idiomas suportados nativamente: fr é exibido como Francês no menu, es é exibido como Espanhol e assim por diante.
  • Os labels dos idiomas podem ser definidos dinamicamente, informando-os com a definição i18n. Você pode definir o label para qualquer idioma, transmitindo-o à chave language_<languageTag>. Esse padrão permite definir labels para qualquer idioma, suportado ou não, além de permitir traduções do próprio label em diferentes configurações regionais. Por exemplo :
    i18n: {
    en: {
        langauge_de: 'German',
        language_en: 'English',
        language_sw: 'Swahili',
        language_tr: 'Turkish'
    },
    de: {
        langauge_de: 'Deutsche',
        language_en: 'Englisch',
        language_sw: 'Swahili',
        language_tr: 'Türkisch'
    }
}
    Se a propriedade i18n incluir strings de tradução para o idioma selecionado, o texto de campos como o placeholder de entrada, o título do chat, o texto instantâneo dos botões e os títulos das dicas de ferramenta serão automaticamente alternados para o idioma selecionado. O texto do campo só pode ser alternado para outro idioma quando há strings de tradução para o idioma selecionado. Se essas strings não existirem, o idioma do texto do campo permanecerá inalterado.
  • O widget detecta automaticamente o idioma no perfil do usuário e ativa a opção Detectar Idioma se você omitir a chave primary.
  • Embora label seja opcional, se você tiver adicionado um idioma que não seja um daqueles suportados nativamente, adicione um rótulo para identificar a tag, especialmente quando não houver string i18n para o idioma. Por exemplo, se você não definir label: 'हिंदी', para lang: hi, a lista drop-down exibirá hi, contribuindo para uma experiência de usuário abaixo do ideal.

Desativar Menu de Idioma

A partir da Versão 21.12, você também pode configurar e atualizar o idioma de chat sem precisar também configurar o menu suspenso de seleção de idioma informando multiLangChat.primary na configuração inicial sem também informar um array multiLangChat.supportedLangs. O valor informado na variável primary é definido como o idioma de chat da conversa.

Detecção de Idioma

Além dos idiomas informados, o widget de chat exibe uma opção Detectar Idioma no drop-down. A seleção dessa opção instrui a habilidade a detectar automaticamente o idioma da conversa da mensagem do usuário e, quando possível, responder no mesmo idioma.
Observação

Se você omitir a chave primary, o widget detectará automaticamente o idioma no perfil do usuário e ativará a opção Detectar Idioma no menu.

Você pode atualizar dinamicamente o idioma selecionado chamando a API setPrimaryChatLanguage(lang). Se o lang informado corresponder a um dos idiomas suportados, esse idioma será selecionado. Quando nenhuma correspondência for encontrada, Detectar Idioma será ativado. Você também pode ativar a opção Idioma Detectado chamando a API setPrimaryChatLanguage('und'), em que 'und' indica indeterminado ou informando multiLangChat: {primary: null} ou multiLangChat: {primary: 'und'}.

Você pode atualizar o idioma de bate-papo dinamicamente usando a API setPrimaryChatLanguage(lang) mesmo quando o menu suspenso não tiver sido configurado. Por exemplo :
Bots.setPrimaryChatLanguage('fr')
Você pode atualizar dinamicamente o idioma, independentemente de o idioma de chat estar configurado inicialmente ou não.
Observação

O Reconhecimento de voz, quando configurado, está disponível quando os usuários selecionam um idioma suportado. Ela não estará disponível quando a opção Detectar Idioma estiver definida. A seleção de um idioma não suportado pelo reconhecimento de voz desativa a funcionalidade de reconhecimento até que um idioma suportado tenha sido selecionado.

Referência Rápida de Chat Multilingual

Para isso... ... Faça isto
Exibe o menu suspenso de seleção de idioma para usuários finais. Informe multiLangChat.supportedLangs.
Defina o idioma do bate-papo sem exibir o menu suspenso de seleção de idioma para os usuários finais. Informe multiLangChat.primary.
Definir um idioma padrão. Informe multiLangChat.primary com multiLangChat.supportedLangs. O valor primary deve ser um dos idiomas suportados incluídos no array.
Ativar detecção de idioma. Informe primary: null ou primary: 'und' com multiLangChat.
Atualize dinamicamente o idioma do chat. Chame a API setPrimaryChatLanguage(lang).

Webview In-Widget

Você pode configurar o comportamento do link em mensagens de chat para permitir que os usuários acessem páginas web dentro do widget de chat. Em vez de ter que alternar da conversa para exibir uma página em uma guia ou em outra janela do browser, um usuário pode permanecer no chat porque o widget de chat abre o link em uma Webview.

Configurar o Comportamento de Link para a Webview

Você pode aplicar a webview a todos os links ou, em um caso de uso mais típico, apenas a links selecionados. Você também pode personalizar a própria webview.
  • Para abrir todos os links na webview, informe linkHandler: { target: 'oda-chat-webview' } nas definições. Isso define o destino de todos os links como oda-chat-webview, que é o nome do iframe na webview.
  • Para abrir somente determinados links na webview, garantindo que outros links sejam abertos normalmente em outras guias ou janelas, use a delegação beforeDisplay. Para abrir uma ação de URL de mensagem específica na webview, substitua o valor 'url' do campo action.type por 'webview'. Quando o tipo de ação for 'webview' na função beforeDisplay, o botão de ação abrirá o link na webview quando clicado.

Abrir Links na Webview

Os links incorporados em uma página que é exibida na WebView só podem ser abertos na WebView quando são convertidos em um elemento âncora (<a>), com um atributo de destino definido como target="oda-chat-webview".

Personalizar o WebView

Você pode personalizar a WebView com a definição webViewConfig que aceita um objeto. Por exemplo :
{ referrerPolicy: 'no-referrer-when-downgrade', closeButtonType: 'icon', size: 'tall'
Os campos desse objeto são opcionais.
Observação

A configuração também pode ser atualizada dinamicamente especificando um objeto webViewConfig no método setWebViewConfig. Todas as propriedades do objeto são opcionais.
Campo Valor Descrição
accessibilityTitle String O nome do elemento de quadro WebView para Acessibilidade Web.
closeButtonIcon String A string do URL/SVG da imagem usada para exibir o ícone do botão Fechar.
closeButtonLabel String Título do label/dica de ferramenta do texto do botão Fechar.
closeButtonType
  • 'icon'
  • 'label'
  • 'iconWithLabel'
Define como o botão Fechar é exibido na WebView.
referrerPolicy ReferrerPolicy Indica qual referenciador enviar ao extrair o recurso do quadro. O valor da política referrerPolicy deve ser uma diretiva válida. A política padrão aplicada é 'no-referrer-when-downgrade'.
sandbox Um array de String Um array de strings de restrição válidas que permite a exclusão de determinadas ações dentro do quadro. As restrições que podem ser informadas para esse campo são incluídas na descrição do atributo sandbox em Documentos Web MDN.
size
  • 'tall'
  • 'full'
A altura da WebView em comparação com a altura do widget de chat. Quando definido como 'tall', é definido como 80% da altura do widget; quando definido como 'full', é igual à altura do widget.
title String O título que é exibido no cabeçalho do contêiner WebView.
Nem todos os links podem ser abertos na WebView. Estes são alguns motivos para isso:
  • As páginas que fornecem o cabeçalho de resposta X-frame-options: deny ou X-frame-options: sameorigin não podem ser abertas na WebView por causa das restrições do servidor que impedem que a página seja aberta em iframes. Nesses casos, a WebView apresenta o link novamente para o usuário para que ele possa abri-lo em uma nova janela ou guia.
  • Por causa das restrições do servidor, as páginas de autorização não podem ser abertas dentro de WebViews, pois as páginas de autorização sempre retornam X-frame-options: deny para evitar um ataque de roubo de clique.
  • Links externos, que não podem ser abertos corretamente na WebView. Somente links incorporados nas mensagens de conversa podem ser abertos na WebView.
    Observação

    Como mensagens externas são incompatíveis com a WebView, não direcione qualquer link externo a ser aberto na WebView.
Quando um link não pode ser aberto na WebView, o widget apresenta ao usuário um texto informativo e um link para a WebView, que abre a página em uma nova guia quando clicado. Você pode personalizar esse texto usando a string de tradução i18n webViewErrorInfoText:
settings = {
    URI: 'instance',
    //...,
    i18n: {
        en: {
            webViewErrorInfoText: 'This link can not be opened here. You can open it in a new page by clicking {0}here{/0}.'
        }
    }
}

Sondagem Longa

Flag de recurso: enableLongPolling: true (padrão: false)

O SDK usa WebSockets para conectar-se ao servidor e conversar com habilidades. Se, por algum motivo, o WebSocket estiver desativado na rede, as chamadas HTTP tradicionais podem ser usadas para conversar com a habilidade. Esse recurso é conhecido como sondagem longa, porque o SDK deve chamar ou sondar continuamente o servidor para extrair as últimas mensagens da habilidade. Este recurso de fallback pode ser ativado especificando enableLongPolling: true nas definições iniciais.

Indicador de Digitação para Conversas do Agente do Usuário

Flag de recurso: enableSendTypingStatus: booliano (padrão: false)

Esse recurso permite que os agentes verifiquem se os usuários ainda estão envolvidos na conversa enviando o status do usuário para o agente ao vivo. Quando enableSendTypingStatus é definido como true, o SDK envia um evento de status de digitação RESPONDING junto com o texto que está sendo digitado no momento pelo usuário para o Oracle B2C Service ou o Oracle Fusion Service. Isso, por sua vez, exibe um indicador de digitação no console do agente. Quando o usuário terminar de digitar, o SDK enviará um evento LISTENING ao serviço para ocultar o indicador de digitação na console do agente.

A configuração typingStatusInterval, que tem um valor mínimo de três segundos, acelera a atualização do status de digitação.

Para enviar um agente do Oracle B2C Service tanto o texto quanto ele está sendo digitado pelo usuário quanto o status de digitação, enableAgentSneakPreview (que por padrão é false) deve ser definido como true e o Sneak Preview deve ser ativado na configuração de chat do Oracle B2C Service.
Observação

Você não precisa configurar o status de digitação ao vivo no lado do usuário. O usuário pode ver o status de digitação do agente por padrão. Quando o agente está digitando, o SDK recebe uma mensagem de status RESPONDING que resulta na exibição de um indicador de digitação na exibição do usuário. Da mesma forma, quando o agente está ocioso, o SDK recebe uma mensagem de status LISTENING que oculta o indicador de digitação.

Reconhecimento de Voz

Flag de recurso: enableSpeech: true (padrão: false)

A definição de enableSpeech: true permite que o botão do microfone seja exibido no lugar do botão de envio sempre que o campo de entrada do usuário estiver vazio.

Sua habilidade também pode utilizar o reconhecimento de voz com o método startVoiceRecording(onSpeechRecognition, onSpeechNetworkChange) para iniciar a gravação e o método stopVoiceRecording para interromper a gravação. (Esses métodos estão descritos no Guia do Usuário que acompanha o SDK.)

Usando o flag enableSpeechAutoSend, você pode configurar se deseja ou não enviar o texto que é reconhecido da voz do usuário diretamente para o servidor de chat sem entrada manual do usuário. Ao definir essa propriedade como true (o padrão), você permite que a resposta de fala do usuário seja automaticamente enviada ao servidor de chat. Ao defini-la como false, você permite que o usuário edite a mensagem antes de enviá-la ao servidor de chat ou a exclui.

Visualizador de Voz

Configuração de recurso: enableSpeechAutoSend

O widget de chat exibe um visualizador de voz quando os usuários clicam no ícone de voz Imagem do ícone Fala do Visualizador de Voz., o widget de chat exibe um visualizador de voz. É um indicador de se o nível de áudio é suficientemente alto o suficiente para o SDK capturar a voz do usuário. A mensagem do usuário, como é reconhecida como texto, é exibida abaixo do visualizador.
Observação

O modo de voz é indicado quando o ícone de teclado Imagem do ícone de teclado. é exibido.
Descrição da voice-visualizer.png a seguir
Descrição da ilustração voice-visualizer.png
Devido à definição padrão de enableSpeechAutosend ser true (enableSpeechAutoSend: true), as mensagens são enviadas automaticamente depois de serem reconhecidas. A definição de enableSpeechAutoSend: false alterna o modo de entrada para texto depois que a mensagem de voz é reconhecida, permitindo que os usuários editem ou concluam suas mensagens usando texto antes de enviá-las manualmente. Como alternativa, os usuários podem concluir suas mensagens com voz por meio de um clique subsequente no ícone de voz antes de enviá-las manualmente.
Observação

O visualizador de voz é criado usando o AnalyserNode. Você pode implementar o visualizador de voz no modo sem interface do usuário usando o método startVoiceRecording. Consulte SDK para obter mais informações sobre o AnalyserNode e os níveis de frequência.