Упреждающий обмен сообщениями для БотыProactive messaging for bots

Важно!

Статьи, приведенные в этом разделе, основаны на пакете SDK "V3 Bot Framework".The articles in this section are based on the v3 Bot Framework SDK. Если вы ищете текущую документацию (версия 4,6 или более поздняя версия пакета SDK), ознакомьтесь с разделом " беседы Боты ".If you're looking for current documentation (version 4.6 or later of the SDK) see the Conversational Bots section.

Упреждающее сообщение — это сообщение, которое отправляется с помощью ленты, чтобы начать беседу.A proactive message is a message that is sent by a bot to start a conversation. Вы можете попытаться начать беседу по ряду причин, в том числе:You may want your bot to start a conversation for a number of reasons, including:

  • Приветственные сообщения для личных беседWelcome messages for personal bot conversations
  • Ответы опросовPoll responses
  • Уведомления о внешних событияхExternal event notifications

Отправка сообщения для запуска нового цепочки беседы отличается от отправки сообщения в ответ на существующую беседу: при начале новой беседы не существует диалогового окна, в котором будет размещаться сообщение.Sending a message to start a new conversation thread is different than sending a message in response to an existing conversation: when your bot starts a new a conversation, there is no pre-existing conversation to post the message to. Чтобы отправить упреждающее сообщение, необходимо выполнить следующие действия:In order to send a proactive message you need to:

  1. Принятие решения о том, что вы собираетесь говоритьDecide what you're going to say
  2. Получение уникального идентификатора пользователя и идентификатора клиентаObtain the user's unique Id and tenant Id
  3. Отправка сообщенияSend the message

При создании упреждающего сообщения необходимо вызвать MicrosoftAppCredentials.TrustServiceUrl и передать URL-адрес службы перед созданием, который ConnectorClient будет использоваться для отправки сообщения.When creating proactive messages you must call MicrosoftAppCredentials.TrustServiceUrl, and pass in the service URL before creating the ConnectorClient you will use to send the message. В противном случае ваше приложение получит 401: Unauthorized ответ.If you do not, your app will receive a 401: Unauthorized response. Ознакомьтесь с приведенными ниже примерами.See the samples below.

Рекомендации по использованию упреждающего обмена сообщениямиBest practices for proactive messaging

Отправка упреждающих сообщений пользователям может быть очень эффективным способом общения с пользователями.Sending proactive messages to users can be a very effective way to communicate with your users. Однако с их точки зрения это сообщение может быть полностью нежелательным, а в случае приветственных сообщений будет использоваться при первом взаимодействии с приложением.However, from their perspective this message can appear to come to them completely unprompted, and in the case of welcome messages will be the first time they've interacted with your app. Таким образом, очень важно использовать эту функцию экономно (не спама для пользователей) и предоставить им достаточно информации, чтобы убедиться в их подлинности.As such, it is very important to use this functionality sparingly (don't spam your users), and to provide them with enough information to let them understand why they are being messaged.

Упреждающие сообщения обычно делятся на две категории: приветственные сообщения или уведомления.Proactive messages generally fall into one of two categories, welcome messages or notifications.

Приветственные сообщенияWelcome messages

При использовании упреждающего обмена сообщениями для отправки пользователю приветственного сообщения необходимо помнить, что большинство людей, получивших сообщение, не будут иметь контекст для их получения.When using proactive messaging to send a welcome message to a user you must keep in mind that for most people receiving the message they will have no context for why they are receiving it. Это также происходит в первый раз, когда он будет взаимодействовать с вашим приложением; можно создать хорошее первое впечатление.This is also the first time they will have interacted with your app; it is your opportunity to create a good first impression. Лучшие приветственные сообщения будут включать:The best welcome messages will include:

  • Почему они получают это сообщение.Why are they receiving this message. Он должен быть очень очевидным, чтобы пользователь получал сообщение.It should be very clear to the user why they are receiving the message. Если ваш Bot был установлен в канале и вы отправили приветственное сообщение всем пользователям, сообщите им о том, в каком канале он был установлен и кто его установил.If your bot was installed in a channel and you sent a welcome message to all users, let them know what channel it was installed in and potentially who installed it.
  • Что вы предоставляете.What do you offer. Что можно делать с приложением?What can they do with your app? Какое значение можно перенести?What value can you bring to them?
  • Что делать дальше.What should they do next. Пригласите их, чтобы испытать команду или взаимодействовать с приложением каким бы то ни было способом.Invite them to try out a command, or interact with your app in some way.

Сообщения уведомленияNotification messages

