Introduction

Overview

@igniter-js/bot is a multi-platform bot framework for Node.js and Bun. It lets you build conversational bots that run on Telegram, WhatsApp, and Discord simultaneously — sharing commands, middlewares, and session state across all platforms.

You define your bot once using the builder pattern, add adapters for each platform, and get a unified API for handling messages, commands, and interactive content — with full TypeScript autocomplete everywhere.

Key Features

• Multi-Platform — Telegram, WhatsApp, Discord, and custom adapters. One codebase, every chat platform.
• Fluent Builder API — IgniterBot.create().withHandle().addAdapters().addCommand().build() — fully typed at every step.
• Command System — Slash commands with aliases, subcommands, Zod argument validation, and automatic platform registration.
• Middleware Pipeline — auth, rateLimit, logging built-in. Extend with custom middleware for any use case.
• Plugin Architecture — Package commands, middlewares, adapters, and hooks into reusable plugins.
• Session Management — Persistent conversational state with pluggable storage (memory, Redis, Prisma).
• Rich Content Types — Send text, images, video, audio, documents, stickers, location, contacts, polls, and interactive buttons.
• Type-Safe Context — BotContext gives you typed access to message, channel, author, session, and reply helpers.
• Framework Integration — Native handlers for Next.js App Router and TanStack Start. Express/Fastify compatible via standard Request/Response.
• Adapter Client — Every adapter exposes a pre-configured HTTP client for making direct API calls when needed.

Architecture

Bot follows the adapter pattern — the same pattern used across the Igniter.js ecosystem. The core handles commands, middlewares, sessions, and event routing. Adapters translate between platform-specific APIs and the normalized BotContext.

graph TD
    A[Incoming Request] --> B[Platform Adapter]
    B --> C[Adapter.handle]
    C --> D{Normalized BotContext}
    D --> E[Session Loader]
    E --> F[Pre-Process Hooks]
    F --> G[Middleware Pipeline]
    G --> H[Command Router]
    H --> I[Command Handler]
    G --> J[Event Listeners]
    I --> K[Reply via Adapter]
    J --> K
    K --> L[Platform API]

Every incoming message flows through: adapter parsing → session loading → pre-process hooks → middleware chain → command routing → handler execution → reply dispatch.

Quick Start

Get a cross-platform bot running in under three minutes.

npm install @igniter-js/bot zod

pnpm add @igniter-js/bot zod

yarn add @igniter-js/bot zod

bun add @igniter-js/bot zod

import { IgniterBot, telegram, whatsapp, discord, memoryStore } from '@igniter-js/bot';

const bot = IgniterBot
  .create()
  .withHandle('@my_awesome_bot')
  .withSessionStore(memoryStore())
  .addAdapters({
    telegram: telegram({ token: process.env.TELEGRAM_TOKEN! }),
    whatsapp: whatsapp({
      token: process.env.WHATSAPP_TOKEN!,
      phone: process.env.WHATSAPP_PHONE!,
    }),
    discord: discord({
      token: process.env.DISCORD_TOKEN!,
      applicationId: process.env.DISCORD_APP_ID!,
      publicKey: process.env.DISCORD_PUBLIC_KEY!,
    }),
  })
  .addCommand('start', {
    name: 'start',
    aliases: ['hello', 'hi'],
    description: 'Greets the user',
    help: 'Use /start to receive a welcome message',
    async handle(ctx) {
      await ctx.reply(
        `👋 Hello, ${ctx.message.author.name}! I'm running on ${ctx.provider}.`,
      );
    },
  })
  .addCommand('ping', {
    name: 'ping',
    aliases: [],
    description: 'Check bot responsiveness',
    help: 'Use /ping to check if the bot is alive',
    async handle(ctx) {
      const start = Date.now();
      await ctx.reply('Pong! 🏓');
    },
  })
  .build();

await bot.start();

// app/api/bot/[adapter]/route.ts
import { nextRouteHandlerAdapter } from '@igniter-js/bot';
import { bot } from '@/lib/bot';

export const { GET, POST } = nextRouteHandlerAdapter({
  'my_awesome_bot': bot,
});

Core Concepts

Real-World Use Cases

Bot powers conversational applications across many domains:

Next Steps