Implementowanie funkcji specyficznej dla kanału

2024-10-09

DOTYCZY: Zestaw SDK w wersji 4

Niektóre kanały udostępniają funkcje, których nie można zaimplementować tylko z tekstem wiadomości i załącznikami. Aby zaimplementować funkcję specyficzną dla kanału, można przekazać natywne metadane do kanału we właściwości danych kanału obiektu działania. Na przykład bot może użyć właściwości danych kanału, aby poinstruować telegram o wysłaniu naklejki lub poinstruowanie usługi Office365 o wysłaniu wiadomości e-mail.

W tym artykule opisano sposób użycia właściwości danych kanału działania do zaimplementowania tej funkcji specyficznej dla kanału:

Kanał	Funkcjonalność
Poczta e-mail	Wysyłanie i odbieranie wiadomości e-mail zawierającej metadane treści, tematu i ważności.
Facebook	Wysyłaj powiadomienia na Facebooku natywnie.
LINII	Wyślij komunikat, który implementuje typy komunikatów specyficznych dla wiersza.
Slack	Wysyłanie komunikatów usługi Slack o pełnej wierności.
Teams	Obsługa @-wzmianek w wiadomościach usługi Microsoft Teams.
Telegram	Wykonaj akcje specyficzne dla usługi Telegram, takie jak udostępnianie notatki głosowej lub naklejki.

Uwaga

Wartość właściwości danych kanału obiektu działania jest obiektem JSON. W związku z tym przykłady w tym artykule pokazują oczekiwany format channelData właściwości JSON w różnych scenariuszach. Aby utworzyć obiekt JSON przy użyciu platformy .NET, użyj JObject klasy (.NET).

Tworzenie niestandardowej wiadomości e-mail

Aby utworzyć niestandardową wiadomość e-mail, ustaw właściwość działania channelData na obiekt JSON zawierający następujące właściwości:

Właściwość	Opis
bccRecipients	Średnik (;) Rozdzielany ciąg adresów e-mail do dodania do pola UDW (ślepa kopia węglowa).
ccRecipients	Średnik (;) Rozdzielany ciąg adresów e-mail, który ma zostać dodany do pola DW (kopia węgla).
htmlBody	Dokument HTML określający treść wiadomości e-mail. Zapoznaj się z dokumentacją kanału, aby uzyskać informacje o obsługiwanych elementach i atrybutach HTML.
Znaczenie	Poziom ważności wiadomości e-mail. Prawidłowe wartości są wysokie, normalne i niskie. Wartość domyślna jest normalna.
toRecipients	Średnik (;) Rozdzielany ciąg adresów e-mail, który ma zostać dodany do pola Do wiadomości.

Komunikaty wychodzące i przychodzące między użytkownikiem a botem mogą mieć channelData działanie zawierające obiekt JSON, którego właściwości są określone w poprzedniej tabeli. Poniższy fragment kodu przedstawia przykład channelData właściwości przychodzącej niestandardowej wiadomości e-mail od bota do użytkownika.

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

Tworzenie powiadomienia w serwisie Facebook

Aby utworzyć powiadomienie w serwisie Facebook, ustaw właściwość danych kanału obiektu działania na obiekt JSON, który określa następujące właściwości:

Właściwość	Opis
notification_type	Typ powiadomienia, taki jak REGULAR, SILENT_PUSH lub NO_PUSH.
Załącznik	Załącznik, który określa obraz, wideo lub inny typ multimediów lub załącznik z szablonem, taki jak potwierdzenie.

Uwaga

Aby uzyskać szczegółowe informacje o formacie i zawartości notification_type właściwości i attachment właściwości, zobacz dokumentację interfejsu API serwisu Facebook.

Ten fragment kodu przedstawia przykład channelData właściwości załącznika potwierdzenia na Facebooku.

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

Tworzenie komunikatu WIERSZA

Aby utworzyć komunikat, który implementuje typy komunikatów specyficznych dla wiersza (takie jak naklejki, szablony lub typy akcji specyficzne dla wiersza, takie jak otwieranie aparatu telefonicznego), ustaw właściwość danych kanału obiektu działania na obiekt JSON, który określa typy komunikatów WIERSZA i typy akcji.

Właściwość	Opis
typ	Nazwa typu akcji/komunikatu LINE

Obsługiwane są następujące typy komunikatów LINE:

Naklejki
Imagemap
Szablon (przycisk, potwierdzenie, karuzela)
Flex

Te akcje WIERSZA można określić w polu akcji obiektu JSON typu komunikatu:

Ogłaszania wstecznego
Komunikat
URI
Datetimerpicker
Aparat fotograficzny
Album Z aparatu
Lokalizacja

Aby uzyskać szczegółowe informacje na temat tych metod LINE i ich parametrów, zobacz dokumentację interfejsu API bota line.

Ten fragment kodu przedstawia przykład channelData właściwości, która określa typ ButtonTemplate komunikatu kanału i trzy typy akcji: "camera", "cameraRoll" i "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"
            }
        ]
    }
}

Tworzenie komunikatu usługi Slack o pełnej wierności

