Uma conversa iniciada pelo aplicativo começa quando um aplicativo externo envia um evento para a habilidade ou para o assistente digital ao qual ele pertence. Existem algumas alterações que você precisa fazer na sua habilidade para que a conversa comece no local correto e exiba os valores desejados.

Um evento que é enviado de um aplicativo externo deve incluir um tipo de payload, que identifica exclusivamente o evento para a habilidade. Normalmente, o tipo de payload indica o que a habilidade deve fazer, como msgReminder ou cancelAppointment. O evento também pode incluir parâmetros em seu objeto JSON variables, como o nome de um paciente ou o horário de um compromisso.

Na habilidade, você deve garantir que haja um estado inicial no fluxo de caixas de diálogo para cada evento (vários eventos podem ter o mesmo estado inicial). Você também precisa adicionar variáveis no nível do fluxo para manter os valores do parâmetro, se houver. Em seguida, você precisa mapear o tipo de payload do evento para o estado inicial.

Para cada evento, execute as seguintes etapas:

1. Se seu aplicativo externo informar um objeto variables no payload da mensagem do evento, adicione variáveis no nível do fluxo para armazenar os valores das propriedades do objeto.

   O nome da variável no nível do fluxo deve corresponder ao nome da propriedade no objeto variables. Digamos, por exemplo, que o aplicativo externo enviará um corpo de solicitação como este para um evento de lembrete de compromisso:

   {
       "userId": "16035550100",
       "messagePayload": {
           "type": "application",
           "payloadType": "msgReminder",
           "channelName": "AppointmentUserChannel",
           "variables": {
           	"patientName": "Joe Doe",
           	"appointmentTime": "5:00 pm"
           }
       }
   }

2. Certifique-se de que seu fluxo de caixas de diálogo tenha um estado inicial para o evento.

   Dica:

   Se a plataforma de mensagem for somente texto, considere tornar a entrada do usuário menos propensa a erros, configurando a numeração automática no fluxo de caixas de diálogo da habilidade. Considere também mostrar ou ocultar texto com base na plataforma de mensagens. Consulte Canais Somente Texto.

3. Para mapear o evento para o estado inicial, clique em Definições , clique em Eventos e clique em + Adicionar Mapeamento. Em seguida, preencha estes campos:

   • Tipo de payload: Um nome que identifica exclusivamente o evento. O aplicativo externo deve usar esse nome para direcionar a mensagem ao estado aplicável.

     Use o tipo de payload do aplicativo externo em vez do nome do estado real, porque o tipo de payload é uma constante, enquanto o nome do estado poderá mudar se o fluxo de caixas de diálogo for revisado.

   • Nome do estado: O estado inicial do evento no fluxo de caixas de diálogo.

   Nesta captura de tela, o tipo de payload msgReminder é mapeado para o estado remindermessage no fluxo de caixas de diálogo.

   
   
   Descrição da ilustração event-map.png
   

   Quando você adiciona uma habilidade a um assistente digital, os mapeamentos de evento para estado da habilidade são adicionados à página Eventos do assistente digital automaticamente. Você acessa essa página na página Definições do assistente digital.

Se sua habilidade exigir que os usuários se autentiquem no Oracle Identity Cloud Service ou no Oracle Access Manager, você deverá configurar o canal do aplicativo, a habilidade e o aplicativo externo para permitir que a habilidade associe o ID do usuário autenticado ao ID do usuário do bot.

Para que os eventos enviados a uma habilidade autenticada pelo usuário funcionem, o usuário já deverá ter acessado o provedor de identidades pela habilidade. Por exemplo, digamos que Deva esteja usando uma habilidade para criar um relatório de despesas. Antes que ela possa fazer qualquer coisa na habilidade, a habilidade pede que ela faça login. Em seguida, a habilidade associa o ID de usuário autenticado dela ao ID de usuário que ela possui da plataforma de mensagens e aos parâmetros da plataforma de mensagens que são armazenados em cache no perfil do usuário.

Depois de concluir o relatório, ela pede para ser notificada quando a despesa for aprovada. A empresa dela usa um aplicativo externo para enviar o evento de notificação para a mesma habilidade. Para que o aplicativo envie o evento a uma habilidade autenticada pelo usuário, ele deverá enviar ao ID de usuário autenticado por Deva, em vez do ID de usuário da plataforma de mensagens. Dado o ID do usuário autenticado, a habilidade pode procurar o ID do usuário da plataforma e as informações do perfil armazenado no cache que obteve quando Deva conectou-se originalmente.

Se Deva nunca tiver acessado com base na habilidade, sua autenticação tiver expirado ou o cache de perfil tiver expirado, o serviço Digital Assistant responderá à solicitação de evento com um erro 500.

