Microsoft Teams: Deeplink pro seu App através da Notificação

Desenvolvendo recentemente um meio de integrar um aplicativo web já existente ao Microsoft Teams, me deparei com a necessidade de que a notificação do Teams ao direcionar para o aplicativo instalado dentro do Teams também passasse um parâmetro extra para que o aplicativo existente pudesse tratar esse parâmetro e redirecionar o usuário para área correta.

Foi custoso achar uma resposta para isso, mas acabei com a ajuda de um colega e dessa maravilhosa página https://microsoft.github.io/app-camp/aad/Deeplink/ conseguir passar parâmetro para dentro da aplicação quando abre através da Notificação.

Quando você envia uma notificação para o usuário do seu aplicativo no Teams você tem a possibilidade de estabelecer duas formas de ao clicar na notificação o usuário ser direcionado para o seu aplicativo direto utilizando o source no item topic como text ou entityURL e passando o value ou o webUrl como no exemplo abaixo.

//Corpo do envio da notificação
//POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
{    
   "topic": {
       "source": "entityUrl",
       "value": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teams_app_id}"
   },

    "activityType": "novaNotificacao",
    "previewText": {
        "content": "Temos uma nova informação para você!!"
    },
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "617310a6-9d5d-4459-b268-07802596d419"
        }
    ]
}

Utilizando o entityUrl é o jeito mais simples de ao clicar na notificação o seu usuário seja redirecionado para o seu aplicativo dentro do Teams. Acontece que através desse método não é possível passar parâmetros nem especificar em qual das abas do seu aplicativo você quer que abra inicialmente. O jeito é usar o modo text passando o weburl. O webURL é uma url do Teams que no entanto utiliza o ID do Teams que é gerado quando envia o aplicativo para a loja de aplicativos da organização, seguido do entityId é que a aba a qual você quer abrir dentro do seu aplicativo. No código abaixo fica mais fácil de entender.

//Corpo do envio da notificação
//POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
{
    "topic": {
        "source": "text",
        "webUrl": "https://teams.microsoft.com/l/entity/{uploaded_teams_app_id}/{entity_id}?context=%7B%22subEntityId%22:%22https://exemplo.com.br/timeline/post/1406%22%7D"
    },
    "activityType": "novaNotificacao",
    "previewText": {        
        "content": "Temos uma nova informação para você!!"
    ]},   
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "617310a6-9d5d-4459-b268-07802596d419"
        }
    ]
}

A sacada para o envio de um parâmetro seu para dentro do seu aplicativo é utilizar o parâmetro “context” onde um JSON no formato {“subEntityId”:”XXXXX”} é passado o valor do subEntityId que pode ser um valor número, uma string ou até um objeto é recuperado através do Teams JS SDK, mas para confusão geral o parâmetro dentro do objeto do contexto é “context.page.subPageId”, chora.

//dentro da sua aplicação
//....
try{

    await app.initialize();
    const context = app.getContext();
    const parametro_passado = context.page.subPageId; //:)        

}
//...

Resumindo: você passa o contexto utilizando o subEntityId e recupera através do Teams JS SDK utilizando o objeto de contexto no “context.page.subPageId”.

Dai com o parâmetro em mãos você faz o que precisa fazer antes da aplicação carregar. No contexto você pode passar uma URL e configurar o seu app para redirecionar o parametro_passado com o valor da URl. Isso simplifica bastante o desenvolvimento e redirecionamento interno.