Implémenter une fonctionnalité spécifique du canal

Article
03/08/2023

S’APPLIQUE À : KIT de développement logiciel (SDK) v4

Certains canaux fournissent des fonctionnalités qui ne peuvent pas être implémentées uniquement avec du texte de message et des pièces jointes. Pour implémenter une fonctionnalité spécifique à un canal, vous pouvez transmettre des métadonnées natives à un canal dans la propriété des données du canal de l’objet d’activité. Par exemple, votre bot peut utiliser la propriété des données du canal 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é des données du canal de l’activité de message pour implémenter cette fonctionnalité propre au canal :

Channel	Fonctionnalités
E-mail	Envoyez et recevez un e-mail contenant des métadonnées de corps, d’objet et d’importance.
Facebook	Envoyer des notifications Facebook en mode natif.
LIGNE	Envoyez un message qui implémente des types de messages spécifiques à LINE.
Slack	Envoyez des messages Slack de fidélité totale.
Équipes	Gérer les @-mentions dans les messages Microsoft Teams.
Telegram	Effectuez des actions spécifiques à Telegram, telles que le partage d’un mémo vocal ou d’un autocollant.

Remarque

La valeur de la propriété des données du canal d’un objet d’activité est un objet JSON. Par conséquent, les exemples de cet article montrent le format attendu de la propriété JSON channelData dans divers scénarios. Pour créer un objet JSON à l’aide de .NET, utilisez la classe (.NET) JObject.

Créer un message électronique personnalisé

Pour créer un message électronique personnalisé, définissez la propriété d’activité channelData sur un objet JSON qui contient les propriétés suivantes :

Propriété	Description
bccRecipients	Chaîne d’adresses e-mail séparées par un point-virgule (;) à ajouter au champ Cci (copie carbone invisible) du message.
ccRecipients	Chaîne d’adresses e-mail séparées par un point-virgule (;) à ajouter au champ Cc (copie carbone) du message.
htmlBody	Document HTML qui spécifie le corps de l’e-mail. Consultez la documentation du canal pour obtenir plus d’informations sur les éléments et attributs HTML pris en charge.
importance	Niveau d’importance de l’e-mail. Les valeurs valides sont high (haute), normal et low (faible). La valeur par défaut est normal.
toRecipients	Chaîne d’adresses e-mail séparées par un point-virgule (;) à ajouter au champ À du message.

Les messages sortants et entrants entre l’utilisateur et le bot peuvent avoir une channelData activité qui contient un objet JSON dont les propriétés sont spécifiées dans le tableau précédent. L’extrait de code ci-dessous montre un exemple de propriété channelData pour un message électronique personnalisé entrant, du bot à l’utilisateur.

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

Créer une notification Facebook

Pour créer une notification Facebook, définissez la propriété des données du canal de l’objet d’activité sur un objet JSON spécifiant ces propriétés :

Propriété	Description
notification_type	Type de notification, tel que 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 LINE

Pour créer un message qui implémente des types de messages spécifiques à LINE (tels que des autocollants, des modèles ou des types d’actions spécifiques à LINE comme l’ouverture de l’appareil photo du téléphone), définissez la propriété de données de canal de l’objet d’activité sur un objet JSON qui spécifie les types de messages LINE et les types d’actions.

Propriété	Description
type	Nom du type d’action/message LINE

Ces types de messages LINE sont pris en charge :

Sticker
Imagemap
Template (Button, Confirm, Carousel)
Flex

Ces actions LINE peuvent être spécifiées dans le champ Action de l’objet JSON du type de message :

Postback
Message
URI
Datetimerpicker
Caméra
Pellicule
Emplacement

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

Cet extrait de code montre un channelData exemple de propriété qui spécifie un type ButtonTemplate de message de canal et trois types d’action : « camera », « cameraRoll » et « 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"
            }
        ]
    }
}

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

Pour créer un message Slack de fidélité totale, définissez la propriété de données de canal de l’objet d’activité sur un objet JSON qui spécifie :

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é des données du canal est renseignée 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.

Vous pouvez créer des boutons dynamiques à l’aide du code JSON suivant :

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

Pour créer des menus interactifs, utilisez le JSON suivant :

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

Ajouter un bot à Teams

Les bots ajoutés à une équipe deviennent un autre membre de l’équipe, qui peut être indiqué comme @mentioned, dans le cadre de la conversation. En fait, les bots ne reçoivent des messages que lorsqu’ils sont @mentioned, de sorte que les autres conversations sur le canal ne sont pas envoyées au bot. Pour plus d’informations, consultez Conversations de canal et de groupe avec un bot Microsoft Teams.

Étant donné que les bots d’un groupe ou d’un canal répondent uniquement lorsqu’ils sont mentionnés (@botname) dans un message, chaque message reçu par un bot dans un canal de groupe contient son propre nom, et vous devez vous assurer que votre analyse de message gère cela. De plus, les bots peuvent analyser d’autres utilisateurs mentionnés et mentionner des utilisateurs dans le cadre de leurs messages.

Rechercher et supprimer la mention @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();
}

Important

L’ajout d’un bot par GUID, à des fins autres que de test, n’est pas recommandé. Ceci limite fortement les fonctionnalités d’un bot. Les bots en production doivent être ajoutés à Teams dans le cadre d’une application. Consultez Créer un bot et Tester et déboguer votre bot Microsoft Teams.

Créer un message Telegram

Pour créer un message qui implémente des actions spécifiques de Telegram, telles que le partage d’un mémo vocal ou d’un autocollant, définissez la propriété des données du canal de l’objet d’activité 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 vous fournira l’ID.
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 un exemple de channelData propriété qui spécifie une seule méthode Telegram :

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

Cet extrait de code montre un exemple de channelData propriété 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"
        }
    }
]

Quand une méthode Telegram est implémentée, votre bot reçoit un message de réponse dans lequel la propriété des données du canal est renseignée avec un objet JSON. Cet objet de réponse spécifie le contenu du message d’origine, y compris un update_id et éventuellement un seul paramètre facultatif. Pour plus d’informations sur la réception des réponses entrantes, consultez Obtenir des mises à jour.

Cet extrait de code montre un exemple de propriété channelData dans le message qu’un bot reçoit lors de la création d’un sondage :

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

Share via

Implémenter une fonctionnalité spécifique du canal

Créer un message électronique personnalisé

Créer une notification Facebook

Créer un message LINE

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

Ajouter un bot à Teams

Rechercher et supprimer la mention @bot

Créer un message Telegram

Ressources supplémentaires

Ressources supplémentaires