Definir comandos de ação de extensão de mensagensDefine messaging extension action commands

Importante

Os exemplos de código nesta seção são baseados em 4.6 e versões posteriores do SDK da Estrutura de Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Se você estiver procurando documentação para versões anteriores, consulte a seção Extensões de Mensagens - V3 SDK na pasta Recursos da documentação.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Os comandos de ação permitem que você apresente aos usuários um pop-up modal chamado módulo de tarefa Teams.Action commands allow you to present your users with a modal popup called a task module in Teams. O módulo de tarefa coleta ou exibe informações, processa a interação e envia as informações de volta para Teams.The task module collects or displays information, processes the interaction and sends the information back to Teams. Este documento orienta você sobre como selecionar locais de invocação de comando de ação, criar seu módulo de tarefa, enviar mensagem final ou cartão, criar comando de ação usando o app studio ou crie-o manualmente.This document guides you on how to select action command invoke locations, create your task module, send final message, or card, create action command using app studio, or create it manually.

Antes de criar o comando de ação, você deve decidir os seguintes fatores:Before creating the action command you must decide the following factors:

  1. De onde o comando de ação pode ser disparado?Where can the action command be triggered from?
  2. Como o módulo de tarefa será criado?How will the task module be created?
  3. A mensagem final ou o cartão será enviado para o canal de um bot ou a mensagem ou o cartão será inserido na área de mensagem de redação para o usuário enviar?Will the final message or card be sent to the channel from a bot, or will the message or card be inserted into the compose message area for the user to submit?

Selecionar locais de invocação de comando de açãoSelect action command invoke locations

Primeiro, você deve decidir o local de onde seu comando de ação deve ser invocado.First, you must decide the location from where your action command must be invoked. Especificando o context no manifesto do aplicativo, seu comando pode ser invocado de um ou mais dos seguintes locais:By specifying the context in your app manifest, your command can be invoked from one or more of the following locations:

  • Área de mensagem de redação: os botões na parte inferior da área de mensagem de composição.Compose message area: The buttons at the bottom of the compose message area.

  • Caixa de comando: @mentioning seu aplicativo na caixa de comando.Command box: By @mentioning your app in the command box.

    Observação

    Se a extensão de mensagens for invocada da caixa de comando, você não poderá responder com uma mensagem bot inserida diretamente na conversa.If messaging extension is invoked from the command box, you cannot respond with a bot message inserted directly into the conversation.

  • Mensagem: diretamente de uma mensagem existente por meio do ... menu de estouro em uma mensagem.Message: Directly from an existing message through the ... overflow menu on a message.

    Observação

    A invocação inicial ao bot inclui um objeto JSON que contém a mensagem da qual foi invocada.The initial invoke to your bot includes a JSON object containing the message from which it was invoked. Você pode processar a mensagem antes de apresentá-la com um módulo de tarefa.You can process the message before presenting them with a task module.

A imagem a seguir exibe os locais de onde o comando de ação é invocado:The following image displays the locations from where action command is invoked:

locais de invocação de comando de ação

Selecione como criar seu módulo de tarefasSelect how to create your task module

Além de selecionar de onde o comando pode ser invocado, você também deve selecionar como preencher o formulário no módulo de tarefas para seus usuários.In addition to selecting where your command can be invoked from, you must also select how to populate the form in the task module for your users. Você tem as três opções a seguir para criar o formulário renderizado dentro do módulo de tarefa:You have the following three options for creating the form that is rendered inside the task module:

  • Lista estática de parâmetros: este é o método mais simples.Static list of parameters: This is the simplest method. Você pode definir uma lista de parâmetros no manifesto do aplicativo que o cliente Teams renderiza, mas não pode controlar a formatação nesse caso.You can define a list of parameters in your app manifest the Teams client renders, but cannot control the formatting in this case.
  • Cartão Adaptável: você pode selecionar para usar um Cartão Adaptável, que fornece maior controle sobre a interface do usuário, mas ainda o limita nos controles disponíveis e opções de formatação.Adaptive Card: You can select to use an Adaptive Card, which provides greater control over the UI, but still limits you on the available controls and formatting options.
  • Exibição da Web incorporada : Você pode selecionar para inserir um exibição da Web personalizado no módulo de tarefas para ter um controle completo sobre a interface do usuário e os controles.Embedded web view: You can select to embed a custom web view in the task module to have a complete control over the UI and controls.

