{"id":18845,"library":"telegraf-mixpanel","title":"Telegraf Mixpanel","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/telegraf/telegraf-mixpanel","tags":["javascript","telegram","telegram bot","telegraf","bot framework","mixpanel","stats"],"install":[{"cmd":"npm install telegraf-mixpanel","lang":"bash","label":"npm"},{"cmd":"yarn add telegraf-mixpanel","lang":"bash","label":"yarn"},{"cmd":"pnpm add telegraf-mixpanel","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency – provides bot context and middleware system","package":"telegraf","optional":false}],"imports":[{"note":"CommonJS only. No default export; use require.","wrong":"import TelegrafMixpanel from 'telegraf-mixpanel'","symbol":"default","correct":"const TelegrafMixpanel = require('telegraf-mixpanel')"},{"note":"Named export for the middleware function.","wrong":"","symbol":"middleware","correct":"const { middleware } = require('telegraf-mixpanel')"},{"note":"No TypeScript types provided.","wrong":"","symbol":"type TelegrafMixpanel","correct":"const TelegrafMixpanel = require('telegraf-mixpanel')"}],"quickstart":{"code":"const Telegraf = require('telegraf');\nconst TelegrafMixpanel = require('telegraf-mixpanel');\n\nconst bot = new Telegraf(process.env.BOT_TOKEN ?? '');\nconst mixpanel = new TelegrafMixpanel(process.env.MIXPANEL_TOKEN ?? '');\n\nbot.use(mixpanel.middleware());\n\nbot.command('/start', (ctx) => {\n  ctx.mixpanel.track('start', { source: 'telegram' });\n  ctx.mixpanel.people.set({ $name: ctx.from.first_name ?? '' });\n  return ctx.reply('Welcome!');\n});\n\nbot.launch();","lang":"javascript","description":"Initializes Telegraf bot, attaches Mixpanel middleware, and tracks a 'start' event and people property on /start."},"warnings":[{"fix":"Ensure mixpanel usage is inside middleware chain where ctx has been processed.","message":"`ctx.mixpanel` is not available outside of middleware (e.g., in error handlers). The mixpanel object is attached only on handled updates.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install mixpanel: `npm install mixpanel`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Telegraf v4+, do not use this package; consider updating to a maintained fork.","message":"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.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Correct usage: `const TelegrafMixpanel = require('telegraf-mixpanel'); const m = new TelegrafMixpanel(token);`","message":"Default export is a constructor, not mixpanel client itself. You must call `new TelegrafMixpanel(token)`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure Mixpanel token is valid and handle errors with try/catch.","message":"`ctx.mixpanel` methods (track, people, etc.) are synchronous wrappers; errors are not handled. If Mixpanel token is invalid, calls may fail silently or throw.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run `npm install mixpanel`.","cause":"telegraf-mixpanel depends on mixpanel but does not list it as a dependency.","error":"Cannot find module 'mixpanel'"},{"fix":"Use `const TelegrafMixpanel = require('telegraf-mixpanel');` (not destructured).","cause":"CommonJS require returns an object with a default property? Or wrong import style.","error":"TelegrafMixpanel is not a constructor"},{"fix":"Call `bot.use(mixpanel.middleware())` before using the bot.","cause":"`ctx.mixpanel` is undefined because middleware was not applied.","error":"TypeError: Cannot read property 'track' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}