Отправка упреждающих уведомлений пользователям

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

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

Упреждающие сообщения могут быть полезны в различных сценариях. Например, если пользователь ранее попросил бот отслеживать стоимость продукта, то бот может оповестить пользователя в случае, если стоимость продукта опустилась на 20 %. Если боту требуется какое-то время, чтобы сформировать ответ на вопрос пользователя, он может проинформировать пользователя о задержке и продолжить диалог. Когда бот сформирует ответ на вопрос, он передаст его пользователю.

В этой статье рассматриваются сведения об упреждающих сообщениях для ботов в целом. Сведения об упреждающих сообщениях в Microsoft Teams см. в статье

• Пример бота беседы Teams в C#, JavaScript, Java или Python.
• Документация по Microsoft Teams о том, как отправлять упреждающие сообщения.

Предварительные условия

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

Сведения о превентивном примере

Как правило, бот в качестве приложения имеет несколько уровней:

• Веб-приложение, которое может принимать HTTP-запросы и специально поддерживает конечную точку обмена сообщениями.
• Адаптер, который обрабатывает подключение к каналам.
• Обработчик очереди, обычно инкапсулированный в классе бота, который управляет логикой ведения диалога для приложения бота.

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

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

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

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

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

Получение и хранение ссылки на беседу

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

private void AddConversationReference(Activity activity)
{
    var conversationReference = activity.GetConversationReference();
    _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
}

protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
    AddConversationReference(turnContext.Activity as Activity);

    return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
}

this.conversationReferences = conversationReferences;

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

}

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

Ссылка на беседу содержит свойство беседы , описывающее беседу, в которой существует действие. Беседа содержит свойство пользователя , которое перечисляет пользователей, участвующих в беседе, и свойство URL-адреса службы, указывающее, где могут отправляться ответы на текущее действие. Для отправки пользователям упреждающих сообщений нужно получить корректную ссылку на беседу. В канале Teams URL-адрес службы привязывается к регионализованному серверу.

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

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

1. Извлекает ссылку на беседу, в которую отправляется упреждающее сообщение.
2. Вызывает метод адаптера продолжения беседы, предоставляя ссылку на беседу и делегат обработчика хода для использования. (Метод продолжения разговора создаёт контекст хода для указанного разговора, а затем вызывает указанный делегат обработчика хода.)
3. В делегате используется контекст поворота для отправки упреждающего сообщения. Здесь делегат определяется на контроллере уведомлений и отправляет пользователю упреждающее сообщение.

[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)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, 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)
    {
        await turnContext.SendActivityAsync("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();
});

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

Для отправки упреждающего сообщения адаптеру нужен идентификатор приложения бота. В рабочей среде можно использовать идентификатор приложения бота. Для локального тестирования бота с помощью эмулятора можно использовать пустую строку ("").

Тестирование бота

1. Если это еще не сделано, установите эмулятор Bot Framework.
2. Выполните этот пример на локальном компьютере.
3. Запустите эмулятор и подключитесь к боту.
4. Загрузите страницу api/notify вашего бота. Это создаст упреждающее сообщение в эмуляторе.

Дополнительная информация:

Требования

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

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

Рекомендации по проектированию

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

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

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

О превентивном повороте

Метод продолжения беседы использует ссылку на беседу и обработчик обратного вызова для:

1. Создайте ход, в котором приложение бота может отправить упреждающее сообщение. Адаптер создает event действие для этого поворота, присвоив ему имя "ContinueConversation".
2. Отправьте задание через конвейер ПО промежуточного слоя адаптера.
3. Вызовите функцию обработчика обратного вызова для выполнения пользовательской логики.

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

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

• Укажите обработчик поворота бота в качестве обработчика обратного вызова. Затем бот получит действие события "ContinueConversation".
• Используйте обработчик обратного вызова, чтобы сначала добавить сведения в контекст поворота, а затем вызвать обработчик поворота бота.

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

Следующие шаги