Добавление вложения с расширенными картами в сообщения с помощью API Bot Connector
Некоторые каналы позволяют боту отправлять богатые карточки пользователям. Многофункциональная карточка — это вложение, содержащее интерактивные элементы, такие как кнопки, текст, изображения, аудио, видео и т. д.
В этой статье описывается создание расширенных карточек, которые можно подключить к сообщению. Узнайте, как добавлять в сообщения вложения мультимедиа для определенных инструкций по добавлению вложения в сообщение.
Типы функциональных карточек
Форматированная карточка содержит название, описание, ссылку и изображения. Сообщение может содержать несколько форматированных карточек, которые отображаются в виде списка или карусели. Сейчас Bot Framework поддерживает восемь типов форматированных карточек.
| Тип карточки | Description |
|---|---|
| AdaptiveCard | Настраиваемая карточка, которая может содержать любое сочетание текста, речи, изображений, кнопок и полей для ввода. См. описание поддержки для каждого канала. |
| AnimationCard | Карточка, которая может воспроизводить GIF-файлы с анимацией или короткие видеоролики. |
| AudioCard | Карточка, которая может воспроизводить звуковой файл. |
| HeroCard | Карточка, которая обычно содержит одно большое изображение, одну или несколько кнопок и текст. |
| ThumbnailCard | Карточка, которая обычно содержит один эскиз, одну или несколько кнопок и текст. |
| ReceiptCard | Карточка, с помощью которой бот выдает квитанцию пользователю. Обычно она содержит список элементов, включаемых в квитанцию, налог, а также общую информацию и другой текст. |
| SignInCard | Карточка, в которой бот запрашивает вход пользователя. Обычно она содержит текст и одну или несколько кнопок, которые можно нажать, чтобы начать процесс входа. |
| VideoCard | Карточка, которая может воспроизводить видео. |
Совет
Сведения о том, какие функции поддерживаются в каждом канале, см. в справочной статье о каналах.
Обработка событий в форматированных карточках
Для обработки событий в форматированных карточках используйте объекты CardAction, чтобы указать, что должно происходить, когда пользователь нажимает кнопку или касается сегмента карточки. Каждый объект CardAction содержит следующие свойства.
| Свойство | Type | Описание |
|---|---|---|
| channelData | строка | Относящиеся к каналу данные, связанные с этим действием. |
| displayText | строка | Текст, отображаемый в канале чата при нажатии кнопки. |
| text | строка | Текст для действия. |
| type | строка | тип действия (одно из значений, указанных в таблице ниже) |
| title | string | название кнопки |
| Изображение | строка | URL-адрес изображения для кнопки |
| значение | строка | значение, необходимое для выполнения указанного типа действия |
Примечание.
Для создания кнопок в адаптивных карточках используются не объекты CardAction, а схема, которая определяется адаптивными карточками.
О том, как добавить кнопку в адаптивную карточку, см. в разделе Добавление адаптивной карточки в сообщение.
Чтобы правильно функционировать, назначьте тип действия каждому элементу, который можно щелкнуть на карточке героя. В этой таблице перечислены и описаны доступные типы действий и требуемый формат для связанного свойства.
Действие messageBack карточки имеет более обобщенное значение, чем другие действия карты. Дополнительные сведения о messageBack других типах действий карточек см. в разделе "Действие карты".
| Тип | Описание | Значение |
|---|---|---|
| call | Инициирует телефонный звонок. | Целевое назначение телефонного звонка в следующем формате: tel:123123123123. |
| downloadFile | Скачивает файл. | URL-адрес для скачивания файла. |
| imBack | Отправляет боту сообщение и отображает полученный ответ в чате. | Текст отправляемого сообщения. |
| messageBack | Представляет текстовый ответ, отправляемый через систему чата. | Необязательное программное значение для включения в созданные сообщения. |
| openUrl | Открывает URL-адрес в окне встроенного браузера. | URL-адрес, который нужно открыть. |
| playAudio | Воспроизводит звук. | URL-адрес для воспроизведения звука. |
| playVideo | Воспроизводит видео. | URL-адрес для воспроизведения видео. |
| postBack | Отправляет боту сообщение, но не всегда отображает полученный ответ в чате. | Текст отправляемого сообщения. |
| showImage | Отображает изображение. | URL-адрес для отображения изображения. |
| signin | Инициирует процесс входа OAuth. | URL-адрес потока OAuth, который нужно запустить. |
Добавление имиджевой карточки в сообщение
Чтобы добавить в сообщение вложение с форматированными карточками, выполните следующее:
- Создайте объект, представляющий тип карточки , которую нужно добавить в сообщение.
- Создайте объект Attachment:
- Задайте для свойства
contentTypeтип носителя карточки. - Задайте его
contentсвойству объект, созданный для представления карточки.
- Задайте для свойства
- Добавьте объект в
Attachmentattachmentsмассив сообщения.
Совет
Сообщения, содержащие вложения с форматированными карточками, обычно не указывают text.
На некоторых каналах можно добавлять несколько форматированных карточек в массив attachments сообщения. Это может быть полезно в сценариях, где необходимо предоставить пользователю несколько параметров. Например, если бот позволяет пользователям забронировать номера в гостинице, то он может предоставить список форматированных карточек, в которых будут показаны типы доступных номеров. Каждая карточка может содержать изображение и список удобств, соответствующих типу комнаты, а пользователь может выбрать тип комнаты, нажав на кнопку или щелкнув карточку.
Совет
Чтобы отобразить несколько форматированных карточек в виде списка, задайте свойству attachmentLayout объекта Activity значение list.
Чтобы отобразить несколько форматированных карточек в виде карусели, задайте свойству attachmentLayout объекта Activity значение carousel.
Если канал не поддерживает формат каруселя, он будет отображать богатые карточки в формате списка, даже если attachmentLayout свойство указывает карусель.
В следующем примере показано полное сообщение, содержащее одно вложение карточки героя. В этом примере запрос https://smba.trafficmanager.net/teams представляет базовый URI. Базовый URI для запросов, отправляемых вашим ботом, может отличаться. Дополнительные сведения о настройке базового URI см. в статье Справочник по API.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "sender's name"
},
"conversation": {
"id": "abcd1234",
"name": "conversation's name"
},
"recipient": {
"id": "1234abcd",
"name": "recipient's name"
},
"attachments": [
{
"contentType": "application/vnd.microsoft.card.hero",
"content": {
"title": "title goes here",
"subtitle": "subtitle goes here",
"text": "descriptive text goes here",
"images": [
{
"url": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"alt": "picture of a duck",
"tap": {
"type": "playAudio",
"value": "url to an audio track of a duck call goes here"
}
}
],
"buttons": [
{
"type": "playAudio",
"title": "Duck Call",
"value": "url to an audio track of a duck call goes here"
},
{
"type": "openUrl",
"title": "Watch Video",
"image": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"value": "url goes here of the duck in flight"
}
]
}
}
],
"replyToId": "5d5cdc723"
}
Добавление адаптивной карточки в сообщение
Адаптивная карточка может содержать любое сочетание текста, речи, изображений, кнопок и полей для ввода. Адаптивные карточки создаются в формате JSON (см. здесь), что позволяет получить больший контроль над содержимым и форматом карточек.
Ознакомьтесь со сведениями на веб-сайте адаптивных карточек, чтобы получить представление о схеме адаптивных карточек, изучить элементы адаптивных карточек и просмотреть примеры JSON, которые можно использовать для создания карточек различного состава и уровня сложности. А воспользовавшись интерактивным визуализатором, вы сможете разрабатывать соответствующие полезные нагрузки и просматривать выходные данные карточки.
В следующем примере показан один объект вложения адаптивной карточки, представляющий задание работы. Чтобы отправить это пользователю, необходимо добавить его в виде вложения в сообщении.
{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.0",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Publish Adaptive Card schema",
"weight": "bolder",
"size": "medium"
},
{
"type": "ColumnSet",
"columns": [
{
"type": "Column",
"width": "auto",
"items": [
{
"type": "Image",
"url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
"size": "small",
"style": "person"
}
]
},
{
"type": "Column",
"width": "stretch",
"items": [
{
"type": "TextBlock",
"text": "Matt Hidinger",
"weight": "bolder",
"wrap": true
},
{
"type": "TextBlock",
"spacing": "none",
"text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
"isSubtle": true,
"wrap": true
}
]
}
]
}
]
},
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
"wrap": true
},
{
"type": "FactSet",
"facts": [
{
"title": "Board:",
"value": "Adaptive Card"
},
{
"title": "List:",
"value": "Backlog"
},
{
"title": "Assigned to:",
"value": "Matt Hidinger"
},
{
"title": "Due date:",
"value": "Not set"
}
]
}
]
}
],
"actions": [
{
"type": "Action.ShowCard",
"title": "Comment",
"card": {
"type": "AdaptiveCard",
"body": [
{
"type": "Input.Text",
"id": "comment",
"isMultiline": true,
"placeholder": "Enter your comment"
}
],
"actions": [
{
"type": "Action.Submit",
"title": "OK"
}
]
}
},
{
"type": "Action.OpenUrl",
"title": "View",
"url": "https://adaptivecards.io"
}
]
}
Результирующая карточка содержит заголовок, сведения о пользователе, создавшем карточку (имя и аватар), время создания карточки, описание назначения задания и сведения, связанные с назначением. Есть также кнопки, которые можно щелкнуть, чтобы закомментировать задание работы или просмотреть его:
