Bot Connector API를 사용 하 여 메시지에 리치 카드 첨부 파일 추가Adding rich card attachments to messages with the Bot Connector API

일부 채널에서는 봇에서 사용자에 게 다양 한 카드 를 보낼 수 있습니다.Some channels allow your bot to send rich cards to users. 리치 카드는 단추, 텍스트, 이미지, 오디오, 비디오 등과 같은 대화형 요소를 포함 하는 첨부 파일입니다.A rich card is an attachment that contains interactive elements, such as buttons, text, images, audio, video, and so on.

이 문서에서는 메시지에 첨부할 수 있는 리치 카드를 만드는 방법을 설명 합니다.This article describes how to create rich cards that you can attachment to a message. 메시지에 첨부 파일을 추가 하는 방법에 대 한 특정 지침은 메시지에 미디어 첨부 파일을 추가 하는 방법을 참조 하세요.See how to add media attachments to messages for specific instructions on adding an attachment to a message.

서식 있는 카드 형식Types of rich cards

서식 있는 카드는 제목, 설명, 링크 및 이미지로 구성됩니다.A rich card comprises a title, description, link, and images. 메시지에는 목록 형식 또는 회전식 형식으로 표시되는 여러 서식 있는 카드가 포함될 수 있습니다.A message can contain multiple rich cards, displayed in either list format or carousel format. Bot Framework는 현재 8가지 형식의 서식 있는 카드를 지원합니다.The Bot Framework currently supports eight types of rich cards:

카드 형식Card type DescriptionDescription
AdaptiveCardAdaptiveCard 텍스트, 음성, 이미지, 단추 및 입력 필드의 조합을 포함할 수 있는 사용자 지정 가능한 카드입니다.A customizable card that can contain any combination of text, speech, images, buttons, and input fields. 채널별 지원을 참조하세요.See per-channel support.
AnimationCardAnimationCard 애니메이션 GIF 또는 짧은 비디오를 재생할 수 있는 카드입니다.A card that can play animated GIFs or short videos.
AudioCardAudioCard 오디오 파일을 재생할 수 있는 카드입니다.A card that can play an audio file.
HeroCardHeroCard 일반적으로 하나의 큰 이미지, 하나 이상의 단추 및 텍스트를 포함하는 카드입니다.A card that typically contains a single large image, one or more buttons, and text.
ThumbnailCardThumbnailCard 일반적으로 하나의 썸네일 이미지, 하나 이상의 단추 및 텍스트를 포함하는 카드입니다.A card that typically contains a single thumbnail image, one or more buttons, and text.
ReceiptCardReceiptCard 봇이 사용자에게 수신 확인을 제공할 수 있는 카드입니다.A card that enables a bot to provide a receipt to the user. 일반적으로 수신 확인, 세금 및 합계 정보에 포함할 항목 목록과 기타 텍스트를 포함합니다.It typically contains the list of items to include on the receipt, tax and total information, and other text.
SignInCardSignInCard 봇이 사용자 로그인을 요청하는 데 사용되는 카드입니다.A card that enables a bot to request that a user sign-in. 일반적으로 사용자가 로그인 프로세스를 시작하기 위해 클릭할 수 있는 하나 이상의 단추와 텍스트를 포함합니다.It typically contains text and one or more buttons that the user can click to initiate the sign-in process.
VideoCardVideoCard 비디오를 재생할 수 있는 카드입니다.A card that can play videos.

각 채널에서 지원되는 기능을 설명하는 표는 채널 참조 문서를 참조하세요.For tables describing which features are supported on each channel, see the channels reference article.

서식 있는 카드 내에서 이벤트 처리Process events within rich cards

서식 있는 카드 내에서 이벤트를 처리하려면 CardAction 개체를 사용하여 사용자가 단추를 클릭하거나 카드의 섹션을 탭할 때 수행되어야 하는 작업을 지정합니다.To process events within rich cards, use CardAction objects to specify what should happen when the user clicks a button or taps a section of the card. CardAction 개체는 다음 속성을 포함합니다.Each CardAction object contains these properties:

속성Property TypeType DescriptionDescription
channelDatachannelData 문자열string 이 작업과 연결된 채널 관련 데이터입니다.channel-specific data associated with this action
displayTextdisplayText 문자열string 단추를 클릭하면 대화 피드에 표시할 테스트입니다.test to display in the chat feed if the button is clicked
texttext 문자열string 작업에 대한 텍스트입니다.text for the action
typetype 문자열string 작업 형식(아래 표에 지정된 값 중 하나)type of action (one of the values specified in the table below)
titletitle 문자열string 단추 제목title of the button
이미지image 문자열string 단추의 이미지 URLimage URL for the button
value 문자열string 지정된 형식의 작업을 수행하는 데 필요한 값value needed to perform the specified type of action

