Experiência de configuração de bot

A experiência de configuração do bot permite que os usuários configurem e reconfigurem as configurações de seus bots diretamente no canal ou no chat de grupo após a instalação, aumentando a eficiência operacional desde o início. Essa funcionalidade elimina a necessidade de intervenções repetidas do usuário que antes dificultavam a realização oportuna de benefícios dos aplicativos. Agora, os usuários podem adaptar o bot a seus fluxos de trabalho e preferências específicos durante a instalação e reconfigurar as configurações conforme necessário para se adaptarem aos requisitos de alteração, garantindo a relevância e o valor contínuos do bot.

Por exemplo, considere um bot que rastreia e compartilha tópicos de notícias ou monitora repositórios do GitHub. Inicialmente configurados para se alinhar aos fluxos de trabalho do usuário, esses bots podem ser facilmente reconfigurados para responder a novos tópicos ou repositórios diretamente do chat de grupo, simplificando o gerenciamento de conteúdo e a interação sem sair do ambiente do Teams. Essa experiência de configuração flexível melhora significativamente a experiência e a produtividade do usuário integrando bots perfeitamente em operações diárias.

Aqui está um exemplo, em que um usuário adiciona o bot a um chat em grupo e o configura para se alinhar com seus requisitos específicos. Em seguida, o usuário reconfigura o bot para alterar o status.

Configurar

Reconfigurar

Experiência de configuração do bot de build

Observação

A experiência de configuração do bot só tem suporte no chat de canal ou grupo.

Ao criar a experiência de configuração do bot, você deve garantir que o usuário deve ser capaz de configurar um bot na primeira instalação e reconfigurá-lo a qualquer momento.

Para criar a experiência de configuração do bot, siga estas etapas:

1. Atualizar manifesto do aplicativo

2. Configurar seu bot

Atualizar manifesto do aplicativo

No arquivo manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo Teams), atualize a fetchTask propriedade sob o objeto da bots.configuration seguinte maneira:

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

Para obter mais informações, consulte esquema de manifesto do aplicativo.

Configurar seu bot

Quando um usuário instala o bot no canal ou no chat em grupo, a fetchTask propriedade no arquivo de manifesto do aplicativo inicia config/fetch ou config/submit conforme definido no teamsBot.js arquivo.

Se você definir a fetchTask propriedade no manifesto do aplicativo como:

• false: o bot não busca uma caixa de diálogo ou um Cartão Adaptável. Em vez disso, o bot deve fornecer uma caixa de diálogo estática ou cartão que é usada quando o bot é invocado. Para obter mais informações, consulte caixas de diálogo.

• true: o bot inicia ou config/fetchconfig/submit conforme definido. Quando o bot é invocado, você pode retornar um Cartão Adaptável ou uma caixa de diálogo, dependendo do contexto fornecido em channelData e userdata.

A tabela a seguir lista o tipo de resposta associado às solicitações de invocação:

Solicitação de invocação	Tipo de resposta
config/fetch	Type: "continue" ou Type = "auth"
config/submit	Type: "continue" ou Type: "message"

• type: "continue": type: "continue" é usado para definir uma continuação de uma caixa de diálogo ou Cartão Adaptável dentro de uma configuração de bot. Quando o tipo é definido como continue, ele indica que o bot está esperando uma interação adicional do usuário para continuar com o processo de configuração.

  A adaptiveCardForContinue é uma função personalizada que retorna o JSON para que um Cartão Adaptável seja usado em diferentes estágios do fluxo de trabalho de um bot. Essas funções são usadas para retornar Cartões Adaptáveis para diferentes cenários com base na interação do usuário com o bot.

  Quando o usuário envia a configuração, a config/submit invocação é disparada. Ele lê a entrada do usuário e retorna um Cartão Adaptável diferente. Você também pode atualizar a configuração do bot para retornar uma caixa de diálogo.

  C#

  Referência de código de exemplo

  protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
  {
      ConfigResponseBase response = adaptiveCardForContinue();
      return Task.FromResult(response);
  }
  

  JavaScript

  Referência de código de exemplo

  async handleTeamsConfigFetch(_context, _configData) {
      let response = {};
      const adaptiveCard = CardFactory.adaptiveCard(this.adaptiveCardForContinue());
      response = {
         config: {
            value: {
               card: adaptiveCard,
               height: 500,
               width: 600,
               title: 'test card',
            },
            type: 'continue',
         },
      };
      return response;
  }
  

