Enviar notificações de feed de atividades para usuários no Microsoft Teams

  • Artigo

O feed de atividades do Microsoft Teams permite que os usuários triagem itens que exigem atenção notificando-os de alterações. Você pode usar as APIs de notificação do feed de atividades no Microsoft Graph para estender essa funcionalidade aos seus aplicativos. Isso permite que seus aplicativos forneçam experiências mais avançadas e envolvam melhor os usuários, ajudando a mantê-los atualizados com alterações nas ferramentas e fluxos de trabalho que eles usam.

Usar casos de notificações de feed de atividades

  • Notícias: ajuda os usuários a se manterem atualizados com as informações mais recentes, como novas atribuições ou novas postagens.
  • Colaboração: quando você compartilha um arquivo ou @ menção um usuário em um comentário, os usuários podem ver uma visualização de texto na faixa de notificação.
  • Lembretes: uma notificação para informar sobre um evento ou uma tarefa. Por exemplo, você tem uma data de vencimento do treinamento hoje, e o aplicativo envia uma notificação de lembrete para ajudá-lo a se lembrar da tarefa ou evento.
  • Alertas: Notificações, que exigem atenção urgente ou imediata. Por exemplo, a data de vencimento de um treinamento passou ou um administrador enviou uma solicitação para corrigir um bug com a maior prioridade.

Vantagens das notificações do feed de atividades

  • A notificação do feed de atividades é uma integração nativa do Teams que leva o usuário perfeitamente ao aplicativo Tab, trazendo um envolvimento adicional do usuário da Atividade para seu aplicativo.
  • A notificação do feed de atividades vem com uma notificação do sistema operacional na área de trabalho e nos clientes móveis do Teams, para que a atenção do usuário seja captada do pop-up e do som do sistema.
  • O conteúdo da notificação é altamente personalizável, permitindo que os usuários visualizem o resumo dos eventos notificados.
  • Você pode vincular profundamente seu aplicativo a uma notificação para que, quando um usuário seleciona a notificação, ele aumenta o envolvimento do aplicativo de usuário.
  • Você pode enviar notificação do feed de atividades para vários destinatários. Por exemplo, enviar uma notificação pessoal ou enviar notificações em lote para um grupo de usuários.
  • A localização do manifesto do aplicativo (anteriormente chamada de manifesto de aplicativo do Teams) dá suporte ao texto modelo em notificações do feed de atividades.

Entender os conceitos básicos das notificações do feed de atividades

No Teams, as notificações do feed de atividades consistem em vários bits de informações exibidos juntos, conforme mostrado na imagem a seguir:

A captura de tela mostra os componentes de uma notificação do feed de atividades.

Os componentes incluem:

Contador Descrição
1 Avatar: mostra quem iniciou a atividade.
2 Tipo de atividade ou ícone de aplicativo: o tipo de atividade ou ícone de aplicativo retrata o tipo de atividade. Para notificações de aplicativo, o ícone de linha é substituído por um ícone de aplicativo.
3 Título: Ator + motivo: Ator: nome do usuário ou aplicativo que iniciou a atividade. Motivo: descreve a atividade.
4 Carimbo de data/hora: mostra quando a atividade aconteceu.
5 Visualização de texto: mostra uma linha truncada desde o início da notificação.
6 Local: mostra onde a atividade aconteceu no Teams.

O exemplo a seguir mostra que os componentes juntos fornecem os detalhes sobre uma notificação.

A captura de tela mostra o exemplo de notificação.

Tipos de cartões de notificação do feed de atividades

As variantes a seguir mostram os tipos de cartões de notificação do feed de atividades que você pode exibir. O logotipo do aplicativo substitui o avatar do usuário por notificações geradas pelo aplicativo:

A captura de tela mostra as notificações do feed de atividades em uma área de trabalho.

Contador Descrição
1 Teams personalizado
2 Windows
3 Mac

Requisitos para usar as APIs de notificação do feed de atividades

