Pular para o conteúdo
AnnA Docs

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);

ou

  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);