Por ejemplo, si el bot recibe una actividad de mensaje, el controlador de turnos vería dicha actividad entrante y la enviaría al controlador de actividad de actividad en mensaje. Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en este controlador en actividad de mensaje. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en el controlador en miembros agregados, al que se llama cada vez que se agrega un miembro a la conversación.
Nota:
Los SDK de JavaScript, C# y Python de Bot Framework seguirán siendo compatibles, pero el SDK de Java se va a retirar con la compatibilidad final a largo plazo que finaliza en noviembre de 2023.
Los bots existentes creados con el SDK de Java seguirán funcionando.
Para la nueva compilación de bots, considere la posibilidad de usar Microsoft Copilot Studio y lea sobre cómo elegir la solución de copilot adecuada.
Para obtener más información, consulte El futuro de la creación de bots.
Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. En estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.
Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de llamar en primer lugar a await base.OnTurnAsync(turnContext, cancellationToken); para asegurarse de que la implementación base de OnTurnAsync se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como OnMessageActivityAsync.
ActivityHandler de JavaScript usa un emisor de eventos y un patrón de escucha.
Por ejemplo, use el método onMessage para registrar un cliente de escucha de eventos para las actividades de mensaje. Puede registrar más de un cliente de escucha. Cuando el bot reciba una actividad de mensaje, el controlador de actividad verá esa actividad entrante y la enviará cada uno de los clientes de escucha de la actividad onMessage, en el orden en que se registraron.
Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en los clientes de escucha onMessage. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en los clientes de escucha onMembersAdded, a los que se llama cada vez que se agrega un miembro a la conversación.
Para agregar estos clientes de escucha, se registran en el bot tal y como se muestra en la siguiente sección Lógica del bot. Incluya la lógica del bot de cada uno de estos clientes de escucha y, después, no olvide llamar a next() al final. Al llamar a next(), asegúrese de que se ejecuta el siguiente cliente de escucha.
Asegúrese de guardar el estado antes de que termine el turno. Para hacerlo, puede invalidar el método run del controlador de actividad y guardar el estado después de que se complete el método run del elemento primario.
No hay situaciones comunes en las que vaya a desear invalidar el controlador de turnos base, así que tenga cuidado si intenta hacerlo.
Hay un controlador especial llamado onDialog. El controlador onDialog se ejecuta al final, después de que se hayan ejecutado el resto de los controladores, y no está asociado a un tipo de actividad determinado. Como con todos los controladores anteriores, asegúrese de llamar a next() para asegurarse de que concluye el resto del proceso.
Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. Para todos estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.
Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de, en primer lugar, llamar a super.onTurn(turnContext); para asegurarse de que la implementación base de onTurn se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como onMessageActivity.
Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en dicho on_message_activitycontrolador. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en el controlador on_members_added, al que se llama cada vez que se agrega un miembro a la conversación.
Por ejemplo, si el bot recibe una actividad de mensaje, el controlador de turnos vería dicha actividad entrante y la enviaría al controlador de actividad on_message_activity.
Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. En estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.
Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de llamar en primer lugar a await super().on_turn(turnContext); para asegurarse de que la implementación base de on_turn se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como on_message_activity.
La lógica del bot procesa las actividades entrantes de uno o varios canales y genera actividades salientes como respuesta.
La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase de bot de ActivityHandler, que implementa la interfaz IBot. ActivityHandler define varios controladores para diferentes tipos de actividades, como OnMessageActivityAsync, y OnMembersAddedAsync. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.
Los controladores definidos en ActivityHandler son:
| Evento |
Handler |
Descripción |
| Cualquier tipo de actividad recibida |
OnTurnAsync |
Llama a uno de los otros controladores, en función del tipo de actividad que reciba. |
| Actividad de mensaje recibida |
OnMessageActivityAsync |
Se invalida para controlar un actividad message. |
| Actividad de actualización de conversación recibida |
OnConversationUpdateActivityAsync |
En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona. |
| Miembros que no son el bot se han unido a la conversación |
OnMembersAddedAsync |
Se invalida para controlar a los miembros que se unen a una conversación. |
| Miembros que no son el bot ha abandonado la conversación |
OnMembersRemovedAsync |
Se invalida para controlar a los miembros que abandonan una conversación. |
| Actividad de evento recibida |
OnEventActivityAsync |
En una actividad event, llama a un controlador específico del tipo de evento. |
| Actividad de evento token-respuesta recibida |
OnTokenResponseEventAsync |
Se invalida para controlar los eventos de respuesta del token. |
| Actividad de evento no token-respuesta recibida |
OnEventAsync |
Se invalida para controlar otros tipos de eventos. |
| Actividad de reacción de mensajes recibida |
OnMessageReactionActivityAsync |
En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje. |
| Reacciones de mensajes agregadas a un mensaje |
OnReactionsAddedAsync |
Invalide esto para controlar las reacciones agregadas a un mensaje. |
| Reacciones de mensajes eliminadas de un mensaje |
OnReactionsRemovedAsync |
Invalide esto para controlar las reacciones eliminadas de un mensaje. |
| Actividad recibida de actualización de la instalación |
OnInstallationUpdateActivityAsync |
En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló. |
| Bot instalado |
OnInstallationUpdateAddAsync |
Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa. |
| Bot desinstalado |
OnInstallationUpdateRemoveAsync |
Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa. |
| Otro tipo de actividad recibida |
OnUnrecognizedActivityTypeAsync |
Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma. |
Estos controladores tienen un objeto turnContext que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, OnMessageActivityAsync siempre se controlará y, por lo general, es el más común.
Al igual que en versiones anteriores de 4.x de este marco, también existe la opción de implementar el método público OnTurnAsync. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de OnTurnAsync, sigue siendo una opción.
Importante
Si invalida el método OnTurnAsync, deberá llamar a base.OnTurnAsync para obtener la implementación base para llamar a los restantes controladores de On<activity>Async, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.
La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, extienda ActivityHandler. ActivityHandler define varios eventos para diferentes tipos de actividades y se puede modificar el comportamiento del bot registrando clientes de escucha, como onMessage y onConversationUpdate.
Utilice estos métodos para registrar clientes de escucha para cada tipo de evento:
| Evento |
Método de registro |
Descripción |
| Cualquier tipo de actividad recibida |
onTurn |
Registra un cliente de escucha para cuando se recibe cualquier actividad . |
| Actividad de mensaje recibida |
onMessage |
Registra un cliente de escucha para cuando se recibe una actividad message. |
| Actividad de actualización de conversación recibida |
onConversationUpdate |
Registra un cliente de escucha para cuando se recibe cualquier actividad conversationUpdate. |
| Miembros se unen a la conversación |
onMembersAdded |
Registra un cliente de escucha para cuando algún miembro se une a la conversación, incluido el bot. |
| Miembros abandonan la conversación |
onMembersRemoved |
Registra un cliente de escucha para cuando algún miembro sale de la conversación, incluido el bot. |
| Actividad de reacción de mensajes recibida |
onMessageReaction |
Registra un cliente de escucha para cuando se recibe cualquier actividad messageReaction. |
| Reacciones de mensajes agregadas a un mensaje |
onReactionsAdded |
Registra un cliente de escucha para cuando se agregan reacciones a un mensaje. |
| Reacciones de mensajes eliminadas de un mensaje |
onReactionsRemoved |
Registra un cliente de escucha para cuando se quitan reacciones de un mensaje. |
| Actividad de evento recibida |
onEvent |
Registra un cliente de escucha para cuando se recibe cualquier actividad event. |
| Actividad de evento token-respuesta recibida |
onTokenResponseEvent |
Registra un cliente de escucha para cuando se recibe cualquier evento tokens/response. |
| Actividad recibida de actualización de la instalación |
onInstallationUpdate |
Registra un cliente de escucha para cuando se recibe cualquier actividad installationUpdate. |
| Bot instalado |
onInstallationUpdateAdd |
Registra un agente de escucha para cuando el bot está instalado en una unidad organizativa. |
| Bot desinstalado |
onInstallationUpdateRemove |
Registra un agente de escucha para cuando el bot está desinstalado en una unidad organizativa. |
| Otro tipo de actividad recibida |
onUnrecognizedActivityType |
Registra un agente de escucha para cuando no hay definido un controlador para el tipo de actividad específico. |
| Los controladores de actividad se han completado |
onDialog |
Se llama después de que se hayan completado los controladores correspondientes. |
Llame al parámetro de función next desde cada controlador para que el procesamiento continúe. Si no se llama a next, el procesamiento de la actividad finaliza.
La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase de bot de ActivityHandler, que implementa la interfaz Bot. ActivityHandler define varios controladores para diferentes tipos de actividades, como onMessageActivity, y onMembersAdded. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.
Los controladores definidos en ActivityHandler son:
| Evento |
Handler |
Descripción |
| Cualquier tipo de actividad recibida |
onTurn |
Llama a uno de los otros controladores, en función del tipo de actividad que reciba. |
| Actividad de mensaje recibida |
onMessageActivity |
Se invalida para controlar un actividad message. |
| Actividad de actualización de conversación recibida |
onConversationUpdateActivity |
En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona. |
| Miembros que no son el bot se han unido a la conversación |
onMembersAdded |
Se invalida para controlar a los miembros que se unen a una conversación. |
| Miembros que no son el bot ha abandonado la conversación |
onMembersRemoved |
Se invalida para controlar a los miembros que abandonan una conversación. |
| Actividad de evento recibida |
onEventActivity |
En una actividad event, llama a un controlador específico del tipo de evento. |
| Actividad de evento token-respuesta recibida |
onTokenResponseEvent |
Se invalida para controlar los eventos de respuesta del token. |
| Actividad de evento no token-respuesta recibida |
onEvent |
Se invalida para controlar otros tipos de eventos. |
| Actividad de reacción de mensajes recibida |
onMessageReactionActivity |
En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje. |
| Reacciones de mensajes agregadas a un mensaje |
onReactionsAdded |
Invalide esto para controlar las reacciones agregadas a un mensaje. |
| Reacciones de mensajes eliminadas de un mensaje |
onReactionsRemoved |
Invalide esto para controlar las reacciones eliminadas de un mensaje. |
| Actividad recibida de actualización de la instalación |
onInstallationUpdate |
En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló. |
| Bot instalado |
onInstallationUpdateAdd |
Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa. |
| Bot desinstalado |
onInstallationUpdateRemove |
Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa. |
| Otro tipo de actividad recibida |
onUnrecognizedActivityType |
Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma. |
Estos controladores tienen un objeto turnContext que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, onMessageActivity siempre se controlará y, por lo general, es el más común.
También existe la opción de implementar el método público onTurn. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de onTurn, sigue siendo una opción.
Importante
Si invalida el método onTurn, deberá llamar a super.onTurn para obtener la implementación base para llamar a los restantes controladores de on<activity>, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.
La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase bot de ActivityHandler, que a su vez deriva de la clase abstracta Bot. ActivityHandler define varios controladores para diferentes tipos de actividades, como on_message_activity y on_members_added. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.
Los controladores definidos en ActivityHandler son:
| Evento |
Handler |
Descripción |
| Cualquier tipo de actividad recibida |
on_turn |
Llama a uno de los otros controladores, en función del tipo de actividad que reciba. |
| Actividad de mensaje recibida |
on_message_activity |
Se invalida para controlar un actividad message. |
| Actividad de actualización de conversación recibida |
on_conversation_update_activity |
En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona. |
| Miembros que no son el bot se han unido a la conversación |
on_members_added_activity |
Se invalida para controlar a los miembros que se unen a una conversación. |
| Miembros que no son el bot ha abandonado la conversación |
on_members_removed_activity |
Se invalida para controlar a los miembros que abandonan una conversación. |
| Actividad de evento recibida |
on_event_activity |
En una actividad event, llama a un controlador específico del tipo de evento. |
| Actividad de evento token-respuesta recibida |
on_token_response_event |
Se invalida para controlar los eventos de respuesta del token. |
| Actividad de evento no token-respuesta recibida |
on_event_activity |
Se invalida para controlar otros tipos de eventos. |
| Actividad de reacción de mensajes recibida |
on_message_reaction_activity |
En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje. |
| Reacciones de mensajes agregadas a un mensaje |
on_reactions_added |
Invalide esto para controlar las reacciones agregadas a un mensaje. |
| Reacciones de mensajes eliminadas de un mensaje |
on_reactions_removed |
Invalide esto para controlar las reacciones eliminadas de un mensaje. |
| Actividad recibida de actualización de la instalación |
on_installation_update |
En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló. |
| Bot instalado |
on_installation_update_add |
Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa. |
| Bot desinstalado |
on_installation_update_remove |
Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa. |
| Otro tipo de actividad recibida |
on_unrecognized_activity_type |
Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma. |
Estos controladores tienen un objeto turn_context que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, on_message_activity siempre se controlará y, por lo general, es el más común.
Al igual que en versiones anteriores de 4.x de este marco, también existe la opción de implementar el método público on_turn. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de on_turn, sigue siendo una opción.
Importante
Si invalida el método on_turn, deberá llamar a super().on_turn para obtener la implementación base para llamar a los restantes controladores de on_<activity>, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.
public class EchoBot : ActivityHandler
{
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
var replyText = $"Echo: {turnContext.Activity.Text}";
await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
}
protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
{
var welcomeText = "Hello and welcome!";
foreach (var member in membersAdded)
{
if (member.Id != turnContext.Activity.Recipient.Id)
{
await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
}
}
}
}
class EchoBot extends ActivityHandler {
constructor() {
super();
// See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
this.onMessage(async (context, next) => {
const replyText = `Echo: ${ context.activity.text }`;
await context.sendActivity(MessageFactory.text(replyText, replyText));
// By calling next() you ensure that the next BotHandler is run.
await next();
});
this.onMembersAdded(async (context, next) => {
const membersAdded = context.activity.membersAdded;
const welcomeText = 'Hello and welcome!';
for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
if (membersAdded[cnt].id !== context.activity.recipient.id) {
await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
}
}
// By calling next() you ensure that the next BotHandler is run.
await next();
});
}
}
public class EchoBot extends ActivityHandler {
@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
return turnContext.sendActivity(
MessageFactory.text("Echo: " + turnContext.getActivity().getText())
).thenApply(sendResult -> null);
}
@Override
protected CompletableFuture<Void> onMembersAdded(
List<ChannelAccount> membersAdded,
TurnContext turnContext
) {
String welcomeText = "Hello and welcome!";
return membersAdded.stream()
.filter(
member -> !StringUtils
.equals(member.getId(), turnContext.getActivity().getRecipient().getId())
).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
.collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
}
}
class EchoBot(ActivityHandler):
async def on_members_added_activity(
self, members_added: [ChannelAccount], turn_context: TurnContext
):
for member in members_added:
if member.id != turn_context.activity.recipient.id:
await turn_context.send_activity("Hello and welcome!")
async def on_message_activity(self, turn_context: TurnContext):
return await turn_context.send_activity(
MessageFactory.text(f"Echo: {turn_context.activity.text}")
)