Skip to main content

Reference

botui package currently exports the following methods, properties and types:

import {
  Plugin,
  Block,
  BlockData,
  BlockMeta,

  createBot,
  BOTUI_BLOCK_TYPES
} from 'botui'

Types​

  • Plugin
  • Block
  • BlockData
  • BlockMeta

Methods and properties​

  • createBot(): BotuiInterface: returns a new BotuiInterface instance.
  • BOTUI_BLOCK_TYPES: an object of block types:
{
  ACTION: 'action',
  MESSAGE: 'message',
}

Interface​

A BotuiInterface instance has following objects and methods.

  • message:
    • .add(data: BlockData, meta: BlockMeta): Promise<number>: Adds a new non-action block to the chat list. Returns its key to be used with .remove() or .update().
    • .getAll(): Promise<Block[]>: Get all of the current blocks listed in the chat.
    • .setAll(blocks: Block[]): Promise<Block[]>: Load existing list of blocks.
    • .get(key: number): Promise<Block>: Get a single block by it's key.
    • .remove(key: number): Promise<void>: Remove a single block by it's key.
    • .update(key: number, data: BlockData, meta: BlockMeta): Promise<void>: Update a single block by it's key.
    • .removeAll(): Promise<void>: Removes all the blocks.
  • action:
    • .set(data: BlockData, meta: BlockMeta): Promise<any>: Asks the user to perform an action. BotUI won't go further until it is resolved by calling .next(data?, meta?) which results in an internal call to message.set(data, meta) to show human response.
    • .get(): Promise<Block | null>: Returns the current action or null if there is none.
  • .onChange(type: BlockType, cb: CallbackFunction): BotuiInterface: Listen to changes in the current action and messages.
  • .wait({ waitTime: <milliseconds> }, forwardData?: BlockData, forwardMeta?: BlockMeta): Promise<any>: Wait does not let the next message/action resolve until .next() is called. When waitTime property is present in the meta, .next(forwardData, forwardMeta) is called internally with that meta.
  • .next(...args: any[]): BotuiInterface: Resolves current action or wait command. Passed data is sent to the next .then()
  • .use(plugin: Plugin): BotuiInterface: Register a plugin with this instance.

Plugins​

A plugin is a function that transforms blocks as they flow through the BotUI system. Plugins enable powerful customization without modifying core functionality.

Plugin Signature​

const plugin = (block: Block) => Block

Basic Plugin Examples​

The plugin below replaces !(text) with <i>text</i>

const myBot = createBot()
myBot.use(block => {
  if (block.type == BOTUI_BLOCK_TYPES.MESSAGE) {
    block.data.text = block.data?.text?.replace(/!\(([^\)]+)\)/igm, "<i>$1</i>")
  }
  return block
})

For comprehensive plugin documentation including advanced examples, best practices, and error handling, see the Plugins Guide.