Implementieren von Kanal spezifischer Funktionalität mit der bot-Connector-APIImplement channel-specific functionality with the Bot Connector API

Einige Kanäle bieten Funktionen, die nicht implementiert werden können, indem nur Nachrichtentext und Anlagen verwendet werden.Some channels provide features that cannot be implemented by using only message text and attachments. Um kanalspezifische Funktionen zu implementieren, können Sie native Metadaten an einen Kanal in der Eigenschaft channelData des [Activity[]]-Objekts übergeben.To implement channel-specific functionality, you can pass native metadata to a channel in the [Activity[]] object's channelData property. 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.For example, your bot can use the channelData property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

Dieser Artikel beschreibt, wie Sie die Eigenschaft channelData einer Nachrichtenaktivität verwenden, um diese kanalspezifische Funktionalität zu implementieren:This article describes how to use a message activity's channelData property to implement this channel-specific functionality:

ChannelChannel FunktionalitätFunctionality
EmailEmail Senden und Empfangen einer E-Mail mit Text, Betreff und wichtigen MetadatenSend and receive an email that contains body, subject, and importance metadata
PufferSlack Senden originalgetreuer Slack-NachrichtenSend full fidelity Slack messages
FacebookFacebook Natives Senden von Facebook-BenachrichtigungenSend Facebook notifications natively
TelegramTelegram Ausführen von Telegram-spezifischen Aktionen, z.B. Freigeben einer Sprachnachricht oder eines StickersPerform Telegram-specific actions, such as sharing a voice memo or a sticker
KikKik Senden und Empfangen nativer Kik-NachrichtenSend and receive native Kik messages

Hinweis

Der Wert der channelData-Eigenschaft eines Activity-Objekts ist ein JSON-Objekt.The value of an Activity object's channelData property is a JSON object. Die Struktur des JSON-Objekts variiert in Abhängigkeit von dem implementierten Kanal und der implementierten Funktionalität, wie nachfolgend beschrieben.The structure of the JSON object will vary according to the channel and the functionality being implemented, as described below.

Benutzerdefinierte e-Mail-Nachricht erstellenCreate a custom email message

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:To create an email message, set the Activity object's channelData property to a JSON object that contains these properties:

EigenschaftProperty BESCHREIBUNGDescription
htmlBodyhtmlBody Der HTML-Code, der für den Text der Nachricht verwendet werden soll.The HTML to use for the body of the message.
subjectsubject Der Betreff, der für die Nachricht verwendet werden soll.The subject to use for the message.
importanceimportance Das Prioritätsflag, das für die Nachricht verwendet werden soll: low, normal oder high.The importance flag to use for the message: low, normal, or high.
toRecipientstoRecipients Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „An“ der Nachricht eingefügt werden sollen.A semicolon (;) delimited string of email addresses to add to the message's To field.
ccRecipientsccRecipients Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „Cc“ (Carbon Copy) der Nachricht eingefügt werden sollen.A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
bccRecipientsbccRecipients Eine durch ein Semikolon (;) getrennte Zeichenfolge von E-Mail-Adressen, die in das Feld „Bcc“ (Blind Carbon Copy) der Nachricht eingefügt werden sollen.A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData-Eigenschaft für eine benutzerdefinierte E-Mail-Nachricht.This snippet shows an example of the channelData property for a custom email message.

"channelData":
{
    "htmlBody": "<html><body style = /"font-family: Calibri; font-size: 11pt;/" >This is more than awesome.</body></html>",
    "subject": "Super awesome message subject",
    "importance": "high",
    "ccRecipients": "Yasemin@adatum.com;Temel@adventure-works.com"
}

Erstellen einer originalgetreuen Slack-NachrichtCreate a full-fidelity Slack message

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.To create a full-fidelity Slack message, set the Activity object's channelData property to a JSON object that specifies Slack messages, Slack attachments, and/or Slack buttons.

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.To support buttons in Slack messages, you must enable Interactive Messages when you connect your bot to the Slack channel.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData-Eigenschaft für eine benutzerdefinierte Slack-Nachricht.This snippet shows an example of the channelData property for a custom Slack message.

"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.When a user clicks a button within a Slack message, your bot will receive a response message in which the channelData property is populated with a payload JSON object. Das payload-Objekt gibt den Inhalt der ursprünglichen Nachricht an und identifiziert die angeklickte Schaltfläche sowie den Benutzer, der diese angeklickt hat.The payload object specifies contents of the original message, identifies the button that was clicked, and identifies the user who clicked the button.

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.This snippet shows an example of the channelData property in the message that a bot receives when a user clicks a button in the Slack message.

"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.Your bot can reply to this message in the normal manner, or it can post its response directly to the endpoint that is specified by the payload object's response_url property. Weitere Informationen dazu, wann und wie Sie eine Antwort an response_url posten können, finden Sie im Artikel zu Slack-Schaltflächen.For information about when and how to post a response to the response_url, see Slack Buttons.

Erstellen einer Facebook-BenachrichtigungCreate a Facebook notification

Um eine Facebook-Nachricht zu erstellen, legen Sie die channelData-Eigenschaft des Activity-Objekts auf ein JSON-Objekt fest, das diese Eigenschaften angibt:To create a Facebook notification, set the Activity object's channelData property to a JSON object that specifies these properties:

