Message Handling

/**
 * Listen for a pattern and execute handler when pattern is heard
 * @param patterns One or more string, regular expression, or test function
 * @param events A list of event types that should be evaluated for patterns
 * @param handler A function that will be called should the pattern be matched
 */
hears(
  patterns: (string | RegExp | { (message: BotkitMessage): Promise<boolean> })[] | RegExp | string | { (message: BotkitMessage): Promise<boolean> },
  events: string | string[],
  handler: BotkitHandler
): void;

interface BotkitHandler {
  (bot: BotWorker, message: BotkitMessage): Promise<any>;
}

// Listen for simple keyword
controller.hears("hello", "message", async (bot, message) => {
  await bot.reply(message, "I heard you say hello.");
});

// Listen for regular expression
controller.hears(new RegExp(/^[A-Z\s]+$/), "message", async (bot, message) => {
  await bot.reply(message, "I heard a message IN ALL CAPS.");
});

// Listen using a function
controller.hears(async (message) => {
  return message.intent === "hello";
}, "message", async (bot, message) => {
  await bot.reply(message, "This message matches the hello intent.");
});

// Multiple patterns
controller.hears(["hi", "hello", "hey"], "message", async (bot, message) => {
  await bot.reply(message, "Greetings!");
});

// Multiple events
controller.hears("help", ["message", "direct_message"], async (bot, message) => {
  await bot.reply(message, "How can I help you?");
});

/**
 * Listen for a pattern that interrupts normal message flow
 * @param patterns One or more string, regular expression, or test function
 * @param events A list of event types that should be evaluated for patterns
 * @param handler A function that will be called should the pattern be matched
 */
interrupts(
  patterns: (string | RegExp | { (message: BotkitMessage): Promise<boolean> })[] | RegExp | RegExp[] | string | { (message: BotkitMessage): Promise<boolean> },
  events: string | string[],
  handler: BotkitHandler
): void;

// Interrupt any dialog with help command
controller.interrupts("help", "message", async (bot, message) => {
  await bot.reply(message, "I can help! Here are available commands...");
});

// Interrupt with cancel command
controller.interrupts(["cancel", "stop", "quit"], "message", async (bot, message) => {
  await bot.cancelAllDialogs();
  await bot.reply(message, "Conversation cancelled.");
});

/**
 * Bind a handler function to one or more events
 * @param events One or more event names
 * @param handler A handler function that will fire whenever one of the named events is received
 */
on(events: string | string[], handler: BotkitHandler): void;

/**
 * Trigger an event to be fired
 * @param event the name of the event
 * @param bot a BotWorker instance created using controller.spawn()
 * @param message An incoming message or event
 */
trigger(event: string, bot?: BotWorker, message?: BotkitMessage): Promise<any>;

// Handle conversation updates
controller.on("conversationUpdate", async (bot, message) => {
  await bot.reply(message, "Welcome to the conversation!");
});

// Handle multiple events
controller.on(["channelJoined", "teamJoined"], async (bot, message) => {
  await bot.reply(message, "Thanks for adding me!");
});

// Handle custom events
controller.on("user_subscribed", async (bot, message) => {
  await bot.reply(message, "You're now subscribed to updates!");
});

// Trigger custom events
controller.trigger("user_subscribed", bot, message);

/**
 * Process incoming messages and evaluate them for triggers
 * @param turnContext a TurnContext representing an incoming message
 */
handleTurn(turnContext: TurnContext): Promise<any>;

// Typically used internally, but can be called directly for custom adapters
await controller.handleTurn(turnContext);

interface BotkitMessage {
  /** The type of event, defined by the messaging channel or adapter */
  type: string;
  /** Text of the message sent by the user */
  text?: string;
  /** Any value field received from the platform */
  value?: string;
  /** Unique identifier of user who sent the message */
  user: string;
  /** Unique identifier of the room/channel/space */
  channel: string;
  /** Full ConversationReference object for sending messages back */
  reference: ConversationReference;
  /** The original incoming BotBuilder Activity object */
  incoming_message: Activity;
  /** Any additional fields found in the incoming payload */
  [key: string]: any;
}

// Handle different message types
controller.on("message", async (bot, message) => {
  console.log(`Received message: ${message.text}`);
});

controller.on("conversationUpdate", async (bot, message) => {
  if (message.membersAdded) {
    await bot.reply(message, "Welcome new members!");
  }
});

// Platform-specific handling
controller.on("task/fetch", async (bot, message) => {
  const taskInfo = {
    type: "continue",
    value: {
      title: "Task Module",
      url: "https://example.com/task"
    }
  };
  await bot.replyWithTaskInfo(message, taskInfo);
});

interface MiddlewareEndpoints {
  /** Runs when a bot worker is spawned */
  spawn: Ware;
  /** Runs when a message is first received */
  ingest: Ware;
  /** Runs before message processing */
  receive: Ware;
  /** Runs before sending messages */
  send: Ware;
  /** Runs during message interpretation */
  interpret: Ware;
}

// Log all received messages
controller.middleware.receive.use((bot, message, next) => {
  console.log("RECEIVED:", message);
  next();
});

// Modify outgoing messages
controller.middleware.send.use((bot, message, next) => {
  if (typeof message === "object") {
    message.text = message.text + " (sent by bot)";
  }
  next();
});