Bot de notificación interactiva en Teams

Artículo
12/11/2024

Microsoft Teams Toolkit le permite crear aplicaciones que capturan eventos y los envían como notificaciones interactivas a un chat personal, grupal o a un canal en Microsoft Teams. Puede enviar notificaciones como texto sin formato o tarjetas adaptables. La plantilla de bot de notificación crea una aplicación que envía un mensaje a Teams con tarjetas adaptables desencadenadas por la solicitud de publicación HTTP.

La plantilla de aplicación se compila mediante el SDK de TeamsFx, que proporciona un conjunto sencillo de funciones a través de Microsoft Bot Framework para implementar sus necesidades. Por ejemplo, una agencia de viajes crea una aplicación en Teams para que sus usuarios los mantengan actualizados con la previsión meteorológica. En el diagrama de flujo siguiente, una aplicación de Teams notifica a los usuarios la previsión meteorológica mediante una tarjeta adaptable:

Puede enviar una notificación de bot en los siguientes escenarios:

Quiere notificar a todos los usuarios de un canal o chatear sobre el mismo contenido o relacionado.
Interfaz de usuario altamente personalizable en una tarjeta
Necesita una respuesta rápida, incluir contenido multimedia o botones de acción.
Envío de notificaciones programadas
Iluminación de distintivos dobles en actividad y chat, canal o aplicación
Agregar plantilla en el código fuente.
Controlar la localización manualmente.

Ventajas

Facilita las notificaciones a un chat personal, grupal y en un canal, mediante las API del SDK de TeamsFx.
Mejora la experiencia del usuario personalizando la notificación con una tarjeta adaptable.
Proporciona varios mecanismos para desencadenar notificaciones como HTTP y programar el desencadenador de temporizador con Azure Functions.
Una tarjeta de notificación se integra fácilmente con un bot y proporciona una experiencia de usuario coherente dentro de la aplicación Bot.

Nota:

La aplicación bot debe instalarse con el ámbito correspondiente antes de enviar la notificación.

Volver al principio

Notificación basada en eventos

Bot Framework SDK proporciona la funcionalidad para enviar mensajes de forma proactiva en Teams. El SDK de TeamsFx proporciona la funcionalidad para administrar las referencias de conversación del bot cuando se desencadena un evento de bot. El SDK de TeamsFx reconoce los siguientes eventos de bot:

Evento	Comportamiento
La primera vez que instala un bot en una persona, grupo o equipo.	Agregue la referencia de conversación de destino al almacenamiento.
Cuando el bot se desinstala de una persona, grupo o equipo.	Quite la referencia de conversación de destino del almacenamiento.
Cuando se elimina el equipo instalado por bot.	Quite la referencia de conversación de destino del almacenamiento.
Cuando se restaura el equipo instalado por el bot.	Agregue la referencia de conversación de destino al almacenamiento.
Cuando el bot envía mensajes.	Cuando la referencia de conversación de destino no exista, agréguela al almacenamiento.

nuevo ejemplo de evento de notificación

Al enviar notificaciones, el SDK de TeamsFx crea una nueva conversación a partir de la referencia de conversación seleccionada y, a continuación, envía un mensaje. Para un uso avanzado, puede acceder directamente a la referencia de conversación para ejecutar su propia lógica de bot:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // call Bot Framework's adapter.continueConversationAsync()
    await target.adapter.continueConversationAsync(
        target.botAppId,
        target.conversationReference,
        async (context) => {
            // your own bot logic
            await context...
        }
    );
}

   // list all installation targets
    foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // call Bot Framework's adapter.ContinueConversationAsync()
    await target.Adapter.ContinueConversationAsync(
        target.BotAppId,
        target.ConversationReference,
        async (context, ctx) =>
        {
            // your own bot logic
            await context...
        },
        cancellationToken);
}

Volver al principio

Instalación del bot de notificación

Un bot de notificación debe instalarse en un equipo o un chat de grupo o como una aplicación personal, en función del ámbito necesario. Durante la instalación, puede seleccionar el ámbito donde desea agregar y usar el bot:

Para abrir el bot en el ámbito personal, seleccione Abrir.
Para abrir el bot en un ámbito compartido, seleccione el canal, el chat o la reunión necesarios de la lista y desplácese por el cuadro de diálogo para seleccionar Ir.

Para obtener más opciones de instalación, consulte Configuración de opciones de instalación predeterminadas. Para la desinstalación, consulte Eliminación de una aplicación de Teams.

Volver al principio

Personalización de la notificación

Puede realizar las siguientes personalizaciones para ampliar la plantilla de notificación para satisfacer sus necesidades empresariales:

Personalización del punto de desencadenador desde el origen del evento
Personalización del contenido de la notificación
Personalización de dónde se envían las notificaciones

Personalización del punto de desencadenador desde el origen del evento

Puede personalizar los siguientes desencadenadores:

Express notificación basada en:
- Cuando se envía una solicitud HTTP al src/index.js punto de entrada, la implementación predeterminada envía una tarjeta adaptable a Teams. Puede personalizar este evento modificando src/index.js. Una implementación típica puede llamar a una API para recuperar eventos, datos o ambos que pueden enviar una tarjeta adaptable según sea necesario. Puede realizar lo siguiente para agregar más desencadenadores:
  - Cree un nuevo enrutamiento: server.post("/api/new-trigger", ...).
  - Agregue desencadenadores de temporizador a partir de paquetes npm ampliamente usados, como cron, node-schedule o desde otros paquetes.
  Nota:
  
  De forma predeterminada, Teams Toolkit aplica scaffolding a un único express punto de entrada en src/index.js.
notificación basada en Azure Functions:
- Al seleccionar timer desencadenador, el desencadenador src/timerTrigger.ts de temporizador de Azure Function implementado predeterminado envía una tarjeta adaptable cada 30 segundos. Puede editar el archivo *Trigger/function.json para personalizar la schedule propiedad. Para obtener más información, consulte la documentación de Azure Function.
- Al seleccionar http desencadenador, la solicitud HTTP desencadena la notificación y la implementación predeterminada envía una tarjeta adaptable a Teams. Puede cambiar este evento personalizando src/*Trigger.ts. Esta implementación puede llamar a una API para recuperar eventos, datos o ambos, que pueden enviar una tarjeta adaptable según sea necesario.
Desencadenadores de Azure Function:
- Event Hub desencadenador para enviar notificaciones cuando se inserta un evento en Azure Event Hub.
- Cosmos DB desencadenador para enviar notificaciones cuando se crea o actualiza un documento de Cosmos.

Para obtener más información sobre los desencadenadores de soporte técnico, consulte Azure Functions desencadenadores de soporte técnico.

Personalización del contenido de la notificación

El archivo src/adaptiveCards/notification-default.json define la tarjeta adaptable predeterminada. Puede usar el diseñador de tarjetas adaptables para ayudar a diseñar visualmente la interfaz de usuario de la tarjeta adaptable. src/cardModels.ts define una estructura de datos que se usa para cargar datos para la tarjeta adaptable. El enlace entre el modelo de tarjeta y la tarjeta adaptable se realiza mediante el nombre coincidente, como CardData.title se asigna a ${title} en la tarjeta adaptable. Puede agregar, editar o quitar propiedades y sus enlaces para personalizar la tarjeta adaptable según sea necesario.

También puede agregar nuevas tarjetas si es necesario. Para obtener más información sobre cómo crear diferentes tipos de tarjetas adaptables con una lista o tabla de contenido dinámico mediante ColumnSet y FactSet, vea Ejemplo de notificación de tarjeta adaptable.

Personalización de dónde se envían las notificaciones

Puede personalizar el envío de la notificación a los siguientes destinos:

Notificaciones a un chat personal:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Person" means this bot is installed as Personal app
    if (target.type === "Person") {
        // Directly notify the individual person
        await target.sendAdaptiveCard(...);
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Person" means this bot is installed as Personal app
    if (target.Type == NotificationTargetType.Person)
    {
        // Directly notify the individual person
        await target.SendAdaptiveCard(...);
    }
}

Notificaciones a un chat de grupo:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Group" means this bot is installed to a Group Chat
    if (target.type === "Group") {
        // Directly notify the Group Chat
        await target.sendAdaptiveCard(...);

            // List all members in the Group Chat then notify each member
            const members = await target.members();
            for (const member of members) {
                await member.sendAdaptiveCard(...);
            }
        }

}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Group" means this bot is installed to a Group Chat
    if (target.Type == NotificationTargetType.Group)
    {
        // Directly notify the Group Chat
        await target.SendAdaptiveCard(...);
    // List all members in the Group Chat then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in members) {
            await member.SendAdaptiveCard(...);
        }
    }
}

Notificaciones a un canal:

TypeScript
C#

// list all installation targets
for (const target of await notificationApp.notification.installations()) {
    // "Channel" means this bot is installed to a Team (default to notify General channel)
    if (target.type === "Channel") {
        // Directly notify the Team (to the default General channel)
        await target.sendAdaptiveCard(...);

        // List all members in the Team then notify each member
        const members = await target.members();
        for (const member of members) {
            await member.sendAdaptiveCard(...);
        }

        // List all channels in the Team then notify each channel
        const channels = await target.channels();
        for (const channel of channels) {
            await channel.sendAdaptiveCard(...);
        }
    }
}

// list all installation targets
foreach (var target in await _conversation.Notification.GetInstallationsAsync()) {
    // "Channel" means this bot is installed to a Team (default to notify General channel)
    if (target.Type == NotificationTargetType.Channel)
    {
        // Directly notify the Team (to the default General channel)
        await target.SendAdaptiveCard(...);

        // List all members in the Team then notify each member
        var members = await target.GetMembersAsync();
        foreach (var member in members) {
            await member.SendAdaptiveCard(...);
        }

        // List all channels in the Team then notify each channel
        var channels = await target.GetChannelsAsync();
        foreach (var channel in channels) {
            await channel.SendAdaptiveCard(...);
        }
    }
}

Notificaciones a un canal específico:

// find the first channel when the predicate is true.
const channel = await notificationApp.notification.findChannel(c => Promise.resolve(c.info.name === "MyChannelName"));

// send adaptive card to the specific channel.
await channel?.sendAdaptiveCard(...);

Nota:

Para evitar una salida no definida, asegúrese de instalar la aplicación de bot en el canal General de un equipo.

Notificaciones a una persona específica:

// find the first person when the predicate is true.
const member = await notificationApp.notification.findMember(m => Promise.resolve(m.account.name === "Bob"));

// send adaptive card to the specific person. 
await member?.sendAdaptiveCard(...);

Nota:

Para evitar una salida indefinida y una notificación que falta, debe incluir a la persona específica en el ámbito de instalación de notificaciones.

Volver al principio

Personalización de la inicialización

Debe crear ConversationBot para enviar una notificación.

Nota:

El código se genera en el proyecto.

JavaScript/TypeScript
C#

/** Javascript/Typescript: src/internal/initialize.*s **/
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
    },
});

