Send proactive installation messages

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:

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:

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.

Enable proactive app installation and messaging

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.

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 installed for a message recipient

You can determine whether your bot is 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

{
   "[email protected]" : "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.");
}

server.get('/api/notify', async (req, res) => {
    for (const conversationReference of Object.values(conversationReferences)) {

        // Sends a proactive message to a conversation.
        await adapter.continueConversationAsync(process.env.MicrosoftAppId, conversationReference, async context => {
            await context.sendActivity('proactive hello');
        });
    }
    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

Code sample

Additional code samples

See also

• Manage app setup policies in Microsoft Teams
• Send proactive notifications to users SDK v4
• Send activity feed notifications to users in Microsoft Teams
• Add app to team - Microsoft Graph v1.0
• Microsoft Teams service limits