Se você selecionar para criar o módulo de tarefa com uma lista estática de parâmetros e quando o usuário enviar o módulo de tarefa, a extensão de mensagens será chamada.If you select to create the task module with a static list of parameters and when the user submits the task module, the messaging extension is called. Ao usar uma exibição da Web incorporada ou um Cartão Adaptável, sua extensão de mensagens deve manipular um evento de invocação inicial do usuário, criar o módulo de tarefa e devolvê-lo ao cliente.When using an embedded web view or an Adaptive Card, your messaging extension must handle an initial invoke event from the user, create the task module, and return it back to the client.

Selecione como a mensagem final é enviadaSelect how the final message is sent

Na maioria dos casos, o comando de ação resulta em um cartão inserido na caixa de mensagem de redação.In most cases, the action command results in a card inserted into the compose message box. O usuário pode enviá-lo para o canal ou chat.The user can send it into the channel or chat. Nesse caso, a mensagem vem do usuário, e o bot não pode editar ou atualizar o cartão ainda mais.In this case, the message comes from the user, and the bot cannot edit or update the card further.

Se a extensão de mensagens for invocada da caixa de redação ou diretamente de uma mensagem, seu serviço Web poderá inserir a resposta final diretamente no canal ou chat.If the messaging extension is invoked from the compose box or directly from a message, your web service can insert the final response directly into the channel or chat. Nesse caso, o Cartão Adaptável vem do bot, o bot o atualiza e responde ao thread de conversa, se necessário.In this case, the Adaptive Card comes from the bot, the bot updates it, and replies to the conversation thread if needed. Você deve adicionar o bot objeto ao manifesto do aplicativo usando a mesma ID e definindo os escopos apropriados.You must add the bot object to the app manifest using the same ID and defining the appropriate scopes.

Adicionar o comando de ação ao manifesto do aplicativoAdd the action command to your app manifest

Para adicionar o comando de ação ao manifesto do aplicativo, você deve adicionar um novo objeto ao nível superior do manifesto composeExtension do aplicativo JSON.To add the action command to the app manifest, you must add a new composeExtension object to the top level of the app manifest JSON. Você pode usar uma das seguintes maneiras de fazer isso:You can use one of the following ways to do so:

Criar um comando de ação usando o App StudioCreate an action command using App Studio

Observação

O pré-requisito para criar um comando de ação é que você já criou uma extensão de mensagens.The prerequisite to create an action command is that you have already created a messaging extension. Para obter informações sobre como criar uma extensão de mensagens, consulte create a messaging extension.For information on how to create a messaging extension, see create a messaging extension.

