AnnA Web Service

O AnnA Web Service é um recurso que possibilita a interação com a AnnA. Com ele, você pode compor os nós de um Fluxo de Trabalho da AnnA para que o bot possa ler e executar conforme desejar.

Como funciona

Ao criar um Web Service, você precisa registrá-lo na AnnA, para que ela gere as chaves necessárias para criptografia/descriptografia. Em seguida, adicione um nó de Web Service ao seu Fluxo de Trabalho da AnnA e selecione o Web Service que será executado.

Nosso sistema chamará o Web Service que você registrou e em seguida executará os contêiners na ordem que você os adicionou à estrutura.

Utilizando a classe AnnAWebService

Para o nó de Web Service da AnnA, você precisará da classe AnnaWebService para instanciar e adicionar contêiners a serem executados.

Exemplos:

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);

  var annaWs = new AnnaWebService(
    new AnnaWebServiceConfig()
    {
        EncryptionKey = YourEncryptionKey,
        DecryptionKey = YourDecryptionKey,
        InitializationVector = ivFromANNAEXEC
    }
  );

Adicionando um contêiner de mensagem:

  annaWs.AddMessageContainer("Hello AnnA!");

Você pode fazer Encadeamento de Métodos ao adicionar contêiners (Como em um builder):

  annaWs.AddMessageContainer("Hello AnnA!").AddTimeContainer(5);

Código de exemplo

  // Encryption and Decryption keys are available when you register a new Web Service in AnnA
  string encryptionKey = "YOUR_ENCRYPTION_KEY";
  string decryptionKey = "YOUR_DECRYPTION_KEY";
  string iv = form.Get("ANNAEXEC"); // form is a FormDataCollection, the IV will be sent to your API Route in the ANNAEXEC post variable

  // Create a new AnnaWS object then add some containers to it
  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWs
      .AddMessageContainer("Hello AnnA!")
      .AddQuestionContainer("What is 1 + 1?", new QuestionContainerOptions
      {
          RightAnswer = "S",
          PossibleAnswers = new string[] { "2", "two" }
      });

  // Now get the encrypted containers
  string encryptedContainers = annaWs.GetEncryptedContainers();

  // Send the response back to AnnA
  // Note: In .NET 5+ applications it is not required to create the HttpResponseMessage object,
  // simply returning "encryptedContainers" will produce the same results
  var response = new HttpResponseMessage(HttpStatusCode.OK);
  response.Content = new StringContent(encryptedContainers, Encoding.UTF8, "text/plain");

  return response;

Adicionando contêiner de mensagem

Envia uma mensagem para o usuário

Parâmetros:

Message: Obrigatório. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Hello123.
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.

Exemplo de utilização

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWs.AddMessageContainer("Hello AnnA!");

Adicionando contêiner ExecFunction

Executa uma ou mais Funções da AnnA.

Parâmetros:

Expression: Obrigatório. Escreva expressões com Funções da AnnA aqui, por exemplo, AddParm(Teste1,123) AddParm(Teste,456)
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.

Exemplo de utilização

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWS.AddExecFunctionContainer("AddParm(Test1,123) AddParm(Test2,456)");

Adicionando contêiner de Tempo

Espere alguns segundos antes de prosseguir com o fluxo de execução dos contêineres.

Parâmetros:

TimeToWait: Obrigatório. Define o tempo em segundos para pausar a execução.
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Time123.
- ShowMessage: Opcional. Se a mensagem deve ser exibida ou não. O padrão é ‘S’ (Mostrar a mensagem).
- Message: Opcional. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.

Exemplo de utilização

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWs.AddTimeContainer(5); // Wait 5 seconds

Adicionando contêiner Multimídia

Envia mídia para o usuário, como imagens, vídeos, áudios e documentos.

Parâmetros:

MediaURL: Obrigatório. O URL de download para um arquivo, por exemplo, https://your.domain/route/to/file.extension
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Media123.
- Message: Opcional. O texto que será enviado ao usuário, por exemplo, Olá Mundo!
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.

Exemplo de utilização

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWS.AddMultimediaContainer("https://learning.anna.center/Resources/AnnaIcon.png", new MultimediaContainerOptions
  {
      Message = "Message of the image"
  });

Adicionando contêiner de Questão

Envia uma pergunta para o usuário

Parâmetros:

