Реализация возможностей для определенных каналов

Статья
03/08/2023

ПРИМЕНИМО К: Пакет SDK версии 4

Некоторые каналы предоставляют функции, которые нельзя реализовать только с текстом сообщения и вложениями. Чтобы реализовать функции, связанные с каналами, вы можете передать в канал собственные метаданные через свойство данных канала для объекта действия. Например, используя свойство данных канала, бот может передать в Telegram команду отправки наклейки или потребовать, чтобы из Office 365 было отправлено сообщение электронной почты.

В этой статье объясняется, как реализовать функции, связанные с каналами, на основе свойства данных канала в действии сообщения.

Channel	Функциональность
Электронная почта	Отправка и получение сообщения электронной почты с метаданными текста, темы и важности.
Facebook	Отправлять уведомления Facebook в собственном коде.
LINE	Отправка сообщения, реализующего типы сообщений, зависящие от LINE.
Slack	Отправлять полные сообщения Slack.
Teams	Обработка @-упоминаний в сообщениях Microsoft Teams.
Telegram	Выполнение действий, относящихся к Telegram, например предоставление общего доступа к голосовой памятке или наклейке.

Примечание

Значение свойства данных канала для объекта действия — это объект JSON. Поэтому в примерах в этой статье показан ожидаемый формат свойства JSON channelData в различных сценариях. Чтобы создать объект JSON с помощью .NET, используйте класс JObject (.NET).

Создание настраиваемого сообщения электронной почты

Чтобы создать пользовательское сообщение электронной почты, задайте для свойства действия channelData объект JSON, содержащий следующие свойства:

Свойство	Описание
bccRecipients	Строка адреса электронной почты, разделенная точками с запятой (;) для добавления к полю "Скрытая копия" сообщения.
ccRecipients	Строка адреса электронной почты, разделенная точками с запятой (;) для добавления к полю "Копия" сообщения.
htmlBody	Документ HTML, который задает текст сообщения электронной почты. Сведения о поддерживаемых элементах и атрибутах HTML приведены в документации по каналу.
importance	Уровень важности сообщения электронной почты. Допустимые значения: high, normal и low. Значение по умолчанию — normal.
toRecipients	Строка адреса электронной почты, разделенная точками с запятой (;) для добавления к полю "Кому" сообщения.

Исходящие и входящие сообщения между пользователем и ботом channelData могут иметь действие, содержащее объект JSON, свойства которого указаны в предыдущей таблице. В приведенном ниже фрагменте кода показан пример свойства для входящего пользовательского channelData сообщения электронной почты от бота пользователю.

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

Создание оповещения Facebook

Чтобы создать оповещение Facebook, присвойте свойству данных канала для объекта действия объект JSON, содержащий следующие свойства:

Свойство	Описание
notification_type	Тип уведомления, например REGULAR, SILENT_PUSH или NO_PUSH.
attachment	Вложение, которое содержит изображение, видео или другой тип мультимедиа, уведомление или другое шаблонное вложение, например квитанция.

Примечание

Дополнительные сведения о формате и содержании свойств notification_type и attachment см. в документации по API Facebook.

В этом фрагменте кода демонстрируется свойство channelData для вложения Facebook.

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

Создание сообщения LINE

Чтобы создать сообщение, реализующее типы сообщений line (например, наклейки, шаблоны или типы действий line, такие как открытие камеры телефона), задайте для свойства данных канала объекта действия объект действия объект JSON, указывающий типы сообщений LINE и типы действий.

Свойство	Описание
type	Имя типа сообщения или действия LINE

Поддерживаются следующие типы сообщений LINE:

наклейка;
гиперкарта;
шаблон (кнопка, подтверждение, карусель);
общая панель.

Эти действия LINE можно указать в поле действия объекта JSON типа сообщения:

обратная передача;
Сообщение
URI
средство выбора даты и времени;
Camera
галерея камеры;
Расположение

Дополнительные сведения об этих методах LINE и их параметрах см. в документации по API LINE Bot.

В этом фрагменте кода показан пример channelData свойства, указывающего тип ButtonTemplate сообщения канала и три типа действий: "camera", "cameraRoll" и "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"
            }
        ]
    }
}

