Implementación de la funcionalidad específica del canal con Bot Connector API

Artículo
03/08/2023

Algunos canales proporcionan características que no se pueden implementar mediante solo texto de mensaje y datos adjuntos. Para implementar la funcionalidad específica del canal, puede pasar metadatos nativos a un canal en la propiedad del channelData objeto Activity. Por ejemplo, el bot puede usar la propiedad channelData para indicar a Telegram que envíe un adhesivo o para indicar a Office 365 que envíe un correo electrónico.

En este artículo se describe cómo usar la propiedad channelData de la actividad de un mensaje para implementar esta funcionalidad específica de canal:

Canal	Funcionalidad
Email	Envío y recepción de un correo electrónico que contiene metadatos de importancia, cuerpo y asunto.
Slack	Envío de mensajes de Slack de plena fidelidad.
Facebook	Envío de notificaciones de Facebook de forma nativa.
Telegram	Acciones específicas de Telegram, como compartir una nota de voz o un adhesivo.

Nota:

El valor de la propiedad channelData de un objeto Activity es un objeto JSON. La estructura del objeto JSON variará según el canal y la funcionalidad que se implementa, tal como se describe a continuación.

Crear un mensaje de correo electrónico personalizado

Para crear un mensaje de correo electrónico, establezca la propiedad channelData del objeto Activity en un objeto JSON que contenga estas propiedades:

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

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un mensaje de correo electrónico personalizado.

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

Crear un mensaje de Slack de plena fidelidad

Para crear un mensaje de Slack de plena fidelidad, establezca la propiedad channelData del objeto Activity en un objeto JSON que especifique mensajes de Slack, adjuntos de Slack o botones de Slack.

Nota:

Para admitir botones en los mensajes de Slack, debe habilitar Mensajes interactivos cuando conecte el bot al canal de Slack.

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un mensaje de Slack personalizado.

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

Cuando un usuario hace clic en un botón dentro de un mensaje de Slack, el bot recibirá un mensaje de respuesta en el que la propiedad channelData se rellena con un objeto JSON payload. El objeto payload especifica el contenido del mensaje original, identifica el botón donde se hizo clic e identifica al usuario que hizo clic en el botón.

En este fragmento de código se muestra un ejemplo de la propiedad channelData en el mensaje que recibe un bot cuando un usuario hace clic en un botón en el mensaje de Slack.

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

El bot puede responder a este mensaje de la forma normal o puede registrar su respuesta directamente en punto de conexión que haya especificado la propiedad response_url del objeto payload. Para obtener información sobre cuándo y cómo publicar una respuesta en response_url, consulte Botones de Slack.

Crear una notificación de Facebook

Para crear una notificación de Facebook, establezca la propiedad channelData del objeto Activity en un objeto JSON que especifique estas propiedades:

Propiedad	Descripción
notification_type	Tipo de notificación (por ejemplo, REGULAR, SILENT_PUSH o NO_PUSH).
attachment	Un elemento adjunto que especifica una imagen, un vídeo u otro tipo de elemento multimedia, o un adjunto con plantilla como, por ejemplo, un recibo.

Nota:

Para obtener más información sobre el formato y el contenido de la propiedad notification_type y la propiedad attachment, consulte la documentación de la API de Facebook.

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un elemento adjunto con recibo de Facebook.

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

Crear un mensaje de Telegram

Para crear un mensaje que implemente las acciones específicas de Telegram, como compartir una nota de voz o un sticker, establezca la propiedad channelData del objeto Activity en un objeto JSON que especifique estas propiedades:

Propiedad	Descripción
method	El método de Telegram Bot API al que se llamará.
parámetros	Los parámetros del método especificado.

Se admiten los métodos de Telegram siguientes:

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

Para obtener más información sobre estos métodos de Telegram y sus parámetros, consulte la documentación de Telegram Bot API.

Nota:

El parámetro chat_id es común a todos los métodos de Telegram. Si no especifica chat_id como parámetro, el marco proporcionará el identificador.
En lugar de pasar el contenido del archivo insertado, especifique el archivo mediante una dirección URL y el tipo de medio, tal como se muestra en el ejemplo siguiente.
Dentro de cada mensaje que recibe su bot del canal de Telegram, la propiedad channelData incluirá el mensaje que su bot envió anteriormente.

En este fragmento de código se muestra un ejemplo de una propiedad channelData que especifica un único método de Telegram.

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

En este fragmento de código se muestra un ejemplo de una propiedad channelData que especifica una matriz de métodos de 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"
        }
    }
]

Compartir a través de

Implementación de la funcionalidad específica del canal con Bot Connector API

Crear un mensaje de correo electrónico personalizado

Crear un mensaje de Slack de plena fidelidad

Crear una notificación de Facebook

Crear un mensaje de Telegram

Recursos adicionales

Recursos adicionales