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

Статья
04/02/2023

Важно!

Эта статья основана на пакете SDK Bot Framework версии 3. Если вы ищете текущую документацию по пакету SDK версии 4.6 или более поздней, см. раздел Боты для бесед.

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

Приветственные сообщения для личных бесед бота.
Опрос ответов.
Уведомления о внешних событиях.

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

Решите, что вы собираетесь сказать
Получите уникальный идентификатор пользователя и идентификатор клиента
Отправка сообщения

При создании упреждающих сообщений обязательно вызовите MicrosoftAppCredentials.TrustServiceUrl и передайте туда URL-адрес службы, прежде чем создавать объект ConnectorClient, используемый для отправки сообщения. В противном случае приложение получит ответ 401: Unauthorized. Дополнительные сведения см. в примерах.

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

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

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

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

Примечание.

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

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

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

Подробные сведения см. в документации Graph по установке приложений для пользователей. В .NET также есть пример.

Примеры

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

POST {Service URL of your bot}/v3/conversations


{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

Укажите id в качестве идентификатора приложения бота и name в качестве имени бота. Вы можете получить membersid из объекта ботов, TurnContext например turnContext.Activity.From.Id. Аналогичным образом, id клиента, из объекта ботов TurnContext , например turnContext.Activity.ChannelData.Tenant.Id.

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

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

}

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

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

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

// 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.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);

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

Бот, добавленный в команду, может публиковать сообщения на канале, создавая новые цепочки ответов. Если вы используете пакет SDK Node.js Teams, используйте startReplyChain(), чтобы получить полный адрес с правильным идентификатором действия и идентификатором беседы. Если вы используете C#, см. следующий пример.

В качестве альтернативы можно использовать REST API и отправить запрос POST к ресурсу /conversations.

Примеры создания беседы канала

Пример .NET из этого примера

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

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

POST {Service URL of your bot}/v3/conversations


{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

Вы можете получить из {Service URL of your bot}TurnContext объекта, например turnContext.Activity.ServiceURL параметр .

Вы можете получить из channelDataTurnContext объекта, например turnContext.Activity.TeamsChannelData параметр .

Укажите id в качестве идентификатора приложения бота и name в качестве имени бота. Аналогичным образом, id клиента, из объекта ботов TurnContext , например turnContext.Activity.ChannelData.Tenant.Id.

Аналогичным образом можно указать teamID для teamsChannelId, teamsTeamId, channel, team в channelData разделе , который отправляет сообщение в общий канал команды.

Если вызов выполнен успешно, API возвращает следующий объект ответа:

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

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

Примеры Bot Framework.

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

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

Приветствия

Уведомления

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

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

Примеры

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

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

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

Примеры создания беседы канала

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

Обратная связь

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