При использовании упреждающего обмена сообщениями для отправки уведомлений необходимо убедиться, что у пользователей есть четко настроенный путь для выполнения общих действий на основе уведомления, и четко понимать, почему возникло уведомление.When using proactive messaging to send notifications you need to make sure your users have a clear path to take common actions based on your notification, and a clear understanding of why the notification occurred. К хорошим сообщениям уведомления обычно относятся:Good notification messages will generally include:

  • Что случилось.What happened. Четкое указание того, что произошло с причиной уведомления.A clear indication of what happened to cause the notification.
  • Что случилось.What it happened to. Должно быть ясно, какие элементы/вещи были обновлены, чтобы получить уведомление.It should be clear what item/thing was updated to cause the notification.
  • Кто это сделал.Who did it. Кто потратил действие, вызвавшее отправку уведомления.Who took the action that caused the notification to be sent.
  • Что они могут сделать.What they can do about it. Облегчить пользователям выполнение действий в соответствии с вашими уведомлениями.Make it easy for your users to take actions based on your notifications.
  • Как они могут отказаться. Необходимо указать путь для пользователей, чтобы отказаться от дополнительных уведомлений.How they can opt out. You need to provide a path for users to opt out of additional notifications.

Получение необходимых сведений о пользователеObtain necessary user information

Боты может создавать новые беседы с отдельным пользователем Microsoft Teams, получая уникальный идентификатор пользователя и идентификатор клиента.Bots can create new conversations with an individual Microsoft Teams user by obtaining the user's unique ID and tenant ID. Эти значения можно получить с помощью одного из следующих методов:You can obtain these values using one of the following methods:

Заактивная установка приложения с помощью GraphProactively install your app using Graph

Примечание

Активная установка приложений с помощью Graph в настоящее время находится на стадии бета-тестирования.Proactively installing apps using graph is currently in beta.

Иногда это может потребоваться для упреждающего сообщения пользователей, которые ранее не устанавливали приложение или не работали с ним.Occasionally it may be necessary to proactively message users that have not installed or interacted with your app previously. Например, вы хотите использовать Communicator компании для отправки сообщений во всю организацию.For example, you want to use the company communicator to send messages to your entire organization. В этом сценарии можно использовать API Graph для профилактической установки приложения для пользователей, а затем кэшировать необходимые значения из события, которое conversationUpdate получит ваше приложение после установки.For this scenario you can use the Graph API to proactively install your app for your users, then cache the necessary values from the conversationUpdate event your app will receive upon install.

Вы можете устанавливать только приложения, которые находятся в каталоге организационных приложений или в магазине приложений Teams.You can only install apps that are in your organizational app catalogue, or the Teams app store.

Подробные сведения приведены в статье Установка приложений для пользователей в документации Graph.See Install apps for users in the Graph documentation for complete details. Кроме того, существует пример в .NET.There is also a sample in .NET.

ПримерыExamples

Перед созданием новой беседы с помощью REST API обязательно проверьте подлинность и наличие маркера носителя.Be sure that you authenticate and have a bearer token before creating a new conversation using the REST API.

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

Необходимо указать идентификатор пользователя и идентификатор клиента.You must supply the user ID and the tenant ID. Если вызов завершается успешно, API возвращает следующий объект Response.If the call succeeds, the API returns with the following response object.

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

Этот идентификатор является уникальным ИДЕНТИФИКАТОРом беседы личного чата.This ID is the personal chat's unique conversation ID. Сохраните это значение и повторно используйте его для последующего взаимодействия с пользователем.Please store this value and reuse it for future interactions with the user.

Использование .NETUsing .NET

В этом примере используется пакет NuGet Microsoft. Bot. Connector. Teams .This example uses the Microsoft.Bot.Connector.Teams NuGet package.

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

Использование Node.jsUsing Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

В этой статье также приведены примеры кода Bot Framework.See also Bot Framework samples.

Создание беседы каналаCreating a channel conversation

Добавленная командой Bot может отправляться в канал для создания новой цепочки ответа.Your team-added bot can post into a channel to create a new reply chain. Если вы используете пакет SDK для Node.js Teams, используйте его, чтобы startReplyChain() полностью заполнить адрес, соответствующий идентификатору действия и идентификатору беседы. Если вы используете C#, обратитесь к представленному ниже примеру.If you're using the Node.js Teams SDK, use startReplyChain() which gives you a fully-populated address with the correct activity id and conversation id. If you are using C#, see the example below.

Кроме того, вы можете использовать REST API и отправить запрос POST /conversations ресурсу.Alternatively, you can use the REST API and issue a POST request to /conversations resource.

Пример .NET (из этого примера).NET example (from this sample)

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}