Implementera kanalspecifika funktioner

Artikel
03/08/2023

GÄLLER FÖR: SDK v4

Vissa kanaler innehåller funktioner som inte kan implementeras med endast meddelandetext och bifogade filer. Om du vill implementera kanalspecifika funktioner kan du skicka inbyggda metadata till en kanal i aktivitetsobjektets kanaldataegenskap . Din robot kan till exempel använda egenskapen kanaldata för att instruera Telegram att skicka en dekal eller instruera Office365 att skicka ett e-postmeddelande.

Den här artikeln beskriver hur du använder en meddelandeaktivitets kanaldataegenskap för att implementera den här kanalspecifika funktionen:

Kanal	Funktioner
E-post	Skicka och ta emot ett e-postmeddelande som innehåller metadata för brödtext, ämne och prioritet.
Facebook	Skicka Facebook-meddelanden internt.
LINJE	Skicka ett meddelande som implementerar LINE-specifika meddelandetyper.
Slack	Skicka Slack-meddelanden med fullständig återgivning.
Teams	Hantera @-omnämnanden i Microsoft Teams-meddelanden.
Telegram	Utför Telegram-specifika åtgärder, till exempel att dela ett röstmemorandum eller ett klistermärke.

Anteckning

Värdet för ett aktivitetsobjekts kanaldataegenskap är ett JSON-objekt. Därför visar exemplen i den här artikeln det förväntade formatet för channelData JSON-egenskapen i olika scenarier. Om du vill skapa ett JSON-objekt med hjälp av .NET använder du JObject klassen (.NET).

Skapa ett anpassat e-postmeddelande

Om du vill skapa ett anpassat e-postmeddelande anger du aktivitetsegenskapen channelData till ett JSON-objekt som innehåller följande egenskaper:

Egenskap	Beskrivning
bccRecipients	Ett semikolon (;) avgränsad sträng med e-postadresser som ska läggas till i meddelandets hemlig kopia (blind kopia).
ccRecipients	Ett semikolon (;) avgränsad sträng med e-postadresser som ska läggas till i meddelandets fält Kopia (kopia).
htmlBody	Ett HTML-dokument som anger brödtexten i e-postmeddelandet. I kanalens dokumentation finns information om HTML-element och attribut som stöds.
prioritet	E-postmeddelandets prioritetsnivå. Giltiga värden är höga, normala och låga. Standardvärdet är normalt.
toRecipients	Ett semikolon (;) avgränsad sträng med e-postadresser som ska läggas till i meddelandets till-fält.

Utgående och inkommande meddelanden mellan användaren och roboten kan ha en channelData aktivitet som innehåller ett JSON-objekt vars egenskaper anges i föregående tabell. Kodfragmentet nedan visar ett exempel på channelData egenskapen för ett inkommande anpassat e-postmeddelande, från roboten till användaren.

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

Skapa ett Facebook-meddelande

Om du vill skapa ett Facebook-meddelande anger du aktivitetsobjektets kanaldataegenskap till ett JSON-objekt som anger följande egenskaper:

Egenskap	Beskrivning
notification_type	Typ av meddelande, till exempel REGULAR, SILENT_PUSH eller NO_PUSH.
Bifogad fil	En bifogad fil som anger en bild, video eller annan multimediatyp eller en bifogad mall, till exempel ett kvitto.

Anteckning

Mer information om format och innehåll för notification_type egenskapen finns attachment i Facebook API-dokumentationen.

Det här kodfragmentet visar ett exempel på channelData egenskapen för en bifogad Facebook-kvittobilaga.

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

Skapa ett LINE-meddelande

Om du vill skapa ett meddelande som implementerar RADspecifika meddelandetyper (till exempel klistermärken, mallar eller RADspecifika åtgärdstyper som att öppna telefonkameran) ställer du in aktivitetsobjektets kanaldataegenskap på ett JSON-objekt som anger RAD-meddelandetyper och åtgärdstyper.

Egenskap	Beskrivning
typ	Radåtgärdens/meddelandetypens namn

Dessa RAD-meddelandetyper stöds:

Klistermärke
Bildkarta
Mall (knapp, bekräfta, karusell)
Flex

Dessa LINE-åtgärder kan anges i åtgärdsfältet i meddelandetypens JSON-objekt:

Återst.
Meddelande
URI
Datetimerpicker
Kamera
Kamerarulle
Location

Mer information om dessa LINE-metoder och deras parametrar finns i dokumentationen för LINE Bot API.

Det här kodfragmentet visar ett exempel på en channelData egenskap som anger en kanalmeddelandetyp ButtonTemplate och tre åtgärdstyper: "kamera", "cameraRoll" och "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"
            }
        ]
    }
}

