Добавление полнофункционированных карта вложений в сообщения с помощью API bot Connector

Статья
03/08/2023

Некоторые каналы позволяют боту отправлять пользователям расширенные карточки . Многофункциональный карта — это вложение, содержащее интерактивные элементы, такие как кнопки, текст, изображения, звук, видео и т. д.

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

Типы функциональных карточек

Форматированная карточка содержит название, описание, ссылку и изображения. Сообщение может содержать несколько форматированных карточек, которые отображаются в виде списка или карусели. Сейчас 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"
    }
  ]
}

Результирующая карточка содержит заголовок, сведения о пользователе, создавшем карточку (имя и аватар), время создания карточки, описание назначения задания и сведения, связанные с назначением. Существуют также кнопки, которые можно нажать, чтобы закомментировать задание или просмотреть его:

Пример напоминания календаря в виде адаптивной карточки.

Добавление полнофункционированных карта вложений в сообщения с помощью API bot Connector

Типы функциональных карточек

Обработка событий в форматированных карточках

Добавление имиджевой карточки в сообщение

Добавление адаптивной карточки в сообщение

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

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