Conceptos básicos de la conversación

Importante

Los ejemplos de código de esta sección se basan en 4,6 y versiones posteriores del SDK de bot Framework. Si está buscando documentación para versiones anteriores, vea la sección SDK de bots-V3 en la carpeta recursos de la documentación.

Una conversación es una serie de mensajes enviados entre el bot y uno o más usuarios. Hay tres tipos de conversaciones (también denominadas ámbitos) en Microsoft Teams:

  • teams También se denominan conversaciones de canal, visibles para todos los miembros del canal.
  • personal Conversaciones entre bots y un único usuario.
  • groupChat Chatear entre un bot y dos o más usuarios. También habilita el bot en los chats de reuniones.

Un bot tiene un comportamiento ligeramente diferente en función del tipo de conversación en el que esté involucrado:

  • Los bots en conversaciones de chat en el grupo y en el canal requieren al usuario que mencione el bot para invocarlo en un canal.
  • Los bots de una conversación uno a uno no requieren @ mención. Todos los mensajes enviados por el usuario se enrutarán a su bot.

Para habilitar el bot en un ámbito determinado, agregue ese ámbito al manifiesto de la aplicación.

Actividades

Cada mensaje es un Activity objeto de tipo messageType: message . Cuando un usuario envía un mensaje, Microsoft Teams expone el mensaje a su bot; en concreto, envía un objeto JSON al extremo de mensajería de bot. El bot examina el mensaje para determinar su tipo y responde en consecuencia.

La conversación básica se controla a través del conector de bot Framework, una única API de REST para permitir que su bot se comunique con Microsoft Teams y otros canales. El SDK de bot Builder proporciona acceso sencillo a esta API, funcionalidad adicional para administrar el flujo de conversaciones y el estado, y formas sencillas de incorporar servicios cognitivos como el procesamiento de lenguaje natural (NLP).

Recibir un mensaje

Para recibir un mensaje de texto, use la Text propiedad del Activity objeto. En el controlador de actividad del bot, use el objeto convertir contexto Activity para leer una única solicitud de mensaje.

El código siguiente muestra un ejemplo.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text}"), cancellationToken);
}

Enviar un mensaje

Para enviar un mensaje de texto, especifique la cadena que desea enviar como la actividad. En los controladores de actividad del bot, use el método Turn context del objeto SendActivityAsync para enviar una respuesta de mensaje único. También puede usar el método del objeto SendActivitiesAsync para enviar varias respuestas a la vez. El siguiente código muestra un ejemplo de cómo enviar un mensaje cuando alguien se agrega a una conversación

protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync(MessageFactory.Text($"Hello and welcome!"), cancellationToken);
}

Datos del canal de Teams

El channelData objeto contiene información específica de Microsoft Teams y es la fuente definitiva de los identificadores de equipo y de canal. Es posible que necesite almacenar en caché y usar estos identificadores como claves para el almacenamiento local. La TeamsActivityHandler en el SDK suele extraer información importante del channelData objeto para que sea más fácil de acceder, pero siempre puede tener acceso a la información original del turnContext objeto.

El channelData objeto no está incluido en los mensajes de las conversaciones personales, ya que éstos tienen lugar fuera de cualquier canal.

Un objeto channelData típico de una actividad enviada a su bot contiene la siguiente información:

  • eventType Tipo de evento de Teams; solo se pasa en casos de eventos de modificación de canal
  • tenant.id IDENTIFICADOR de inquilino de Azure Active Directory; se pasan en todos los contextos
  • team Solo se pasa en contextos de canal, no en chat personal.
  • channel Solo se pasa en contextos de canal cuando se menciona el bot o para eventos en los canales en equipos en los que se ha agregado el bot
  • channelData.teamsTeamId En desuso. Esta propiedad se incluye únicamente para la compatibilidad con versiones anteriores.
  • channelData.teamsChannelId En desuso. Esta propiedad se incluye únicamente para la compatibilidad con versiones anteriores.

Ejemplo de objeto channelData (evento channelCreated)

"channelData": {
    "eventType": "channelCreated",
    "tenant": {
        "id": "72f988bf-86f1-41af-91ab-2d7cd011db47"
    },
    "channel": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype",
        "name": "My New Channel"
    },
    "team": {
        "id": "19:693ecdb923ac4458a5c23661b505fc84@thread.skype"
    }
}

Contenido del mensaje

El bot puede enviar texto enriquecido, imágenes y tarjetas. Los usuarios pueden enviar texto enriquecido e imágenes a su bot.

Formato De un usuario a un bot De bot a User Notas
Texto enriquecido
Imágenes Máximo de 1024 × 1024 y 1 MB en formato PNG, JPEG o GIF; no se admiten GIF animados
Tarjetas Ver la referencia de la tarjeta Teams para tarjetas compatibles
Emojis Actualmente, los equipos son compatibles con emojis mediante UTF-16 (como U + 1F600 para la cara Grinning).

Adición de notificaciones al mensaje

Las notificaciones alertan a los usuarios sobre nuevas tareas, menciones y comentarios relacionados con el trabajo en el que están trabajando, o bien deben consultarse mediante la inserción de un aviso en su fuente de actividades. Puede establecer notificaciones para que desencadenen desde el mensaje de bot estableciendo la TeamsChannelData propiedad Objects Notification.Alert en true. El hecho de que se genere una notificación dependerá en última instancia de la configuración de Teams del usuario individual y no podrá reemplazar esta configuración mediante programación. El tipo de notificación será un banner, un banner o un correo electrónico.

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  var message = MessageFactory.Text("You'll get a notification, if you've turned them on.");
  message.TeamsNotifyUser();

  await turnContext.SendActivityAsync(message);
}

Mensajes de imagen

Las imágenes se envían agregando datos adjuntos a un mensaje. Puede encontrar más información sobre los datos adjuntos en la documentación de bot Framework.

Las imágenes pueden tener como máximo 1024 x 1024 y 1 MB en formato PNG, JPEG o GIF; GIF animado no es compatible.

Le recomendamos que especifique el alto y el ancho de cada imagen utilizando XML. Si usa Markdown, el tamaño de imagen predeterminado es de 256 × 256. Por ejemplo:

  • Utilizados <img src="http://aka.ms/Fo983c" alt="Duck on a rock" height="150" width="223"></img>
  • No use- ![Duck on a rock](http://aka.ms/Fo983c)

Siguientes pasos