Беседы с бото в канале и групповом чате

Важно!

Примеры кода в этом разделе основаны на версии 4.6 и более поздних версиях пакета SDK Bot Framework. Если вы ищете документацию по более ранним версиям, см. раздел пакет SDK для ботов версии 3 в папке Устаревшие пакеты SDK документации.

Чтобы установить Microsoft Teams бота в чате группы или команды, добавьте боту область teams или groupchat. В результате все участники беседы взаимодействовать с вашим ботом. После установки бот получает доступ к метаданным беседы, например к списку участников. Кроме того, при установке в команде бот имеет доступ к подробным сведениям об этой команде и полному списку каналов.

Боты в группе или канале получают сообщения только при упоминании @botname. Они не получают других сообщений, отправляемых в беседу. Бот должен быть @mentioned непосредственно. Бот не получает сообщение, когда упоминается команда или канал или когда кто-то отвечает на сообщение от вашего бота без @mentioning него.

Примечание.

• RSC для всех сообщений чата доступен только в общедоступной предварительной версии для разработчиков.
• Используя согласие для конкретного ресурса (RSC), боты могут получать все сообщения канала в командах, в которых он установлен, без использования @mentioned. Дополнительные сведения см. в статье Получение всех сообщений канала с помощью RSC.
• Публикация сообщений или адаптивных карточек в частном канале в настоящее время не поддерживается.

См. следующее видео, чтобы узнать о беседах в канале и групповом чате с ботом:

Рекомендации по дизайну

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

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

Создание цепочки беседы

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

Затем можно получить упоминания с помощью объекта entities и добавить упоминания в сообщения с помощью объекта Mention.

Работа с @упоминаниями

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

Кроме того, необходимо удалить @mentions из содержимого сообщения, которое получает бот.

Получение упоминаний

Упоминания возвращаются в полезных данных объекта entities и содержат как уникальный ИД пользователя, так и имя упомянутого пользователя. Текст сообщения также содержит упоминание, например <at>@John Smith<at>. Однако не полагайтесь на текст в сообщении для получения каких-либо сведений о пользователе. Пользователь, отправляющий сообщение, может изменить его. Поэтому используйте объект entities.

Вы можете получить все упоминания в сообщении, вызвав функцию GetMentions в пакете SDK Bot Builder, которая возвращает массив объектов Mention.

В следующем фрагменте программного кода показан пример получения упоминаний:

C#

• Справочные материалы для SDK

• Пример справочника по коду

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Resolves the mentions from the entities activity.
    Mention[] mentions = turnContext.Activity.GetMentions();
    if(mentions != null)
    {
        ChannelAccount firstMention = mentions[0].Mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync($"Hello {firstMention.Name}");
    }
    else
    {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("Aw, no one was mentioned.");
    }
}

TypeScript

Справочные материалы для SDK