/** .NET: Program.cs or Startup.cs **/
// Create the Conversation with notification feature enabled.
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        // To use your own CloudAdapter
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
        },
    };

    return new ConversationBot(options);
});

Volver al principio

Personalizar adaptador

Para personalizarlo, cree su propio adaptador o personalice el adaptador después de la inicialización. A continuación se muestra el ejemplo de código para crear el adaptador:

// Create your own adapter
const adapter = new CloudAdapter(...);

// Customize your adapter, e.g., error handling
adapter.onTurnError = ...

const notificationApp = new ConversationBot({
    // use your own adapter
    adapter: adapter;
    ...
});

// Or, customize later
notificationApp.adapter.onTurnError = ...

Volver al principio

Agregar almacenamiento

El almacenamiento se puede usar para implementar conexiones de notificación. Puede agregar su propio almacenamiento con la ayuda del siguiente ejemplo de código:

TypeScript
C#

// implement your own storage
class MyStorage implements NotificationTargetStorage {...}
const myStorage = new MyStorage(...);

// initialize ConversationBot with notification enabled and customized storage
const notificationApp = new ConversationBot({
    // The bot id and password to create CloudAdapter.
    // See https://aka.ms/about-bot-adapter to learn more about adapters.
    adapterConfig: {
        MicrosoftAppId: config.botId,
        MicrosoftAppPassword: config.botPassword,
        MicrosoftAppType: "MultiTenant",
    },
    // Enable notification
    notification: {
        enabled: true,
        storage: myStorage,
    },
});

// implement your own storage
public class MyStorage : INotificationTargetStorage {...}

// initialize ConversationBot with notification enabled and customized storage
builder.Services.AddSingleton(sp =>
{
    var options = new ConversationOptions()
    {
        Adapter = sp.GetService<CloudAdapter>(),
        Notification = new NotificationOptions
        {
            BotAppId = builder.Configuration["MicrosoftAppId"],
            // Use your own storage
            Storage = new MyStorage(),
        },
    };

    return new ConversationBot(options);
});

Si no se proporciona el almacenamiento, puede usar un almacenamiento de archivos local predeterminado, que almacena las conexiones de notificación en:

.notification.localstore.json si se ejecuta localmente.
${process.env.TEMP}/.notification.localstore.json, si process.env.RUNNING_ON_AZURE está establecido en 1.

Si usa el almacenamiento de archivos local predeterminado, la aplicación web de Azure y Azure Functions limpiar el archivo local durante un reinicio o una nueva implementación. También puede desinstalar el bot de Teams y, a continuación, instalarlo para agregar de nuevo conexiones al almacenamiento.

