Implémenter des fonctionnalités spécifiques au canal avec l’API Bot Connector

Article
03/08/2023

Certains canaux fournissent des fonctionnalités qui ne peuvent pas être implémentées en utilisant uniquement du texte de message et des pièces jointes. Pour implémenter des fonctionnalités spécifiques au canal, vous pouvez transmettre des métadonnées natives à un canal dans la propriété de l’objet channelDataActivity. Par exemple, votre bot peut utiliser la propriété channelData pour indiquer à Telegram d’envoyer un autocollant, ou pour demander à Office 365 d’envoyer un e-mail.

Cet article explique comment utiliser une propriété channelData d’activité de message pour implémenter cette fonctionnalité propre au canal :

Channel	Fonctionnalités
E-mail	Envoyer et recevoir un e-mail qui contient un corps, un objet et des métadonnées d’importance
Slack	Envoyer des messages Slack de fidélité
Facebook	Envoyer des notifications Facebook en mode natif
Telegram	Effectuer des actions spécifiques à Telegram, comme le partage d’un mémo vocal ou d’un autocollant

Remarque

La valeur d’une propriété channelData de l’objet Activity est un objet JSON. La structure de l’objet JSON varie en fonction du canal et des fonctionnalités implémentées, comme décrit ci-dessous.

Créer un message électronique personnalisé

Pour créer un e-mail, définissez la propriété channelData de l’objet Activity sur un objet JSON qui contient ces propriétés :

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

Cet extrait de code montre un exemple de la propriété channelData d’un e-mail personnalisé.

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

Créer un message Slack de fidélité optimale

Pour créer un message Slack de fidélité optimale, définissez la propriété channelData de l’objet Activity sur un objet JSON qui spécifie des messages Slack, des pièces jointes Slack et/ou des boutons Slack.

Remarque

Pour prendre en charge des boutons dans les messages Slack, vous devez activer Interactive Messages (Messages interactifs) lorsque vous connectez votre bot au canal Slack.

Cet extrait de code montre un exemple de la propriété channelData pour un message Slack personnalisé.

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

Lorsqu’un utilisateur clique sur un bouton dans un message Slack, votre bot reçoit un message de réponse dans lequel la propriété channelData est remplie par un objet JSON payload. L’objet payload précise le contenu du message d’origine, il identifie le bouton qui a été cliqué et identifie l’utilisateur qui a cliqué sur le bouton.

Cet extrait de code montre un exemple de la propriété channelData dans le message reçu par un bot lorsqu’un utilisateur clique sur un bouton dans le message Slack.

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

Votre bot peut répondre à ce message normalement, ou il peut publier sa réponse directement sur le point de terminaison spécifié par la propriété response_url de l’objet payload. Pour plus d’informations sur le moment et la façon de publier une réponse sur response_url, consultez Slack Buttons.

Créer une notification Facebook

Pour créer une notification Facebook, définissez la propriété channelData de l’objet Activity sur un objet JSON qui contient ces propriétés :

Propriété	Description
notification_type	Type de notification (par exemple, REGULAR, SILENT_PUSH ou NO_PUSH).
attachment	Pièce jointe qui spécifie une image, une vidéo ou un autre type multimédia, ou encore une pièce jointe basée sur un modèle, comme un accusé de réception.

Remarque

Pour plus d’informations sur le format et le contenu de la propriété notification_type et de la propriété attachment, consultez la documentation de l’API Facebook.

Cet extrait de code montre un exemple de la propriété channelData pour une pièce jointe d’accusé de réception de Facebook.

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

Créer un message Telegram

Pour créer un message qui implémente des actions propres à Telegram, tels que le partage d’un mémo vocal ou d’un autocollant, définissez la propriété channelData de l’objet Activity sur un objet JSON qui spécifie ces propriétés :

Propriété	Description
method	Méthode de l’API Bot Telegram à appeler.
parameters	Paramètres de la méthode spécifiée.

Les méthodes Telegram prises en charge sont les suivantes :

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

Pour plus d’informations sur ces méthodes Telegram et leurs paramètres, consultez la documentation de l’API Bot Telegram.

Remarque

Le paramètre chat_id est commun à toutes les méthodes Telegram. Si vous ne spécifiez chat_id pas en tant que paramètre, l’infrastructure fournit l’ID pour vous.
Au lieu de passer le contenu de fichier inline, spécifiez le fichier à l’aide d’une URL et d’un type de média, comme indiqué dans l’exemple ci-dessous.
Dans chaque message que votre bot reçoit du canal Telegram, la propriété channelData inclut le message précédemment envoyé par votre bot.

Cet extrait de code montre l’exemple d’une propriété channelData qui spécifie une méthode Telegram unique.

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

Cet extrait de code montre l’exemple d’une propriété channelData qui spécifie un tableau de méthodes 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"
        }
    }
]

Implémenter des fonctionnalités spécifiques au canal avec l’API Bot Connector

Créer un message électronique personnalisé

Créer un message Slack de fidélité optimale

Créer une notification Facebook

Créer un message Telegram

Ressources supplémentaires

Ressources supplémentaires