チャネル固有の機能の実装

[アーティクル]
03/08/2023

適用対象: SDK v4

一部のチャネルには、メッセージテキストと添付ファイルのみで実装できない機能が用意されています。チャネル固有の機能を実装するには、アクティビティオブジェクトの "チャネルデータ" プロパティを使用して、ネイティブのメタデータをチャネルに渡します。たとえば、お使いのボットでチャネルデータプロパティを使用して、ステッカーを送信するように Telegram に指示したり、電子メールを送信するように Office365 に指示したりできます。

この記事では、メッセージアクティビティのチャネルデータプロパティを使用して、このチャネル固有の機能を実装する方法について説明します。

チャネル	機能
Email	本文、件名、重要度のメタデータを含む電子メールを送受信します。
Facebook	Facebook の通知をネイティブに送信します。
LINE	LINE 固有のメッセージ型を実装するメッセージを送信します。
Slack	完全に忠実な Slack メッセージを送信します。
Teams	Microsoft Teams メッセージで @-メンションを処理します。
Telegram	ボイスメモやステッカーの共有など、Telegram 固有のアクションを実行します。

注意

アクティビティオブジェクトのチャネルデータプロパティの値は JSON オブジェクトです。そのため、この記事の例では、さまざまなシナリオにおいて有効な channelData JSON プロパティの書式を示します。 .NET を使用して JSON オブジェクトを作成するには、JObject (.NET) クラスを使用します。

カスタム電子メールメッセージを作成する

カスタム電子メールメッセージを作成するには、activity channelData プロパティを、次のプロパティを含む JSON オブジェクトに設定します。

プロパティ	説明
bccRecipients	メッセージの BCC (ブラインドカーボンコピー) フィールドに追加する、セミコロン (;) 区切りの電子メールアドレスの文字列。
ccRecipients	メッセージの CC (カーボンコピー) フィールドに追加する、セミコロン (;) 区切りの電子メールアドレスの文字列。
htmlBody	電子メールメッセージの本文を指定する HTML ドキュメント。サポートされている HTML の要素と属性については、チャネルのドキュメントを参照してください。
importance	電子メールの重要度レベル。有効な値は、high、normal、および low です。既定値は normal です。
toRecipients	メッセージの宛先フィールドに追加する、セミコロン (;) 区切りの電子メールアドレスの文字列。

ユーザーとボットの間の送信メッセージと受信メッセージには channelData 、前の表でプロパティが指定されている JSON オブジェクトを含むアクティビティがある場合があります。次の channelData スニペットは、ボットからユーザーへの受信カスタム電子メールメッセージのプロパティの例を示しています。

{
    "type": "ActivityTypes.Message",
    "locale": "en-Us",
    "channelID": "email",
    "fromName": { "id": "mybot@mydomain.com", "name": "My bot"},
    "recipientName": { "id": "joe@otherdomain.com", "name": "Joe Doe"},
    "conversation": { "id": "123123123123", "topic": "awesome chat" },
    "channelData":
    {
        "htmlBody": "<html><body style = \"font-family: Calibri; font-size: 11pt;\" >This is more than awesome.</body></html>",
        "importance": "high",
        "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com",
    }
}

Facebook 通知を作成する

Facebook 通知を作成するには、アクティビティオブジェクトのチャネルデータプロパティを JSON オブジェクトに設定し、以下のプロパティを指定します。

プロパティ	説明
notification_type	REGULAR、SILENT_PUSH、NO_PUSHなどの通知の種類。
attachment	画像、動画、またはその他のマルチメディアの種類を指定する添付ファイル、または受信確認などのテンプレート化された添付ファイル。

Note

notification_type プロパティおよび attachment プロパティの形式とコンテンツの詳細については、Facebook API のドキュメントを参照してください。

このスニペットは、Facebook 受信確認添付ファイル用の channelData プロパティの例を示しています。

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

LINE のメッセージを作成する

LINE 固有のメッセージの種類 (ステッカー、テンプレート、電話カメラを開くなどの LINE 固有のアクションの種類など) を実装するメッセージを作成するには、アクティビティオブジェクトのチャネルデータプロパティを、LINE メッセージの種類とアクションの種類を指定する JSON オブジェクトに設定します。

プロパティ	説明
type	LINE のアクションまたはメッセージのタイプ名

次の LINE メッセージのタイプがサポートされています。

スタンプ
イメージマップ
テンプレート (ボタン、確認、カルーセル)
Flex

次の LINE アクションを、メッセージタイプ JSON オブジェクトの action フィールドで指定できます。

ポストバック
Message
URI
日時選択
Camera
カメラロール
場所

これらの LINE メソッドとそのパラメーターの詳細については、LINE Bot API のドキュメントを参照してください。

このスニペットは、チャネルメッセージの channelData 種類 ButtonTemplate と、"camera"、"cameraRoll"、"datetimepicker" の 3 つのアクションの種類を指定するプロパティの例を示しています。

