Csatornaspecifikus funkcionalitás megvalósítása

Cikk
03/08/2023

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

Egyes csatornák olyan funkciókat biztosítanak, amelyek nem implementálhatók csak üzenetszöveggel és mellékletekkel. A csatornaspecifikus funkciók implementálásához natív metaadatokat adhat át egy csatornának a tevékenységobjektum csatornaadat-tulajdonságában . A robot például a csatornaadatok tulajdonságával utasíthatja a Telegramot matricák küldésére, vagy utasíthatja az Office365-öt e-mailek küldésére.

Ez a cikk azt ismerteti, hogyan valósíthatja meg ezt a csatornaspecifikus funkciót az üzenettevékenység csatornaadat-tulajdonságának használatával:

Csatorna	Funkció
E-mail	Küldjön és fogadj egy e-mailt, amely törzs-, tárgy- és fontossági metaadatokat tartalmaz.
Facebook	Küldjön Facebook-értesítéseket natív módon.
VONAL	Küldjön egy üzenetet, amely a LINE-specifikus üzenettípusokat implementálja.
Slack	Teljes hűségű Slack-üzenetek küldése.
Teams	@megemlítések kezelése a Microsoft Teams-üzenetekben.
Telegram	Távirat-specifikus műveleteket hajthat végre, például hangjegyzetet vagy matricát oszthat meg.

Megjegyzés

A tevékenységobjektum csatornaadat-tulajdonságának értéke egy JSON-objektum. Ezért a cikkben szereplő példák a JSON-tulajdonság várt formátumát channelData mutatják be különböző forgatókönyvekben. JSON-objektum .NET használatával történő létrehozásához használja a JObject (.NET) osztályt.

Egyéni e-mail-üzenet létrehozása

Egyéni e-mail-üzenet létrehozásához állítsa a tevékenység channelData tulajdonságot egy JSON-objektumra, amely a következő tulajdonságokat tartalmazza:

Tulajdonság	Leírás
bccRecipients	Pontosvessző (;) az üzenet Titkos másolat (vak másolat) mezőjéhez hozzáadni kívánt e-mail-címek elválasztott sztringje.
ccRecipients	Pontosvessző (;) az üzenet Másolatot kap (másolat) mezőjéhez hozzáadni kívánt e-mail-címek elválasztott sztringje.
htmlBody	Az e-mail törzsét meghatározó HTML-dokumentum. A támogatott HTML-elemekkel és attribútumokkal kapcsolatos információkért tekintse meg a csatorna dokumentációját.
Fontos	Az e-mail fontossági szintje. Az érvényes értékek magasak, normálak és alacsonyak. Az alapértelmezett érték normál.
toRecipients	Pontosvessző (;) az üzenet Címzett mezőjéhez hozzáadni kívánt e-mail-címek elválasztott sztringje.

A felhasználó és a robot közötti kimenő és bejövő üzenetek olyan tevékenységet tartalmazhatnak channelData , amely olyan JSON-objektumot tartalmaz, amelynek tulajdonságai az előző táblázatban vannak megadva. Az alábbi kódrészlet egy példát mutat be egy channelData bejövő egyéni e-mail-üzenet tulajdonságára a robottól a felhasználóig.

