Criar extensões de mensagem usando o Bot Framework

As extensões de mensagem criadas usando o Bot Framework (com base em bot) usam um serviço Web como um 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 redação de mensagem, a caixa de comando ou diretamente de uma mensagem e enviar de volta dados estruturados, como cartões.

A extensão de mensagem baseada em bot aproveita o esquema de mensagens e o protocolo de comunicação segura do Bot Framework. 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.

Observação

Os agentes fornecem uma experiência mais flexível, inteligente e pronta para o futuro que permite um raciocínio mais avançado, um desenvolvimento mais simples e um melhor alinhamento com o Teams em evolução e a plataforma Microsoft 365. Recomendamos que você explore e crie agentes.

Para obter mais informações, confira Criar agentes declarativos e Criar agentes no Teams.

Se você tiver uma extensão de mensagem baseada em bot existente, também poderá estendê-la como um agente .

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
Comandos de ação

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 card. 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 limite de tamanho do card de resultados é 28 KB. O card não será enviado se seu 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 propriedade e o query tipo no manifesto do aplicativo (anteriormente chamado de manifesto composeExtensions.commands do aplicativo do Teams). As descrições de comandos e parâmetros 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 composeExtensions seguir é um exemplo da 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 à sua composeExtensions.commands matriz 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.	Sim	1.0
`description`	Texto de ajuda indicando 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 LLMs (Large Language Models).	Não	1.17
`type`	Tipo de comando. O padrão é `query`.	Não	1.4
`initialRun`	Se essa propriedade for definida como true, isso indicará que esse comando deve ser executado assim que o usuário o selecionar 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 ao seu serviço na solicitação do usuário.	Sim	1.0
`parameter.description`	Descreve as finalidades do parâmetro ou 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 pelos Large Language Models (LLMs).	Não	1.17
`parameter.title`	Título ou rótulo de parâmetro curto e fácil de usar.	Sim	1.0
`parameter.inputType`	Defina como o tipo de entrada necessária. Os valores possíveis incluem `text`, `textarea`, `number`, `date`, `time`, `toggle`. O padrão é definido como `text`.	Não	1.4
`parameters.value`	Valor inicial para o parâmetro. O valor não é compatível	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

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 que você apresente 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 card e criar um comando de ação manualmente.

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

O código a composeExtensions seguir é um exemplo da 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 à sua composeExtensions.commands matriz de objetos:

Nome da propriedade	Objetivo	Obrigatório?	Versão do manifesto
`id`	ID exclusiva que você atribui a esse 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 `true` para um Cartão Adaptável ou exibição da Web incorporada para seu módulo de tarefa e`false` para uma lista estática de parâmetros ou ao carregar a exibição da Web por um `taskInfo`.	Não	1.4
`context`	Matriz opcional de valores que define de onde a extensão de 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 curto e fácil de usar.	Sim	1.0
`parameter.inputType`	Defina como o tipo de entrada necessária. 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 um modo de exibição da Web incorporado, poderá, opcionalmente, adicionar o objeto para buscar seu modo de exibição da Web sem chamar o taskInfo 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

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Criar extensões de mensagem usando o Bot Framework

Parâmetros

Próxima etapa

Confira também

Comentários

Recursos adicionais