Implementar una funcionalidad específica de canalImplement channel-specific functionality

se aplica a: SDK V4APPLIES TO: SDK v4

Algunos canales proporcionan características que no se pueden implementar usando únicamente el texto y los datos adjuntos del mensaje.Some channels provide features that cannot be implemented by using only message text and attachments. Para implementar una funcionalidad específica de canal, puede pasar los metadatos nativos a un canal en la propiedad channel data del objeto activity.To implement channel-specific functionality, you can pass native metadata to a channel in the activity object's channel data property. 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.For example, your bot can use the channel data property to instruct Telegram to send a sticker or to instruct Office365 to send an email.

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:This article describes how to use a message activity's channel data property to implement this channel-specific functionality:

CanalChannel FuncionalidadFunctionality
EmailEmail Envío y recepción de un correo electrónico que contiene metadatos de importancia, cuerpo y asunto.Send and receive an email that contains body, subject, and importance metadata
SlackSlack Envío de mensajes de Slack de plena fidelidad.Send full fidelity Slack messages
FacebookFacebook Envío de notificaciones de Facebook de forma nativa.Send Facebook notifications natively
TelegramTelegram Acciones específicas de Telegram, como compartir una nota de voz o un adhesivo.Perform Telegram-specific actions, such as sharing a voice memo or a sticker
KikKik Envío y recepción de mensajes nativos de Kik.Send and receive native Kik messages

Nota

El valor de la propiedad channel data de un objeto activity es un objeto JSON.The value of an activity object's channel data property is a JSON object. Por lo tanto, los ejemplos de este artículo muestran el formato esperado de la propiedad JSON channelData en distintos escenarios.Therefore, the examples in this article show the expected format of the channelData JSON property in various scenarios. Para crear un objeto JSON con. NET, use la clase JObject (.NET).To create a JSON object using .NET, use the JObject (.NET) class.

Crear un mensaje de correo electrónico personalizadoCreate a custom Email message

Para crear un mensaje de correo electrónico personalizado, establezca la propiedad channelData activity en un objeto JSON que contenga las siguientes propiedades:To create a custom email message, set the activity channelData property to a JSON object that contains the following properties:

PropiedadProperty DescripciónDescription
bccRecipientsbccRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CCO (copia carbón oculta) del mensaje.A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.
ccRecipientsccRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CC (copia carbón) del mensaje.A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
htmlBodyhtmlBody Un documento HTML que especifique el cuerpo del mensaje de correo electrónico.An HTML document that specifies the body of the email message. Consulte la documentación del canal para obtener información acerca de los atributos y elementos HTML compatibles.See the channel's documentation for information about supported HTML elements and attributes.
importanceimportance Nivel de importancia del correo electrónico.The email's importance level. Los valores válidos son high, normal y low.Valid values are high, normal, and low. El valor predeterminado es normal.The default value is normal.
subjectsubject Asunto del correo electrónico.The email's subject. Consulte la documentación del canal para obtener información acerca de los requisitos del campo.See the channel's documentation for information about field requirements.
toRecipientstoRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo Para del mensaje.A semicolon (;) delimited string of email addresses to add to the message's To field.

Los mensajes salientes y entrantes entre el usuario y el bot pueden tener una actividad que contiene un objeto JSON cuyas propiedades se channelData especifican en la tabla anterior.The outgoing and incoming messages between the user and the bot may have a channelData activity that contains a JSON object whose properties are specified in the previous table. El fragmento de código siguiente muestra un ejemplo de la propiedad para un mensaje de correo electrónico personalizado channelData entrante, del bot al usuario.The snippet below shows an example of the channelData property for an incoming custom email message, from the bot to the user.

PropiedadProperty DescripciónDescription
htmlBodyhtmlBody El código HTML que se utilizará para el cuerpo del mensaje.The HTML to use for the body of the message.
subjectsubject El asunto que se usará para el mensaje.The subject to use for the message.
importanceimportance La marca de importancia que se usará para el mensaje: low, normal o high.The importance flag to use for the message: low, normal, or high.
toRecipientstoRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo Para del mensaje.A semicolon (;) delimited string of email addresses to add to the message's To field.
ccRecipientsccRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CC (copia carbón) del mensaje.A semicolon (;) delimited string of email addresses to add to the message's Cc (carbon copy) field.
bccRecipientsbccRecipients Una cadena de direcciones de correo electrónico delimitada por punto y coma (;) para agregar al campo CCO (copia carbón oculta) del mensaje.A semicolon (;) delimited string of email addresses to add to the message's Bcc (blind carbon copy) field.

Crear un mensaje de Slack de plena fidelidadCreate a full-fidelity Slack message

Para crear un mensaje de Slack de plena fidelidad, establezca la propiedad channel data del objeto activity en un objeto JSON que especifique mensajes de Slack, elementos adjuntos de Slack o botones de Slack.To create a full-fidelity Slack message, set the activity object's channel data property to a JSON object that specifies Slack messages, Slack attachments, and/or Slack buttons.