Es NotificationTargetStorage diferente del almacenamiento personalizado del SDK de Bot Framework. El almacenamiento de notificaciones requiere writeread, , deletey list funcionalidades, pero el almacenamiento del SDK de Bot Framework tiene read, writey delete funcionalidades y no tiene la list funcionalidad .

Para obtener más información sobre Azure Blob Storage, consulte el ejemplo de implementación del almacenamiento de notificaciones.

Nota:

Se recomienda usar su propio almacenamiento compartido para el entorno de producción.
Si implementa su propio almacenamiento del SDK de Bot Framework, por ejemplo, botbuilder-azure-blobs.BlobsStorage, debe implementar otro almacenamiento para la notificación. Puede compartir la misma cadena de conexión de blob con contenedores diferentes.

Volver al principio

Agregar autenticación para la API de notificación

Si selecciona Desencadenador HTTP, la API de notificación con scaffolding no tiene habilitada la autenticación ni la autorización. Asegúrese de agregar autenticación o autorización para la API antes de usarla para producción. Puede realizar una de las siguientes acciones:

Use una clave de API. Puede usar claves de acceso de función si selecciona Azure Functions para hospedar el bot de notificación.
Use un token de acceso emitido por Microsoft Entra ID. Para obtener más información, consulte Configuración del inicio de sesión único para el bot en Microsoft Entra ID.

Puede haber más soluciones de autenticación o autorización para una API; puede seleccionar según sea necesario.

Volver al principio

Conexión a las API existentes

Si no tiene el SDK necesario y desea invocar API externas en el código, el comando Teams: Conectarse a una API en la extensión Microsoft Visual Studio Code Teams Toolkit o el comando teamsfx add api-connection en la CLI de TeamsFx se puede usar para arrancar código para llamar a las API de destino. Para obtener más información, consulte Integración de API de terceros existentes.

Aplicación de bot de Teams o webhook entrante de Teams

TeamsFx admite dos maneras de ayudarle a enviar notificaciones desde el sistema a Teams:

Cree una aplicación de bot de Teams.
Crear webhook entrante de Teams.

En la tabla siguiente, puede ver la comparación de las dos maneras diferentes:

	Aplicación bot de Teams	Webhook entrante de Teams
Persona individual del mensaje	✔️	❌
Chat del grupo de mensajes	✔️	❌
Canal público de mensajes	✔️	✔️
Canal privado de mensajes	❌	✔️
Enviar mensaje de tarjeta	✔️	✔️
Enviar mensaje de bienvenida	✔️	❌
Recuperación del contexto de Teams	✔️	❌
Requerir pasos de instalación en Teams	✔️	❌
Requerir recurso de Azure	Azure Bot Service	❌

Notificación de webhook entrante

Los webhooks entrantes ayudan a publicar mensajes de aplicaciones en Teams. Si los webhooks entrantes están habilitados para un equipo en cualquier canal, expone el punto de conexión HTTPS, que acepta JSON con el formato correcto e inserta los mensajes en ese canal. Por ejemplo, puede crear un webhook entrante en el canal de DevOps, configurar la compilación e implementar y supervisar servicios simultáneamente para enviar alertas. TeamsFx proporciona un ejemplo de notificación de webhook entrante que le ayuda a:

Cree un webhook entrante en Teams.
Enviar notificaciones mediante webhooks entrantes con tarjetas adaptables.

Volver al principio

Envío de notificaciones de fuente de actividad

Si desea enviar notificaciones de fuente de actividad para la aplicación, puede usar las API de notificación de fuente de actividad en Microsoft Graph. Para obtener más información, consulte Envío de notificaciones de fuente de actividad a usuarios de Microsoft Teams.

Preguntas más frecuentes

¿Por qué las instalaciones de notificación están vacías aunque la aplicación de bot esté instalada en Teams?

Teams envía un evento solo en la primera instalación. Si la aplicación de bot ya está instalada antes de que se inicie el servicio de bot de notificación, el evento de instalación no llegó al servicio bot o se omite.

Puede resolver este problema de las siguientes maneras:

Envíe un mensaje al bot personal o mencione el bot en el chat en grupo o canal, lo que le ayuda a ponerse de nuevo en contacto con el servicio de bots con la información de instalación correcta.
Desinstale la aplicación del bot de Teams y vuelva a compilarla o vuelva a iniciarla. Puede volver a enviar el evento de instalación al servicio bot.