참고

적응형 카드 내의 단추를 만들 때는 CardAction 개체를 사용하는 대신, 적응형 카드에서 정의한 스키마를 사용합니다.Buttons within Adaptive Cards are not created using CardAction objects, but instead using the schema that is defined by Adaptive Cards. 적응형 카드에 단추를 추가하는 방법을 보여 주는 예제는 메시지에 적응형 카드 추가를 참조하세요.See Add an Adaptive Card to a message for an example that shows how to add buttons to an Adaptive Card.

제대로 작동 하려면 주인공 카드의 클릭 가능한 각 항목에 작업 유형을 할당 합니다.To function correctly, assign an action type to each clickable item on a hero card. 이 표에는 사용 가능한 동작 유형 및 관련 값 속성에 필요한 항목과 관련 설명이 나와 있습니다.This table lists and describes the available action types and what should be in the associated value property. messageBack카드 작업은 다른 카드 작업 보다 일반화 된 의미를 가집니다.The messageBack card action has a more generalized meaning than the other card actions. 및 기타 카드 작업 유형에 대 한 자세한 내용은 활동 스키마카드 작업 섹션을 참조 하세요 messageBack .See the Card action section of the Activity schema for more information about the messageBack and other card action types.

형식Type 설명Description Value
callcall 전화 통화를 시작합니다.Initiates a phone call. 전화 통화 대상입니다(tel:123123123123 형식).Destination for the phone call in this format: tel:123123123123.
downloadFiledownloadFile 파일을 다운로드합니다.Downloads a file. 다운로드할 파일의 URL입니다.The URL of the file to download.
imBackimBack 봇에 메시지를 보내고 채팅에 표시 가능한 응답을 게시합니다.Sends a message to the bot, and posts a visible response in the chat. 보낼 메시지의 텍스트입니다.Text of the message to send.
messageBackmessageBack 채팅 시스템을 통해 보낼 텍스트 응답을 나타냅니다.Represents a text response to be sent via the chat system. 생성 된 메시지에 포함할 선택적 프로그래밍 값입니다.An optional programmatic value to include in generated messages.
openUrlopenUrl 기본 제공 브라우저에서 URL이 열립니다.Opens a URL in the built-in browser. 열려는 URL입니다.The URL to open.
playAudioplayAudio 오디오를 재생합니다.Plays audio. 재생할 오디오의 URL입니다.The URL of the audio to play.
playVideoplayVideo 비디오를 재생합니다.Plays a video. 재생할 비디오의 URL입니다.The URL of video to play.
postBackpostBack 봇에 메시지를 보내고 채팅에 표시 가능한 응답을 게시하지 않을 수 있습니다.Sends a message to the bot, and may not post a visible response in the chat. 보낼 메시지의 텍스트입니다.Text of the message to send.
showImageshowImage 이미지를 표시합니다.Displays an image. 표시할 이미지의 URL입니다.The URL of the image to display.
signinsignin OAuth 로그인 프로세스를 시작 합니다.Initiates an OAuth sign-in process. 시작할 OAuth 흐름의 URL입니다.The URL of the OAuth flow to initiate.

메시지에 영웅 카드 추가Add a Hero card to a message

메시지에 리치 카드 첨부 파일을 추가 하려면 다음을 수행 합니다.To add a rich card attachment to a message:

  1. 메시지에 추가 하려는 카드의 유형을 나타내는 개체를 만듭니다.Create an object that represents the type of card that you want to add to the message.
  2. [첨부 파일][] 개체를 만듭니다.Create an Attachment object:
    • 해당 contentType 속성을 카드의 미디어 유형으로 설정 합니다.Set its contentType property to the card's media type.
    • 해당 속성을 만든 개체로 설정 하 여 content 카드를 나타냅니다.Set its content property to the object you created to represent the card.
  3. Attachment메시지의 배열에 개체를 추가 attachments 합니다.Add the Attachment object to the attachments array of the message.

서식 있는 카드 첨부 파일을 포함하는 메시지는 일반적으로 text를 지정하지 않습니다.Messages that contain rich card attachments typically do not specify text.

