Definir comandos de acción de extensión de mensajería

Antes de crear el comando de acción, debe decidir los siguientes factores:

1. ¿Desde dónde se puede desencadenar el comando de acción?
2. ¿Cómo se crea el cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x)?
3. ¿Se envía el mensaje final o la tarjeta al canal desde un bot o se inserta el mensaje o la tarjeta en el área de redacción del mensaje para que el usuario lo envíe?

Seleccionar ubicaciones de invocación de comando de acción

En primer lugar, debe decidir la ubicación desde la que se debe invocar el comando de acción. Al especificar la propiedad en el context manifiesto de la aplicación (anteriormente denominado manifiesto de aplicación de Teams), el comando se puede invocar desde una o varias de las siguientes ubicaciones:

• Área redactar mensaje: los botones de la parte inferior del área de redacción del mensaje.

  Contexto de comandos = compose

• Cuadro de comandos: mediante / en el cuadro de comandos. Por ejemplo, /your-app-name. Si usa teams clásicos, el comando action se invoca @mentioning en el cuadro de comandos. Por ejemplo, @your-app-name.

  Contexto de comandos = commandBox

  Nota:

  Si se invoca una extensión de mensaje desde el cuadro de comando, no puede responder con un mensaje de bot insertado directamente en la conversación.

• Mensaje: directamente desde un mensaje existente a través del menú de desbordamiento ... en un mensaje.

  Contexto de comandos = message

  Nota:

  • La invocación inicial al bot incluye un objeto JSON que contiene el mensaje desde el que se invocó. Puede procesar el mensaje antes de presentar un cuadro de diálogo.

  • Cuando el usuario selecciona puntos suspensivos ..., se muestra un menú de desbordamiento. Sin embargo, de forma predeterminada, no se muestran las acciones de mensaje de las aplicaciones creadas por usted para su organización o aplicaciones de terceros. Una vez que el usuario selecciona Más acciones, puede ver las acciones del mensaje y seleccionar la opción necesaria. La acción del mensaje correspondiente se muestra en el menú de desbordamiento. El menú de desbordamiento muestra las tres acciones de mensaje más recientes. No se puede anclar la acción del mensaje que se va a mostrar.

En la imagen siguiente se muestran las ubicaciones desde las que se invoca el comando de acción:

Seleccione cómo crear el cuadro de diálogo.

Además de seleccionar desde dónde se puede invocar el comando, también debe seleccionar cómo rellenar el formulario en el cuadro de diálogo para los usuarios. Tiene las tres opciones siguientes para crear el formulario que se representa dentro del cuadro de diálogo:

• Lista estática de parámetros: este es el método más sencillo. Puede definir una lista de parámetros en el manifiesto de la aplicación que representa el cliente de Teams, pero no puede controlar el formato en este caso.
• Tarjeta adaptable: puede seleccionar usar una tarjeta adaptable, que proporciona un mayor control sobre la interfaz de usuario, pero sigue limitando los controles disponibles y las opciones de formato.
• Vista web incrustada: puede seleccionar insertar una vista web personalizada en el cuadro de diálogo para tener un control completo sobre la interfaz de usuario y los controles.

Si selecciona crear el cuadro de diálogo con una lista estática de parámetros y cuando el usuario envía el cuadro de diálogo, se llama a la extensión de mensaje. Al usar una vista web incrustada o una tarjeta adaptable, la extensión de mensaje debe controlar un evento de invocación inicial del usuario, crear el cuadro de diálogo y devolverlo al cliente.

Seleccionar cómo se envía el mensaje final

En la mayoría de los casos, el comando de acción da como resultado una tarjeta insertada en el cuadro de redacción del mensaje. El usuario puede enviarlo al canal o chat. En este caso, el mensaje procede del usuario y el bot no puede editar ni actualizar aún más la tarjeta.

Si la extensión de mensaje se invoca desde el cuadro de redacción o directamente desde un mensaje, el servicio web puede insertar la respuesta final directamente en el canal o chat. En este caso, la tarjeta adaptable procede del bot, el bot la actualiza y responde al hilo de conversación si es necesario. Debe agregar el bot objeto al manifiesto de la aplicación con el mismo identificador y definir los ámbitos adecuados.

