Беседа с роботом Microsoft TeamsHave a conversation with a Microsoft Teams bot

Важно!

Статьи, приведенные в этом разделе, основаны на пакете 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.

Беседа — это серия сообщений, отправляемых между 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.

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

Чтобы элемент Bot мог работать в определенной области, он должен быть указан в манифесте как поддерживающий эту область в манифесте.In order for the bot to work in a particular scope it should be listed as supporting that scope in the manifest. Области определены и обсуждаются в справочнике по манифесту.Scopes are defined and discussed further in the Manifest Reference.

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

Боты могут участвовать в беседе или инициировать ее.Bots can participate in a conversation or initiate one. Большая часть обмена сообщениями заключается в ответ на другое сообщение.Most communication is in response to another message. Если программа-робот инициирует беседу, она называется упреждающим сообщением.If a bot initiates a conversation it is called a proactive message. Примеры:Examples include:

  • Приветственные сообщенияWelcome messages
  • Уведомления о событияхEvent notifications
  • Опрос сообщенийPolling messages

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

Каждое сообщение является 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.

Боты также поддерживает сообщения в стиле события.Bots also support event-style messages. Более подробную информацию можно узнать в статье обработка событий Bot в Microsoft Teams .See Handle bot events in Microsoft Teams for more details. В настоящее время речь не поддерживается.Speech is currently not supported.

Сообщения для большинства областей имеют одинаковое значение, но существуют различия в доступе к интерфейсу Bot в пользовательском интерфейсе и различиях в сценах, о которых необходимо знать.Messages are for the most part the same in across all scopes, but there are differences in how the bot is accessed in the UI and differences behind the scenes which you will need to know about.

Основная беседа обрабатывается через соединитель 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).

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

Ваш робот может отправлять форматированный текст, изображения и карточки.Your bot can send rich text, pictures, and cards. Пользователи могут отправлять форматированный текст и изображения в Bot.Users can send rich text and pictures to your bot. Вы можете указать тип контента, который может обработать пользователь Bot, на странице параметров Microsoft Teams для ленты.You can specify the type of content your bot can handle in the Microsoft Teams settings page for 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)

Для получения дополнительных сведений о типах взаимодействий с Bot, поддерживаемых с помощью Bot Framework (которые основаны на Боты в Teams), ознакомьтесь с документацией по разработке для ленты и связанными понятиями, изложенными в документации по пакету SDK построителя для .NET и пакету SDK построителя для Node.js.For more information on the types of bot interaction supported by the Bot Framework (which bots in teams are based on), see the Bot Framework documentation on conversation flow and related concepts in the documentation for the Bot Builder SDK for .NET and the Bot Builder SDK for Node.js.

Форматирование сообщенияMessage formatting

Можно задать необязательное TextFormat свойство элемента, message чтобы управлять отображением текстового контента сообщения.You can set the optional TextFormat property of a message to control how your message's text content is rendered. В статье Форматирование сообщений представлено подробное описание поддерживаемого форматирования в сообщениях Bot.See Message formatting for a detailed description of supported formatting in bot messages. Можно задать необязательное TextFormat свойство, чтобы управлять отображением текстового контента сообщения.You can set the optional TextFormat property to control how your message's text content is rendered.

Подробные сведения о том, как teams поддерживает форматирование текста в Teams, см в разделе Форматирование текста в сообщениях Bot.For detailed information on how Teams supports text formatting in teams see Text formatting in bot messages.

Сведения о форматировании карточек в сообщениях можно узнать в статье Форматирование карточки.For information on formatting cards in messages, see Card formatting.

Графические сообщения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)

Получение сообщенийReceiving messages

В зависимости от того, какие области объявляются, Bot может получать сообщения в следующих контекстах:Depending on which scopes are declared, your bot can receive messages in the following contexts:

  • Личный чат Пользователи могут общаться в частном разговоре с помощью ленты, просто выбрав добавленного элемента Bot в журнале чата или введя его имя или идентификатор приложения в поле Кому: в новом сеансе разговора.personal chat Users can interact in a private conversation with a bot by simply selecting the added bot in the chat history, or typing its name or app ID in the To: box on a new chat.
  • Каналы Вы можете упомянуть в канале ("@ботнаме"), если она была добавлена в команду.Channels A bot can be mentioned ("@botname") in a channel if it has been added to the team. Обратите внимание, что для дополнительных ответов на канале Bot в канале требуется упоминание Bot.Note that additional replies to a bot in a channel require mentioning the bot. Он не реагирует на ответы, где он не упоминается.It will not respond to replies where it is not mentioned.

