Implementieren von kanalspezifischer Funktionalität
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 |
---|---|
Senden und Empfangen einer E-Mail, die Text-, Betreff- und Wichtigkeitsmetadaten enthält. | |
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 angebenchat_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
}
}
}