일부 채널을 사용하면 메시지 내의 attachments 배열에 여러 서식 있는 카드를 추가할 수 있습니다.Some channels allow you to add multiple rich cards to the attachments array within a message. 사용자에게 여러 옵션을 제공하려는 시나리오에서는 이 기능이 유용할 수 있습니다.This capability can be useful in scenarios where you want to provide the user with multiple options. 예를 들어, 사용자가 봇을 통해 호텔 객실을 예약할 수 있는 경우 봇은 예약 가능한 객실 유형을 보여 주는 서식 있는 카드 목록을 사용자에게 제공합니다.For example, if your bot lets users book hotel rooms, it could present the user with a list of rich cards that shows the types of available rooms. 각 카드는 객실 유형에 해당하는 편의 시설의 그림 및 목록을 포함할 수 있고 사용자는 카드를 탭하거나 단추를 클릭하여 객실 유형을 선택할 수 있습니다.Each card could contain a picture and list of amenities corresponding to the room type and the user could select a room type by tapping a card or clicking a button.

여러 서식 있는 카드를 목록 형식으로 표시하려면 Activity 개체의 attachmentLayout 속성을 “list”로 설정합니다.To display multiple rich cards in list format, set the Activity object's attachmentLayout property to "list". 여러 서식 있는 카드를 회전식 형식으로 표시하려면 Activity 개체의 attachmentLayout 속성을 “carousel”로 설정합니다.To display multiple rich cards in carousel format, set the Activity object's attachmentLayout property to "carousel". 채널이 회전식 형식을 지원하지 않으면 attachmentLayout 속성을 “carousel”로 지정된 경우에도 서식 있는 카드가 목록 형식으로 표시됩니다.If the channel does not support carousel format, it will display the rich cards in list format, even if the attachmentLayout property specifies "carousel".

다음 예에서는 단일 주인공 카드 첨부 파일이 포함 된 전체 메시지를 보여 줍니다.The following example shows a complete message that contains a single Hero card attachment. 이 예제 요청에서 https://smba.trafficmanager.net/apis는 기본 URI를 나타냅니다. 봇이 실행하는 요청의 기본 URI는 다를 수 있습니다.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. 기본 URI를 설정하는 방법에 대한 자세한 내용은 API 참조를 참조하세요.For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/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"
}

메시지에 적응형 카드 추가Add an Adaptive card to a message

적응형 카드는 텍스트, 음성, 이미지, 단추 및 입력 필드의 모든 조합을 포함할 수 있습니다.The Adaptive Card can contain any combination of text, speech, images, buttons, and input fields. 적응형 카드는 적응형 카드에 지정된 JSON 형식을 사용하여 생성되며, 카드 콘텐츠 및 형식에 대한 모든 권한을 제공합니다.Adaptive Cards are created using the JSON format specified in Adaptive Cards, which gives you full control over card content and format.

적응형 카드 사이트 내의 정보를 이용하여 적응형 카드 스키마를 이해하고, 적응형 카드 요소를 살펴보고, 다양한 컴퍼지션 및 복잡성이 포함된 카드를 만드는 데 사용할 수 있는 JSON 샘플을 확인합니다.Leverage the information within the Adaptive Cards site to understand Adaptive Card schema, explore Adaptive Card elements, and see JSON samples that can be used to create cards of varying composition and complexity. 또한, 대화형 시각화 도우미를 사용하여 적응형 카드 페이로드를 설계하고 카드 출력을 미리 볼 수 있습니다.Additionally, you can use the Interactive Visualizer to design Adaptive Card payloads and preview card output.

다음 예에서는 작업 할당을 나타내는 단일 적응 카드 첨부 개체를 보여 줍니다.The following example shows a single Adaptive Card attachment object, representing a work assignment. 이를 사용자에 게 보내려면 메시지에 첨부 파일로 추가 해야 합니다.To send this to a user, you would need to add it as an attachment in a message.

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

결과 카드에는 제목, 카드를 만든 사람에 대한 정보(이름 및 아바타), 카드를 만든 시간, 작업 할당에 대한 설명 및 할당과 관련된 정보가 포함됩니다.The resulting card contains a title, information about who created the card (their name and avatar), when the card was created, a description of the work assignments, and information related to the assignment. 작업 할당에 대한 주석이나 보기를 클릭할 수 있는 단추도 있습니다.There are also buttons which can be clicked to either comment on the work assignment or view it:

적응형 카드 일정 미리 알림

추가 리소스Additional resources