Enviar notificações de feed de atividades aos usuários no Microsoft TeamsSend activity feed notifications to users in Microsoft Teams

O feed de atividades do Microsoft Teams permite que os usuários triagem itens que exigem atenção notificando-os sobre alterações.The Microsoft Teams activity feed enables users to triage items that require attention by notifying them of changes. Você pode usar as APIs de notificação de feed de atividades no Microsoft Graph para estender essa funcionalidade para seus aplicativos.You can use the activity feed notification APIs in Microsoft Graph to extend this functionality to your apps. Isso permite que seus aplicativos forneçam experiências mais completas e envolvam melhor os usuários, ajudando a mantê-los atualizados com as alterações nas ferramentas e nos fluxos de trabalho que eles usam.This allows your apps to provide richer experiences and better engage users by helping to keep them up to date with changes in the tools and workflows they use.

Noções básicas da notificação de feed de atividadesUnderstanding the basics of activity feed notification

As notificações de feed de atividades no Microsoft Teams são compostas por vários bits de informações, exibidas juntas, conforme mostrado na imagem a seguir.Activity feed notifications in Microsoft Teams are comprised of multiple bits of information, displayed together, as shown in the following image.

Imagem mostrando componentes de uma notificação de feed de atividades

Os componentes incluem:The components include:

  • O ator que iniciou a atividadeThe actor who initiated the activity
  • Um ícone que representa o tipo de atividadeAn icon that represents the activity type
  • O motivo pelo qual o ator fez a atividadeThe reason the actor did the activity
  • Uma visualização de textoA text preview
  • Um carimbo de data/horaA time stamp
  • O local da atividadeThe location of the activity

O exemplo a seguir mostra como esses componentes juntos fornecem os detalhes sobre uma notificação.The following example shows how these components together provide the details about a notification. Este exemplo é uma notificação sobre um usuário mencionado em uma comunidade do Yammer.This example is a notification about a user mentioned in a Yammer community.

Exemplo de notificação de actifity do Yammer

Requisitos para usar as APIs de notificação do feed de atividadesRequirements for using the activity feed notification APIs

As APIs de feed de atividades funcionam com um aplicativo do Teams.Activity feed APIs work with a Teams app. A seguir estão os requisitos para o envio de notificações do feed de atividades:The following are the requirements for sending activity feed notifications:

  • O manifesto do aplicativo Teams deve ter a ID de aplicativo do Azure AD adicionada à webApplicationInfo seção.The Teams app manifest must have the Azure AD app ID added to the webApplicationInfo section. Para obter detalhes, consulte o esquema de manifesto.For details, see manifest schema.
  • Os tipos de atividade devem ser declarados na activities seção.Activity types must be declared in the activities section. Para obter detalhes, consulte o esquema de manifesto.For details, see manifest schema.
  • O aplicativo Teams deve ser instalado para o destinatário, pessoalmente, ou em uma equipe ou chat do que ele faz parte.The Teams app must be installed for the recipient, either personally, or in a team or chat they are part of. Para saber mais, confira a instalação do aplicativo Teams.For more information, see Teams app installation.

Alterações no manifesto do aplicativo TeamsTeams app manifest changes

Esta seção descreve as alterações que precisam ser adicionadas ao manifesto do aplicativo Teams.This section describes the changes that need to be added to Teams app manifest. Observe que você deve estar usando a versão do manifesto do aplicativo Teams ou 1.7 superior.Note that you must be using the Teams app manifest version 1.7 or greater.

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

Alterações na seção webApplicationInfowebApplicationInfo section changes

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
ParâmetroParameter TipoType DescriçãoDescription
idid cadeia de caracteresstring ID do aplicativo Azure AD (ID do cliente).Azure AD app ID (client ID).
recursoresource cadeia de caracteresstring Recurso associado ao aplicativo Azure AD.Resource associated with the Azure AD app. Também conhecido como URL de resposta ou redirecionamento no Portal do Azure.Also known as reply or redirect URL in the Azure Portal.

Observação: Você pode receber um erro se vários aplicativos do Teams no mesmo escopo (equipe, chat ou usuário) estão usando o mesmo aplicativo do Azure AD.Note: You might get an error if multiple Teams apps in the same scope (team, chat or user) are using the same Azure AD app. Certifique-se de que você esteja usando aplicativos exclusivos do Azure AD.Make sure that you're using unique Azure AD apps.

alterações na seção de atividadesactivities section changes

