Criar extensões de mensagem usando o Bot Framework

As extensões de mensagem criadas usando o Bot Framework (baseado em Bot) usam um serviço Web como bot. Você pode usar extensões de mensagem para permitir que os usuários interajam com seu serviço Web de diferentes locais no cliente do Teams, como a área de mensagem de composição, a caixa de comando ou diretamente de uma mensagem e enviar dados estruturados de volta, como cartões.

A extensão de mensagem baseada em bot aproveita o esquema de mensagens do Bot Framework e o protocolo de comunicação segura. O bot é definido no manifesto do aplicativo para o aplicativo Teams e você também pode definir diferentes tipos de comandos para sua extensão de mensagem, como comandos de ação ou comandos de pesquisa.

Há dois tipos de comandos de extensão de mensagem: comando de ação e comando de pesquisa. O tipo de comando de extensão de mensagem define os elementos de interface do usuário e os fluxos de interação disponíveis para seu serviço Web. Você pode usar um comando de pesquisa ou um comando de ação para interagir com seu serviço Web por meio de um bot no Teams.

Comandos de pesquisa

Os comandos de pesquisa de extensão de mensagem permitem que os usuários pesquisem sistemas externos e insiram os resultados dessa pesquisa em uma mensagem na forma de um cartão. Este documento orienta você sobre como selecionar locais de invocação de comando de pesquisa e adicionar o comando de pesquisa ao manifesto do aplicativo.

Observação

O resultado cartão limite de tamanho é de 28 KB. O cartão não será enviado se o tamanho exceder 28 KB.

Confira o vídeo a seguir para saber como definir comandos de pesquisa de extensão de mensagem:

O comando de pesquisa em uma extensão de mensagem é configurado usando a composeExtensions.commands propriedade e o query tipo no manifesto do aplicativo (anteriormente chamado como manifesto do aplicativo teams). As descrições de comando e parâmetro aprimoram a usabilidade e a eficácia de uma extensão de mensagem. Uma boa descrição de comando oferece um resumo claro e conciso dos recursos do aplicativo.

O código a seguir é um exemplo da composeExtensions propriedade que define um comando de pesquisa:

{
 "composeExtensions": [
    {
      "botId": "eccdf132-0900-4d36-936b-dec5e6357f11",
      "commands": [
        {
          "id": "Dev",
          "type": "query",
          "title": "Jedi",
          "description": "May the force be with you",
          "initialRun": true,
          "fetchTask": false,
          "context": [
            "commandBox",
            "compose",
            "message"
          ],
          "parameters": [
            {
              "name": "Luke",
              "title": "Skywalker",
              "description": "Jedi master",
              "inputType": "text"
            }
          ]
        }
      ],
      "canUpdateConfiguration": true
    }
  ],

Parâmetros

Você deve adicionar os seguintes parâmetros à matriz composeExtensions.commands de objetos:

Nome da propriedade	Objetivo	Obrigatório?	Versão do Manifesto
id	ID exclusiva que você atribui ao comando de pesquisa. A solicitação do usuário inclui essa ID.	Sim	1.0
title	Nome do comando. Esse valor aparece na interface do usuário (interface do usuário).	Sim	1.0
description	Texto de ajuda que indica o que esse comando faz. Esse valor aparece na interface do usuário.	Sim	1.0
semanticDescription	Descrição semântica do comando para consumo pelo modelo de linguagem grande.	Não	1.17
type	Tipo de comando. O padrão é query.	Não	1.4
initialRun	Se essa propriedade estiver definida como true, ela indica que esse comando deve ser executado assim que o usuário selecionar esse comando na interface do usuário.	Não	1.0
context	Matriz opcional de valores que define o contexto em que a ação de pesquisa está disponível. Os valores possíveis são message, compose ou commandBox. O padrão é compose,commandBox.	Não	1,5

Você deve adicionar os seguintes detalhes do parâmetro de pesquisa que definem o texto visível para o usuário no cliente do Teams:

Nome da propriedade	Objetivo	É necessário?	Versão mínima do manifesto
parameters	Define uma lista estática de parâmetros para o comando.	Não	1.0
parameter.name	Descreve o nome do parâmetro. O parameter.name é enviado para seu serviço na solicitação de usuário.	Sim	1.0
parameter.description	Descreve as finalidades do parâmetro ou o exemplo do valor que deve ser fornecido. Esse valor aparece na interface do usuário.	Sim	1.0
parameter.semanticDescription	Descrição semântica do parâmetro para consumo pelo modelo de linguagem grande.	Não	1.17
parameter.title	Título ou rótulo de parâmetro amigável ao usuário curto.	Sim	1.0
parameter.inputType	Defina como o tipo da entrada necessária. Os valores possíveis incluem , , , , , toggletime. datenumbertextareatext O padrão é definido como text.	Não	1.4
parameters.value	Valor inicial para o parâmetro. Atualmente, o valor não tem suporte	Não	1,5

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

Próxima etapa

Definir comando de pesquisa de extensão de mensagem

Comandos de ação

Observação

Quando uma ação de mensagem é iniciada, os detalhes do anexo não são enviados como parte da atividade de invocação turncontext .

Os comandos de ação permitem apresentar aos usuários um pop-up modal chamado módulo de tarefa no Teams. O módulo de tarefa coleta ou exibe informações, processa a interação e envia as informações de volta para o 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 criar manualmente.

O comando de ação em uma extensão de mensagem é configurado usando a composeExtensions.commands propriedade e action digite no manifesto do aplicativo.

O código a seguir é um exemplo da composeExtensions propriedade que define um comando de ação:

"composeExtensions": [
        {
            "botId": "xxxxxx-xxx-bot-ID-xxxxxxxx}",
            "commands": [
                {
                    "id": "createCard",
                    "context": [
                        "compose",
                        "message",
                        "commandBox"
                    ],
                    "description": "Command to run action to create a Card from Compose Box",
                    "title": "Create Card",
                    "type": "action",
                    "parameters": [
                        {
                            "name": "title",
                            "title": "Card title",
                            "description": "Title for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "subTitle",
                            "title": "Subtitle",
                            "description": "Subtitle for the card",
                            "inputType": "text"
                        },
                        {
                            "name": "text",
                            "title": "Text",
                            "description": "Text for the card",
                            "inputType": "textarea"
                        }
                    ]
                }
            ]
        }
    ]

Parâmetros

Você deve adicionar os seguintes parâmetros à matriz composeExtensions.commands de objetos:

Nome da propriedade	Objetivo	Obrigatório?	Versão do Manifesto
id	ID exclusiva que você atribui a este comando. A solicitação do usuário inclui essa ID.	Sim	1.0
title	Nome do comando. Esse valor aparece na interface do usuário.	Sim	1.0
type	Tipo de extensão de mensagem. O padrão é action.	Não	1.4
fetchTask	Defina como para true um Cartão Adaptável ou exibição da Web inserida para o módulo de tarefas efalse para uma lista estática de parâmetros ou ao carregar o modo de exibição da Web por um taskInfo.	Não	1.4
context	Matriz opcional de valores que define de onde a extensão da mensagem é invocada. Os valores possíveis são message, compose ou commandBox. O valor padrão é ["compose", "commandBox"].	Não	1,5

Se você estiver usando uma lista estática de parâmetros, também deverá adicionar os seguintes parâmetros:

Nome da propriedade	Objetivo	É necessário?	Versão mínima do manifesto
parameters	Descreve a lista estática de parâmetros para o comando. Use somente quando fetchTask for false.	Não	1.0
parameter.name	Descreve o nome do parâmetro. Isso é enviado ao seu serviço na solicitação do usuário.	Sim	1.0
parameter.description	Descreve as finalidades do parâmetro ou o exemplo do valor que deve ser fornecido. Esse valor aparece na interface do usuário.	Sim	1.0
parameter.title	Título ou rótulo de parâmetro amigável ao usuário curto.	Sim	1.0
parameter.inputType	Defina como o tipo de entrada necessário. Os valores possíveis incluem text, textarea, number, date, time, toggle. O valor padrão é definido como text.	Não	1.4

Se você estiver usando uma exibição da Web inserida, opcionalmente poderá adicionar o taskInfo objeto para buscar sua exibição da Web sem chamar o bot diretamente. Se você selecionar essa opção, o comportamento será semelhante ao do uso de uma lista estática de parâmetros. Já que a primeira interação com o bot é responder à ação de envio do módulo de tarefa. Se você estiver usando um taskInfo objeto, deverá definir o fetchTask parâmetro como false.

Nome da propriedade	Objetivo	É necessário?	Versão mínima do manifesto
taskInfo	Especifique o módulo de tarefa a ser pré-carregado ao usar um comando de extensão de mensagem.	Não	1.4
taskInfo.title	Título do módulo de tarefa inicial.	Não	1.4
taskInfo.width	Largura do módulo de tarefa, um número em pixels ou layout padrão, como large, medium ou small.	Não	1.4
taskInfo.height	Altura do módulo de tarefa, um número em pixels ou layout padrão, como large, medium ou small.	Não	1.4
taskInfo.url	URL inicial do modo de exibição da Web.	Não	1.4

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

Próxima etapa

Definir comandos de ação de extensão de mensagem

Confira também

• Ações Universais para extensões de mensagens baseadas em pesquisa
• Extensão de mensagem baseada em API