Delen via

Kanaalspecifieke functionaliteit implementeren met de Bot Connector-API

  • Artikel

Sommige kanalen bieden functies die niet kunnen worden geïmplementeerd door alleen berichttekst en bijlagen te gebruiken. Als u kanaalspecifieke functionaliteit wilt implementeren, kunt u systeemeigen metagegevens doorgeven aan een kanaal in de eigenschap van channelData het object Activity. Uw bot kan de eigenschap bijvoorbeeld gebruiken channelData om Telegram de opdracht te geven een sticker te verzenden of office365 te instrueren een e-mail te verzenden.

In dit artikel wordt beschreven hoe u de eigenschap van channelData een berichtactiviteit gebruikt om deze kanaalspecifieke functionaliteit te implementeren:

Kanaal Functionaliteit
E-mail Een e-mailbericht verzenden en ontvangen met metagegevens over hoofdtekst, onderwerp en urgentie
Slack Slack-berichten met volledige betrouwbaarheid verzenden
Facebook Systeemeigen Facebook-meldingen verzenden
Telegram Telegram-specifieke acties uitvoeren, zoals het delen van een spraakmemo of een sticker

Notitie

De waarde van de eigenschap van een Activity object channelData is een JSON-object. De structuur van het JSON-object is afhankelijk van het kanaal en de functionaliteit die wordt geïmplementeerd, zoals hieronder wordt beschreven.

Een aangepast e-mailbericht maken

Als u een e-mailbericht wilt maken, stelt u de eigenschap van channelData het Activity object in op een JSON-object dat deze eigenschappen bevat:

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

Dit fragment toont een voorbeeld van de channelData eigenschap voor een aangepast e-mailbericht.

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

Een Slack-bericht met volledige betrouwbaarheid maken

Als u een Slack-bericht met volledige kwaliteit wilt maken, stelt u de eigenschap van channelData het Activity object in op een JSON-object waarin Slack-berichten, Slack-bijlagen en/of Slack-knoppen worden opgegeven.

Notitie

Als u knoppen in Slack-berichten wilt ondersteunen, moet u Interactieve berichten inschakelen wanneer u uw bot verbindt met het Slack-kanaal.

Dit fragment toont een voorbeeld van de channelData eigenschap voor een aangepast Slack-bericht.

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

Wanneer een gebruiker op een knop in een Slack-bericht klikt, ontvangt uw bot een antwoordbericht waarin de channelData eigenschap wordt gevuld met een payload JSON-object. Het payload object geeft de inhoud van het oorspronkelijke bericht aan, identificeert de knop waarop is geklikt en identificeert de gebruiker die op de knop heeft geklikt.

Dit fragment toont een voorbeeld van de channelData eigenschap in het bericht dat een bot ontvangt wanneer een gebruiker op een knop in het Slack-bericht klikt.

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

Uw bot kan dit bericht op de normale manier beantwoorden of het antwoord rechtstreeks posten op het eindpunt dat is opgegeven door de eigenschap van response_url het payload object. Zie Slack-knoppen voor informatie over wanneer en hoe u een antwoord op de response_urlplaatst.

Een Facebook-melding maken

Als u een Facebook-melding wilt maken, stelt u de eigenschap van channelData het Activity object in op een JSON-object waarin deze eigenschappen worden opgegeven:

Eigenschap Beschrijving
notification_type Het type melding (zoals REGULAR, SILENT_PUSH of NO_PUSH).
Bijlage Een bijlage met een afbeelding, video of ander multimediatype, of een sjabloonbijlage, zoals een ontvangstbewijs.

Notitie

Zie de Facebook API-documentatie voor meer informatie over de notification_type indeling en inhoud van de eigenschap en attachment eigenschap.

Dit fragment toont een voorbeeld van de channelData eigenschap voor een Facebook-ontvangstbevestigingsbijlage.

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

Een Telegram-bericht maken

Als u een bericht wilt maken waarmee Telegram-specifieke acties worden geïmplementeerd, zoals het delen van een spraakmemo of een sticker, stelt u de eigenschap van channelData het Activity object in op een JSON-object waarin deze eigenschappen worden opgegeven:

Eigenschap Beschrijving
method De Telegram Bot API-methode om aan te roepen.
parameters De parameters van de opgegeven methode.

Deze Telegram-methoden worden ondersteund:

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

Zie de Telegram Bot API-documentatie voor meer informatie over deze Telegram-methoden en hun parameters.

Notitie

  • De chat_id parameter is gebruikelijk voor alle Telegram-methoden. Als u niet opgeeft chat_id als parameter, geeft het framework de id voor u op.
  • In plaats van bestandsinhoud inline door te geven, geeft u het bestand op met behulp van een URL en mediatype, zoals wordt weergegeven in het onderstaande voorbeeld.
  • In elk bericht dat uw bot van het Telegram-kanaal ontvangt, bevat de channelData eigenschap het bericht dat uw bot eerder heeft verzonden.

Dit fragment toont een voorbeeld van een channelData eigenschap die een enkele Telegram-methode opgeeft.

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

Dit fragment toont een voorbeeld van een channelData eigenschap die een matrix van Telegram-methoden opgeeft.

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

Aanvullende resources