Nota

Para admitir botones en los mensajes de Slack, debe habilitar Mensajes interactivos cuando conecte el bot al canal de Slack.To support buttons in Slack messages, you must enable Interactive Messages when you connect your bot to the Slack channel.

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un mensaje de Slack personalizado.This snippet shows an example of the channelData property for a custom Slack message.

"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.When a user clicks a button within a Slack message, your bot will receive a response message in which the channel data property is populated with a payload JSON object. 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.The payload object specifies contents of the original message, identifies the button that was clicked, and identifies the user who clicked the button.

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.This snippet shows an example of the channelData property in the message that a bot receives when a user clicks a button in the Slack message.

"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.Your bot can reply to this message in the normal manner, or it can post its response directly to the endpoint that is specified by the payload object's response_url property. Para obtener información sobre cuándo y cómo publicar una respuesta en response_url, consulte Botones de Slack.For information about when and how to post a response to the response_url, see Slack Buttons.

Puede crear botones dinámicos con el código JSON siguiente.You can create dynamic buttons using the following 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:To create interactive menus, use the following 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"
                        }
                    ]
                }
            ]
        }
    ]
}

Crear una notificación de FacebookCreate a Facebook notification

Para crear una notificación de Facebook, establezca la propiedad channel data del objeto activity en un objeto JSON que especifique estas propiedades:To create a Facebook notification, set the activity object's channel data property to a JSON object that specifies these properties:

PropiedadProperty DescripciónDescription
notification_typenotification_type El tipo de notificación (por ejemplo, REGULAR, SILENT_PUSH, NO_PUSH).The type of notification (e.g., REGULAR, SILENT_PUSH, NO_PUSH).
attachmentattachment 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.An attachment that specifies an image, video, or other multimedia type, or a templated attachment such as a receipt.

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.For details about format and contents of the notification_type property and attachment property, see the Facebook API documentation.

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un elemento adjunto con recibo de Facebook.This snippet shows an example of the channelData property for a Facebook receipt attachment.

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

Crear un mensaje de TelegramCreate a Telegram message

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:To create a message that implements Telegram-specific actions, such as sharing a voice memo or a sticker, set the activity object's channel data property to a JSON object that specifies these properties:

PropiedadProperty DescripciónDescription
methodmethod El método de Telegram Bot API al que se llamará.The Telegram Bot API method to call.
parámetrosparameters Los parámetros del método especificado.The parameters of the specified method.

Se admiten los métodos de Telegram siguientes:These Telegram methods are supported:

  • answerInlineQueryanswerInlineQuery
  • editMessageCaptioneditMessageCaption
  • editMessageReplyMarkupeditMessageReplyMarkup
  • editMessageTexteditMessageText
  • forwardMessageforwardMessage
  • kickChatMemberkickChatMember
  • sendAudiosendAudio
  • sendChatActionsendChatAction
  • sendContactsendContact
  • sendDocumentsendDocument
  • sendLocationsendLocation
  • sendMessagesendMessage
  • sendPhotosendPhoto
  • sendStickersendSticker
  • sendVenuesendVenue
  • sendVideosendVideo
  • sendVoicesendVoice
  • unbanChateMemberunbanChateMember

Para obtener más información sobre estos métodos de Telegram y sus parámetros, consulte la documentación de Telegram Bot API.For details about these Telegram methods and their parameters, see the Telegram Bot API documentation.

Nota

  • El parámetro chat_id es común a todos los métodos de Telegram.The chat_id parameter is common to all Telegram methods. Si no especifica chat_id como parámetro, el marco proporcionará el identificador automáticamente.If you do not specify chat_id as a parameter, the framework will provide the ID for you.
  • 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.Instead of passing file contents inline, specify the file using a URL and media type as shown in the example below.
  • Dentro de cada mensaje que recibe su bot del canal de Telegram, la propiedad ChannelData incluirá el mensaje que su bot envió anteriormente.Within each message that your bot receives from the Telegram channel, the ChannelData property will include the message that your bot sent previously.

En este fragmento de código se muestra un ejemplo de una propiedad channelData que especifica un único método de Telegram.This snippet shows an example of a channelData property that specifies a single Telegram method.

"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.This snippet shows an example of a channelData property that specifies an array of Telegram methods.

"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.When a Telegram method is implemented, your bot will receive a response message in which the channel data property is populated with a JSON object. Este objeto de respuesta especifica el contenido del mensaje original, incluido un elemento update_id y, como máximo, un parámetro opcional.This response object specifies the contents of the original message, including an update_id and, at most, one optional parameter. Para obtener información acerca de cómo recibir respuestas entrantes, consulte Getting updates (Obtención de actualizaciones).For information about receiving incoming responses, see Getting updates.