"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âmetroParameter TipoType DescriçãoDescription
typetype stringstring Tipo de atividade.Type of activity. Isso precisa ser exclusivo em um manifesto específico.This needs to be unique in a specific manifest.
descriptiondescription stringstring Descrição curta acessível para humanos.Human-readable short description. Isso ficará visível no cliente do Microsoft Teams.This will be visible on the Microsoft Teams client.
templateTexttemplateText cadeia de caracteresstring Texto do modelo para a notificação de atividade.Template text for the activity notification. Você pode declarar seus parâmetros encapsulando parâmetros em {} .You can declare your parameters by encapsulating parameters in {}.

Observação: actor é um parâmetro especial que sempre leva o nome do chamador.Note: actor is a special parameter that always takes the name of the caller. Em chamadas delegadas, actor é o nome do usuário.In delegated calls, actor is the user's name. Em chamadas somente de aplicativo, ele recebe o nome do aplicativo Teams.In application-only calls, it takes the name of the Teams app.

Instalando o aplicativo TeamsInstalling the Teams app

Os aplicativos do Teams podem ser instalados em uma equipe, um chat ou para um usuário pessoalmente e podem ser distribuídos de várias maneiras.Teams apps can be installed in a team, a chat, or for a user personally, and can be distributed in multiple ways. Para obter detalhes, confira os métodos de distribuição de aplicativos do Teams.For details, see Teams app distribution methods. Normalmente, o sideload é preferencial para fins de desenvolvimento.Typically, sideloading is preferred for development purposes. Após o desenvolvimento, você pode escolher o método de distribuição certo com base em se você deseja distribuir para um locatário ou para todos os locatários.After development, you can choose the right distribution method based on whether you want to distribute to one tenant or to all tenants.

Você também pode usar APIs de instalação de aplicativos do Teams para gerenciar instalações de aplicativos do Teams.You can also use Teams app installation APIs to manage Teams app installations.

Enviar notificações de feed de atividades aos usuáriosSending activity feed notifications to users

Como um aplicativo do Teams pode ser instalado para um usuário, em uma equipe ou em um chat, as notificações também podem ser enviadas nesses três contextos:Because a Teams app can be installed for a user, in a team, or in a chat, the notifications can be sent in these three contexts as well:

Para obter detalhes sobre quais tópicos são suportados para cada cenário, consulte as APIs específicas.For details about what topics are supported for each scenario, see the specific APIs. Tópicos personalizados baseados em texto são suportados para todos os cenários.Custom text-based topics are supported for all scenarios.

Exemplo 1: Notificar um usuário sobre uma tarefa criada em um chatExample 1: Notify a user about a task created in a chat

Este exemplo mostra como você pode enviar uma notificação de feed de atividades para uma nova tarefa criada em um chat.This example shows how you can send an activity feed notification for a new task created in a chat. Nesse caso, o aplicativo Teams deve ser instalado em um chat com ID e o usuário também deve fazer parte chatId 569363e2-4e49-4661-87f2-16f245c5d66a do chat.In this case, the Teams app must be installed in a chat with Id chatId and user 569363e2-4e49-4661-87f2-16f245c5d66a must be part of the chat as well.

SolicitaçãoRequest

POST https://graph.microsoft.com/beta/chats/{chatId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/chats/{chatId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

RespostaResponse

HTTP/1.1 204 No Content

Exemplo 2: Notificar um usuário sobre uma tarefa criada em uma equipeExample 2: Notify a user about a task created in a team

Este exemplo mostra como você pode enviar uma notificação de feed de atividades para uma equipe.This example shows how you can send an activity feed notification for a team. Este exemplo notifica o proprietário da equipe sobre uma nova tarefa criada que requer sua atenção.This example notifies the team owner about a new task created that requires their attention.

SolicitaçãoRequest

POST https://graph.microsoft.com/beta/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/beta/teams/{teamId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

RespostaResponse

HTTP/1.1 204 No Content

Exemplo 3: Notificar um usuário sobre um evento usando um tópico personalizadoExample 3: Notify a user about an event using a custom topic

Conforme visto nos exemplos anteriores, você pode vincular a diferentes aspectos de uma equipe ou de um chat.As seen in the previous examples, you can link to different aspects of a team or a chat. No entanto, se você quiser vincular a um aspecto que não faz parte da equipe ou não é representado pelo Microsoft Graph, ou se quiser personalizar o nome, você pode definir a origem do para e passar um valor personalizado para topic text ele.However, if you want to link to an aspect that is not part of the team or is not represented by Microsoft Graph, or if you want to customize the name, you can set the source of the topic to text and pass in a custom value for it. Além disso, webUrl é necessário quando você usa a fonte como topic text .Additionally, webUrl is required when you use topic source as text.