Для входящих сообщений Bot получает Activity объект типа messageType: message .For incoming messages, your bot receives an Activity object of type messageType: message. Несмотря на то Activity , что объект может содержать другие типы информации, например обновления канала , отправляемые в Bot, message тип представляет связь между Bot и пользователем.Although the Activity object can contain other types of information, like channel updates sent to your bot, the message type represents communication between bot and user.

Ваш Bot получает полезные данные, содержащие сообщение пользователя Text , а также другие сведения о пользователе, источник сообщения и сведения о Teams.Your bot receives a payload that contains the user message Text as well as other information about the user, the source of the message, and Teams information. Примечание:Of note:

  • timestampДата и время сообщения в формате всемирного координированного времени (UTC).timestamp The date and time of the message in Coordinated Universal Time (UTC)
  • localTimestampДата и время сообщения в часовом поясе отправителяlocalTimestamp The date and time of the message in the time zone of the sender
  • channelIdВсегда "мстеамс".channelId Always "msteams". Это относится к каналу Bot Framework, а не к каналу Teams.This refers to a bot framework channel, not a teams channel.
  • from.idУникальный и зашифрованный идентификатор пользователя для ленты. подходит в качестве ключа, если ваше приложение должно хранить пользовательские данные.from.id A unique and encrypted ID for that user for your bot; suitable as a key if your app needs to store user data. Он уникален для почтового робота и не может использоваться непосредственно за престоронним экземпляром Bot с помощью какого-либо осмысленного способа идентификации этого пользователяIt is unique for your bot and cannot be directly used outside your bot instance in any meaningful way to identify that user
  • channelData.tenant.idИдентификатор клиента для пользователя.channelData.tenant.id The tenant ID for the user.

Примечание

from.idявляется уникальным для почтового робота и не может использоваться непосредственно за престоронним экземпляром Bot с помощью какого-либо осмысленного способа идентификации этого пользователя.from.id is unique for your bot and cannot be directly used outside your bot instance in any meaningful way to identify that user.

Объединение каналов и частных взаимодействий с BotCombining channel and private interactions with your bot

При взаимодействии с каналом Bot должен быть разумным, чтобы принимать определенные беседы в автономном режиме с пользователем.When interacting in a channel, your bot should be smart about taking certain conversations offline with a user. Например, предположим, что пользователь пытается координировать сложную задачу, например планирование с набором участников группы.For instance, suppose a user is trying to coordinate a complex task, such as scheduling with a set of team members. Вместо того чтобы всю последовательность взаимодействий, видимых каналу, рассмотрите возможность отправки пользователю личного сообщения разговора.Rather than have the entire sequence of interactions visible to the channel, consider sending a personal chat message to the user. Ваш робот должен легко перевести пользователя между личными и каналами бесед без потери состояния.Your bot should be able to easily transition the user between personal and channel conversations without losing state.

Примечание

Не забудьте обновить канал после завершения взаимодействия, чтобы уведомить других участников группы.Don’t forget to update the channel when the interaction is complete to notify the other team members.

Пример полной входящей схемыFull inbound schema example

