Experiência de configuração do bot

Artigo
06/26/2024

A experiência de configuração do bot permite que os utilizadores configurem e reconfigurem as definições dos bots diretamente no canal ou no chat de grupo após a instalação, melhorando a eficiência operacional desde o início. Esta funcionalidade elimina a necessidade de intervenções repetidas do utilizador que anteriormente dificultavam a realização de benefícios oportunos das aplicações. Os utilizadores podem agora adaptar o bot aos seus fluxos de trabalho e preferências específicos durante a instalação e reconfigurar as definições conforme necessário para se adaptarem aos requisitos em mudança, garantindo a relevância e o valor contínuos do bot.

Por exemplo, considere um bot que controla e partilha tópicos de notícias ou monitoriza repositórios do GitHub. Inicialmente configurados para se alinharem com os fluxos de trabalho dos utilizadores, estes bots podem ser facilmente reconfigurados para responder a novos tópicos ou repositórios diretamente a partir do chat de grupo, simplificando a gestão de conteúdos e interação sem sair do ambiente do Teams. Esta experiência de configuração flexível melhora significativamente a experiência do utilizador e a produtividade ao integrar bots de forma totalmente integrada nas operações diárias.

Eis um exemplo, em que um utilizador adiciona o bot a uma conversa de grupo e, em seguida, configura-o para se alinhar com os requisitos específicos. Em seguida, o utilizador reconfigura o bot para alterar o estado.

Configurar

Gráfico a mostrar o processo de configuração de um bot num canal do Teams.

Reconfigurar

Captura de ecrã a mostrar a opção de configuração do bot na área de composição de mensagens.

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

Observação

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

Quando cria a experiência de configuração do bot, tem de garantir que o utilizador tem de conseguir configurar um bot na primeira instalação e reconfigurá-lo em qualquer altura.

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

Atualizar manifesto do aplicativo
Configurar o bot

Atualizar manifesto do aplicativo

No ficheiro de manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams), atualize a fetchTask propriedade abaixo do objeto da bots.configuration seguinte forma:

"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, veja esquema de manifesto de aplicação.

Configurar o bot

Quando um utilizador instala o bot num chat de canal ou grupo, a fetchTask propriedade no ficheiro de manifesto da aplicação é iniciada ou config/fetchconfig/submit conforme definido no teamsBot.js ficheiro.

Se definir a fetchTask propriedade no manifesto da aplicação para:

falso: o bot não obtém uma caixa de diálogo ou um Cartão Ajustável. Em vez disso, o bot tem de fornecer uma caixa de diálogo estática ou um cartão que é utilizado quando o bot é invocado. Para obter mais informações, veja caixas de diálogo.
true: o bot inicia ou config/fetchconfig/submit conforme definido. Quando o bot é invocado, pode devolver um Cartão Ajustável ou uma caixa de diálogo consoante o contexto fornecido em channelData e userdata.

A tabela seguinte lista o tipo de resposta associado aos pedidos de invocação:

Invocar pedido	Tipo de resposta
`config/fetch`	`Type: "continue"` ou `Type = "auth"`
`config/submit`	`Type: "continue"` ou `Type: "message"`

type: "continue": type: "continue" é utilizado para definir uma continuação de uma caixa de diálogo ou cartão ajustável numa configuração de bot. Quando o tipo está definido como continue, indica que o bot espera uma interação adicional do utilizador para continuar com o processo de configuração.

A adaptiveCardForContinue é uma função personalizada que devolve o JSON para que um Cartão Ajustável seja utilizado em diferentes fases do fluxo de trabalho de um bot. Estas funções são utilizadas para devolver Cartões Ajustáveis para diferentes cenários com base na interação do utilizador com o bot.

Quando o utilizador submete a configuração, a invocação é acionada config/submit . Lê a entrada do utilizador e devolve um Cartão Ajustável diferente. Também pode atualizar a configuração do bot para devolver uma caixa de diálogo.
- C#
- JavaScript
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);
}
```
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": também pode pedir ao utilizador para se autenticar como resposta ao config/fetch pedido. A type: "auth" configuração pede ao utilizador para iniciar sessão através de um URL especificado, que tem de estar ligado a uma página de autenticação válida que pode ser aberta num browser. A autenticação é essencial para cenários em que o bot exige que o utilizador seja autenticado. Garante que a identidade do utilizador é verificada, mantendo a segurança e as experiências personalizadas dentro da funcionalidade do bot.

Observação

Apenas type: "auth" para autenticação de terceiros é suportada. O início de sessão único (SSO) não é suportado. Para obter mais informações sobre a autenticação de terceiros, veja Adicionar autenticação.

C#
JavaScript

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"
    }
};

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 está definido como mensagem, indica que o bot está a enviar uma mensagem simples de volta para o utilizador, indicando o fim da interação ou fornecendo informações sem precisar de mais entradas.

C#
JavaScript

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

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 utilizador reconfigura o bot, a fetchTask propriedade no ficheiro de manifesto da aplicação é config/fetch iniciada na lógica do bot. O utilizador pode reconfigurar as definições do bot após a instalação de duas formas:

@mention o bot na área de composição de mensagens. Selecione a opção Definições que aparece acima da área de composição de mensagens. É apresentada uma caixa de diálogo, atualização ou altera as definições de configuração do bot na caixa de diálogo.
Paire o cursor sobre o bot e o cartão de perfil do bot é apresentado. Para atualizar ou alterar as definições de configuração do bot, selecione o ícone de definições no cartão de perfil do bot.

Práticas recomendadas

Se quiser ter uma configuração individual ao nível do canal do bot, certifique-se de que controla a configuração de acordo com o canal. Os dados de configuração não são armazenados e o payload de invocação inclui o channelData suficiente.
Forneça uma caixa de diálogo simples e simples que pede ao utilizador para introduzir as informações necessárias para que o bot funcione corretamente, como um URL, um caminho de área ou uma ligação de dashboard.
Evite enviar várias notificações ou pedidos de configuração após a instalação, uma vez que pode confundir os utilizadores.

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js	Manifesto
Aplicação de configuração de bot	Este código de exemplo descreve a configuração e reconfiguração dos bots no chat de equipa e de grupo com `continue` os tipos de resposta e `message` .	View	View	View
Aplicação de configuração de bot com autenticação	Este código de exemplo descreve a configuração e reconfiguração dos bots no chat de equipa e de grupo com `auth` os 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 a partir da equipa ou chat de grupo onde o bot está instalado.

Partilhar via

Experiência de configuração do bot

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

Atualizar manifesto do aplicativo

Configurar o bot

Práticas recomendadas

Exemplo de código

Guias passo a passo

Confira também

Recursos adicionais