Implementare funzionalità specifiche del canale con l'API bot Connector

Articolo
03/08/2023

Alcuni canali forniscono funzionalità che non possono essere implementate usando solo il testo del messaggio e gli allegati. Per implementare funzionalità specifiche del canale, è possibile passare metadati nativi a un canale nella proprietà dell'oggetto channelDataActivity. Ad esempio, il bot può usare la proprietà channelData 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à channelData di un'attività di tipo messaggio per implementare le funzionalità specifiche del canale seguenti:

Channel	Funzionalità
Email	Inviare e ricevere un messaggio di posta elettronica contenente corpo, oggetto e metadati della priorità
Slack	Inviare messaggi Slack con la massima fedeltà
Facebook	Inviare notifiche Facebook in modo nativo
Telegram	Eseguire azioni specifiche di Telegram, come la condivisione di un promemoria vocale o uno sticker

Nota

Il valore della proprietà channelData di un oggetto Activity è un oggetto JSON. La struttura dell'oggetto JSON varia a seconda del canale e della funzionalità implementata, come descritto di seguito.

Creare un messaggio di posta elettronica personalizzato

Per creare un messaggio di posta elettronica, impostare la proprietà channelData dell'oggetto Activity su un oggetto JSON contenente queste proprietà:

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

Questo frammento di codice mostra un esempio della proprietà channelData per un messaggio di posta elettronica personalizzato.

"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 un messaggio Slack con la massima fedeltà

Per creare un messaggio Slack con la massima fedeltà, impostare la proprietà channelData dell'oggetto Activity su un oggetto JSON che specifica messaggi Slack, allegati Slack e/o pulsanti Slack.

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à channelData è 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 al 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.

Creare una notifica Facebook

Per creare una notifica Facebook, impostare la proprietà channelData 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 Telegram

Per creare un messaggio che implementa azioni specifiche di Telegram, come la condivisione di un promemoria vocale o uno sticker, impostare la proprietà channelData 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.
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 mostra un esempio di una proprietà channelData che specifica un singolo metodo di Telegram.

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

Questo frammento mostra un esempio di una proprietà channelData che specifica una matrice di metodi di 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"
        }
    }
]

Condividi tramite

Implementare funzionalità specifiche del canale con l'API bot Connector

Creare un messaggio di posta elettronica personalizzato

Creare un messaggio Slack con la massima fedeltà

Creare una notifica Facebook

Creare un messaggio Telegram

Risorse aggiuntive

Risorse aggiuntive