Edit

Send proactive installation messages

  • Article

Proactive messaging in Teams

Proactive messages are initiated by bots to start conversations with a user. They serve many purposes including sending welcome messages, conducting surveys or polls, and broadcasting organization-wide notifications. Proactive messages in Teams can be delivered as either ad-hoc or dialog-based conversations:

Message type Description
Ad-hoc proactive message The bot interjects a message without interrupting the conversation flow.
Dialog-based proactive message The bot creates a new dialog thread, takes control of a conversation, delivers the proactive message, closes, and returns control to the previous dialog.

Proactive app installation in Teams

Before your bot can proactively message a user, it must be installed either as a personal app or in a team where the user is a member. At times, you need to proactively message users that haven't installed or previously interacted with your app. For example, If you need to message important information to everyone in your organization, then you can use the Microsoft Graph API to proactively install your bot for your users.

Permissions

Microsoft Graph teamsAppInstallation resource type permissions help you to manage your app's installation lifecycle for all user (personal) or team (channel) scopes within the Microsoft Teams platform:

Application permission Description
TeamsAppInstallation.ReadWriteSelfForUser.All Allows a Teams app to read, install, upgrade, and uninstall itself for any user, without prior sign in or use.
TeamsAppInstallation.ReadWriteSelfForTeam.All Allows a Teams app to read, install, upgrade, and uninstall itself in any team, without prior sign in or use.

To use these permissions, you must add a webApplicationInfo key to your app manifest (previously called Teams app manifest) with the following values:

  • id: Your Microsoft Entra app ID.
  • resource: The resource URL for the app.

Note

  • Your bot requires application and not user delegated permissions because the installation is for others.

  • A Microsoft Entra tenant administrator must explicitly grant permissions to an application. After the application is granted permissions, all members of the Microsoft Entra tenant get the granted permissions.

Enable proactive app installation and messaging

Important

Microsoft Graph can only install apps published to your organization's app store or the Microsoft Teams Store.

Create and publish your proactive messaging bot for Teams

To get started, you need a bot for Teams with proactive messaging capabilities that is in your organization's app store or the Teams Store.

Tip

The production-ready Company Communicator app template permits broadcast messaging and is a good start to build your proactive bot application.

Get the teamsAppId for your app

You can retrieve the teamsAppId in the following ways:

  • From your organization's app catalog:

    Microsoft Graph page reference: teamsApp resource type

    HTTP GET request:

    GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'

    The request must return a teamsApp object id, which is the app's catalog generated app ID. This is different from the ID that you provided in your app manifest:

    {
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}

    Note

    When the app is in the Teams Store, the teamsAppId is same as IdFromManifest and the externalId must not be used in this case.

  • If your app has already been uploaded for a user in personal scope:

    Microsoft Graph page reference: List apps installed for user

    HTTP GET request:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

  • If your app has already been uploaded for a channel in team scope:

    Microsoft Graph page reference: List apps in team

    HTTP GET request:

    GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

    Tip

    To narrow the list of results, you can filter any of the fields of the teamsApp object.

Determine whether your bot is currently installed for a message recipient

You can determine whether your bot is currently installed for a message recipient as follows:

Microsoft Graph page reference: List apps installed for user

HTTP GET request:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

The request returns:

  • An empty array if the app isn't installed.
  • An array with a single teamsAppInstallation object if the app is installed.

Install your app

You can install your app as follows:

Microsoft Graph page reference: Install app for user

HTTP POST request:

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}"
}

If the user has Microsoft Teams running, app installation occurs immediately. A restart may be required to view the installed app.

Retrieve the conversation chatId

When your app is installed for the user, the bot receives a conversationUpdate event notification that contains the necessary information to send the proactive message.

Microsoft Graph page reference: Get chat

  1. You must have your app's {teamsAppInstallationId}. If you don't have it, use the following:

    HTTP GET request:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

    The id property of the response is the teamsAppInstallationId.

  2. Make the following request to fetch the chatId:

    HTTP GET request (permission—TeamsAppInstallation.ReadWriteSelfForUser.All):

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat

    The id property of the response is the chatId.

    You can also retrieve the chatId with the following request but it requires the broader Chat.Read.All permission:

    HTTP GET request (permission—Chat.Read.All):

    GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')

Send proactive messages

Your bot can send proactive messages after the bot has been added for a user or a team, and has received all the user information.

Code snippets

The following code provides an example of sending proactive messages:

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.");
}

Code sample

Sample Name Description .NET Node.js
Proactive installation of app and sending proactive notifications This sample shows how you can use proactive installation of app for users and send proactive notifications by calling Microsoft Graph APIs. View View

Additional code samples

Teams proactive messaging code samples

See also