dashgram

Name	dashgram JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	A Python SDK for Dashgram
upload_time	2025-08-29 13:35:09
maintainer	None
docs_url	None
author	MrNereof
requires_python	>=3.9
license	MIT
keywords	sdk api client
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Dashgram SDK

A Python SDK for Dashgram - Analytics and tracking for Telegram bots with seamless integration for popular Python Telegram bot frameworks.

[![PyPI version](https://badge.fury.io/py/dashgram.svg)](https://badge.fury.io/py/dashgram)
[![Python versions](https://img.shields.io/pypi/pyversions/dashgram.svg)](https://pypi.org/project/dashgram/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🚀 **Easy Integration** - Works with aiogram, python-telegram-bot, and pyTelegramBotAPI
- 📊 **Event Tracking** - Track messages, callback queries, and all Telegram update types
- 🔄 **Framework Agnostic** - Automatically detects your bot framework
- ⚡ **Async Support** - Full async/await support with automatic sync wrapper
- 🛡️ **Error Handling** - Robust error handling with configurable exception suppression
- 🎯 **Invitation Tracking** - Track user invitations and referrals

## Supported Frameworks

- [aiogram](https://github.com/aiogram/aiogram) (v3.x)
- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) (v21.x)
- [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (v4.x)

## Installation

```bash
pip install dashgram
```

## Quick Start

### Basic Usage

```python
from dashgram import Dashgram, HandlerType

# Initialize the SDK with your project credentials
sdk = Dashgram(
    project_id="your_project_id",
    access_key="your_access_key"
)

# Track any Telegram update
sdk.track_event(update)

# Track a specific event type
sdk.track_event(event_data, HandlerType.MESSAGE)

# Mark user as invited by another user (for referral analytics)
sdk.invited_by(user_id, inviter_user_id)
```

The `event_data` parameter should contain the update data in raw Telegram API format, or the corresponding update/message object from your framework (aiogram, python-telegram-bot, or pyTelegramBotAPI).

### Framework Integration

#### aiogram

Choose the integration method that best fits your needs:

```python
import asyncio
from aiogram import Bot, Dispatcher
from aiogram.types import Message, Update
from dashgram import Dashgram, HandlerType

# Initialize SDK with your credentials
sdk = Dashgram(
    project_id="your_project_id", 
    access_key="your_access_key"
)

dp = Dispatcher()

# Option 1: Automatic tracking (recommended for most use cases)
sdk.bind_aiogram(dp)

@dp.message()
async def handle_message(message: Message, event_update: Update):
    # Option 2: Manual tracking with full update data
    await sdk.track_event(event_update)
    ...

@dp.edited_message()
async def handle_edited_message(edited_message: Message):
    # Option 3: Manual tracking with specific handler type
    await sdk.track_event(edited_message, HandlerType.EDITED_MESSAGE)
    ...
```

#### python-telegram-bot (v21.x)

```python
from telegram.ext import Application, MessageHandler, filters
from dashgram import Dashgram

# Initialize SDK with your credentials
sdk = Dashgram(
    project_id="your_project_id", 
    access_key="your_access_key"
)

async def handle_message(update, context):
    # Manual tracking for specific events
    await sdk.track_event(update)
    ...

application = Application.builder().token("YOUR_BOT_TOKEN").build()
application.add_handler(MessageHandler(filters.TEXT, handle_message))

# Automatic tracking for all events
sdk.bind_telegram(application)

application.run_polling()
```

#### pyTelegramBotAPI

```python
import telebot
from dashgram import Dashgram, HandlerType

# Initialize SDK with your credentials
sdk = Dashgram(
    project_id="your_project_id", 
    access_key="your_access_key"
)

bot = telebot.TeleBot("YOUR_BOT_TOKEN", use_class_middlewares=True)

# Automatic tracking for all events
sdk.bind_telebot(bot)

@bot.message_handler(func=lambda message: True)
def handle_message(message):
    # Manual tracking for specific events
    sdk.track_event(message, HandlerType.MESSAGE)
    ...

bot.polling()
```

## API Reference

### Dashgram Class

#### Constructor

```python
Dashgram(
    project_id: Union[int, str],
    access_key: str,
    *,
    api_url: Optional[str] = None,
    origin: Optional[str] = None
)
```

**Parameters:**
- `project_id` - Your Dashgram project ID (found in your project settings)
- `access_key` - Your Dashgram access key (found in your project settings)
- `api_url` - Custom API URL (defaults to `https://api.dashgram.io/v1`)
- `origin` - Custom origin string for SDK usage analytics (optional)

#### Methods

##### track_event()

```python
async def track_event(
    event,
    handler_type: Optional[HandlerType] = None,
    suppress_exceptions: bool = True
) -> bool
```

Track a Telegram event or update. This method automatically detects the framework and extracts relevant data.

**Parameters:**
- `event` - Telegram event object or dictionary (from any supported framework)
- `handler_type` - Type of handler (optional if event is a framework object)
- `suppress_exceptions` - Whether to suppress exceptions (default: True)

**Returns:** `bool` - True if successful, False otherwise

##### invited_by()

```python
async def invited_by(
    user_id: int,
    invited_by: int,
    suppress_exceptions: bool = True
) -> bool
```

Track user invitation/referral for analytics purposes.

**Parameters:**
- `user_id` - ID of the invited user
- `invited_by` - ID of the user who sent the invitation
- `suppress_exceptions` - Whether to suppress exceptions (default: True)

**Returns:** `bool` - True if successful, False otherwise

##### Framework Binding Methods

```python
def bind_aiogram(dp) -> None
def bind_telegram(app, group: int = -1, block: bool = False) -> None
def bind_telebot(bot) -> None
```

Automatically track all events for the respective framework. These methods integrate middleware or handlers to capture all bot interactions.

## Examples

### Complete aiogram Example

```python
import asyncio
import logging
from os import getenv

from aiogram import Bot, Dispatcher, html
from aiogram.enums import ParseMode
from aiogram.filters import CommandStart
from aiogram.types import Message

from dashgram import Dashgram, HandlerType

# Setup logging
logging.basicConfig(level=logging.INFO)

# Initialize SDK with environment variables
sdk = Dashgram(
    project_id=getenv("PROJECT_ID"),
    access_key=getenv("ACCESS_KEY")
)

dp = Dispatcher()

# Manual tracking example
@dp.message(CommandStart())
async def start_handler(message: Message):
    await message.answer(f"Hello, {html.bold(message.from_user.full_name)}!")

# Automatic tracking for all events
sdk.bind_aiogram(dp)

async def main():
    bot = Bot(token=getenv("BOT_TOKEN"))
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())
```

### Complete python-telegram-bot Example

```python
import logging
from os import getenv

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters

from dashgram import Dashgram

# Setup logging
logging.basicConfig(level=logging.INFO)

# Initialize SDK with environment variables
sdk = Dashgram(
    project_id=getenv("PROJECT_ID"),
    access_key=getenv("ACCESS_KEY")
)

async def start(update: Update, context):
    await update.message.reply_text("Hello!")

async def echo(update: Update, context):
    await update.message.reply_text(update.message.text)

def main():
    application = Application.builder().token(getenv("BOT_TOKEN")).build()
    
    # Add handlers
    application.add_handler(CommandHandler("start", start))
    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    
    # Automatic tracking for all events
    sdk.bind_telegram(application)
    
    application.run_polling()

if __name__ == "__main__":
    main()
```

### Complete pyTelegramBotAPI Example

```python
import logging
from os import getenv

import telebot
from dashgram import Dashgram

# Setup logging
logging.basicConfig(level=logging.INFO)

# Initialize SDK with environment variables
sdk = Dashgram(
    project_id=getenv("PROJECT_ID"),
    access_key=getenv("ACCESS_KEY")
)

bot = telebot.TeleBot(getenv("BOT_TOKEN"), use_class_middlewares=True)

# Automatic tracking for all events
sdk.bind_telebot(bot)

@bot.message_handler(commands=['start'])
def start(message):
    bot.reply_to(message, "Hello!")

@bot.message_handler(func=lambda message: True)
def echo(message):
    bot.reply_to(message, message.text)

if __name__ == "__main__":
    bot.polling()
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📧 Email: team@dashgram.io
- 📖 Documentation: [docs.dashgram.io](https://docs.dashgram.io)
- 🐛 Issues: [GitHub Issues](https://github.com/Dashgram/sdk-python/issues)
- 💬 Community: [Telegram Channel](https://t.me/dashgram_live)

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "dashgram",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "sdk, api, client",
    "author": "MrNereof",
    "author_email": "mrnereof@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/c5/21/4664c75065f0b520958018ff031e1e5d88868d57c2f25400b7a9fe375733/dashgram-0.1.0.tar.gz",
    "platform": null,
    "description": "# Dashgram SDK\n\nA Python SDK for Dashgram - Analytics and tracking for Telegram bots with seamless integration for popular Python Telegram bot frameworks.\n\n[![PyPI version](https://badge.fury.io/py/dashgram.svg)](https://badge.fury.io/py/dashgram)\n[![Python versions](https://img.shields.io/pypi/pyversions/dashgram.svg)](https://pypi.org/project/dashgram/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Features\n\n- \ud83d\ude80 **Easy Integration** - Works with aiogram, python-telegram-bot, and pyTelegramBotAPI\n- \ud83d\udcca **Event Tracking** - Track messages, callback queries, and all Telegram update types\n- \ud83d\udd04 **Framework Agnostic** - Automatically detects your bot framework\n- \u26a1 **Async Support** - Full async/await support with automatic sync wrapper\n- \ud83d\udee1\ufe0f **Error Handling** - Robust error handling with configurable exception suppression\n- \ud83c\udfaf **Invitation Tracking** - Track user invitations and referrals\n\n## Supported Frameworks\n\n- [aiogram](https://github.com/aiogram/aiogram) (v3.x)\n- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) (v21.x)\n- [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (v4.x)\n\n## Installation\n\n```bash\npip install dashgram\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom dashgram import Dashgram, HandlerType\n\n# Initialize the SDK with your project credentials\nsdk = Dashgram(\n    project_id=\"your_project_id\",\n    access_key=\"your_access_key\"\n)\n\n# Track any Telegram update\nsdk.track_event(update)\n\n# Track a specific event type\nsdk.track_event(event_data, HandlerType.MESSAGE)\n\n# Mark user as invited by another user (for referral analytics)\nsdk.invited_by(user_id, inviter_user_id)\n```\n\nThe `event_data` parameter should contain the update data in raw Telegram API format, or the corresponding update/message object from your framework (aiogram, python-telegram-bot, or pyTelegramBotAPI).\n\n### Framework Integration\n\n#### aiogram\n\nChoose the integration method that best fits your needs:\n\n```python\nimport asyncio\nfrom aiogram import Bot, Dispatcher\nfrom aiogram.types import Message, Update\nfrom dashgram import Dashgram, HandlerType\n\n# Initialize SDK with your credentials\nsdk = Dashgram(\n    project_id=\"your_project_id\", \n    access_key=\"your_access_key\"\n)\n\ndp = Dispatcher()\n\n# Option 1: Automatic tracking (recommended for most use cases)\nsdk.bind_aiogram(dp)\n\n@dp.message()\nasync def handle_message(message: Message, event_update: Update):\n    # Option 2: Manual tracking with full update data\n    await sdk.track_event(event_update)\n    ...\n\n@dp.edited_message()\nasync def handle_edited_message(edited_message: Message):\n    # Option 3: Manual tracking with specific handler type\n    await sdk.track_event(edited_message, HandlerType.EDITED_MESSAGE)\n    ...\n```\n\n#### python-telegram-bot (v21.x)\n\n```python\nfrom telegram.ext import Application, MessageHandler, filters\nfrom dashgram import Dashgram\n\n# Initialize SDK with your credentials\nsdk = Dashgram(\n    project_id=\"your_project_id\", \n    access_key=\"your_access_key\"\n)\n\nasync def handle_message(update, context):\n    # Manual tracking for specific events\n    await sdk.track_event(update)\n    ...\n\napplication = Application.builder().token(\"YOUR_BOT_TOKEN\").build()\napplication.add_handler(MessageHandler(filters.TEXT, handle_message))\n\n# Automatic tracking for all events\nsdk.bind_telegram(application)\n\napplication.run_polling()\n```\n\n#### pyTelegramBotAPI\n\n```python\nimport telebot\nfrom dashgram import Dashgram, HandlerType\n\n# Initialize SDK with your credentials\nsdk = Dashgram(\n    project_id=\"your_project_id\", \n    access_key=\"your_access_key\"\n)\n\nbot = telebot.TeleBot(\"YOUR_BOT_TOKEN\", use_class_middlewares=True)\n\n# Automatic tracking for all events\nsdk.bind_telebot(bot)\n\n@bot.message_handler(func=lambda message: True)\ndef handle_message(message):\n    # Manual tracking for specific events\n    sdk.track_event(message, HandlerType.MESSAGE)\n    ...\n\nbot.polling()\n```\n\n## API Reference\n\n### Dashgram Class\n\n#### Constructor\n\n```python\nDashgram(\n    project_id: Union[int, str],\n    access_key: str,\n    *,\n    api_url: Optional[str] = None,\n    origin: Optional[str] = None\n)\n```\n\n**Parameters:**\n- `project_id` - Your Dashgram project ID (found in your project settings)\n- `access_key` - Your Dashgram access key (found in your project settings)\n- `api_url` - Custom API URL (defaults to `https://api.dashgram.io/v1`)\n- `origin` - Custom origin string for SDK usage analytics (optional)\n\n#### Methods\n\n##### track_event()\n\n```python\nasync def track_event(\n    event,\n    handler_type: Optional[HandlerType] = None,\n    suppress_exceptions: bool = True\n) -> bool\n```\n\nTrack a Telegram event or update. This method automatically detects the framework and extracts relevant data.\n\n**Parameters:**\n- `event` - Telegram event object or dictionary (from any supported framework)\n- `handler_type` - Type of handler (optional if event is a framework object)\n- `suppress_exceptions` - Whether to suppress exceptions (default: True)\n\n**Returns:** `bool` - True if successful, False otherwise\n\n##### invited_by()\n\n```python\nasync def invited_by(\n    user_id: int,\n    invited_by: int,\n    suppress_exceptions: bool = True\n) -> bool\n```\n\nTrack user invitation/referral for analytics purposes.\n\n**Parameters:**\n- `user_id` - ID of the invited user\n- `invited_by` - ID of the user who sent the invitation\n- `suppress_exceptions` - Whether to suppress exceptions (default: True)\n\n**Returns:** `bool` - True if successful, False otherwise\n\n##### Framework Binding Methods\n\n```python\ndef bind_aiogram(dp) -> None\ndef bind_telegram(app, group: int = -1, block: bool = False) -> None\ndef bind_telebot(bot) -> None\n```\n\nAutomatically track all events for the respective framework. These methods integrate middleware or handlers to capture all bot interactions.\n\n## Examples\n\n### Complete aiogram Example\n\n```python\nimport asyncio\nimport logging\nfrom os import getenv\n\nfrom aiogram import Bot, Dispatcher, html\nfrom aiogram.enums import ParseMode\nfrom aiogram.filters import CommandStart\nfrom aiogram.types import Message\n\nfrom dashgram import Dashgram, HandlerType\n\n# Setup logging\nlogging.basicConfig(level=logging.INFO)\n\n# Initialize SDK with environment variables\nsdk = Dashgram(\n    project_id=getenv(\"PROJECT_ID\"),\n    access_key=getenv(\"ACCESS_KEY\")\n)\n\ndp = Dispatcher()\n\n# Manual tracking example\n@dp.message(CommandStart())\nasync def start_handler(message: Message):\n    await message.answer(f\"Hello, {html.bold(message.from_user.full_name)}!\")\n\n# Automatic tracking for all events\nsdk.bind_aiogram(dp)\n\nasync def main():\n    bot = Bot(token=getenv(\"BOT_TOKEN\"))\n    await dp.start_polling(bot)\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### Complete python-telegram-bot Example\n\n```python\nimport logging\nfrom os import getenv\n\nfrom telegram import Update\nfrom telegram.ext import Application, CommandHandler, MessageHandler, filters\n\nfrom dashgram import Dashgram\n\n# Setup logging\nlogging.basicConfig(level=logging.INFO)\n\n# Initialize SDK with environment variables\nsdk = Dashgram(\n    project_id=getenv(\"PROJECT_ID\"),\n    access_key=getenv(\"ACCESS_KEY\")\n)\n\nasync def start(update: Update, context):\n    await update.message.reply_text(\"Hello!\")\n\nasync def echo(update: Update, context):\n    await update.message.reply_text(update.message.text)\n\ndef main():\n    application = Application.builder().token(getenv(\"BOT_TOKEN\")).build()\n    \n    # Add handlers\n    application.add_handler(CommandHandler(\"start\", start))\n    application.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))\n    \n    # Automatic tracking for all events\n    sdk.bind_telegram(application)\n    \n    application.run_polling()\n\nif __name__ == \"__main__\":\n    main()\n```\n\n### Complete pyTelegramBotAPI Example\n\n```python\nimport logging\nfrom os import getenv\n\nimport telebot\nfrom dashgram import Dashgram\n\n# Setup logging\nlogging.basicConfig(level=logging.INFO)\n\n# Initialize SDK with environment variables\nsdk = Dashgram(\n    project_id=getenv(\"PROJECT_ID\"),\n    access_key=getenv(\"ACCESS_KEY\")\n)\n\nbot = telebot.TeleBot(getenv(\"BOT_TOKEN\"), use_class_middlewares=True)\n\n# Automatic tracking for all events\nsdk.bind_telebot(bot)\n\n@bot.message_handler(commands=['start'])\ndef start(message):\n    bot.reply_to(message, \"Hello!\")\n\n@bot.message_handler(func=lambda message: True)\ndef echo(message):\n    bot.reply_to(message, message.text)\n\nif __name__ == \"__main__\":\n    bot.polling()\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: team@dashgram.io\n- \ud83d\udcd6 Documentation: [docs.dashgram.io](https://docs.dashgram.io)\n- \ud83d\udc1b Issues: [GitHub Issues](https://github.com/Dashgram/sdk-python/issues)\n- \ud83d\udcac Community: [Telegram Channel](https://t.me/dashgram_live)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python SDK for Dashgram",
    "version": "0.1.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/Dashgram/sdk-python/issues",
        "Homepage": "https://github.com/Dashgram/sdk-python",
        "Source Code": "https://github.com/Dashgram/sdk-python"
    },
    "split_keywords": [
        "sdk",
        " api",
        " client"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "10c13d72ce2adbb6362da4192361d9ee663bf5492bf4a0556f12e4a726f60cd3",
                "md5": "289c90db05e9af912545efd84b1112c1",
                "sha256": "53b096652bd54540859523adeb4e8cfb24991aee4bb026ccfafd06ab8caa3a84"
            },
            "downloads": -1,
            "filename": "dashgram-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "289c90db05e9af912545efd84b1112c1",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 16019,
            "upload_time": "2025-08-29T13:35:07",
            "upload_time_iso_8601": "2025-08-29T13:35:07.883019Z",
            "url": "https://files.pythonhosted.org/packages/10/c1/3d72ce2adbb6362da4192361d9ee663bf5492bf4a0556f12e4a726f60cd3/dashgram-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c5214664c75065f0b520958018ff031e1e5d88868d57c2f25400b7a9fe375733",
                "md5": "99c707b621e4bf554aedf71f9b9a5fae",
                "sha256": "4f01af9e1f86fd5864992a24dcadd16096c342536f733c71ad2915581a112325"
            },
            "downloads": -1,
            "filename": "dashgram-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "99c707b621e4bf554aedf71f9b9a5fae",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 14106,
            "upload_time": "2025-08-29T13:35:09",
            "upload_time_iso_8601": "2025-08-29T13:35:09.301002Z",
            "url": "https://files.pythonhosted.org/packages/c5/21/4664c75065f0b520958018ff031e1e5d88868d57c2f25400b7a9fe375733/dashgram-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-29 13:35:09",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Dashgram",
    "github_project": "sdk-python",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "dashgram"
}