Question: Obrigatório. A pergunta que será enviada ao usuário
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado..
- Competence: Opcional. Uma competência já registrada na empresa. Uma nova competência será criada se não existir na empresa.
- Subject: Opcional. Um assunto já registrado na empresa. Um novo assunto será criado se não existir na empresa.
- Topic: Opcional. Um tópico dentro do assunto. Será criado se não existir.
- IgnoreExecFluxo: Opcional. Ignora outras ações do usuário além de responder à pergunta atual ou encerrar todos os serviços.
- SensitiveData: Opcional. Informe ‘S’ para criptografar a resposta usando a chave de criptografia da empresa. Observe que ao recuperar a resposta usando as Funções da AnnA, ela também estará criptografada. O padrão é ‘N’.
- RightAnswer: Opcional. Ative este recurso se desejar verificar se a resposta está no array de respostas possíveis.
- RightAnswerValue: Opcional. Os pontos que serão ganhos pelo usuário se ele responder corretamente.
- AnswerType: Opcional. ‘N’ se não deseja enviar feedback sobre a resposta. ‘Q’ se deseja enviar feedback. Padrão é ‘N’.
- CorrectAnswerComment: Opcional. Quando answerType for ‘Q’, use esta configuração para enviar um feedback positivo ao usuário.
- IncorrectAnswerComment: Opcional. Quando o answerType for ‘Q’, use esta configuração para enviar um feedback negativo ao usuário.
- DynamicValidations: Opcional. Escreva expressões usando Funções da AnnA que retornem TRUE ou FALSE. A execução continuará quando a expressão retornar TRUE.
- ValidationError: Opcional. Defina uma mensagem para erros de validação quando dynamicValidations retornar FALSE.
- ValidationMask: Opcional. Defina uma máscara para a resposta do usuário.
- ExternalData: Opcional. Pode armazenar qualquer informação que você deseje recuperar com Funções da AnnA, por exemplo, “LastAnswerJSON()” ou “AnswersJSON()”.
- PossibleAnswers: Opcional. Se “rightAnswer” estiver definido como “S”, então esta propriedade deve ser fornecida. Uma coleção de strings contendo as possíveis respostas corretas para a pergunta.

Exemplo de utilização

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWS.AddQuestionContainer("What is 1 + 1?", new QuestionContainerOptions
  {
      RightAnswer = "S",
      PossibleAnswers = new string[] { "2", "two" }
  });

Adicionando contêiner de Alternativa

Envia uma pergunta de múltipla escolha para o usuário.

Parâmetros:

Question: Obrigatório. A pergunta que será enviada ao usuário
Alternatives: Obrigatório. Array que contém as alternativas.
- Alternative: Obrigatório. Texto da alternativa.
- Alias: Opcional. Alias da alternativa, pode ser usado para identificar a resposta do usuário em nós subsequentes.
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- ExhibitionRule: Opcional. Use Funções da AnnA para escrever uma expressão que retorne TRUE ou FALSE. Se a expressão retornar TRUE, o contêiner será executado.
- IsCorrectAnswer: Opcional. Disponível apenas quando a opção “rightAnswer” é definida como ‘S’. Use ‘S’ para marcar a alternativa como resposta correta.
- AlternativeValue: Opcional. Um valor para as alternativas que será usado em estatísticas.
- Order: Opcional. Ordem da alternativa.
- Comment: Opcional. Mensagem que será enviada ao usuário depois que ele selecionar a alternativa.
Opções
- Alias: Opcional. Use para identificar o contêiner após a execução do nó do Web Service, por exemplo, Function123.
- RestrictToGroup: Opcional. Preencha com os apelidos dos grupos de usuários registrados na empresa.
- BeforeExecutionRule: Opcional. Deve ser uma expressão. Você pode usar Funções da AnnA que retornem “true” ou “false” para decidir se este contêiner deve ser executado.
- Competence: Opcional. Uma competência já registrada na empresa. Uma nova competência será criada se não existir na empresa.
- Subject: Opcional. Um assunto já registrado na empresa. Um novo assunto será criado se não existir na empresa.
- Topic: Opcional. Um tópico dentro do assunto. Será criado se não existir.
- Enumeration: Opcional. Defina a enumeração das alternativas. N = Números, L = Letras, R = Romanos, I = Lista (Popup no WhatsApp), B = Botões (Botões no WhatsApp)
- Randomize: Opcional. Informe ‘S’ para embaralhar as alternativas. Padrão é ‘N’.
- RightAnswer: Opcional. Ative este recurso se desejar verificar se a resposta está no array de respostas possíveis.
- AnswerType: Opcional. ‘N’ se não deseja enviar feedback sobre a resposta. ‘Q’ se deseja enviar feedback. Padrão é ‘N’.
- AnswerTypeComment: Opcional. A mensagem que será enviada quando o usuário responder à pergunta.
- ExternalData: Opcional. Pode armazenar qualquer informação que você deseje recuperar com Funções da AnnA, por exemplo, “LastAnswerJSON()” ou “AnswersJSON()”.

Exemplo de utilização

  List<AnnaAlternative> alternatives = new List<AnnaAlternative>()
  {
      new AnnaAlternative
      {
          Alias = "Alternative001",
          Alternative = "2 two",
          Order = "1",
          IsCorrectAnswer = "S"
      },
      new AnnaAlternative
      {
          Alias = "Alternative002",
          Alternative = "5 five",
          Order = "2",
          IsCorrectAnswer = "N"
      }
  };

  var annaWs = new AnnaWebService(encryptionKey, decryptionKey, iv);
  annaWS.AddAlternativeContainer("What is 1 + 1?", alternatives);