Implementieren kanalspezifischer Funktionen mit der Bot Connector-API

Artikel
03/08/2023

Einige Kanäle bieten Features, die nicht nur mithilfe von Nachrichtentext und Anlagen implementiert werden können. Um kanalspezifische Funktionen zu implementieren, können Sie native Metadaten in der Eigenschaft des channelDataActivity-Objekts an einen Kanal übergeben. Zum Beispiel kann Ihr Bot die Eigenschaft channelData verwenden, um Telegram anzuweisen, einen Sticker zu senden, oder um Office 365 anzuweisen, eine E-Mail zu senden.

Dieser Artikel beschreibt, wie Sie die Eigenschaft channelData einer Nachrichtenaktivität verwenden, um diese kanalspezifische Funktionalität zu implementieren:

Channel	Funktionalität
Email	Senden und Empfangen einer E-Mail mit Text, Betreff und wichtigen Metadaten
Puffer	Senden originalgetreuer Slack-Nachrichten
Facebook	Natives Senden von Facebook-Benachrichtigungen
Telegram	Ausführen von Telegram-spezifischen Aktionen, z.B. Freigeben einer Sprachnachricht oder eines Stickers

Hinweis

Der Wert der channelData-Eigenschaft eines Activity-Objekts ist ein JSON-Objekt. Die Struktur des JSON-Objekts variiert in Abhängigkeit von dem implementierten Kanal und der implementierten Funktionalität, wie nachfolgend beschrieben.

Erstellen einer benutzerdefinierten E-Mail-Nachricht

Um eine E-Mail-Nachricht zu erstellen, legen Sie die channelData-Eigenschaft des Activity-Objekts auf ein JSON-Objekt fest, das diese Eigenschaften enthält:

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

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

"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 originalgetreuen Slack-Nachricht

Um eine originalgetreue Slack-Nachricht zu erstellen, setzen Sie die channelData-Eigenschaft des Activity-Objekts auf ein JSON-Objekt, das Slack-Nachrichten, Slack-Anlagen und/oder Slack-Schaltflächen festlegt.

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 channelData-Eigenschaft mit einem JSON-Objekt 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.

Erstellen einer Facebook-Benachrichtigung

Um eine Facebook-Nachricht zu erstellen, legen Sie die channelData-Eigenschaft des Activity-Objekts 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 Telegram-Nachricht

Um eine Nachricht zu erstellen, die Telegram-spezifische Aktionen implementiert, z.B. die Freigabe einer Sprachnotiz oder eines Stickers, setzen Sie die channelData-Eigenschaft des Activity-Objekts auf ein JSON-Objekt, 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 Telegram-Methodenarray 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"
        }
    }
]

Implementieren kanalspezifischer Funktionen mit der Bot Connector-API

Erstellen einer benutzerdefinierten E-Mail-Nachricht

Erstellen einer originalgetreuen Slack-Nachricht

Erstellen einer Facebook-Benachrichtigung

Erstellen einer Telegram-Nachricht

Zusätzliche Ressourcen

Zusätzliche Ressourcen