As APIs do feed de atividades funcionam com um aplicativo do Teams. A seguir estão os requisitos para enviar notificações do feed de atividades:

  • O manifesto do aplicativo deve ter a ID do aplicativo Microsoft Entra adicionada à webApplicationInfo seção. Para obter mais informações, consulte esquema de manifesto do aplicativo.
  • As notificações de atividade podem ser enviadas com ou sem tipos de atividade adicionados no manifesto do aplicativo.
    • Por padrão, você pode usar as APIs de notificação de atividade sem adicionar a activities seção no manifesto do aplicativo. O systemDefault tipo de atividade é reservado, o que permite que você forneça texto de forma gratuita na Actor+Reason linha da notificação do feed de atividades. Para obter mais informações, consulte enviar notificações de feed de atividade personalizável.

      Observação

      O systemDefault tipo de atividade está disponível apenas na versão prévia do desenvolvedor público.

    • Se você quiser enviar uma notificação com modelo no modo tradicional, a activityTypes propriedade deverá ser adicionada na seção atividades . Para obter mais informações, consulte esquema de manifesto do aplicativo.
  • O aplicativo Teams deve ser instalado para o destinatário pessoalmente ou em uma equipe ou chat do qual eles fazem parte.

Permissões

Use permissões delegadas ou de aplicativo para enviar notificações do feed de atividades. Quando você usa permissões de aplicativo, recomendamos usar o RSC (consentimento específico do recurso), pois a TeamsActivity.Send.User permissão é consentida pelo usuário para enviar notificações de atividade. Certifique-se de adicionar as permissões RSC no arquivo de manifesto do aplicativo.

Atualização do manifesto do aplicativo

Esta seção descreve as atualizações que precisam ser adicionadas ao manifesto do aplicativo. Verifique se você usa a versão 1.7 do manifesto do aplicativo ou posterior.

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

Atualização webApplicationInfo

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
Parâmetro Tipo Descrição
id string Microsoft Entra ID do aplicativo (ID do cliente).
resource string Recurso associado ao aplicativo Microsoft Entra. Também conhecida como URL de resposta ou redirecionamento no Portal do Microsoft Azure.

Observação

Você pode receber um erro se vários aplicativos do Teams no mesmo escopo (equipe, chat ou usuário) estiverem usando o mesmo aplicativo Microsoft Entra. Verifique se você está usando aplicativos Microsoft Entra exclusivos.

Atualização de atividades

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}
Parâmetro Tipo Descrição
type string Tipo de atividade. Isso precisa ser exclusivo em um manifesto de aplicativo específico.
description string Descrição curta legível pelo homem. Isso está visível no cliente do Teams.
templateText string Texto do modelo para a notificação de atividade. Você pode adicionar seus parâmetros encapsulando parâmetros em {}.

Observação

  • O actor é um parâmetro especial que sempre leva o nome do chamador. Em chamadas delegadas, actor é o nome do usuário. Em chamadas somente de aplicativo, ele usa o nome do aplicativo Teams.
  • O tipo de atividade reservada systemDefault não deve ser incluído na activities seção do manifesto do aplicativo. O systemDefault tipo de atividade permite que você forneça texto de forma gratuita na Actor+Reason linha da notificação do feed de atividades.

Atualização de autorização

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
}
Parâmetro Tipo Descrição
type string O tipo da permissão RSC.
nome string O nome da permissão RSC. Para obter mais informações, consulte permissões RSC com suporte.

Instalar o aplicativo Teams

Os aplicativos do Teams devem ser instalados em uma equipe, chat ou para um usuário no escopo pessoal para que os usuários recebam notificações do feed de atividades. Para obter detalhes, confira Métodos de distribuição de aplicativos do Teams. Para fins de desenvolvimento, preferimos carregar o aplicativo personalizado. Após o desenvolvimento, você pode escolher o método de distribuição correto com base em se deseja distribuir para um locatário ou para todos os locatários.

