or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapters-integration.mdbrain-user-management.mdcli.mdcore-bot-management.mddatastore.mdindex.mdmessage-handling.mdscripts-middleware.md
tile.json

index.mddocs/

Hubot

Hubot is a comprehensive chat bot framework modeled after GitHub's Campfire bot, designed to enable developers to build extensible chat bots that can work across multiple chat services including Slack, Discord, MS Teams, and IRC. The framework provides a robust library with built-in support for custom scripts, adapters for various chat platforms, command-line interface for creating and managing bot instances, and Express.js-powered HTTP server capabilities.

Package Information

  • Package Name: hubot
  • Package Type: npm
  • Language: JavaScript (ES modules)
  • Installation: 
    npm install hubot

Core Imports

import { Robot, Adapter, loadBot } from "hubot";

For CommonJS:

const { Robot, Adapter, loadBot } = require("hubot");

Complete imports (all available exports):

import { 
  Robot, 
  Adapter, 
  User, 
  Brain, 
  Response, 
  Listener, 
  TextListener,
  Message,
  TextMessage,
  EnterMessage,
  LeaveMessage,
  TopicMessage,
  CatchAllMessage,
  DataStore,
  DataStoreUnavailable,
  Middleware,
  loadBot
} from "hubot";

Basic Usage

import { Robot } from "hubot";

// Create a bot with Shell adapter for development
const robot = new Robot("Shell", true, "MyBot");

// Listen for messages
robot.hear(/hello/i, (res) => {
  res.reply("Hello there!");
});

// Respond to direct mentions
robot.respond(/how are you/i, (res) => {
  res.send("I'm doing great, thanks for asking!");
});

// Listen for user events
robot.enter((res) => {
  res.send(`Welcome, ${res.message.user.name}!`);
});

// Start the bot
await robot.run();

Architecture

Hubot is built around several key components:

  • Robot: Central orchestrator managing adapters, listeners, brain, HTTP server, and event system
  • Adapters: Interface between the bot and chat services (Shell, Campfire, etc.)
  • Brain: Memory and user management system with persistent storage and automatic serialization
  • Listeners: Pattern-matching system for messages and events with middleware support
  • Messages: Type hierarchy for different chat events (text, enter/leave, topic changes, catch-all)
  • Middleware: Pluggable request/response processing pipeline with listener, response, and receive phases
  • Scripts: Dynamically loaded bot functionality from local files or npm packages
  • DataStore: Pluggable persistent storage system for robot data
  • HTTP Server: Built-in Express.js server for webhooks and web interfaces
  • Event System: EventEmitter-based communication between components

Capabilities

Core Bot Management

Primary robot functionality including lifecycle management, message processing, and adapter integration. Essential for all bot implementations.

class Robot {
  constructor(adapter: string | Adapter, httpd?: boolean, name?: string, alias?: string | boolean);
  async run(): Promise<void>;
  shutdown(): void;
  async messageRoom(room: string, ...strings: string[]): Promise<void>;
  helpCommands(): string[];
  parseVersion(): string;
  respondPattern(regex: RegExp): RegExp;
}

function loadBot(adapter: string | Adapter, enableHttpd: boolean, name: string, alias?: string | boolean): Robot;

Core Bot Management

Message Handling

Comprehensive message pattern matching and response system for different types of chat interactions and events.

// Listener registration methods
hear(regex: RegExp, options?: ListenerOptions, callback: ListenerCallback): void;
respond(regex: RegExp, options?: ListenerOptions, callback: ListenerCallback): void;
enter(options?: ListenerOptions, callback: ListenerCallback): void;
leave(options?: ListenerOptions, callback: ListenerCallback): void;
topic(options?: ListenerOptions, callback: ListenerCallback): void;
catchAll(options?: ListenerOptions, callback: ListenerCallback): void;
listen(matcher: Function, options?: ListenerOptions, callback: ListenerCallback): void;
error(callback: (error: Error, response?: Response) => void): void;

// Response methods
class Response {
  async send(...strings: string[]): Promise<void>;
  async reply(...strings: string[]): Promise<void>;
  async emote(...strings: string[]): Promise<void>;
  async topic(...strings: string[]): Promise<void>;
  async play(...strings: string[]): Promise<void>;
  async locked(...strings: string[]): Promise<void>;
  random(items: any[]): any;
  finish(): void;
  http(url: string, options?: object): HttpClient;
}

Message Handling

Brain and User Management

