Отправка сообщений об упреждающей установке

Статья
04/04/2023

Упреждающий обмен сообщениями в Teams

Упреждающие сообщения инициируются ботами для начала разговора с пользователем. Они служат многим целям, включая отправку приветственных сообщений, проведение опросов или исследований, а также рассылку уведомлений широкого охвата по всей организации. Упреждающие сообщения в Teams могут быть доставлены в виде ситуативных или диалоговых бесед:

Тип сообщения	Описание
Ситуативное упреждающее сообщение	Бот вставляет сообщение, не прерывая поток беседы.
Диалоговое упреждающее сообщение	Бот создает новую ветку диалога, берет на себя управление беседой, доставляет упреждающее сообщение, закрывает и возвращает управление предыдущему диалогу.

Упреждающая установка приложений в Teams

Прежде чем бот сможет активно отправлять сообщения пользователю, его необходимо установить либо как личное приложение, либо в команде, участником которой является пользователь. Иногда необходимо заранее отправлять сообщения пользователям, которые не установили приложение или не взаимодействовали с ним. Например, если вам нужно отправить важную информацию всем сотрудникам организации, вы можете использовать API Graph Майкрософт для упреждающей установки бота для пользователей.

Разрешения

Разрешения Microsoft Graph типа ресурса teamAppInstallation помогают управлять жизненным циклом установки приложения для всех пользовательских (личных) или групповых (канальных) областей на платформе Microsoft Teams:

Разрешение приложения	Описание
`TeamsAppInstallation.ReadWriteSelfForUser.All`	Позволяет приложению Teams читать, устанавливать, обновлять и удалять себя для любого пользователя без предварительного входа или использования.
`TeamsAppInstallation.ReadWriteSelfForTeam.All`	Позволяет приложению Teams читать, устанавливать, обновлять и удалять себя в любой команде без предварительного входа или использования.

Чтобы использовать эти разрешения, необходимо добавить ключ webApplicationInfo в манифест приложения (ранее — манифест приложения Teams) со следующими значениями:

id: идентификатор приложения Microsoft Entra.
ресурс: URL-адрес ресурса для приложения.

Примечание.

Боту требуются приложения, а не делегированные пользователем разрешения, поскольку установка предназначена для других.
Администратор клиента Microsoft Entra должен явно предоставить разрешения приложению. После предоставления приложению разрешений все члены клиента Microsoft Entra получают предоставленные разрешения.

Включить упреждающую установку приложений и обмен сообщениями

Важно!

Microsoft Graph может устанавливать только приложения, опубликованные в магазине приложений вашей организации или Microsoft Teams Store.

Создайте и опубликуйте бот для активного обмена сообщениями для Teams

Чтобы приступить к работе, вам потребуется бот для Teams с возможностями упреждающего обмена сообщениями , который находится в магазине приложений вашей организации или в Магазине Teams.

Совет

Готовый к работе шаблон приложения Company Communicator позволяет осуществлять широковещательную рассылку сообщений и является хорошим началом для создания упреждающего приложения-бота.

Получите `teamsAppId` для приложения

Вы можете получить teamsAppId следующими способами:

Из каталога приложений организации:

Ссылка на страницу Microsoft Graph:тип ресурса teamsApp

ЗапросHTTP GET:
```
GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'
```
Запрос должен возвращать teamsAppобъектid, который представляет собой идентификатор приложения, сгенерированный каталогом приложения. Это отличается от идентификатора, указанного в манифесте приложения:
```
{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}
```
Примечание.

Если приложение находится в Магазине Teams, teamsAppId в этом случае не должно использоваться то же, что IdFromManifest и externalId .
Если приложение уже отправлено для пользователя в личных область:

Ссылка на страницу Microsoft Graph:список приложений, установленных для пользователя

ЗапросHTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Если ваше приложение уже отправлено для канала в команде область:

Ссылка на страницу Microsoft Graph:список приложений в команде

ЗапросHTTP GET:
```
GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'
```
Совет

Чтобы сузить список результатов, вы можете отфильтровать любое из полей объекта teamApp.

Определите, установлен ли ваш бот в настоящее время для получателя сообщения

Вы можете определить, установлен ли ваш бот для получателя сообщения, следующим образом:

Ссылка на страницу Microsoft Graph:список приложений, установленных для пользователя

ЗапросHTTP GET:

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

Запрос возвращает:

Пустой массив, если приложение не установлено.
Массив с одним объектом teamsAppInstallation, если приложение установлено.

Установите приложение

Вы можете установить приложение следующим образом:

Справочник по странице Microsoft Graph:установка приложения для пользователя

Запрос HTTP POST

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

Если у пользователя запущены Microsoft Teams, установка приложения происходит немедленно. Для просмотра установленного приложения может потребоваться перезагрузка.

Получить беседу `chatId`

Когда приложение установлено для пользователя, бот получает уведомление о событииconversationUpdate, содержащее необходимые сведения для отправки упреждающего сообщения.

Ссылка на страницу Microsoft Graph:Получение чата

У вас должен быть {teamsAppInstallationId} приложения. Если у вас его нет, используйте следующее:

ЗапросHTTP GET:
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'
```
Свойство id отклика — teamsAppInstallationId.
Отправьте следующий запрос, чтобы получить chatId:

HTTP-запрос GET (разрешение—TeamsAppInstallation.ReadWriteSelfForUser.All ):
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat
```
Свойство id отклика — chatId.

Вы также можете получить chatId с помощью следующего запроса, но для этого требуется более широкое Chat.Read.All разрешение:

HTTP-запрос GET (разрешение—Chat.Read.All ):
```
GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')
```

Отправка упреждающих сообщений

Бот может отправлять упреждающие сообщения после добавления бота для пользователя или команды и получения им всех сведений о пользователе.

Фрагменты кода

Следующий код представляет собой пример отправки упреждающих сообщений:

C#
Node.js

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();
});

Пример кода

Название примера	Описание	.NET	Node.js
Упреждающая установка приложений и отправка упреждающих уведомлений	В этом примере показано, как использовать упреждающую установку приложений для пользователей и отправлять упреждающие уведомления, вызывая API Microsoft Graph.	View	Просмотр

Дополнительный образец кода

Примеры кода упреждающих сообщений в Teams

Отправка сообщений об упреждающей установке

Упреждающий обмен сообщениями в Teams

Упреждающая установка приложений в Teams

Разрешения

Включить упреждающую установку приложений и обмен сообщениями

Создайте и опубликуйте бот для активного обмена сообщениями для Teams

Получите `teamsAppId` для приложения

Определите, установлен ли ваш бот в настоящее время для получателя сообщения

Установите приложение

Получить беседу `chatId`

Отправка упреждающих сообщений

Фрагменты кода

Пример кода

Дополнительный образец кода

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы

Отправка сообщений об упреждающей установке

Упреждающий обмен сообщениями в Teams

Упреждающая установка приложений в Teams

Разрешения

Включить упреждающую установку приложений и обмен сообщениями

Создайте и опубликуйте бот для активного обмена сообщениями для Teams

Получите teamsAppId для приложения

Определите, установлен ли ваш бот в настоящее время для получателя сообщения

Установите приложение

Получить беседу chatId

Отправка упреждающих сообщений

Фрагменты кода

Пример кода

Дополнительный образец кода

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы

Получите `teamsAppId` для приложения

Получить беседу `chatId`