Você também pode usar APIs de instalação de aplicativo do Teams para gerenciar instalações de aplicativo do Teams.

Enviar notificações de feed de atividades aos usuários

Como um aplicativo do Teams pode ser instalado para um usuário, em uma equipe ou em um chat, ele também pode enviar notificações nos três contextos a seguir:

Além disso, você pode enviar notificações em massa para até 100 usuários por vez:

Para encontrar detalhes sobre os tópicos com suporte para cada cenário, consulte as APIs específicas. Há suporte para tópicos baseados em texto personalizados para todos os cenários.

Você pode usar a notificação do feed de atividades nos seguintes cenários:

  • Notifique os indivíduos sobre o conteúdo personalizado que requer sua atenção.
  • Mostrar conteúdo avançado no aplicativo Tab ou na URL.
  • Dá suporte a interações complexas do usuário.
  • Envie notificações delegadas do usuário que iniciou a notificação.
  • Coloque o modelo no manifesto do aplicativo.
  • O Teams manipula a localização para notificações.

Observação

O ícone de atividade é baseado no contexto em que a solicitação é feita. Se a solicitação for feita com permissões delegadas, a foto do usuário será exibida como o avatar, enquanto o ícone do aplicativo teams será exibido como o ícone de atividade. Em um contexto somente aplicativo, o ícone do aplicativo teams é usado como o avatar e o ícone de atividade é omitido.

Personalizar as notificações

Os usuários do Teams podem personalizar as notificações que veem no feed ou como uma faixa. As notificações geradas por meio de APIs de feed de atividades também podem ser personalizadas. Os usuários podem escolher como são notificados por meio de configurações no Teams. Os aplicativos do Teams aparecem na lista para o usuário escolher, conforme mostrado na seguinte captura de tela:

A captura de tela mostra as configurações de Notificações no Teams, com a opção Personalizada realçada.

Os usuários podem selecionar Editar ao lado de um aplicativo e personalizar as notificações. O manifesto do aplicativo exibe o description campo.

A captura de tela mostra as notificações personalizadas para o Banner e o feed de um aplicativo do Teams.

Exemplos

Para obter exemplos sobre como enviar uma notificação do feed de atividades, consulte enviar exemplos de notificação do feed de atividades.

Tipo de atividade reservado para enviar notificações de feed de atividades

  • O systemDefault tipo de atividade é reservado e não pode ser usado no manifesto do aplicativo durante a adição de atividades.
  • Recomendamos usar notificações de modelo, pois elas dependem de modelos de atividade no manifesto do aplicativo para lotes recorrentes e grandes de notificações.
  • O systemDefault tipo de atividade reservada está disponível mesmo se os outros tipos de atividade estiverem listados no manifesto do aplicativo.

A seguir estão os benefícios e limitações para o systemDefault tipo de atividade:

Benefícios Limitações
Você pode testar novos cenários e tentar APIs de notificação do feed de atividades sem adicionar tipos de atividade ao manifesto do aplicativo.

Com os aplicativos da Teams Store, o systemDefault tipo de atividade simplifica o processo e economiza tempo, pois elimina a necessidade de ajustes constantes nos tipos de atividade no manifesto do aplicativo. O systemDefault tipo de atividade está pronto para uso imediatamente.		 Você não pode utilizar os recursos de localização internos fornecidos pelo manifesto do aplicativo.

Você não pode confiar no envio de notificações personalizáveis com o tipo de systemDefault atividade. Os usuários podem desativar todas as notificações do seu aplicativo com um alternância nas configurações do cliente do Teams, o que pode obstruir a comunicação entre seu aplicativo e seus usuários.

Exemplo de código

Nome do exemplo Descrição .NET Node.js
Enviar notificações de feed de atividades O aplicativo de exemplo demonstra como enviar notificações de feed de atividades usando o Microsoft API do Graph. View View

Guias passo a passo

Siga o guia passo a passo para enviar notificações do feed de atividades no Teams.

Confira também