Além das etapas em Configurar a Qualificação, você deve concluir as seguintes etapas para configurar conversas iniciadas pelo aplicativo para habilidades autenticadas pelo usuário:

1. Se sua habilidade já tiver ativado a autenticação do usuário, vá para Definições > Serviços de Autenticação, abra o serviço e verifique se a opção Período de Retenção do Token de Atualização está definida como 14 dias, que corresponde à duração da expiração do cache do perfil do usuário. Esses valores devem ser sincronizados.

2. Se sua habilidade ainda não tiver ativado a autenticação do usuário, conclua estas etapas:

   1. Certifique-se de que um administrador tenha concluído as etapas em Registro do Provedor de Identidade.

   2. Crie um serviço de autenticação para o provedor de identidades, conforme descrito em Serviços de Autenticação.

   3. Certifique-se de que a opção Período de Retenção do Token de Atualização do serviço de autenticação esteja definida como 14 dias, que corresponde à duração da expiração do cache do perfil do usuário. Esses valores devem ser sincronizados.

   4. Para permitir que os usuários acessem a habilidade, adicione um estado para o componente Link da Conta OAuth 2.0 ao fluxo de caixas de diálogo, conforme descrito em OAuth 2.0 - Link da Conta.

3. Ao criar o canal do aplicativo, alterne Usar ID do Usuário Autenticado para Ativado. Ou, se ele já tiver sido criado, abra o canal e alterne-o para Ativado.

No corpo da solicitação que o seu aplicativo externo envia para o serviço Digital Assistant, lembre-se de definir a propriedade userId como o ID do usuário autenticado, conforme descrito em Configurar o Aplicativo Externo.

Para que as conversas iniciadas pelo aplicativo funcionem, você precisará criar um canal de usuário para vincular a habilidade à sua conta da plataforma de mensagens. Consulte estes tópicos para saber as etapas para criar um canal de usuário para a plataforma específica.

• Twilio/SMS
• Slack
• Microsoft Teams

Observe que, se você selecionar uma habilidade da lista Rotear para do canal, todas as mensagens do aplicativo externo enviadas para esse canal serão roteadas para a habilidade selecionada. No entanto, se você selecionar um assistente digital, será necessário especificar a habilidade de destino no payload da mensagem do aplicativo externo.

Crie um canal de aplicativos para permitir que o aplicativo externo envie mensagens para o Digital Assistant. Após a criação do canal, o serviço Digital Assistant designará uma chave secreta. Você precisa usar essa chave secreta no seu aplicativo externo.

1. Na barra de navegação esquerda, clique em Canais, clique em Aplicativos e, em seguida, clique em + Configuração do Aplicativo.

2. Digite um nome e opcionalmente uma descrição.

3. (Opcional) Todas as mensagens de erro relacionadas ao canal são registradas no arquivo de log do servidor. Se você também quiser que o Digital Assistant envie essas mensagens de erro para um web service externo, digite o URL do web service no campo URL do Aplicativo de Saída.

   Se ocorrer um erro, como um problema na inicialização de uma conversa por meio do canal de usuário, o serviço Digital Assistant enviará uma mensagem de erro como objeto JSON, com as propriedades botId, sessionId e message.

4. (Opcional) Se a habilidade direcionada exigir autenticação usando o componente Link da Conta OAuth 2.0, e seu aplicativo externo enviar o ID do usuário autenticado em vez do ID da plataforma de mensagens, alterne Usar ID do Usuário Autenticado para Ativado.

   Quando essa opção estiver ativada, o serviço Digital Assistant procurará o ID do usuário da plataforma de mensagens para o ID do usuário autenticado especificado. Observe que o usuário deverá ter acessado por meio da habilidade para que a pesquisa seja concluída com sucesso. Para obter mais detalhes, consulte Configurar uma Habilidade Autenticada pelo Usuário.

5. Clique em Criar.

6. Alterne Aplicativo Ativado para Ativado.

7. Anote a chave secreta e o URL de entrada. Eles serão usados pelo aplicativo externo.

   • Ele envia mensagens enviando a solicitação POST para o URL de entrada.
   • Ele usa a chave secreta para autenticar suas solicitações POST.

Se sua habilidade oferecer suporte a conversas iniciadas pelo aplicativo e você adicioná-la a um assistente digital, convém ajustar esses parâmetros de configuração na página Definições do assistente digital:

• Prompt de Interrupção: Esse prompt é exibido ao interromper um fluxo para iniciar outro.
• Ativar Numeração Automática em Ações de Postback: É uma boa prática verificar se essa definição está definida como true para todos os canais somente texto para que a entrada do usuário seja menos propensa a erros. Por padrão, essa definição é true para todos os canais do Twilio: ${(system.channelType=='twilio')?then('true','false')}

