Instale proativamente seu bot para usuários usando o Microsoft Graph

Se você precisar enviar mensagens para usuários que não instalaram ou interagiram anteriormente com seu aplicativo, por exemplo, para transmitir informações importantes para todos em sua organização, você pode usar a API do Graph para instalar proativamente seu bot para esses usuários. 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.

Este artigo aborda como usar o Microsoft Graph para marcar o status da instalação e instalar seu bot programaticamente. Após a instalação, consulte Enviar uma mensagem de boas-vindas pessoal para saber como recuperar a ID da conversa e enviar uma mensagem 1:1 ao usuário.

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:

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

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

Habilitar a instalação proativa de aplicativos e mensagens

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.

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:tipo de recurso teamsApp

  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 fornecida 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 estiver na Teams Store, ele teamsAppId é o mesmo que IdFromManifest e não externalId deve ser usado neste caso.

• Se o aplicativo já tiver sido carregado para um usuário no escopo pessoal:

  Referência da página do Microsoft Graph:Listar aplicativos instalados para o 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 o aplicativo já tiver sido carregado para um canal no escopo da equipe:

  Referência da página Microsoft Graph:Listar aplicativos na 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 para um destinatário da mensagem

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

Referência da página do Microsoft Graph:Listar aplicativos instalados para o 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 de 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.

Para as próximas etapas, consulte Enviar uma mensagem de boas-vindas pessoal para saber como recuperar a ID da conversa e enviar uma mensagem 1:1 ao usuário.

Exemplo de código

Exemplos de código adicionais

Confira também

• Gerenciar políticas de configuração de aplicativo no Teams
• Sistema de mensagens proativo com o SDK do Teams
• Enviar notificações do feed de atividades para usuários no Microsoft Teams
• Adicionar aplicativo à equipe - Microsoft Graph v1.0
• Limites do serviço do Microsoft Teams