Основы разговораConversation basics

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Боты – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Bots - v3 SDK section in the Resources folder of the documentation.

Беседа — это серия сообщений, отправляемых между Bot и одним или несколькими пользователями.A conversation is a series of messages sent between your bot and one or more users. В Teams существует три вида бесед (также называемых областями):There are three kinds of conversations (also called scopes) in Teams:

  • teams Также называется каналы каналов, видимых всем участникам канала.teams Also called channel conversations, visible to all members of the channel.
  • personal Беседы между Боты и одним пользователем.personal Conversations between bots and a single user.
  • groupChat Чат между Bot и двумя или несколькими пользователями.groupChat Chat between a bot and two or more users. Кроме того, в конференциях можно включить робота.Also enables your bot in meeting chats.

В зависимости от типа беседы, в которой она участвует, программа-робота немного ведет себя по-разному.A bot behaves slightly differently depending on what kind of conversation it is involved in:

  • Для боты в беседах в канале и группе необходимо, чтобы пользователь "@" привызывал его в канале.</span><span class="sxs-lookup">Bots in channel and group chat conversations require the user to @ mention the bot to invoke it in a channel.
  • Для боты в беседе "один к одному" не требуется указать @ упоминание.Bots in a one-to-one conversation do not require an @ mention. Все сообщения, отправленные пользователем, будут перенаправляться в робот.All messages sent by the user will be routed to your bot.

Чтобы включить Bot в определенной области, добавьте эту область в манифест приложения.To enable your bot in a particular scope, add that scope to your app manifest.

ДействияActivities

Каждое сообщение является Activity объектом типа messageType: message .Each message is an Activity object of type messageType: message. Когда пользователь отправляет сообщение, Teams отправляет сообщение на сервер почтовых роботов; в частности, он отправляет объект JSON в конечную точку обмена сообщениями ленты.When a user sends a message, Teams posts the message to your bot; specifically, it sends a JSON object to your bot's messaging endpoint. Ваш почтовый робот просматривает сообщение, чтобы определить его тип и ответить соответствующим образом.Your bot examines the message to determine its type and responds accordingly.

Основная беседа обрабатывается через соединитель Bot Framework, один REST API, позволяющий роботам общаться с Teams и другими каналами.Basic conversation is handled through the Bot Framework Connector, a single REST API to enable your bot to communicate with Teams and other channels. Пакет SDK построителя позволяет легко получить доступ к этому API, дополнительные функции для управления движением и состоянием беседы, а также простые способы внедрения таких служб, как естественный язык (НЛП).The Bot Builder SDK provides easy access to this API, additional functionality to manage conversation flow and state, and simple ways to incorporate cognitive services such as natural language processing (NLP).

Получение сообщенияReceive a message

Для получения текстового сообщения используйте Text свойство Activity объекта.To receive a text message, use the Text property of the Activity object. В обработчике действий Bot используйте объект "переключить контекст", Activity чтобы считать один запрос сообщения.In the bot's activity handler, use the turn context object's Activity to read a single message request.

Ниже приведен пример кода.The code below shows an example.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

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

Чтобы отправить текстовое сообщение, укажите строку, которую необходимо отправить как действие.To send a text message, specify the string you want to send as the activity. В обработчиках действий Bot используйте метод "переключить контекстный объект" SendActivityAsync для отправки одного ответа на сообщение.In the bot's activity handlers, use the turn context object's SendActivityAsync method to send a single message response. Кроме того, можно использовать метод объекта SendActivitiesAsync для отправки нескольких ответов одновременно.You can also use the object's SendActivitiesAsync method to send multiple responses at once. В приведенном ниже коде показан пример отправки сообщения, когда кто-то добавляется в беседу.The code below shows an example of sending a message when someone is added to a conversation

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Данные канала TeamsTeams channel data

channelDataОбъект содержит сведения, зависящие от команды, и является основным источником для идентификаторов команд и каналов.The channelData object contains Teams-specific information and is the definitive source for team and channel IDs. Возможно, вам потребуется кэшировать и использовать эти идентификаторы в качестве ключей для локального хранилища.You may need to cache and use these ids as keys for local storage. TeamsActivityHandlerВ пакете SDK обычно запрашиваются важные сведения из channelData объекта, чтобы сделать его более легко доступным, но вы всегда можете получить доступ к исходным данным из turnContext объекта.The TeamsActivityHandler in the SDK will typically pull out important information from the channelData object to make it more easily accessible, however you can always access the original information from the turnContext object.