O aplicativo externo inicia um evento enviando uma solicitação POST para o URL de entrada de um canal do aplicativo. Veja aqui o que o aplicativo deve fazer para preparar e enviar a solicitação.

• Inclua estas propriedades no corpo da solicitação (exemplos a seguir):

  • userId: Deve ser um dos seguintes IDs:

    • ID do Usuário do Microsoft Bot: O ID do usuário do bot para o canal do Microsoft Bot. Esse ID é específico para cada canal do Microsoft Bot. A habilidade salva esse valor na variável profile.msBotUserId.

    • ID do Usuário do Slack: O ID do membro do usuário do Slack. A habilidade salva esse valor em system.message.channelConversation.userId.

    • ID do Canal do Twilio/SMS: O número do telefone celular do usuário. Deve ser um dos números que estão associados ao número de telefone da conta do Twilio que é especificado na configuração de canal do usuário do serviço Digital Assistant. A habilidade salva esse valor na variável profile.firstName.

    • ID do Usuário Gerado pelo Sistema: Se você estiver testando sua habilidade na Visualização, esse deverá ser o ID do usuário gerado pelo sistema para a sessão na Visualização. Consulte Testando Conversas Iniciadas pelo Aplicativo na Visualização.

    • ID do Usuário Autenticado: Se o canal do aplicativo associado estiver com a opção Usar ID do Usuário Autenticado definida como Ativado, este deverá ser o ID do usuário autenticado. O usuário com esse ID de usuário autenticado já deverá estar conectado à habilidade direcionada por meio do componente Link da Conta OAuth 2.0. Consulte Configurar uma Habilidade Autenticada pelo Usuário.

  • messagePayload: Este objeto contém:

    • type: Defina como application.

    • payloadType: O nome do evento (tipo de payload) mapeado para o estado inicial desejado no fluxo de caixas de diálogo. Consulte Configurar a Habilidade.

    • skillName e version: (Opcional) Se o canal do usuário da plataforma de mensagens for roteado para um assistente digital, você deverá incluir o skillName e a version da habilidade para que o assistente digital saiba para qual habilidade e versão enviar o evento.

    • channelName: O nome do canal do usuário da plataforma de mensagens configurado para a habilidade ou o assistente digital.

      Se você estiver testando sua habilidade na Visualização, precisará definir channelName com o nome do canal do Sistema. Consulte Testando Conversas Iniciadas pelo Aplicativo na Visualização.

    • variables: (Opcional) Pares de valor/chave a serem informados para as variáveis do fluxo de caixas de diálogo. Se as variáveis de fluxo correspondentes forem definidas no fluxo de caixas de diálogo, elas serão preenchidas com os valores informados por este objeto.

  • channelProperties: Este objeto destina-se ao MS Teams e ao Slack. Não é necessário incluir este objeto no corpo da solicitação se a opção Usar ID do Usuário Autenticado estiver ativada para o canal do usuário.

    Objeto channelProperties do MS Teams

    Este objeto é necessário se o usuário não tiver interagido com a conversa num período de 14 dias. Suas propriedades são:

    • botName: Este é o identificador de bot especificado quando você criou o registro de canal de bot, conforme descrito na Etapa 1: Criar um Bot. Esse valor é salvo na variável profile.botName.

    • tenantId: O ID do tenant do Microsoft Teams. Esse valor é salvo na variável profile.tenantId.

    • serviceUrl: O URL do serviço para o bot. Esse valor é salvo na variável profile.serviceUrl.

    Quando o usuário do Microsoft Teams conversa com a habilidade, o Digital Assistant captura e armazena esses valores no cache de perfil. Se o payload de solicitação de um evento não incluir o objeto channelProperties, a habilidade usará os valores do cache de perfil, se disponíveis (o cache expirará após 14 dias). A habilidade só usará os valores de perfil armazenados em cache se estiverem ausentes no corpo da solicitação.

    Quando seu fluxo de caixas de diálogo enviar uma solicitação de notificação para o backend, como por meio de um componente personalizado, ele deverá informar esses valores de perfil para o backend. Em seguida, o aplicativo externo poderá usar esses valores no objeto channelProperties, caso em que o cache de perfil poderá ter expirado. Este é um trecho de código do componente personalizado que obtém os valores para enviar ao backend.

        let serviceUrl = conversation.variable('profile.serviceUrl') ?
            conversation.variable('profile.serviceUrl') : "";
        let tenantId = conversation.variable('profile.tenantId') ? 
            conversation.variable('profile.tenantId') : "";
        let botName = conversation.variable('profile.botName') ?
            conversation.variable('profile.botName') : "";
        let msBotUserId = conversation.variable('profile.msBotUserId') ?       
            conversation.variable('profile.msBotUserId') : "";

    Objeto channelProperties do Slack

    Para o Slack, inclua estas propriedades no objeto channelProperties:

    • teamId: ID do espaço de trabalho do Slack. Esse valor é salvo na variável profile.team_id.

    • channel: ID do canal no espaço de trabalho. Ou seja, o canal do usuário. Esse valor é salvo na variável profile.channel.

    Você pode obter o ID da equipe e o canal do URL Web do Slack. Por exemplo, se o URL for https://app.slack.com/client/ABCDEFG/HIJKLMNOP, então, o ID da equipe será ABCDEFG e o canal será HIJKLMNOP.

  Aqui estão exemplos das diferentes plataformas de mensagem para habilidades que não usam IDs de usuário autenticado.

  Exemplo do Slack:

  { 
      "userId": "ABCDE712A3",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "teamId": "ABCDEFG",
              "channel":"HIJKLMNOP" 
          } 
      }
  }

  Exemplo do MS Teams:

  { 
      "userId": "12:1A2B3C3d....",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          },
          "channelProperties": {
              "tenantId": "ab12c34d-e56...",
              "botName":"my-bot",
              "serviceUrl":"https://example.com/path/"
          } 
      }
  }

  Exemplo do Twilio:

  { 
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  Este exemplo mostra como enviar um evento para um canal que é roteado para um assistente digital. Quando o canal for roteado para um assistente digital, você deverá incluir o nome e a versão da habilidade.

  {
      "userId": "1234567890",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "skillName": "myBot",
          "version": "1.0",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

  Aqui está um exemplo de uma habilidade autenticada pelo usuário (ou seja, o canal do aplicativo associado tem a opção Usar ID do Usuário Autenticado definida como Ativado). Este exemplo se aplica ao MS Teams, Slack e Twilio. Observe que, para o MS Teams e o Slack, você não inclui o objeto channelProperties quando roteia para uma habilidade autenticada pelo usuário.

  {
      "userId": "first.last@example.com",
      "messagePayload": {
          "type": "application",
          "payloadType": "msgReminder",
          "channelName": "AppointmentUserChannel",
          "variables": {
              "patientName": "Joe Doe",
              "appointmentTime": "5:00 pm"
          }
      }
  }

• Para autenticar a solicitação, adicione um cabeçalho X-Hub-Signature com um hash SHA256 do corpo usando a chave secreta do canal do aplicativo. Por exemplo :

  X-Hub-Signature: sha256={{HMAC SHA-256 signature of body}}

  A seção Usar Postman como um Aplicativo Externo no tutorial Enviar Lembretes Usando Conversas Iniciadas pelo Aplicativo mostra um exemplo de definição desse cabeçalho.

• Envie a solicitação POST para o URL de entrada do canal do aplicativo. A aparência deve ser semelhante à seguinte:

  POST https://<host>:<port>/connectors/v2/listeners/application/channels/4E09-42F7-ECB7A7F18F62

Você precisará do nome do canal do Sistema e do ID do usuário da Visualização para enviar suas mensagens do aplicativo externo para a Visualização. Quando um aplicativo externo envia uma mensagem para o canal do Sistema, o Oracle Digital Assistant roteia a mensagem para a Visualização que tem o ID do usuário especificado.

1. Para obter o nome do canal do Sistema, na barra de navegação esquerda, clique em Canais, clique em Sistema e examine o nome.

   O nome será System_Bot_Test ou System_Global_Test.

2. Para obter o ID do usuário da Visualização, abra a habilidade e clique em Visualizar .

3. Abra o Monitor de Rede selecionando primeiro Web Developer no menu do browser e, em seguida, clique em Rede.

4. Selecione XHR para exibir apenas as solicitações REST.

5. Digite uma mensagem na Visualização.

6. Depois que a habilidade gerar um texto, vá para o Monitor de Rede e verifique a guia Resposta.

   Selecione cada resposta até encontrar uma que contenha um messagePayload.

7. Digite userId no campo Propriedades do Filtro para exibir o valor do userId.

8. Deixe a Visualização ativa e não clique em Redefinir.

   Se você redefinir ou fechar a Visualização, o ID do usuário será alterado.

Depois de obter o nome do canal do Sistema e o ID do usuário do sistema, você poderá enviar mensagens do seu aplicativo externo para a Visualização da habilidade.

Para usar a Visualização em vez do serviço de mensagens, defina userId como ID do usuário da Visualização e channelName como nome do canal do Sistema, conforme mostrado aqui:

{
    "userId": "7319408",
    "messagePayload": {
        "type": "application",
        "payloadType": "msgReminder",
        "channelName": "System_Global_Test",
        "variables": {
        	"patientName": "Joe Doe",
        	"appointmentTime": "5:00 pm"
        }
    }
}