this.onMessage(async (turnContext, next) => {
    
    // Resolves the mentions from the entities activity.
    const mentions = TurnContext.getMentions(turnContext.activity);
    if (mentions){
        const firstMention = mentions[0].mentioned;

        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Hello ${firstMention.name}.`);
    } else {
        // Sends a message activity to the sender of the incoming activity.
        await turnContext.sendActivity(`Aw, no one was mentioned.`);
    }

    await next();
});

JSON

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Python

Справочные материалы для SDK

@staticmethod
// Resolves the mentions from the entities of this activity.
def get_mentions(activity: Activity) -> List[Mention]:
    result: List[Mention] = []
    if activity.entities is not None:
        for entity in activity.entities:
            if entity.type.lower() == "mention":
                    result.append(entity)
     return result

Добавление упоминаний в сообщения

Существует два типа упоминаний:

• Упоминание пользователя
• Упоминание тегов

Упоминание пользователя

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

Объект Mention имеет два свойства, которые необходимо задать с помощью следующих элементов:

• Включите @имя_пользователя в текст сообщения.
• Включите объект упоминания в коллекцию сущностей.

Пакет SDK Bot Framework предоставляет вспомогательные методы и объекты для создания упоминаний.

В следующем фрагменте программного кода показан пример добавления упоминаний в сообщения:

C#

• Справочные материалы для SDK
• Пример справочника по коду

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var mention = new Mention
    {
        Mentioned = turnContext.Activity.From,
        Text = $"<at>{XmlConvert.EncodeName(turnContext.Activity.From.Name)}</at>",
        Type = "mention",
    };

    // Returns a simple text message.
    var replyActivity = MessageFactory.Text($"Hello {mention.Text}.");
    replyActivity.Entities = new List<Entity> { mention };

    // Sends an activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

TypeScript

this.onMessage(async (turnContext, next) => {
    const mention = {
        mentioned: turnContext.activity.from,
        text: `<at>${ new TextEncoder().encode(turnContext.activity.from.name) }</at>`,
        type: "mention",
    } as Mention;

    // Returns a simple text message.
    const replyActivity = MessageFactory.text(`Hello ${mention.text}`);
    replyActivity.entities = [mention];

    // Sends a message activity to the sender of the incoming activity.
    await turnContext.sendActivity(replyActivity);

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

JSON

Поле text в объекте в массиве entities должно соответствовать части поля сообщения text. Если это не так, упоминание игнорируется.

{
    "type": "message",
    "text": "Hey <at>Pranav Smith</at> check out this message",
    "timestamp": "2017-10-29T00:51:05.9908157Z",
    "localTimestamp": "2017-10-28T17:51:05.9908157-07:00",
    "serviceUrl": "https://skype.botframework.com",
    "channelId": "msteams",
    "from": {
        "id": "29:9e52142b-5e5e-4d7b-bb3e-e82dcf620000",
        "name": "Jane Smith"
    },
    "conversation": {
        "id": "19:aebd0ad4d6ab42c8b9ed19c251c2fc37@thread.skype;messageid=1481567603816"
    },
    "recipient": {
        "id": "8:orgid:6aebbad0-e5a5-424a-834a-20fb051f3c1a",
        "name": "stlrgload100"
    },
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://upload.wikimedia.org/wikipedia/en/a/a6/Bender_Rodriguez.png",
            "name": "Bender_Rodriguez.png"
        }
    ],
    "entities": [
        {
            "type":"mention",
            "mentioned":{
                "id":"29:08q2j2o3jc09au90eucae",
                "name":"Pranav Smith"
            },
            "text": "<at>@Pranav Smith</at>"
        }
    ],
    "replyToId": "3UP4UTkzUk1zzeyW"
}

Python

• Справочные материалы для SDK
• Пример справочника по коду

async def _mention_activity(self, turn_context: TurnContext):
        mention = Mention(
            mentioned=turn_context.activity.from_property,
            text=f"<at>{turn_context.activity.from_property.name}</at>",
            type="mention"
        )
        // Returns a simple text message.
        reply_activity = MessageFactory.text(f"Hello {mention.text}")
        # Sends a message activity to the sender of the incoming activity.
        reply_activity.entities = [Mention().deserialize(mention.serialize())]
        await turn_context.send_activity(reply_activity)

Теперь ваш бот может представиться при первой установке или добавлении в группу или команду.

Упоминание тегов

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

Примечание.

Упоминания тегов не поддерживаются в клиентах Облака сообщества для государственных организаций (GCC), GCC-High и Министерства обороны (DoD).

Упоминание тегов в текстовом сообщении

В объекте mention.properties добавьте свойство 'type': 'tag'. Если свойство 'type': 'tag' не добавлено, бот обрабатывает упоминание как упоминание пользователя.

Пример.

Добавляется type:tag как в Properties ChannelAccount.

Справочные материалы для SDK

​var mention = new ChannelAccount(tagId, "Test Tag"); 
​mention.Properties = JObject.Parse("{'type': 'tag'}"); 
​var mentionObj = new Mention 
​{ 
​    Mentioned = mention, 
​    Text = "<at>Test Tag</at>" 
​}; 

​var replyActivity = MessageFactory.Text("Hello " + mentionObj.Text); 
​replyActivity.Entities = new List<Microsoft.Bot.Schema.Entity> { mentionObj }; 
​await turnContext.SendActivityAsync(replyActivity, cancellationToken); 

Упоминания тегов в адаптивной карточке

В схеме адаптивной карточки в объекте mentioned добавьте "type": "tag" свойство . "type": "tag" Если свойство не добавлено, бот обрабатывает упоминание как упоминание пользователя.

Список тегов, доступных в канале, можно получить с помощью API list teamworkTags .

Пример.

​{ 
​    "type": "mention", 
    ​"text": "<at>Test Tag</at>", 
​    "mentioned": { 
            ​"id": "base64 encoded id" ,// tag graph 64 base ID
​            "name": "Test Tag", 
            ​"type": "tag" 
​    } 
​} 

Параметры запроса

Имя	Описание
type	Тип упоминание. Поддерживаемый тип — tag.
id	Уникальный идентификатор тега. Дополнительные сведения см. в разделе TeamworkTag.

Код ошибки

Код состояния	Код ошибки	Значения сообщений	Повторный запрос	Действие разработчика
400	Код: Bad Request	Упомянутый тег с идентификатором {id string} не существует в текущей команде Тег можно упомянуть только в канале Недопустимый упомянутый тег, так как в команде не существует тега	Нет	Переоценка полезных данных запроса на наличие ошибок. Проверьте возвращенное сообщение об ошибке для получения дополнительных сведений.
502	Код: Bad Gateway	Недопустимый идентификатор группы команды Неправильный идентификатор клиента для тега Не удается разрешить идентификатор упоминания	Нет	Повторите попытку вручную.

Пределы регулирования

Любой запрос может оцениваться с учетом нескольких ограничений в зависимости от область, типа окна (короткого и длинного), количества тегов на сообщение и других факторов. Первое достигнутое ограничение запускает действие регулирования.

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

В следующей таблице перечислены ограничения регулирования для упоминаний тегов в боте:

Области	Тип окна	Количество тегов на сообщение	Временные окна (с)	Максимальное число сообщений в период времени
На бота на поток	Короткие	10	5	2
	Длинные	10	60	5
Все боты на поток	Короткие	10	5	4
	Длинное целое	10	60	5

Ограничения

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

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

При первом добавлении бота в группу или команду необходимо отправить начальное приветственное сообщение. Сообщение должно содержать краткое описание функций бота и способы их использования. Необходимо подписаться на событие conversationUpdate с помощью eventType teamMemberAdded. Событие отправляется при добавлении нового участника команды. Проверьте, является ли добавленный новый участник ботом. Подробнее см. в статье Отправка приветственного сообщения новому участнику команды.

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

Примечание.

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

Не отправляйте сообщение в следующих случаях:

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

Примеры ботов Teams

Пример кода

Полные рабочие примеры, демонстрирующие эту функциональность, см. в следующих примерах Teams для Bot Framework:

Название примера	Описание	.NET	Node.js	Python	Манифест
Бот для беседы в Teams	В этом примере показано, как использовать различные события бесед бота, доступные в bot framework версии 4 для личных и командных область.	Просмотр	Просмотр	Просмотр	Просмотр
Проверка подлинности с помощью OAuthPrompt	В этом примере показана проверка подлинности и базовый обмен сообщениями в Bot Framework версии 4.	Просмотр	Просмотр	Просмотр	Просмотр
Отправка файла Teams	В этом примере показано, как использовать файлы с ботом в беседе один к одному.	Просмотр	Просмотр	Просмотр	Просмотр
Dialog (называется модулем задач в TeamsJS версии 1.x)	В этом примере показано, как использовать диалоговое окно и значения из карточек в нем для расширения сообщений.	Просмотр	Просмотр	Просмотр	View
Запуск новой цепочки в канале	В этом примере показано, как использовать новый поток в канале с помощью бота.	Просмотр	Просмотр	Просмотр	Просмотр
Локализация приложений Teams	В этом примере показано, как использовать локализацию приложений Teams с помощью бота и вкладки.	Просмотр	Просмотр	Н/Д	View

Пошаговые инструкции

Следуйте пошаговому руководству, создайте бот для бесед Teams.

Следующий этап

Подписка на события беседы

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

• Получение контекста в Teams.
• Создание частного канала от имени пользователя
• Подключение бота к каналу Веб-чат