Implementare funzionalità specifiche del canale

Articolo
03/08/2023

SI APPLICA A: SDK v4

Alcuni canali forniscono funzionalità che non possono essere implementate solo con testo e allegati di messaggi. Per implementare funzionalità specifiche del canale, è possibile passare metadati nativi a un canale nella proprietà channel data dell'oggetto activity. Ad esempio, il bot può usare la proprietà channel data per indicare a Telegram di inviare uno sticker o a Office365 di inviare un messaggio di posta elettronica.

Questo articolo illustra come usare la proprietà channel data di un'attività di tipo messaggio per implementare queste funzionalità specifiche del canale:

Channel	Funzionalità
Posta elettronica	Inviare e ricevere un messaggio di posta elettronica contenente metadati corpo, oggetto e importanza.
Facebook	Inviare notifiche di Facebook in modo nativo.
LINE	Inviare un messaggio che implementa tipi di messaggi specifici della riga.
Slack	Inviare messaggi Slack con fedeltà completa.
Teams	Gestire le @-mention nei messaggi di Microsoft Teams.
Telegram	Eseguire azioni specifiche di Telegram, ad esempio la condivisione di un memo vocale o un adesivo.

Nota

Il valore della proprietà channel data di un oggetto activity è un oggetto JSON. Di conseguenza, gli esempi di questo articolo illustrano il formato previsto della proprietà JSON channelData in vari scenari. Per creare un oggetto JSON con .NET usare la classe JObject (.NET).

Creare un messaggio di posta elettronica personalizzato

Per creare un messaggio di posta elettronica personalizzato, impostare la proprietà activity channelData su un oggetto JSON contenente le proprietà seguenti:

Proprietà	Descrizione
bccRecipients	Stringa di indirizzi di posta elettronica delimitata da punto e virgola (;) da aggiungere al campo Ccn (copia per conoscenza nascosta).
ccRecipients	Stringa di indirizzi di posta elettronica delimitata da punto e virgola (;) da aggiungere al campo Cc (copia per conoscenza).
htmlBody	Un documento HTML che specifica il corpo del messaggio di posta elettronica. Per informazioni sugli elementi HTML e gli attributi supportati, vedere la documentazione del canale.
importance	Il livello di importanza del messaggio di posta elettronica. I valori validi sono high, normal e low. Il valore predefinito è normal.
toRecipients	Stringa di indirizzi di posta elettronica delimitata da punto e virgola (;) da aggiungere al campo A.

I messaggi in uscita e in ingresso tra l'utente e il bot possono avere un'attività che contiene un channelData oggetto JSON le cui proprietà vengono specificate nella tabella precedente. Il frammento di codice seguente mostra un esempio della channelData proprietà per un messaggio di posta elettronica personalizzato in ingresso, dal bot all'utente.

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

Creare una notifica Facebook

Per creare una notifica Facebook, impostare la proprietà channel data dell'oggetto activity su un oggetto JSON che specifica queste proprietà:

Proprietà	Descrizione
notification_type	Tipo di notifica, ad esempio REGULAR, SILENT_PUSH o NO_PUSH.
attachment	Allegato che specifica un'immagine, un video o un altro tipo di elemento multimediale oppure allegato basato su modelli come una ricevuta.

Nota

Per informazioni dettagliate sul formato e sul contenuto delle proprietà notification_type e attachment, vedere la documentazione dell'API Facebook.

Questo frammento mostra un esempio della proprietà channelData per un allegato Facebook di tipo ricevuta.

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

Creare un messaggio LINE

Per creare un messaggio che implementa tipi di messaggi specifici della linea (ad esempio adesivi, modelli o tipi di azione specifici della linea, ad esempio l'apertura della fotocamera del telefono), impostare la proprietà dei dati del canale dell'oggetto attività su un oggetto JSON che specifica tipi di messaggio LINE e tipi di azione.

Proprietà	Descrizione
type	Il nome del tipo di messaggio/azione di LINE

Sono supportati questi tipi di messaggio di LINE:

Sticker
Imagemap
Template (pulsante, conferma, sequenza)
Flex

Nel campo dell'azione dell'oggetto JSON del tipo di messaggio è possibile specificare queste azioni di LINE:

Postback
Message
URI
Datetimerpicker
Camera
CameraRoll
Location

Per informazioni dettagliate su questi metodi di LINE e sui rispettivi parametri, vedere la documentazione dell'API Bot Line.

Questo frammento di codice mostra un esempio di proprietà che specifica un tipo di ButtonTemplate messaggio di canale e tre tipi di channelData azione: "fotocamera", "cameraRoll" e "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"
            }
        ]
    }
}

Creare un messaggio Slack con la massima fedeltà

Per creare un messaggio Slack con fedeltà completa, impostare la proprietà dei dati del canale dell'oggetto activity su un oggetto JSON che specifica:

Nota

Per supportare i pulsanti nei messaggi Slack, è necessario abilitare Interactive Messages (Messaggi interattivi) al momento della connessione del bot al canale Slack.

Questo frammento mostra un esempio della proprietà channelData per un messaggio Slack personalizzato.

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

Quando un utente fa clic su un pulsante in un messaggio Slack, il bot riceve un messaggio di risposta in cui la proprietà channel data è popolata con un oggetto JSON payload. L'oggetto payload specifica il contenuto del messaggio originale e identifica il pulsante selezionato e l'utente che ha fatto clic sul pulsante.

Questo frammento mostra un esempio della proprietà channelData nel messaggio che un bot riceve quando un utente fa clic su un pulsante nel messaggio Slack.

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

Il bot può rispondere a questo messaggio in modo normale oppure inviare la risposta direttamente all'endpoint specificato dalla proprietà response_url dell'oggetto payload. Per informazioni su come e quando inviare una risposta a response_url, vedere il documento relativo ai pulsanti Slack.

È possibile creare pulsanti dinamici usando il codice JSON seguente:

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

Per creare menu interattivi, usare il codice JSON seguente:

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

Aggiungere un bot a Teams

I bot aggiunti a un team diventano un altro membro del team e possono essere @mentioned durante la conversazione. Infatti, i bot ricevono solo messaggi quando sono @mentioned, quindi altre conversazioni sul canale non vengono inviate al bot. Per altre informazioni, vedere Conversazioni chat di gruppo e di canale con un bot Microsoft Teams.

Poiché i bot in un gruppo o un canale rispondono solo quando vengono menzionati (@botname) in un messaggio, ogni messaggio ricevuto da un bot in un canale di gruppo contiene il proprio nome e è necessario assicurarsi che l'analisi dei messaggi gestisca tale operazione. I bot possono inoltre analizzare altri utenti menzionati e menzionare utenti nei propri messaggi.

Cercare e rimuovere la menzione @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();
}

Importante

L'aggiunta di un bot da GUID, per scopi diversi da quelli di test, non è consigliata. Questa operazione limita infatti notevolmente la funzionalità di un bot. Per aggiungere bot in produzione a Teams, è necessario includerli in un'app. Vedere Creare un bot e Testare ed eseguire il debug del bot Microsoft Teams.

Creare un messaggio Telegram

Per creare un messaggio che implementa azioni specifiche di Telegram, come la condivisione di un promemoria vocale o di uno sticker, impostare la proprietà channel data dell'oggetto activity su un oggetto JSON che specifica queste proprietà:

Proprietà	Descrizione
method	Il metodo di Telegram Bot API da chiamare.
parametri	I parametri del metodo specificato.

Sono supportati i metodi di Telegram seguenti:

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

Per informazioni dettagliate su questi metodi di Telegram e i rispettivi parametri, vedere la documentazione di Telegram Bot API.

Nota

Il parametro chat_id è comune a tutti i metodi di Telegram. Se non si specifica chat_id come parametro, il framework fornirà l'ID per l'utente.
Anziché passare il contenuto del file inline, specificare il file con un URL e il tipo di elemento multimediale come illustrato nell'esempio di seguito.
In ogni messaggio che il bot riceve dal canale Telegram, la proprietà ChannelData includerà il messaggio inviato in precedenza dal bot.

Questo frammento di codice mostra un esempio di channelData proprietà che specifica un singolo metodo Telegram:

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

Questo frammento di codice mostra un esempio di channelData proprietà che specifica una matrice di metodi Telegram:

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

Quando viene implementato un metodo Telegram, il bot riceve un messaggio di risposta in cui la proprietà channel data è popolata con un oggetto JSON. Questo oggetto response specifica il contenuto del messaggio originale, incluso un update_id e, al massimo, un parametro facoltativo. Per informazioni sulla ricezione di risposte in ingresso, vedere la sezione sul recupero degli aggiornamenti.

Questo frammento di codice mostra un esempio della channelData proprietà nel messaggio che un bot riceve quando viene creato un polling:

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

Implementare funzionalità specifiche del canale

Creare un messaggio di posta elettronica personalizzato

Creare una notifica Facebook

Creare un messaggio LINE

Creare un messaggio Slack con la massima fedeltà

Aggiungere un bot a Teams

Cercare e rimuovere la menzione @bot

Creare un messaggio Telegram

Risorse aggiuntive

Risorse aggiuntive