{
    "type": "message",
    "id": "1485983408511",
    "timestamp": "2017-02-01T21:10:07.437Z",
    "localTimestamp": "2017-02-01T14:10:07.437-07:00",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "channelId": "msteams",
    "from": {
        "id": "29:1XJKJMvc5GBtc2JwZq0oj8tHZmzrQgFmB39ATiQWA85gQtHieVkKilBZ9XHoq9j7Zaqt7CZ-NJWi7me2kHTL3Bw",
        "name": "Megan Bowen",
        "aadObjectId": "7faf8ab2-3d56-4244-b585-20c8a42ed2b8"
    },
    "conversation": {
        "conversationType": "personal",
        "id": "a:17I0kl9EkpE1O9PH5TWrzrLNwnWWcfrU7QZjKR0WSfOpzbfcAg2IaydGElSo10tVr4C7Fc6GtieTJX663WuJCc1uA83n4CSrHSgGBj5XNYLcVlJAs2ZX8DbYBPck201w-"
    },
    "recipient": {
        "id": "28:c9e8c047-2a74-40a2-b28a-b162d5f5327c",
        "name": "Teams TestBot"
    },
    "textFormat": "plain",
    "text": "Hello Teams TestBot",
    "entities": [
      { 
        "locale": "en-US",
        "country": "US",
        "platform": "Windows",
        "timezone": "America/Los_Angeles",
        "type": "clientInfo"
      }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Примечание

Текстовое поле для входящих сообщений иногда содержит упоминания.The text field for inbound messages sometimes contains mentions. Обязательно проверьте и извлеките их.Be sure to properly check and strip those. Дополнительные сведения см.For more information, see Mentions.

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

channelDataОбъект содержит сведения, зависящие от команды, и является основным источником для идентификаторов команд и каналов.The channelData object contains Teams-specific information and is the definitive source for team and channel IDs. Вы должны кэшировать и использовать эти идентификаторы в качестве ключей для локального хранилища.You should cache and use these ids as keys for local storage.

Этот 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"
    }
}

Пример .NET.NET example

Пакет NuGet Microsoft. Bot. Connector. Teams предоставляет специализированный TeamsChannelData объект, который предоставляет свойства для доступа к сведениям, относящимся к Teams.The Microsoft.Bot.Connector.Teams NuGet package provides a specialized TeamsChannelData object, which exposes properties to access Teams-specific information.

TeamsChannelData channelData = activity.GetChannelData<TeamsChannelData>();
string tenantId = channelData.Tenant.Id;

Отправка ответов на сообщенияSending replies to messages

Чтобы ответить на существующее сообщение, звоните ReplyToActivity в .NET или session.send в Node.js.To reply to an existing message, call ReplyToActivity in .NET or session.send in Node.js. Пакет SDK построителя построителя обрабатывает все подробные сведения.The Bot Builder SDK handles all the details.

Если вы решили использовать REST API, вы также можете вызвать /v3/conversations/{conversationId}/activities/{activityId} конечную точку.If you choose to use the REST API, you can also call the /v3/conversations/{conversationId}/activities/{activityId} endpoint.

Само содержимое сообщения может содержать простой текст или некоторые карточки и действия карточки сBot Framework.The message content itself can contain simple text or some of the Bot Framework supplied cards and card actions.

Обратите внимание, что в используемой схеме исходящей почты следует всегда использовать ту же информацию, что и serviceUrl в полученном виде.Please note that in your outbound schema you should always use the same serviceUrl as the one you received. Имейте в виду, что значение serviceUrl является стабильным, но может измениться.Be aware that the value of serviceUrl tends to be stable but can change. Когда поступает новое сообщение, ваш робот должен проверить сохраненное значение serviceUrl .When a new message arrives, your bot should verify its stored value of serviceUrl.

Обновление сообщенийUpdating messages

Вместо того чтобы сообщения были статическими моментальными снимками данных, ваш Bot может динамически обновлять сообщения после отправки.Rather than have your messages be static snapshots of data, your bot can dynamically update messages inline after sending them. Динамическое обновление сообщений можно использовать для таких сценариев, как обновление опросов, изменение доступных действий после нажатия кнопки или любое другое изменение асинхронного состояния.You can use dynamic message updates for scenarios such as poll updates, modifying available actions after a button press, or any other asynchronous state change.

Новое сообщение не должно быть соответствующим исходному типу.The new message need not match the original in type. Например, если исходное сообщение содержит вложение, новое сообщение может быть простым текстовым сообщением.For instance, if the original message contained an attachment, the new message can be a simple text message.

Примечание

Вы можете обновить только содержимое, отправленное в сообщениях с одним вложением и в виде схем обоймы.You can update only content sent in single-attachment messages and carousel layouts. Публикация обновлений сообщений с несколькими вложениями в раскладке списков не поддерживается.Posting updates to messages with multiple attachments in list layout is not supported.

REST APIREST API

Чтобы отправить сообщение об обновлении, просто выполните запрос PUT для /v3/conversations/<conversationId>/activities/<activityId>/ конечной точки, используя заданный идентификатор действия.To issue a message update, simply perform a PUT request against the /v3/conversations/<conversationId>/activities/<activityId>/ endpoint using a given activity ID. Для выполнения этого сценария необходимо кэшировать идентификатор действия, возвращенный исходным вызовом POST.To complete this scenario, you should cache the activity ID returned by the original POST call.

