Упреждающие сообщения

Упреждающее сообщение — это любое сообщение, отправленное агентом и не являющееся ответом на запрос пользователя. Это сообщение может включать в себя следующие элементы:

  • Приветствия
  • Уведомления
  • Запланированные сообщения

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

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

Отправка упреждающего сообщения отличается от отправки обычного сообщения. Упреждающие сообщения отправляются через приложение. Send() вне обработчика действия. SDK автоматически создает беседу при звонке приложению. Send(). Вам нужно , conversationIdпакет SDK автоматически разрешает URL-адрес службы. Например, новый приватный чат или новая цепочка беседы на канале. Вы не можете создать новый групповой чат или новый канал в команде с упреждающими сообщениями.

Чтобы отправить упреждающее сообщение, выполните следующие действия.

  1. При необходимости получите идентификатор пользователя Microsoft Entra, идентификатор пользователя, идентификатор команды или идентификатор канала.
  2. Создание беседы при необходимости.
  3. Получение ИД беседы.
  4. Отправка сообщения.

Фрагменты кода в разделе примеров предназначены для создания приватной беседы. Ссылки на примеры как для личных бесед, так и для сообщений групп или каналов см. в примерах кода. Чтобы эффективно использовать упреждающие сообщения, ознакомьтесь с рекомендациями по упреждающему обмену сообщениями.

Получение идентификатора пользователя Microsoft Entra, идентификатора пользователя, идентификатора команды или идентификатора канала

Вы можете создать новую беседу с пользователем или цепочку беседы в канале, и у вас должен быть правильный идентификатор. Вы можете получить или извлечь этот идентификатор любым из следующих способов:

  • Если приложение установлено в определенном контексте, вы получаете onMembersAdded действие.
  • При добавлении нового пользователя в контекст, где установлено ваше приложение, вы получаете onMembersAdded действие.
  • Каждое событие, которое получает агент, содержит необходимую информацию, которую можно получить из контекста агента (контекста активности).
  • Вы можете получить список каналов в команде, где установлено приложение.
  • Вы можете получить список участников команды, где установлено приложение.

Независимо от того, как вы получили информацию, сохраните, tenantId а затем сохраните либо userId, либо channelId для создания новой беседы. Вы также можете использовать teamId, чтобы создать новую беседу в общем или стандартном канале команды. Убедитесь, что агент установлен в группе, прежде чем отправлять упреждающее сообщение в канал.

  • Это aadObjectId уникальное значение для пользователя, и его можно получить с помощью API Graph для создания новой беседы в личном чате. Прежде чем отправлять упреждающее сообщение, убедитесь, что агент установлен в личной области. Если агент не установлен в личной области, при отправке упреждающего сообщения с aadObjectIdпомощью , агент возвращает 403 ошибку с ForbiddenOperationException сообщением.

  • Он userId уникален для вашего идентификатора агента и конкретного пользователя. Повторное использование данных между агентами userId невозможно.

  • channelId — глобальный параметр.

Создайте беседу, получив информацию о пользователе или канале.

Примечание.

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

Создание беседы

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

Чтобы создать беседу, вам нужны or aadObjectIduserId, tenantId, и serviceUrl.

Примечание.

Чтобы создать диалог, передайте aadObjetId значение в параметре Id .

Для serviceUrl, используйте значение из входящего действия, запускающего поток, или один из глобальных URL-адресов службы. Если входящее serviceUrl действие, запускающее упреждающий сценарий недоступно, используйте следующие глобальные конечные точки URL-адресов:

  • Общедоступный: https://smba.trafficmanager.net/teams/
  • GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  • GCC High: https://smba.infra.gov.teams.microsoft.us/teams
  • Министерство обороны: https://smba.infra.dod.teams.microsoft.us/teams

Предупреждение

  • Эти URL-адреса предназначены только для упреждающих сообщений. Избегайте жесткого кодирования. Вместо этого используйте serviceUrl ссылку на входящее действие или ссылку на беседу. Если оно недоступно, используйте глобальные URL-адреса в зависимости от региона и облака.

  • Для любых ответов на сообщения используйте serviceURL текст из входящего запроса. Дополнительные сведения см. в разделе свойства Activity.ServiceUrl .

Вы можете получить беседу при первой установке приложения. После создания беседы получите идентификатор беседы. conversationId доступен в событиях обновления беседы.

ИД беседы уникален для каждого агента в конкретном канале, даже в многопользовательской среде. Этот идентификатор гарантирует, что сообщения агента направляются в соответствующий канал и не прерываются другими агентами или каналами в той же или другой организации.

Если у conversationIdвас нет , вы можете заранее установить приложение с помощью Graph , conversationIdчтобы получить

Получение ИД беседы

Используйте объект conversationReference или conversationId и tenantId для отправки сообщения. Вы можете получить этот ИД, создав беседу или сохранив ее, из любого действия, отправленного вам из этого контекста. Сохраните этот ИД для справки.

Получив соответствующие сведения об адресе, вы можете отправить сообщение.

Отправка сообщения

Теперь, когда у вас есть правильные сведения об адресе, вы можете отправить сообщение. При использовании пакета SDK необходимо использовать метод app.Send() и conversationId прямой вызов API. Чтобы отправить сообщение, задайте conversationParameters См. раздел "Примеры " или используйте один из примеров, перечисленных в разделе "Примеры кода ".

Чтобы заранее отправить сообщение в качестве ответа в цепочку в канале, используйте app.Reply() как идентификатор беседы, так и идентификатор корневого сообщения цепочки.

Примечание.

Teams не поддерживает отправку упреждающих сообщений с помощью электронной почты или имени участника-пользователя (UPN).

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

Узнайте, кто заблокировал, открыл или удалил агент

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