Создание сообщение Slack с полным контролем

Чтобы создать сообщение Slack с полной точностью, присвойте свойству данных канала объекта действия значение объекта JSON, указывающее:

Примечание

Для включения поддержки кнопок в сообщениях Slack необходимо включить интерактивные сообщения при подключении бота к каналу Slack.

В этом фрагменте кода демонстрируется свойство channelData для пользовательского сообщения Slack.

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

Когда пользователь нажмет кнопку в сообщении Slack, бот получит ответное сообщение, в котором свойство данных канала содержит объект JSON payload. Этот объект payload определяет содержимое исходного сообщения, нажатую кнопку и идентификатор пользователя, который нажал эту кнопку.

В этом фрагменте кода показан пример свойства channelData в сообщении, которое бот получает при нажатии кнопки в сообщении Slack.

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

Бот может ответить на это сообщение обычным способом или отправить ответ напрямую на конечную точку, которая определена свойством response_url объекта payload. Сведения том, как и в каких случаях следует отправлять ответ для response_url, см. в документации по кнопкам Slack.

Динамические кнопки можно создать с помощью следующего 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"
                    }
                }
            ]
        }
    ]
}

Чтобы создать интерактивные меню, используйте такой код JSON:

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

Добавление бота в Teams

Добавленный в группу бот становится участником группы, которого можно упоминать (@mentioned) в ходе диалога. На самом деле боты получают сообщения только в том случае, если они имеют @mentionedзначение , поэтому другие беседы на канале не отправляются боту. См. сведения о ведении бесед в групповых чатах и каналах с помощью бота Microsoft Teams.

Так как боты в группе или канале отвечают только при упоминании (@botname) в сообщении, каждое сообщение, полученное ботом в канале группы, содержит собственное имя, и вы должны убедиться, что анализ сообщений обрабатывает это. Кроме того, боты могут распознавать имена других упомянутых пользователей и в свою очередь упоминать их в своих сообщениях.

Проверка и удаление упоминания @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();
}

Важно!

Добавлять бота по GUID не рекомендуется для других целей, кроме тестирования. В противном случае функциональность бота будет существенно ограничена. Боты, используемые в рабочей среде, следует добавлять в Teams как часть приложения. См. сведения о создании бота и тестировании и отладке бота Microsoft Teams.

Создание сообщения Telegram

Чтобы создать сообщение, которое реализует специальные действия Telegram, например предоставление в совместный доступ голосового напоминания или наклейки, присвойте свойству данных канала для объекта действия объект JSON, который определяет следующие свойства:

Свойство	Описание
method	Вызываемый метод API Telegram Bot.
параметры	Параметры указанного метода.

Поддерживаются следующие методы Telegram:

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

Дополнительные сведения об этих методах Telegram и их параметрах см. в документации по API Telegram Bot.

Примечание

Параметр chat_id применяется во всех методах Telegram. Если не указать chat_id в качестве параметра, платформа предоставит вам идентификатор.
Чтобы не передавать содержимое файла прямо в запросе, включите ссылку на файл через URL-адрес и тип носителя, как показано в следующем примере.
В каждом сообщении, которое бот получает из канала Telegram, свойство ChannelData содержит отправленное ранее сообщение.

В этом фрагменте кода показан пример channelData свойства, указывающего один метод Telegram:

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

В этом фрагменте кода показан пример channelData свойства, указывающего массив методов 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"
        }
    }
]

При реализации метода Telegram бот получит ответное сообщение, в котором свойство данных канала содержит объект JSON. Этот объект ответа определяет содержимое исходного сообщения, включая update_id и не более одного необязательного параметра. См. сведения о получении входящих ответов в руководстве по получению обновлений.

В этом фрагменте кода показан пример channelData свойства в сообщении, которое бот получает при создании опроса:

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

Поделиться через

Реализация возможностей для определенных каналов

Создание настраиваемого сообщения электронной почты

Создание оповещения Facebook

Создание сообщения LINE

Создание сообщение Slack с полным контролем

Добавление бота в Teams

Проверка и удаление упоминания @bot

Создание сообщения Telegram

Дополнительные ресурсы

Дополнительные ресурсы