Envío de mensajes de instalación proactiva

Artículo
11/21/2023

Mensajería proactiva en Teams

Los bots inician mensajes proactivos para iniciar conversaciones con un usuario. Sirven para muchos propósitos, como el envío de mensajes de bienvenida, la realización de encuestas o sondeos y la difusión de notificaciones de toda la organización. Los mensajes proactivos en Teams se pueden entregar como ad-hoc o conversaciones basadas en diálogos:

Tipo de mensaje	Descripción
Mensaje proactivo ad hoc	El bot intercepta un mensaje sin interrumpir el flujo de conversación.
Mensaje proactivo basado en diálogos	El bot crea un nuevo subproceso de diálogo, asume el control de una conversación, entrega el mensaje proactivo, lo cierra y devuelve el control al diálogo anterior.

Instalación proactiva de aplicaciones en Teams

Antes de que el bot pueda enviar mensajes de forma proactiva a un usuario, debe estar instalado como una aplicación personal o en un equipo del que el usuario sea miembro. En ocasiones, debe enviar mensajes de forma proactiva a los usuarios que no han instalado o han interactuado previamente con la aplicación. Por ejemplo, si necesita enviar información importante a todos los usuarios de la organización, puede usar Microsoft Graph API para instalar el bot de forma proactiva para los usuarios.

Permisos

Los permisos del tipo de recurso teamsAppInstallation de Microsoft Graph le ayudan a administrar el ciclo de vida de instalación de la aplicación para todos los ámbitos de usuario (personal) o de equipo (canal) dentro de la plataforma de Microsoft Teams:

Permiso de la aplicación	Descripción
`TeamsAppInstallation.ReadWriteSelfForUser.All`	Permite que una aplicación de Teams se lea, instale, actualice y desinstale por sí misma para cualquier usuario, sin que se haya usado o iniciado sesión en ella previamente.
`TeamsAppInstallation.ReadWriteSelfForTeam.All`	Permite que una aplicación de Teams se lea, instale, actualice y desinstale a sí misma en cualquier equipo sin que se haya usado o iniciado sesión en ella previamente.

Para usar estos permisos, debe agregar una clave webApplicationInfo al manifiesto de la aplicación (anteriormente denominado manifiesto de aplicación de Teams) con los siguientes valores:

id: el identificador de la aplicación Microsoft Entra.
resource: La dirección URL del recurso de la aplicación.

Nota:

El bot requiere permisos delegados de aplicación y no de usuario porque la instalación es para otros usuarios.
Un administrador de inquilinos de Microsoft Entra debe conceder permisos explícitamente a una aplicación. Una vez que se conceden permisos a la aplicación, todos los miembros del inquilino de Microsoft Entra obtienen los permisos concedidos.

Habilitar la instalación y mensajería proactivas de la aplicación

Importante

Microsoft Graph solo puede instalar aplicaciones publicadas en la tienda de aplicaciones de su organización o en la Tienda Microsoft Teams.

Crear y publicar el bot de mensajería proactiva para Teams

Para empezar, necesita un bot para Teams con funcionalidades de mensajería proactiva que se encuentra en la tienda de aplicaciones de su organización o en la Tienda Teams.

Sugerencia

La plantilla de la aplicación lista para producción Company Communicator permite la difusión de mensajes y es un buen punto de partida para crear la aplicación de bot proactiva.

Obtener el `teamsAppId` para la aplicación

Puede recuperar el teamsAppId de las siguientes maneras:

Desde al catálogo de aplicaciones de su organización:

Referencia de página de Microsoft Graph:tipo de recurso teamsApp

Solicitud HTTP GET:
```
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
```
La solicitud debe devolver un objeto de teamsAppid, que es el id. de aplicación generado por el catálogo de la aplicación. Esto es diferente del identificador que proporcionó en el manifiesto de la aplicación:
```
{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}
```
Nota:

Cuando la aplicación está en la Tienda Teams, es igual teamsAppIdIdFromManifest que y externalId no se debe usar en este caso.
Si la aplicación ya se ha cargado para un usuario en el ámbito personal:

Referencia de página de Microsoft Graph:Lista de aplicaciones instaladas para el usuario

Solicitud HTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Si la aplicación ya se ha cargado para un canal en el ámbito de equipo:

Referencia de página de Microsoft Graph:Enumerar aplicaciones en equipo

