Introduction

Overview

The Bots package provides a modern, type-safe foundation for building multi-platform chatbots in Igniter.js applications. Whether you're creating a Telegram bot, WhatsApp integration, or supporting multiple messaging platforms, this package gives you a unified, extensible API with excellent developer experience.

Key Features

• Multi-Platform: First-party adapters for Telegram and WhatsApp Cloud API
• Adapter Pattern: Clean, extensible architecture for adding new messaging providers
• Type Safety: End-to-end TypeScript with Zod runtime validation
• Middleware Pipeline: Express-like chain for cross-cutting concerns (auth, metrics, rate limiting)
• Command System: Aliases, help text, and structured command handling
• Mention Detection: Configurable bot handle activation for group contexts
• Structured Logging: Pluggable logger interface for consistent logging
• Error Handling: Consistent error codes and BotError class for better observability
• Lightweight: Tree-shakeable exports with no hidden side effects
• Extensible: Dynamic runtime registration of adapters, commands, and middleware

Architecture

The Bots system follows Igniter.js's adapter pattern. The core Bot class provides a unified interface while adapters handle platform-specific logic.

Introduction

Get started with the Bots package in just a few steps. This quick guide will help you create your first bot and understand the core concepts.

npm install @igniter-js/bot

pnpm add @igniter-js/bot

yarn add @igniter-js/bot

bun add @igniter-js/bot

import { Bot, telegram } from '@igniter-js/bot'

const bot = Bot.create({
  id: 'demo-bot',
  name: 'Demo Bot',
  adapters: {
    telegram: telegram({
      token: process.env.TELEGRAM_TOKEN!,
      handle: '@demo_bot',
      webhook: {
        url: process.env.TELEGRAM_WEBHOOK_URL!,
        secret: process.env.TELEGRAM_SECRET
      }
    })
  },
  commands: {
    start: Bot.command({
      name: 'start',
      aliases: ['hello'],
      description: 'Greets the user',
      help: 'Use /start to receive a welcome message.',
      async handle(ctx) {
        await ctx.bot.send({
          provider: ctx.provider,
          channel: ctx.channel.id,
          content: { type: 'text', content: '👋 Welcome, friend!' }
        })
      }
    })
  }
})

await bot.start()

// Next.js API Route example
export async function POST(req: Request) {
  return bot.handle('telegram', req)
}

Concepts

Understand the core concepts that make the Bots package powerful and easy to use. Each concept is designed to work together seamlessly, providing a complete solution for building multi-platform chatbots.

Example Use Cases

The Bots package is flexible enough to power a wide variety of applications. Here are some common use cases where bots shine:

Roadmap