Aby utworzyć komunikat usługi Slack o pełnej wierności, ustaw właściwość danych kanału obiektu działania na obiekt JSON, który określa:

Uwaga

Aby obsługiwać przyciski w komunikatach usługi Slack, należy włączyć komunikaty interakcyjne podczas łączenia bota z kanałem usługi Slack.

Ten fragment kodu przedstawia przykład channelData właściwości niestandardowego komunikatu slack.

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

Gdy użytkownik kliknie przycisk w komunikacie usługi Slack, bot otrzyma komunikat odpowiedzi, w którym właściwość danych kanału zostanie wypełniona obiektem payload JSON. Obiekt payload określa zawartość oryginalnego komunikatu, identyfikuje kliknięty przycisk i identyfikuje użytkownika, który kliknął przycisk.

Ten fragment kodu przedstawia przykład channelData właściwości w komunikacie, który bot otrzymuje, gdy użytkownik kliknie przycisk w komunikacie usługi Slack.

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

Bot może odpowiedzieć na tę wiadomość w normalny sposób lub opublikować odpowiedź bezpośrednio w punkcie końcowym określonym przez payload właściwość obiektu response_url . Aby uzyskać informacje o tym, kiedy i jak opublikować odpowiedź na response_urlobiekt , zobacz Przyciski usługi Slack.

Przyciski dynamiczne można tworzyć przy użyciu następującego kodu 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"
                    }
                }
            ]
        }
    ]
}

Aby utworzyć interaktywne menu, użyj następującego kodu 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Dodawanie bota do usługi Teams

Boty dodane do zespołu stają się kolejnym członkiem zespołu, który może być @mentioned częścią konwersacji. W rzeczywistości boty odbierają komunikaty tylko wtedy, gdy są @mentioned, więc inne konwersacje w kanale nie są wysyłane do bota. Aby uzyskać więcej informacji, zobacz Konwersacje na czacie kanału i grupy z botem usługi Microsoft Teams.

Ponieważ boty w grupie lub kanale reagują tylko wtedy, gdy są wymienione (@botname) w komunikacie, każdy komunikat otrzymany przez bota w kanale grupy zawiera własną nazwę i musisz upewnić się, że twój komunikat obsługuje tę funkcję. Ponadto boty mogą analizować innych użytkowników wymienionych i wymieniać użytkowników w ramach swoich wiadomości.

Sprawdzanie i usuwanie wzmianki @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();
}

Ważne

Dodawanie bota według identyfikatora GUID w celach innych niż testowanie nie jest zalecane. W ten sposób poważnie ogranicza funkcjonalność bota. Boty w środowisku produkcyjnym należy dodać do usługi Teams w ramach aplikacji. Zobacz Tworzenie bota i testowanie i debugowanie bota usługi Microsoft Teams.

Tworzenie komunikatu telegramu

Aby utworzyć komunikat implementujący akcje specyficzne dla telegramu, takie jak udostępnianie notatki głosowej lub naklejki, ustaw właściwość danych kanału obiektu działania na obiekt JSON, który określa następujące właściwości:

Właściwość	Opis
method	Metoda interfejsu API bota telegramu do wywołania.
parameters	Parametry określonej metody.

Obsługiwane są następujące metody telegramu:

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

Aby uzyskać szczegółowe informacje na temat tych metod telegramu i ich parametrów, zobacz dokumentację interfejsu API bota telegramu.

Uwaga

Parametr chat_id jest wspólny dla wszystkich metod Telegram. Jeśli nie określisz chat_id jako parametru, platforma podasz identyfikator.
Zamiast przekazywać zawartość pliku w tekście, określ plik przy użyciu adresu URL i typu nośnika, jak pokazano w poniższym przykładzie.
W każdej wiadomości odbieranej przez bota z kanału ChannelData Telegram właściwość będzie zawierać komunikat wysłany wcześniej przez bota.

Ten fragment kodu przedstawia przykład channelData właściwości, która określa jedną metodę Telegram:

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

Ten fragment kodu przedstawia przykład channelData właściwości, która określa tablicę 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 zaimplementowaniu metody Telegram bot otrzyma komunikat odpowiedzi, w którym właściwość danych kanału jest wypełniana obiektem JSON. Ten obiekt odpowiedzi określa zawartość oryginalnego komunikatu, w tym co najwyżej jeden update_id opcjonalny parametr i. Aby uzyskać informacje na temat odbierania odpowiedzi przychodzących, zobacz Pobieranie aktualizacji.

Ten fragment kodu przedstawia przykład channelData właściwości w komunikacie odbieranym przez bota po utworzeniu ankiety:

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

Udostępnij za pośrednictwem

Implementowanie funkcji specyficznej dla kanału

Tworzenie niestandardowej wiadomości e-mail

Tworzenie powiadomienia w serwisie Facebook

Tworzenie komunikatu WIERSZA

Tworzenie komunikatu usługi Slack o pełnej wierności

Dodawanie bota do usługi Teams

Sprawdzanie i usuwanie wzmianki @bot

Tworzenie komunikatu telegramu

Dodatkowe zasoby

Dodatkowe zasoby