Реализация функций, зависящих от канала, с помощью API Bot Connector

Статья
03/08/2023

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

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

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

Примечание

Значение свойства channelData объекта Activity — это объект JSON. Структура этого объекта JSON будет разной в зависимости от канала и реализованных функций, как описано ниже.

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

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

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

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

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

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

Чтобы создать сообщение Slack с полным контролем, присвойте свойству channelData объекта Activity объект JSON, который определяет сообщения, вложения и (или) кнопки Slack.

Примечание

Для включения поддержки кнопок в сообщениях 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, бот получит ответное сообщение, в котором свойство channelData содержит объект 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.

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

Чтобы создать оповещение Facebook, присвойте свойству channelData объекта Activity объект 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",
            //...
        }
    }
}

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

Чтобы создать сообщение, которое реализует специальные действия Telegram, например предоставление в совместный доступ голосового напоминания или наклейки, присвойте свойству channelData объекта Activity объект 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"
        }
    }
]

Реализация функций, зависящих от канала, с помощью API Bot Connector

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

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

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

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

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

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