Этот channelData объект не включается в сообщения в личных беседах, так как они выполняются вне какого-либо канала.The channelData object is not included in messages in personal conversations since these take place outside of any channel.

Типичный объект Чаннелдата в действии, отправляемом на почтовый робот, содержит следующие сведения:A typical channelData object in an activity sent to your bot contains the following information:

  • eventType Тип события Teams; передается только в случае событий изменения каналаeventType Teams event type; passed only in cases of channel modification events
  • tenant.id Идентификатор клиента Azure Active Directory; передается во всех контекстахtenant.id Azure Active Directory tenant ID; passed in all contexts
  • team Передается только в контекстах канала, а не в личном сеансе чата.team Passed only in channel contexts, not in personal chat.
  • channel Передается только в контекстах канала при упоминании Bot или для событий в каналах в Microsoft Teams, где добавлен Botchannel Passed only in channel contexts when the bot is mentioned or for events in channels in teams where the bot has been added
  • channelData.teamsTeamId Устаревшие.channelData.teamsTeamId Deprecated. Это свойство включено только для обеспечения обратной совместимости.This property is included only for backwards compatibility.
  • channelData.teamsChannelId Устаревшие.channelData.teamsChannelId Deprecated. Это свойство включено только для обеспечения обратной совместимости.This property is included only for backwards compatibility.

Пример объекта Чаннелдата (событие Чаннелкреатед)Example channelData object (channelCreated event)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Содержимое сообщенияMessage content

Ваш робот может отправлять форматированный текст, изображения и карточки.Your bot can send rich text, pictures, and cards. Пользователи могут отправлять форматированный текст и изображения в Bot.Users can send rich text and pictures to your bot.

FormatFormat От пользователя к BotFrom user to bot От Bot к пользователюFrom bot to user ПримечанияNotes
Форматированный текст Rich text
ИзображенияPictures Не более 1024 × 1024 и 1 МБ в формате PNG, JPEG или GIF; анимированный GIF-файл не поддерживаетсяMaximum 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF are not supported
КарточкиCards Поддерживаемые карточки представлены в справочнике по карточке TeamsSee the Teams Card Reference for supported cards
ЭмодзиEmojis В настоящее время Teams поддерживает эмодзи, используя кодировку UTF-16 (например, U + 1F600 для гриннинг Face)Teams currently supports emojis via UTF-16 (such as U+1F600 for grinning face)

Добавление уведомлений в сообщениеAdding notifications to your message

Уведомления уведомляют пользователей о новых задачах, упоминании и комментариях, связанных с тем, над чем они работают, или необходимо просмотреть, вставив уведомление в свой канал активности.Notifications alert users about new tasks, mentions and comments related to what they are working on, or need to look at by inserting a notice into their Activity Feed. Вы можете настроить уведомления для запуска из сообщения Bot, задав TeamsChannelData Notification.Alert для свойства Objects значение true.You can set notifications to trigger from your bot message by setting the TeamsChannelData objects Notification.Alert property to true. Если уведомление не будет вызвано, в конечном итоге зависит от параметров Teams отдельного пользователя, и вы не сможете программно переопределить эти параметры.Whether or not a notification is raised will ultimately depend on the individual user's Teams settings and you cannot programmatically override these settings. Типом уведомления будет либо баннер, либо баннер и электронная почта.The type of notification will be either a banner or both a banner and an email.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  await turnContext.SendActivityAsync(message);
}

Графические сообщенияPicture messages

Изображения отправляются путем добавления вложений к сообщению.Pictures are sent by adding attachments to a message. Дополнительные сведения о вложениях можно найти в документации по среде Bot.You can find more information on attachments in the Bot Framework documentation.

Рисунки могут иметь не более 1024 × 1024 и 1 МБ в формате PNG, JPEG или GIF; анимированный GIF-файл не поддерживается.Pictures can be at most 1024×1024 and 1 MB in PNG, JPEG, or GIF format; animated GIF is not supported.

Рекомендуем указать высоту и ширину каждого изображения с помощью XML.We recommend that you specify the height and width of each image by using XML. Если вы используете Markdown, размер изображения по умолчанию равен 256 × 256.If you use Markdown, the image size defaults to 256×256. Например:For example:

  • Используйте <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>Use - <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • Не используйте — ![Duck on a rock](http://aka.ms/Fo983c)Don't use - ![Duck on a rock](http://aka.ms/Fo983c)

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