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 a caixa de diálogo (chamada de módulo de tarefa no TeamsJS v1.x) é criada?
3. A mensagem final ou cartão enviada para o canal de um bot ou a mensagem ou cartão está inserida na área de mensagem de composição para o usuário enviar?

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

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 você especifica a propriedade no manifesto do context aplicativo (anteriormente chamado de manifesto do aplicativo teams), seu comando pode ser invocado de um ou mais dos seguintes locais:

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

  Contexto de comandos = compose

• Caixa de comando: usando /na caixa de comando. Por exemplo, /your-app-name. Se você estiver usando o teams clássico, o comando de ação será 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 da caixa de comando, você não poderá responder com uma mensagem de bot inserida diretamente na conversa.

• 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. Você pode processar a mensagem antes de apresentar uma caixa de diálogo.

  • Quando o usuário seleciona reticências ..., um menu de estouro é exibido. No entanto, por padrão, as ações de mensagem para aplicativos criados por você para sua organização ou aplicativos de terceiros não são exibidas. Depois que o usuário selecionar Mais ações, ele poderá ver as ações da mensagem e selecionar a opção necessária. A respectiva ação de mensagem é exibida no menu de estouro. O menu de estouro exibe as três ações de mensagem mais recentes. Você não pode fixar a ação da mensagem a ser exibida.

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

Selecione como criar sua caixa de diálogo

Além de selecionar de onde seu comando pode ser invocado, você também deve selecionar como preencher o formulário na caixa de diálogo para seus usuários. Você tem as três opções a seguir para criar o formulário renderizado dentro da caixa de diálogo:

• Lista estática de parâmetros: Esse é o método mais simples. Você pode definir uma lista de parâmetros em seu aplicativo manifestar as renderizações do cliente do Teams, mas não pode controlar a formatação nesse caso.
• 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 limita você nas opções de controles e formatação disponíveis.
• Exibição da Web inserida: você pode selecionar inserir uma exibição da Web personalizada na caixa de diálogo para ter um controle completo sobre a interface do usuário e os controles.

Se você selecionar para criar a caixa de diálogo com uma lista estática de parâmetros e quando o usuário enviar a caixa de diálogo, a extensão da mensagem será chamada. Ao usar uma exibição web inserida ou um Cartão Adaptável, sua extensão de mensagem deve lidar com um evento de invocação inicial do usuário, 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. Nesse caso, a mensagem vem do usuário e o bot não pode editar ou atualizar o cartão mais adiante.

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. Você deve adicionar o bot objeto ao manifesto do aplicativo usando a mesma ID e definindo os escopos apropriados.

Criar comando de ação usando o Portal do Desenvolvedor

Você pode criar um comando de ação usando o Teams Toolkit e o Portal do Desenvolvedor para o Teams.

Kit de ferramentas do Teams

Para criar uma extensão de mensagem baseada em ação usando o Teams Toolkit, siga estas etapas:

1. Abra o Visual Studio Code.
2. No painel esquerdo, selecione Kit de Ferramentas do Teams.
3. Selecione Criar um Novo Aplicativo.
4. Selecione Extensão de Mensagem.
5. Selecione Coletar de Dados de Entrada e Processo.
6. Selecione uma linguagem de programação.
7. Selecione Pasta Padrão.
8. Insira o nome do aplicativo e selecione Inserir.

O Teams Toolkit faz scaffolds 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ção usando o Portal do Desenvolvedor para Teams, siga estas etapas:

1. Acesse Portal do Desenvolvedor para Teams.

2. Acesse Aplicativos.

3. Selecione Criar um novo aplicativo.

4. Em Configurar, selecioneRecursos de aplicativo.

5. Selecione Extensão de mensagens.

   

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

   1. Se você receber uma isenção de responsabilidade, que lê a extensão de mensagem de API já está em uso pelos usuários. Deseja alterar o tipo de extensão de mensagem para bot?. Selecione Sim, altere.

   

7. Se você não tiver um bot existente, selecione Bot existente ou, se tiver uma ID do bot, selecione Inserir ID do Bot.

   1. Se você não tiver uma ID do bot, selecione Criar um bot para criar um novo bot e insira a ID do bot do novo bot que você criou.

8. Selecione os escopos necessários.

9. Em Comando, selecione + Adicionar um comando.

   Uma página de detalhes de comando é exibida.

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 de comando
    • Descrição do comando
    • Contexto em que o comando funciona
    • Nome do parâmetro
    • Título de parâmetro
    • Descrição do parâmetro
    • Tipo de descrição de parâmetro

12. Selecione Adicionar um domínio em Links de visualização.

13. Insira domínio válido e selecione Adicionar.

    

14. Selecione Salvar.

    

Para adicionar parâmetros adicionais

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

   

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

   

3. Selecione Salvar

Uma extensão de mensagem de ação baseada em bot é criada.

Trechos de código

O código a seguir fornece um exemplo de ação baseado em ação para extensões de mensagem:

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 envio de diálogo.	View	View	Exibir
Visualização da ação de extensão de mensagem	Este exemplo mostra como usar a visualização de ação em Extensões de Mensagens usando 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ção do Teams.

Próxima etapa

Se você estiver usando um Cartão Adaptável ou uma exibição web inserida sem um taskInfo objeto, a próxima etapa será:

Criar e enviar caixa de diálogo

Se você estiver usando os parâmetros ou uma exibição da Web inserida com um taskInfo objeto, a próxima etapa será:

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

Confira também

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