# Telegram Init Data Python
[](https://badge.fury.io/py/telegram-init-data)
[](https://pypi.org/project/telegram-init-data)
[](https://opensource.org/licenses/MIT)
A Python library for working with Telegram Mini Apps initialization data. This library provides utilities to parse, validate, and sign init data on the server side, similar to the official [@telegram-apps/init-data-node](https://docs.telegram-mini-apps.com/packages/telegram-apps-init-data-node/2-x) package.
## Features
- 🔐 **Validate init data** - Verify signature and expiration of Telegram Mini App init data
- 📝 **Parse init data** - Convert URL-encoded init data to structured Python objects
- ✍️ **Sign init data** - Create signed init data for testing and development
- 🔍 **Type safety** - Full type hints and validation
- 🚀 **FastAPI integration** - Ready-to-use middleware for FastAPI applications
- 🌐 **3rd party validation** - Support for validating data signed by Telegram directly
## Installation
```bash
pip install telegram-init-data
```
For FastAPI integration:
```bash
pip install telegram-init-data[fastapi]
```
## Quick Start
### Basic Validation
```python
from telegram_init_data import validate, parse
# Your bot token from @BotFather
bot_token = "YOUR_BOT_TOKEN"
# Init data string from Telegram Mini App
init_data = "query_id=AAHdF6IQAAAAAN0XohDhrOrc&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%22%2C%22last_name%22%3A%22Kibenko%22%2C%22username%22%3A%22vdkfrost%22%2C%22language_code%22%3A%22ru%22%2C%22is_premium%22%3Atrue%7D&auth_date=1662771648&hash=c501b71e775f74ce10e377dea85a7ea24ecd640b223ea86dfe453e0eaed2e2b2"
try:
# Validate the init data
validate(init_data, bot_token)
print("✅ Init data is valid!")
# Parse the init data
parsed_data = parse(init_data)
print(f"User: {parsed_data['user']['first_name']}")
except Exception as e:
print(f"❌ Validation failed: {e}")
```
### Using with FastAPI
```python
from fastapi import FastAPI, Depends, HTTPException
from telegram_init_data import validate, parse
app = FastAPI()
def verify_init_data(init_data: str) -> dict:
"""Dependency to verify and parse init data"""
bot_token = "YOUR_BOT_TOKEN"
try:
validate(init_data, bot_token)
return parse(init_data)
except Exception as e:
raise HTTPException(status_code=401, detail=str(e))
@app.post("/user/profile")
async def get_profile(init_data: dict = Depends(verify_init_data)):
user = init_data.get("user")
if not user:
raise HTTPException(status_code=400, detail="User data not found")
return {"user_id": user["id"], "name": user["first_name"]}
```
### Advanced Usage
```python
from telegram_init_data import sign, is_valid
from datetime import datetime
# Create test init data
test_data = {
"query_id": "test_query_id",
"user": {
"id": 123456789,
"first_name": "John",
"last_name": "Doe",
"username": "johndoe",
"language_code": "en"
},
"auth_date": datetime.now()
}
# Sign the data
signed_data = sign(test_data, bot_token, datetime.now())
print(f"Signed data: {signed_data}")
# Check if data is valid (returns boolean)
if is_valid(signed_data, bot_token):
print("✅ Data is valid")
else:
print("❌ Data is invalid")
```
## API Reference
### Core Functions
#### `validate(value, token, options=None)`
Validates Telegram Mini App init data.
**Parameters:**
- `value` (str | dict): Init data to validate
- `token` (str): Bot token from @BotFather
- `options` (dict, optional): Validation options
- `expires_in` (int): Expiration time in seconds (default: 86400)
**Raises:**
- `SignatureMissingError`: When hash parameter is missing
- `AuthDateInvalidError`: When auth_date is invalid or missing
- `ExpiredError`: When init data has expired
- `SignatureInvalidError`: When signature verification fails
#### `is_valid(value, token, options=None)`
Checks if init data is valid without raising exceptions.
**Returns:** `bool` - True if valid, False otherwise
#### `parse(value)`
Parses init data string into structured Python object.
**Parameters:**
- `value` (str | dict): Init data to parse
**Returns:** `InitData` - Parsed init data object
#### `sign(data, token, auth_date, options=None)`
Signs init data for testing/development.
**Parameters:**
- `data` (dict): Data to sign
- `token` (str): Bot token
- `auth_date` (datetime): Authentication date
- `options` (dict, optional): Signing options
**Returns:** `str` - Signed init data as URL-encoded string
### Data Types
#### `InitData`
```python
class InitData(TypedDict):
query_id: Optional[str]
user: Optional[User]
receiver: Optional[User]
chat: Optional[Chat]
chat_type: Optional[ChatType]
chat_instance: Optional[str]
start_param: Optional[str]
can_send_after: Optional[int]
auth_date: int
hash: str
signature: Optional[str]
```
#### `User`
```python
class User(TypedDict):
id: int
first_name: str
last_name: Optional[str]
username: Optional[str]
language_code: Optional[str]
is_bot: Optional[bool]
is_premium: Optional[bool]
added_to_attachment_menu: Optional[bool]
allows_write_to_pm: Optional[bool]
photo_url: Optional[str]
```
#### `Chat`
```python
class Chat(TypedDict):
id: int
type: ChatType
title: Optional[str]
username: Optional[str]
photo_url: Optional[str]
```
### Exception Classes
- `TelegramInitDataError`: Base exception class
- `AuthDateInvalidError`: Invalid or missing auth_date
- `SignatureInvalidError`: Invalid signature
- `SignatureMissingError`: Missing signature/hash
- `ExpiredError`: Init data has expired
## Configuration Options
### Validation Options
```python
options = {
"expires_in": 3600, # 1 hour expiration instead of default 24 hours
}
validate(init_data, bot_token, options)
```
### Disable Expiration Check
```python
options = {
"expires_in": 0, # Disable expiration check
}
validate(init_data, bot_token, options)
```
## Testing
Run tests with pytest:
```bash
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest
# Run with coverage
pytest --cov=telegram_init_data --cov-report=html
```
## Examples
### Complete FastAPI Application
```python
from fastapi import FastAPI, Depends, HTTPException, Header
from telegram_init_data import validate, parse, is_valid
app = FastAPI()
def get_init_data(authorization: str = Header(None)):
"""Extract and validate init data from Authorization header"""
if not authorization:
raise HTTPException(status_code=401, detail="Authorization header missing")
if not authorization.startswith("tma "):
raise HTTPException(status_code=401, detail="Invalid authorization format")
init_data = authorization[4:] # Remove "tma " prefix
bot_token = "YOUR_BOT_TOKEN"
if not is_valid(init_data, bot_token):
raise HTTPException(status_code=401, detail="Invalid init data")
return parse(init_data)
@app.get("/me")
async def get_current_user(init_data: dict = Depends(get_init_data)):
"""Get current user info"""
user = init_data.get("user")
if not user:
raise HTTPException(status_code=400, detail="User data not found")
return {
"id": user["id"],
"name": user.get("first_name", ""),
"username": user.get("username"),
"is_premium": user.get("is_premium", False)
}
@app.post("/settings")
async def update_settings(
settings: dict,
init_data: dict = Depends(get_init_data)
):
"""Update user settings"""
user = init_data.get("user")
# Save settings for user["id"]
return {"status": "success"}
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/telegram-init-data/telegram-init-data-python.git
cd telegram-init-data-python
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e .[dev]
# Run tests
pytest
# Format code
black telegram_init_data tests
isort telegram_init_data tests
# Type checking
mypy telegram_init_data
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request
## License
MIT License. See [LICENSE](LICENSE) for details.
## Related Projects
- [@telegram-apps/init-data-node](https://docs.telegram-mini-apps.com/packages/telegram-apps-init-data-node/2-x) - Official Node.js implementation
- [Telegram Mini Apps Documentation](https://docs.telegram-mini-apps.com/) - Official documentation
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for details about changes in each version.
## Support
If you have questions or need help:
1. Check the [documentation](https://github.com/iCodeCraft/telegram-init-data/blob/main/README.md)
2. Look at the [examples](examples/)
3. Open an [issue](https://github.com/iCodeCraft/telegram-init-data/issues)
---
Developed with ❤️ by Imran Gadzhiev to support Telegram Mini Apps developers.
Raw data
{
"_id": null,
"home_page": null,
"name": "telegram-init-data",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "telegram, mini-apps, init-data, validation, signature, bot",
"author": null,
"author_email": "Imran Gadzhiev <i.gadzhiev.m@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/98/47/b56c72cb3b3188e15cf17c1201c38437a0c8869d8381af7a152cf5735d99/telegram_init_data-1.0.1.tar.gz",
"platform": null,
"description": "# Telegram Init Data Python\n\n[](https://badge.fury.io/py/telegram-init-data)\n[](https://pypi.org/project/telegram-init-data)\n[](https://opensource.org/licenses/MIT)\n\nA Python library for working with Telegram Mini Apps initialization data. This library provides utilities to parse, validate, and sign init data on the server side, similar to the official [@telegram-apps/init-data-node](https://docs.telegram-mini-apps.com/packages/telegram-apps-init-data-node/2-x) package.\n\n## Features\n\n- \ud83d\udd10 **Validate init data** - Verify signature and expiration of Telegram Mini App init data\n- \ud83d\udcdd **Parse init data** - Convert URL-encoded init data to structured Python objects\n- \u270d\ufe0f **Sign init data** - Create signed init data for testing and development\n- \ud83d\udd0d **Type safety** - Full type hints and validation\n- \ud83d\ude80 **FastAPI integration** - Ready-to-use middleware for FastAPI applications\n- \ud83c\udf10 **3rd party validation** - Support for validating data signed by Telegram directly\n\n## Installation\n\n```bash\npip install telegram-init-data\n```\n\nFor FastAPI integration:\n```bash\npip install telegram-init-data[fastapi]\n```\n\n## Quick Start\n\n### Basic Validation\n\n```python\nfrom telegram_init_data import validate, parse\n\n# Your bot token from @BotFather\nbot_token = \"YOUR_BOT_TOKEN\"\n\n# Init data string from Telegram Mini App\ninit_data = \"query_id=AAHdF6IQAAAAAN0XohDhrOrc&user=%7B%22id%22%3A279058397%2C%22first_name%22%3A%22Vladislav%22%2C%22last_name%22%3A%22Kibenko%22%2C%22username%22%3A%22vdkfrost%22%2C%22language_code%22%3A%22ru%22%2C%22is_premium%22%3Atrue%7D&auth_date=1662771648&hash=c501b71e775f74ce10e377dea85a7ea24ecd640b223ea86dfe453e0eaed2e2b2\"\n\ntry:\n # Validate the init data\n validate(init_data, bot_token)\n print(\"\u2705 Init data is valid!\")\n \n # Parse the init data\n parsed_data = parse(init_data)\n print(f\"User: {parsed_data['user']['first_name']}\")\n \nexcept Exception as e:\n print(f\"\u274c Validation failed: {e}\")\n```\n\n### Using with FastAPI\n\n```python\nfrom fastapi import FastAPI, Depends, HTTPException\nfrom telegram_init_data import validate, parse\n\napp = FastAPI()\n\ndef verify_init_data(init_data: str) -> dict:\n \"\"\"Dependency to verify and parse init data\"\"\"\n bot_token = \"YOUR_BOT_TOKEN\"\n \n try:\n validate(init_data, bot_token)\n return parse(init_data)\n except Exception as e:\n raise HTTPException(status_code=401, detail=str(e))\n\n@app.post(\"/user/profile\")\nasync def get_profile(init_data: dict = Depends(verify_init_data)):\n user = init_data.get(\"user\")\n if not user:\n raise HTTPException(status_code=400, detail=\"User data not found\")\n \n return {\"user_id\": user[\"id\"], \"name\": user[\"first_name\"]}\n```\n\n### Advanced Usage\n\n```python\nfrom telegram_init_data import sign, is_valid\nfrom datetime import datetime\n\n# Create test init data\ntest_data = {\n \"query_id\": \"test_query_id\",\n \"user\": {\n \"id\": 123456789,\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"username\": \"johndoe\",\n \"language_code\": \"en\"\n },\n \"auth_date\": datetime.now()\n}\n\n# Sign the data\nsigned_data = sign(test_data, bot_token, datetime.now())\nprint(f\"Signed data: {signed_data}\")\n\n# Check if data is valid (returns boolean)\nif is_valid(signed_data, bot_token):\n print(\"\u2705 Data is valid\")\nelse:\n print(\"\u274c Data is invalid\")\n```\n\n## API Reference\n\n### Core Functions\n\n#### `validate(value, token, options=None)`\n\nValidates Telegram Mini App init data.\n\n**Parameters:**\n- `value` (str | dict): Init data to validate\n- `token` (str): Bot token from @BotFather\n- `options` (dict, optional): Validation options\n - `expires_in` (int): Expiration time in seconds (default: 86400)\n\n**Raises:**\n- `SignatureMissingError`: When hash parameter is missing\n- `AuthDateInvalidError`: When auth_date is invalid or missing\n- `ExpiredError`: When init data has expired\n- `SignatureInvalidError`: When signature verification fails\n\n#### `is_valid(value, token, options=None)`\n\nChecks if init data is valid without raising exceptions.\n\n**Returns:** `bool` - True if valid, False otherwise\n\n#### `parse(value)`\n\nParses init data string into structured Python object.\n\n**Parameters:**\n- `value` (str | dict): Init data to parse\n\n**Returns:** `InitData` - Parsed init data object\n\n#### `sign(data, token, auth_date, options=None)`\n\nSigns init data for testing/development.\n\n**Parameters:**\n- `data` (dict): Data to sign\n- `token` (str): Bot token\n- `auth_date` (datetime): Authentication date\n- `options` (dict, optional): Signing options\n\n**Returns:** `str` - Signed init data as URL-encoded string\n\n### Data Types\n\n#### `InitData`\n\n```python\nclass InitData(TypedDict):\n query_id: Optional[str]\n user: Optional[User]\n receiver: Optional[User]\n chat: Optional[Chat]\n chat_type: Optional[ChatType]\n chat_instance: Optional[str]\n start_param: Optional[str]\n can_send_after: Optional[int]\n auth_date: int\n hash: str\n signature: Optional[str]\n```\n\n#### `User`\n\n```python\nclass User(TypedDict):\n id: int\n first_name: str\n last_name: Optional[str]\n username: Optional[str]\n language_code: Optional[str]\n is_bot: Optional[bool]\n is_premium: Optional[bool]\n added_to_attachment_menu: Optional[bool]\n allows_write_to_pm: Optional[bool]\n photo_url: Optional[str]\n```\n\n#### `Chat`\n\n```python\nclass Chat(TypedDict):\n id: int\n type: ChatType\n title: Optional[str]\n username: Optional[str]\n photo_url: Optional[str]\n```\n\n### Exception Classes\n\n- `TelegramInitDataError`: Base exception class\n- `AuthDateInvalidError`: Invalid or missing auth_date\n- `SignatureInvalidError`: Invalid signature\n- `SignatureMissingError`: Missing signature/hash\n- `ExpiredError`: Init data has expired\n\n## Configuration Options\n\n### Validation Options\n\n```python\noptions = {\n \"expires_in\": 3600, # 1 hour expiration instead of default 24 hours\n}\n\nvalidate(init_data, bot_token, options)\n```\n\n### Disable Expiration Check\n\n```python\noptions = {\n \"expires_in\": 0, # Disable expiration check\n}\n\nvalidate(init_data, bot_token, options)\n```\n\n## Testing\n\nRun tests with pytest:\n\n```bash\n# Install development dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=telegram_init_data --cov-report=html\n```\n\n## Examples\n\n### Complete FastAPI Application\n\n```python\nfrom fastapi import FastAPI, Depends, HTTPException, Header\nfrom telegram_init_data import validate, parse, is_valid\n\napp = FastAPI()\n\ndef get_init_data(authorization: str = Header(None)):\n \"\"\"Extract and validate init data from Authorization header\"\"\"\n if not authorization:\n raise HTTPException(status_code=401, detail=\"Authorization header missing\")\n \n if not authorization.startswith(\"tma \"):\n raise HTTPException(status_code=401, detail=\"Invalid authorization format\")\n \n init_data = authorization[4:] # Remove \"tma \" prefix\n bot_token = \"YOUR_BOT_TOKEN\"\n \n if not is_valid(init_data, bot_token):\n raise HTTPException(status_code=401, detail=\"Invalid init data\")\n \n return parse(init_data)\n\n@app.get(\"/me\")\nasync def get_current_user(init_data: dict = Depends(get_init_data)):\n \"\"\"Get current user info\"\"\"\n user = init_data.get(\"user\")\n if not user:\n raise HTTPException(status_code=400, detail=\"User data not found\")\n \n return {\n \"id\": user[\"id\"],\n \"name\": user.get(\"first_name\", \"\"),\n \"username\": user.get(\"username\"),\n \"is_premium\": user.get(\"is_premium\", False)\n }\n\n@app.post(\"/settings\")\nasync def update_settings(\n settings: dict,\n init_data: dict = Depends(get_init_data)\n):\n \"\"\"Update user settings\"\"\"\n user = init_data.get(\"user\")\n # Save settings for user[\"id\"]\n return {\"status\": \"success\"}\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/telegram-init-data/telegram-init-data-python.git\ncd telegram-init-data-python\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Format code\nblack telegram_init_data tests\nisort telegram_init_data tests\n\n# Type checking\nmypy telegram_init_data\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Submit a pull request\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Related Projects\n\n- [@telegram-apps/init-data-node](https://docs.telegram-mini-apps.com/packages/telegram-apps-init-data-node/2-x) - Official Node.js implementation\n- [Telegram Mini Apps Documentation](https://docs.telegram-mini-apps.com/) - Official documentation\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for details about changes in each version.\n\n## Support\n\nIf you have questions or need help:\n\n1. Check the [documentation](https://github.com/iCodeCraft/telegram-init-data/blob/main/README.md)\n2. Look at the [examples](examples/)\n3. Open an [issue](https://github.com/iCodeCraft/telegram-init-data/issues)\n\n---\n\nDeveloped with \u2764\ufe0f by Imran Gadzhiev to support Telegram Mini Apps developers.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for working with Telegram Mini Apps initialization data",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://github.com/telegram-init-data/telegram-init-data-python#readme",
"Homepage": "https://github.com/telegram-init-data/telegram-init-data-python",
"Issues": "https://github.com/telegram-init-data/telegram-init-data-python/issues",
"Repository": "https://github.com/telegram-init-data/telegram-init-data-python"
},
"split_keywords": [
"telegram",
" mini-apps",
" init-data",
" validation",
" signature",
" bot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2423de17c1243d85d346fed7774895e0926e01a50bafa76f952102cafff44fdc",
"md5": "4bd1585fb1c3f54fc9dab82aeca791d2",
"sha256": "c530edd74973881ba18c8ac48b2f3c7db41bac6cc073c2828e696a47e3a7ce05"
},
"downloads": -1,
"filename": "telegram_init_data-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bd1585fb1c3f54fc9dab82aeca791d2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18606,
"upload_time": "2025-07-13T18:39:16",
"upload_time_iso_8601": "2025-07-13T18:39:16.744572Z",
"url": "https://files.pythonhosted.org/packages/24/23/de17c1243d85d346fed7774895e0926e01a50bafa76f952102cafff44fdc/telegram_init_data-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9847b56c72cb3b3188e15cf17c1201c38437a0c8869d8381af7a152cf5735d99",
"md5": "184823613db588b594110b99949fccd1",
"sha256": "f54aa6e881b9744e4feadc3c191c3a5d896058db9ad184e89cb91e2c9e2e6757"
},
"downloads": -1,
"filename": "telegram_init_data-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "184823613db588b594110b99949fccd1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19305,
"upload_time": "2025-07-13T18:39:18",
"upload_time_iso_8601": "2025-07-13T18:39:18.099313Z",
"url": "https://files.pythonhosted.org/packages/98/47/b56c72cb3b3188e15cf17c1201c38437a0c8869d8381af7a152cf5735d99/telegram_init_data-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 18:39:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "telegram-init-data",
"github_project": "telegram-init-data-python#readme",
"github_not_found": true,
"lcname": "telegram-init-data"
}
JSON