---

• type: "auth": você também pode solicitar que o usuário se autentique como uma resposta à config/fetch solicitação. A type: "auth" configuração solicita que o usuário entre por meio de uma URL especificada, que deve ser vinculada a uma página de autenticação válida que pode ser aberta em um navegador. A autenticação é essencial para cenários em que o bot exige que o usuário seja autenticado. Ele garante que a identidade do usuário seja verificada, mantendo a segurança e experiências personalizadas dentro da funcionalidade do bot.

  Observação

  Para type: "auth" apenas autenticação de terceiros, há suporte. Não há suporte para SSO (logon único). Para obter mais informações sobre autenticação de terceiros, consulte adicionar autenticação.

  C#

  Referência de código de exemplo

  protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
  {
      ConfigResponseBase response = new ConfigResponse<BotConfigAuth> {
         Config = new BotConfigAuth {
            SuggestedActions = new SuggestedActions {
               Actions = new List<CardAction> {
                  new CardAction {
                     type: "openUrl",
                     value: "https://example.com/auth",
                     title: "Sign in to this app"
                  }
               }
            },
         Type = "auth"
      }
  };
  

  JavaScript

  Referência de código de exemplo

  async handleTeamsConfigFetch(_context, _configData) {
      let response = {};
      response = {
         config: {
            type: "auth",
            suggestedActions: {
               actions: [{
                  type: "openUrl",
                  value: "https://example.com/auth",
                  title: "Sign in to this app"
               }]
            },
        },
      };
      return response;
  }
  

---

• type="message": quando o tipo é definido como mensagem, ele indica que o bot está enviando uma mensagem simples de volta para o usuário, indicando o fim da interação ou fornecendo informações sem exigir mais entrada.

  C#

  Referência de código de exemplo

  protected override Task<ConfigResponseBase> OnTeamsConfigSubmitAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
  {
      ConfigResponseBase response = new ConfigResponse<TaskModuleResponseBase>
      {
         Config = new TaskModuleMessageResponse
         {
            Type = "message",
            Value = "You have chosen to finish setting up bot"
         }
      };
      return Task.FromResult(response);
  }
  

  JavaScript

  Referência de código de exemplo

  async handleTeamsConfigSubmit(context, _configData) {
      let response = {};
      response = {
         config: {
            type: 'message',
            value: 'You have chosen to finish setting up bot',
         },
      }
      return response;
  }
  

---

Quando um usuário reconfigura o bot, a fetchTask propriedade no arquivo de manifesto do aplicativo é config/fetch iniciada na lógica do bot. O usuário pode reconfigurar as configurações do bot após a instalação de duas maneiras:

• @mention o bot na área de composição de mensagens. Selecione a opção Configurações exibida acima da área de composição da mensagem. Uma caixa de diálogo aparece, atualiza ou altera as configurações de configuração do bot na caixa de diálogo.

  

• Passe o mouse sobre o bot, o perfil do bot cartão aparece. Para atualizar ou alterar as configurações do bot, selecione o ícone de configurações no perfil do bot cartão.

  

Práticas recomendadas

• Se você quiser ter uma configuração de nível de canal individual do bot, verifique se você acompanha a configuração de acordo com o canal. Os dados de configuração não são armazenados e a carga de invocação inclui o canal suficienteData.

• Forneça uma caixa de diálogo clara e amigável ao usuário que solicita que o usuário insira as informações necessárias para que o bot opere corretamente, como uma URL, um caminho de área ou um link dashboard.

• Evite enviar várias notificações ou solicitações de configuração após a instalação, pois isso pode confundir os usuários.

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js	Manifesto
Aplicativo de configuração de bot	Este código de exemplo descreve a configuração e a reconfiguração para bots em chat em equipe e em grupo com continue tipos de resposta e message .	View	View	View
Aplicativo de configuração de bot com auth	Este código de exemplo descreve a configuração e a reconfiguração para bots em chat em equipe e em grupo com auth tipos de resposta e message .	View	View	View

Guias passo a passo

Siga o guia passo a passo para configurar o bot durante a instalação ou após a instalação da equipe ou do chat em grupo em que o bot está instalado.

Confira também

• Criar bots para o Teams
• Cartões Adaptáveis