O exemplo de notificação do Yammer mostrado anteriormente usa um tópico personalizado porque os recursos do Yammer não são suportados pelo Microsoft Graph.The Yammer notification example shown earlier uses a custom topic because Yammer's resources are not supported by Microsoft Graph.

Observação: webUrl deve começar com o domínio do Microsoft Teams (teams.microsoft.com por exemplo).Note: webUrl must start with the Microsoft Teams domain (teams.microsoft.com for example).

SolicitaçãoRequest

POST https://graph.microsoft.com/beta/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Deployment Approvals Channel",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "New deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "Microsoft.Teams.GraphSvc.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ]
}

RespostaResponse

HTTP/1.1 204 No Content

Personalização de como as notificações alertam vocêCustomizing how the notifications alert you

Os usuários do Microsoft Teams podem personalizar as notificações que veem no feed, como uma faixa e assim por diante.Microsoft Teams users can customize the notifications they see in their feed, as a banner, and so on. As notificações geradas por meio de APIs de feed de atividades também podem ser personalizadas.Notifications generated through activity feed APIs can also be customized. Os usuários podem escolher como serão notificados por meio das configurações no Microsoft Teams.Users can choose how they are notified via settings in Microsoft Teams. Os aplicativos do Teams aparecerão na lista de escolha do usuário, conforme mostrado na captura de tela a seguir.Teams apps will appear in the list for the user to choose from, as shown in the following screenshot.

Captura de tela das configurações de Notificações no Teams, com a opção Personalizada realçada

Os usuários podem clicar em Editar ao lado de um aplicativo e personalizar as notificações, conforme mostrado no exemplo a seguir.Users can click Edit next to an app and customize the notifications, as shown in the following example. O description campo no manifesto do aplicativo Teams é exibido.The description field in the Teams app manifest is displayed.

Screenshot showing notifications customized to Banner and feed for a Teams app

Perguntas FrequentesFAQs

Quem precisa instalar o aplicativo Teams?Who needs to install the Teams app?

O usuário de destino deve ter o aplicativo Teams que está enviando notificações instalado.The target user must have the Teams app that is sending notifications installed.

Um usuário pode enviar notificações para si mesmo?Can a user send notifications to themselves?

Não, um usuário não pode enviar notificações para si mesmo.No, a user cannot send notifications to themselves. Para este cenário, use permissões de aplicativo.For this scenario, use application permissions.

Um aplicativo do Teams pode controlar como as notificações são mostradas ao usuário?Can a Teams app control how the notifications are shown to the user?

Não, somente os usuários podem alterar as configurações de notificação.No, only users are allowed to change notification settings.

Instalei meu aplicativo, por que não vejo as configurações de notificação na conta de usuário?I installed my app, why don't I see notification settings under the user account?

As configurações aparecerão depois que a primeira notificação for enviada pelo aplicativo Teams.The settings will appear after the first notification is sent by the Teams app. Isso reduz o número de configurações que os usuários veem.This reduces the number of settings that users see.

Eu começo a receber um erro 409 (conflito), como faço para resolvê-lo?I started getting a 409 (conflict) error, how do I resolve it?

Conflict ocorrem principalmente quando vários aplicativos do Teams instalados no mesmo escopo (equipe, chat, usuário e assim por diante) têm a mesma appId do Azure AD na seção do webApplicationInfo manifesto.Conflict errors primarily occur when multiple Teams apps installed in the same scope (team, chat, user, and so on) have the same Azure AD appId in the webApplicationInfo section of the manifest. Quando isso acontece, você receberá um erro Found multiple applications with the same Azure AD App ID 'Your AzureAD AppId'. como.When this happens, you will get an error such as Found multiple applications with the same Azure AD App ID 'Your AzureAD AppId'.. Certifique-se de usar aplicativos exclusivos do Azure AD para aplicativos exclusivos do Teams.Make sure that you use unique Azure AD apps for unique Teams apps. Observe que você pode ter o mesmo aplicativo teams instalado em vários escopos (equipe + usuário, por exemplo).Note that you can have the same Teams app installed in multiple scopes (team + user for example).