Para criar um comando de açãoTo create an action command

  1. Abra o App Studio no cliente Microsoft Teams e selecione a guia Editor de manifesto.Open App Studio from the Microsoft Teams client and select the Manifest editor tab.

  2. Se você já criou seu pacote de aplicativos no App Studio, selecione-o na lista.If you already created your app package in App Studio, select it from the list. Se você não tiver criado um pacote de aplicativos, importe um existente.If you have not created an app package, import an existing one.

  3. Depois de importar um pacote de aplicativos, selecione Extensões de mensagens em Recursos.After importing an app package, select Messaging extensions under Capabilities. Você tem uma janela pop-up para configurar a extensão de mensagens.You get a pop-up window to set up the messaging extension.

  4. Selecione Configurar na janela para incluir a extensão de mensagens na experiência do aplicativo.Select Set up in the window to include the messaging extension in your app experience. A imagem a seguir exibe a janela de configuração da extensão de mensagens:The following image displays the messaging extension set up window:

    messaging extension set up
  5. Para criar uma extensão de mensagens, você precisa de um bot registrado da Microsoft.To create a messaging extension, you need a Microsoft registered bot. Você pode usar um bot existente ou criar um novo bot.You can either use an existing bot or create a new bot. Selecione Criar nova opção bot, dê um nome para o novo bot e selecione Criar.Select Create new bot option, give a name for the new bot, and select Create. A imagem a seguir exibe a criação de bots para extensão de mensagens:The following image displays bot creation for messaging extension:

    create bot for messaging extension
  6. Selecione Adicionar na seção Comando da página extensões de mensagens para incluir os comandos que decidem o comportamento da extensão de mensagens.Select Add in the Command section of the messaging extensions page to include the commands which decides the behaviour of messaging extension.
    A imagem a seguir exibe a adição de comando para extensão de mensagens:The following image displays command addition for messaging extension:

    include command
  7. Selecione Permitir que os usuários acionem ações em serviços externos enquanto estão Teams.Select Allow users to trigger actions in external services while inside of Teams. A imagem a seguir exibe a seleção de comando de ação:The following image displays the action command selection:

    action command selection
  8. Para usar um conjunto estático de parâmetros para criar seu módulo de tarefa, selecione Definir um conjunto de parâmetros estáticos para o comando.To use a static set of parameters to create your task module, select Define a set of static parameters for the command.

    A imagem a seguir exibe a seleção de parâmetro estático do comando de ação:The following image displays the action command static parameter selection:

    action command static parameter selection

    A imagem a seguir exibe um exemplo de configuração de parâmetro estático:The following image displays an example static parameter set-up:

    action command static parameter set-up

    A imagem a seguir exibe um exemplo de teste de parâmetro estático:The following image displays an example static parameter testing:

    action command static parameter testing
  9. Para usar parâmetros dinâmicos, selecione Para Buscar um conjunto dinâmico de parâmetros do bot.To use dynamic parameters, select to Fetch a dynamic set of parameters from your bot. A imagem a seguir exibe a seleção do parâmetro de comando de ação:The following image displays the action command parameter selection:

    action command dynamic parameter selection
  10. Adicione uma ID de Comando e um Título.Add a Command Id and a Title.

  11. Selecione o local de onde você deseja invocar o comando de ação.Select the location from where you want to invoke the action command. A imagem a seguir exibe o local de invocação do comando de ação:The following image displays the action command invoke location:

    action command invoke location
  12. Selecione Salvar.Select Save.

  13. Para adicionar mais parâmetros, selecione o botão Adicionar na seção Parâmetros.To add more parameters, select the Add button in the Parameters section.

Criar um comando de ação manualmenteCreate an action command manually

Para adicionar manualmente o comando de extensão de mensagens baseada em ação ao manifesto do aplicativo, adicione os seguintes parâmetros à composeExtension.commands matriz de objetos:To manually add your action-based messaging extension command to your app manifest, you must add the following parameters to the composeExtension.commands array of objects:

Nome da propriedadeProperty name ObjetivoPurpose Obrigatório?Required? Versão mínima do manifestoMinimum manifest version
id Essa propriedade é uma ID exclusiva que você atribui a este comando.This property is an unique ID that you assign to this command. A solicitação do usuário inclui essa ID.The user request includes this ID. SimYes 1.01.0
title Essa propriedade é um nome de comando.This property is a command name. Esse valor aparece na interface do usuário.This value appears in the UI. SimYes 1.01.0
type Essa propriedade deve ser action um .This property must be an action. NãoNo 1.41.4
fetchTask Essa propriedade é definida como para um cartão adaptável ou exibição da Web incorporada para o módulo de tarefas e para uma lista estática de parâmetros ou ao carregar o visualização true da Web por um false taskInfo .This property is set to true for an adaptive card or embedded web view for your task module, andfalse for a static list of parameters or when loading the web view by a taskInfo. NãoNo 1.41.4
context Essa propriedade é uma matriz opcional de valores que define de onde a extensão de mensagens é invocada.This property is an optional array of values that defines where the messaging extension is invoked from. Os valores possíveis são message, compose ou commandBox.The possible values are message, compose, or commandBox. O valor padrão é ["compose", "commandBox"].The default value is ["compose", "commandBox"]. NãoNo 1,51.5

Se você estiver usando uma lista estática de parâmetros, também deverá adicionar os seguintes parâmetros:If you are using a static list of parameters, you must also add the following parameters:

Nome da propriedadeProperty name ObjetivoPurpose É necessário?Is required? Versão mínima do manifestoMinimum manifest version
parameters Essa propriedade descreve a lista estática de parâmetros do comando.This property describes the static list of parameters for the command. Use somente quando fetchTask for false .Only use when fetchTask is false. NãoNo 1.01.0
parameter.name Essa propriedade descreve o nome do parâmetro.This property describes the name of the parameter. Isso é enviado ao seu serviço na solicitação do usuário.This is sent to your service in the user request. SimYes 1.01.0
parameter.description Esta propriedade descreve as finalidades do parâmetro ou o exemplo do valor que deve ser fornecido.This property describes the parameter’s purposes or example of the value that should be provided. Esse valor aparece na interface do usuário.This value appears in the UI. SimYes 1.01.0
parameter.title Essa propriedade é um título ou rótulo de parâmetro fácil de usar.This property is a short user-friendly parameter title or label. SimYes 1.01.0
parameter.inputType Essa propriedade é definida como o tipo de entrada necessária.This property is set to the type of input required. Os valores possíveis text textarea incluem , number , , , , date time toggle .The possible values include text, textarea, number, date, time, toggle. O valor padrão é definido como text .The default value is set to text. NãoNo 1.41.4