PUT /v3/conversations/19%3Aja0cu120i1jod12j%40skype.net/activities/012ujdo0128
{
    "type": "message",
    "text": "This message has been updated"
}

Пример .NET.NET example

UpdateActivityAsyncС помощью метода в пакете SDK построителя построителя можно обновить существующее сообщение.You can use the UpdateActivityAsync method in the Bot Builder SDK to update an existing message.

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
  if (activity.Type == ActivityTypes.Message)
  {
    ConnectorClient connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    Activity reply = activity.CreateReply($"You sent {activity.Text} which was {activity.Text.Length} characters");
    var msgToUpdate = await connector.Conversations.ReplyToActivityAsync(reply);
    Activity updatedReply = activity.CreateReply($"This is an updated message");
    await connector.Conversations.UpdateActivityAsync(reply.Conversation.Id, msgToUpdate.Id, updatedReply);
  }
}

Пример Node.jsNode.js example

session.connector.updateС помощью метода в пакете SDK построителя построителя можно обновить существующее сообщение.You can use the session.connector.update method in the Bot Builder SDK to update an existing message.

function sendCardUpdate(bot, session, originalMessage, address) {

  var origAttachment = originalMessage.data.attachments[0];
  origAttachment.content.subtitle = 'Assigned to Larry Jin';

  var updatedMsg = new builder.Message()
    .address(address)
    .textFormat(builder.TextFormat.markdown)
    .addAttachment(origAttachment)
    .toMessage();

  session.connector.update(updatedMsg, function(err, addresses) {
    if (err) {
      console.log(`Could not update the message`);
    }
  });
}

Начало беседы (упреждающий обмен сообщениями)Starting a conversation (proactive messaging)

Вы можете создать личный разговор с пользователем или начать новую цепочку ответа в канале для командного канала.You can create a personal conversation with a user or start a new reply chain in a channel for your team bot. Это позволяет отправлять сообщения пользователям и пользователям, не прибегая к ним, прежде чем приступить к работе с роботом.This lets you to message your user or users without having them first initiate contact with your bot. Дополнительную информацию см. в следующих статьях:For more information, see the following topics:

В этой статье приведены сведения об активных сообщениях для Боты для получения общих сведений о беседах, запущенных Боты.See Proactive messaging for bots for more general information on conversations started by bots.

Удаление сообщенийDeleting messages

Сообщения можно удалять с помощью метода Connectors delete() в ботбуилдер SDK.Messages can be deleted using the connectors delete() method in the BotBuilder SDK.

bot.dialog('BotDeleteMessage', function (session: builder.Session) {
  var msg = new teams.TeamsMessage(session).text("Bot will delete this message in 5 sec.")
  bot.send(msg, function (err, response) {
    if (err) {
      console.log(err);
      session.endDialog();
    }

    console.log('Proactive message response:');
    console.log(response);
    console.log('---------------------------------------------------')
    setTimeout(function () {
      var activityId: string = null;
      var messageAddress: builder.IChatConnectorAddress = null;
      if (response[0]){
        messageAddress = response[0];
        activityId = messageAddress.id;
      }

      if (activityId == null)
      {
        console.log('Message failed to send.');
        session.endDialog();
        return;
      }

      // Bot delete message
      let address: builder.IChatConnectorAddress  = {
        channelId: 'msteams',
        user: messageAddress.user,
        bot: messageAddress.bot,
        id : activityId,
        serviceUrl : (<builder.IChatConnectorAddress>session.message.address).serviceUrl,
        conversation: {
          id: session.message.address.conversation.id
        }
      };

      connector.delete(address, function (err) {
        if (err)
        {
          console.log(err);
        }
        else
        {
          console.log("Message: " + activityId + " deleted successfully.");
        }

        // Try editing deleted message would fail
        var newMsg = new builder.Message().address(address).text("To edit message.");
        connector.update(newMsg.toMessage(), function (err, address) {
          if (err)
          {
            console.log(err);
            console.log('Deleted message can not be edited.');
          }
          else
          {
            console.log("There is something wrong. Message: " + activityId + " edited successfully.");
            console.log(address);
          }

          session.endDialog();
        });
      });
    }, 5000);
  });
})