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

Antes de criar o comando de ação, você deve decidir os seguintes fatores:

1. De onde o comando de ação pode ser disparado?
2. Como é criada a caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x)?
3. A mensagem ou cartão final é enviado para o canal a partir de um bot ou a mensagem ou cartão é inserido na área de composição de mensagens para o utilizador submeter?

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

Primeiro, você deve decidir o local de onde o comando de ação deve ser invocado. Quando especificar a context propriedade no manifesto da aplicação (anteriormente denominado manifesto de aplicação do Teams), o comando pode ser invocado a partir de uma ou mais das seguintes localizações:

• Área redigir mensagem: os botões na parte inferior da área de mensagem de redação.

  Contexto de comandos = compose

• Caixa de comando: ao utilizar / na caixa de comando. Por exemplo, /your-app-name. Se estiver a utilizar o Teams clássico, o comando de ação é invocado na @mentioning caixa de comando. Por exemplo, @your-app-name.

  Contexto de comandos = commandBox

  Observação

  Se uma extensão de mensagem for invocada a partir da caixa de comando, não poderá responder com uma mensagem de bot inserida diretamente na conversação.

• Mensagem: Diretamente de uma mensagem existente por meio do menu de estouro ... em uma mensagem.

  Contexto de comandos = message

  Observação

  • A invocação inicial para o bot inclui um objeto JSON que contém a mensagem da qual ele foi invocado. Pode processar a mensagem antes de apresentar uma caixa de diálogo.

  • Quando o utilizador seleciona as reticências ..., é apresentado um menu de capacidade excedida. No entanto, por predefinição, as ações de mensagens para aplicações criadas por si para a sua organização ou aplicações de terceiros não são apresentadas. Depois de o utilizador selecionar Mais ações, pode ver as ações da mensagem e selecionar a opção necessária. A respetiva ação de mensagem é apresentada no menu de capacidade excedida. O menu de capacidade excedida apresenta as três ações de mensagens mais recentes. Não é possível afixar a ação da mensagem a apresentar.

A imagem a seguir exibe os locais dos quais o comando de ação é invocado:

Selecione como criar a sua caixa de diálogo

Para além de selecionar a partir de onde o comando pode ser invocado, também tem de selecionar como preencher o formulário na caixa de diálogo para os seus utilizadores. Tem as três opções seguintes para criar o formulário que é composto dentro da caixa de diálogo:

• Lista estática de parâmetros: Esse é o método mais simples. Pode definir uma lista de parâmetros no manifesto da aplicação que o cliente do Teams compõe, mas não pode controlar a formatação neste caso.
• Cartão Ajustável: pode optar por utilizar um Cartão Ajustável, que fornece um maior controlo sobre a IU, mas ainda o limita nas opções de formatação e controlos disponíveis.
• Vista Web incorporada: pode optar por incorporar uma vista Web personalizada na caixa de diálogo para ter um controlo completo sobre a IU e os controlos.

Se optar por criar a caixa de diálogo com uma lista estática de parâmetros e quando o utilizador submeter a caixa de diálogo, a extensão da mensagem é chamada. Ao utilizar uma vista Web incorporada ou um Cartão Ajustável, a extensão de mensagem tem de processar um evento de invocação inicial do utilizador, criar a caixa de diálogo e devolvê-la ao cliente.

Selecione como a mensagem final é enviada

Na maioria dos casos, o comando de ação resulta em um cartão inserido na caixa de mensagem de redação. O usuário pode enviá-lo para o canal ou chat. Neste caso, a mensagem é proveniente do utilizador e o bot não pode editar ou atualizar o cartão mais detalhadamente.

Se a extensão da mensagem for invocada da caixa de redação ou diretamente de uma mensagem, o serviço Web poderá inserir a resposta final diretamente no canal ou chat. Nesse caso, o Cartão Adaptável vem do bot, o bot o atualiza e responde ao thread de conversa, se necessário. Tem de adicionar o bot objeto ao manifesto da aplicação com o mesmo ID e definir os âmbitos adequados.

Comando Criar ação com o Portal do Programador

Pode criar um comando de ação com o Teams Toolkit e o Portal do Programador para Teams.

Kit de ferramentas do Teams

Para criar uma extensão de mensagem baseada em ação com o Teams Toolkit, siga estes passos:

1. Abra o Visual Studio Code.
2. No painel esquerdo, selecione Teams Toolkit.
3. Selecione Criar uma Nova Aplicação.
4. Selecione Extensão da Mensagem.
5. Selecione Recolher a Partir de Dados de Entrada e Processo.
6. Selecione uma linguagem de programação.
7. Selecione Pasta predefinida.
8. Introduza o nome da sua aplicação e selecione Enter.

