Implementace funkcí specifických pro kanál

Článek
03/08/2023

PLATÍ PRO: SDK v4

Některé kanály poskytují funkce, které se nedají implementovat jenom s textem zprávy a přílohami. Pokud chcete implementovat funkce specifické pro kanál, můžete kanálu předat nativní metadata ve vlastnosti dat kanálu objektu aktivity. Robot může například pomocí datové vlastnosti kanálu dát Aplikaci Telegram pokyn, aby poslal nálepku nebo office365 poslal e-mail.

Tento článek popisuje, jak používat vlastnost dat kanálu aktivity zpráv k implementaci této funkce specifické pro kanál:

Kanál	Funkce
E-mail	Odešlete a přijmete e-mail, který obsahuje metadata textu, předmětu a důležitosti.
Facebook	Posílat oznámení z Facebooku nativně.
ŘÁDKU	Odeslat zprávu, která implementuje typy zpráv specifické pro ŘÁDEK.
Slack	Odesílat úplné věrnosti zpráv Slacku.
Teams	Zpracování @zmínek ve zprávách Microsoft Teams
Telegram	Provádět akce specifické pro Telegram, jako je sdílení hlasové poznámky nebo nálepky.

Poznámka

Hodnota datové vlastnosti kanálu objektu aktivity je objekt JSON. Proto příklady v tomto článku ukazují očekávaný formát channelData vlastnosti JSON v různých scénářích. Pokud chcete vytvořit objekt JSON pomocí .NET, použijte JObject třídu (.NET).

Vytvoření vlastní e-mailové zprávy

Pokud chcete vytvořit vlastní e-mailovou zprávu, nastavte vlastnost aktivity channelData na objekt JSON, který obsahuje následující vlastnosti:

Vlastnost	Popis
bccRecipients	Středník (;) řetězec e-mailových adres s oddělovači, který se má přidat do pole Skrytá kopie zprávy.
příjemce ccRecipients	Středník (;) Řetězec e-mailových adres s oddělovači, který se má přidat do pole Kopie (kopie) zprávy.
htmlBody	Dokument HTML, který určuje text e-mailové zprávy. Informace o podporovaných prvcích a atributech HTML najdete v dokumentaci ke kanálu.
Význam	Úroveň důležitosti e-mailu Platné hodnoty jsou vysoké, normální a nízké. Výchozí hodnota je normální.
naPočteni	Středník (;) Řetězec e-mailových adres s oddělovači, který se má přidat do pole Do zprávy.

Odchozí a příchozí zprávy mezi uživatelem a robotem channelData můžou obsahovat aktivitu, která obsahuje objekt JSON, jehož vlastnosti jsou zadané v předchozí tabulce. Následující fragment kódu ukazuje příklad channelData vlastnosti pro příchozí vlastní e-mailovou zprávu od robota k uživateli.

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

Vytvoření facebookového oznámení

Pokud chcete vytvořit oznámení z Facebooku, nastavte vlastnost dat kanálu objektu aktivity na objekt JSON, který určuje tyto vlastnosti:

Vlastnost	Popis
notification_type	Typ oznámení, například REGULAR, SILENT_PUSH nebo NO_PUSH.
Přílohu	Příloha, která určuje obrázek, video nebo jiný typ multimédií, nebo přílohu se šablonou, jako je potvrzení.

Poznámka

Podrobnosti o formátu a obsahu notification_type vlastnosti a attachment vlastnosti najdete v dokumentaci k rozhraní FACEBOOK API.

Tento fragment kódu ukazuje příklad vlastnosti pro přílohu channelData facebookové účtenky.

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

Vytvoření zprávy LINE

Pokud chcete vytvořit zprávu, která implementuje typy zpráv specifické pro ŘÁDEK (například nálepky, šablony nebo typy akcí specifické pro ŘÁDEK, jako je otevření fotoaparátu telefonu), nastavte vlastnost dat kanálu objektu aktivity na objekt JSON, který určuje typy zpráv a typy akcí TYPU ŘÁDEK.

Vlastnost	Popis
typ	Název typu akce ŘÁDEK nebo zprávy

Podporují se tyto typy zpráv TYPU ŘÁDEK:

Nálepka
Imagemap
Šablona (tlačítko, potvrzení, karusel)
Flex

Tyto akce LINE je možné zadat v poli akce objektu JSON typu zprávy:

Postback
Zpráva
Identifikátor URI
Datetimerpicker
Camera
Z fotoaparátu
Umístění

Podrobnosti o těchto metodách LINE a jejich parametrech najdete v dokumentaci k rozhraní LINE Bot API.

Tento fragment kódu ukazuje příklad channelData vlastnosti, která určuje typ ButtonTemplate zprávy kanálu a tři typy akcí: "camera", "cameraRoll" a "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"
            }
        ]
    }
}

Vytvoření plně věrné zprávy Slacku

Pokud chcete vytvořit plně věrnou zprávu Slacku, nastavte vlastnost dat kanálu objektu aktivity na objekt JSON, který určuje:

