Добавление полнофункционированных карта вложений в сообщения с помощью API bot Connector
Некоторые каналы позволяют боту отправлять пользователям расширенные карточки . Многофункциональный карта — это вложение, содержащее интерактивные элементы, такие как кнопки, текст, изображения, звук, видео и т. д.
В этой статье описывается создание расширенных карточек, которые можно вложить в сообщение. Инструкции по добавлению вложения в сообщение см. в статье Добавление вложения мультимедиа в сообщения.
Типы функциональных карточек
Форматированная карточка содержит название, описание, ссылку и изображения. Сообщение может содержать несколько форматированных карточек, которые отображаются в виде списка или карусели. Сейчас Bot Framework поддерживает восемь типов форматированных карточек.
Тип карточки | Описание |
---|---|
AdaptiveCard | Настраиваемая карточка, которая может содержать любое сочетание текста, речи, изображений, кнопок и полей для ввода. См. описание поддержки для каждого канала. |
AnimationCard | Карточка, которая может воспроизводить GIF-файлы с анимацией или короткие видеоролики. |
AudioCard | Карточка, которая может воспроизводить звуковой файл. |
HeroCard; | Карточка, которая обычно содержит одно большое изображение, одну или несколько кнопок и текст. |
ThumbnailCard. | Карточка, которая обычно содержит один эскиз, одну или несколько кнопок и текст. |
ReceiptCard; | Карточка, с помощью которой бот выдает квитанцию пользователю. Обычно она содержит список элементов, включаемых в квитанцию, налог, а также общую информацию и другой текст. |
SignInCard | Карточка, в которой бот запрашивает вход пользователя. Обычно она содержит текст и одну или несколько кнопок, которые можно нажать, чтобы начать процесс входа. |
VideoCard | Карточка, которая может воспроизводить видео. |
Совет
Сведения о том, какие функции поддерживаются в каждом канале, см. в справочной статье о каналах .
Обработка событий в форматированных карточках
Для обработки событий в форматированных карточках используйте объекты CardAction, чтобы указать, что должно происходить, когда пользователь нажимает кнопку или касается сегмента карточки. Каждый объект CardAction
содержит следующие свойства.
Свойство | Тип | Описание |
---|---|---|
channelData | строка | Относящиеся к каналу данные, связанные с этим действием. |
displayText | строка | Текст, отображаемый в канале чата при нажатии кнопки. |
text | строка | Текст для действия. |
type | строка | тип действия (одно из значений, указанных в таблице ниже) |
title | строка | название кнопки |
Изображение | строка | URL-адрес изображения для кнопки |
value | строка | значение, необходимое для выполнения указанного типа действия |
Примечание
Для создания кнопок в адаптивных карточках используются не объекты CardAction
, а схема, которая определяется адаптивными карточками.
О том, как добавить кнопку в адаптивную карточку, см. в разделе Добавление адаптивной карточки в сообщение.
Чтобы правильно функционировать, назначьте тип действия каждому элементу, который можно щелкнуть в карта. В этой таблице перечислены и описаны доступные типы действий и требуемый формат для связанного свойства.
Действие messageBack
карта имеет более обобщенное значение, чем другие действия карта. Дополнительные сведения о messageBack
и других типах действий карта см. в разделе Действие карточкисхемы действия.
Тип | Описание | Значение |
---|---|---|
вызывает | Инициирует телефонный звонок. | Целевое назначение телефонного звонка в следующем формате: tel:123123123123 . |
downloadFile | Скачивает файл. | URL-адрес для скачивания файла. |
imBack | Отправляет боту сообщение и отображает полученный ответ в чате. | Текст отправляемого сообщения. |
messageBack | Представляет текстовый ответ, отправляемый через систему чата. | Необязательное программное значение для включения в созданные сообщения. |
openUrl | Открывает URL-адрес в окне встроенного браузера. | URL-адрес, который нужно открыть. |
playAudio | Воспроизводит звук. | URL-адрес для воспроизведения звука. |
playVideo | Воспроизводит видео. | URL-адрес для воспроизведения видео. |
postBack | Отправляет боту сообщение, но не всегда отображает полученный ответ в чате. | Текст отправляемого сообщения. |
showImage | Отображает изображение. | URL-адрес для отображения изображения. |
signin | Инициирует процесс входа OAuth. | URL-адрес потока OAuth, который нужно запустить. |
Добавление имиджевой карточки в сообщение
Чтобы добавить в сообщение многофункциональное вложение карта, выполните следующее:
- Создайте объект , представляющий тип карта, который требуется добавить в сообщение.
- Создайте объект Attachment :
- Присвойте свойству
contentType
тип мультимедиа карта. - Присвойте свойству
content
значение объекта , созданного для представления карта.
- Присвойте свойству
Attachment
Добавьте объект вattachments
массив сообщения.
Совет
Сообщения, содержащие полнофункционированные карта вложения, обычно не указывают text
.
На некоторых каналах можно добавлять несколько форматированных карточек в массив attachments
сообщения. Это может быть полезно в сценариях, где необходимо предоставить пользователю несколько параметров. Например, если бот позволяет пользователям забронировать номера в гостинице, то он может предоставить список форматированных карточек, в которых будут показаны типы доступных номеров. Каждая карточка может содержать изображение и список удобств, соответствующих типу комнаты, а пользователь может выбрать тип комнаты, нажав на кнопку или щелкнув карточку.
Совет
Чтобы отобразить несколько форматированных карточек в виде списка, задайте свойству attachmentLayout
объекта Действие значение list.
Чтобы отобразить несколько форматированных карточек в виде карусели, задайте свойству attachmentLayout
объекта Activity
значение carousel.
Если канал не поддерживает формат карусели, он будет отображать расширенные карточки в формате списка, даже если свойство attachmentLayout
указывает "карусель".
В следующем примере показано полное сообщение, содержащее одно вложение карта hero. В этом примере запрос 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"
}
]
}
Результирующая карточка содержит заголовок, сведения о пользователе, создавшем карточку (имя и аватар), время создания карточки, описание назначения задания и сведения, связанные с назначением. Существуют также кнопки, которые можно нажать, чтобы закомментировать задание или просмотреть его: