Enviar mensagens de instalação proativas

Artigo
11/14/2023

Mensagens proativas no Teams

Mensagens proativas são iniciadas por bots para iniciar conversas com um usuário. Eles têm muitas finalidades, incluindo enviar mensagens de boas-vindas, realizar pesquisas ou votações e transmitir notificações em toda a organização. As mensagens proativas no Teams podem ser entregues como conversas ad hoc ou baseadas em diálogo:

Tipo de mensagem	Descrição
Mensagem proativa ad hoc	O bot interjecta uma mensagem sem interromper o fluxo de conversa.
Mensagem proativa baseada em diálogo	O bot cria um novo thread de diálogo, assume o controle de uma conversa, entrega a mensagem proativa, fecha e retorna o controle para o diálogo anterior.

Instalação proativa de aplicativos no Teams

Antes que o bot possa enviar mensagens proativamente a um usuário, ele deve ser instalado como um aplicativo pessoal ou em uma equipe na qual o usuário é membro. Às vezes, você precisa enviar mensagens proativas aos usuários que não estiveram instalados ou interagiram anteriormente com seu aplicativo. Por exemplo, se você precisar enviar informações importantes para todos em sua organização, poderá usar o Microsoft API do Graph para instalar proativamente o bot para seus usuários.

Permissões

Microsoft Graph tipo de recurso teamsAppInstallation ajuda você a gerenciar o ciclo de vida de instalação do aplicativo para todos os escopos de usuário (pessoal) ou equipe (canal) na plataforma Microsoft Teams:

Permissão do aplicativo	Descrição
`TeamsAppInstallation.ReadWriteSelfForUser.All`	Permite que um aplicativo do Teams leia, instale, atualize e desinstale a si mesmo para qualquer usuário, sem antes entrar ou usar.
`TeamsAppInstallation.ReadWriteSelfForTeam.All`	Permite que um aplicativo Teams leia, instale, atualize e desinstale a si mesmo em qualquer equipe, sem antes entrar ou usar.

Para usar essas permissões, você deve adicionar uma chave WebApplicationInfo ao manifesto do aplicativo (anteriormente chamado de manifesto do aplicativo Teams) com os seguintes valores:

id: sua ID do aplicativo Microsoft Entra.
recurso: a URL de recurso do aplicativo.

Observação

Seu bot requer permissões delegadas pelo aplicativo e não pelo usuário porque a instalação é para outras pessoas.
Um administrador Microsoft Entra locatário deve conceder explicitamente permissões a um aplicativo. Depois que o aplicativo receber permissões, todos os membros do locatário Microsoft Entra obterão as permissões concedidas.

Habilitar a instalação proativa de aplicativos e mensagens

Importante

O Microsoft Graph só pode instalar aplicativos publicados na loja de aplicativos da sua organização ou na Microsoft Teams Store.

Criar e publicar seu bot de mensagens proativo para o Teams

Para começar, você precisa de um bot para o Teams com recursos de mensagens proativas que esteja na loja de aplicativos da sua organização ou na Teams Store.

Dica

O modelo de aplicativo Communicator da empresa permite mensagens de difusão e é um bom começo para criar seu aplicativo de bot proativo.

Obtenha o `teamsAppId` para seu aplicativo

Você pode recuperar o teamsAppId das seguintes maneiras:

No catálogo de aplicativos da sua organização:

Referência da página do Microsoft Graph:teamsApp tipo de recurso

Solicitação HTTP GET:
```
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
```
A solicitação deve retornar um teamsApp objeto id, que é a ID do aplicativo gerado pelo catálogo do aplicativo. Isso é diferente da ID que você forneceu no manifesto do aplicativo:
```
{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}
```
Observação

Quando o aplicativo está na Teams Store, o é igual teamsAppIdIdFromManifest e o externalId não deve ser usado nesse caso.
Se seu aplicativo já tiver sido carregado para um usuário no escopo pessoal:

Referência da página do Microsoft Graph:Listar aplicativos instalados para usuário

Solicitação HTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Se seu aplicativo já tiver sido carregado para um canal no escopo da equipe:

Referência da página do Microsoft Graph:Listar aplicativos em equipe

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

Para restringir a lista de resultados, você pode filtrar qualquer um dos campos do objeto teamsApp.

Determinar se o bot está instalado no momento para um destinatário da mensagem

Você pode determinar se o bot está instalado no momento para um destinatário da mensagem da seguinte maneira:

Referência da página do Microsoft Graph:Listar aplicativos instalados para usuário

Solicitação HTTP GET:

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

A solicitação retorna:

Uma matriz vazia se o aplicativo não estiver instalado.
Uma matriz com um único objeto teamsAppInstallation se o aplicativo estiver instalado.

Instalar seu aplicativo

Você pode instalar seu aplicativo da seguinte maneira:

Referência da página do Microsoft Graph:Instalar aplicativo para usuário

Solicitação 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}"
}

Se o usuário tiver o Microsoft Teams em execução, a instalação do aplicativo ocorrerá imediatamente. Uma reinicialização pode ser necessária para exibir o aplicativo instalado.

Recuperar a conversa `chatId`

Quando seu aplicativo é instalado para o usuário, o bot recebe uma conversationUpdatenotificação de evento que contém as informações necessárias para enviar a mensagem proativa.

Referência da página do Microsoft Graph:Obter chat

Você deve ter o {teamsAppInstallationId}. Se você não tiver, use o seguinte:

Solicitação HTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
```
A propriedade id da resposta é teamsAppInstallationId.
Faça a seguinte solicitação para buscar o chatId:

Solicitação HTTP GET (permissão—TeamsAppInstallation.ReadWriteSelfForUser.All):
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
```
A propriedade id da resposta é chatId.

Você também pode recuperar o chatId com a seguinte solicitação, mas requer a permissão Chat.Read.All mais ampla:

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

Enviar mensagens proativas

Seu bot pode enviar mensagens proativas depois que o bot foi adicionado para um usuário ou uma equipe e recebeu todas as informações do usuário.

Trechos de código

O código a seguir fornece um exemplo de envio de mensagens proativas:

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

Exemplo de código

Nome de exemplo	Descrição	.NET	Node.js
Instalação proativa do aplicativo e envio de notificações proativas	Este exemplo mostra como você pode usar a instalação proativa do aplicativo para usuários e enviar notificações proativas chamando as APIs do Microsoft Graph.	View	Exibir

Exemplos de código adicionais

Exemplos de código de mensagens proativas do Teams

Enviar mensagens de instalação proativas

Mensagens proativas no Teams

Instalação proativa de aplicativos no Teams

Permissões

Habilitar a instalação proativa de aplicativos e mensagens

Criar e publicar seu bot de mensagens proativo para o Teams

Obtenha o `teamsAppId` para seu aplicativo

Determinar se o bot está instalado no momento para um destinatário da mensagem

Instalar seu aplicativo

Recuperar a conversa `chatId`

Enviar mensagens proativas

Trechos de código

Exemplo de código

Exemplos de código adicionais

Confira também

Comentários

Recursos adicionais

Enviar mensagens de instalação proativas

Mensagens proativas no Teams

Instalação proativa de aplicativos no Teams

Permissões

Habilitar a instalação proativa de aplicativos e mensagens

Criar e publicar seu bot de mensagens proativo para o Teams

Obtenha o teamsAppId para seu aplicativo

Determinar se o bot está instalado no momento para um destinatário da mensagem

Instalar seu aplicativo

Recuperar a conversa chatId

Enviar mensagens proativas

Trechos de código

Exemplo de código

Exemplos de código adicionais

Confira também

Comentários

Recursos adicionais

Obtenha o `teamsAppId` para seu aplicativo

Recuperar a conversa `chatId`