Las conexiones de destino de notificación se almacenan en el almacenamiento de persistencia. Si usa el almacenamiento de archivos local predeterminado, todas las instalaciones se almacenan en .notification.localstore.json.

Nota:

Para obtener más información para agregar su propio almacenamiento, consulte Agregar almacenamiento.

¿Por qué se produce un error de solicitud incorrecta o de argumento incorrecto al enviar la notificación?

Si la instalación de la notificación no coincide con el identificador o la contraseña del bot, puede obtener un error de id. de conversación no se pudo descifrar . Una posible causa de este error es que se cambia el identificador o la contraseña del bot debido a la limpieza del estado local o a la revisión.

Para resolver este problema, limpie el almacenamiento de notificaciones. Después de limpiar, notifique en Teams que vuelva a instalar el bot y asegúrese de que la nueva instalación está actualizada. Cada instalación de notificación almacenada está enlazada con un bot. Si puede comprobar el almacenamiento de notificaciones, su campo de bot debe coincidir con el bot que está ejecutando, como el identificador del bot con el mismo GUID.

Nota:

En el caso del almacenamiento local, la ubicación predeterminada es .notification.localstore.json.

¿Por qué se pierde el destino de notificación después de reiniciar o volver a implementar la aplicación de bot?

Las conexiones de destino de notificación se almacenan en el almacenamiento de persistencia. Si usa el almacenamiento de archivos local predeterminado, la aplicación web de Azure y Azure Functions limpiar el archivo local durante un reinicio o una nueva implementación. También puede desinstalar el bot de Teams y, a continuación, instalarlo para agregar de nuevo conexiones al almacenamiento. Se recomienda usar su propio almacenamiento compartido para el entorno de producción.

¿Por qué se devuelve un error indefinido al usar la API 'findChannel'()?

Puede encontrar un error indefinido cuando la aplicación bot se instala en otros canales en lugar del General canal. Para corregir este error, puede desinstalar la aplicación de bot de Teams y volver a asignarla y volver a iniciarla. Después de volver a compilar y volver a iniciar, asegúrese de que la aplicación de bot está instalada en el General canal.

¿Puedo saber todos los destinos en los que está instalado mi bot dentro y fuera del proyecto de notificación?

Hay API de Microsoft Graph para enumerar las aplicaciones instaladas en un equipo, grupo o chat. Si es necesario, recorre en iteración el equipo, el grupo o el chat en una aplicación instalada para que sea el destino. En el proyecto de notificación, usa almacenamiento de persistencia para almacenar destinos de instalación. Para obtener más información, consulte notificación basada en eventos.

¿Cómo personalizar los puertos de escucha Azurite?

Si Azurite se cierra debido al puerto en uso, puede especificar otro puerto de escucha y actualizar el cadena de conexión de AzureWebJobsStorage en local.settings.json.

¿Cómo ampliar mi bot de notificación para admitir el comando y la respuesta?

Vaya a y actualice conversationBot la bot\src\internal\initialize.ts(js) inicialización para habilitar la característica de notificación:
Para agregar un comando al bot, siga las instrucciones de Bot de comandos en Teams.

¿Cómo ampliar mi bot de notificación agregando acciones de tarjeta adaptable del bot de flujo de trabajo?

La característica de controlador de acciones de tarjeta adaptable permite que la aplicación responda a las acciones de tarjeta adaptable desencadenadas por los usuarios finales para completar un flujo de trabajo secuencial. Una tarjeta adaptable proporciona uno o varios botones en la tarjeta para solicitar la entrada del usuario, como llamar a algunas API. A continuación, la tarjeta adaptable envía otra tarjeta adaptable en la conversación para responder a la acción de la tarjeta.

Para obtener más información sobre cómo agregar acciones de tarjeta adaptable al bot de comandos, consulte Bot de flujo de trabajo en Teams.

Volver al principio

Guía paso a paso

Siga la guía paso a paso para compilar el bot de notificación de Teams.

Compartir a través de

Bot de notificación interactiva en Teams

Notificación basada en eventos

Instalación del bot de notificación

Personalización de la notificación

Personalización del punto de desencadenador desde el origen del evento

Personalización del contenido de la notificación

Personalización de dónde se envían las notificaciones

Personalización de la inicialización

Personalizar adaptador

Agregar almacenamiento

Agregar autenticación para la API de notificación

Conexión a las API existentes

Aplicación de bot de Teams o webhook entrante de Teams

Notificación de webhook entrante

Envío de notificaciones de fuente de actividad

Preguntas más frecuentes

Guía paso a paso

Recursos adicionales

Recursos adicionales