{
    "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-értesítés létrehozása

Facebook-értesítés létrehozásához állítsa a tevékenységobjektum csatornaadat-tulajdonságát egy JSON-objektumra, amely ezeket a tulajdonságokat határozza meg:

Tulajdonság	Leírás
notification_type	Az értesítés típusa, például REGULÁRIS, SILENT_PUSH vagy NO_PUSH.
Mellékletet	Kép-, videó- vagy egyéb multimédiás típust, illetve sablonalapú mellékletet, például nyugtát meghatározó melléklet.

Megjegyzés

A tulajdonság és tulajdonság notification_type formátumával és attachment tartalmával kapcsolatos részletekért tekintse meg a Facebook API dokumentációját.

Ez a kódrészlet egy Facebook-nyugta melléklet tulajdonságára channelData mutat példát.

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

LINE-üzenet létrehozása

Vonalspecifikus üzenettípusokat (például matricákat, sablonokat vagy VONALspecifikus művelettípusokat, például a telefon kamerájának megnyitását) megvalósító üzenet létrehozásához állítsa a tevékenységobjektum csatornaadat-tulajdonságát egy OLYAN JSON-objektumra, amely megadja a LINE üzenettípusokat és a művelettípusokat.

Tulajdonság	Leírás
típus	A LINE művelet/üzenettípus neve

Ezek a LINE-üzenettípusok támogatottak:

Matrica
Képtérkép
Sablon (Gomb, megerősítés, körhinta)
Flex

Ezek a SORműveletek a JSON-objektum üzenettípus műveletmezőjében adhatók meg:

Visszaküldési
Üzenet
URI
Datetimerpicker
Kamera
Filmtekercs mappa
Hely

Ezekről a LINE metódusokról és paramétereikről a LINE Bot API dokumentációjában talál további információt.

Ez a kódrészlet egy channelData olyan tulajdonságra mutat példát, amely csatornaüzenet-típust ButtonTemplate és három művelettípust határoz meg: "kamera", "cameraRoll" és "datetimepicker".

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

Teljes körű Slack-üzenet létrehozása

Teljes hűségű Slack-üzenet létrehozásához állítsa a tevékenységobjektum csatornaadat-tulajdonságát egy JSON-objektumra, amely a következőt határozza meg:

Megjegyzés

A Slack-üzenetek gombjainak támogatásához engedélyeznie kell az Interaktív üzenetek funkciót , amikor csatlakoztatja a robotot a Slack-csatornához.

Ez a kódrészlet egy egyéni Slack-üzenet tulajdonságára channelData mutat példát.

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

Amikor egy felhasználó egy Slack-üzenetben egy gombra kattint, a robot egy válaszüzenetet kap, amelyben a csatornaadatok tulajdonság egy payload JSON-objektummal van feltöltve. Az payload objektum megadja az eredeti üzenet tartalmát, azonosítja a kattintott gombot, és azonosítja a gombra kattintó felhasználót.

Ez a kódrészlet egy példát mutat a channelData robot által kapott üzenet tulajdonságára, amikor a felhasználó a Slack-üzenet egyik gombjára kattint.

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

A robot normál módon válaszolhat erre az üzenetre, vagy közvetlenül az objektum tulajdonsága által megadott végpontra küldheti a payload válaszát response_url . A válasz közzétételének időpontjáról és módjáról a response_urlSlack-gombok című témakörben olvashat.

Dinamikus gombokat a következő JSON használatával hozhat létre:

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

Interaktív menük létrehozásához használja a következő JSON-t:

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

Robot hozzáadása a Teamshez

A csapathoz hozzáadott robotok egy másik csapattaggá válnak, akik a beszélgetés részeként lehetnek @mentioned . A robotok valójában csak akkor kapnak üzeneteket, ha azok @mentionedvannak, így a csatornán lévő többi beszélgetés nem lesz elküldve a robotnak. További információ: Csatorna- és csoportos csevegések Egy Microsoft Teams-robottal.

Mivel egy csoport vagy csatorna robotjai csak akkor válaszolnak, ha () megemlítik@botname őket egy üzenetben, a csoportcsatornában lévő robot által fogadott összes üzenet tartalmazza a saját nevét, és meg kell győződnie arról, hogy az üzenet elemzése kezeli ezt. Emellett a robotok elemezhetik a többi említett felhasználót, és megemlíthetik a felhasználókat az üzeneteik részeként.

Keresés és említés csíkozása @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();
}

Fontos

Nem ajánlott a robot GUID alapján történő hozzáadása a tesztelési céloktól eltérő célokra. Ez súlyosan korlátozza a robot működését. Az éles környezetben lévő robotokat egy alkalmazás részeként kell hozzáadni a Teamshez. Lásd: Robot létrehozása és a Microsoft Teams-robot tesztelése és hibakeresése.

Távirati üzenet létrehozása

Ha olyan üzenetet szeretne létrehozni, amely Telegram-specifikus műveleteket hajt végre, például hangjegyzetet vagy matricát oszt meg, állítsa a tevékenységobjektum csatornaadat-tulajdonságát egy JSON-objektumra, amely ezeket a tulajdonságokat határozza meg:

Tulajdonság	Leírás
method	A Meghívandó Telegram Bot API-metódus.
parameters	A megadott metódus paraméterei.

Ezek a Telegram-metódusok támogatottak:

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

Ezekről a Telegram-metódusokról és paramétereikről a Telegram Bot API dokumentációjában talál további információt.

Megjegyzés

A chat_id paraméter minden Telegram-metódusnál gyakori. Ha nem adja meg chat_id paraméterként, a keretrendszer megadja az azonosítót.
A fájl tartalmának beágyazott átadása helyett adja meg a fájlt URL-címmel és médiatípussal az alábbi példában látható módon.
A robot által a Telegram-csatornáról kapott minden egyes üzenetben a ChannelData tulajdonság tartalmazza a robot által korábban küldött üzenetet.

Ez a kódrészlet egy olyan tulajdonságra mutat példát channelData , amely egyetlen Telegram-metódust határoz meg:

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

Ez a kódrészlet egy olyan tulajdonságra mutat példát channelData , amely a Telegram metódusok tömbjét adja meg:

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

A Telegram-metódus implementálása után a robot egy válaszüzenetet kap, amelyben a csatornaadat-tulajdonság egy JSON-objektummal van feltöltve. Ez a válaszobjektum az eredeti üzenet tartalmát határozza meg, beleértve egy update_id és legfeljebb egy választható paramétert. A bejövő válaszok fogadásáról további információt a Frissítések lekérése című témakörben talál.

Ez a kódrészlet egy példát mutat a channelData robot által a szavazás létrehozásakor kapott üzenet tulajdonságára:

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

Megosztás a következőn keresztül:

Csatornaspecifikus funkcionalitás megvalósítása

Egyéni e-mail-üzenet létrehozása

Facebook-értesítés létrehozása

LINE-üzenet létrehozása

Teljes körű Slack-üzenet létrehozása

Robot hozzáadása a Teamshez

Keresés és említés csíkozása @bot

Távirati üzenet létrehozása

További források

További források