"channelData": {
    "type": "template",
    "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"
            }
        ]
    }
}

完全に忠実な Slack メッセージを作成する

完全に忠実な Slack メッセージを作成するには、アクティビティオブジェクトのチャネルデータプロパティを、次を指定する JSON オブジェクトに設定します。

注意

Slack メッセージでボタンをサポートするには、Slack チャネルにお使いのボットを接続するときに、インタラクティブメッセージを有効にする必要があります。

このスニペットは、カスタム Slack メッセージ用の channelData プロパティの例を示しています。

"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 オブジェクトが設定されています。 payload オブジェクトによって、元のメッセージのコンテンツが指定され、クリックされたボタンと、そのボタンをクリックしたユーザーが特定されます。

このスニペットは、ユーザーが Slack メッセージ内のボタンをクリックしたときに、ボットに届くメッセージ内の channelData プロパティの例を示しています。

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

お使いのボットでは通常の方法でこのメッセージに返信するか、その応答を、payload オブジェクトの response_url プロパティで指定されているエンドポイントに直接投稿できます。応答を response_url に投稿するタイミングと方法については、Slack ボタンに関するページをご覧ください。

動的ボタンは、次の 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 を使用します。

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

ボットを Teams に追加する

チームに追加されたボットは、別のチームメンバーとなり、会話の中で @mentioned によって言及される可能性があります。実際、ボットは、の場合 @mentionedにのみメッセージを受信するため、チャネル上の他の会話はボットに送信されません。詳細については、「Microsoft Teams のボットを使用したチャネルおよびグループチャットでの会話」を参照してください。

グループまたはチャネル内のボットはメッセージにメンション@botname () されている場合にのみ応答するため、グループチャネル内のボットによって受信されたすべてのメッセージには独自の名前が含まれており、メッセージ解析で処理されることを確認する必要があります。また、ボットは、メンションされた他のユーザーを解析し、そのメッセージの中でユーザーをメンションできます。

@bot メンションの確認と削除

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 によってボットを追加することはお勧めしません。そのようにすると、ボットの機能が厳しく制限されます。運用環境のボットは、アプリの一部として Teams に追加する必要があります。「ボットの作成」と「Microsoft Teams のボットのテストとデバッグ」を参照してください。

Telegram メッセージを作成する

音声メモやステッカーの共有など、Telegram 固有のアクションが実装されているメッセージを作成するには、アクティビティオブジェクトのチャネルデータプロパティを JSON オブジェクトに設定し、次のプロパティを指定します。

プロパティ	説明
method	呼び出す Telegram Bot API メソッド。
parameters	指定されたメソッドのパラメーター。

次の Telegram メソッドがサポートされています。

answerInlineQuery
editMessageCaption
editMessageReplyMarkup
editMessageText
forwardMessage
banChatMember
sendAudio
sendChatAction
sendContact
sendDocument
sendLocation
sendMessage
sendPhoto
sendSticker
sendVenue
sendVideo
sendVoice
unbanChatMember

これらの Telegram メソッドとそのパラメーターの詳細については、Telegram Bot API のドキュメントを参照してください。

Note

chat_id パラメーターは、すべての Telegram メソッドに共通です。パラメーターとしてを指定 chat_id しない場合、フレームワークによって ID が提供されます。
ファイルコンテンツをインラインで渡すのではなく、以下の例で示すように、URL およびメディアの種類を使用してファイルを指定します。
お使いのボットで受信した、Telegram チャネルからの各メッセージの ChannelDataプロパティに、お使いのボットによって以前送信されたメッセージが指定されます。

このスニペットは、1 つの Telegram メソッドを channelData 指定するプロパティの例を示しています。

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

このスニペットは、Telegram メソッドの channelData 配列を指定するプロパティの例を示しています。

"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 オブジェクトが設定されている応答メッセージを受信します。この応答オブジェクトは、元のメッセージの内容 (update_id と最大で 1 つの省略可能なパラメーターを含む) を示します。着信応答の受信の詳細については、「更新プログラムの取得」を参照してください。

このスニペットは、ポーリングの作成時に channelData ボットが受け取るメッセージ内のプロパティの例を示しています。

"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
        }
    }
}

次の方法で共有

チャネル固有の機能の実装

カスタム電子メールメッセージを作成する

Facebook 通知を作成する

LINE のメッセージを作成する

完全に忠実な Slack メッセージを作成する

ボットを Teams に追加する

@bot メンションの確認と削除

Telegram メッセージを作成する

その他のリソース

その他のリソース

次の方法で共有

チャネル固有の機能の実装

カスタム電子メール メッセージを作成する

Facebook 通知を作成する

LINE のメッセージを作成する

完全に忠実な Slack メッセージを作成する

ボットを Teams に追加する

@bot メンションの確認と削除

Telegram メッセージを作成する

その他のリソース

その他のリソース

カスタム電子メールメッセージを作成する