Enviar mensagens de instalação proativa

Artigo
06/06/2024

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. Por vezes, tem de enviar mensagens proativas aos utilizadores que não tenham sido instalados ou interagidos anteriormente com a sua aplicação. Por exemplo, se precisar de enviar mensagens a informações importantes para todas as pessoas na sua organização, pode utilizar a Microsoft Graph API para instalar proativamente o bot para os seus utilizadores.

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 utilizar estas permissões, tem de adicionar uma chave webApplicationInfo ao manifesto da sua aplicação (anteriormente denominado manifesto da aplicação Teams) com os seguintes valores:

id: O ID da aplicação 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 inquilino do Microsoft Entra tem de conceder explicitamente permissões a uma aplicação. Depois de ser concedida permissão à aplicação, todos os membros do inquilino do Microsoft Entra obtêm as permissões concedidas.

Habilitar a instalação proativa de aplicativos e mensagens

Importante

O Microsoft Graph só pode instalar aplicações publicadas na app store da sua organização ou na Microsoft Teams Store.

Criar e publicar seu bot de mensagens proativo para o Teams

Para começar, precisa de um bot para o Teams com capacidades de mensagens proativas que se encontra na loja de aplicações da sua organização ou na Loja Teams.

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 de página do Microsoft Graph:teams Tipo de recurso de aplicação

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. Isto é diferente do ID que forneceu no manifesto da aplicação:
```
{
  "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 a aplicação está na Loja Teams, a teamsAppId é igual IdFromManifest a e externalId não pode ser utilizada neste caso.
Se a sua aplicação já tiver sido carregada para um utilizador no âmbito pessoal:

Referência da página do Microsoft Graph:Listar aplicações instaladas para o utilizador

Solicitação HTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Se a sua aplicação já tiver sido carregada para um canal no âmbito da equipa:

Referência de página do Microsoft Graph:Listar aplicações na equipa

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 aplicações instaladas para o utilizador

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 a aplicação não estiver instalada.
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 aplicação para o utilizador

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 a aplicação é instalada para o utilizador, o bot recebe uma conversationUpdatenotificação de evento que contém as informações necessárias para enviar a mensagem proativa.

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

Você deve ter o {teamsAppInstallationId}. Se não o tiver, utilize 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:

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

Pedido 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

Compartilhar via

Enviar mensagens de instalação proativa

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

Compartilhar via

Enviar mensagens de instalação proativa

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`