Implementieren von kanalspezifischer Funktionalität

Artikel
03/08/2023

GILT FÜR: SDK v4

Einige Kanäle bieten Features, die nicht nur mit Nachrichtentext und Anlagen implementiert werden können. Um kanalspezifische Funktionen zu implementieren, können Sie native Metadaten an einen Kanal in der channel data-Eigenschaft des Aktivitätsobjekts übergeben. Beispielsweise kann Ihr Bot die „channel data“-Eigenschaft verwenden, um Telegram anzuweisen, einen Sticker zu senden, oder um Office 365 anzuweisen, eine E-Mail zu senden.

In diesem Artikel wird beschrieben, wie Sie die „channel data“-Eigenschaft einer Nachrichtenaktivität verwenden, um diese kanalspezifische Funktionalität zu implementieren:

Channel	Funktionalität
E-Mail	Senden und Empfangen einer E-Mail, die Text-, Betreff- und Wichtigkeitsmetadaten enthält.
Facebook	Senden sie nativ Facebook-Benachrichtigungen.
LINE	Senden Sie eine Nachricht, die LINE-spezifische Nachrichtentypen implementiert.
Puffer	Senden von Slack-Nachrichten mit voller Genauigkeit.
Teams	Behandeln von @-Erwähnungen in Microsoft Teams-Nachrichten.
Telegram	Führen Sie Telegram-spezifische Aktionen aus, z. B. das Freigeben eines Sprachnotizbuchs oder eines Aufklebers.

Hinweis

Der Wert der „channel data“-Eigenschaft eines Aktivitätsobjekts ist ein JSON-Objekt. Deswegen zeigen die Beispiele in diesem Artikel das erwartete Format der JSON-Eigenschaft channelData in verschiedenen Szenarien. Verwenden Sie die (.NET-)Klasse JObject, um ein JSON-Objekt mit .NET zu erstellen.

Erstellen einer benutzerdefinierten E-Mail-Nachricht

Um eine benutzerdefinierte E-Mail-Nachricht zu erstellen, legen Sie die Aktivitätseigenschaft channelData auf ein JSON-Objekt fest, das die folgenden Eigenschaften enthält:

Eigenschaft	BESCHREIBUNG
bccRecipients	Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „Bcc“ (Blind Carbon Copy) der Nachricht eingefügt werden sollen.
ccRecipients	Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „Cc“ (Carbon Copy) der Nachricht eingefügt werden sollen.
htmlBody	Ein HTML-Dokument, das den E-Mail-Nachrichtentext angibt. Weitere Informationen zu den unterstützten HTML-Elementen und -Attributen finden Sie in der Dokumentation des Kanals.
importance	Die Wichtigkeit der E-Mail. Gültige Werte sind Hoch, Normal und Niedrig. Der Standardwert ist Normal.
toRecipients	Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „An“ der Nachricht eingefügt werden sollen.

Die ausgehenden und eingehenden Nachrichten zwischen dem Benutzer und dem Bot verfügen möglicherweise über eine channelData Aktivität, die ein JSON-Objekt enthält, dessen Eigenschaften in der vorherigen Tabelle angegeben sind. Der folgende Codeausschnitt zeigt ein Beispiel für die channelData -Eigenschaft für eine eingehende benutzerdefinierte E-Mail-Nachricht vom Bot an den Benutzer.

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

Erstellen einer Facebook-Benachrichtigung

Um eine Facebook-Nachricht zu erstellen, legen Sie die „channel data“-Eigenschaft des Aktivitätsobjekts auf ein JSON-Objekt fest, das diese Eigenschaften angibt:

Eigenschaft	BESCHREIBUNG
notification_type	Der Typ der Benachrichtigung, z. B. REGULAR, SILENT_PUSH oder NO_PUSH.
attachment	Eine Anlage, die ein Bild, ein Video oder einen anderen Multimediatyp angibt bzw. eine auf Vorlagen basierende Anlage, z.B. eine Bestätigung

