채널 관련 기능 구현Implement channel-specific functionality

적용 대상: SDK v4APPLIES TO: SDK v4

일부 채널은 메시지 텍스트 및 첨부 파일만으로는 구현할 수 없는 기능을 제공합니다.Some channels provide features that cannot be implemented by using only message text and attachments. 채널 관련 기능을 구현하려면 활동 개체의 채널 데이터 속성에서 채널에 네이티브 메타데이터를 전달할 수 있습니다.To implement channel-specific functionality, you can pass native metadata to a channel in the activity object's channel data property. 예를 들어, 봇은 채널 데이터 속성을 사용하여 Telegram에 스티커를 전송하도록 지시하거나 Office365에 이메일을 전송하도록 지시할 수 있습니다.For example, your bot can use the channel data property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

이 문서에서는 메시지 작업의 채널 데이터 속성을 사용하여 다음과 같은 채널 관련 기능을 구현하는 방법을 설명합니다.This article describes how to use a message activity's channel data property to implement this channel-specific functionality:

채널Channel 기능Functionality
EmailEmail 본문, 제목 및 중요 메타데이터를 포함하는 이메일 보내기 및 받기Send and receive an email that contains body, subject, and importance metadata
SlackSlack 완전히 신뢰할 수 있는 Slack 메시지 보내기Send full fidelity Slack messages
FacebookFacebook 고유하게 Facebook 알림 보내기Send Facebook notifications natively
TelegramTelegram 음성 메모 또는 스티커 공유와 같은 Telegram 관련 작업 수행Perform Telegram-specific actions, such as sharing a voice memo or a sticker
KikKik 네이티브 Kik 메시지 보내기 및 받기Send and receive native Kik messages

참고

활동 개체의 채널 데이터 속성 값은 JSON 개체입니다.The value of an activity object's channel data property is a JSON object. 따라서 이 문서의 예제에서는 다양한 시나리오에서 예상되는 channelData JSON 속성의 형식을 보여줍니다.Therefore, the examples in this article show the expected format of the channelData JSON property in various scenarios. .NET을 사용하여 JSON 개체를 만들려면 JObject(.NET) 클래스를 사용합니다.To create a JSON object using .NET, use the JObject (.NET) class.

사용자 지정 이메일 메시지 만들기Create a custom Email message

사용자 지정 전자 메일 메시지를 만들려면 작업 속성을 channelData 다음 속성을 포함 하는 JSON 개체로 설정 합니다.To create a custom email message, set the activity channelData property to a JSON object that contains the following properties:

속성Property DescriptionDescription
bccRecipientsbccRecipients 메시지의 Bcc(숨은 참조) 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.
ccRecipientsccRecipients 메시지의 Cc(참조) 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
htmlBodyhtmlBody 이메일 메시지의 본문을 지정하는 HTML 문서입니다.An HTML document that specifies the body of the email message. 지원되는 HTML 요소 및 특성에 대한 정보는 채널의 설명서를 참조하세요.See the channel's documentation for information about supported HTML elements and attributes.
importanceimportance 이메일의 중요도 수준입니다.The email's importance level. 유효한 값은 높음, 기본낮음 입니다.Valid values are high, normal, and low. 기본값은 기본 입니다.The default value is normal.
subjectsubject 이메일의 제목입니다.The email's subject. 필드 요구 사항에 대한 정보는 채널의 설명서를 참조하세요.See the channel's documentation for information about field requirements.
toRecipientstoRecipients 메시지의 받는 사람 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's To field.

사용자와 봇 사이에 나가는 메시지와 들어오는 메시지에는 channelData 위의 표에 지정 된 속성이 있는 JSON 개체를 포함 하는 작업이 있을 수 있습니다.The outgoing and incoming messages between the user and the bot may have a channelData activity that contains a JSON object whose properties are specified in the previous table. 아래 코드 조각은 channelData 봇에서 사용자에 들어오는 사용자 지정 전자 메일 메시지에 대 한 속성의 예를 보여 줍니다.The snippet below shows an example of the channelData property for an incoming custom email message, from the bot to the user.

속성Property DescriptionDescription
htmlBodyhtmlBody 메시지의 본문에 사용할 HTML입니다.The HTML to use for the body of the message.
subjectsubject 메시지에 사용할 제목입니다.The subject to use for the message.
importanceimportance 메시지에 사용할 중요도 플래그로, low, normal 또는 high입니다.The importance flag to use for the message: low, normal, or high.
toRecipientstoRecipients 메시지의 받는 사람 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's To field.
ccRecipientsccRecipients 메시지의 Cc(참조) 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
bccRecipientsbccRecipients 메시지의 Bcc(숨은 참조) 필드에 추가할 세미콜론(;)으로 구분된 이메일 주소 문자열입니다.A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.

완전히 신뢰할 수 있는 Slack 메시지 만들기Create a full-fidelity Slack message

완전히 신뢰할 수 있는 Slack 메시지를 만들려면 활동 개체의 채널 데이터 속성을 Slack 메시지, Slack 첨부 파일 및/또는 Slack 단추를 지정하는 JSON 개체로 설정합니다.To create a full-fidelity Slack message, set the activity object's channel data property to a JSON object that specifies Slack messages, Slack attachments, and/or Slack buttons.

참고

설정 단추에서 Slack 메시지를 지원 해야 합니다 대화형 메시지 때 있습니다 봇을 연결 Slack 채널에 있습니다.To support buttons in Slack messages, you must enable Interactive Messages when you connect your bot to the Slack channel.

이 코드 조각은 사용자 지정 Slack 메시지에 대한 channelData 속성의 예제를 보여 줍니다.This snippet shows an example of the channelData property for a custom Slack message.

"channelData": {
   "text": "Now back in stock! :tada:",
   "attachments": [
        {
            "title": "The Further Adventures of Slackbot",
            "author_name": "Stanford S. Strickland",
            "author_icon": "https://api.slack.com/img/api/homepage_custom_integrations-2x.png",
            "image_url": "http://i.imgur.com/OJkaVOI.jpg?1"
        },
        {
            "fields": [
                {
                    "title": "Volume",
                    "value": "1",
                    "short": true
                },
                {
                    "title": "Issue",
                    "value": "3",
                    "short": true
                }
            ]
        },
        {
            "title": "Synopsis",
            "text": "After @episod pushed exciting changes to a devious new branch back in Issue 1, Slackbot notifies @don about an unexpected deploy..."
        },
        {
            "fallback": "Would you recommend it to customers?",
            "title": "Would you recommend it to customers?",
            "callback_id": "comic_1234_xyz",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "recommend",
                    "text": "Recommend",
                    "type": "button",
                    "value": "recommend"
                },
                {
                    "name": "no",
                    "text": "No",
                    "type": "button",
                    "value": "bad"
                }
            ]
        }
    ]
}

사용자가 Slack 메시지 내의 단추를 클릭하면 봇은 채널 데이터 속성이 payload JSON 개체로 채워진 응답 메시지를 받게 됩니다.When a user clicks a button within a Slack message, your bot will receive a response message in which the channel data property is populated with a payload JSON object. payload 개체는 원본 메시지의 콘텐츠를 지정하고, 클릭된 단추를 식별하고, 단추를 클릭한 사용자를 식별합니다.The payload object specifies contents of the original message, identifies the button that was clicked, and identifies the user who clicked the button.

이 코드 조각은 사용자가 Slack 메시지에서 단추를 클릭할 때 봇에서 수신하는 메시지에서 channelData 속성의 예제를 보여줍니다.This snippet shows an example of the channelData property in the message that a bot receives when a user clicks a button in the Slack message.

"channelData": {
    "payload": {
        "actions": [
            {
                "name": "recommend",
                "value": "yes"
            }
        ],
        . . .
        "original_message": "{…}",
        "response_url": "https://hooks.slack.com/actions/..."
    }
}

봇은 일반적인 방식으로 이 메시지에 응답하거나 payload 개체의 response_url 속성으로 지정된 엔드포인트에 해당 응답을 직접 게시할 수 있습니다.Your bot can reply to this message in the normal manner, or it can post its response directly to the endpoint that is specified by the payload object's response_url property. response_url에 응답을 게시하는 시기 및 방법에 대한 정보는 Slack 단추를 참조하세요.For information about when and how to post a response to the response_url, see Slack Buttons.

다음 JSON을 사용하여 동적 단추를 만들 수 있습니다.You can create dynamic buttons using the following JSON.

{
    "text": "Would you like to play a game ? ",
    "attachments": [
        {
            "text": "Choose a game to play!",
            "fallback": "You are unable to choose a game",
            "callback_id": "wopr_game",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "actions": [
                {
                    "name": "game",
                    "text": "Chess",
                    "type": "button",
                    "value": "chess"
                },
                {
                    "name": "game",
                    "text": "Falken's Maze",
                    "type": "button",
                    "value": "maze"
                },
                {
                    "name": "game",
                    "text": "Thermonuclear War",
                    "style": "danger",
                    "type": "button",
                    "value": "war",
                    "confirm": {
                        "title": "Are you sure?",
                        "text": "Wouldn't you prefer a good game of chess?",
                        "ok_text": "Yes",
                        "dismiss_text": "No"
                    }
                }
            ]
        }
    ]
}

대화형 메뉴를 만들려면 다음 JSON을 사용합니다.To create interactive menus, use the following JSON:

{
    "text": "Would you like to play a game ? ",
    "response_type": "in_channel",
    "attachments": [
        {
            "text": "Choose a game to play",
            "fallback": "If you could read this message, you'd be choosing something fun to do right now.",
            "color": "#3AA3E3",
            "attachment_type": "default",
            "callback_id": "game_selection",
            "actions": [
                {
                    "name": "games_list",
                    "text": "Pick a game...",
                    "type": "select",
                    "options": [
                        {
                            "text": "Hearts",
                            "value": "menu_id_hearts"
                        },
                        {
                            "text": "Bridge",
                            "value": "menu_id_bridge"
                        },
                        {
                            "text": "Checkers",
                            "value": "menu_id_checkers"
                        },
                        {
                            "text": "Chess",
                            "value": "menu_id_chess"
                        },
                        {
                            "text": "Poker",
                            "value": "menu_id_poker"
                        },
                        {
                            "text": "Falken's Maze",
                            "value": "menu_id_maze"
                        },
                        {
                            "text": "Global Thermonuclear War",
                            "value": "menu_id_war"
                        }
                    ]
                }
            ]
        }
    ]
}

Facebook 알림 만들기Create a Facebook notification

Facebook 알림을 만들려면 활동 개체의 채널 데이터 속성을 이러한 속성을 지정하는 JSON 개체로 설정합니다.To create a Facebook notification, set the activity object's channel data property to a JSON object that specifies these properties:

속성Property DescriptionDescription
notification_typenotification_type 알림 유형(예: REGULAR, SILENT_PUSH, NO_PUSH)The type of notification (e.g., REGULAR, SILENT_PUSH, NO_PUSH).
attachmentattachment 이미지, 비디오 또는 다른 멀티미디어 형식을 지정하는 첨부 파일 또는 영수증과 같은 템플릿 기반 첨부 파일입니다.An attachment that specifies an image, video, or other multimedia type, or a templated attachment such as a receipt.

참고

notification_type 속성 및 attachment 속성의 형식 및 콘텐츠에 대한 자세한 내용은 Facebook API 설명서를 참조하세요.For details about format and contents of the notification_type property and attachment property, see the Facebook API documentation.

이 코드 조각은 Facebook 영수증 첨부 파일에 대한 channelData 속성의 예제를 보여 줍니다.This snippet shows an example of the channelData property for a Facebook receipt attachment.

"channelData": {
    "notification_type": "NO_PUSH",
    "attachment": {
        "type": "template"
        "payload": {
            "template_type": "receipt",
            . . .
        }
    }
}

Telegram 메시지 만들기Create a Telegram message

음성 메모 또는 스티커 공유와 같은 Telegram 관련 작업을 구현하는 메시지를 만들려면 활동 개체의 채널 데이터 속성을 이러한 속성을 지정하는 JSON 개체로 설정합니다.To create a message that implements Telegram-specific actions, such as sharing a voice memo or a sticker, set the activity object's channel data property to a JSON object that specifies these properties:

속성Property DescriptionDescription
methodmethod 호출할 Telegram Bot API 메서드입니다.The Telegram Bot API method to call.
매개 변수parameters 지정된 메서드의 매개 변수입니다.The parameters of the specified method.

다음과 같은 Telegram 메서드가 지원됩니다.These Telegram methods are supported:

  • answerInlineQueryanswerInlineQuery
  • editMessageCaptioneditMessageCaption
  • editMessageReplyMarkupeditMessageReplyMarkup
  • editMessageTexteditMessageText
  • forwardMessageforwardMessage
  • kickChatMemberkickChatMember
  • sendAudiosendAudio
  • sendChatActionsendChatAction
  • sendContactsendContact
  • sendDocumentsendDocument
  • sendLocationsendLocation
  • sendMessagesendMessage
  • sendPhotosendPhoto
  • sendStickersendSticker
  • sendVenuesendVenue
  • sendVideosendVideo
  • sendVoicesendVoice
  • unbanChateMemberunbanChateMember

이러한 Telegram 메서드 및 해당 매개 변수에 대한 자세한 내용은 Telegram Bot API 설명서를 참조하세요.For details about these Telegram methods and their parameters, see the Telegram Bot API documentation.

참고

  • chat_id 매개 변수는 모든 Telegram 메서드에 공통적입니다.The chat_id parameter is common to all Telegram methods. 매개 변수로 chat_id를 지정하지 않는 경우 프레임워크는 ID를 제공합니다.If you do not specify chat_id as a parameter, the framework will provide the ID for you.
  • 파일 콘텐츠 인라인을 전달하는 대신 아래 예제에서와 같이 URL 및 미디어 형식을 사용하여 파일을 지정합니다.Instead of passing file contents inline, specify the file using a URL and media type as shown in the example below.
  • 봇이 Telegram 채널에서 받는 각 메시지 내에서 ChannelData 속성은 봇이 이전에 전송한 메시지를 포함합니다.Within each message that your bot receives from the Telegram channel, the ChannelData property will include the message that your bot sent previously.

이 코드 조각은 단일 Telegram 메서드를 지정하는 channelData 속성의 예제를 보여 줍니다.This snippet shows an example of a channelData property that specifies a single Telegram method.

"channelData": {
    "method": "sendSticker",
    "parameters": {
        "sticker": {
            "url": "https://domain.com/path/gif",
            "mediaType": "image/gif",
        }
    }
}

이 코드 조각은 Telegram 메서드의 배열을 지정하는 channelData 속성의 예제를 보여줍니다.This snippet shows an example of a channelData property that specifies an array of Telegram methods.

"channelData": [
    {
        "method": "sendSticker",
        "parameters": {
            "sticker": {
                "url": "https://domain.com/path/gif",
                "mediaType": "image/gif",
            }
        }
    },
    {
        "method": "sendMessage",
        "parameters": {
            "text": "<b>This message is HTML formatted.</b>",
            "parse_mode": "HTML"
        }
    }
]

Telegram 메서드가 구현되면 채널 데이터 속성이 JSON 개체로 채워진 응답 메시지가 봇에 표시됩니다.When a Telegram method is implemented, your bot will receive a response message in which the channel data property is populated with a JSON object. 이 응답 개체는 update_id 및 최대 하나의 선택적 매개 변수를 포함하여 원본 메시지의 내용을 지정합니다.This response object specifies the contents of the original message, including an update_id and, at most, one optional parameter. 들어오는 응답을 받는 방법에 대한 자세한 내용은 업데이트 가져오기를 참조하세요.For information about receiving incoming responses, see Getting updates.

다음 코드 조각에서는 설문 조사가 만들어질 때 봇에서 받는 메시지의 channelData 속성에 대한 예제를 보여 줍니다.This snippet shows an example of the channelData property in the message that a bot receives when a poll is created.

"channelData": {
    "update_id": 43517575,
    "message": {
        "message_id": 618,
        "from": {
            "id": 803613355,
            "is_bot": false,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "language_code": "en"
        },
        "chat": {
            "id": 803613355,
            "first_name": "Joe",
            "last_name": "Doe",
            "username": "jdoe",
            "type": "private"
        },
        "date": 1582577834,
        "poll": {
        "id": "5089525250643722242",
        "question": "How to win?",
        "options": [
            {
                "text": "Be the best",
                "voter_count": 0
            },
            {
                "text": "Help those in need",
                "voter_count": 0
            },
            {
                "text": "All of the above",
                "voter_count": 0
            }
        ],
        "total_voter_count": 0,
        "is_closed": false,
        "is_anonymous": true,
        "type": "regular",
        "allows_multiple_answers": false
        }
    }
}

네이티브 Kik 메시지 만들기Create a native Kik message

네이티브 Kik 메시지를 만들려면 활동 개체의 채널 데이터 속성을 이 속성을 지정하는 JSON 개체로 설정합니다.To create a native Kik message, set the activity object's channel data property to a JSON object that specifies this property:

속성Property DescriptionDescription
messagesmessages Kik 메시지의 배열입니다.An array of Kik messages. Kik 메시지 형식에 대한 자세한 내용은 Kik 메시지 형식을 참조하세요.For details about Kik message format, see Kik Message Formats.

이 코드 조각은 네이티브 Kik 메시지에 대한 channelData 속성의 예제를 보여 줍니다.This snippet shows an example of the channelData property for a native Kik message.

"channelData": {
    "messages": [
        {
            "chatId": "c6dd8165…",
            "type": "link",
            "to": "kikhandle",
            "title": "My Webpage",
            "text": "Some text to display",
            "url": "http://botframework.com",
            "picUrl": "http://lorempixel.com/400/200/",
            "attribution": {
                "name": "My App",
                "iconUrl": "http://lorempixel.com/50/50/"
            },
            "noForward": true,
            "kikJsData": {
                    "key": "value"
                }
        }
    ]
}

LINE 메시지 만들기Create a LINE message

LINE 관련 메시지 유형(예: 스티커, 템플릿 또는 휴대폰 카메라 열기 같은 LINE 관련 작업 유형)을 구현하는 메시지를 만들려면 활동 개체의 채널 데이터 속성을 LINE 메시지 유형 및 작업 유형을 지정하는 JSON 개체로 설정하세요.To create a message that implements LINE-specific message types (such as sticker, templates, or LINE specific action types like opening the phone camera), set the activity object's channel data property to a JSON object that specifies LINE message types and action types.

속성Property DescriptionDescription
typetype LINE 작업/메시지 유형 이름The LINE action/message type name

다음과 같은 LINE 메시지 유형이 지원됩니다.These LINE message types are supported:

  • 스티커Sticker
  • 이미지맵Imagemap
  • 템플릿(단추, 확인, 회전식)Template (Button, confirm, carousel)
  • FlexFlex

이러한 LINE 작업은 메시지 유형 JSON 개체의 작업 필드에 지정할 수 있습니다.These LINE actions can be specified in the action field of the message type JSON object:

  • 포스트백Postback
  • 메시지Message
  • URIURI
  • DatetimerpickerDatetimerpicker
  • CameraCamera
  • 카메라 앨범Camera roll
  • 위치Location

이러한 LINE 메서드 및 해당 매개 변수에 대한 자세한 내용은 LINE Bot API 설명서를 참조하세요.For details about these LINE methods and their parameters, see the LINE Bot API documentation.

이 코드 조각은 채널 메시지 유형 ButtonTemplate 및 camera, cameraRoll, Datetimepicker와 같은 3개의 작업 유형을 지정하는 channelData 속성의 예를 보여줍니다.This snippet shows an example of a channelData property that specifies a channel message type ButtonTemplate and 3 action types: camera, cameraRoll, Datetimepicker.

"channelData": {
    "type": "ButtonsTemplate",
    "altText": "This is a buttons template",
    "template": {
        "type": "buttons",
        "thumbnailImageUrl": "https://example.com/bot/images/image.jpg",
        "imageAspectRatio": "rectangle",
        "imageSize": "cover",
        "imageBackgroundColor": "#FFFFFF",
        "title": "Menu",
        "text": "Please select",
        "defaultAction": {
            "type": "uri",
            "label": "View detail",
            "uri": "http://example.com/page/123"
        },
        "actions": [{
                "type": "cameraRoll",
                "label": "Camera roll"
            },
            {
                "type": "camera",
                "label": "Camera"
            },
            {
                "type": "datetimepicker",
                "label": "Select date",
                "data": "storeId=12345",
                "mode": "datetime",
                "initial": "2017-12-25t00:00",
                "max": "2018-01-24t23:59",
                "min": "2017-12-25t00:00"
            }
        ]
    }
}

Teams에 봇 추가Adding a bot to Teams

팀에 추가된 봇은 대화의 일부로 @mentioned일 수 있는 다른 팀 멤버가 됩니다.Bots added to a team become another team member, who can be @mentioned as part of the conversation. 실제로 봇은 @mentioned일 때만 메시지를 받으므로 채널의 다른 대화는 봇으로 보내지지 않습니다.In fact, bots only receive messages when they are @mentioned, so other conversations on the channel are not sent to the bot. 자세한 내용은 Microsoft Teams Bot을 사용하는 채널 및 그룹 채팅 대화를 참조하세요.For more information, see Channel and Group chat conversations with a Microsoft Teams bot.

그룹 또는 채널의 봇은 메시지에서 언급하는 경우에만(@botname) 응답하므로 그룹 채널의 봇에서 받은 모든 메시지에는 자체의 고유한 이름이 포함되며 메시지 구문 분석에서 이를 처리해야 합니다.Because bots in a group or channel respond only when they are mentioned (@botname) in a message, every message received by a bot in a group channel contains its own name, and you must ensure your message parsing handles that. 또한 봇은 언급된 다른 사용자를 구문 분석하여 해당 사용자를 메시지의 일부로 언급할 수 있습니다.In addition, bots can parse out other users mentioned and mention users as part of their messages.

@bot 멘션 확인 및 제거Check for and strip @bot mention


Mention[] m = sourceMessage.GetMentions();
var messageText = sourceMessage.Text;

for (int i = 0;i < m.Length;i++)
{
    if (m[i].Mentioned.Id == sourceMessage.Recipient.Id)
    {
        //Bot is in the @mention list.
        //The below example will strip the bot name out of the message, so you can parse it as if it wasn't included. Note that the Text object will contain the full bot name, if applicable.
        if (m[i].Text != null)
            messageText = messageText.Replace(m[i].Text, "");
    }
}
var text = message.text;
if (message.entities) {
    message.entities
        .filter(entity => ((entity.type === "mention") && (entity.mentioned.id.toLowerCase() === botId)))
        .forEach(entity => {
            text = text.replace(entity.text, "");
        });
    text = text.trim();
}

중요

GUID를 사용하여 봇을 추가하는 것은 테스트 이외의 다른 용도로 사용하지 않는 것이 좋습니다.Adding a bot by GUID, for anything other than testing purposes, is not recommended. 이렇게 하면 봇의 기능이 심각하게 제한됩니다.Doing so severely limits the functionality of a bot. 프로덕션 환경의 봇은 앱의 일부로 Teams에 추가해야 합니다.Bots in production should be added to Teams as part of an app. 봇 만들기Microsoft Teams 봇 테스트 및 디버그를 참조하세요.See Create a bot and Test and debug your Microsoft Teams bot.

추가 리소스Additional resources