En este fragmento de código se muestra un ejemplo de la propiedad channelData en el mensaje que recibe un bot cuando se crea un sondeo.This snippet shows an example of the channelData property in the message that a bot receives when a poll is created.

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

Crear un mensaje de Kik nativoCreate a native Kik message

Para crear un mensaje de Kik nativo, establezca la propiedad sticker del objeto activity en un objeto JSON que especifique esta propiedad:To create a native Kik message, set the activity object's channel data property to a JSON object that specifies this property:

PropiedadProperty DescripciónDescription
messagesmessages Una matriz de mensajes de Kik.An array of Kik messages. Para obtener más información sobre el formato de los mensajes de Kik, consulte los formatos de mensaje de Kik.For details about Kik message format, see Kik Message Formats.

En este fragmento de código se muestra un ejemplo de la propiedad channelData para un mensaje de Kik nativo.This snippet shows an example of the channelData property for a native Kik message.

"channelData": {
    "messages": [
        {
            "chatId": "c6dd8165…",
            "type": "link",
            "to": "kikhandle",
            "title": "My Webpage",
            "text": "Some text to display",
            "url": "http://botframework.com",
            "picUrl": "http://lorempixel.com/400/200/",
            "attribution": {
                "name": "My App",
                "iconUrl": "http://lorempixel.com/50/50/"
            },
            "noForward": true,
            "kikJsData": {
                    "key": "value"
                }
        }
    ]
}

Creación de un mensaje de LINECreate a LINE message

Para crear un mensaje que implementa los tipos de mensajes específicos de LINE (por ejemplo, adhesivo o plantillas, o tipos de acciones específicos de LINE como la apertura de 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 acciones y mensajes de LINE.To create a message that implements LINE-specific message types (such as sticker, templates, or LINE specific action types like opening the phone camera), set the activity object's channel data property to a JSON object that specifies LINE message types and action types.

PropiedadProperty DescripciónDescription
typetype Nombre del tipo de acción o mensaje de LINEThe LINE action/message type name

Se admiten estos tipos de mensajes de LINE:These LINE message types are supported:

  • StickerSticker
  • ImagemapImagemap
  • Template (Button, confirm, carousel)Template (Button, confirm, carousel)
  • FlexFlex

Estas acciones de LINE se pueden especificar en el campo de acción del objeto JSON de tipo de mensaje:These LINE actions can be specified in the action field of the message type JSON object:

  • PostbackPostback
  • MessageMessage
  • URIURI
  • DatetimerpickerDatetimerpicker
  • CámaraCamera
  • Camera rollCamera roll
  • LocationLocation

Para más información sobre estos métodos de LINE y sus parámetros, consulte la documentación Bot API para LINE.For details about these LINE methods and their parameters, see the LINE Bot API documentation.

Este fragmento de código muestra un ejemplo de una propiedad channelData que especifica un tipo de mensaje de canal ButtonTemplate y tres tipos de acciones: camera, cameraRoll, Datetimepicker.This snippet shows an example of a channelData property that specifies a channel message type ButtonTemplate and 3 action types: camera, cameraRoll, Datetimepicker.

"channelData": {
    "type": "ButtonsTemplate",
    "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"
            }
        ]
    }
}

Adición de un bot a TeamsAdding a bot to 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.Bots added to a team become another team member, who can be @mentioned as part of the conversation. De hecho, los bots solo reciben mensajes cuando se les @mentionedmenciona, por lo que no se envían al bot otras conversaciones del canal.In fact, bots only receive messages when they are @mentioned, so other conversations on the channel are not sent to the bot. Para más información, consulte Conversaciones de chat de canal y grupo con un bot de Microsoft Teams.For more information, see Channel and Group chat conversations with a Microsoft Teams bot.

Dado que los bots de un grupo o canal solo responden cuando se les menciona (@botname) en un mensaje, cada mensaje que recibe un bot en un canal de grupo contiene su propio nombre, y debe asegurarse de que el análisis del mensaje administra eso.Because bots in a group or channel respond only when they are mentioned (@botname) in a message, every message received by a bot in a group channel contains its own name, and you must ensure your message parsing handles that. Además, los bots pueden analizar otros usuarios mencionados y mencionar a usuarios como parte de sus mensajes.In addition, bots can parse out other users mentioned and mention users as part of their messages.

Buscar y quitar menciones @botCheck for and strip @bot mention


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, salvo con fines de prueba.Adding a bot by GUID, for anything other than testing purposes, is not recommended. Si lo hace, se limitará en gran medida la funcionalidad de un bot.Doing so severely limits the functionality of a bot. Los bots de producción se deben agregar a Teams como parte de una aplicación.Bots in production should be added to Teams as part of an app. Consulte Creación de un bot y Prueba y depuración del bot de Microsoft Teams.See Create a bot and Test and debug your Microsoft Teams bot.

Recursos adicionalesAdditional resources