Skapa ett Slack-meddelande med fullständig återgivning

Om du vill skapa ett Slack-meddelande med fullständig återgivning anger du aktivitetsobjektets kanaldataegenskap till ett JSON-objekt som anger:

Anteckning

Om du vill ha stöd för knappar i Slack-meddelanden måste du aktivera interaktiva meddelanden när du ansluter roboten till Slack-kanalen.

Det här kodfragmentet visar ett exempel på channelData egenskapen för ett anpassat Slack-meddelande.

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

När en användare klickar på en knapp i ett Slack-meddelande får roboten ett svarsmeddelande där kanaldataegenskapen fylls med ett payload JSON-objekt. Objektet payload anger innehållet i det ursprungliga meddelandet, identifierar knappen som klickades och identifierar användaren som klickade på knappen.

Det här kodfragmentet visar ett exempel på channelData egenskapen i meddelandet som en robot tar emot när en användare klickar på en knapp i Slack-meddelandet.

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

Roboten kan svara på det här meddelandet på vanligt sätt, eller så kan den publicera sitt svar direkt till den slutpunkt som anges av payload objektets response_url -egenskap. Information om när och hur du publicerar ett svar på finns i response_urlSlack-knappar.

Du kan skapa dynamiska knappar med hjälp av följande 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"
                    }
                }
            ]
        }
    ]
}

Använd följande JSON för att skapa interaktiva menyer:

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

Lägga till en robot i Teams

Robotar som läggs till i ett team blir en annan teammedlem, som kan ingå @mentioned i konversationen. I själva verket tar robotar bara emot meddelanden när de är @mentioned, så andra konversationer på kanalen skickas inte till roboten. Mer information finns i Kanal- och gruppchattkonversationer med en Microsoft Teams-robot.

Eftersom robotar i en grupp eller kanal bara svarar när de nämns (@botname) i ett meddelande innehåller varje meddelande som tas emot av en robot i en gruppkanal sitt eget namn, och du måste se till att meddelandeparsningen hanterar det. Dessutom kan robotar parsa ut andra användare som nämns och nämna användare som en del av sina meddelanden.

Sök efter och ta bort @bot omnämnande

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

Viktigt

Att lägga till en robot efter GUID, för något annat än testningsändamål, rekommenderas inte. Om du gör det begränsas funktionaliteten för en robot avsevärt. Robotar i produktion bör läggas till i Teams som en del av en app. Se Skapa en robot och Testa och felsöka din Microsoft Teams-robot.

Skapa ett Telegram-meddelande

Om du vill skapa ett meddelande som implementerar Telegram-specifika åtgärder, till exempel att dela ett röstmemorandum eller en dekal, anger du aktivitetsobjektets kanaldataegenskap till ett JSON-objekt som anger följande egenskaper:

Egenskap	Beskrivning
metod	Den Telegram Bot API-metod som ska anropas.
parametrar	Parametrarna för den angivna metoden.

Dessa Telegram-metoder stöds:

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

Mer information om dessa Telegram-metoder och deras parametrar finns i Telegram Bot API-dokumentationen.

Anteckning

Parametern chat_id är gemensam för alla Telegram-metoder. Om du inte anger chat_id som en parameter tillhandahåller ramverket ID:t åt dig.
I stället för att skicka infogat filinnehåll anger du filen med hjälp av en URL och medietyp enligt exemplet nedan.
I varje meddelande som roboten tar emot från Telegram-kanalen ChannelData innehåller egenskapen det meddelande som roboten skickade tidigare.

Det här kodfragmentet visar ett exempel på en channelData egenskap som anger en enda Telegram-metod:

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

Det här kodfragmentet visar ett exempel på en channelData egenskap som anger en matris med Telegram-metoder:

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

När en Telegram-metod implementeras får roboten ett svarsmeddelande där kanaldataegenskapen fylls med ett JSON-objekt. Det här svarsobjektet anger innehållet i det ursprungliga meddelandet, inklusive en update_id och högst en valfri parameter. Information om hur du tar emot inkommande svar finns i Hämta uppdateringar.

Det här kodfragmentet visar ett exempel på channelData egenskapen i meddelandet som en robot tar emot när en avsökning skapas:

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

Dela via

Implementera kanalspecifika funktioner

Skapa ett anpassat e-postmeddelande

Skapa ett Facebook-meddelande

Skapa ett LINE-meddelande

Skapa ett Slack-meddelande med fullständig återgivning

Lägga till en robot i Teams

Sök efter och ta bort @bot omnämnande

Skapa ett Telegram-meddelande

Ytterligare resurser

Ytterligare resurser