Implement channel-specific functionality (Kanaalspecifieke functionaliteit implementeren)

Artikel
03/08/2023

VAN TOEPASSING OP: SDK v4

Sommige kanalen bieden functies die niet kunnen worden geïmplementeerd met alleen berichttekst en bijlagen. Als u kanaalspecifieke functionaliteit wilt implementeren, kunt u systeemeigen metagegevens doorgeven aan een kanaal in de eigenschap kanaalgegevens van het activiteitsobject . Uw bot kan bijvoorbeeld de eigenschap kanaalgegevens gebruiken 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 kanaalgegevens van een berichtactiviteit gebruikt om deze kanaalspecifieke functionaliteit te implementeren:

Kanaal	Functionaliteit
E-mail	Verzend en ontvang een e-mailbericht met metagegevens over de hoofdtekst, het onderwerp en de urgentie.
Facebook	Facebook-meldingen systeemeigen verzenden.
LIJN	Een bericht verzenden dat regelspecifieke berichttypen implementeert.
Slack	Volledige betrouwbaarheid Slack-berichten verzenden.
Teams	@-vermeldingen verwerken in Microsoft Teams-berichten.
Telegram	Telegram-specifieke acties uitvoeren, zoals het delen van een spraakmemo of een sticker.

Notitie

De waarde van de eigenschap kanaalgegevens van een activiteitsobject is een JSON-object. Daarom tonen de voorbeelden in dit artikel de verwachte indeling van de channelData JSON-eigenschap in verschillende scenario's. Als u een JSON-object wilt maken met behulp van .NET, gebruikt u de JObject klasse (.NET).

Een aangepast e-mailbericht maken

Als u een aangepast e-mailbericht wilt maken, stelt u de eigenschap activiteit channelData in op een JSON-object dat de volgende eigenschappen bevat:

Eigenschap	Beschrijving
bCCRecipients	Een puntkomma (;) een tekenreeks met e-mailadressen die u wilt toevoegen aan het veld BCC (blind carbon copy) van het bericht.
ccRecipients	Een puntkomma (;) gescheiden reeks e-mailadressen die u wilt toevoegen aan het veld CC (carbon copy) van het bericht.
htmlBody	Een HTML-document waarin de hoofdtekst van het e-mailbericht wordt opgegeven. Raadpleeg de documentatie van het kanaal voor informatie over ondersteunde HTML-elementen en -kenmerken.
importance	Het urgentieniveau van het e-mailbericht. Geldige waarden zijn hoog, normaal en laag. De standaardwaarde is normaal.
toRecipients	Een puntkomma (;) gescheiden reeks e-mailadressen die moeten worden toegevoegd aan het veld Aan van het bericht.

De uitgaande en binnenkomende berichten tussen de gebruiker en de bot kunnen een channelData activiteit hebben die een JSON-object bevat waarvan de eigenschappen zijn opgegeven in de vorige tabel. In het onderstaande fragment ziet u een voorbeeld van de channelData eigenschap voor een binnenkomend aangepast e-mailbericht, van de bot naar de gebruiker.

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

Een Facebook-melding maken

Als u een Facebook-melding wilt maken, stelt u de eigenschap kanaalgegevens van het activiteitsobject in op een JSON-object waarmee deze eigenschappen worden opgegeven:

Eigenschap	Beschrijving
notification_type	Het type melding, zoals REGULAR, SILENT_PUSH of NO_PUSH.
Bijlage	Een bijlage die een afbeelding, video of ander multimediatype opgeeft, 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 REGELbericht maken

Als u een bericht wilt maken waarin regelspecifieke berichttypen (zoals sticker, sjablonen of regelspecifieke actietypen, zoals het openen van de camera van de telefoon), worden geïmplementeerd, stelt u de eigenschap kanaalgegevens van het activiteitsobject in op een JSON-object dat line-berichttypen en actietypen specificeert.

Eigenschap	Beschrijving
type	De naam van het actie-/berichttype REGEL

Deze regelberichttypen worden ondersteund:

Sticker
Imagemap
Sjabloon (knop, bevestigen, carrousel)
Flex

Deze REGELacties kunnen worden opgegeven in het actieveld van het berichttype JSON-object:

Terugdraaien
Bericht
URI
Datetimerpicker
Camera
Camera-album
Locatie

Zie de DOCUMENTATIE van de LINE Bot API voor meer informatie over deze LINE-methoden en hun parameters.

Dit fragment toont een voorbeeld van een channelData eigenschap die een kanaalberichttype ButtonTemplate en drie actietypen opgeeft: 'camera', 'cameraRoll' en '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"
            }
        ]
    }
}

Een Slack-bericht met volledige kwaliteit maken

Als u een Slack-bericht met volledige kwaliteit wilt maken, stelt u de eigenschap kanaalgegevens van het activiteitsobject in op een JSON-object dat het volgende aangeeft:

Notitie

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

Dit codefragment 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 eigenschap kanaalgegevens 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 naar 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.

U kunt dynamische knoppen maken met behulp van de volgende JSON:

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

Gebruik de volgende JSON om interactieve menu's te maken:

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

Een bot toevoegen aan Teams

Bots die zijn toegevoegd aan een team, worden een ander teamlid, dat deel kan uitmaken @mentioned van het gesprek. Bots ontvangen zelfs alleen berichten wanneer ze dat zijn @mentioned, zodat andere gesprekken op het kanaal niet naar de bot worden verzonden. Zie Kanaal- en groepschatgesprekken met een Microsoft Teams-bot voor meer informatie.

Omdat bots in een groep of kanaal alleen reageren wanneer ze in een bericht worden vermeld,@botname bevat elk bericht dat door een bot in een groepskanaal wordt ontvangen, een eigen naam en moet u ervoor zorgen dat uw berichtparsering dit verwerkt. Bovendien kunnen bots andere vermelde gebruikers parseren en gebruikers vermelden als onderdeel van hun berichten.

Controleren op vermeldingen en verwijderen @bot

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

Belangrijk

Het toevoegen van een bot per GUID, voor iets anders dan testdoeleinden, wordt niet aanbevolen. Hierdoor wordt de functionaliteit van een bot ernstig beperkt. Bots in productie moeten worden toegevoegd aan Teams als onderdeel van een app. Zie Een bot maken en Uw Microsoft Teams-bot testen en fouten opsporen.

Een Telegram-bericht maken

Als u een bericht wilt maken waarin Telegram-specifieke acties worden geïmplementeerd, zoals het delen van een spraakmemo of een sticker, stelt u de eigenschap kanaalgegevens van het activiteitsobject 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 documentatie van de Telegram Bot API voor meer informatie over deze Telegram-methoden en hun parameters.

Notitie

De chat_id parameter is gemeenschappelijk voor alle Telegram-methoden. Als u niet opgeeft chat_id als parameter, geeft het framework de id voor u op.
In plaats van de 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 ontvangt van het Telegram-kanaal, 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 specificeert:

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

Wanneer een Telegram-methode is geïmplementeerd, ontvangt uw bot een antwoordbericht waarin de eigenschap kanaalgegevens wordt gevuld met een JSON-object. Dit antwoordobject geeft de inhoud van het oorspronkelijke bericht op, inclusief een update_id en maximaal één optionele parameter. Zie Updates ophalen voor meer informatie over het ontvangen van binnenkomende antwoorden.

In dit fragment ziet u een voorbeeld van de channelData eigenschap in het bericht dat een bot ontvangt wanneer een poll wordt gemaakt:

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

Delen via

Implement channel-specific functionality (Kanaalspecifieke functionaliteit implementeren)

Een aangepast e-mailbericht maken

Een Facebook-melding maken

Een REGELbericht maken

Een Slack-bericht met volledige kwaliteit maken

Een bot toevoegen aan Teams

Controleren op vermeldingen en verwijderen @bot

Een Telegram-bericht maken

Aanvullende resources

Aanvullende resources