Hinweis

Ausführliche Informationen zum Format und Inhalt der Eigenschaften notification_type und attachment finden Sie in der Dokumentation zur Facebook-API.

Dieser Codeausschnitt zeigt ein Beispiel der channelData-Eigenschaft für eine Facebook-Anlage vom Typ „Bestätigung“.

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

Erstellen einer LINE-Nachricht

Um eine Nachricht zu erstellen, die LINE-spezifische Nachrichtentypen implementiert (z. B. Aufkleber, Vorlagen oder LINE-spezifische Aktionstypen wie das Öffnen der Telefonkamera), legen Sie die Kanaldateneigenschaft des Aktivitätsobjekts auf ein JSON-Objekt fest, das LINE-Nachrichtentypen und Aktionstypen angibt.

Eigenschaft	BESCHREIBUNG
type	Name des LINE-Aktionstyps bzw. -Nachrichtentyps

Diese LINE-Nachrichtentypen werden unterstützt:

Sticker
Imagemap
Template (Button, confirm, carousel)
Flex

Diese LINE-Aktionen können im Aktionsfeld des JSON-Objekts für den Nachrichtentyp angegeben werden:

Postback
`Message`
URI
Datetimerpicker
Camera
Camera roll
Standort

Weitere Informationen zu diesen LINE-Methoden und ihren Parametern finden Sie in der LINE-Bot-API-Dokumentation.

Dieser Codeausschnitt zeigt ein Beispiel für eine channelData Eigenschaft, die einen Kanalnachrichtentyp ButtonTemplate und drei Aktionstypen angibt: "camera", "cameraRoll" und "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"
            }
        ]
    }
}

Erstellen einer originalgetreuen Slack-Nachricht

Um eine Slack-Nachricht mit voller Genauigkeit zu erstellen, legen Sie die Kanaldateneigenschaft des Aktivitätsobjekts auf ein JSON-Objekt fest, das Folgendes angibt:

Hinweis

Um Schaltflächen in Slack-Nachrichten zu unterstützen, müssen Sie interaktive Nachrichten aktivieren, wenn Sie Ihren Bot mit dem Slack-Kanal verbinden.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData-Eigenschaft für eine benutzerdefinierte Slack-Nachricht.

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

Wenn ein Benutzer auf eine Schaltfläche in einer Slack-Nachricht klickt, erhält der Bot eine Antwortnachricht, in der die „channel data“-Eigenschaft mit einem JSON-Objekt vom Typ payload gefüllt ist. Das payload-Objekt gibt den Inhalt der ursprünglichen Nachricht an und identifiziert die angeklickte Schaltfläche sowie den Benutzer, der diese angeklickt hat.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData-Eigenschaft in der Nachricht, die ein Bot empfängt, wenn ein Benutzer auf eine Schaltfläche in der Slack-Nachricht klickt.

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

Ihr Bot kann auf diese Nachricht normal antworten oder seine Antwort direkt an den Endpunkt posten, der durch die response_url-Eigenschaft des payload-Objekts angegeben ist. Weitere Informationen dazu, wann und wie Sie eine Antwort an response_url posten können, finden Sie im Artikel zu Slack-Schaltflächen.

Sie können dynamische Schaltflächen mithilfe des folgenden JSON-Codes erstellen:

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

Verwenden Sie zum Erstellen interaktiver Menüs den folgenden JSON-Code:

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

Hinzufügen eines Bots zu Teams

Bots, die einem Team hinzugefügt werden, werden zu einem weiteren Teammitglied und können im Rahmen der Konversation erwähnt (@mentioned) werden. Tatsächlich empfangen Bots nur Nachrichten, wenn sie sind @mentioned, sodass andere Unterhaltungen im Kanal nicht an den Bot gesendet werden. Weitere Informationen finden Sie unter Channel and Group chat conversations with a Microsoft Teams bot (Kanal- und Gruppenchatkonversationen mit einem Microsoft Teams-Bot).

