Send proactive installation messages
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. |
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.
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 admin must explicitly grant permissions to an application. After the application is granted permissions, all members of the Microsoft Entra tenant get the granted permissions.
Important
Microsoft Graph can only install apps published to your organization's app store or the Microsoft Teams Store.
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.
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
objectid
, 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 asIdFromManifest
and theexternalId
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.
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.
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.
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
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
.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 broaderChat.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}')
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.
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.");
}
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 |
Platform Docs feedback
Platform Docs is an open source project. Select a link to provide feedback: