Bot Connector API を使用してチャネル固有の機能を実装するImplement channel-specific functionality with the Bot Connector API

一部のチャネルには、メッセージのテキストと添付ファイルだけでは実装できない機能が用意されています。Some channels provide features that cannot be implemented by using only message text and attachments. チャネル固有の機能を実装するには、[Activity[]] オブジェクトの channelData プロパティを使用して、ネイティブのメタデータをチャネルに渡します。To implement channel-specific functionality, you can pass native metadata to a channel in the [Activity[]] object's channelData property. たとえば、お使いのボットで channelData プロパティを使用して、ステッカーを送信するように Telegram に指示したり、電子メールを送信するように Office365 に指示したりできます。For example, your bot can use the channelData property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

この記事では、メッセージ アクティビティの channelData プロパティを使用して、このチャネル固有の機能を実装する方法について説明します。This article describes how to use a message activity's channelData 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

注意

Activity オブジェクトの channelData プロパティの値は JSON オブジェクトです。The value of an Activity object's channelData property is a JSON object. 以下に示すように、JSON オブジェクトの構造は、チャネルおよび実装されている機能によって異なります。The structure of the JSON object will vary according to the channel and the functionality being implemented, as described below.

カスタム電子メール メッセージを作成するCreate a custom Email message

電子メール メッセージを作成するには、Activity オブジェクトの channelData プロパティを、次のプロパティを含む JSON オブジェクトに設定します。To create an email message, set the Activity object's channelData property to a JSON object that contains these properties:

プロパティProperty 説明Description
htmlBodyhtmlBody メッセージの本文に使用する HTML。The HTML to use for the body of the message.
subjectsubject メッセージに使用する件名。The subject to use for the message.
importanceimportance メッセージで使用する重要度フラグです。lownormal、または 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.

次のスニペットは、カスタム電子メール メッセージ用の channelData プロパティの例を示しています。This snippet shows an example of the channelData property for a custom email message.

"channelData":
{
    "htmlBody": "<html><body style = /"font-family: Calibri; font-size: 11pt;/" >This is more than awesome.</body></html>",
    "subject": "Super awesome message subject",
    "importance": "high",
    "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com"
}

完全に忠実な Slack メッセージを作成するCreate a full-fidelity Slack message

完全に忠実な Slack メッセージを作成するには、Activity オブジェクトの channelData プロパティを、Slack のメッセージSlack の添付ファイルSlack のボタンを指定する JSON オブジェクトに設定します。To create a full-fidelity Slack message, set the Activity object's channelData 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 メッセージ内のボタンをクリックすると、お使いのボットに応答メッセージが届きます。このメッセージの channelData プロパティには payload JSON オブジェクトが設定されています。When a user clicks a button within a Slack message, your bot will receive a response message in which the channelData 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.

Facebook 通知を作成するCreate a Facebook notification

Facebook 通知を作成するには、Activity オブジェクトの channelData プロパティを JSON オブジェクトに設定し、次のプロパティを指定します。To create a Facebook notification, set the Activity object's channelData property to a JSON object that specifies these properties:

プロパティProperty 説明Description
notification_typenotification_type 通知の種類 (例: REGULARSILENT_PUSHNO_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 固有のアクションが実装されているメッセージを作成するには、Activity オブジェクトの channelData プロパティを JSON オブジェクトに設定し、次のプロパティを指定します。To create a message that implements Telegram-specific actions, such as sharing a voice memo or a sticker, set the Activity object's channelData property to a JSON object that specifies these properties:

プロパティProperty 説明Description
methodmethod 呼び出す Telegram Bot API メソッド。The Telegram Bot API method to call.
parametersparameters 指定されたメソッドのパラメーター。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.

このスニペットは、1 つの 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"
        }
    }
]

ネイティブ Kik メッセージを作成するCreate a native Kik message

ネイティブ Kik メッセージを作成するには、Activity オブジェクトの channelData プロパティを JSON オブジェクトに設定し、次のプロパティを指定します。To create a native Kik message, set the Activity object's channelData property to a JSON object that specifies this property:

プロパティProperty 説明Description
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"
                }
        }
    ]
}

その他のリソースAdditional resources