Telegraf Mixpanel

1.0.0 verified Sat Apr 25 auth: no javascript

Mixpanel analytics middleware for the Telegraf Telegram bot framework. Current version 1.0.0. Provides a simple way to track events, set people properties, and manage charges directly from Telegraf context via `ctx.mixpanel`. Requires Telegraf v2 or v3. Lightweight wrapper around the Mixpanel Node.js library, designed for bot-specific analytics workflows like sales funnels. No breaking changes yet; limited to single Mixpanel instance per bot.

Common errors

error Cannot find module 'mixpanel' ↓

cause telegraf-mixpanel depends on mixpanel but does not list it as a dependency.

fix

Run npm install mixpanel.

error TelegrafMixpanel is not a constructor ↓

cause CommonJS require returns an object with a default property? Or wrong import style.

fix

Use const TelegrafMixpanel = require('telegraf-mixpanel'); (not destructured).

error TypeError: Cannot read property 'track' of undefined ↓

cause `ctx.mixpanel` is undefined because middleware was not applied.

fix

Call bot.use(mixpanel.middleware()) before using the bot.

Warnings

gotcha `ctx.mixpanel` is not available outside of middleware (e.g., in error handlers). The mixpanel object is attached only on handled updates. ↓

fix Ensure mixpanel usage is inside middleware chain where ctx has been processed.

gotcha Mixpanel Node library must be installed separately? Actually bundling: telegraf-mixpanel does not bundle mixpanel; it uses `require('mixpanel')` internally. If mixpanel is not installed, it will throw at runtime. ↓

fix Install mixpanel: `npm install mixpanel`.

deprecated Telegraf v2 and v3 are deprecated; newer Telegraf v4+ may not be compatible. The peer dep range `^2.0.0 || ^3.0.0` does not include v4. ↓

fix For Telegraf v4+, do not use this package; consider updating to a maintained fork.

gotcha Default export is a constructor, not mixpanel client itself. You must call `new TelegrafMixpanel(token)`. ↓

fix Correct usage: `const TelegrafMixpanel = require('telegraf-mixpanel'); const m = new TelegrafMixpanel(token);`

gotcha `ctx.mixpanel` methods (track, people, etc.) are synchronous wrappers; errors are not handled. If Mixpanel token is invalid, calls may fail silently or throw. ↓

fix Ensure Mixpanel token is valid and handle errors with try/catch.

Install

npm install telegraf-mixpanel

yarn add telegraf-mixpanel

pnpm add telegraf-mixpanel

Imports

default

wrong

import TelegrafMixpanel from 'telegraf-mixpanel'

correct

const TelegrafMixpanel = require('telegraf-mixpanel')

CommonJS only. No default export; use require.

middleware

const { middleware } = require('telegraf-mixpanel')

Named export for the middleware function.

type TelegrafMixpanel

const TelegrafMixpanel = require('telegraf-mixpanel')

No TypeScript types provided.

Quickstart

Initializes Telegraf bot, attaches Mixpanel middleware, and tracks a 'start' event and people property on /start.

const Telegraf = require('telegraf');
const TelegrafMixpanel = require('telegraf-mixpanel');

const bot = new Telegraf(process.env.BOT_TOKEN ?? '');
const mixpanel = new TelegrafMixpanel(process.env.MIXPANEL_TOKEN ?? '');

bot.use(mixpanel.middleware());

bot.command('/start', (ctx) => {
  ctx.mixpanel.track('start', { source: 'telegram' });
  ctx.mixpanel.people.set({ $name: ctx.from.first_name ?? '' });
  return ctx.reply('Welcome!');
});

bot.launch();