Se você estiver usando uma exibição da Web incorporada, você pode, opcionalmente, adicionar o objeto para buscar sua taskInfo exibição da Web sem chamar seu bot diretamente.If you are using an embedded web view, you can optionally add the taskInfo object to fetch your web view without calling your bot directly. Se você selecionar essa opção, o comportamento será semelhante ao de usar uma lista estática de parâmetros.If you select this option, the behavior is similar to that of using a static list of parameters. Na medida em que a primeira interação com seu bot está respondendo à açãode envio do módulo de tarefas .In that the first interaction with your bot is responding to the task module submit action. Se você estiver usando um taskInfo objeto, deverá definir o fetchTask parâmetro como false .If you are using a taskInfo object, you must set the fetchTask parameter to false.

Nome da propriedadeProperty name ObjetivoPurpose É necessário?Is required? Versão mínima do manifestoMinimum manifest version
taskInfo Especifique o módulo de tarefa a ser pré-carregado ao usar um comando de extensão de mensagens.Specify the task module to preload when using a messaging extension command. NãoNo 1.41.4
taskInfo.title Título inicial do módulo de tarefa.Initial task module title. NãoNo 1.41.4
taskInfo.width Largura do módulo de tarefa, um número em pixels ou layout large padrão, como , medium ou small .Task module width, either a number in pixels or default layout such as large, medium, or small. NãoNo 1.41.4
taskInfo.height Altura do módulo de tarefa, um número em pixels ou layout large padrão, como , medium ou small .Task module height, either a number in pixels or default layout such as large, medium, or small. NãoNo 1.41.4
taskInfo.url URL de exibição da Web inicial.Initial web view URL. NãoNo 1.41.4

Exemplo de manifesto do aplicativoApp manifest example

A seção a seguir é um exemplo de um composeExtensions objeto que define dois comandos de ação.The following section is an example of a composeExtensions object defining two action commands. Não é um exemplo do manifesto completo.It is not an example of the complete manifest. Para o esquema de manifesto completo do aplicativo, consulte esquema de manifesto do aplicativo:For the complete app manifest schema, see app manifest schema:

...
"composeExtensions": [
  {
    "botId": "12a3c29f-1fc5-4d97-a142-12bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "addTodo",
        "description": "Create a To Do item",
        "title": "Create To Do",
        "type": "action",
        "context": ["commandBox", "message", "compose"],
        "fetchTask": true,
        "parameters": [
          {
            "name": "Name",
            "description": "To Do Title",
            "title": "Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "description": "Description of the task",
            "title": "Description",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "description": "Due date for the task",
            "title": "Date",
            "inputType": "date"
          }
        ]
      },
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Reassign a todo item",
        "type": "action",
        "fetchTask": true,
      }
    ]
  }
]
...

Exemplo de códigoCode sample

Exemplo de nomeSample Name DescriçãoDescription .NET.NET Node.jsNode.js
Teams ação de extensão de mensagensTeams messaging extension action Descreve como definir comandos de ação, criar módulo de tarefa e responder à ação de envio do módulo de tarefa.Describes how to define action commands, create task module, and respond to task module submit action. ViewView ViewView
Teams de extensão de mensagensTeams messaging extension search Descreve como definir comandos de pesquisa e responder a pesquisas.Describes how to define search commands and respond to searches. ViewView ViewView

Próxima etapaNext step

Se você estiver usando um Cartão Adaptável ou uma exibição da Web incorporada sem um objeto, a taskInfo próxima etapa será:If you are using either an Adaptive Card or an embedded web view without a taskInfo object, the next step is to:

Se você estiver usando os parâmetros ou uma exibição da Web incorporada com um objeto, a taskInfo próxima etapa será:If you are using the parameters or an embedded web view with a taskInfo object, the next step is to: