Criar extensões de mensagens com o Bot Framework

As extensões de mensagens criadas com o Bot Framework (baseado em Bot) utilizam um serviço Web como bot. Pode utilizar extensões de mensagens para permitir que os utilizadores interajam com o seu serviço Web a partir de diferentes localizações no cliente do Teams, como a área de composição de mensagens, a caixa de comando ou diretamente a partir de uma mensagem e enviar dados estruturados de volta, como cartões.

A extensão de mensagens baseada em bot tira partido do esquema de mensagens do Bot Framework e do protocolo de comunicação seguro. O bot é definido no manifesto da aplicação para a aplicação Teams e também pode definir diferentes tipos de comandos para a 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. Pode utilizar um comando de pesquisa ou um comando de ação para interagir com o seu serviço Web através de um bot no Teams.

Comandos de pesquisa

Os comandos de pesquisa da extensão de mensagens permitem que os utilizadores pesquisem sistemas externos e insiram os resultados dessa pesquisa numa mensagem sob a forma de um card. Este documento orienta-o sobre como selecionar o comando de pesquisa invocar localizações e adicionar o comando de pesquisa ao manifesto da aplicação.

Observação

O limite de tamanho do resultado card é de 28 KB. O card não é enviado se o tamanho exceder os 28 KB.

Veja o seguinte vídeo para saber como definir comandos de pesquisa de extensões de mensagens:

O comando de pesquisa numa extensão de mensagem é configurado com a composeExtensions.commands propriedade e o query tipo no manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams). As descrições de comandos e parâmetros melhoram a usabilidade e a eficácia de uma extensão de mensagem. Uma boa descrição do comando oferece um resumo claro e conciso das funcionalidades da aplicação.

O código seguinte é um exemplo da propriedade que composeExtensions 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

Tem de adicionar os seguintes parâmetros à sua composeExtensions.commands matriz de objetos:

Nome da propriedade	Objetivo	Obrigatório?	Versão do manifesto
id	ID exclusivo que atribui ao comando de pesquisa. A solicitação do usuário inclui essa ID.	Sim	1.0
title	Nome do comando. Este valor aparece na interface de utilizador (IU).	Sim	1.0
description	Texto de ajuda que indica o que este comando faz. Esse valor aparece na interface do usuário.	Sim	1.0
semanticDescription	Descrição semântica do comando para consumo pelos Modelos de Linguagem Grandes (LLMs).	Não	1.17
type	Tipo de comando. O padrão é query.	Não	1.4
initialRun	Se esta propriedade estiver definida como true, indica que este comando deve ser executado assim que o utilizador selecionar este comando na IU.	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. A predefinição é compose,commandBox.	Não	1,5

Tem de adicionar os seguintes detalhes do parâmetro de pesquisa que definem o texto visível para o utilizador 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 o seu serviço no pedido de utilizador.	Sim	1.0
parameter.description	Descreve os objetivos do parâmetro ou o exemplo do valor que tem de ser fornecido. Esse valor aparece na interface do usuário.	Sim	1.0
parameter.semanticDescription	Descrição semântica do parâmetro para consumo pelos Modelos de Linguagem Grandes (LLMs).	Não	1.17
parameter.title	Título ou etiqueta abreviado do parâmetro amigável do utilizador.	Sim	1.0
parameter.inputType	Defina para o tipo de entrada necessária. Os valores possíveis incluem text, textarea, number, date, time, . toggle A predefinição está definida como text.	Não	1.4
parameters.value	Valor inicial para o parâmetro. O valor não é suportado	Não	1,5

Para obter mais informações, veja esquema de manifesto de aplicação.

Próxima etapa

Definir comando de pesquisa da 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 turncontext atividade de invocação.

Os comandos de ação permitem-lhe apresentar aos seus utilizadores um pop-up modal denominado módulo de tarefas 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 numa extensão de mensagem é configurado com a composeExtensions.commands propriedade e action escreva no manifesto da aplicação.

O código seguinte é um exemplo da propriedade que composeExtensions 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

Tem de adicionar os seguintes parâmetros à sua composeExtensions.commands matriz de objetos:

Nome da propriedade	Objetivo	Obrigatório?	Versão do manifesto
id	ID exclusivo que 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	true Defina como para um Cartão Ajustável ou vista Web incorporada para o módulo de tarefas efalse para uma lista estática de parâmetros ou ao carregar a vista Web por um taskInfo.	Não	1.4
context	Matriz opcional de valores que define a origem da extensão da mensagem. Os valores possíveis são message, compose ou commandBox. O valor padrão é ["compose", "commandBox"].	Não	1,5

Se estiver a utilizar uma lista estática de parâmetros, também tem de 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 os objetivos 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 etiqueta abreviado do parâmetro amigável do utilizador.	Sim	1.0
parameter.inputType	Defina para 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 estiver a utilizar uma vista Web incorporada, opcionalmente, pode adicionar o objeto para obter a taskInfo vista 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 estiver a utilizar um taskInfo objeto, tem de 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, veja esquema de manifesto de aplicação.

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