Implementar una funcionalidad específica de canal

Artículo
03/08/2023

SE APLICA A: SDK v4

Algunos canales proporcionan características que no se pueden implementar solo con texto de mensaje y datos adjuntos. Para implementar una funcionalidad específica de canal, puede pasar los metadatos nativos a un canal en la propiedad channel data del objeto activity. Por ejemplo, el bot puede usar la propiedad channel data 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 channel data de la actividad de un mensaje para implementar esta funcionalidad específica de canal:

Canal	Funcionalidad
Correo electrónico	Envíe y reciba un correo electrónico que contenga metadatos de cuerpo, asunto e importancia.
Facebook	Enviar notificaciones de Facebook de forma nativa.
LINE	Envíe un mensaje que implemente tipos de mensaje específicos de LINE.
Slack	Enviar mensajes de Slack de fidelidad completa.
Teams	Controle @-mentions en los mensajes de Microsoft Teams.
Telegram	Realizar acciones específicas de Telegram, como compartir un memo de voz o una pegatina.

Nota:

El valor de la propiedad channel data de un objeto activity es un objeto JSON. Por lo tanto, los ejemplos de este artículo muestran el formato esperado de la propiedad JSON channelData en distintos escenarios. Para crear un objeto JSON con. NET, use la clase JObject (.NET).

Crear un mensaje de correo electrónico personalizado

Para crear un mensaje de correo electrónico personalizado, establezca la propiedad activity channelData en un objeto JSON que contenga las siguientes propiedades:

Propiedad	Descripción
bccRecipients	Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CCO (copia carbón oculta) del mensaje.
ccRecipients	Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CC (copia carbón) del mensaje.
htmlBody	Un documento HTML que especifique el cuerpo del mensaje de correo electrónico. Consulte la documentación del canal para obtener información acerca de los atributos y elementos HTML compatibles.
importance	Nivel de importancia del correo electrónico. Los valores válidos son high, normal y low. El valor predeterminado es normal.
toRecipients	Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo Para del mensaje.

Los mensajes salientes y entrantes entre el usuario y el bot pueden tener una channelData actividad que contiene un objeto JSON cuyas propiedades se especifican en la tabla anterior. En el fragmento de código siguiente se muestra un ejemplo de la channelData propiedad de un mensaje de correo electrónico personalizado entrante, desde el bot al usuario.

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

Crear una notificación de Facebook

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

Propiedad	Descripción
notification_type	Tipo de notificación, como 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",
            //...
        }
    }
}

Creación de un mensaje de LINE

Para crear un mensaje que implemente tipos de mensaje específicos de LINE (como adhesivos, plantillas o tipos de acción específicos de LINE, como abrir la cámara del teléfono), establezca la propiedad de datos de canal del objeto de actividad en un objeto JSON que especifique los tipos de mensaje LINE y los tipos de acción.

Propiedad	Descripción
type	Nombre del tipo de acción o mensaje de LINE

Se admiten estos tipos de mensajes de LINE:

Sticker
Imagemap
Template (Button, confirm, carousel)
Flex

Estas acciones de LINE se pueden especificar en el campo de acción del objeto JSON de tipo de mensaje:

Postback
Message
URI
Datetimerpicker
Cámara
Camera roll
Location

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

Este fragmento de código muestra un ejemplo de una channelData propiedad que especifica un tipo ButtonTemplate de mensaje de canal y tres tipos de acción: "camera", "cameraRoll" y "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"
            }
        ]
    }
}

Crear un mensaje de Slack de plena fidelidad

Para crear un mensaje de Slack de plena fidelidad, establezca la propiedad de datos del canal del objeto de actividad en un objeto JSON que especifique:

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 channel data 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.

Puede crear botones dinámicos con el siguiente código 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"
                    }
                }
            ]
        }
    ]
}

Para crear menús interactivos, use el siguiente código 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Agregar un bot a Teams

Los bots que se agregan a un equipo se convierten en otro miembro del equipo, al que se puede @mentionedmencionar como parte de la conversación. De hecho, los bots solo reciben mensajes cuando son @mentioned, por lo que no se envían otras conversaciones en el canal al bot. Para más información, consulte Conversaciones de chat de canal y grupo con un bot de Microsoft Teams.

Dado que los bots de un grupo o canal solo responden cuando se mencionan (@botname) en un mensaje, cada mensaje recibido por un bot de un canal de grupo contiene su propio nombre y debe asegurarse de que el análisis de mensajes lo controla. Además, los bots pueden analizar otros usuarios mencionados y mencionar a usuarios como parte de sus mensajes.

Buscar y quitar menciones @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();
}

Importante

No se recomienda agregar un bot por GUID, con fines distintos de las pruebas. Si lo hace, se limitará en gran medida la funcionalidad de un bot. Los bots de producción se deben agregar a Teams como parte de una aplicación. Consulte Creación de un bot y Prueba y depuración del bot de Microsoft Teams.

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 adhesivo, establezca la propiedad sticker 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.

Este fragmento de código muestra un ejemplo de una channelData propiedad que especifica un único método telegrama:

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

Este fragmento de código muestra un ejemplo de una channelData propiedad 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"
        }
    }
]

Cuando se implementa un método de Telegram, el bot recibirá un mensaje de respuesta en el que la propiedad channelData se rellena con un objeto JSON. Este objeto de respuesta especifica el contenido del mensaje original, incluido un elemento update_id y, como máximo, un parámetro opcional. Para obtener información acerca de cómo recibir respuestas entrantes, consulte Getting updates (Obtención de actualizaciones).

Este fragmento de código muestra un ejemplo de la channelData propiedad en el mensaje que recibe un bot cuando se crea un sondeo:

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

Implementar una funcionalidad específica de canal

Crear un mensaje de correo electrónico personalizado

Crear una notificación de Facebook

Creación de un mensaje de LINE

Crear un mensaje de Slack de plena fidelidad

Agregar un bot a Teams

Buscar y quitar menciones @bot

Crear un mensaje de Telegram

Recursos adicionales

Recursos adicionales