Comando Crear acción mediante el Portal para desarrolladores

Puede crear un comando de acción mediante el Kit de herramientas de Teams y el Portal para desarrolladores para Teams.

Kit de herramientas de Teams

Para crear una extensión de mensaje basada en acciones mediante el kit de herramientas de Teams, siga estos pasos:

1. Abra Visual Studio Code.
2. En el panel izquierdo, seleccione Kit de herramientas de Teams.
3. Seleccione Crear una nueva aplicación.
4. Seleccione Extensión de mensaje.
5. Seleccione Recopilar de datos de entrada y proceso.
6. Seleccione un lenguaje de programación.
7. Seleccione Carpeta predeterminada.
8. Escriba el nombre de la aplicación y seleccione Entrar.

El kit de herramientas de Teams aplica scaffolding al proyecto y crea una extensión de mensaje de acción.

Portal para desarrolladores de Teams

Para crear una extensión de mensaje basada en acciones mediante el Portal para desarrolladores para Teams, siga estos pasos:

1. Vaya al Portal para desarrolladores de Teams.

2. Vaya a Aplicaciones.

3. Seleccione Crear una nueva aplicación.

4. En Configurar, seleccione Características de la aplicación.

5. Seleccione Extensión de mensajería.

   

6. En Tipo de extensión de mensaje, seleccione Bot.

   1. Si obtiene una declinación de responsabilidades, que lee la extensión de mensaje de API ya está en uso por parte de los usuarios. ¿Desea cambiar el tipo de extensión de mensaje a bot?. Seleccione Sí, cambie.

   

7. Si no tiene un bot existente, seleccione Bot existente o, si tiene un identificador de bot, seleccione Entrar id. de bot.

   1. Si no tiene un identificador de bot, seleccione Crear un bot para crear un bot y escriba el identificador de bot del nuevo bot que creó.

8. Seleccione los ámbitos necesarios.

9. En Comando, seleccione + Agregar un comando.

   Aparece una página de detalles del comando.

10. En la página Detalles del comando, seleccione Acción y, a continuación, seleccione Tipo de parámetro.

11. Seleccione Acción como tipo de comando y actualice los campos siguientes:

    • Identificador de comando
    • Título del comando
    • Descripción del comando
    • Contexto en el que funciona el comando
    • Nombre del parámetro
    • Título del parámetro
    • Descripción del parámetro
    • Tipo de descripción de parámetro

12. Seleccione Agregar un dominio en Vínculos de vista previa.

13. Escriba dominio válido y, a continuación, seleccione Agregar.

    

14. Haga clic en Guardar.

    

Para agregar parámetros adicionales

1. En el comando , seleccione el icono de elipse (...) y, a continuación, seleccione Editar parámetro.

   

2. Seleccione Agregar un parámetro y actualice los detalles del parámetro.

   

3. Seleccione Guardar.

Se crea una extensión de mensaje de acción basada en bots.

Fragmentos de código

El código siguiente proporciona un ejemplo basado en acciones para las extensiones de mensaje:

C#

• Referencia del SDK
• Referencia de código de ejemplo

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

Referencia de código de ejemplo

// 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`
                }
            }
        };
    }

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Manifiesto
Acción de extensión de mensaje de Teams	En este ejemplo se muestra cómo definir comandos de acción, crear cuadros de diálogo y responder a la acción de envío del cuadro de diálogo.	View	View	View
Vista previa de la acción de extensión de mensaje	En este ejemplo se muestra cómo usar la versión preliminar de la acción en Extensiones de mensajería mediante Bot Framework v4.	View	View	View

Guía paso a paso

Siga la guía paso a paso para crear la extensión de mensajes basada en acciones de Teams.

Paso siguiente

Si usa una tarjeta adaptable o una vista web incrustada sin un taskInfo objeto, el siguiente paso es:

Cuadro de diálogo Crear y enviar

Si usa los parámetros o una vista web incrustada con un taskInfo objeto , el siguiente paso es:

Respuesta a la acción de envío del cuadro de diálogo

Vea también

• Portal para desarrolladores de Teams
• Extensiones de mensajes