Используя Teams, вы можете отправить упреждающее сообщение агенту, чтобы проверить, не заблокировал ли пользователь агента или не удалил его. Если агент заблокирован или удален, Teams возвращает код ответа 403 с .subCode: MessageWritesBlocked Этот отклик означает, что сообщение, отправленное агентом, не доставлено пользователю.

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

В следующем примере кода кода ответа 403 приведен пример:

HTTP/1.1 403 Forbidden
Cache-Control: no-store, must-revalidate, no-cache
Pragma: no-cache
Content-Length: 196
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0
ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0
Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\n  \"subCode\": \"MessageWritesBlocked\",\n  \"details\": \"Thread is blocked from message writes.\",\n  \"errorCode\": null,\n  \"errorSubCode\": null\n}"}

Рекомендации по упреждающим сообщениям

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

Приветствия

Если для отправки приветственного сообщения пользователю используется упреждающий обмен сообщениями, контекст для этого пользователя отсутствует. Кроме того, это первое взаимодействие пользователя с вашим приложением. Это возможность создать хорошее первое впечатление. Хорошее взаимодействие с пользователем обеспечивает лучшее принятие приложения. Плохие приветственные сообщения могут привести к тому, что пользователи заблокируют ваше приложение. Напишите четкое приветственное сообщение и доработайте его повторно, если оно не дает желаемого эффекта.

Хорошее приветственное сообщение может включать следующую информацию:

  • Причина сообщения: пользователю должно быть понятно, почему он получил это сообщение. Если агент был установлен в канале и вы отправили приветственное сообщение всем пользователям, сообщите им, в каком канале он установлен и кто его установил.

  • Ваше предложение — пользователи должны быть в состоянии определить, что они могут делать с вашим приложением и какую пользу вы можете им принести.

  • Дальнейшие действия. Пользователи должны понимать следующие действия. Например, предложите пользователям опробовать команду или взаимодействовать с вашим приложением.

Уведомления

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

  • Что произошло? Четкое указание того, что стало причиной получения уведомления.

  • Каков результат? Должно быть понятно, какой элемент обновлен для получения уведомления.

  • Кто или что его активирует? Кто или что выполнило действие, вызвавшее отправку уведомления.

  • Что пользователи могут сделать в ответ? Сделайте так, чтобы на основе ваших уведомлений было удобно совершать действия.

  • Как пользователи могут отказаться от получения уведомлений? Необходимо предоставить пользователям возможность отказаться от дополнительных уведомлений.

Для отправки сообщений большой группе пользователей, например в организацию, заранее установите приложение с помощью Graph.

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

  1. Отслеживайте отправленные сообщения, сохраняя их идентификаторы или ссылки на беседы при отправке упреждающего сообщения.

  2. Используйте context.Api.Conversations.Activities.UpdateAsync(conversationId, activityId, updatedActivity) или context.Api.Conversations.Activities.DeleteAsync(conversationId, activityId) методы для обновления или удаления исходного сообщения.

Запланированные сообщения

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

  • Почему пользователь получает сообщение? Сделайте так, чтобы пользователи могли легко понять причину, по которой они получают сообщение.

  • Что пользователь может сделать дальше? Пользователи могут выполнить требуемое действие на основе содержимого сообщения.

Заранее установите приложение с помощью Graph

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

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

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

Примеры

Перед созданием новой беседы с помощью REST API проверьте подлинность и наличие маркера носителя . Ниже приведены REST API для создания беседы в различных контекстах:

  • REST API для создания беседы в чате один на один.

  • REST API для создания беседы в канале.

  • REST API для обновления сообщений в беседе: чтобы обновить существующее действие в беседе, включите conversationId и activityId в конечную точку запроса. Чтобы выполнить этот сценарий, вы должны кэшировать идентификатор действия, возвращенный исходным почтовым вызовом.

    PUT {Service URL of your agent}/v3/conversations/{conversationId}/activities/{activityId}

    
{
    "type": "message",
    "text": "This message has been updated"
}

    Чтобы обновить существующее действие в беседе, включите conversationId и activityId в конечную точку запроса. Для выполнения этого сценария необходимо кэшировать данные activity ID , возвращенные исходным вызовом POST. В случае успешного вызова API возвращает следующий объект отклика:

    {
    "id": "{{activityID}}"
}

Примеры

В следующем коде показано, как отправлять упреждающие сообщения с помощью пакета SDK (библиотека ИИ Teams):

// Save the conversation ID and schedule a proactive reminder on install
teams.OnInstall(async (context, cancellationToken) =>
{
    context.Storage.Set(context.Activity.From.AadObjectId!, context.Activity.Conversation.Id);
    await context.Send("Hi! I am going to remind you to say something to me soon!", cancellationToken);
    notificationQueue.AddReminder(context.Activity.From.AadObjectId!, Notifications.SendProactive, 10_000);
});
 
// Send proactive message using stored conversation ID
public static class Notifications
{
    public static async Task SendProactive(string userId)
    {
        var conversationId = (string?)storage.Get(userId);
        if (conversationId is null) return;
        await app.Send(conversationId, "Hey! It's been a while. How are you?");
    }
}

Примеры кода

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

Название примера Описание .NET Node.js Python Манифест
Основы бесед в Teams В этом примере приложения показано, как использовать различные события бесед с агентами, доступные в Teams SDK версии 2 для личной и командной областей. Просмотр Просмотр Просмотр Просмотр
Упреждающее сообщение бота В этом примере показано, как получить и сохранить идентификатор беседы из действия установки и использовать его для немедленной отправки и отложенных упреждающих сообщений пользователю. Просмотр Просмотр Просмотр Н/Д

Дальнейшие действия

Форматирование сообщений агента

См. также

  • Last updated on