Поделиться через


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

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

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

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

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

Прежде чем бот сможет активно отправлять сообщения пользователю, его необходимо установить либо как личное приложение, либо в команде, участником которой является пользователь. Иногда необходимо заранее отправлять сообщения пользователям, которые не установили приложение или не взаимодействовали с ним. Например, если вам нужно отправить важную информацию всем пользователям в организации, можно использовать API Microsoft 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:Получение чата

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

    ЗапросHTTP GET:

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

    Свойство id отклика — teamsAppInstallationId.

  2. Отправьте следующий запрос, чтобы получить 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}')
    

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

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

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

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

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

Пример кода

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

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

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