Compartir vía


Bot de notificación interactiva en Teams

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:

Escenario de notificación de ejemplo de previsión meteorológica

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 el desencadenador de temporizador de programación 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:

// 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...
        }
    );
}

Volver al principio

Instalación del bot de notificación

Un bot de notificación debe instalarse en un equipo, un chat de grupo o como aplicación personal, en función del ámbito necesario. Debe seleccionar el destino de instalación antes de agregar el bot a la aplicación.

agregar ámbito de instalación

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

Puede personalizar los siguientes desencadenadores:

  • Restify 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 restify 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.

      ejemplo de notificación desencadenada por el temporizador

    • 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.

      ejemplo de notificación desencadenada por HTTP

  • 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 Desencadenadores de soporte técnico de Azure Functions.

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:

    // 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(...);
        }
    }
    

  • Notificaciones a un chat de grupo:

    // 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(...);
                }
            }
    
    }
    

  • Notificaciones a un canal:

    // 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(...);
            }
        }
    }
    

  • 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: 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,
    },
});

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:

// 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,
    },
});

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 limpian 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:

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 pueden 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:

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 limpian 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 la 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?
  1. Vaya a y actualice conversationBot la bot\src\internal\initialize.ts(js) inicialización para habilitar la característica de notificación:

    Inicialización del bot de conversación para habilitar la característica de notificación.

  2. 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.

Vea también