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

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел пакет SDK для ботов версии 3 в папке Устаревшие пакеты SDK документации.

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

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

Важно!

• Чтобы отправить упреждающее сообщение, рекомендуется начать с создания бота уведомлений с помощью JavaScript или примера уведомления о входящих веб-перехватчиках. Чтобы приступить к работе, скачайте обзор набора средств Teams . Дополнительные сведения см. в документах Teams Toolkit.

• Боты доступны в облаках сообщества для государственных организаций (GCC), GCC-High и Министерстве обороны (DOD). Для упреждающих сообщений боты должны использовать следующие конечные точки для облачных сред для государственных организаций:
  -GCC: https://smba.infra.gcc.teams.microsoft.com/teams
  — GCCH: https://smba.infra.gov.teams.microsoft.us/teams
  -DOD: https://smba.infra.dod.teams.microsoft.us/teams

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

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

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

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

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

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

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

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

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

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

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

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

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

Create беседу после получения сведений о пользователе или канале.

Примечание.

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

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

Вы можете создать беседу, если она не существует или вы не знаете conversationId. Create беседу только один раз и сохраните conversationId значение или conversationReference объект .

Чтобы создать беседу, вам потребуется aadObjectId или userId, tenantIdи serviceUrl.

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

• Общественного: https://smba.trafficmanager.net/teams/
• GCC: https://smba.infra.gcc.teams.microsoft.com/teams
• GCCH: https://smba.infra.gov.teams.microsoft.us/teams
• DOD: https://smba.infra.dod.teams.microsoft.us/teams

Пример кода см. в вызове CreateConversationAsync в примере.

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

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

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

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

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

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

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

Теперь, когда у вас есть правильные сведения об адресе, вы можете отправить сообщение. Если вы используете пакет SDK, необходимо использовать метод continueConversation, а также conversationId и tenantId для прямого вызова API. Чтобы отправить сообщение, задайте .conversationParameters См. раздел с образцами или воспользуйтесь одним из примеров, перечисленных в разделе с примерами кода.

Примечание.

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":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

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

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

Приветствия

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

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

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

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

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

Уведомления

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. сведения об установке приложений для пользователей в документации Graph и упреждающей установке бота и отправке сообщения в Teams с помощью Graph. На платформе GitHub также есть пример Microsoft .NET Framework.

Примеры

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

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

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

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

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

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

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

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

Примеры

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

C#

• Справочные материалы для SDK
• Пример справочника по коду

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent.
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

Пример фрагмента кода для демонстрации создания ссылки на беседу.

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };

JavaScript

• Справочные материалы для SDK
• Пример справочника по коду

async SendNotificationToAllUsersAsync(context) {
     const TeamMembers = await TeamsInfo.getPagedMembers(context);
     let Sent_msg_Cout = TeamMembers.members.length;
     TeamMembers.members.map(async member => {
         const ref = TurnContext.getConversationReference(context.activity);
         ref.user = member;
         await context.adapter.createConversation(ref, async (context) => {
             const ref = TurnContext.getConversationReference(context.activity);
             await context.adapter.continueConversation(ref, async (context) => {
                 await context.sendActivity("Proactive hello.");
             });
         });
     });
    await context.sendActivity(MessageFactory.text("Message sent:" + Sent_msg_Cout));
}

Python

• Справочные материалы для SDK
• Пример справочника по коду

# Send message to all members.
async def _message_all_members(self, turn_context: TurnContext):
    team_members = await self._get_paged_members(turn_context)

    for member in team_members:
        # A conversation reference for the conversation that contains this activity.
        conversation_reference = TurnContext.get_conversation_reference(
            turn_context.activity
        )

        conversation_parameters = ConversationParameters(
            is_group=False,
            bot=turn_context.activity.recipient,
            members=[member],
            tenant_id=turn_context.activity.conversation.tenant_id,
        )

        async def get_ref(tc1):
            conversation_reference_inner = TurnContext.get_conversation_reference(
                tc1.activity
            )
            return await tc1.adapter.continue_conversation(
                conversation_reference_inner, send_message, self._app_id
            )

        async def send_message(tc2: TurnContext):
            return await tc2.send_activity(
                f"Hello {member.name}. I'm a Teams conversation bot."
            )

        await turn_context.adapter.create_conversation(
            conversation_reference, get_ref, conversation_parameters
        )

    # Sends an activity to the sender of the incoming activity.
    await turn_context.send_activity(
        MessageFactory.text("All messages have been sent")
    )

JSON

POST /v3/conversations
{
  "bot": {
    "id": "28:10j12ou0d812-2o1098-c1mjojzldxcj-1098028n ",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Необходимо предоставить ИД пользователя и ИД клиента. В случае успешного вызова API возвращает следующий объект отклика:

{
  "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"
}

Пример кода

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

Название примера	Описание	.NET	Node.js	Python	Манифест
Основы бесед в Teams	В этом примере приложения показано, как использовать различные события бесед бота, доступные в bot framework версии 4 для личных и командных область.	Просмотр	Просмотр	Просмотр	View
Запуск новой цепочки в канале	В этом примере показано, как запустить поток в канале определенной команды с помощью Bot Framework версии 4.	Просмотр	Просмотр	Просмотр	View
Упреждающая установка приложений и отправка упреждающих уведомлений	В этом примере показано, как использовать упреждающую установку приложений для пользователей и отправлять упреждающие уведомления, вызывая API Microsoft Graph.	View	Просмотр	Н/Д	Просмотр
Упреждающий обмен сообщениями	В этом примере показано, как сохранить справочные сведения о беседах пользователя для отправки упреждающего напоминания с помощью ботов.	Просмотр	Просмотр	Н/Д

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

Следующий этап

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

См. также

• Примеры кода упреждающих сообщений в Teams
• Беседы с ботом в канале и групповом чате
• Ответ на действие отправки в диалоговом окне
• Отправка упреждающих уведомлений пользователям
• Создание первого приложения бота с помощью JavaScript
• Создание бота уведомлений с помощью JavaScript для отправки упреждающего сообщения
• TurnContext
• Реализация пользовательского хранилища для бота