Da Bots in einer Gruppe oder einem Kanal nur antworten, wenn sie in einer Nachricht erwähnt werden (@botname), enthält jede nachricht, die von einem Bot in einem Gruppenkanal empfangen wird, einen eigenen Namen, und Sie müssen sicherstellen, dass die Nachrichtenanalyse dies verarbeitet. Darüber hinaus können Bots andere erwähnte Benutzer herausfiltern sowie ihrerseits Benutzer in ihren Nachrichten erwähnen.

Überprüfen auf und Entfernen von @bot-Erwähnungen

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

Wichtig

Das Hinzufügen eines Bots per GUID zu anderen Zwecken als zu Testzwecken wird nicht empfohlen. Durch diese Vorgehensweise wird die Funktionalität eines Bots erheblich eingeschränkt. Bots in der Produktionsumgebung sollten Teams als Teil einer App hinzugefügt werden. Weitere Informationen finden Sie unter Create a bot (Erstellen eines Bots) sowie unter Test and debug your Microsoft Teams bot (Testen und Debuggen Ihres Microsoft Teams-Bots).

Erstellen einer Telegram-Nachricht

Um eine Nachricht zu erstellen, die Telegram-spezifische Aktionen implementiert, z.B. die Freigabe einer Sprachnotiz oder eines Stickers, legen Sie die „channel data“-Eigenschaft des Aktivitätsobjekts auf ein JSON-Objekt fest, das diese Eigenschaften angibt:

Eigenschaft	BESCHREIBUNG
method	Die aufzurufende Telegram-Bot-API-Methode
parameters	Die Parameter der angegebenen Methode

Die folgenden Telegram-Methoden werden unterstützt:

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

Weitere Informationen zu diesen Telegram-Methoden und ihren Parametern finden Sie in der Telegram-Bot-API-Dokumentation.

Hinweis

Der chat_id-Parameter gilt für alle Telegram-Methoden. Wenn Sie keinen Parameter angeben chat_id , stellt das Framework die ID für Sie bereit.
Anstatt Dateiinhalte inline zu übergeben, geben Sie die Datei über eine URL und einen Medientyp an, wie im Beispiel unten gezeigt.
In jeder Nachricht, die Ihr Bot vom Telegram-Kanal empfängt, enthält die ChannelData-Eigenschaft die Nachricht, die Ihr Bot zuvor gesendet hat.

Dieser Codeausschnitt zeigt ein Beispiel für eine channelData Eigenschaft, die eine einzelne Telegram-Methode angibt:

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

Dieser Codeausschnitt zeigt ein Beispiel für eine channelData Eigenschaft, die ein Array von Telegram-Methoden angibt:

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

Bei Implementierung einer Telegram-Methode erhält der Bot eine Antwortnachricht, in der die Kanaldateneigenschaft mit einem JSON-Objekt gefüllt wird. Dieses Antwortobjekt gibt den Inhalt der ursprünglichen Nachricht an und enthält eine Aktualisierungs-ID (update_id) sowie maximal einen optionalen Parameter. Informationen zum Empfangen eingehender Antworten finden Sie unter Erhalten von Aktualisierungen.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData Eigenschaft in der Nachricht, die ein Bot empfängt, wenn eine Umfrage erstellt wird:

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

Implementieren von kanalspezifischer Funktionalität

Erstellen einer benutzerdefinierten E-Mail-Nachricht

Erstellen einer Facebook-Benachrichtigung

Erstellen einer LINE-Nachricht

Erstellen einer originalgetreuen Slack-Nachricht

Hinzufügen eines Bots zu Teams

Überprüfen auf und Entfernen von @bot-Erwähnungen

Erstellen einer Telegram-Nachricht

Zusätzliche Ressourcen

Zusätzliche Ressourcen