Сообщения в беседах с ботами

• 10.06.2021
• Чтение занимает 7 мин
• • l

Каждое сообщение в беседе является Activity объектом типа messageType: message . Когда пользователь отправляет сообщение, Teams отправляет сообщение в бот. Teams отправляет объект JSON в конечную точку обмена сообщениями вашего бота. Бот проверяет сообщение, чтобы определить его тип, и отвечает соответствующим образом.

Основные беседы обрабатываются через соединители Bot Framework, единый API REST. Этот API позволяет боту общаться с Teams другими каналами. В SDK Bot Builder представлены следующие функции:

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

Ваш бот получает сообщения из Teams с помощью свойства и отправляет пользователям одиночные или несколько Text ответов на сообщения.

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

Чтобы получить текстовое сообщение, используйте свойство Text объекта Activity. В обработчике активности бота используйте объект контекста поворота Activity для чтения одного запроса сообщения.

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

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

export class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity(`Echo: '${context.activity.text}'`);
            await next();
        });
    }
}

async def on_message_activity(self, turn_context: TurnContext):
    return await turn_context.send_activity(MessageFactory.text(f"Echo: {turn_context.activity.text}"))

{
    "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"
}

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

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

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

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

export class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello and welcome!');
            await next();
        });
    }
}

async def on_members_added_activity(
    self, members_added: [ChannelAccount], turn_context: TurnContext
):
    for member in teams_members_added:
        await turn_context.send_activity(f"Welcome your new team member {member.id}")
    return

{
    "text": "hi",
    "textFormat": "plain",
    "type": "message",
    "timestamp": "2019-10-31T20:57:27.2347285Z",
    "localTimestamp": "2019-10-31T13:57:27.2347285-07:00",
    "id": "1572555447214",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1Xv-kvy4dKirR0rZfSF_kAVUzotoT1SXuEzkC9XGkuZng8YBw8qyu5uh4128fQRjlGgvEiRLx-0XP4KYMwcgdZw",
        "name": "Jane Doe",
        "aadObjectId": "df486eae-88fd-42a5-b45e-c581588186db"
    },
    "conversation": {
        "conversationType": "personal",
        "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
        "id": "a:1oAmWTVBBe9E0JrpGxauqNyx4CCE_iQf2ZuWon9D42722Fon3wYIpbhgbRChE3wgVS1Gwl9zS1pZy4FSu6-x1vGEq5KBQK-EbBgyPyeP_C-lbLBY3vxnGk9m9D_282jbg"
    },
    "recipient": {
        "id": "28:5baea8d1-d4ea-43a1-b101-882f4c8d9cb4",
        "name": "Imported Bot"
    },
    "entities": [
        {
            "locale": "en-US",
            "country": "US",
            "platform": "Windows",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
        }
    },
    "locale": "en-US"
}

Сообщения, отправленные между пользователями и ботами, включают внутренние данные канала в сообщении. Эти данные позволяют боту правильно общаться на этом канале. SDK bot Builder позволяет изменять структуру сообщений.

Teams каналов

Объект содержит Teams и является окончательным источником для кодов группы и channelData канала. Дополнительно можно кэширования и использования этих ID в качестве ключей для локального хранения. SDK извлекет важные сведения из объекта, чтобы сделать его TeamsActivityHandler channelData доступным. Однако вы всегда можете получить доступ к исходным данным turnContext объекта.

Объект не входит в сообщения в личных беседах, так как они проходят за channelData пределами канала.

Типичный channelData объект в действии, отправленного боту, содержит следующие сведения:

• eventType: Teams тип события передается только в случаях событий изменения канала.
• tenant.id: Azure Active Directory клиента, переданный во всех контекстах.
• team: Передается только в контекстах каналов, а не в личном чате.
  • id: GUID для канала.
  • name: Имя команды передается только в случаях переименования событий команды.
• channel. Передается только в контекстах каналов, когда бот упоминается или для событий в каналах в командах, где был добавлен бот.
  • id: GUID для канала.
  • name: Имя канала передается только в случаях событий изменения канала.
• channelData.teamsTeamId: Обесценилось. Это свойство включено только для обратной совместимости.
• channelData.teamsChannelId: Обесценилось. Это свойство включено только для обратной совместимости.

Пример объекта channelData или события channelCreated

В следующем коде показан пример объекта channelData:

"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"
    }
}

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

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

Вы также можете добавить уведомления в сообщение с помощью Notification.Alert свойства.

Уведомления о вашем сообщении

Уведомления предупреждают пользователей о новых задачах, упоминаниях и комментариях. Эти оповещения связаны с тем, над чем работают пользователи или на что они должны смотреть, вставляя уведомление в канал активности. Чтобы уведомления запускались из сообщения бота, установите свойство TeamsChannelData Notification.Alert объектов true . Вопрос о том, будет ли поднято уведомление, зависит от параметров Teams пользователя, и переопределять эти параметры невозможно. Тип уведомления — это либо баннер, либо баннер и электронная почта.

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

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

this.onMessage(async (turnContext, next) => {
    let message = MessageFactory.text("You'll get a notification, if you've turned them on.");
    teamsNotifyUser(message);

    await turnContext.sendActivity(message);

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

async def on_message_activity(self, turn_context: TurnContext):
    message = MessageFactory.text("You'll get a notification, if you've turned them on.")
    teams_notify_user(message)

    await turn_context.send_activity(message)

{
  "type": "message",
  "timestamp": "2017-04-24T21:46:00.9663655Z",
  "localTimestamp": "2017-04-24T14:46:00.9663655-07:00",
  "serviceUrl": "https://callback.com",
  "channelId": "msteams",
  "from": {
    "id": "28:e4fda94a-4b80-40eb-9bf0-6314491bc793",
    "name": "The bot"
  },
  "conversation": {
    "id": "a:1pL6i0oY3C0K8oAj8"
  },
  "recipient": {
    "id": "29:1rsVJmSSFMScF0YFyCXpvNWlo",
    "name": "User"
  },
  "text": "John Phillips assigned you a weekly todo",
  "summary": "Don't forget to meet with Marketing next week",
  "channelData": {
    "notification": {
      "alert": true
    }
  },
  "replyToId": "1493070356924"
}

Чтобы улучшить сообщение, вы можете включить изображения в качестве вложений к этому сообщению.

Сообщения изображений

Изображения отправляются путем добавления вложений в сообщение. Дополнительные сведения о вложениях см. в документации Bot Framework.

Изображения могут быть не более 1024×1024 и 1 МБ в формате PNG, JPEG или GIF. Анимированный GIF не поддерживается.

Укажите высоту и ширину каждого изображения с помощью XML. При разметки размер изображения по умолчанию составляет 256×256. Пример.

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

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

Адаптивные карточки

Адаптивные карты можно авторить в боте и показывать в нескольких приложениях, таких как Teams, веб-сайт и так далее. Дополнительные сведения см. в дополнительных сведениях в адаптивных картах.

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

{
    "type": "AdaptiveCard",
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5",
    "body": [
    {
        "items": [
        {
            "size": "large",
            "text": " Simple Adaptivecard Example with a Textbox",
            "type": "TextBlock",
            "weight": "bolder",
            "wrap": true
        },
        ],
        "spacing": "extraLarge",
        "type": "Container",
        "verticalContentAlignment": "center"
    }
    ]
}

Дополнительные информацию о картах и картах в ботах см. в документации по картам.

Ответы на код состояния

Ниже печатаются коды состояния и их код ошибок и значения сообщений:

Пример кода

См. также

• Отправка упреждающих сообщений

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

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