O Teams Toolkit estrutura o seu projeto e cria uma extensão de mensagem de ação.

Portal do Desenvolvedor do Teams

Para criar uma extensão de mensagem baseada em ações com o Portal do Programador para Teams, siga estes passos:

1. Aceda ao Portal do Programador do Teams.

2. Aceda a Aplicações.

3. Selecione Criar uma nova aplicação.

4. Em Configurar, selecioneFuncionalidades da aplicação.

5. Selecione Extensão de mensagens.

   

6. Em Tipo de extensão de mensagem, selecione Bot.

   1. Se receber uma exclusão de responsabilidade, que diz API Message extension já está a ser utilizada pelos utilizadores. Pretende alterar o tipo de extensão da mensagem para bot? Selecione Sim, alterar.

   

7. Se não tiver um bot existente, selecione Bot existente ou, se tiver um ID de bot, selecione Introduzir ID do Bot.

   1. Se não tiver um ID de bot, selecione Criar um bot para criar um novo bot e introduza o ID do bot novo que criou.

8. Selecione os âmbitos necessários.

9. Em Comando, selecione + Adicionar um comando.

   É apresentada uma página de detalhes do comando.

10. Na página Detalhes do comando, selecione Ação e, em seguida, selecione tipo de parâmetro.

11. Selecione Ação como o tipo de comando e atualize os seguintes campos:

    • ID do Comando
    • Título do comando
    • Descrição do comando
    • Contexto no qual o comando funciona
    • Nome do parâmetro
    • Título do parâmetro
    • Descrição do parâmetro
    • Tipo de descrição do parâmetro

12. Selecione Adicionar um domínio em Ligações de pré-visualização.

13. Introduza um domínio válido e, em seguida, selecione Adicionar.

    

14. Selecione Salvar.

    

Para adicionar parâmetros adicionais

1. Em comando, selecione o ícone de reticências (...) e, em seguida, selecione Editar parâmetro.

   

2. Selecione Adicionar um Parâmetro e atualize os detalhes do parâmetro.

   

3. Selecione Salvar

É criada uma extensão de mensagem de ação baseada em bot.

Trechos de código

O código seguinte fornece um exemplo de ação baseada em ações para extensões de mensagens:

C#

• Referência do SDK
• Referência de código de exemplo

protected override Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionFetchTaskAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
        {
            // Handle different actions using switch.
            switch (action.CommandId)
            {
                case "HTML":
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Height = 200,
                                Width = 400,
                                Title = "Task Module HTML Page",
                                Url = baseUrl + "/htmlpage.html",
                            },
                        },
                    };
                default:
                    string memberName = "";
                    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
                    memberName = member.Name;
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Card = <<AdaptiveAction card json>>,
                                Height = 200,
                                Width = 400,
                                Title = $"Welcome {memberName}",
                            },
                        },
                    };
            }
        }

Node.js

Referência de código de exemplo

// Invoked when a Messaging Extension Fetch activity is received from the connector.
    async handleTeamsMessagingExtensionFetchTask(context, action) {
        switch (action.commandId) {
            case 'Static HTML':
                return staticHtmlPage();
        }
    }

    staticHtmlPage(){
        return {
            task: {
                type: 'continue',
                value: {
                    width: 450,
                    height: 125,
                    title: 'Dialog Static HTML',
                    url: `${baseurl}/StaticPage.html`
                }
            }
        };
    }

Exemplo de código

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
Ação de extensão de mensagem do Teams	Este exemplo mostra como definir comandos de ação, criar caixa de diálogo e responder à ação de submissão da caixa de diálogo.	View	View	View
Pré-visualização da ação da extensão de mensagem	Este exemplo mostra como utilizar a pré-visualização de ações em Extensões de Mensagens com o Bot Framework v4.	View	View	View

Guias passo a passo

Siga o guia passo a passo para criar a extensão de mensagem baseada em ações do Teams.

Próxima etapa

Se estiver a utilizar um Cartão Ajustável ou uma vista Web incorporada sem um taskInfo objeto, o passo seguinte é:

Caixa de diálogo Criar e enviar

Se estiver a utilizar os parâmetros ou uma vista Web incorporada com um taskInfo objeto, o passo seguinte é:

Responder à ação de submissão de caixa de diálogo

Confira também

• Portal do Desenvolvedor do Teams
• Extensões de mensagens