Poznámka

Pokud chcete podporovat tlačítka ve zprávách Slacku, musíte při připojení robota ke kanálu Slacku povolit interaktivní zprávy.

Tento fragment kódu ukazuje příklad channelData vlastnosti pro vlastní zprávu Slacku.

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

Když uživatel klikne na tlačítko ve zprávě Slack, robot obdrží zprávu s odpovědí, ve které se vlastnost dat kanálu naplní objektem payload JSON. Objekt payload určuje obsah původní zprávy, identifikuje tlačítko, na které bylo kliklo, a identifikuje uživatele, který na tlačítko klikl.

Tento fragment kódu ukazuje příklad channelData vlastnosti ve zprávě, kterou robot obdrží, když uživatel klikne na tlačítko ve zprávě Slack.

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

Robot může na tuto zprávu odpovědět normálním způsobem nebo může svou odpověď odeslat přímo do koncového bodu, který je určený vlastností objektu payloadresponse_url . Informace o tom, kdy a jak publikovat odpověď na , najdete v response_urltématu Tlačítka Slacku.

Dynamická tlačítka můžete vytvořit pomocí následujícího kódu 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"
                    }
                }
            ]
        }
    ]
}

K vytvoření interaktivních nabídek použijte následující kód 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Přidání robota do Teams

Roboti přidaní do týmu se stanou dalším členem týmu, který může být @mentioned součástí konverzace. Roboti ve skutečnosti přijímají zprávy jenom tehdy, když jsou @mentioned, takže ostatní konverzace v kanálu se do robota neodesílají. Další informace najdete v tématu Kanálové a skupinové konverzace chatu pomocí robota Microsoft Teams.

Vzhledem k tomu, že roboti ve skupině nebo kanálu reagují jenom v případě, že jsou ve zprávě zmíněni (@botname), každá zpráva přijatá robotem v kanálu skupiny obsahuje vlastní název, a vy musíte zajistit, aby to vaše analýza zpráv zvládla. Kromě toho můžou roboti parsovat ostatní zmíněné uživatele a v rámci svých zpráv je zmiňují.

Kontrola a odstranění @bot zmínky

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();
}

Důležité

Přidání robota podle identifikátoru GUID pro jiné účely než pro účely testování se nedoporučuje. To výrazně omezuje funkčnost robota. Roboti v produkčním prostředí by se měli přidat do Teams jako součást aplikace. Viz Vytvoření robota a Testování a ladění robota Microsoft Teams.

Vytvoření zprávy Aplikace Telegram

Pokud chcete vytvořit zprávu, která implementuje akce specifické pro Aplikaci Telegram, jako je sdílení hlasové poznámky nebo nálepky, nastavte vlastnost dat kanálu objektu aktivity na objekt JSON, který určuje tyto vlastnosti:

Vlastnost	Popis
method	Volání metody rozhraní Api robota aplikace Telegram
parameters	Parametry zadané metody.

Podporují se tyto metody Telegramu:

answerInlineQuery
editMessageCaption
editMessageReplyMarkup
upravitText zprávy
dopředná zpráva
banChatMember
Houdio
sendChatAction
odeslatContact
odeslat dokument
umístění odeslání
Sendmessage
odeslatPhoto
sendSticker
odeslatVenue
odeslatVideo
sendVoice
unbanChatMember

Podrobnosti o těchto metodách Aplikace Telegram a jejich parametrech najdete v dokumentaci k rozhraní API robota aplikace Telegram.

Poznámka

Parametr chat_id je společný pro všechny metody Aplikace Telegram. Pokud jako parametr nezadáte chat_id , rozhraní poskytne ID za vás.
Místo předávání obsahu souboru v textu zadejte soubor pomocí adresy URL a typu média, jak je znázorněno v následujícím příkladu.
V každé zprávě, kterou robot obdrží z kanálu Telegram, ChannelData bude vlastnost obsahovat zprávu, kterou robot odeslal dříve.

Tento fragment kódu ukazuje příklad channelData vlastnosti, která určuje jednu metodu Telegram:

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

Tento fragment kódu ukazuje příklad channelData vlastnosti, která určuje pole metod Telegram:

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

Po implementaci metody Telegram obdrží robot zprávu s odpovědí, ve které se vlastnost data kanálu naplní objektem JSON. Tento objekt odpovědi určuje obsah původní zprávy, včetně a maximálně jednoho volitelného update_id parametru. Informace o příjmu příchozích odpovědí najdete v tématu Získání aktualizací.

Tento fragment kódu ukazuje příklad channelData vlastnosti ve zprávě, kterou robot obdrží při vytvoření hlasování:

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

Sdílet prostřednictvím

Implementace funkcí specifických pro kanál

Vytvoření vlastní e-mailové zprávy

Vytvoření facebookového oznámení

Vytvoření zprávy LINE

Vytvoření plně věrné zprávy Slacku

Přidání robota do Teams

Kontrola a odstranění @bot zmínky

Vytvoření zprávy Aplikace Telegram

Další materiály

Další materiály