Robot memory system with user management, persistent data storage, and automatic serialization for maintaining state across restarts.

class Brain {
  set(key: string, value: any): Brain;
  get(key: string): any;
  remove(key: string): Brain;
  save(): void;
  close(): void;
  setAutoSave(enabled: boolean): void;
  resetSaveInterval(seconds: number): void;
  mergeData(data: object): void;
  users(): Record<string, User>;
  userForId(id: string, options?: UserOptions): User;
  userForName(name: string): User | null;
  usersForRawFuzzyName(fuzzyName: string): User[];
  usersForFuzzyName(fuzzyName: string): User[];
}

class User {
  constructor(id: string, options?: UserOptions);
  async set(key: string, value: any): Promise<void>;
  async get(key: string): Promise<any>;
}

Brain and User Management

Adapters and Integration

Adapter system for integrating with different chat platforms, including built-in Shell and Campfire adapters and extensibility patterns.

class Adapter {
  constructor(robot: Robot);
  async send(envelope: Envelope, ...strings: string[]): Promise<void>;
  async emote(envelope: Envelope, ...strings: string[]): Promise<void>;
  async reply(envelope: Envelope, ...strings: string[]): Promise<void>;
  async topic(envelope: Envelope, ...strings: string[]): Promise<void>;
  async play(envelope: Envelope, ...strings: string[]): Promise<void>;
  async run(): Promise<void>;
  close(): void;
  async receive(message: Message): Promise<void>;
}

Adapters and Integration

Script and Middleware System

Dynamic script loading from files and npm packages, plus middleware system for customizing message processing pipeline.

// Script loading
async loadFile(filepath: string, filename: string): Promise<any>;
async load(path: string): Promise<any[]>;
async loadExternalScripts(packages: string[] | object): Promise<void>;
async loadAdapter(adapterPath?: string): Promise<void>;

// Middleware registration
listenerMiddleware(middleware: MiddlewareFunction): void;
responseMiddleware(middleware: MiddlewareFunction): void;
receiveMiddleware(middleware: MiddlewareFunction): void;

class Middleware {
  constructor(robot: Robot);
  register(middleware: MiddlewareFunction): void;
  async execute(context: object): Promise<boolean>;
}

Scripts and Middleware

Command Line Interface

Complete CLI for creating, configuring, and running hubot instances with various adapter and configuration options.

# Create new bot deployment
hubot --create mybot --adapter @hubot-friends/hubot-slack

# Run bot with options
hubot --adapter Shell --name MyBot --alias "!"

# Configuration testing
hubot --config-check

Command Line Interface

Data Persistence

Pluggable data storage system providing persistent storage for robot data with support for custom backend implementations.

class DataStore {
  constructor(robot: Robot);
  async set(key: string, value: any): Promise<void>;
  async setObject(key: string, objectKey: string, value: any): Promise<void>;
  async setArray(key: string, value: any): Promise<void>;
  async get(key: string): Promise<any>;
  async getObject(key: string, objectKey: string): Promise<any>;
}

class DataStoreUnavailable extends Error {}

Data Persistence

Types

interface ListenerOptions {
  id?: string;
}

interface UserOptions {
  name?: string;
  room?: string;
  [key: string]: any;
}

interface Envelope {
  room: string;
  user: User;
  message: Message;
}

interface HttpClient {
  get(): Promise<any>;
  post(data?: any): Promise<any>;
  put(data?: any): Promise<any>;
  delete(): Promise<any>;
  patch(data?: any): Promise<any>;
  head(): Promise<any>;
  header(name: string, value: string): HttpClient;
  headers(headers: object): HttpClient;
  query(params: object): HttpClient;
  timeout(ms: number): HttpClient;
  auth(user: string, pass: string): HttpClient;
  encoding(encoding: string): HttpClient;
}

abstract class Message {
  constructor(user: User, done?: boolean);
  finish(): void;
  user: User;
  done: boolean;
  room?: string;
}

class TextMessage extends Message {
  constructor(user: User, text: string, id?: string);
  match(regex: RegExp): RegExpMatchArray | null;
  toString(): string;
  text: string;
  id?: string;
}

class EnterMessage extends Message {}
class LeaveMessage extends Message {}
class TopicMessage extends TextMessage {}
class CatchAllMessage extends Message {
  constructor(message: Message);
  message: Message;
}

type ListenerCallback = (response: Response) => void | Promise<void>;
type MiddlewareFunction = (context: any, next: () => void, done: () => void) => void;