Documentation

Get your project key, drop in the SDK, and start tracking. Your data arrives in Telegram.

Quick Start

1

Get your project key

Open @MyTelegramAnalyticsBot in Telegram and type /add yourproject.com. The bot replies instantly with your API key.

2

Add the SDK

Pick your platform below. Initialize once with your key, then track events anywhere.

3

Ask the bot

Type /report signup 7d or set up alerts with /alerts. Charts and alerts arrive in your chat.

SDK Setup

One project key works across all platforms. Events from your web app, mobile app, and backend all flow into the same Telegram reports.

JavaScript / TypeScript

npm install or drop in a script tag. Works in React, Vue, vanilla JS, and server-side rendering.

// npm install tgram-analytics
import TGA from 'tgram-analytics';

// Initialize once
TGA.init('proj_xxx', { serverUrl: 'https://api.tgram-analytics.com' });

// Track events
TGA.track('signup', { plan: 'pro' });
TGA.track('purchase', { amount: 49 });

Flutter / Dart

Add to pubspec.yaml. The SDK buffers events before init, so you can track anywhere.

// flutter pub add tgram_analytics
import 'package:tgram_analytics/tgram_analytics.dart';

// In main():
void main() {
  TGA.init('proj_xxx', 'https://api.tgram-analytics.com');
  runApp(MyApp());
}

// Track from anywhere
TGA.track('purchase', userId, properties: {'amount': 49.99});

Python

Sync and async support. Great for Django, FastAPI, or background jobs.

# pip install tgram-analytics
from tgram_analytics import TGA

# Initialize
tga = TGA("proj_xxx", "https://api.tgram-analytics.com")

# Track events
tga.track(
    "subscription_created",
    session_id=user.id,
    properties={"plan": "pro"}
)
Keep personal data out of properties. Don't put emails, names, phone numbers, tokens, or anything else identifying into event properties. The server drops properties with common PII key names (email, phone, password, token, credit_card, …) before storage — but that tripwire is a safety net, not a guarantee: property values are never inspected, so PII under an innocent key name would be stored as-is. Under the GDPR, you (the operator) are the controller for whatever you choose to send — see the privacy policy and the Data Processing Agreement.

Bot Commands

Everything happens in Telegram. No dashboard to open, no login to remember.

Command What it does Example
/add <project> Create a new project and get an API key /add myapp.com
/report <event> <time> Get a chart and totals for any event /report signup 7d, /report error 24h
/alerts Open an interactive menu to configure event alerts /alerts, then pick an event and threshold
/digest Get a 7-day recap: sessions and alerted-event counts with week-over-week deltas /digest
/projects List all your projects and keys /projects
/help Show all available commands /help

AI Assistant MCP

Connect Claude — or any MCP client — to your tgram-analytics account and ask about your analytics in plain language. Sign in once with Telegram; from then on the assistant can read your projects and events, pull reports, and help you wire up tracking. Access is scoped to the projects you own — no API keys to paste. Reading is unrestricted; the few write actions (creating a project, rotating a project key) are gated on your explicit approval — project creation is confirmed from the Telegram bot.

Endpoint

Point any MCP client at this URL. Authentication is handled for you over OAuth — you log in with Telegram, the same account you use with the bot.

https://mcp.tgram-analytics.com/mcp

Claude Desktop & claude.ai

1

Add a custom connector

Open Settings → Connectors → Add custom connector, paste https://mcp.tgram-analytics.com/mcp, and save.

2

Sign in with Telegram

Click Connect, then Log in with Telegram and approve. The connector is now linked to your projects.

Claude Code, Cursor & other MCP clients

Add the server to your client's MCP config (for example .mcp.json), then run its authenticate step — a browser opens for the one-time Telegram login.

{
  "mcpServers": {
    "tgram-analytics": {
      "type": "http",
      "url": "https://mcp.tgram-analytics.com/mcp"
    }
  }
}

What you can ask

Once connected, just talk to your assistant. A few examples:

Under the hood the assistant calls these tools:

Area Tools
Query analytics query_events, compare_periods, top_pages, recent_events, list_event_names
Projects & setup list_projects, get_project, get_integration_guide, get_sdk_snippet, verify_integration
Write (approval-gated) create_project, get_project_request_status, rotate_api_key

Self-hosting your own instance

Running your own tgram-analytics server? It exposes the same MCP endpoint and tools at /mcp on your own domain. Instead of the hosted OAuth login, you authenticate with a token you create from the bot — no extra infrastructure to set up. One token covers every project on your account.

1

Get your setup details from the bot

Send /mcp to your bot for tailored instructions, then /mcp_token new <label> to mint an access token. The <label> is any name you'll recognise later (e.g. macbook) — it's shown only once, so copy it. Manage or revoke tokens anytime with /mcp_token.

2

Claude Desktop & claude.ai

Open Settings → Connectors → Add custom connector, paste https://your-host/mcp, and click Connect. A browser page opens — paste the token from step 1 to authorize. Every authorization also pings you on Telegram (with the connecting app and a one-tap revoke button).

3

Claude Code, Cursor & other header-capable clients

These send the token as a header directly:

claude mcp add --transport http tgram https://your-host/mcp \
  --header "Authorization: Bearer mcp_..."

In Cursor and similar, add an HTTP MCP server with the same URL and an Authorization: Bearer mcp_... header.

Config: set MCP_PUBLIC_URL=https://your-host so metadata and links use the right address (defaults to WEBHOOK_BASE_URL); set MCP_ENABLED=false to switch the endpoint off entirely. Access is the same scope as the hosted service — your own projects only, with the same approval-gated write actions.