Installation

Install and configure @igniter-js/bot for your runtime. Choose the right adapters and set up your first bot in minutes.

Installation

@igniter-js/bot works on Node.js 18+ and Bun 1.0+. It requires zod as a peer dependency for adapter parameter validation.

npm install @igniter-js/bot zod
pnpm add @igniter-js/bot zod
yarn add @igniter-js/bot zod
bun add @igniter-js/bot zod

Runtime Requirements

RuntimeVersionNotes
Node.js18+Full support for all adapters
Bun1.0+Native File API support for media uploads
Edge RuntimeLimitedOnly adapters that don't use Node-specific APIs

Choosing Adapters

Bot comes with three first-party adapters. Install only the platforms you need — the package is tree-shakeable.

Telegram

Best for: General-purpose bots, group management, channel automation

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

const tgAdapter = telegram({
  token: process.env.TELEGRAM_TOKEN!,
  handle: '@your_bot', // Optional: overrides global handle
  webhook: {
    url: 'https://your-domain.com/api/bot/telegram',
    secret: process.env.TELEGRAM_WEBHOOK_SECRET!, // Optional: validates webhook authenticity
    dropPendingUpdates: true, // Clear pending updates on restart (default: true)
  },
});

Environment variables supported:

  • TELEGRAM_TOKEN — Bot API token (from @BotFather)
  • TELEGRAM_WEBHOOK_URL — Public HTTPS endpoint for webhook
  • TELEGRAM_WEBHOOK_SECRET — Secret token for webhook verification

WhatsApp (Cloud API)

Best for: Customer support, e-commerce, notification bots

import { whatsapp } from '@igniter-js/bot';

const waAdapter = whatsapp({
  token: process.env.WHATSAPP_TOKEN!,
  phone: process.env.WHATSAPP_PHONE!, // Phone number ID from Meta Business
});

WhatsApp Cloud API requires a Meta Business account and a verified phone number. The init method is a no-op — webhook setup is managed through the Meta Developer dashboard.

Discord

Best for: Community servers, gaming, developer communities

import { discord } from '@igniter-js/bot';

const dcAdapter = discord({
  token: process.env.DISCORD_TOKEN!,
  applicationId: process.env.DISCORD_APP_ID!,
  publicKey: process.env.DISCORD_PUBLIC_KEY!, // Required for interaction verification
});

Discord requires interaction signature verification. Always provide publicKey in production, or the adapter will log a warning on every request.

Adapter Capability Comparison

FeatureTelegramWhatsAppDiscord
Text messages
Images
Video
Audio
Documents
Stickers
Location
Contacts
Polls
Interactive buttons✅ (max 3)✅ (max 5/row)
Edit messages
Delete messages
Reactions
Threads
Webhooks
Long polling
Slash commands❌ (bot commands)
Groups✅ (servers)
Max message length4,096 chars4,096 chars2,000 chars
Max file size50 MB100 MB25 MB

Framework Integration Packages

Next.js App Router

The nextRouteHandlerAdapter creates a ready-to-use route handler:

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

export const { GET, POST } = nextRouteHandlerAdapter(bots);

The adapter expects dynamic route segments [adapter] and [botId]. It automatically handles webhook verification (GET) and message processing (POST).

TanStack Start

The tanstackStartRouteHandlerAdapter follows the same pattern:

// app/routes/api/bot/$adapter/$botId.ts
import { tanstackStartRouteHandlerAdapter } from '@igniter-js/bot';

export const { GET, POST } = tanstackStartRouteHandlerAdapter(bots);

Express / Fastify / Hono / Any HTTP Framework

Bot adapters work with any framework through the standard Request/Response API:

// Express example
app.post('/api/bot/:adapter', async (req, res) => {
  const webResponse = await bot.handle(req.params.adapter, toWebRequest(req));
  res.status(webResponse.status);
  // Forward headers and body...
});

See the Framework Integration guide for complete examples with Express, Fastify, Hono, and more.


Environment Variables Reference

Bot adapters read from environment variables as defaults. You only need to pass config values explicitly when the env vars differ.

VariableUsed ByDescription
TELEGRAM_TOKENTelegramBot API token
TELEGRAM_WEBHOOK_URLTelegramWebhook endpoint URL
TELEGRAM_WEBHOOK_SECRETTelegramWebhook secret token
WHATSAPP_TOKENWhatsAppCloud API access token
WHATSAPP_PHONEWhatsAppPhone number ID
DISCORD_TOKENDiscordBot token
DISCORD_APP_IDDiscordApplication ID
DISCORD_PUBLIC_KEYDiscordPublic key for signature verification

Next Steps