Solicitud HTTP GET:
```
GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Sugerencia

Para restringir la lista de resultados, puede filtrar cualquiera de los campos del objeto teamsApp.

Determinar si el bot está instalado para un destinatario del mensaje

Puede determinar si el bot está instalado para un destinatario del mensaje como se indica a continuación:

Referencia de página de Microsoft Graph:Lista de aplicaciones instaladas para el usuario

Solicitud HTTP GET:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

La solicitud devuelve:

Matriz vacía si la aplicación no está instalada.
Una matriz con un objeto teamsAppInstallation único si la aplicación está instalada.

Instalar la aplicación

Puede instalar la aplicación de la siguiente manera:

Referencia de página de Microsoft Graph:Instalar aplicación para el usuario

Solicitud HTTP POST:

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

Si el usuario está ejecutando Microsoft Teams, la instalación de la aplicación se produce inmediatamente. Podría ser necesario reiniciar para ver la aplicación instalada.

Recuperar la conversación `chatId`

Cuando la aplicación está instalada para el usuario, el bot recibe una conversationUpdatenotificación de evento que contiene la información necesaria para enviar el mensaje proactivo.

Referencia de página de Microsoft Graph:Obtener chat

Debe tener el {teamsAppInstallationId} de la aplicación. Si no lo tiene, use lo siguiente:

Solicitud HTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
```
La propiedad del id de la respuesta es el teamsAppInstallationId.
Realice la siguiente solicitud para capturar el chatId:

Solicitud HTTP GET (permiso):TeamsAppInstallation.ReadWriteSelfForUser.All
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
```
La propiedad del id de la respuesta es el chatId.

También puede recuperar el chatId con la siguiente solicitud, aunque requiere un permiso Chat.Read.All más amplio:

Solicitud HTTP GET (permiso):Chat.Read.All
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
```

Enviar mensajes proactivos

El bot puede enviar mensajes proactivos para un usuario o equipo después de agregado y después de que haya recibido toda la información del usuario.

Fragmentos de código

El código siguiente proporciona un ejemplo de envío de mensajes proactivos:

C#
Node.js

public async Task<int> SendNotificationToAllUsersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
   int msgSentCount = 0;

   // Send notification to all the members.
   foreach (var conversationReference in _conversationReferences.Values)
   {
       await turnContext.Adapter.ContinueConversationAsync(_configuration["MicrosoftAppId"], conversationReference, BotCallback, cancellationToken);
       msgSentCount++;
   }

   return msgSentCount;
}

private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
{
    // Sends an activity to the sender of the incoming activity.
   await turnContext.SendActivityAsync("Proactive hello.");
}

server.get('/api/notify', async (req, res) => {
    for (const conversationReference of Object.values(conversationReferences)) {

        // Sends a proactive message to a conversation.
        await adapter.continueConversationAsync(process.env.MicrosoftAppId, conversationReference, async context => {
            await context.sendActivity('proactive hello');
        });
    }
    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Ejemplo de código

Nombre de ejemplo	Descripción	.NET	Node.js
Instalación proactiva de la aplicación y envío de notificaciones proactivas	En este ejemplo se muestra cómo puede usar la instalación proactiva de la aplicación para usuarios y enviar notificaciones proactivas mediante una llamada a las API de Microsoft Graph.	View	View

Ejemplo de código adicional

Ejemplos de código de mensajería proactiva de Teams

Compartir vía

Envío de mensajes de instalación proactiva

Mensajería proactiva en Teams

Instalación proactiva de aplicaciones en Teams

Permisos

Habilitar la instalación y mensajería proactivas de la aplicación

Crear y publicar el bot de mensajería proactiva para Teams

Obtener el `teamsAppId` para la aplicación

Determinar si el bot está instalado para un destinatario del mensaje

Instalar la aplicación

Recuperar la conversación `chatId`

Enviar mensajes proactivos

Fragmentos de código

Ejemplo de código

Ejemplo de código adicional

Vea también

Recursos adicionales

Compartir vía

Envío de mensajes de instalación proactiva

Mensajería proactiva en Teams

Instalación proactiva de aplicaciones en Teams

Permisos

Habilitar la instalación y mensajería proactivas de la aplicación

Crear y publicar el bot de mensajería proactiva para Teams

Obtener el teamsAppId para la aplicación

Determinar si el bot está instalado para un destinatario del mensaje

Instalar la aplicación

Recuperar la conversación chatId

Enviar mensajes proactivos

Fragmentos de código

Ejemplo de código

Ejemplo de código adicional

Vea también

Recursos adicionales

Obtener el `teamsAppId` para la aplicación

Recuperar la conversación `chatId`