EigenschaftProperty BESCHREIBUNGDescription
notification_typenotification_type Der Typ der Benachrichtigung (z.B. REGULAR, SILENT_PUSH, NO_PUSH)The type of notification (e.g., REGULAR, SILENT_PUSH, NO_PUSH).
attachmentattachment Eine Anlage, die ein Bild, ein Video oder einen anderen Multimediatyp angibt bzw. eine auf Vorlagen basierende Anlage, z.B. eine BestätigungAn attachment that specifies an image, video, or other multimedia type, or a templated attachment such as a receipt.

Hinweis

Ausführliche Informationen zum Format und Inhalt der Eigenschaften notification_type und attachment finden Sie in der Dokumentation zur Facebook-API.For details about format and contents of the notification_type property and attachment property, see the Facebook API documentation.

Dieser Codeausschnitt zeigt ein Beispiel der channelData-Eigenschaft für eine Facebook-Anlage vom Typ „Bestätigung“.This snippet shows an example of the channelData property for a Facebook receipt attachment.

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

Erstellen einer Telegram-NachrichtCreate a Telegram message

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:To create a message that implements Telegram-specific actions, such as sharing a voice memo or a sticker, set the Activity object's channelData property to a JSON object that specifies these properties:

EigenschaftProperty BESCHREIBUNGDescription
methodmethod Die aufzurufende Telegram-Bot-API-MethodeThe Telegram Bot API method to call.
parametersparameters Die Parameter der angegebenen MethodeThe parameters of the specified method.

Die folgenden Telegram-Methoden werden unterstützt:These Telegram methods are supported:

  • answerInlineQueryanswerInlineQuery
  • editMessageCaptioneditMessageCaption
  • editMessageReplyMarkupeditMessageReplyMarkup
  • editMessageTexteditMessageText
  • forwardMessageforwardMessage
  • kickChatMemberkickChatMember
  • sendAudiosendAudio
  • sendChatActionsendChatAction
  • sendContactsendContact
  • sendDocumentsendDocument
  • sendLocationsendLocation
  • sendMessagesendMessage
  • sendPhotosendPhoto
  • sendStickersendSticker
  • sendVenuesendVenue
  • sendVideosendVideo
  • sendVoicesendVoice
  • unbanChateMemberunbanChateMember

Weitere Informationen zu diesen Telegram-Methoden und ihren Parametern finden Sie in der Telegram-Bot-API-Dokumentation.For details about these Telegram methods and their parameters, see the Telegram Bot API documentation.

Hinweis

  • Der chat_id-Parameter gilt für alle Telegram-Methoden.The chat_id parameter is common to all Telegram methods. Wenn Sie chat_id nicht als Parameter angeben, stellt das Framework die ID für die Sie bereit.If you do not specify chat_id as a parameter, the framework will provide the ID for you.
  • Anstatt Dateiinhalte inline zu übergeben, geben Sie die Datei über eine URL und einen Medientyp an, wie im Beispiel unten gezeigt.Instead of passing file contents inline, specify the file using a URL and media type as shown in the example below.
  • In jeder Nachricht, die Ihr Bot vom Telegram-Kanal empfängt, enthält die channelData-Eigenschaft die Nachricht, die Ihr Bot zuvor gesendet hat.Within each message that your bot receives from the Telegram channel, the channelData property will include the message that your bot sent previously.

Dieser Codeausschnitt zeigt ein Beispiel für eine channelData-Eigenschaft, die eine einzelne Telegram-Methode angibt.This snippet shows an example of a channelData property that specifies a single Telegram method.

"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.This snippet shows an example of a channelData property that specifies an array of Telegram methods.

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

Erstellen einer nativen Kik-NachrichtCreate a native Kik message

Um eine native Kik-Nachricht zu erstellen, legen Sie die channelData-Eigenschaft des Activity-Objekts auf ein JSON-Objekt fest, das diese Eigenschaft angibt:To create a native Kik message, set the Activity object's channelData property to a JSON object that specifies this property:

EigenschaftProperty BESCHREIBUNGDescription
Cloud an das Gerätmessages Ein Array von Kik-Nachrichten.An array of Kik messages. Weitere Informationen zum Kik-Nachrichtenformat finden Sie im Artikel zu Kik-Nachrichtenformaten.For details about Kik message format, see Kik Message Formats.

Dieser Codeausschnitt zeigt ein Beispiel für die channelData-Eigenschaft für eine native Kik-Nachricht.This snippet shows an example of the channelData property for a native Kik message.

"channelData": {
    "messages": [
        {
            "chatId": "c6dd8165…",
            "type": "link",
            "to": "kikhandle",
            "title": "My Webpage",
            "text": "Some text to display",
            "url": "http://botframework.com",
            "picUrl": "http://lorempixel.com/400/200/",
            "attribution": {
                "name": "My App",
                "iconUrl": "http://lorempixel.com/50/50/"
            },
            "noForward": true,
            "kikJsData": {
                    "key": "value"
                }
        }
    ]
}

Zusätzliche RessourcenAdditional resources